maestro-flow 0.5.36 → 0.5.38

package/.agy/skills/team-uidesign/roles/implementer/role.md

@@ -2,92 +2,93 @@
 role: implementer
 prefix: BUILD
 inner_loop: false
+message_types: [state_update]
 ---
-
-# Component Code Builder
-
-Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns.
-
-## Phase 2: Context & Artifact Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Design tokens | <session>/design/design-tokens.json | Yes (token build) |
-| Component specs | <session>/design/component-specs/*.md | Yes (component build) |
-| Design intelligence | <session>/research/design-intelligence.json | Yes |
-| Latest audit report | <session>/audit/audit-*.md | No |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
-
-1. Extract session path from task description
-2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation
-3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build)
-4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines
-5. Read latest audit report for approved changes and feedback
-6. Detect project tech stack from package.json
-
-## Phase 3: Implementation Execution
-
-**Token Implementation (BUILD-001)**:
-- Convert design tokens to production code
-- Output files in `<session>/build/token-files/`:
-  - `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback
-  - `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support
-  - `README.md`: Token usage guide
-- **Color tokens**: generate OKLCH values in CSS custom properties (no hex/rgb)
-- **Motion tokens**: generate easing + duration custom properties + reduced-motion query:
-  ```css
-  --easing-default: cubic-bezier(0.25, 1, 0.5, 1);
-  --duration-instant: 100ms;
-  --duration-fast: 150ms;
-  /* ... */
-  @media (prefers-reduced-motion: reduce) { /* ... */ }
-  ```
-- **Spacing**: 4pt scale custom properties (--space-0 through --space-24)
-- Z-index tokens: generate semantic z-index custom properties (`--z-dropdown` through `--z-tooltip`)
-- Dark mode: ensure dark theme uses lighter surfaces for depth, reduced font weight references
-- All color tokens must have both light and dark values
-- Semantic token names must match design token definitions
-
-**Component Implementation (BUILD-002)**:
-- Implement component code from design specifications
-- Per-component output in `<session>/build/component-files/`:
-  - `{ComponentName}.tsx`: React/Vue/Svelte component (match detected stack)
-  - `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only
-  - `{ComponentName}.test.tsx`: Basic render + state tests
-  - `index.ts`: Re-export
-- Requirements: no hardcoded colors/spacing (use design tokens), implement **all 8 states**, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
-- **Focus**: use `:focus-visible` not bare `:focus`. Spec: `outline: 2px solid var(--color-primary); outline-offset: 2px; border-radius: inherit`
-- **Hover**: wrap in `@media(hover:hover)` guard
-- **Animation**: transform+opacity only (NEVER width/height/margin/padding), use motion tokens for easing and duration, add reduced-motion fallback via `@media (prefers-reduced-motion: reduce)`
-- **Touch targets**: 44x44px minimum for all interactive elements, 8px gap between adjacent targets
-- Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
-- Responsive images: use `srcset` with width descriptors + `sizes` attribute for content images. Use `<picture>` for art direction
-- Input method: beyond `@media(hover:hover)`, also use `@media(pointer:coarse)` for touch-specific adjustments (larger targets, simpler hover alternatives)
-- UX writing: implement button labels, error messages, empty states as specified in component spec. No generic "OK/Cancel"
-- Check implementation against design intelligence anti_patterns and `specs/anti-patterns.md`
-
-## Phase 4: Validation & Output
-
-1. Token build validation:
-
-| Check | Pass Criteria |
-|-------|---------------|
-| File existence | tokens.css and tokens.ts exist |
-| Token coverage | All defined tokens present in CSS |
-| Theme support | Light/dark variants exist |
-
-2. Component build validation:
-
-| Check | Pass Criteria |
-|-------|---------------|
-| File existence | At least 3 files per component (component, style, index) |
-| No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) |
-| focus_visible_used | Uses `:focus-visible` not bare `:focus` |
-| Responsive | `@media` queries present |
-| Anti-pattern clean | No violations of design intelligence anti_patterns |
-| no_layout_animations | No width/height/margin/padding animations (transform+opacity only) |
-| reduced_motion_present | `@media (prefers-reduced-motion: reduce)` exists in stylesheets |
-| touch_targets | Interactive elements >= 44x44px (min-width/min-height or padding) |
-
-3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
-   - Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back
+
+# Component Code Builder
+
+Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Design tokens | <session>/design/design-tokens.json | Yes (token build) |
+| Component specs | <session>/design/component-specs/*.md | Yes (component build) |
+| Design intelligence | <session>/research/design-intelligence.json | Yes |
+| Latest audit report | <session>/audit/audit-*.md | No |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation
+3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build)
+4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines
+5. Read latest audit report for approved changes and feedback
+6. Detect project tech stack from package.json
+
+## Phase 3: Implementation Execution
+
+**Token Implementation (BUILD-001)**:
+- Convert design tokens to production code
+- Output files in `<session>/build/token-files/`:
+  - `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback
+  - `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support
+  - `README.md`: Token usage guide
+- **Color tokens**: generate OKLCH values in CSS custom properties (no hex/rgb)
+- **Motion tokens**: generate easing + duration custom properties + reduced-motion query:
+  ```css
+  --easing-default: cubic-bezier(0.25, 1, 0.5, 1);
+  --duration-instant: 100ms;
+  --duration-fast: 150ms;
+  /* ... */
+  @media (prefers-reduced-motion: reduce) { /* ... */ }
+  ```
+- **Spacing**: 4pt scale custom properties (--space-0 through --space-24)
+- Z-index tokens: generate semantic z-index custom properties (`--z-dropdown` through `--z-tooltip`)
+- Dark mode: ensure dark theme uses lighter surfaces for depth, reduced font weight references
+- All color tokens must have both light and dark values
+- Semantic token names must match design token definitions
+
+**Component Implementation (BUILD-002)**:
+- Implement component code from design specifications
+- Per-component output in `<session>/build/component-files/`:
+  - `{ComponentName}.tsx`: React/Vue/Svelte component (match detected stack)
+  - `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only
+  - `{ComponentName}.test.tsx`: Basic render + state tests
+  - `index.ts`: Re-export
+- Requirements: no hardcoded colors/spacing (use design tokens), implement **all 8 states**, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
+- **Focus**: use `:focus-visible` not bare `:focus`. Spec: `outline: 2px solid var(--color-primary); outline-offset: 2px; border-radius: inherit`
+- **Hover**: wrap in `@media(hover:hover)` guard
+- **Animation**: transform+opacity only (NEVER width/height/margin/padding), use motion tokens for easing and duration, add reduced-motion fallback via `@media (prefers-reduced-motion: reduce)`
+- **Touch targets**: 44x44px minimum for all interactive elements, 8px gap between adjacent targets
+- Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
+- Responsive images: use `srcset` with width descriptors + `sizes` attribute for content images. Use `<picture>` for art direction
+- Input method: beyond `@media(hover:hover)`, also use `@media(pointer:coarse)` for touch-specific adjustments (larger targets, simpler hover alternatives)
+- UX writing: implement button labels, error messages, empty states as specified in component spec. No generic "OK/Cancel"
+- Check implementation against design intelligence anti_patterns and `specs/anti-patterns.md`
+
+## Phase 4: Validation & Output
+
+1. Token build validation:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| File existence | tokens.css and tokens.ts exist |
+| Token coverage | All defined tokens present in CSS |
+| Theme support | Light/dark variants exist |
+
+2. Component build validation:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| File existence | At least 3 files per component (component, style, index) |
+| No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) |
+| focus_visible_used | Uses `:focus-visible` not bare `:focus` |
+| Responsive | `@media` queries present |
+| Anti-pattern clean | No violations of design intelligence anti_patterns |
+| no_layout_animations | No width/height/margin/padding animations (transform+opacity only) |
+| reduced_motion_present | `@media (prefers-reduced-motion: reduce)` exists in stylesheets |
+| touch_targets | Interactive elements >= 44x44px (min-width/min-height or padding) |
+
+3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
+   - Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back

