claude-code-workflow 7.2.26 → 7.2.28

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

@@ -0,0 +1,142 @@
+---
+role: verifier
+prefix: VERIFY
+inner_loop: false
+message_types: [verify_passed, verify_failed, fix_required, error]
+---
+
+# Verification & Regression Check
+
+Before/after comparison verification. Re-scan fixed code against same 8 dimensions, calculate improvement, detect regressions. Acts as Critic in the optimizer<->verifier Generator-Critic loop.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Original scan report | <session>/scan/scan-report.md | Yes |
+| Fix log | <session>/optimization/fix-log.md | 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 |
+| Scoring guide | specs/scoring-guide.md | Yes |
+
+1. Extract session path from task description
+2. Read original scan report: parse before-scores per dimension and issue inventory
+3. Read fix log: parse all fixes applied and files modified
+4. Read specs for scoring reference
+
+## Phase 3: Verification
+
+### Step 1: Re-scan Fixed Code
+
+Apply the same 8-dimension scan as the scanner role (reference roles/scanner/role.md Phase 3) to the current state of files. Use identical checklist items and scoring criteria.
+
+If Chrome DevTools available:
+- Take screenshots at same 3 viewports (mobile 375px, tablet 768px, desktop 1440px)
+- Save to `<session>/evidence/after-mobile.png`, `after-tablet.png`, `after-desktop.png`
+
+### Step 2: Calculate Score Delta
+
+For each dimension, compare before and after:
+
+| Dimension | Before | After | Delta | Status |
+|-----------|--------|-------|-------|--------|
+| 1. Anti-Patterns | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 2. Color Quality | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 3. Typography | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 4. Spacing/Layout | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 5. Motion | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 6. Interaction States | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 7. Visual Hierarchy | X/4 | Y/4 | +/-N | improved/same/regressed |
+| 8. Responsive | X/4 | Y/4 | +/-N | improved/same/regressed |
+| **Total** | X/32 | Y/32 | +/-N | |
+
+### Step 3: Regression Detection
+
+Check for NEW issues not present in original scan report:
+
+| Check | Method |
+|-------|--------|
+| New issues introduced | Compare current issue inventory against original. Any issue not in original = regression |
+| Score dropped | Any dimension score lower than before = regression |
+| Positive findings broken | Items from original "Positive Findings" no longer hold |
+| Build broken | Modified files have syntax errors or lint failures |
+
+Classify regressions:
+- **Critical**: Score dropped in any dimension, WCAG AA violation introduced, build broken
+- **Non-critical**: New minor issues introduced but overall score improved
+
+### Step 4: Determine Signal
+
+| Condition | Signal |
+|-----------|--------|
+| No regressions AND total score >= before score | `verify_passed` |
+| Non-critical regressions AND total score improved | `verify_failed` (fixable) |
+| Critical regressions OR total score dropped | `fix_required` (urgent) |
+
+## Phase 4: Generate Verification Report
+
+Output: `<session>/verification/verify-report.md`
+
+```markdown
+# Verification Report
+
+## Verdict: <PASSED | FAILED | FIX REQUIRED>
+
+## Score Comparison
+
+| Dimension | Before | After | Delta |
+|-----------|--------|-------|-------|
+| 1. Anti-Patterns | X/4 | Y/4 | +N |
+| 2. Color Quality | X/4 | Y/4 | +N |
+| 3. Typography | X/4 | Y/4 | +N |
+| 4. Spacing/Layout | X/4 | Y/4 | +N |
+| 5. Motion | X/4 | Y/4 | +N |
+| 6. Interaction States | X/4 | Y/4 | +N |
+| 7. Visual Hierarchy | X/4 | Y/4 | +N |
+| 8. Responsive | X/4 | Y/4 | +N |
+| **Total** | **X/32** | **Y/32** | **+N** |
+
+## Before Rating: <rating-band> -> After Rating: <rating-band>
+
+## Regressions Found
+<list of regressions with location, severity, description>
+<or "None" if clean>
+
+## Remaining Issues
+<issues from original scan that were NOT fixed>
+
+## Improvements
+<per-dimension improvement details>
+
+## Screenshots
+- Before: <session>/evidence/before-*.png
+- After: <session>/evidence/after-*.png
+<or "Chrome DevTools not available" if no screenshots>
+
+## Metadata
+- Original scan: <session>/scan/scan-report.md
+- Fix log: <session>/optimization/fix-log.md
+- GC round: <round number>
+- Timestamp: <ISO timestamp>
+```
+
+After writing the report, send signal-appropriate message:
+
+**If verify_passed**:
+```
+mcp__ccw-tools__team_msg(session_id, role="verifier", type="verify_passed", content="Verification passed. Score: before X/32 -> after Y/32 (+N). No regressions.")
+SendMessage(participant="coordinator", message="[verifier] VERIFY-001 passed. Score: X/32 -> Y/32 (+N). No regressions. Report: <session>/verification/verify-report.md")
+```
+
+**If verify_failed**:
+```
+mcp__ccw-tools__team_msg(session_id, role="verifier", type="verify_failed", content="Verification failed. N non-critical regressions found. Score: X/32 -> Y/32.")
+SendMessage(participant="coordinator", message="[verifier] VERIFY-001 failed. N regressions (non-critical). Score: X/32 -> Y/32. Report: <session>/verification/verify-report.md")
+```
+
+**If fix_required**:
+```
+mcp__ccw-tools__team_msg(session_id, role="verifier", type="fix_required", content="Fix required. N critical regressions. Score dropped: X/32 -> Y/32.")
+SendMessage(participant="coordinator", message="[verifier] VERIFY-001 fix_required. N critical regressions. Score: X/32 -> Y/32 (DROPPED). Report: <session>/verification/verify-report.md")
+```

