claude-code-workflow 7.2.27 → 7.2.28

package/.claude/skills/team-ui-polish/specs/scoring-guide.md

@@ -0,0 +1,162 @@
+# Scoring Guide
+
+How to score each dimension consistently. Used by scanner for initial audit and verifier for re-assessment.
+
+## Rating Bands (Total Score out of 36)
+
+| Range | Rating | Description |
+|-------|--------|-------------|
+| 32-36 | Excellent | Distinctive, intentional design. Minimal or zero issues |
+| 25-31 | Good | Solid design with minor polish opportunities |
+| 18-24 | Acceptable | Functional but significant design work needed |
+| 11-17 | Poor | Major overhaul required across multiple dimensions |
+| 0-10 | Critical | AI slop gallery or fundamentally broken design |
+
+## Per-Dimension Scoring (0-4)
+
+### General Rubric
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Completely failing. Multiple major violations. Fundamental problems |
+| 1 | Major gaps. 3-4 violations. Some effort but insufficient |
+| 2 | Partial effort. 1-2 noticeable issues. Functional but not good |
+| 3 | Mostly clean. Subtle issues only. Good with minor polish needed |
+| 4 | Excellent. Genuinely distinctive/intentional. Meets all standards |
+
+### Dimension 1: Anti-AI-Slop Detection
+
+| Score | Criteria |
+|-------|----------|
+| 0 | 5+ AI slop tells present. Looks immediately AI-generated |
+| 1 | 3-4 AI slop tells. Heavy AI influence obvious |
+| 2 | 1-2 noticeable AI tells. Some templated elements |
+| 3 | Subtle traces only. Mostly intentional design choices |
+| 4 | Zero AI tells. Genuinely distinctive aesthetic. Would never guess AI-made |
+
+### Dimension 2: Color Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Multiple WCAG AA failures, pure black/white everywhere, hard-coded colors, no system |
+| 1 | Some contrast issues, hard-coded colors, no token system, pure grays |
+| 2 | Basic contrast OK, some OKLCH or tokens, but gaps (untinted grays, missing semantic colors) |
+| 3 | Good color system with minor gaps (a few hard-coded values, imperfect 60-30-10) |
+| 4 | OKLCH-based, fully tokenized, WCAG AA+ compliant, proper 60-30-10, semantic roles defined |
+
+### Dimension 3: Typography Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Generic font, no scale, body text <16px, no hierarchy |
+| 1 | Overused font, muddy sizes (many close values), missing fluid sizing |
+| 2 | Decent font choice but inconsistent scale or line-height issues |
+| 3 | Good typography with minor gaps (missing clamp, slight rhythm inconsistencies) |
+| 4 | Distinctive font, clear modular scale, fluid sizing, proper vertical rhythm, max-width on prose |
+
+### Dimension 4: Spacing & Layout Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Random spacing, nested cards, fixed widths, tiny touch targets |
+| 1 | Some spacing pattern but many arbitrary values, cards overused |
+| 2 | Decent spacing but monotonous rhythm or occasional arbitrary values |
+| 3 | Good spacing system with minor gaps (occasional non-scale value, mostly gap usage) |
+| 4 | Consistent scale, varied rhythm, gap for siblings, proper touch targets, no card nesting |
+
+### Dimension 5: Motion & Animation Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Layout animations, no reduced-motion, bounce easing, no system |
+| 1 | Some transform-based but bad easing, missing reduced-motion |
+| 2 | Decent animations but no token system or still missing reduced-motion |
+| 3 | Good system with minor gaps (occasional ease default, missing exit animation) |
+| 4 | Transform+opacity only, exponential easing, reduced-motion query, duration tokens, proper stagger |
+
+### Dimension 6: Interaction States
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No hover, no focus, outline:none without replacement, no loading states |
+| 1 | Basic hover but missing focus/active on many elements, no loading states |
+| 2 | Hover + focus exist but no focus-visible, missing some states (disabled, error, empty) |
+| 3 | Most states present with minor gaps (imperfect focus ring, missing empty state) |
+| 4 | All 8 states implemented, focus-visible, proper focus ring, loading/error/success/empty states |
+
+### Dimension 7: Visual Hierarchy
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Everything same visual weight, no clear primary action, fails squint test completely |
+| 1 | Some size differences but no clear hierarchy system, multiple competing primary actions |
+| 2 | Basic hierarchy via size but missing weight/color/space dimensions |
+| 3 | Good hierarchy with minor issues (occasional visual competition, could be stronger) |
+| 4 | Clear squint test pass, obvious primary action, multi-dimension hierarchy, progressive disclosure |
+
+### Dimension 8: Responsive Design
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No responsive design, horizontal scroll, completely broken on mobile |
+| 1 | Basic media queries but many breakage points, some fixed widths |
+| 2 | Decent mobile but some fixed widths, small targets, or missing breakpoints |
+| 3 | Good responsive with minor issues (missing container queries, occasional small target) |
+| 4 | Fluid design, proper breakpoints, container queries, 44px targets, no overflow, adapted content |
+
+### Dimension 9: Cognitive Load & UX Writing
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Information overload everywhere, no grouping, generic labels, useless error messages |
+| 1 | Some grouping but >7 data groups visible, many generic labels, errors without fix guidance |
+| 2 | Decent grouping but missing progressive disclosure, some generic buttons, partial error messages |
+| 3 | Good information architecture with minor issues (occasional generic label, one missing empty state) |
+| 4 | Clear progressive disclosure, verb+object labels, what+why+fix errors, guided empty states, proper grouping |
+
+### Dimension 10: Dark Mode Quality (Conditional)
+
+Only scored if dark mode exists. If no dark mode, this dimension is excluded from total.
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Pure black bg, no surface hierarchy, saturated colors vibrating, dangerous combos |
+| 1 | Some dark surfaces but flat (same lightness), still using light-mode font weights |
+| 2 | Basic surface hierarchy but still saturated accents or missing font weight reduction |
+| 3 | Good dark mode with minor issues (occasional pure black, one dangerous combo) |
+| 4 | Proper surface hierarchy (lighter=higher), desaturated accents, reduced font weights, tinted dark bg |
+
+When dark mode exists: total out of 40, bands shift +4. When no dark mode: total out of 36.
+
+---
+
+## Severity Mapping
+
+| Severity | Definition | Score Correlation | Action |
+|----------|-----------|-------------------|--------|
+| P0 Blocking | Prevents use or violates law/standard. WCAG AA failure, missing focus, horizontal scroll on mobile, no viewport meta | Any dimension at 0 | Fix immediately, blocks release |
+| P1 Major | Significant UX harm or near-violation. Pure black/white, missing hover, all buttons primary, muddy hierarchy | Any dimension at 1 | Fix before release |
+| P2 Minor | Annoyance with workaround. No OKLCH, overused fonts, monotonous spacing, no container queries | Any dimension at 2 | Fix in next polish pass |
+| P3 Polish | Nice-to-fix, minimal user impact. Missing exit animation, optical adjustments, font fallback metrics | Dimension at 3 with minor issues | Fix when convenient |
+
+---
+
+## Scoring Process
+
+1. For each dimension, go through every checklist item in the scanner audit
+2. Count the number and severity of violations found
+3. Apply the dimension-specific rubric to assign 0-4
+4. Sum all 8 dimensions for total (0-32)
+5. Apply rating band
+
+### Tie-Breaking Rules
+- If between two scores, the presence of any P0 issue in that dimension rounds down
+- If between two scores with no P0, consider the count of P1 issues
+- When in doubt, score lower (conservative) -- it is better to fix something unnecessary than miss something important
+
+### Verification Scoring
+When verifier re-scores after optimization:
+- Use identical checklist and rubric as original scan
+- Score independently (do not adjust based on "how much improved")
+- Report both absolute score and delta from original
+- Flag any dimension where score decreased (regression)

