claude-code-workflow 7.2.26 → 7.2.28

package/.claude/skills/team-ui-polish/roles/optimizer/role.md

@@ -0,0 +1,225 @@
+---
+role: optimizer
+prefix: OPT
+inner_loop: true
+message_types: [opt_complete, opt_progress, error]
+---
+
+# UI Optimizer -- Targeted Fix Application
+
+Apply targeted fixes following Impeccable design standards. Consumes diagnosis report and applies fixes in dependency order. Acts as Generator in the optimizer<->verifier Generator-Critic loop.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan report | <session>/scan/scan-report.md | Yes |
+| Diagnosis report | <session>/diagnosis/diagnosis-report.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Fix strategies | specs/fix-strategies.md | Yes |
+| Design standards | specs/design-standards.md | Yes |
+| Verification feedback | <session>/verification/verify-report.md | Only for GC fix tasks |
+
+1. Extract session path from task description
+2. Read diagnosis report: parse root cause groups, fix dependency graph, recommended fix order
+3. Read scan report: parse positive findings (things to preserve)
+4. Read specs/fix-strategies.md and specs/design-standards.md for fix reference
+5. Detect task type from subject: "OPT-001" -> initial optimization, "OPT-fix-*" -> GC fix round
+6. If GC fix task: read verification feedback for specific regressions to fix
+
+## Phase 3: Apply Fixes
+
+Follow the fix dependency graph from diagnosis report. Apply fixes in order, one category at a time. After each category, self-validate before proceeding.
+
+**CRITICAL**: Preserve positive findings from scan report. Do not break what already works.
+
+---
+
+### Fix Category 1: Anti-AI-Slop Fixes
+
+Target: Root cause groups tagged with anti-patterns dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Generic fonts (Inter, Roboto, Open Sans) | Replace with distinctive alternatives: Instrument Sans, Plus Jakarta Sans, Fraunces, DM Sans, Manrope, Space Grotesk, Geist |
+| Gradient text | Convert to solid accent color. Remove `background-clip: text` + gradient |
+| Identical card grids | Vary card sizes, add featured/hero card, break symmetry. Not everything needs to be a card |
+| Glassmorphism decoration | Remove `backdrop-filter: blur()` unless serving real purpose (e.g., overlays). Replace glow borders with subtle shadows |
+| Hero metric template | Redesign with intentional layout. Vary metric sizes by importance. Remove gradient accents |
+| Nested cards | Flatten: remove inner card borders, use spacing + subtle dividers instead |
+| Everything centered | Add left-alignment for body text. Use asymmetric layouts. Vary alignment per section |
+| All buttons primary | Create button hierarchy: 1 primary, ghost/outline for secondary, text links for tertiary |
+| Same spacing everywhere | Introduce spacing rhythm: tighter within groups, generous between sections |
+| Bounce/elastic easing | Replace with exponential curves: `cubic-bezier(0.25, 1, 0.5, 1)` (ease-out-quart) |
+
+---
+
+### Fix Category 2: Color Fixes
+
+Target: Root cause groups tagged with color dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Pure black (#000) | Replace with tinted near-black: `oklch(0.15 0.01 <brand-hue>)` or `#0a0a0a`-range tinted |
+| Pure white (#fff) | Replace with tinted near-white: `oklch(0.98 0.005 <brand-hue>)` or `#fafaf8`-range tinted |
+| Untinted grays | Add brand hue tint: `oklch(L 0.005-0.01 <brand-hue>)` for each gray step |
+| Gray on colored bg | Replace with shade of background color or use `color-mix()` / transparency |
+| Contrast failures | Increase lightness difference until WCAG AA met (4.5:1 text, 3:1 large text, 3:1 UI) |
+| No OKLCH | Convert key palette colors to `oklch()`. Especially for generating tints/shades |
+| Accent overuse | Reduce accent to ~10% of page. Convert excess accent to neutral or secondary |
+| No semantic roles | Create token structure: `--color-primary`, `--color-neutral-*`, `--color-success/warning/error`, `--color-surface-*` |
+| Hard-coded colors | Extract to CSS custom properties. Create design token file if none exists |
+
+---
+
+### Fix Category 3: Typography Fixes
+
+Target: Root cause groups tagged with typography dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Overused fonts | Replace with distinctive alternatives. Body: Plus Jakarta Sans, Instrument Sans, DM Sans. Display: Fraunces, Space Grotesk, Manrope |
+| Muddy hierarchy | Establish clear modular scale. Remove intermediate sizes. Target: 5-7 distinct sizes |
+| No modular scale | Define scale with ratio (1.25 major third, 1.333 perfect fourth, 1.5 perfect fifth). Base: 16px |
+| Small body text | Set minimum `font-size: 1rem` (16px) for body. 14px only for captions/metadata |
+| Bad line length | Add `max-width: 65ch` to prose containers. Min 45ch, max 75ch |
+| Inconsistent line-height | Establish system: 1.5 for body, 1.2-1.3 for headings, 1.6-1.7 for small text |
+| No fluid sizing | Add `clamp()` for h1-h3: e.g., `font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem)` |
+| Missing font-display | Add `font-display: swap` to all @font-face declarations |
+
+---
+
+### Fix Category 4: Spacing & Layout Fixes
+
+Target: Root cause groups tagged with spacing dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Arbitrary spacing | Replace with nearest value on 4pt scale: 4, 8, 12, 16, 24, 32, 48, 64, 96px |
+| No spacing scale | Create CSS custom properties: `--space-1: 0.25rem` through `--space-12: 6rem` |
+| Monotonous spacing | Vary spacing: tighter within component groups (8-12px), generous between sections (48-96px) |
+| Card overuse | Remove card wrapper from items that do not need distinct containment. Use spacing + dividers |
+| Nested cards | Flatten inner cards. Remove inner borders. Use spacing or subtle background tint |
+| Fixed widths | Replace `width: Npx` with `max-width` + `width: 100%` or grid/flex |
+| Small touch targets | Set `min-height: 44px; min-width: 44px` on all interactive elements |
+| Margin for siblings | Replace `margin-top/bottom` between siblings with `gap` on flex/grid parent |
+
+---
+
+### Fix Category 5: Motion Fixes
+
+Target: Root cause groups tagged with motion dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Layout property animation | Replace `width/height/top/left/margin/padding` transitions with `transform` + `opacity` |
+| Bad easing | Replace `ease`, `linear`, `ease-in-out` with `cubic-bezier(0.25, 1, 0.5, 1)` (ease-out-quart) |
+| Bounce/elastic | Replace with exponential: `cubic-bezier(0.25, 1, 0.5, 1)` for enter, `cubic-bezier(0.5, 0, 0.75, 0)` for exit |
+| No reduced-motion | Add: `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }` |
+| No motion tokens | Create: `--duration-instant: 100ms`, `--duration-fast: 150ms`, `--duration-normal: 250ms`, `--duration-slow: 400ms`, `--duration-entrance: 500ms` |
+| Uncapped stagger | Cap at 10 items visible, total stagger <= 500ms. Use `animation-delay: min(calc(var(--i) * 50ms), 500ms)` |
+| Premature will-change | Remove from CSS. Add via JS on `pointerenter`/`focusin`, remove on `animationend`/`transitionend` |
+
+---
+
+### Fix Category 6: Interaction State Fixes
+
+Target: Root cause groups tagged with interaction dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Missing hover | Add `:hover` with subtle background change or opacity shift. Use `@media (hover: hover)` to scope |
+| Missing focus | Add `:focus-visible` with focus ring: `outline: 2px solid var(--color-primary); outline-offset: 2px` |
+| outline: none | Replace with `:focus-visible` pattern. Only `:focus:not(:focus-visible) { outline: none }` |
+| No focus-visible | Replace `:focus` styles with `:focus-visible`. Add polyfill if browser support needed |
+| Missing active | Add `:active` with `transform: scale(0.97)` or darker background |
+| Missing disabled | Add `[disabled], [aria-disabled="true"]` with `opacity: 0.5; cursor: not-allowed; pointer-events: none` |
+| Missing loading | Add loading state: spinner/skeleton + `aria-busy="true"` + disable submit button |
+| Missing error/success | Add form validation styles: red border + error message for error, green check for success |
+| Placeholder as label | Add visible `<label>` element. Keep placeholder as hint only. Use `aria-labelledby` if needed |
+| Focus ring quality | Ensure: 2px solid accent, offset 2px, 3:1 contrast ratio against background |
+
+---
+
+### Fix Category 7: Visual Hierarchy Fixes
+
+Target: Root cause groups tagged with hierarchy dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Fails squint test | Increase size/weight/color contrast of primary element. Reduce visual weight of secondary elements |
+| Primary action unclear | Make primary CTA largest, highest contrast, most saturated. Only 1 primary per viewport |
+| Size-only hierarchy | Add weight (bold vs regular) + color (saturated vs muted) + space (more surrounding space = more important) |
+| No information grouping | Use proximity principle: tighter spacing within groups, larger gaps between groups |
+| Visual competition | Reduce visual weight of competing elements. Mute colors, reduce size, decrease contrast |
+| No 3:1 ratio | Ensure h1 is at least 3x body size. Each heading level should be 1.25-1.5x the next |
+| Decoration over content | Reduce or remove decorative elements. Mute icon colors. Remove background decorations |
+
+---
+
+### Fix Category 8: Responsive Fixes
+
+Target: Root cause groups tagged with responsive dimension.
+
+| Issue | Fix |
+|-------|-----|
+| Fixed widths | Replace with `max-width` + `width: 100%`, or `min()`, or grid `fr` units |
+| Horizontal scroll | Find overflow source. Add `overflow-x: hidden` on body only as last resort. Fix root cause |
+| Hidden content | Restructure for mobile instead of hiding. Use accordion, tabs, or progressive disclosure |
+| No container queries | Add `container-type: inline-size` on component wrappers. Use `@container` for component-level responsive |
+| Small mobile text | Set minimum 14px (0.875rem) for all text on mobile. Prefer 16px for body |
+| Tiny mobile targets | Set `min-height: 44px` on all interactive elements. Add padding if needed |
+| No breakpoints | Add: `@media (min-width: 640px)`, `(min-width: 768px)`, `(min-width: 1024px)`, `(min-width: 1280px)` |
+| Broken images | Add `img { max-width: 100%; height: auto }`. Use `object-fit` for fixed aspect ratios |
+
+---
+
+## Phase 4: Self-Validation & Output
+
+1. After all fixes applied, validate:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Code compiles | No syntax errors in modified files |
+| Lint passes | No new lint errors introduced |
+| No positive findings broken | Items from scan report "Positive Findings" section still intact |
+| Fix log complete | Every applied fix documented |
+
+2. Write fix log: `<session>/optimization/fix-log.md`
+
+```markdown
+# Optimization Fix Log
+
+## Summary
+- Fixes applied: N
+- Files modified: N
+- Categories addressed: <list>
+- GC round: <1 | fix-N>
+
+## Fixes Applied
+
+### Category: <category name>
+| # | File | Line | Before | After | Issue Ref |
+|---|------|------|--------|-------|-----------|
+| 1 | path/to/file.css | 42 | `color: #000` | `color: oklch(0.15 0.01 250)` | P1-Color-3 |
+
+### Category: <next category>
+...
+
+## Files Modified
+- `path/to/file.css`: <summary of changes>
+- `path/to/file.tsx`: <summary of changes>
+
+## Preserved (not modified)
+- <positive findings that were intentionally kept>
+
+## Metadata
+- Source diagnosis: <session>/diagnosis/diagnosis-report.md
+- Timestamp: <ISO timestamp>
+```
+
+3. Send completion message:
+```
+mcp__ccw-tools__team_msg(session_id, role="optimizer", type="opt_complete", content="Optimization complete. Fixes applied: N. Files modified: N. Categories: <list>.")
+SendMessage(participant="coordinator", message="[optimizer] OPT-001 complete. Applied N fixes across N files. Categories: <list>. Log: <session>/optimization/fix-log.md")
+```

package/.claude/skills/team-ui-polish/roles/scanner/role.md

@@ -0,0 +1,356 @@
+---
+role: scanner
+prefix: SCAN
+inner_loop: false
+message_types: [scan_complete, scan_progress, error]
+---
+
+# UI Scanner -- 8-Dimension Design Audit
+
+Scan existing UI against Impeccable's 8 audit dimensions to discover all design problems. This is the team's core diagnostic engine. Every issue found here drives the entire downstream pipeline.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Target files or URL | From task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Anti-patterns catalog | specs/anti-patterns.md | Yes |
+| Design standards | specs/design-standards.md | Yes |
+
+1. Extract session path and target from task description
+2. Read specs/anti-patterns.md and specs/design-standards.md for reference criteria
+3. Load target files based on target type:
+   - **URL target**: Use Chrome DevTools to navigate, take screenshots at 3 viewports:
+     - Mobile: `mcp__chrome-devtools__resize_page(width=375, height=812)` + screenshot
+     - Tablet: `mcp__chrome-devtools__resize_page(width=768, height=1024)` + screenshot
+     - Desktop: `mcp__chrome-devtools__resize_page(width=1440, height=900)` + screenshot
+     - Save to `<session>/evidence/before-mobile.png`, `before-tablet.png`, `before-desktop.png`
+   - **Component target**: Read CSS/SCSS, HTML, JS/TS/JSX/TSX files
+   - **Full site target**: Glob for all frontend source files (*.css, *.scss, *.tsx, *.jsx, *.html, *.vue, *.svelte)
+4. Extract raw data for analysis:
+   - All color values (hex, rgb, hsl, oklch, named colors, CSS custom properties)
+   - All font declarations (font-family, font-size, font-weight, line-height)
+   - All spacing values (margin, padding, gap, inset)
+   - All animation/transition declarations
+   - All interactive pseudo-classes and state handling
+5. If Chrome DevTools available: extract computed styles via `mcp__chrome-devtools__evaluate_script`
+
+## Phase 3: 8-Dimension Scan
+
+For each dimension, check every item in the checklist. Record each finding with:
+- Location: file:line (or "screenshot: viewport" for visual-only issues)
+- Severity: P0 (blocking) / P1 (major) / P2 (minor) / P3 (polish)
+- Description: what is wrong and why it matters
+- Evidence: the specific code or visual that triggers the finding
+
+---
+
+### Dimension 1: Anti-AI-Slop Detection (CRITICAL -- scan first)
+
+**The AI Slop Test**: "If you showed this to someone and said 'AI made this,' would they believe you immediately? If yes, that is the problem."
+
+Check for these AI-generated UI fingerprints:
+
+| # | Pattern | What to Look For | Severity |
+|---|---------|-------------------|----------|
+| 1 | AI color palette | cyan-on-dark (#00d4ff, #06b6d4), purple-to-blue gradients, neon accents on dark backgrounds | P1 |
+| 2 | Gradient text | `background-clip: text` + gradient on metrics, headings, or hero text for "impact" | P1 |
+| 3 | Default dark mode | Dark background with glowing/neon accents as the default theme; avoids real design decisions | P2 |
+| 4 | Glassmorphism everywhere | `backdrop-filter: blur()`, glass cards, glow borders (`box-shadow: 0 0 Xpx color`), used decoratively not functionally | P1 |
+| 5 | Hero metric layout | Big number + small label + supporting stats in a row + gradient accent. The "AI dashboard" template | P2 |
+| 6 | Identical card grids | Same-sized cards with icon + heading + body text repeated 3-6 times in a grid | P2 |
+| 7 | Nested cards | Cards inside cards (`.card .card`, multiple layers of bordered containers) | P2 |
+| 8 | Generic fonts | Inter, Roboto, Arial, Open Sans, Lato, Montserrat, system-ui used without intentional choice | P2 |
+| 9 | Rounded rect + shadow | `border-radius: 8-16px` + `box-shadow: 0 1-4px 6-24px rgba(0,0,0,0.1)` on everything | P3 |
+| 10 | Icon-above-heading | Large icons (24-48px) with rounded corners/background placed above every heading or card | P2 |
+| 11 | One-side border accent | `border-left: 3-4px solid <accent>` or `border-top` as lazy accent on cards | P3 |
+| 12 | Decorative sparklines | Tiny charts/graphs that look sophisticated but convey no actionable data | P2 |
+| 13 | Bounce/elastic easing | `cubic-bezier(0.68, -0.55, 0.265, 1.55)` or spring animations. Dated, 2015 aesthetic | P2 |
+| 14 | Redundant copy | Intro paragraphs that restate the heading. "Welcome to Dashboard. This dashboard shows..." | P3 |
+| 15 | All buttons primary | Every button is filled/primary. No ghost buttons, text links, or secondary variants | P1 |
+| 16 | Everything centered | `text-align: center` or `justify-content: center` on everything. No asymmetry | P2 |
+| 17 | Same spacing everywhere | Identical margin/padding on all elements. No spacing rhythm or variation | P2 |
+| 18 | Monospace as tech | Monospace fonts used for non-code content to appear "techy" | P3 |
+| 19 | Modal overuse | Modals for confirmations, settings, forms -- when inline or drawer would work | P3 |
+| 20 | Pure black/white | `#000000` or `#ffffff` without any tint toward brand hue | P1 |
+
+**Scoring**:
+- 0: AI slop gallery (5+ tells present)
+- 1: Heavy AI influence (3-4 tells)
+- 2: Some AI tells (1-2 noticeable)
+- 3: Mostly clean (subtle traces only)
+- 4: Distinctive (genuinely intentional design, zero AI tells)
+
+---
+
+### Dimension 2: Color Quality
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Pure black usage | `#000`, `#000000`, `rgb(0,0,0)` anywhere except borders/outlines | P1 |
+| 2 | Pure white usage | `#fff`, `#ffffff`, `rgb(255,255,255)` for backgrounds without brand tint | P1 |
+| 3 | Untinted grays | Gray values with chroma exactly 0 (pure gray). Should have chroma 0.005-0.01 toward brand hue | P2 |
+| 4 | Gray on colored bg | Gray text (#666, #999, etc.) on colored backgrounds. Looks washed out. Use shade of background or transparency | P1 |
+| 5 | WCAG AA contrast | Text contrast below 4.5:1 (normal text) or 3:1 (large text >= 18px/24px bold) | P0 |
+| 6 | UI component contrast | Interactive component boundaries below 3:1 contrast against adjacent colors | P1 |
+| 7 | No OKLCH | All colors in hex/rgb/hsl without oklch() for perceptual uniformity | P2 |
+| 8 | Accent overuse | Accent color exceeds 10% of visual weight. Violates 60-30-10 rule (60% neutral, 30% secondary, 10% accent) | P2 |
+| 9 | No semantic roles | Colors not organized into primary/neutral/semantic(success,warning,error)/surface layers | P2 |
+| 10 | Hard-coded colors | Color values inline in components instead of CSS custom properties or design tokens | P2 |
+| 11 | No dark/light tokens | Single-theme colors without alternate theme support | P3 |
+
+**Scoring**:
+- 0: Multiple contrast failures, pure black/white everywhere, no system
+- 1: Contrast issues, hard-coded colors, no tokens
+- 2: Basic contrast OK but no OKLCH, some hard-coded values
+- 3: Good system with minor gaps (some untinted grays or missing tokens)
+- 4: OKLCH-based, fully tokenized, WCAG AA+ compliant, proper 60-30-10
+
+---
+
+### Dimension 3: Typography Quality
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Overused fonts | Inter, Roboto, Open Sans, Lato, Montserrat, Arial without intentional justification | P2 |
+| 2 | Muddy hierarchy | Too many close font sizes (e.g., 13/14/15/16/18). Should have clear steps | P1 |
+| 3 | No modular scale | Font sizes without mathematical ratio (1.125, 1.2, 1.25, 1.333, 1.5, 1.618) | P2 |
+| 4 | Small body text | Body/paragraph text below 16px (1rem) | P1 |
+| 5 | Line length | Body text wider than 75ch or narrower than 45ch. Optimal: 65ch | P2 |
+| 6 | Inconsistent line-height | Different line-heights without system. Should follow vertical rhythm | P2 |
+| 7 | No fluid sizing | Headings without `clamp()` for responsive scaling. Fixed px that are too big on mobile or too small on desktop | P2 |
+| 8 | Monospace misuse | Monospace fonts for non-code body content used as "tech" aesthetic | P3 |
+| 9 | Missing font-display | No `font-display: swap` causing FOIT (flash of invisible text) | P2 |
+| 10 | Too many font families | More than 2-3 font families in use (excluding monospace for code) | P2 |
+| 11 | No fallback metrics | Custom fonts without `size-adjust`, `ascent-override` for CLS prevention | P3 |
+
+**Scoring**:
+- 0: Generic font, no scale, tiny text, no hierarchy
+- 1: Overused font, muddy sizes, missing fluid sizing
+- 2: Decent font choice but inconsistent scale or line-height
+- 3: Good typography with minor gaps (missing clamp, slight inconsistencies)
+- 4: Distinctive font, clear modular scale, fluid sizing, proper rhythm
+
+---
+
+### Dimension 4: Spacing & Layout Quality
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Arbitrary spacing | Spacing values outside a consistent scale (e.g., 7px, 13px, 22px, 37px) | P2 |
+| 2 | No spacing scale | No evidence of 4pt base (4, 8, 12, 16, 24, 32, 48, 64, 96px) or similar system | P2 |
+| 3 | Monotonous spacing | Same padding/margin value everywhere. No rhythm (tight groups + generous separations) | P2 |
+| 4 | Card overuse | Everything wrapped in cards. Cards for single text items, cards for navigation, cards for everything | P2 |
+| 5 | Nested cards | Cards inside cards. Multiple bordered containers creating visual noise | P1 |
+| 6 | Fixed widths | Hard-coded pixel widths that break on different viewports | P1 |
+| 7 | Small touch targets | Interactive elements below 44x44px (buttons, links, inputs on mobile) | P1 |
+| 8 | Margin for siblings | Using `margin` between sibling elements instead of `gap` on parent | P3 |
+| 9 | No optical adjustment | Purely mathematical centering without optical corrections (e.g., play button in circle) | P3 |
+| 10 | No max-width on prose | Text containers without max-width causing ultra-wide line lengths | P2 |
+
+**Scoring**:
+- 0: Random spacing, nested cards, fixed widths, tiny touch targets
+- 1: Some system but many arbitrary values, cards overused
+- 2: Decent spacing but monotonous or missing rhythm
+- 3: Good system with minor gaps (occasional arbitrary value)
+- 4: Consistent scale, varied rhythm, gap usage, proper touch targets
+
+---
+
+### Dimension 5: Motion & Animation Quality
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Layout property animation | Animating `width`, `height`, `top`, `left`, `margin`, `padding` (causes layout thrashing) | P1 |
+| 2 | Bad easing | Using `ease` (default), `linear`, or `ease-in-out` for UI transitions. Should use exponential curves | P2 |
+| 3 | Bounce/elastic | `cubic-bezier(0.68, -0.55, 0.265, 1.55)` or similar bounce curves. Dated aesthetic | P2 |
+| 4 | No reduced-motion | Missing `@media (prefers-reduced-motion: reduce)` query. Affects ~35% of adults over 40 | P0 |
+| 5 | No motion tokens | No consistent duration/easing system. Random 200ms/300ms/0.5s values | P2 |
+| 6 | Uncapped stagger | Stagger animation over 10 items or total duration > 500ms | P2 |
+| 7 | Premature will-change | `will-change` set in CSS instead of activated on interaction (wastes GPU memory) | P3 |
+| 8 | No exit animation | Elements appear with animation but disappear instantly | P3 |
+| 9 | Slow feedback | Hover/focus/active feedback slower than 150ms | P2 |
+| 10 | Animation on load | Heavy entrance animations on page load that delay content access | P2 |
+
+**Scoring**:
+- 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 missing reduced-motion
+- 3: Good system with minor gaps (occasional bad easing, missing exit animation)
+- 4: Transform+opacity only, exponential easing, reduced-motion, token system, proper stagger
+
+---
+
+### Dimension 6: Interaction States
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Missing hover | Interactive elements without `:hover` state (no pointer feedback) | P1 |
+| 2 | Missing focus | Interactive elements without `:focus` state (keyboard users invisible) | P0 |
+| 3 | outline: none | `outline: none` or `outline: 0` without replacement focus indicator | P0 |
+| 4 | No focus-visible | Using `:focus` instead of `:focus-visible` (showing focus ring on mouse click) | P2 |
+| 5 | Missing active | No `:active` / pressed state on buttons/links | P2 |
+| 6 | Missing disabled | No visual distinction for disabled state, or `disabled` without opacity/cursor change | P2 |
+| 7 | Missing loading | Async actions (form submit, API calls) without loading feedback | P1 |
+| 8 | Missing error/success | Forms without error/success state indication | P1 |
+| 9 | Placeholder as label | `placeholder` used as the only label for form inputs (disappears on focus) | P1 |
+| 10 | No empty state | Lists/tables without empty state design (blank space when no data) | P2 |
+| 11 | Focus ring quality | Focus ring not meeting 2px solid accent, offset 2px, 3:1 contrast spec | P2 |
+
+**Scoring**:
+- 0: No hover, no focus, outline:none everywhere, no loading states
+- 1: Basic hover but missing focus/active, no loading states
+- 2: Hover + focus exist but no focus-visible, missing some states
+- 3: Most states present with minor gaps (missing empty state, imperfect focus ring)
+- 4: All 8 states implemented, focus-visible, proper focus ring, loading/error/success/empty
+
+---
+
+### Dimension 7: Visual Hierarchy
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Fails squint test | When page is blurred/squinted, cannot identify 1st and 2nd most important elements | P1 |
+| 2 | Primary action unclear | Cannot identify the primary action within 2 seconds of viewing | P1 |
+| 3 | Size-only hierarchy | Hierarchy established only through font size, not combining size + weight + color + space | P2 |
+| 4 | No information grouping | Related content not grouped by proximity. Equal spacing between related and unrelated items | P2 |
+| 5 | Visual competition | Multiple elements competing for attention at the same visual weight | P1 |
+| 6 | No 3:1 ratio | Less than 3:1 size ratio between major hierarchy levels (e.g., h1 vs body) | P2 |
+| 7 | Decoration over content | Visual decorations (icons, borders, backgrounds) draw more attention than content | P2 |
+| 8 | No progressive disclosure | All information shown at once. No layering of detail (summary -> detail on demand) | P3 |
+
+**Scoring**:
+- 0: Everything same visual weight, no clear action, fails squint test
+- 1: Some size differences but no clear hierarchy system
+- 2: Basic hierarchy via size but missing weight/color/space dimensions
+- 3: Good hierarchy with minor issues (occasional visual competition)
+- 4: Clear squint test pass, obvious primary action, multi-dimension hierarchy, progressive disclosure
+
+---
+
+### Dimension 8: Responsive Design
+
+| # | Check | What to Look For | Severity |
+|---|-------|-------------------|----------|
+| 1 | Fixed widths | Hard-coded pixel widths that break below certain viewport sizes | P1 |
+| 2 | Horizontal scroll | Content causing horizontal scrollbar on viewports >= 320px | P0 |
+| 3 | Hidden content | Content hidden on mobile via `display:none` instead of being adapted/restructured | P2 |
+| 4 | No container queries | Components that should adapt to container size still using viewport media queries only | P3 |
+| 5 | Small mobile text | Text below 14px on mobile viewports (illegible without zoom) | P1 |
+| 6 | Tiny mobile targets | Touch targets below 44x44px on mobile (frustrating to tap) | P1 |
+| 7 | No breakpoints | Single layout for all viewports. No media queries or responsive grid | P1 |
+| 8 | Broken images | Images that overflow or distort on narrow viewports (missing max-width:100%) | P1 |
+| 9 | No viewport meta | Missing `<meta name="viewport" content="width=device-width, initial-scale=1">` | P0 |
+| 10 | Desktop-first only | Only desktop layout works properly. Mobile is broken or unusable | P1 |
+
+**Scoring**:
+- 0: No responsive design, horizontal scroll, broken on mobile
+- 1: Basic media queries but many breakage points
+- 2: Decent mobile but some fixed widths or small targets
+- 3: Good responsive with minor issues (missing container queries, occasional small target)
+- 4: Fluid design, proper breakpoints, container queries, 44px targets, no overflow
+
+---
+
+### Dimension 9: Cognitive Load
+
+Evaluate information processing burden per Impeccable's cognitive load principles.
+
+| Check | Detection | Score Impact |
+|-------|-----------|-------------|
+| Information overload | >7 distinct data groups visible simultaneously without progressive disclosure | -1 per violation |
+| Choice overload | >5 equally-weighted CTAs in one viewport | -1 |
+| No progressive disclosure | All details shown at once, no expand/collapse or summary→detail | -1 |
+| Redundant copy | Heading text repeated in body paragraph (>50% overlap) | -0.5 |
+| Generic labels | "OK/Submit/Cancel" buttons without verb+object | -0.5 |
+| Error without guidance | Error messages missing what+why+fix formula | -1 |
+| Empty state without action | Data list shows "No data" without create/import guidance | -0.5 |
+| No visual grouping | Related items not proximity-grouped or separated from unrelated | -1 |
+
+### Dimension 10: Dark Mode Quality
+
+Only score if dark mode exists. Skip and note "N/A — no dark mode" if not present.
+
+| Check | Detection | Score Impact |
+|-------|-----------|-------------|
+| Pure black background | #000 or rgb(0,0,0) as base background | -2 |
+| Same font weights as light | No weight reduction in dark theme | -1 |
+| Saturated accents on dark | Same chroma values as light theme (vibrating colors) | -1 |
+| No surface hierarchy | All dark surfaces same lightness (flat, no depth) | -1 |
+| Dangerous combinations | Gray text on colored bg, saturated red-green adjacent | -1 |
+
+---
+
+## Phase 4: Generate Scan Report
+
+Output: `<session>/scan/scan-report.md`
+
+Report structure:
+
+```markdown
+# UI Polish Scan Report
+
+## Overall Score: X/36 (<rating-band>)
+
+## Anti-Patterns Verdict (Dimension 1)
+Score: X/4
+<verdict summary -- this section comes FIRST as it is most important>
+<list of detected AI slop tells>
+
+## Per-Dimension Scores
+
+| Dimension | Score | Key Finding |
+|-----------|-------|-------------|
+| 1. Anti-Patterns | X/4 | <one-line summary> |
+| 2. Color Quality | X/4 | <one-line summary> |
+| 3. Typography | X/4 | <one-line summary> |
+| 4. Spacing/Layout | X/4 | <one-line summary> |
+| 5. Motion | X/4 | <one-line summary> |
+| 6. Interaction States | X/4 | <one-line summary> |
+| 7. Visual Hierarchy | X/4 | <one-line summary> |
+| 8. Responsive | X/4 | <one-line summary> |
+| 9. Cognitive Load | X/4 | <one-line summary> |
+| 10. Dark Mode | X/4 or N/A | <one-line summary> |
+
+## Issue Inventory
+
+### P0 -- Blocking
+| # | Dimension | Location | Description |
+|---|-----------|----------|-------------|
+| 1 | ... | file:line | ... |
+
+### P1 -- Major
+...
+
+### P2 -- Minor
+...
+
+### P3 -- Polish
+...
+
+## Patterns & Systemic Issues
+<recurring problems that affect multiple locations>
+
+## Positive Findings
+<what works well -- important for optimizer to not break>
+
+## Scan Metadata
+- Target: <target>
+- Files scanned: <count>
+- Screenshots: <yes/no, viewports>
+- Timestamp: <ISO timestamp>
+```
+
+**Rating Bands** (total out of 36, or 40 with dark mode):
+- 32-36: Excellent (36-40 with dark mode)
+- 25-31: Good (29-35 with dark mode)
+- 18-24: Acceptable (22-28 with dark mode)
+- 11-17: Poor (15-21 with dark mode)
+- 0-10: Critical (0-14 with dark mode)
+
+After writing the report, send completion message:
+```
+mcp__ccw-tools__team_msg(session_id, role="scanner", type="scan_complete", content="Scan complete. Score: X/36. P0: N, P1: N, P2: N, P3: N issues found.")
+SendMessage(participant="coordinator", message="[scanner] SCAN-001 complete. Score: X/36 (<rating-band>). Issues: P0=N P1=N P2=N P3=N. Report: <session>/scan/scan-report.md")
+```