package/.claude/skills/team-ui-polish/specs/anti-patterns.md

@@ -0,0 +1,141 @@
+# Anti-Pattern Catalog
+
+Complete catalog of UI design anti-patterns from Impeccable's design audit knowledge. Used by scanner for detection and optimizer for remediation.
+
+## 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."
+
+AI-generated UIs share recognizable fingerprints. These are not inherently bad techniques -- they become problems when used as defaults without intentional design decisions. The issue is not the technique itself but the lack of thought behind it.
+
+## AI Slop Tells (20 Items)
+
+### 1. AI Color Palette
+**Pattern**: Cyan-on-dark (#00d4ff, #06b6d4), purple-to-blue gradients (#8b5cf6 to #3b82f6), neon accents on dark backgrounds.
+**Why it is a tell**: Every AI model defaults to the same "futuristic" palette. It signals zero design intent.
+**Detection**: Search for cyan/purple/neon values on dark backgrounds. Check if palette could be from any Tailwind dark template.
+**Severity**: P1
+
+### 2. Gradient Text for Impact
+**Pattern**: `background-clip: text` + gradient applied to metrics, headings, or hero text.
+**Why it is a tell**: AI uses gradient text as a crutch to make numbers and titles feel "premium." Real typography achieves emphasis through weight, size, and space.
+**Detection**: Search for `background-clip: text` or `-webkit-background-clip: text`.
+**Severity**: P1
+
+### 3. Default Dark Mode with Glowing Accents
+**Pattern**: Dark background (gray-900/950) as default with glowing/neon accent colors. No light mode offered or light mode is an afterthought.
+**Why it is a tell**: Dark mode with glow effects requires no real color decisions. It hides contrast problems and creates false sophistication.
+**Detection**: Check default theme. If dark with glow `box-shadow` or neon colors, flag it.
+**Severity**: P2
+
+### 4. Glassmorphism Everywhere
+**Pattern**: `backdrop-filter: blur()`, glass cards, glow borders (`box-shadow: 0 0 Xpx <color>`), used decoratively on multiple components.
+**Why it is a tell**: Glassmorphism is a valid technique for specific use cases (overlays, elevated surfaces). AI applies it everywhere as the default "modern" aesthetic.
+**Detection**: Count instances of `backdrop-filter: blur`. If > 2 components use it without functional reason, flag.
+**Severity**: P1
+
+### 5. Hero Metric Layout
+**Pattern**: Big number (32-48px) + small label underneath + supporting stats in a row + gradient accent or colored bar.
+**Why it is a tell**: This is the universal "AI dashboard" template. Every AI-generated analytics page uses this exact layout.
+**Detection**: Pattern match for large-number + small-label structures repeated in a metrics row/grid.
+**Severity**: P2
+
+### 6. Identical Card Grids
+**Pattern**: Same-sized cards with icon + heading + body text repeated 3-6 times in a grid. Equal width, equal height, equal spacing.
+**Why it is a tell**: Real content varies in importance. AI treats all items as equally important because it has no content strategy.
+**Detection**: Grid of 3+ cards with identical structure and sizing. No featured/hero card.
+**Severity**: P2
+
+### 7. Nested Cards
+**Pattern**: Cards inside cards. `.card > .card-body > .inner-card`. Multiple layers of bordered containers.
+**Why it is a tell**: AI nests containers to create visual "depth." It actually creates noise and makes hierarchy unclear.
+**Detection**: Search for elements with border/shadow inside elements with border/shadow. Two levels of containment.
+**Severity**: P2
+
+### 8. Generic Fonts
+**Pattern**: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, system-ui used as primary font without intentional choice.
+**Why it is a tell**: These are defaults. AI picks them because they are safe. Safe means forgettable.
+**Detection**: Check `font-family` declarations. If primary font is in the generic list, flag.
+**Severity**: P2
+
+### 9. Rounded Rectangles with Generic Drop Shadows
+**Pattern**: `border-radius: 8-16px` combined with `box-shadow: 0 1-4px 6-24px rgba(0,0,0,0.05-0.15)` on every container.
+**Why it is a tell**: The "safe shape." Every AI output uses this exact combination because it is never wrong -- but never distinctive either.
+**Detection**: Count elements with both border-radius (8-16px range) and generic box-shadow. If > 5, flag.
+**Severity**: P3
+
+### 10. Large Icons Above Every Heading
+**Pattern**: 24-48px icons with rounded corners or colored backgrounds placed above every heading or card title.
+**Why it is a tell**: AI uses icons as visual filler. Real design uses icons sparingly where they aid comprehension.
+**Detection**: Pattern match for icon elements directly above heading elements. If repeated 3+ times, flag.
+**Severity**: P2
+
+### 11. One-Side Border Accent
+**Pattern**: `border-left: 3-4px solid <accent-color>` or `border-top` used as the primary accent technique on cards/containers.
+**Why it is a tell**: Lazy accent. It is a shortcut to add "personality" without making real design decisions.
+**Detection**: Search for `border-left: [2-5]px solid` or `border-top: [2-5]px solid` with accent colors.
+**Severity**: P3
+
+### 12. Decorative Sparklines
+**Pattern**: Tiny charts, mini-graphs, or trend indicators that look sophisticated but convey no actionable data. Often in card corners.
+**Why it is a tell**: AI adds charts to appear data-driven. If the chart has no axis labels, no values, and no interaction, it is decoration.
+**Detection**: Small SVG/canvas charts (<100px) without labels, tooltips, or legends.
+**Severity**: P2
+
+### 13. Bounce/Elastic Easing
+**Pattern**: `cubic-bezier(0.68, -0.55, 0.265, 1.55)`, spring animations, or any easing that overshoots.
+**Why it is a tell**: Bounce easing was trendy circa 2015. AI still defaults to it for "playfulness." It feels dated and tacky in modern UI.
+**Detection**: Search for cubic-bezier with negative values or spring keyword.
+**Severity**: P2
+
+### 14. Redundant Copy
+**Pattern**: Intro paragraphs that restate the heading. "Welcome to your Dashboard. This is your dashboard where you can see..."
+**Why it is a tell**: AI generates text to fill space. Real UX uses headings as the message and body for additional context only.
+**Detection**: Compare heading text with first paragraph. If >50% word overlap, flag.
+**Severity**: P3
+
+### 15. All Buttons Primary
+**Pattern**: Every button is filled/primary color. No ghost buttons, text links, outline buttons, or secondary variants.
+**Why it is a tell**: AI makes everything important. Real design creates hierarchy: 1 primary, 1-2 secondary, rest tertiary.
+**Detection**: Check button variants. If all buttons have same fill/color treatment, flag.
+**Severity**: P1
+
+### 16. Everything Centered
+**Pattern**: `text-align: center` or `justify-content: center` / `align-items: center` on most content blocks including body text.
+**Why it is a tell**: Centering is the safe choice. Real design uses left-alignment for readability, centering only for specific elements (headings, hero).
+**Detection**: Count centered text blocks. If body text is centered, flag. If > 60% of content sections are centered, flag.
+**Severity**: P2
+
+### 17. Same Spacing Everywhere
+**Pattern**: Identical padding/margin on all cards, sections, and components. No variation in spacing rhythm.
+**Why it is a tell**: AI applies uniform spacing because it has no sense of content grouping or visual rhythm.
+**Detection**: Extract all padding/margin values. If > 70% are the same value, flag.
+**Severity**: P2
+
+### 18. Monospace as Tech Aesthetic
+**Pattern**: Monospace font (Fira Code, JetBrains Mono, Source Code Pro) used for non-code content to appear "techy."
+**Why it is a tell**: AI equates monospace with "developer tool" aesthetic. Real design uses monospace only for actual code.
+**Detection**: Monospace `font-family` on non-`<code>`, non-`<pre>` elements.
+**Severity**: P3
+
+### 19. Modal Overuse
+**Pattern**: Modals for confirmations, settings changes, form entries, when inline editing, drawers, or expandable sections would work.
+**Why it is a tell**: Modals are AI's default "interaction" pattern because they are self-contained. Real UX considers context loss and flow interruption.
+**Detection**: Count modal/dialog components. If > 3 modals for non-critical actions, flag.
+**Severity**: P3
+
+### 20. Pure Black or Pure White
+**Pattern**: `#000000` or `#ffffff` used as primary background/text colors without any tint.
+**Why it is a tell**: Pure black and white create harsh contrast and feel sterile. Real design tints toward a brand hue.
+**Detection**: Search for `#000`, `#000000`, `rgb(0,0,0)`, `#fff`, `#ffffff`, `rgb(255,255,255)` in styles.
+**Severity**: P1
+
+## Scoring Guide
+
+| Score | Tells Present | Label |
+|-------|---------------|-------|
+| 0 | 5+ tells | AI Slop Gallery |
+| 1 | 3-4 tells | Heavy AI Influence |
+| 2 | 1-2 tells | Some AI Tells |
+| 3 | Subtle traces only | Mostly Clean |
+| 4 | Zero tells, distinctive | Genuinely Intentional |

package/.claude/skills/team-ui-polish/specs/design-standards.md

@@ -0,0 +1,356 @@
+# Design Standards
+
+Impeccable's positive design standards. These are the target state -- what good looks like. Used by scanner for scoring (how close to ideal) and optimizer as fix targets.
+
+---
+
+## Color
+
+### Principles
+- Use **OKLCH** for perceptually uniform palettes. Colors at the same lightness actually look the same lightness
+- Tint neutrals toward brand hue (chroma 0.005-0.01). Never pure gray
+- **60-30-10 rule**: 60% neutral, 30% secondary/supporting, 10% accent
+- Semantic token hierarchy: primitive -> semantic -> component tokens
+- Never pure black (`#000`) or pure white (`#fff`). Always tint
+
+### Color Token Structure
+```
+--color-primary          oklch(0.55 0.2 250)
+--color-primary-hover    oklch(0.50 0.22 250)
+--color-primary-active   oklch(0.45 0.22 250)
+
+--color-neutral-50       oklch(0.98 0.005 250)    /* near-white, brand tinted */
+--color-neutral-100      oklch(0.95 0.005 250)
+--color-neutral-200      oklch(0.90 0.007 250)
+--color-neutral-300      oklch(0.80 0.007 250)
+--color-neutral-400      oklch(0.65 0.008 250)
+--color-neutral-500      oklch(0.50 0.008 250)
+--color-neutral-600      oklch(0.40 0.008 250)
+--color-neutral-700      oklch(0.30 0.008 250)
+--color-neutral-800      oklch(0.20 0.010 250)
+--color-neutral-900      oklch(0.13 0.010 250)
+--color-neutral-950      oklch(0.08 0.010 250)    /* near-black, brand tinted */
+
+--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.15 250)
+
+--color-surface          var(--color-neutral-50)
+--color-surface-raised   var(--color-neutral-100)
+--color-surface-overlay  var(--color-neutral-900 / 0.5)
+
+--color-text-primary     var(--color-neutral-900)
+--color-text-secondary   var(--color-neutral-600)
+--color-text-muted       var(--color-neutral-400)
+```
+
+### Contrast Requirements (WCAG AA)
+- Normal text (<18px / <24px bold): 4.5:1 minimum
+- Large text (>=18px / >=24px bold): 3:1 minimum
+- UI components and graphical objects: 3:1 minimum
+- Focus indicators: 3:1 against adjacent colors
+
+### Text on Colored Backgrounds
+- Never gray text on colored backgrounds (looks washed out)
+- Use shade of the background color, or white/dark with transparency
+- `color-mix(in oklch, var(--bg-color) 30%, black)` for text on colored surfaces
+
+---
+
+## Typography
+
+### Font Selection
+Avoid: Inter, Roboto, Open Sans, Lato, Montserrat, Arial (overused defaults).
+
+Recommended alternatives by category:
+- **Sans-serif body**: Instrument Sans, Plus Jakarta Sans, DM Sans, Geist, General Sans
+- **Sans-serif display**: Space Grotesk, Manrope, Outfit, Satoshi, Clash Display
+- **Serif display**: Fraunces, Playfair Display 2, Source Serif 4
+- **Monospace (code only)**: Geist Mono, JetBrains Mono, Fira Code
+
+### Modular Type Scale
+Choose one ratio and apply consistently:
+
+| Ratio | Name | Scale (base 16px) |
+|-------|------|--------------------|
+| 1.125 | Major Second | 16, 18, 20.25, 22.78, 25.63 |
+| 1.200 | Minor Third | 16, 19.2, 23.04, 27.65, 33.18 |
+| 1.250 | Major Third | 16, 20, 25, 31.25, 39.06 |
+| 1.333 | Perfect Fourth | 16, 21.33, 28.43, 37.9, 50.52 |
+| 1.500 | Perfect Fifth | 16, 24, 36, 54, 81 |
+
+### Fluid Sizing
+Use `clamp()` for display text:
+```css
+--text-xs:   0.75rem;                                    /* 12px, fixed */
+--text-sm:   0.875rem;                                   /* 14px, fixed */
+--text-base: 1rem;                                       /* 16px, body */
+--text-lg:   1.125rem;                                   /* 18px */
+--text-xl:   clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);   /* 20-24px */
+--text-2xl:  clamp(1.5rem, 1.2rem + 1vw, 2rem);         /* 24-32px */
+--text-3xl:  clamp(1.875rem, 1.4rem + 1.5vw, 2.5rem);   /* 30-40px */
+--text-4xl:  clamp(2.25rem, 1.5rem + 2.5vw, 3.5rem);    /* 36-56px */
+```
+
+### Line Height & Spacing
+- Body text: `line-height: 1.5` (24px at 16px base)
+- Headings: `line-height: 1.2` (tighter)
+- Small text / captions: `line-height: 1.6`
+- Reading width: `max-width: 65ch` (range: 45-75ch)
+
+### Loading
+- `font-display: swap` on all custom fonts
+- Provide `size-adjust`, `ascent-override`, `descent-override` on fallback for minimal CLS
+
+---
+
+## Spacing
+
+### 4pt Base Scale
+```css
+--space-0:  0;
+--space-1:  0.25rem;   /* 4px */
+--space-2:  0.5rem;    /* 8px */
+--space-3:  0.75rem;   /* 12px */
+--space-4:  1rem;      /* 16px */
+--space-5:  1.25rem;   /* 20px */
+--space-6:  1.5rem;    /* 24px */
+--space-8:  2rem;      /* 32px */
+--space-10: 2.5rem;    /* 40px */
+--space-12: 3rem;      /* 48px */
+--space-16: 4rem;      /* 64px */
+--space-24: 6rem;      /* 96px */
+```
+
+### Rhythm
+- **Tight**: 4-8px within component groups (e.g., label + input, icon + text)
+- **Comfortable**: 16-24px between related items (e.g., list items, form fields)
+- **Generous**: 48-96px between major sections (e.g., page sections, content blocks)
+
+Monotonous spacing (same value everywhere) = no rhythm = boring. Vary spacing intentionally.
+
+### Layout Principles
+- Use `gap` instead of `margin` for sibling spacing
+- Cards only when content is truly distinct and actionable. Not everything needs a card
+- Flatten nested cards -- use spacing + subtle dividers instead
+- Container queries (`@container`) for component-level responsive
+- Touch targets: minimum 44x44px for all interactive elements
+- Optical adjustments: visually center, not mathematically center (e.g., play button in circle needs right offset)
+
+---
+
+## Motion
+
+### Property Rules
+- **Animate ONLY**: `transform`, `opacity`, `clip-path`, `background-color`, `color`, `border-color`, `box-shadow`, `filter`
+- **NEVER animate**: `width`, `height`, `top`, `left`, `right`, `bottom`, `margin`, `padding` (triggers layout)
+
+### Easing
+- **Default (ease-out-quart)**: `cubic-bezier(0.25, 1, 0.5, 1)` -- decelerates naturally
+- **Enter (ease-out)**: `cubic-bezier(0, 0, 0.25, 1)` -- elements arrive and settle
+- **Exit (ease-in)**: `cubic-bezier(0.5, 0, 0.75, 0)` -- elements accelerate away
+- **NEVER**: `ease` (default), `linear` (mechanical), bounce/elastic (dated)
+
+### Duration Scale
+```css
+--duration-instant:   100ms;   /* tooltip show, ripple */
+--duration-fast:      150ms;   /* button hover, focus ring */
+--duration-normal:    250ms;   /* dropdown open, tab switch */
+--duration-slow:      400ms;   /* modal open, sidebar slide */
+--duration-entrance:  500ms;   /* page entrance, hero animation */
+--duration-complex:   800ms;   /* complex sequence, page transition */
+```
+
+- Exit = 75% of entrance duration
+- Feedback (hover, active, focus): 100-150ms maximum
+- State change: 200-300ms
+- Layout change: 300-500ms
+
+### Stagger
+- Max visible items to stagger: 10
+- Total stagger duration: max 500ms
+- Formula: `animation-delay: calc(var(--index) * 50ms)`
+- Cap: `animation-delay: min(calc(var(--index) * 50ms), 500ms)`
+
+### Reduced Motion
+**Required** -- affects ~35% of adults over 40:
+```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
+- Do NOT set in CSS (wastes GPU memory permanently)
+- Add via JS on `pointerenter` / `focusin`
+- Remove on `animationend` / `transitionend`
+
+---
+
+## Interaction States
+
+### The 8 Required States
+
+Every interactive element must define:
+
+| State | CSS | Visual Change |
+|-------|-----|---------------|
+| Default | -- | Base appearance |
+| Hover | `:hover` (wrap in `@media(hover:hover)`) | Subtle background/opacity change |
+| Focus | `:focus-visible` | Focus ring: 2px solid accent, offset 2px |
+| Active | `:active` | Scale down (0.97) or darker background |
+| Disabled | `[disabled], [aria-disabled="true"]` | Opacity 0.5, cursor not-allowed |
+| Loading | `[aria-busy="true"]` | Spinner/skeleton, disable interaction |
+| Error | `[aria-invalid="true"]` | Red border, error message below |
+| Success | custom class/attribute | Green check, success message |
+
+### Focus Ring Specification
+```css
+:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: inherit;
+}
+
+/* Only remove outline for mouse clicks */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+Focus ring contrast: 3:1 minimum against all adjacent colors.
+
+### Form Labels
+- Always provide visible `<label>` elements
+- Placeholders are hints, NOT labels (they disappear)
+- Use `aria-labelledby` or `aria-label` for icon-only buttons
+- Error messages: `aria-describedby` linking input to error text
+
+### Touch Targets
+- Minimum: 44x44px (WCAG 2.5.5 AAA) / 24x24px (WCAG 2.5.8 AA minimum)
+- Use padding to increase hit area without changing visual size
+- Minimum 8px gap between adjacent targets
+
+---
+
+## Visual Hierarchy
+
+### Squint Test
+Blur the page (or squint). You should immediately identify:
+1. The most important element (usually primary heading or CTA)
+2. The second most important element
+3. Clear groupings of related content
+
+If everything looks the same when blurred, hierarchy has failed.
+
+### Hierarchy Tools (use 2-3 together)
+| Tool | Effect |
+|------|--------|
+| Size | Larger = more important. 3:1 ratio between major levels |
+| Weight | Bold vs regular vs light. Maximum 2 weights per page |
+| Color | Saturated vs muted. Primary color for emphasis |
+| Space | More surrounding space = more important |
+| Position | Top-left reads first (in LTR). Above fold > below fold |
+| Contrast | High contrast = more important. Low contrast recedes |
+
+### Primary Action Rule
+- Only 1 primary CTA per viewport
+- Primary: filled button, highest contrast, most saturated
+- Secondary: outline/ghost button
+- Tertiary: text link, no background
+
+### Progressive Disclosure
+- Show summary first, detail on demand
+- Expandable sections, "show more," detail panels
+- Do not dump all information at once
+
+---
+
+## Responsive Design
+
+### Breakpoints
+```css
+/* Mobile first */
+--bp-sm:  640px;    /* Small tablets */
+--bp-md:  768px;    /* Tablets */
+--bp-lg:  1024px;   /* Laptops */
+--bp-xl:  1280px;   /* Desktops */
+--bp-2xl: 1536px;   /* Large screens */
+```
+
+### Fluid Design Principles
+- Use `%`, `vw`, `fr`, `min()`, `max()`, `clamp()` instead of fixed `px` widths
+- `max-width` instead of `width` for containers
+- Grid with `fr` units for responsive layouts
+- Container queries (`@container`) for component-level responsiveness
+
+### Mobile Requirements
+- Minimum text: 14px (0.875rem), prefer 16px for body
+- Touch targets: 44x44px minimum
+- No horizontal scroll at >= 320px viewport
+- Must have `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- Images: `max-width: 100%; height: auto`
+
+### Adapt, Don't Hide
+- Content should be restructured for smaller screens, not hidden
+- Stack horizontal layouts vertically
+- Use accordion/tabs for complex content
+- Simplify navigation (hamburger, bottom nav)
+
+---
+
+## UX Writing
+
+### Button Labels
+- NEVER: "OK", "Submit", "Yes", "No" (generic)
+- ALWAYS: verb + object — "Save changes", "Create account", "Delete message"
+- Destructive: name the destruction + count — "Delete 5 items"
+
+### Error Messages
+Formula: what happened + why + how to fix
+- "Password must be 8+ characters with a number" not "Invalid password"
+- Never blame user, never use codes alone
+- Preserve user input on error
+
+### Empty States
+Acknowledge + explain value + provide action
+- "No projects yet. Create your first project to start collaborating. [Create project]"
+
+### Loading Text
+- Specific: "Saving your draft..." not "Loading..."
+- Multi-step: "Uploading (2 of 5 files)..."
+
+### Consistency
+- One term per concept (delete/remove → pick one)
+- Same icon for same action everywhere
+
+---
+
+## Dark Mode (when present)
+
+### Rules
+- NOT inverted light mode — requires deliberate design
+- **Surface hierarchy**: lighter surfaces = higher elevation
+  - Base: `oklch(0.10-0.15 0.01 <hue>)`
+  - Raised: `oklch(0.18-0.22 0.01 <hue>)`
+  - Overlay: `oklch(0.24-0.28 0.01 <hue>)`
+- **Font weight**: reduce by 1 step (600→500, 500→400) — light text on dark looks heavier
+- **Accent colors**: desaturate — reduce OKLCH chroma by 0.05-0.10 from light theme values
+- Never: pure black `#000` background
+
+### Dangerous Combinations
+| Combination | Problem | Fix |
+|-------------|---------|-----|
+| Gray on colored bg | Washed out | Use shade of bg color or white with opacity |
+| Red + Green adjacent | Color blindness | Add icons/patterns |
+| Yellow on white | Invisible | Use dark amber |
+| Thin light text on images | Unpredictable contrast | Text shadow or overlay |
+| Saturated on dark | Visual vibration | Desaturate chroma |