package/.claude/skills/team-ui-polish/specs/team-config.json

@@ -0,0 +1,73 @@
+{
+  "team_name": "ui-polish",
+  "team_display_name": "UI Polish",
+  "description": "Auto-discover and fix UI design issues using Impeccable design standards",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Pipeline orchestration, scope assessment, GC loop management",
+      "message_types": ["task_unblocked", "gc_checkpoint", "fix_required", "error", "shutdown"]
+    },
+    "scanner": {
+      "task_prefix": "SCAN",
+      "responsibility": "8-dimension UI audit using Impeccable design standards",
+      "message_types": ["scan_complete", "scan_progress", "error"]
+    },
+    "diagnostician": {
+      "task_prefix": "DIAG",
+      "responsibility": "Root cause analysis, severity classification, fix prioritization",
+      "message_types": ["diag_complete", "diag_progress", "error"]
+    },
+    "optimizer": {
+      "task_prefix": "OPT",
+      "responsibility": "Apply targeted fixes following Impeccable design standards",
+      "message_types": ["opt_complete", "opt_progress", "error"]
+    },
+    "verifier": {
+      "task_prefix": "VERIFY",
+      "responsibility": "Before/after comparison, regression detection",
+      "message_types": ["verify_passed", "verify_failed", "fix_required", "error"]
+    }
+  },
+
+  "pipelines": {
+    "scan-only": {
+      "description": "Discover + diagnose, no fixes (report only)",
+      "task_chain": ["SCAN-001", "DIAG-001"],
+      "complexity": "low"
+    },
+    "targeted": {
+      "description": "Fix specific dimensions only",
+      "task_chain": ["SCAN-001", "DIAG-001", "OPT-001", "VERIFY-001"],
+      "complexity": "medium"
+    },
+    "full": {
+      "description": "Complete polish cycle with GC loop",
+      "task_chain": ["SCAN-001", "DIAG-001", "OPT-001", "VERIFY-001"],
+      "gc_loop": true,
+      "complexity": "high"
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "optimizer",
+      "critic": "verifier",
+      "max_rounds": 2,
+      "convergence": "verify.regressions === 0 && verify.score_delta >= 0",
+      "escalation": "Coordinator intervenes after max rounds"
+    }
+  },
+
+  "session_dirs": {
+    "base": ".workflow/.team/UIP-{slug}-{YYYY-MM-DD}/",
+    "scan": "scan/",
+    "diagnosis": "diagnosis/",
+    "optimization": "optimization/",
+    "verification": "verification/",
+    "evidence": "evidence/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}

package/.claude/skills/team-uidesign/SKILL.md

@@ -89,6 +89,10 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5
 ## Specs Reference
 
 - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+- [specs/design-standards.md](specs/design-standards.md) — Impeccable design standards (OKLCH, typography, spacing, motion, interaction)
+- [specs/anti-patterns.md](specs/anti-patterns.md) — AI slop detection catalog (20 items)
+- [specs/scoring-guide.md](specs/scoring-guide.md) — 8-dimension quality scoring rubric
+- [specs/ux-writing.md](specs/ux-writing.md) — UX writing standards (labels, errors, empty states, voice)
 
 ## Session Directory
 
@@ -101,7 +105,8 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5
 │   ├── design-system-analysis.json
 │   ├── component-inventory.json
 │   ├── accessibility-audit.json
-│   └── design-intelligence.json
+│   ├── design-intelligence.json
+│   └── visual-quality-baseline.json
 ├── design/                    # Designer output
 │   ├── design-tokens.json
 │   ├── component-specs/

package/.claude/skills/team-uidesign/roles/designer/role.md

@@ -28,16 +28,35 @@ Define visual language through design tokens (W3C Design Tokens Format) and comp
 
 **Token System Design (DESIGN-001)**:
 - Define complete token system following W3C Design Tokens Format
-- Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide)
+- Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide), Motion Easing, Motion Duration, Motion Stagger
+- **Color tokens MUST use OKLCH values** (reference `specs/design-standards.md` Color section)
+- Neutrals: tint toward brand hue with chroma 0.005-0.01 (never pure gray)
+- Add semantic colors: success (oklch hue 145), warning (hue 85), error (hue 25), info (hue 250)
+- **Typography**: choose from recommended fonts (Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces -- NOT Inter/Roboto/Open Sans/Lato/Montserrat/Arial), apply modular scale ratio, define fluid `clamp()` values for display sizes
+- **Spacing**: follow 4pt scale (0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96)
+- **Motion tokens**: define easing (ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)` as default), duration scale (instant 100ms, fast 150ms, normal 250ms, slow 400ms, entrance 500ms, complex 800ms), reduced-motion strategy
 - All color tokens must have light/dark variants using `$value: { light: ..., dark: ... }`
 - Integrate design intelligence: recommended.colors -> color tokens, recommended.typography -> font stacks
 - Document anti-patterns from design intelligence for implementer reference
+- Output categories must include: color, typography, spacing, shadow, border, breakpoint, motion_easing, motion_duration, motion_stagger
 - Output: `<session>/design/design-tokens.json`
 
 **Component Specification (DESIGN-002)**:
 - Define component specs consuming design tokens
-- Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (default/hover/focus/active/disabled), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints
-- All interactive states required: default, hover (background/opacity change), focus (outline 2px solid, offset 2px), active (pressed), disabled (opacity 0.5, cursor not-allowed)
+- Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (**all 8 required**), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints, Visual Hierarchy Notes (where component sits in hierarchy, CTA level: primary/secondary/tertiary)
+- **8 interaction states required** (reference `specs/design-standards.md` Interaction States):
+  - Default: base appearance
+  - Hover: subtle bg/opacity change, wrap in `@media(hover:hover)` guard
+  - Focus: `:focus-visible` with `outline: 2px solid var(--color-primary); outline-offset: 2px` (NOT bare `:focus`)
+  - Active: `scale(0.97)` or darker background
+  - Disabled: `opacity 0.5, cursor: not-allowed` via `[disabled], [aria-disabled="true"]`
+  - Loading: spinner/skeleton via `[aria-busy="true"]`
+  - Error: red border + message via `[aria-invalid="true"]`
+  - Success: green check + message
+- Touch targets: minimum 44x44px for all interactive components
+- UX Writing: button labels (verb+object), error message templates (what+why+fix), empty state copy pattern, loading text pattern. Reference `specs/ux-writing.md`
+- Dark Mode: if light+dark tokens, ensure dark mode follows rules: lighter surfaces for depth, reduced font weight, desaturated accents
+- Elevation: specify z-index layer for overlay/popup components using semantic scale (reference `specs/design-standards.md` Elevation)
 - Output: `<session>/design/component-specs/{component-name}.md`
 
 **GC Fix Mode (DESIGN-fix-N)**:
@@ -60,10 +79,15 @@ Define visual language through design tokens (W3C Design Tokens Format) and comp
 
 | Check | Pass Criteria |
 |-------|---------------|
-| states_complete | All 5 states (default/hover/focus/active/disabled) defined |
+| eight_states | All 8 states (default/hover/focus/active/disabled/loading/error/success) defined |
 | a11y_specified | Role, ARIA, keyboard behavior defined |
 | responsive_defined | At least mobile/desktop breakpoints |
 | token_refs_valid | All `{token.path}` references resolve to defined tokens |
+| oklch_used | All color values use OKLCH notation |
+| no_generic_fonts | Primary font not in generic list (Inter/Roboto/Open Sans/Lato/Montserrat/Arial) |
+| motion_tokens_present | Easing + duration tokens defined in token system |
+| reduced_motion | Reduced motion strategy documented |
+| ux_writing_specified | Button labels are verb+object, error/empty/loading text patterns defined |
 
 3. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
    - Read existing -> merge `{ "designer": { task_type, token_categories, component_count, style_decisions } }` -> write back

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

@@ -34,6 +34,18 @@ Translate design tokens and component specifications into production code. Gener
   - `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
 
