gathering-ui

Gathering UI 🌲🦎🦌

鼓声在林间空地回荡。指挥者站在空地中央，协调两种截然不同的关注方式。变色龙带着全新的视角到来——对页面应该呈现什么样子没有先入为主的想法，只有规格说明和森林的调色板。随后，鹿也带着全新的视角到来——它没有看着 CSS 被编写，因此能在不带无意识信任的情况下测试无障碍性。由彼此独立的思维打造，美观且无障碍。

何时召集

• 设计新页面或界面
• 实现完整的 UI 功能
• 确保视觉设计符合无障碍标准
• 打造 Grove 主题体验
• 让美观与包容并存时

IMPORTANT：这场集会是一个指挥者。它从不直接编写组件或审核无障碍性，而是派遣子 Agent——每种动物各一名——各自拥有独立的上下文和指定的模型。指挥者只负责管理交接和关卡检查。

---

集会

SUMMON → DISPATCH → GATE → DISPATCH → GATE → VERIFY
  ↓         ↓        ↓        ↓        ↓        ↓
Spec    Chameleon  Check     Deer    Check    Visual
(self)  (sonnet)    ✓      (sonnet)   ✓     Proof

派遣的动物

顺序	动物	模型	职责	全新视角？
1	🦎 变色龙	sonnet	以 Grove 美学设计 UI	是——只查看 UI 规格说明
2	🦌 鹿	sonnet	独立审核无障碍性	是——只查看文件列表，不查看设计推理过程

**参考：**加载 references/conductor-dispatch.md，查看精确的子 Agent 提示词和交接格式

---

阶段 1：召集

鼓声响起。林间空地静候……

指挥者接收 UI 请求并准备派遣计划：

明确 UI 工作内容：

• 我们要设计什么页面／组件？
• 希望营造什么情绪基调？
• 应该体现哪个季节？
• 内容结构是什么？

与用户确认后继续。

**输出：**UI 规格说明，已确认的派遣计划。

---

阶段 2：适应（变色龙）

指挥者发出信号。变色龙变换色彩……

Agent(chameleon, model: sonnet)
  Input:  UI specification only
  Reads:  chameleon-adapt/SKILL.md + references (MANDATORY)
  Output: built components + file list

派遣一个 sonnet 子 Agent来设计并构建 UI。变色龙只会收到 UI 规格说明。它会读取自己的技能文件，并执行完整工作流。

变色龙构建的内容：

• 带有玻璃拟态效果的 Svelte 组件
• 季节性色彩调色板集成
• 自然装饰（树木、动物、天气）
• 适配移动设备的布局
• 减少动态效果支持
• 面向用户术语的 GroveTerm 组件

**交接给指挥者：**文件列表（每个新建／修改的文件）、组件摘要（构建内容、使用的玻璃效果变体、季节元素）。

**关卡检查：**运行 gw dev ci --affected --fail-fast——必须编译成功。如果构建失败，则恢复变色龙的工作。

---

阶段 3：感知（鹿）

鹿走进林间空地。它没有看着色彩变化……

