claude-code-workflow 7.2.26 → 7.2.28

package/.claude/skills/team-uidesign/specs/design-standards.md

@@ -0,0 +1,329 @@
+# Impeccable Design Standards
+
+Reference spec for all roles. Every design decision must trace back to these standards.
+
+---
+
+## Color (OKLCH)
+
+OKLCH for perceptually uniform palettes. All color tokens MUST use OKLCH notation.
+
+### Token Hierarchy
+
+primitive -> semantic -> component
+
+```
+/* Primitives */
+--color-primary          oklch(0.55 0.2 250)
+--color-primary-light    oklch(0.70 0.15 250)
+--color-primary-dark     oklch(0.40 0.22 250)
+
+/* Tinted neutrals (chroma 0.005-0.01, brand hue) */
+--color-neutral-50       oklch(0.98 0.005 250)  /* brand tinted */
+--color-neutral-100      oklch(0.95 0.006 250)
+--color-neutral-200      oklch(0.90 0.007 250)
+--color-neutral-300      oklch(0.82 0.007 250)
+--color-neutral-400      oklch(0.70 0.008 250)
+--color-neutral-500      oklch(0.55 0.008 250)
+--color-neutral-600      oklch(0.45 0.009 250)
+--color-neutral-700      oklch(0.35 0.009 250)
+--color-neutral-800      oklch(0.25 0.010 250)
+--color-neutral-900      oklch(0.15 0.010 250)
+--color-neutral-950      oklch(0.08 0.010 250)
+
+/* Semantic */
+--color-success          oklch(0.65 0.18 145)
+--color-warning          oklch(0.75 0.15 85)
+--color-error            oklch(0.55 0.22 25)
+--color-info             oklch(0.60 0.18 250)
+```
+
+### Rules
+
+- **60-30-10 rule**: 60% neutral, 30% secondary, 10% accent
+- **Never pure black** (`#000`) or **pure white** (`#fff`) -- use tinted neutrals
+- **Tinted neutrals**: chroma 0.005-0.01, hue matching brand primary
+- **Text on colored backgrounds**: use `color-mix(in oklch, ...)` not gray
+
+### Dark Mode Rules
+- Dark mode is NOT inverted light mode. It requires deliberate design:
+  - Use **lighter surfaces** for elevation/depth (not darker)
+  - **Reduce font weight** by 1 step (600→500, 500→400) — light text on dark looks heavier
+  - **Desaturate accent colors** — saturated colors vibrate on dark backgrounds
+  - Surface hierarchy: `oklch(0.15 ...)` base → `oklch(0.20 ...)` raised → `oklch(0.25 ...)` overlay
+- Never: pure black `#000` background (too harsh). Use `oklch(0.10 0.01 <hue>)` minimum
+- Test: all contrast ratios must meet WCAG AA in BOTH themes
+
+### Dangerous Color Combinations
+| Combination | Problem | Fix |
+|-------------|---------|-----|
+| Gray text on colored background | Looks washed out, low contrast | Use shade of bg color or white/dark with transparency |
+| Red + Green (adjacent) | 8% male color blindness | Add icons/patterns, not just color |
+| Yellow text on white | Near-invisible | Use dark amber instead |
+| Thin light text on images | Unpredictable contrast | Add text shadow or semi-transparent overlay |
+| Saturated colors on dark bg | Visual vibration | Desaturate: reduce OKLCH chroma by 0.05-0.10 |
+
+- **WCAG AA contrast**:
+  - Normal text: 4.5:1
+  - Large text (>= 18px bold or >= 24px): 3:1
+  - UI components and graphical objects: 3:1
+  - Focus indicators: 3:1
+
+---
+
+## Typography
+
+### Font Selection
+
+**Avoid** (overused defaults): Inter, Roboto, Open Sans, Lato, Montserrat, Arial
+
+**Recommended**: Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces
+
+### Modular Scale
+
+Choose one ratio for the project:
+
+| Name | Ratio | Use Case |
+|------|-------|----------|
+| Major Second | 1.125 | Dense UI, dashboards |
+| Minor Third | 1.200 | General purpose |
+| Major Third | 1.250 | Marketing, editorial |
+| Perfect Fourth | 1.333 | Bold, expressive |
+
+### Fluid Sizing
+
+Use `clamp()` for display and heading sizes:
+
+```css
+--text-sm:      clamp(0.8rem, 0.77rem + 0.15vw, 0.875rem);
+--text-base:    clamp(0.9rem, 0.85rem + 0.25vw, 1rem);
+--text-lg:      clamp(1.05rem, 0.95rem + 0.35vw, 1.125rem);
+--text-xl:      clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);
+--text-2xl:     clamp(1.5rem, 1.25rem + 0.75vw, 1.875rem);
+--text-3xl:     clamp(1.875rem, 1.5rem + 1.1vw, 2.25rem);
+--text-display: clamp(2.25rem, 1.75rem + 1.5vw, 3rem);
+```
+
+### Line Height
+
+- Body text: 1.5
+- Headings: 1.2
+- Small / caption text: 1.6
+
+### Reading Width
+
+`max-width: 65ch` (acceptable range: 45-75ch)
+
+### Font Loading
+
+`font-display: swap` with fallback metrics:
+
+```css
+@font-face {
+  font-family: 'Plus Jakarta Sans';
+  font-display: swap;
+  size-adjust: 102%;
+  ascent-override: 95%;
+}
+```
+
+---
+
+## Spacing (4pt Base)
+
+### Scale
+
+```
+0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96 px
+```
+
+Map to tokens:
+
+```
+--space-0:   0px;
+--space-1:   4px;    /* 0.25rem */
+--space-2:   8px;    /* 0.5rem */
+--space-3:   12px;   /* 0.75rem */
+--space-4:   16px;   /* 1rem */
+--space-5:   20px;   /* 1.25rem */
+--space-6:   24px;   /* 1.5rem */
+--space-8:   32px;   /* 2rem */
+--space-10:  40px;   /* 2.5rem */
+--space-12:  48px;   /* 3rem */
+--space-16:  64px;   /* 4rem */
+--space-24:  96px;   /* 6rem */
+```
+
+### Rhythm
+
+| Context | Spacing | Tokens |
+|---------|---------|--------|
+| Tight (within groups) | 4-8px | space-1, space-2 |
+| Comfortable (between items) | 16-24px | space-4 to space-6 |
+| Generous (between sections) | 48-96px | space-12 to space-24 |
+
+### Layout Rules
+
+- Use `gap` not `margin` for sibling spacing
+- Cards only for distinct actionable content -- flatten nested cards
+- Container queries for component-level responsive behavior
+- Touch targets: **44x44px minimum**, 8px gap between adjacent targets
+
+---
+
+## Motion
+
+### Animatable Properties (ONLY these)
+
+transform, opacity, clip-path, background-color, color, border-color, box-shadow, filter
+
+### NEVER Animate (layout triggers)
+
+width, height, top, left, margin, padding
+
+### Easing
+
+Default: ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)`
+
+NEVER use: `ease`, `linear`, `bounce`, `elastic`
+
+### Duration Scale
+
+| Token | Duration | Use |
+|-------|----------|-----|
+| --duration-instant | 100ms | Toggles, checkboxes |
+| --duration-fast | 150ms | Feedback, micro-interactions |
+| --duration-normal | 250ms | Standard transitions |
+| --duration-slow | 400ms | Panels, drawers |
+| --duration-entrance | 500ms | Page/section entrance |
+| --duration-complex | 800ms | Multi-step orchestration |
+
+- Exit duration = 75% of entrance
+- Feedback animations: 100-150ms max
+
+### Stagger
+
+- Max 10 items in stagger group
+- Max 500ms total stagger duration
+- Formula: `calc(var(--index) * 50ms)`
+
+### Reduced Motion (REQUIRED)
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+### will-change
+
+Add via JS on `pointerenter`, remove on `animationend`/`transitionend`. Never set permanently in CSS.
+
+---
+
+## Interaction States (8 Required)
+
+Every interactive component MUST define all 8 states:
+
+| State | CSS | Visual Treatment |
+|-------|-----|------------------|
+| Default | -- | Base appearance |
+| Hover | `:hover` (wrap in `@media(hover:hover)`) | Subtle bg shift or opacity change |
+| Focus | `:focus-visible` | 2px solid accent, offset 2px |
+| Active | `:active` | `scale(0.97)` or darker background |
+| Disabled | `[disabled], [aria-disabled="true"]` | opacity 0.5, `cursor: not-allowed` |
+| Loading | `[aria-busy="true"]` | Spinner or skeleton placeholder |
+| Error | `[aria-invalid="true"]` | Red border + error message |
+| Success | custom attribute | Green check + success message |
+
+### Focus Ring Spec
+
+```css
+:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: inherit;
+}
+```
+
+---
+
+## Visual Hierarchy
+
+### Squint Test
+
+Blur the page -- you should immediately identify the top 2 elements and groupings.
+
+### Tools
+
+Size (3:1 ratio between primary and body), weight (max 2 weights per page), color, space, position, contrast.
+
+### CTA Hierarchy
+
+- **1 primary CTA per viewport** -- filled button
+- Secondary -- outline button
+- Tertiary -- text link
+
+### Progressive Disclosure
+
+Reveal complexity gradually. Default to the simplest view.
+
+---
+
+## Responsive
+
+### Breakpoints (mobile-first)
+
+```
+640px, 768px, 1024px, 1280px, 1536px
+```
+
+### Fluid Design
+
+Prefer `%`, `vw`, `fr`, `min()`, `max()`, `clamp()` over fixed `px`.
+
+### Mobile Requirements
+
+- Minimum 14px text
+- 44px touch targets
+- No horizontal scroll at 320px viewport
+- Adapt layout, don't hide content
+
+---
+
+## Elevation & Z-Index
+
+### Semantic Z-Index Scale
+```css
+--z-dropdown:       100;
+--z-sticky:         200;
+--z-fixed:          300;
+--z-modal-backdrop: 400;
+--z-modal:          500;
+--z-popover:        600;
+--z-toast:          700;
+--z-tooltip:        800;
+```
+
+- Never use arbitrary z-index values (z-index: 9999)
+- Each level has clear semantic meaning
+- Modal backdrop + modal are separate layers (backdrop catches clicks)
+- Toast above modal (error during modal interaction must be visible)
+
+---
+
+## UX Writing
+
+Reference: [specs/ux-writing.md](ux-writing.md) for full guidelines.
+
+Key rules for design token and component spec work:
+- Button labels: verb + object ("Save changes" not "Submit")
+- Error messages: what + why + fix
+- Empty states: acknowledge + explain value + action
+- Destructive actions: name the destruction + show count
+- Never "OK/Cancel" — use specific action names

package/.claude/skills/team-uidesign/specs/scoring-guide.md

@@ -0,0 +1,114 @@
+# 8-Dimension Quality Scoring Rubric
+
+Score each dimension 0-4. Total: 0-32.
+
+## Dimensions
+
+### 1. Anti-AI-Slop (Weight: 10%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | 4+ P1 anti-patterns present |
+| 1 | 2-3 P1 anti-patterns present |
+| 2 | 1 P1 or 3+ P2 anti-patterns present |
+| 3 | 1-2 P2 or 2+ P3 anti-patterns only |
+| 4 | Zero P1/P2 anti-patterns, at most 1 P3 |
+
+### 2. Color Quality (Weight: 15%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No color system; hex/rgb throughout; pure black/white used |
+| 1 | Some tokens but not OKLCH; no tinted neutrals; contrast failures |
+| 2 | OKLCH used partially; tinted neutrals attempted; most contrast passes |
+| 3 | Full OKLCH; tinted neutrals; 60-30-10 applied; all WCAG AA passes; semantic tokens present |
+| 4 | Score-3 plus: primitive->semantic->component hierarchy; color-mix usage; light/dark themes complete |
+
+### 3. Typography Quality (Weight: 15%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | System/generic font only; no scale; no fluid sizing |
+| 1 | Generic font (Inter/Roboto/etc); basic size scale; no clamp() |
+| 2 | Distinctive font chosen; modular scale present; no fluid sizing |
+| 3 | Distinctive font; modular scale with clamp(); proper line-height; reading width constrained |
+| 4 | Score-3 plus: font-display swap with fallback metrics; caption/body/heading line-heights differentiated |
+
+### 4. Spacing & Layout (Weight: 12.5%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Arbitrary spacing; no system; nested cards |
+| 1 | Some consistent spacing but not 4pt scale; margin-heavy |
+| 2 | 4pt scale used; mostly gap over margin; some rhythm variation |
+| 3 | Full 4pt scale; gap throughout; rhythm variation (tight/comfortable/generous); touch targets met |
+| 4 | Score-3 plus: container queries used; no nested cards; 8px adjacent target gaps |
+
+### 5. Motion & Animation (Weight: 10%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Layout property animations; no easing system; no reduced-motion |
+| 1 | Some transform/opacity; default ease/linear; no reduced-motion |
+| 2 | Transform/opacity only; custom easing present; reduced-motion exists but incomplete |
+| 3 | All animations on safe properties; ease-out-quart default; duration tokens; complete reduced-motion |
+| 4 | Score-3 plus: stagger system; will-change managed via JS; exit = 75% entrance |
+
+### 6. Interaction States (Weight: 15%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Only default state; no hover/focus/disabled |
+| 1 | 2-3 states (e.g., default + hover + disabled) |
+| 2 | 5 states (default/hover/focus/active/disabled) but missing loading/error/success |
+| 3 | All 8 states defined; :focus-visible used; hover in @media(hover:hover) |
+| 4 | Score-3 plus: focus ring spec (2px solid + offset 2px); active scale(0.97); ARIA attributes on all states |
+
+### 7. Visual Hierarchy (Weight: 10%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Everything same size/weight; no CTA hierarchy; all centered |
+| 1 | Some size variation; multiple primary CTAs per viewport |
+| 2 | Clear heading hierarchy; CTA levels present but inconsistent |
+| 3 | Passes squint test; single primary CTA per viewport; 3:1 size ratio; max 2 weights |
+| 4 | Score-3 plus: progressive disclosure; clear information density gradient |
+
+### 8. Responsive Design (Weight: 12.5%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Fixed widths; breaks below 768px; content hidden on mobile |
+| 1 | Some media queries; horizontal scroll at 320px; small touch targets |
+| 2 | Mobile-first breakpoints; fluid widths; 14px min text; some issues at 320px |
+| 3 | Full breakpoint coverage; fluid design (clamp/vw/fr); 44px targets; no 320px scroll |
+| 4 | Score-3 plus: container queries; adapt-don't-hide approach; fluid typography |
+
+---
+
+## Rating Bands
+
+| Score | Band | Meaning |
+|-------|------|---------|
+| 28-32 | Excellent | Production-ready, Impeccable quality |
+| 22-27 | Good | Minor polish needed, shippable |
+| 16-21 | Acceptable | Needs revision, core structure sound |
+| 10-15 | Poor | Significant rework required |
+| 0-9 | Critical | Fundamental issues, restart design phase |
+
+## Severity Mapping
+
+| Severity | Dimension Score | Action |
+|----------|----------------|--------|
+| P0 Blocking | Dimension = 0 | Must fix before any progress |
+| P1 Major | Dimension = 1 | Fix in current iteration |
+| P2 Minor | Dimension = 2 | Fix in next iteration |
+| P3 Polish | Dimension = 3 | Track for future improvement |
+
+## Signal Determination
+
+| Condition | Signal | Action |
+|-----------|--------|--------|
+| Score >= 26 AND no P0 (no dim at 0) | `audit_passed` (GC CONVERGED) | Unblock downstream |
+| Score >= 20 AND no P0 | `audit_result` (REVISION NEEDED) | Create fix task |
+| Score < 20 OR any P0 | `fix_required` (CRITICAL) | Urgent fix task |

package/.claude/skills/team-uidesign/specs/team-config.json

@@ -23,7 +23,7 @@
     "reviewer": {
       "task_prefix": "AUDIT",
       "additional_prefixes": [],
-      "responsibility": "Design consistency audit, accessibility compliance, visual review",
+      "responsibility": "8-dimension Impeccable-aligned audit (anti-slop, color, typography, spacing, motion, interaction, hierarchy, responsive)",
       "message_types": ["audit_result", "audit_passed", "fix_required", "error"]
     },
     "implementer": {

package/.claude/skills/team-uidesign/specs/ux-writing.md

@@ -0,0 +1,86 @@
+# UX Writing Standards
+
+Guidelines for all text content in UI components. From Impeccable's UX writing reference.
+
+---
+
+## Button Labels
+
+- **NEVER**: "OK", "Submit", "Yes", "No", "Cancel" (generic)
+- **ALWAYS**: verb + object — "Save changes", "Create account", "Delete message"
+- Destructive actions: name the destruction + show count — "Delete 5 items" not "Delete selected"
+- Primary CTA: specific benefit — "Start free trial" not "Get started"
+
+## Error Messages
+
+Formula: (1) What happened + (2) Why + (3) How to fix
+
+| Type | Template |
+|------|----------|
+| Format | "{Field} must be {format}. Example: {example}" |
+| Required | "{Field} is required to {reason}" |
+| Permission | "You don't have access to {resource}. Contact {who} for access" |
+| Network | "Couldn't reach the server. Check your connection and try again" |
+| Server | "Something went wrong on our end. Try again in a few minutes" |
+
+- Never blame user: "Please enter..." not "You entered..."
+- Never use codes alone: "Error 404" → "Page not found"
+- Be specific: "Password must be 8+ characters with a number" not "Invalid password"
+
+## Empty States
+
+Three components: (1) Acknowledge + (2) Explain value + (3) Provide action
+
+| Context | Example |
+|---------|---------|
+| First use | "No projects yet. Create your first project to get started. [Create project]" |
+| Search | "No results for '{query}'. Try a different search term or [browse all]" |
+| Filtered | "No items match these filters. [Clear filters]" |
+| Error | "Couldn't load items. [Try again]" |
+
+## Loading States
+
+- Be specific: "Saving your draft..." not "Loading..."
+- Multi-step: show progress — "Uploading (2 of 5 files)..."
+- Duration hint: "This usually takes about 30 seconds"
+
+## Confirmation Dialogs
+
+- Use sparingly — prefer undo over confirm
+- Title: what will happen — "Delete this project?"
+- Body: consequences — "This will permanently delete 12 files. This can't be undone."
+- Buttons: specific — "Delete project" / "Keep project" (not OK/Cancel)
+
+## Voice & Tone
+
+- **Voice**: consistent brand personality (professional/friendly/technical — choose one)
+- **Tone**: adapts to moment — cheerful for success, empathetic for errors, neutral for routine
+- Keep consistent: same word for same concept everywhere (delete/remove/trash → pick one)
+
+## Form Instructions
+
+- Show format with placeholder: `placeholder="john@example.com"`
+- Explain non-obvious fields with helper text below label
+- Mark optional fields (not required ones) — most fields should be required
+- Group related fields with clear section headers
+
+## Translation Planning
+
+| Language | Length vs English |
+|----------|------------------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30-40% |
+| Chinese | -30% |
+| Japanese | -10-20% |
+
+- Design for longest language (German)
+- Never truncate translated text — allow wrapping
+- Avoid idioms and cultural references in source text
+
+## Redundant Copy Detection
+
+- Don't repeat visible information (heading ≠ first paragraph)
+- Labels describe the field, not restate the value
+- Tooltips add information, not repeat the label
+- If heading says it all, skip the intro paragraph

package/.claude/skills/team-ux-improve/SKILL.md

@@ -98,6 +98,9 @@ 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 visual design standards
+- [specs/anti-patterns.md](specs/anti-patterns.md) — AI slop detection catalog (20 items)
+- [specs/heuristics.md](specs/heuristics.md) — Nielsen's 10 usability heuristics evaluation framework
 
 ## Session Directory
 

package/.claude/skills/team-ux-improve/roles/designer/role.md

@@ -101,6 +101,36 @@ const handleSubmit = async () => {
 | Text input for folder path | Add directory picker: `<input type="file" webkitdirectory />` |
 | No validation | Add validation rules and error messages |
 
+### Visual Design Solutions
+
+Reference `specs/design-standards.md` for target standards.
+
+| Issue | Solution Design |
+|-------|-----------------|
+| Pure black/white | Define OKLCH neutral scale tinted toward brand hue (chroma 0.005-0.01) |
+| Generic fonts | Select from: Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces |
+| No modular scale | Choose ratio (1.200 or 1.250), derive all sizes from base 16px |
+| Missing fluid sizing | Apply clamp() to display sizes (xl+): `clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem)` |
+| All buttons primary | Define: primary (filled), secondary (outline/ghost), tertiary (text link) |
+| Monotonous spacing | Apply 4pt scale with rhythm: tight (4-8px), comfortable (16-24px), generous (48-96px) |
+| Nested cards | Flatten: remove inner card, use spacing + subtle border-bottom divider |
+| Layout animations | Replace with transform: translateX/Y/scale + opacity transitions |
+| No reduced-motion | Add global `@media (prefers-reduced-motion: reduce)` reset |
+| Missing focus-visible | Add `:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px }` |
+| Bounce easing | Replace with ease-out-quart: `cubic-bezier(0.25, 1, 0.5, 1)` |
+| Missing interaction states | Define all 8 states per component with CSS selectors and ARIA attributes |
+
+### UX Writing Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Generic button labels | Replace with verb+object: "Save changes", "Create project", "Delete 3 items" |
+| Error without guidance | Apply formula: what happened + why + how to fix. Template per error type |
+| Empty state without action | Three parts: acknowledge → explain value → provide action button |
+| Loading text generic | Be specific: "Saving your draft..." not "Loading..." Show progress for multi-step |
+| Confirmation too generic | Title: what will happen. Body: consequences. Buttons: specific actions (not OK/Cancel) |
+| Redundant copy | Remove intro paragraph if heading is self-explanatory. Labels ≠ values |
+
 ## Phase 4: Design Document Generation
 
 1. Generate implementation guide for each issue and write to `<session>/artifacts/design-guide.md`

package/.claude/skills/team-ux-improve/roles/diagnoser/role.md

@@ -69,6 +69,20 @@ For each issue from scan report:
 | No error handling | Missing catch block | Add try/catch with error state |
 | Race condition | Multiple concurrent requests | Add request cancellation or debounce |
 
+### Visual Design Diagnosis
+
+| Pattern | Root Cause | Fix Strategy |
+|---------|------------|--------------|
+| Pure black/white colors | No intentional color system | Introduce OKLCH palette with tinted neutrals |
+| Generic font usage | Default font selection | Replace with distinctive alternatives from recommended list |
+| Missing interaction states | Incomplete component design | Add all 8 states per Impeccable spec |
+| Layout animations | Wrong animation properties | Switch to transform + opacity, add will-change via JS |
+| No reduced-motion | Accessibility oversight | Add @media (prefers-reduced-motion: reduce) global query |
+| All buttons primary | No hierarchy design | Establish primary/secondary/tertiary button system |
+| Monotonous spacing | No spacing system | Implement 4pt scale with rhythm variation |
+| Nested cards | Over-containment | Flatten to spacing + dividers |
+| Missing focus-visible | Outdated focus handling | Replace :focus with :focus-visible, add ring spec |
+
 ## Phase 4: Diagnosis Report
 
 1. Generate root cause analysis for each issue and write to `<session>/artifacts/diagnosis.md`
@@ -87,7 +101,8 @@ If new root cause patterns discovered:
               pattern_types: {
                 state_management: <count>,
                 event_binding: <count>,
-                async_handling: <count>
+                async_handling: <count>,
+                visual_design: <count>
               }
             })
    ```