@@ -44,9 +56,16 @@ Translate design tokens and component specifications into production code. Gener
   - `{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 5 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
+- 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
-- Check implementation against design intelligence anti_patterns
+- 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
 
@@ -64,9 +83,12 @@ Translate design tokens and component specifications into production code. Gener
 |-------|---------------|
 | 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 styles | `:focus` or `:focus-visible` defined |
+| 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/.claude/skills/team-uidesign/roles/researcher/role.md

@@ -31,6 +31,11 @@ Analyze existing design system, build component inventory, assess accessibility
 
 3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) 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
 
@@ -41,6 +46,8 @@ Execute 4 analysis streams:
 - 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**:
@@ -63,11 +70,22 @@ Execute 4 analysis streams:
 - Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
 - Output: `<session>/research/design-intelligence.json`
 
-Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count.
+**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 4 output files exist and contain valid JSON with required fields:
+1. Verify all 5 output files exist and contain valid JSON with required fields:
 
 | File | Required Fields |
 |------|----------------|
@@ -75,6 +93,7 @@ Compile research summary metrics: design_system_exists, styling_approach, total_
 | 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
 

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

@@ -27,39 +27,41 @@ Audit design tokens and component specs for consistency, accessibility complianc
 
 ## Phase 3: Audit Execution
 
-Score 5 dimensions on 1-10 scale:
+Score 8 dimensions on 0-4 scale (reference `specs/scoring-guide.md`). Total: 0-32.
 
 | Dimension | Weight | Focus |
 |-----------|--------|-------|
-| Consistency | 20% | Token usage, naming conventions, visual uniformity |
-| Accessibility | 25% | WCAG AA compliance, ARIA attributes, keyboard nav, contrast |
-| Completeness | 20% | All states defined, responsive specs, edge cases |
-| Quality | 15% | Token reference integrity, documentation clarity, maintainability |
-| Industry Compliance | 20% | Anti-pattern avoidance, UX best practices, design intelligence adherence |
+| 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**: Naming convention (kebab-case, semantic names), value patterns (consistent units), theme completeness (light+dark for all colors), contrast ratios (text on background >= 4.5:1), minimum font sizes (>= 12px), all categories present, W3C $type metadata, no duplicates.
+**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**: Token references resolve, naming matches convention, ARIA roles defined, keyboard behavior specified, focus indicator defined, all 5 states present, responsive breakpoints specified, variants documented, clear descriptions.
+**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).
-
-**Score calculation**: `overallScore = round(consistency*0.20 + accessibility*0.25 + completeness*0.20 + quality*0.15 + industryCompliance*0.20)`
+**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 >= 8 AND critical_count === 0 | `audit_passed` (GC CONVERGED) |
-| Score >= 6 AND critical_count === 0 | `audit_result` (GC REVISION NEEDED) |
-| Score < 6 OR critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) |
+| 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, signal, critical/high/medium counts
+   - Summary: overall score (out of 32), signal, rating band (Excellent/Good/Acceptable/Poor/Critical)
    - Sync Point Status (if applicable): PASSED/BLOCKED
-   - Dimension Scores table (score/weight/weighted per dimension)
-   - Critical/High/Medium issues with descriptions, locations, fix suggestions
+   - 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