gathering-ui

Gathering UI 🌲🦎🦌

The drum echoes through the glade. The conductor stands at the clearing's center, orchestrating two very different kinds of attention. The Chameleon arrives with fresh eyes — no preconceptions about what the page should look like, just the spec and the forest's palette. The Deer arrives later, also with fresh eyes — it hasn't watched the CSS being written, so it tests accessibility without unconscious trust. Beautiful and accessible, built by isolated minds.

When to Summon

• Designing new pages or interfaces
• Implementing complete UI features
• Ensuring visual design meets accessibility standards
• Creating Grove-themed experiences
• When beauty and inclusion must coexist

IMPORTANT: This gathering is a conductor. It never writes components or audits accessibility directly. It dispatches subagents — one per animal — each with isolated context and an intentional model. The conductor only manages handoffs and gate checks.

---

The Gathering

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

Animals Dispatched

Order	Animal	Model	Role	Fresh Eyes?
1	🦎 Chameleon	sonnet	Design UI with Grove aesthetics	Yes — sees only the UI spec
2	🦌 Deer	sonnet	Audit accessibility independently	Yes — sees file list only, not design reasoning

Reference: Load references/conductor-dispatch.md for exact subagent prompts and handoff formats

---

Phase 1: SUMMON

The drum sounds. The glade awaits...

The conductor receives the UI request and prepares the dispatch plan:

Clarify the UI Work:

• What page/component are we designing?
• What's the emotional tone?
• Which season should it reflect?
• What's the content structure?

Confirm with the human, then proceed.

Output: UI specification, dispatch plan confirmed.

---

Phase 2: ADAPT (Chameleon)

The conductor signals. The Chameleon shifts its colors...

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

Dispatch a sonnet subagent to design and build the UI. The Chameleon receives ONLY the UI specification. It reads its own skill file and executes its full workflow.

What the Chameleon builds:

• Svelte components with glassmorphism
• Seasonal color palette integration
• Nature decorations (trees, creatures, weather)
• Mobile-responsive layouts
• Reduced motion support
• GroveTerm components for user-facing terminology

Handoff to conductor: File list (every file created/modified), component summary (what was built, glass variants used, seasonal elements).

Gate check: Run gw dev ci --affected --fail-fast — must compile. If build fails, resume Chameleon.

---

Phase 3: SENSE (Deer)

The Deer steps into the glade. It hasn't watched the colors change...

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

Dispatch a sonnet subagent to audit accessibility. The Deer receives ONLY the file list — NOT the Chameleon's design decisions or reasoning. This isolation is intentional: the Deer should test what's rendered, not trust what was intended.

What the Deer audits:

• Keyboard navigation (tab order, focus management, escape handling)
• Screen reader compatibility (ARIA labels, semantic HTML, live regions)
• Color contrast (4.5:1 minimum, WCAG AA)
• Touch targets (44px minimum)
• Reduced motion (prefers-reduced-motion respected)
• Focus indicators visible

Handoff to conductor: Accessibility report (violations found, fixes applied, WCAG level achieved), updated file list.

Gate check: Run gw dev ci --affected --fail-fast — must still compile after a11y fixes.

---

Phase 4: ITERATION (When Deer Finds Issues)

If the Deer's report includes issues it couldn't fix directly (e.g., structural changes needed for keyboard navigation, color scheme changes for contrast):

1. Resume Chameleon with Deer's specific findings
2. Chameleon applies fixes
3. Gate check: CI passes
4. Resume Deer to re-verify only the changed files
5. Max 2 iterations — then escalate to human

---

Phase 5: VERIFY

The glade is complete. But the conductor looks with its own eyes...

Component Audit Gate (MANDATORY before page-level verification):

Before capturing full pages, the conductor audits every component the Chameleon built or modified in isolation using Showroom. This gate catches design token violations, off-grid spacing, missing focus styles, and hardcoded colors (including accent surfaces that should use var(--grove-accent-*) tokens) that page-level captures miss.

# 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

All Showroom compliance violations must be resolved before proceeding to page-level Glimpse. If violations are found, resume the Chameleon with the specific findings.

Visual Verification (MANDATORY for UI gatherings):

# 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

Review every screenshot. If something looks wrong — fix it and capture again.

Validation Checklist (after visual verification):

• Showroom: Every built/modified component passes glimpse showroom with no compliance violations
• Glimpse: Page captured across all target seasons — looks correct
• Glimpse: Light and dark mode both visually verified
• Glimpse: No console errors in --logs output
• Chameleon: UI matches Grove aesthetic (verified by screenshot)
• Chameleon: Glassmorphism readable (verified by screenshot)
• Chameleon: Mobile responsive
• Deer: Keyboard navigation works
• Deer: Screen reader compatible
• Deer: Color contrast passes (4.5:1)
• Deer: Reduced motion respected
• Deer: Touch targets adequate (44px)
• Both: Grove terminology uses GroveTerm components

Completion Report:

🌲 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.

---

Conductor Rules

Never Do Animal Work

The conductor dispatches. It does not write CSS, build components, or audit accessibility.

Fresh Eyes Are a Feature

The Deer hasn't watched the Chameleon work. It sees only the rendered result, not the design intent. This isolation catches contrast issues, missing labels, and navigation gaps that a sympathetic observer would miss.

Gate Every Transition

CI between Chameleon and Deer. Showroom audit on every component after Chameleon. CI after Deer's fixes. Glimpse after everything.

Visual Proof Required

The conductor MUST capture and review Glimpse screenshots before declaring complete. CI passing is not the same as looking correct.

Resume, Don't Restart

If iteration is needed, resume existing agents. They have context from their prior work.

---

Anti-Patterns

The conductor does NOT:

• Write components itself
• Let Deer see Chameleon's design reasoning (isolation is the point)
• Skip Glimpse verification ("CI passed so it looks fine")
• Skip the Deer phase ("it's just a small component")
• Declare complete without visual proof

---

Beautiful and accessible — the forest welcomes all. 🌲