Agent(deer, model: sonnet)
  Input:  UI file list ONLY (not Chameleon's design reasoning)
  Reads:  deer-sense/SKILL.md + references (MANDATORY)
  Output: accessibility report + applied fixes

派遣一个 sonnet 子 Agent来审核无障碍性。鹿只会收到文件列表——不会收到变色龙的设计决策或推理过程。这种隔离是有意为之：鹿应该测试实际渲染的内容，而不是相信设计意图。

鹿审核的内容：

• 键盘导航（Tab 顺序、焦点管理、Escape 键处理）
• 屏幕阅读器兼容性（ARIA 标签、语义化 HTML、实时区域）
• 色彩对比度（最低 4.5:1，WCAG AA）
• 触控目标（最低 44px）
• 减少动态效果（遵循 prefers-reduced-motion 设置）
• 焦点指示器清晰可见

**交接给指挥者：**无障碍报告（发现的违规项、已应用的修复、达到的 WCAG 等级）、更新后的文件列表。

**关卡检查：**运行 gw dev ci --affected --fail-fast——无障碍修复后仍必须编译成功。

---

阶段 4：迭代（鹿发现问题时）

如果鹿的报告指出了它无法直接修复的问题（例如，需要进行结构性更改才能支持键盘导航，或需要更改配色方案以提高对比度）：

1. 向变色龙提供鹿发现的具体问题并恢复其工作
2. 变色龙应用修复
3. 门禁检查：CI 通过
4. 恢复鹿的工作，仅重新验证已更改的文件
5. 最多迭代 2 次，然后升级给人工处理

---

阶段 5：验证

林间空地已完工。但指挥者要亲眼查看……

组件审查门禁（页面级验证前的强制步骤）：

在捕获完整页面之前，指挥者会使用 Showroom 单独审查变色龙构建或修改的每个组件。此门禁可以发现页面级截图无法发现的问题，例如设计令牌违规、间距偏离网格、缺少焦点样式，以及硬编码颜色（包括应使用 var(--grove-accent-*) 令牌的强调色表面）。

# For each component built or modified by the Chameleon:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

# For new components, scaffold fixtures first:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte --scaffold

在进入页面级 Glimpse 验证之前，必须解决所有 Showroom 合规性违规。如果发现违规，请向变色龙提供具体问题并恢复其工作。

视觉验证（UI 集合的强制步骤）：

# Seed database if not already done
uv run --project tools/glimpse glimpse seed --yes

# Capture across all seasons and themes
uv run --project tools/glimpse glimpse matrix \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --seasons spring,summer,autumn,winter --themes light,dark --logs --auto

# Interactive verification — click around, verify flows
uv run --project tools/glimpse glimpse browse \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --do "click navigation, scroll content, interact with elements" \
  --screenshot-each --logs --auto

检查每张截图。如果发现问题，就修复并重新截图。

验证清单（视觉验证之后）：

• Showroom：所有构建或修改的组件通过 glimpse showroom，且没有合规性违规
• Glimpse：页面已在所有目标季节中捕获，显示正确
• Glimpse：已对浅色和深色模式进行视觉验证
• Glimpse：--logs 输出中没有控制台错误
• 变色龙：UI 符合 Grove 美学（已通过截图验证）
• 变色龙：毛玻璃效果清晰易读（已通过截图验证）
• 变色龙：适配移动设备
• 鹿：键盘导航正常
• 鹿：兼容屏幕阅读器
• 鹿：颜色对比度达标（4.5:1）
• 鹿：遵循减少动态效果设置
• 鹿：触控目标尺寸足够（44px）
• 两者：Grove 术语使用 GroveTerm 组件

完成报告：

🌲 GATHERING UI COMPLETE

UI: [Name]

DISPATCH LOG
  🦎 Chameleon (sonnet) — [X components built, Y files created/modified]
  🦌 Deer (sonnet)       — [Z a11y issues found, W fixed]

GATE LOG
  After Chameleon: ✅ compiles clean
  After Deer:      ✅ compiles clean, a11y verified
  Iterations:      [N iterations / none needed]
  Visual:          ✅ Glimpse matrix captured and reviewed
  Final CI:        ✅ gw dev ci --affected passes

ACCESSIBILITY
  Keyboard nav: ✅
  Screen reader: ✅
  Contrast: ✅ [ratios]
  Touch targets: ✅ 44px+
  Reduced motion: ✅
  WCAG level: [AA/AAA]

The glade welcomes all wanderers.

---

指挥者规则

绝不亲自承担动物的工作

指挥者负责派遣，不负责编写 CSS、构建组件或审查无障碍性。

新鲜视角是一项优势

鹿没有看过变色龙的工作过程。它只能看到渲染结果，而非设计意图。这种隔离能发现富有同情心的观察者可能忽略的对比度问题、缺失标签和导航缺口。

每次交接都要设置门禁

变色龙与鹿之间进行 CI 检查。变色龙完成后审查每个组件的 Showroom。鹿修复后进行 CI 检查。全部完成后进行 Glimpse 验证。

必须提供视觉证明

指挥者必须捕获并审查 Glimpse 截图，才能宣布完成。CI 通过不等于页面看起来正确。

恢复工作，不要重新开始

如果需要迭代，请恢复现有 Agent 的工作。它们保留了之前工作的上下文。

---

反模式

指挥者不会：

• 亲自编写组件
• 让鹿看到变色龙的设计思路（隔离正是目的所在）
• 跳过 Glimpse 验证（“CI 通过了，所以看起来没问题”）
• 跳过鹿的阶段（“这只是个小组件”）
• 在没有视觉证明的情况下宣布完成

---

兼具美观与无障碍性——森林欢迎所有人。 🌲