package/.agy/skills/team-uidesign/roles/researcher/role.md

@@ -2,99 +2,100 @@
 role: researcher
 prefix: RESEARCH
 inner_loop: false
+message_types: [state_update]
 ---
-
-# Design System Researcher
-
-Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles.
-
-## Phase 2: Context & Environment Detection
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
-
-1. Extract session path and target scope from task description
-2. Detect project type and tech stack from package.json or equivalent:
-
-| Package | Detected Stack |
-|---------|---------------|
-| next | nextjs |
-| react | react |
-| vue | vue |
-| svelte | svelte |
-| @shadcn/ui | shadcn |
-| (default) | html-tailwind |
-
-3. Use CLI tools (e.g., `maestro delegate "..." --to gemini --mode analysis`) or direct tools (Glob, Grep) to scan for existing design tokens, component files, styling patterns
-4. Read industry context from session config (industry, strictness, must-have features)
-5. **Context-First Protocol**: Before any design work, ensure these are known (extract from task description, or ask coordinator to clarify):
-   - **Target audience**: Who uses it, in what context? (e.g., developers, end users, admins)
-   - **Use cases**: What jobs are they doing? (e.g., data entry, monitoring, content creation)
-   - **Brand personality**: How should it feel? (e.g., professional, playful, technical, luxurious)
-   - If not provided in task description, flag as `context_missing` in output — designer cannot make good decisions without this
-
-## Phase 3: Research Execution
-
-Execute 4 analysis streams:
-
-**Stream 1 -- Design System Analysis**:
-- Search for existing design tokens (CSS variables, theme configs, token files)
-- Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
-- Map color palette, typography scale, spacing system
-- Find component library usage (MUI, Ant Design, shadcn, custom)
-- Check dark mode implementation quality: surface hierarchy, font weight adjustments, accent desaturation
-- Check z-index patterns: arbitrary values vs semantic scale
-- Output: `<session>/research/design-system-analysis.json`
-
-**Stream 2 -- Component Inventory**:
-- Find all UI component files; identify props/API surface
-- Identify states supported (hover, focus, disabled, etc.)
-- Check accessibility attributes (ARIA labels, roles)
-- Map inter-component dependencies and usage counts
-- Output: `<session>/research/component-inventory.json`
-
-**Stream 3 -- Accessibility Baseline**:
-- Check ARIA attribute usage patterns, keyboard navigation support
-- Assess color contrast ratios (if design tokens found)
-- Find focus management and semantic HTML patterns
-- Output: `<session>/research/accessibility-audit.json`
-
-**Stream 4 -- Design Intelligence (ui-ux-pro-max)**:
-- Call `view_file(AbsolutePath="<agy-skills-dir>/ui-ux-pro-max/SKILL.md") + execute inline (args: "<industry> <keywords> --design-system")` for design system recommendations
-- Call `view_file(AbsolutePath="<agy-skills-dir>/ui-ux-pro-max/SKILL.md") + execute inline (args: "accessibility animation responsive --domain ux")` for UX guidelines
-- Call `view_file(AbsolutePath="<agy-skills-dir>/ui-ux-pro-max/SKILL.md") + execute inline (args: "<keywords> --stack <detected-stack>")` for stack guidelines
-- Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
-- Output: `<session>/research/design-intelligence.json`
-
-**Stream 5 -- Visual Quality Baseline**:
-- Scan for AI slop tells (reference `specs/anti-patterns.md`): check for P1 items (AI color palette, gradient text, glassmorphism, all-buttons-primary, pure black/white)
-- Check color system: OKLCH usage, pure black/white (`#000`/`#fff`), tinted neutrals (chroma 0.005-0.01), 60-30-10 distribution
-- Check typography: font choices (flag Inter/Roboto/Open Sans/Lato/Montserrat/Arial), modular scale presence, fluid `clamp()` usage
-- Check spacing: 4pt scale adherence, `gap` vs `margin` usage ratio, nested cards detection
-- Check motion: easing values (flag `bounce`/`elastic`/`linear`/`ease`), `prefers-reduced-motion` query presence, `will-change` in CSS (should not be permanent)
-- Check interaction states: count distinct states per interactive component (target: 8 per `specs/design-standards.md`)
-- Check UX writing quality: generic button labels (OK/Submit/Cancel), error messages without fix guidance, empty states without actions
-- Check dark mode: pure black backgrounds, non-desaturated accents, same font weights as light
-- Output: `<session>/research/visual-quality-baseline.json`
-
-Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count, visual_quality_score.
-
-## Phase 4: Validation & Output
-
-1. Verify all 5 output files exist and contain valid JSON with required fields:
-
-| File | Required Fields |
-|------|----------------|
-| design-system-analysis.json | existing_tokens, styling_approach |
-| component-inventory.json | components array |
-| accessibility-audit.json | wcag_level |
-| design-intelligence.json | _source, design_system |
-| visual-quality-baseline.json | slop_tells, color_system, typography, spacing, motion, interaction_states |
-
-2. If any file missing or invalid, re-run corresponding stream
-
-3. Update `<session>/wisdom/.msg/meta.json` under `researcher` namespace:
-   - Read existing -> merge `{ "researcher": { detected_stack, component_count, wcag_level, di_source, scope } }` -> write back
+
+# Design System Researcher
+
+Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project type and tech stack from package.json or equivalent:
+
+| Package | Detected Stack |
+|---------|---------------|
+| next | nextjs |
+| react | react |
+| vue | vue |
+| svelte | svelte |
+| @shadcn/ui | shadcn |
+| (default) | html-tailwind |
+
+3. Use CLI tools (e.g., `maestro delegate "..." --to agy --mode analysis`) or direct tools (Glob, Grep) to scan for existing design tokens, component files, styling patterns
+4. Read industry context from session config (industry, strictness, must-have features)
+5. **Context-First Protocol**: Before any design work, ensure these are known (extract from task description, or ask coordinator to clarify):
+   - **Target audience**: Who uses it, in what context? (e.g., developers, end users, admins)
+   - **Use cases**: What jobs are they doing? (e.g., data entry, monitoring, content creation)
+   - **Brand personality**: How should it feel? (e.g., professional, playful, technical, luxurious)
+   - If not provided in task description, flag as `context_missing` in output — designer cannot make good decisions without this
+
+## Phase 3: Research Execution
+
+Execute 4 analysis streams:
+
+**Stream 1 -- Design System Analysis**:
+- Search for existing design tokens (CSS variables, theme configs, token files)
+- Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
+- Map color palette, typography scale, spacing system
+- Find component library usage (MUI, Ant Design, shadcn, custom)
+- Check dark mode implementation quality: surface hierarchy, font weight adjustments, accent desaturation
+- Check z-index patterns: arbitrary values vs semantic scale
+- Output: `<session>/research/design-system-analysis.json`
+
+**Stream 2 -- Component Inventory**:
+- Find all UI component files; identify props/API surface
+- Identify states supported (hover, focus, disabled, etc.)
+- Check accessibility attributes (ARIA labels, roles)
+- Map inter-component dependencies and usage counts
+- Output: `<session>/research/component-inventory.json`
+
+**Stream 3 -- Accessibility Baseline**:
+- Check ARIA attribute usage patterns, keyboard navigation support
+- Assess color contrast ratios (if design tokens found)
+- Find focus management and semantic HTML patterns
+- Output: `<session>/research/accessibility-audit.json`
+
+**Stream 4 -- Design Intelligence (ui-ux-pro-max)**:
+- Call `view_file(AbsolutePath="<agy-skills-dir>/ui-ux-pro-max/SKILL.md") + execute inline (args: "<industry> <keywords> --design-system")` for design system recommendations
+- Call `view_file(AbsolutePath="<agy-skills-dir>/ui-ux-pro-max/SKILL.md") + execute inline (args: "accessibility animation responsive --domain ux")` for UX guidelines
+- Call `view_file(AbsolutePath="<agy-skills-dir>/ui-ux-pro-max/SKILL.md") + execute inline (args: "<keywords> --stack <detected-stack>")` for stack guidelines
+- Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
+- Output: `<session>/research/design-intelligence.json`
+
+**Stream 5 -- Visual Quality Baseline**:
+- Scan for AI slop tells (reference `specs/anti-patterns.md`): check for P1 items (AI color palette, gradient text, glassmorphism, all-buttons-primary, pure black/white)
+- Check color system: OKLCH usage, pure black/white (`#000`/`#fff`), tinted neutrals (chroma 0.005-0.01), 60-30-10 distribution
+- Check typography: font choices (flag Inter/Roboto/Open Sans/Lato/Montserrat/Arial), modular scale presence, fluid `clamp()` usage
+- Check spacing: 4pt scale adherence, `gap` vs `margin` usage ratio, nested cards detection
+- Check motion: easing values (flag `bounce`/`elastic`/`linear`/`ease`), `prefers-reduced-motion` query presence, `will-change` in CSS (should not be permanent)
+- Check interaction states: count distinct states per interactive component (target: 8 per `specs/design-standards.md`)
+- Check UX writing quality: generic button labels (OK/Submit/Cancel), error messages without fix guidance, empty states without actions
+- Check dark mode: pure black backgrounds, non-desaturated accents, same font weights as light
+- Output: `<session>/research/visual-quality-baseline.json`
+
+Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count, visual_quality_score.
+
+## Phase 4: Validation & Output
+
+1. Verify all 5 output files exist and contain valid JSON with required fields:
+
+| File | Required Fields |
+|------|----------------|
+| design-system-analysis.json | existing_tokens, styling_approach |
+| component-inventory.json | components array |
+| accessibility-audit.json | wcag_level |
+| design-intelligence.json | _source, design_system |
+| visual-quality-baseline.json | slop_tells, color_system, typography, spacing, motion, interaction_states |
+
+2. If any file missing or invalid, re-run corresponding stream
+
+3. Update `<session>/wisdom/.msg/meta.json` under `researcher` namespace:
+   - Read existing -> merge `{ "researcher": { detected_stack, component_count, wcag_level, di_source, scope } }` -> write back