package/.claude/skills/team-ux-improve/roles/scanner/role.md

@@ -63,6 +63,48 @@ Scan strategy:
 | Input without validation | Form input without validation rules | Low |
 | Missing file selector | Text input for file/folder path without picker | Medium |
 
+### Visual Design Scanning
+
+In addition to interaction issues, scan for visual design quality problems.
+Reference `specs/design-standards.md` and `specs/anti-patterns.md`.
+
+| Category | Detection Pattern | Severity |
+|----------|-------------------|----------|
+| AI color palette | Cyan (#00d4ff, #06b6d4), purple-blue gradients on dark | High |
+| Pure black/white | #000, #fff, rgb(0,0,0), rgb(255,255,255) as primary colors | High |
+| Generic font | Inter, Roboto, Open Sans, Arial as primary font-family | Medium |
+| All buttons primary | Every button has same fill treatment, no hierarchy | High |
+| Nested cards | border/shadow inside border/shadow containers | Medium |
+| No focus-visible | Using :focus or outline:none without :focus-visible | High |
+| Layout animations | Animating width/height/margin/padding | Medium |
+| No reduced-motion | Missing @media(prefers-reduced-motion) | Medium |
+| Bounce easing | cubic-bezier with negative values, spring/bounce | Medium |
+| Monotonous spacing | >70% same padding/margin value | Low |
+| Missing 8 states | Interactive elements with <5 defined states | Medium |
+| Glassmorphism overuse | backdrop-filter:blur on >2 components | Medium |
+| Generic button labels | "OK", "Submit", "Yes/No", "Cancel" without specific verb+object | Medium |
+| Error messages without fix guidance | Error shows "Something went wrong" with no next step | High |
+| Empty states without action | Data list shows "No data" without create/import action | Medium |
+| Redundant copy | Heading text repeated in first paragraph (>50% word overlap) | Low |
+
+### Heuristic UX Scanning
+
+Apply Nielsen's 10 usability heuristics as a structured scan checklist.
+Reference: `specs/heuristics.md`
+
+| Heuristic | What to Check | Severity |
+|-----------|---------------|----------|
+| Visibility of system status | Loading indicators, progress bars, state feedback, timestamps | High |
+| Match between system and real world | Jargon-free labels, familiar metaphors, logical ordering | Medium |
+| User control and freedom | Undo/redo, back navigation, cancel actions, escape from modals | High |
+| Consistency and standards | Same terms/icons for same actions, platform conventions | Medium |
+| Error prevention | Confirmation for destructive actions, input validation, disable invalid options | High |
+| Recognition over recall | Visible options, recent items, search suggestions, breadcrumbs | Medium |
+| Flexibility and efficiency | Keyboard shortcuts, power-user features, bulk actions | Low |
+| Aesthetic and minimalist design | Information density, noise reduction, visual hierarchy | Medium |
+| Help users recover from errors | Error messages with fix guidance (what+why+fix), retry options | High |
+| Help and documentation | Tooltips, onboarding, contextual help, empty states with guidance | Low |
+
 For each component file:
 1. Read file content
 2. Scan for interaction patterns using Grep
@@ -73,7 +115,7 @@ For each component file:
 ## Phase 4: Issue Report Generation
 
 1. Classify issues by severity (High/Medium/Low)
-2. Group by category (unresponsive, missing feedback, state issues, input UX)
+2. Group by category (unresponsive, missing feedback, state issues, input UX, visual design)
 3. Generate structured report and write to `<session>/artifacts/scan-report.md`
 4. Share state via team_msg:
    ```