package/.agy/skills/team-uidesign/roles/reviewer/role.md

@@ -2,67 +2,68 @@
 role: reviewer
 prefix: AUDIT
 inner_loop: false
+message_types: [state_update]
 ---
-
-# Design Auditor
-
-Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines.
-
-## Phase 2: Context & Artifact Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Design artifacts | <session>/design/*.json, <session>/design/component-specs/*.md | Yes |
-| Design intelligence | <session>/research/design-intelligence.json | Yes |
-| Audit history | .msg/meta.json -> reviewer namespace | No |
-| Build artifacts | <session>/build/**/* | Only for final audit |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
-
-1. Extract session path from task description
-2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit
-3. Read design intelligence for anti-patterns and ux_guidelines
-4. Read design artifacts: design-tokens.json (token/component audit), component-specs/*.md (component/final audit), build/**/* (final audit only)
-5. Load audit_history from meta.json for trend analysis
-
-## Phase 3: Audit Execution
-
-Score 8 dimensions on 0-4 scale (reference `specs/scoring-guide.md`). Total: 0-32.
-
-| Dimension | Weight | Focus |
-|-----------|--------|-------|
-| Anti-AI-Slop | 10% | AI slop tells detection (reference `specs/anti-patterns.md`) |
-| Color Quality | 15% | OKLCH usage, tinted neutrals, 60-30-10, WCAG AA contrast, token hierarchy, dark mode surface hierarchy (lighter = higher elevation), dangerous color combinations (gray-on-color, red-green, yellow-white) |
-| Typography Quality | 15% | Distinctive fonts, modular scale, fluid clamp(), line-height, reading width, OpenType features usage (tabular numbers for data, proper ligatures) |
-| Spacing & Layout | 12.5% | 4pt scale, rhythm variation, gap over margin, no nested cards, touch targets |
-| Motion & Animation | 10% | Transform+opacity only, exponential easing, duration tokens, reduced-motion |
-| Interaction States | 15% | All 8 states, focus-visible, focus ring spec, loading/error/success, UX writing quality: button labels (verb+object), error messages (what+why+fix), empty states |
-| Visual Hierarchy | 10% | Squint test, single primary CTA, progressive disclosure, size/weight hierarchy |
-| Responsive | 12.5% | Fluid design, container queries, mobile requirements, adapt don't hide |
-
-**Token Audit**: OKLCH color values, tinted neutrals (chroma 0.005-0.01), no pure black/white, semantic token hierarchy (primitive->semantic->component), theme completeness (light+dark), contrast ratios (text >= 4.5:1, large text >= 3:1), distinctive font choice, modular scale ratio, fluid clamp() values, 4pt spacing scale, motion easing + duration tokens, reduced-motion strategy.
-
-**Component Audit**: All 8 interaction states present, `:focus-visible` (not bare `:focus`), hover in `@media(hover:hover)`, active `scale(0.97)`, loading/error/success states with ARIA, touch targets >= 44x44px, token references resolve, CTA hierarchy (primary/secondary/tertiary), no layout property animations.
-
-**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns), anti-pattern scan across all outputs.
-
-**Signal determination**:
-
-| Condition | Signal |
-|-----------|--------|
-| Score >= 26 AND no dimension at 0 | `audit_passed` (GC CONVERGED) |
-| Score >= 20 AND no dimension at 0 | `audit_result` (REVISION NEEDED) |
-| Score < 20 OR any dimension at 0 | `fix_required` (CRITICAL) |
-
-## Phase 4: Report & Output
-
-1. Write audit report to `<session>/audit/audit-{NNN}.md`:
-   - Summary: overall score (out of 32), signal, rating band (Excellent/Good/Acceptable/Poor/Critical)
-   - Sync Point Status (if applicable): PASSED/BLOCKED
-   - 8-Dimension Scores table: Anti-AI-Slop, Color Quality, Typography Quality, Spacing & Layout, Motion & Animation, Interaction States, Visual Hierarchy, Responsive (each 0-4 with weight and weighted score)
-   - P0/P1/P2/P3 issues with descriptions, locations, fix suggestions, mapped to dimensions
-   - Anti-pattern detections (reference `specs/anti-patterns.md` item numbers)
-   - GC Loop Status: signal, action required
-   - Trend analysis (if audit_history exists): improving/stable/declining
-
-2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
-   - Read existing -> merge `{ "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } }` -> write back
+
+# Design Auditor
+
+Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Design artifacts | <session>/design/*.json, <session>/design/component-specs/*.md | Yes |
+| Design intelligence | <session>/research/design-intelligence.json | Yes |
+| Audit history | .msg/meta.json -> reviewer namespace | No |
+| Build artifacts | <session>/build/**/* | Only for final audit |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit
+3. Read design intelligence for anti-patterns and ux_guidelines
+4. Read design artifacts: design-tokens.json (token/component audit), component-specs/*.md (component/final audit), build/**/* (final audit only)
+5. Load audit_history from meta.json for trend analysis
+
+## Phase 3: Audit Execution
+
+Score 8 dimensions on 0-4 scale (reference `specs/scoring-guide.md`). Total: 0-32.
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Anti-AI-Slop | 10% | AI slop tells detection (reference `specs/anti-patterns.md`) |
+| Color Quality | 15% | OKLCH usage, tinted neutrals, 60-30-10, WCAG AA contrast, token hierarchy, dark mode surface hierarchy (lighter = higher elevation), dangerous color combinations (gray-on-color, red-green, yellow-white) |
+| Typography Quality | 15% | Distinctive fonts, modular scale, fluid clamp(), line-height, reading width, OpenType features usage (tabular numbers for data, proper ligatures) |
+| Spacing & Layout | 12.5% | 4pt scale, rhythm variation, gap over margin, no nested cards, touch targets |
+| Motion & Animation | 10% | Transform+opacity only, exponential easing, duration tokens, reduced-motion |
+| Interaction States | 15% | All 8 states, focus-visible, focus ring spec, loading/error/success, UX writing quality: button labels (verb+object), error messages (what+why+fix), empty states |
+| Visual Hierarchy | 10% | Squint test, single primary CTA, progressive disclosure, size/weight hierarchy |
+| Responsive | 12.5% | Fluid design, container queries, mobile requirements, adapt don't hide |
+
+**Token Audit**: OKLCH color values, tinted neutrals (chroma 0.005-0.01), no pure black/white, semantic token hierarchy (primitive->semantic->component), theme completeness (light+dark), contrast ratios (text >= 4.5:1, large text >= 3:1), distinctive font choice, modular scale ratio, fluid clamp() values, 4pt spacing scale, motion easing + duration tokens, reduced-motion strategy.
+
+**Component Audit**: All 8 interaction states present, `:focus-visible` (not bare `:focus`), hover in `@media(hover:hover)`, active `scale(0.97)`, loading/error/success states with ARIA, touch targets >= 44x44px, token references resolve, CTA hierarchy (primary/secondary/tertiary), no layout property animations.
+
+**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns), anti-pattern scan across all outputs.
+
+**Signal determination**:
+
+| Condition | Signal |
+|-----------|--------|
+| Score >= 26 AND no dimension at 0 | `audit_passed` (GC CONVERGED) |
+| Score >= 20 AND no dimension at 0 | `audit_result` (REVISION NEEDED) |
+| Score < 20 OR any dimension at 0 | `fix_required` (CRITICAL) |
+
+## Phase 4: Report & Output
+
+1. Write audit report to `<session>/audit/audit-{NNN}.md`:
+   - Summary: overall score (out of 32), signal, rating band (Excellent/Good/Acceptable/Poor/Critical)
+   - Sync Point Status (if applicable): PASSED/BLOCKED
+   - 8-Dimension Scores table: Anti-AI-Slop, Color Quality, Typography Quality, Spacing & Layout, Motion & Animation, Interaction States, Visual Hierarchy, Responsive (each 0-4 with weight and weighted score)
+   - P0/P1/P2/P3 issues with descriptions, locations, fix suggestions, mapped to dimensions
+   - Anti-pattern detections (reference `specs/anti-patterns.md` item numbers)
+   - GC Loop Status: signal, action required
+   - Trend analysis (if audit_history exists): improving/stable/declining
+
+2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
+   - Read existing -> merge `{ "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } }` -> write back