@hegemonart/get-design-done 1.0.7

package/reference/anti-patterns.md

@@ -0,0 +1,336 @@
+# Anti-Pattern Catalog
+
+Use during Discover (baseline audit), Design (prevention), and Verify (compliance scoring).
+
+---
+
+## The AI-Slop Test
+
+Before shipping any artifact: **"If I told someone 'AI made this,' would they believe me immediately?"**
+
+If yes — redo. The training-set monoculture has specific fingerprints. Learn them all.
+
+---
+
+## Hard Bans (BAN-XX)
+
+Zero tolerance. Each violation = −3 points from Anti-Pattern score. Rewrite rather than soften.
+
+### BAN-01: Side-Stripe Borders
+
+```css
+/* BANNED — AI-generated card tell, regardless of color */
+border-left: 4px solid var(--color-primary);
+border-right: 3px solid #6366f1;
+```
+
+**Why**: The border-left accent card is the most recognizable AI default. It signals no design thinking happened.
+
+**Fix**: Use different element structure — colored icon, colored background section, or inline accent element.
+
+**Grep**: `border-left:\s*[2-9][0-9]*px|border-right:\s*[2-9][0-9]*px`
+
+### BAN-02: Gradient Text
+
+```css
+/* BANNED */
+background: linear-gradient(to right, #6366f1, #8b5cf6);
+-webkit-background-clip: text;
+-webkit-text-fill-color: transparent;
+background-clip: text;
+```
+
+**Why**: Every AI-generated hero uses this. It's a visual cliché and fails against light backgrounds.
+
+**Fix**: Solid color, emphasis via weight or size increase.
+
+**Grep**: `background-clip:\s*text|text-fill-color:\s*transparent`
+
+### BAN-03: Bounce/Elastic Easing
+
+```css
+/* BANNED */
+transition: all 300ms cubic-bezier(0.68, -0.55, 0.265, 1.55);
+animation: bounce 1s ease;
+animation-timing-function: spring(1, 80, 10, 0);
+```
+
+**Why**: Skeuomorphic residue from 2012. Feels toy-like and unprofessional.
+
+**Fix**: `ease-out` for enter, `ease-in` for exit, `ease-in-out` for transitions.
+
+**Grep**: `cubic-bezier\(.*-[0-9]|bounce|elastic|spring\(`
+
+### BAN-04: Animating Keyboard Actions
+
+No animation on: command palette open/close, keyboard shortcuts, tab switching, filter/sort toggles, navigation item expand/collapse.
+
+**Why**: These repeat 100+ times per day. Every millisecond of animation accumulates into felt sluggishness.
+
+**Fix**: Instant state change. Zero transition duration.
+
+### BAN-05: Pure Black Dark Mode
+
+```css
+/* BANNED */
+background: #000000;
+background: rgb(0, 0, 0);
+```
+
+**Why**: Pure black in dark mode creates harsh contrast and looks amateur.
+
+**Fix**: oklch(12% 0 0) through oklch(18% 0.005 [hue]) — slightly warm or cool near-black.
+
+**Grep**: `background.*#000000|background.*rgb\(0,\s*0,\s*0\)`
+
+### BAN-06: Disabling Zoom
+
+```html
+<!-- BANNED -->
+<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+<meta name="viewport" content="width=device-width, maximum-scale=1">
+```
+
+**Why**: WCAG 1.4.4 violation. Breaks accessibility for low-vision users.
+
+**Grep**: `user-scalable=no|maximum-scale=1`
+
+### BAN-07: Naked `outline: none`
+
+```css
+/* BANNED — unless a custom focus indicator replaces it */
+:focus { outline: none; }
+button:focus { outline: 0; }
+```
+
+**Why**: Removes keyboard navigation visibility. WCAG 2.4.7 failure.
+
+**Fix**: `:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 2px; }` with `outline: none` only on `:focus:not(:focus-visible)`.
+
+**Grep**: `:focus\s*\{[^}]*outline:\s*(none|0)`
+
+### BAN-08: `transition: all`
+
+```css
+/* BANNED */
+transition: all 300ms ease;
+```
+
+**Why**: Animates every property including layout properties (width, height, top) causing expensive paint/layout operations.
+
+**Fix**: Specify exact properties: `transition: transform 200ms ease-out, opacity 150ms ease-out;`
+
+**Grep**: `transition:\s*all\s`
+
+### BAN-09: `scale(0)` Animation Entry
+
+```css
+/* BANNED — nothing in the real world materializes from nothing */
+@keyframes enter { from { transform: scale(0); } }
+```
+
+**Fix**: `scale(0.95)` + `opacity: 0` → `scale(1)` + `opacity: 1`.
+
+---
+
+## AI-Slop Tells (SLOP-XX)
+
+Each confirmed tell = −1 point from Anti-Pattern score. These signal training-set monoculture without deliberate design choices.
+
+### SLOP-01: AI Default Palette
+
+```
+#6366f1 (indigo-500) + #8b5cf6 (violet-500) + #06b6d4 (cyan-500)
+```
+
+The exact palette generated by GPT-4 and Claude for 80% of UI requests.
+
+**Grep**: `#6366f1|#8b5cf6|#06b6d4`
+
+### SLOP-02: Purple → Blue Gradient Hero
+
+```css
+background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+background: linear-gradient(to right, #6366f1, #8b5cf6);
+```
+
+### SLOP-03: Cyan Accent on Dark Background
+
+`color: #06b6d4` or `color: #22d3ee` as the primary accent in dark mode.
+
+### SLOP-04: `backdrop-filter: blur` Without Purpose
+
+```css
+/* SLOP if used purely decoratively */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(10px);
+```
+
+Glassmorphism as the default card treatment signals no layout thinking.
+
+**Valid uses**: Modal overlays dimming content behind them, floating command palette, persistent header over content.
+
+**Grep**: `backdrop-filter:\s*blur`
+
+### SLOP-05: Default Font Without Decision
+
+Using Inter, DM Sans, Space Grotesk, or Plus Jakarta Sans without a documented brand reason.
+
+**Test**: Can you give 3 concrete reasons this font matches the product's brand? If not — choose again.
+
+### SLOP-06: Card-in-Card
+
+A component with `border-radius` + `background` + `box-shadow` nested inside another such component.
+
+### SLOP-07: "Icon in Rounded Square Above Every Heading"
+
+The feature section pattern where every item has: `rounded-xl bg-primary/10 p-3 mb-4` containing an icon, followed by a heading and 2 sentences.
+
+### SLOP-08: Rainbow Status Badges
+
+Assigning a different color to every status: blue (pending), yellow (in review), purple (waiting), orange (blocked), teal (processing). Status color must be semantic: green (success/active), yellow (warning/pending), red (error/blocked), gray (inactive/draft). Only those four roles.
+
+### SLOP-09: Decorative Sparklines
+
+Charts placed in dashboards with no real data, purely decorative "trend lines" that don't encode information.
+
+### SLOP-10: Generic Drop Shadow
+
+```css
+box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+```
+
+The Tailwind `shadow-md` default. Used without considering elevation system.
+
+### SLOP-11: "Simple, Powerful, Flexible" Copy
+
+Hero headline triplets with no subject or verb. Feature list as the hero. "We're passionate about..." opener.
+
+### SLOP-12: 3D Isometric Illustration
+
+Pastel-colored isometric illustrations with floating icons. Figma community template vibe. Use photography, real screenshots, or purposefully-styled illustration with brand character.
+
+---
+
+## Visual Anti-Patterns
+
+### Color Errors
+
+- Gray on colored backgrounds (fails contrast, not "subtle")
+- Pure gray neutrals — add 0.005–0.015 chroma toward brand hue
+- Red + green as the only meaning carrier (colorblind failure)
+- Text over image without scrim or overlay
+- Alpha-heavy transparency everywhere (incomplete palette signal)
+- > 1 semantic role for the same color (red = danger ONLY)
+
+### Typography Errors
+
+- Body text < 16px on web (< 12px anywhere)
+- > 6 font-size/weight combinations on a single page
+- `all-caps` body text (labels/badges only)
+- Fluid `clamp()` on app/dashboard UI (marketing headings only)
+- Line height 1.0–1.2 on body text (needs 1.5–1.75)
+- `letter-spacing` changes with no typographic reason
+- `font-weight: 300` on text < 16px (illegible)
+
+### Layout Errors
+
+- Full-width buttons for every CTA (primary only)
+- Placeholder-only labels (no visible `<label>` above input)
+- Multi-column forms on mobile
+- Hamburger as PRIMARY nav on desktop (> 1024px)
+- Bottom nav with > 5 items
+- Container width fixed at 1200px (breaks at 1300+)
+- Spacing values not from 4/8/12/16/24/32/48/64 series (e.g. `padding: 13px`)
+
+### Shadow/Elevation Errors
+
+- 3+ shadow depths when 2 tiers is enough
+- Shadow AND border AND background color on the same element
+- Inner shadow + outer shadow simultaneously
+- Drop shadows on flat/minimal design systems
+
+---
+
+## Motion Anti-Patterns
+
+- `ease-in` on entrances (use `ease-out`)
+- Same duration for enter and exit (exit should be 60–70% of enter)
+- Animating `width`/`height` (triggers layout — use `transform` only)
+- No `prefers-reduced-motion` media query
+- Popover origin `transform-origin: center` (should come from trigger element)
+- Button with no `:active` press feedback
+- Toast re-playing entrance on every state update
+- Decorative pulses > 1s that loop forever
+
+---
+
+## UX/Interaction Anti-Patterns
+
+### Forms
+- Validation firing on every keystroke (exception: password strength)
+- Errors shown only at top of form for field-level problems
+- Native `<select>` for > 10 options without typeahead search
+- No progressive disclosure on long forms (show all fields upfront)
+
+### Feedback
+- Instant (0ms) state transitions — feels broken
+- "Loading..." spinners with no context ("Loading contacts..." is better)
+- Success toast that blocks the next interaction
+- Destructive action with no undo and no confirmation
+- Confirmation dialog for reversible action (annoyance — use undo instead)
+
+### Navigation
+- Browser back button breaks app state
+- Custom back button overriding native swipe gesture (mobile)
+- FAB (floating action button) on iOS native (Material Design pattern, not HIG)
+
+---
+
+## Copy Anti-Patterns
+
+- Placeholder text as the only label (disappears on focus; accessibility failure)
+- "Click here" / "Read more" / "Learn more" links (use verb-first + specific: "Download the guide")
+- "OK" / "Submit" / "Yes" buttons (use action verbs: "Save changes", "Create account", "Delete message")
+- Error messages that blame the user: "You entered an invalid email" → "Email address not recognized"
+- "Oops!" / "Uh oh!" in error states
+- Empty state that only says "No items found" (missed onboarding opportunity)
+
+---
+
+## Auto-Detection Grep Commands
+
+Run these against the codebase for quick anti-pattern audit:
+
+```bash
+# BAN violations (−3 each)
+grep -rn "border-left:\s*[2-9]" src/ --include="*.css" --include="*.scss"
+grep -rn "background-clip:\s*text" src/
+grep -rn "text-fill-color:\s*transparent" src/
+grep -rn "cubic-bezier(.*-[0-9]" src/
+grep -rn "user-scalable=no\|maximum-scale=1" public/
+grep -rn ":focus\s*{" src/ | grep -v "focus-visible"
+grep -rn "transition:\s*all\s" src/
+
+# SLOP signals (−1 each)
+grep -rn "#6366f1\|#8b5cf6\|#06b6d4" src/
+grep -rn "backdrop-filter:\s*blur" src/
+grep -rn "bounce\|elastic" src/ --include="*.css"
+```
+
+---
+
+## Pre-Ship Self-Check
+
+- [ ] Default font (Inter, DM Sans, Space Grotesk) used without a brand reason?
+- [ ] Accent uses purple → blue gradient, cyan-on-dark, or AI default palette?
+- [ ] Any card-in-card nesting?
+- [ ] Every shadow a rounded-rectangle drop shadow?
+- [ ] Hero headline: "Simple, powerful, [noun]"?
+- [ ] Decorative sparklines with no real data?
+- [ ] Empty state just says "No items found"?
+- [ ] Border-left accent on cards/alerts?
+- [ ] Gradient text on any heading?
+- [ ] Bounce or elastic easing anywhere?
+
+If YES to any → rewrite that element before proceeding.

package/reference/audit-scoring.md

@@ -0,0 +1,205 @@
+# Design Audit Scoring Framework
+
+Use during Discover (establishing baseline) and Verify (measuring improvement).
+
+---
+
+## Severity Classification
+
+| Level | Code | Impact | Action |
+|---|---|---|---|
+| Blocker | **P0** | Breaks functionality or violates a hard requirement | Fix before shipping — no exceptions |
+| Major | **P1** | Significantly degrades UX or fails accessibility standard | Fix in this design pass |
+| Minor | **P2** | Noticeable issue but doesn't break flows | Fix if time allows |
+| Cosmetic | **P3** | Polish item only, subjective quality issue | Deferred to polish pass |
+
+---
+
+## Audit Categories and Scoring Rubric
+
+Score each category 0–10. Overall score = weighted average.
+
+### 1. Accessibility (Weight: 25%)
+
+| Score | Criteria |
+|---|---|
+| 10 | All WCAG 2.1 AA criteria pass. Keyboard nav works end-to-end. Focus rings visible. No color-only meaning. |
+| 8–9 | Minor issues — 1–2 non-critical violations, no contrast failures on primary text |
+| 5–7 | Several violations — contrast issues on secondary text, some missing labels |
+| 3–4 | Multiple failures — some interactive elements inaccessible, missing alt text |
+| 0–2 | Critical failures — primary text fails contrast, keyboard nav broken, missing form labels |
+
+Auto-checkable:
+- Body text contrast ≥ 4.5:1
+- Large text contrast ≥ 3:1
+- Touch targets ≥ 44×44px
+- Focus rings present (`:focus-visible` defined)
+- Form labels associated
+- Images have alt text
+- No `<div onClick>` for interactive elements
+
+### 2. Visual Hierarchy (Weight: 20%)
+
+| Score | Criteria |
+|---|---|
+| 10 | Clear primary action per view. Reading order is instantly obvious. Headlines scannable without reading body. |
+| 8–9 | Mostly clear hierarchy, 1–2 competing priorities |
+| 5–7 | Multiple elements compete for primary attention, visual noise |
+| 3–4 | Hard to identify primary action, everything is same weight |
+| 0–2 | No discernible hierarchy, flat design with equal visual weight throughout |
+
+Check for:
+- One primary CTA per section/screen
+- Heading vs body text visually distinguishable by weight/family (not just size)
+- Spacing used to group related elements (8–16px within groups, 32–64px between groups)
+
+### Auto-checkable grep patterns (Phase 3 addition)
+
+Use these patterns during audit to flag hierarchy violations automatically:
+
+**Multiple same-weight headings (hierarchy violation):**
+```bash
+grep -rEn "font-weight:\s*400.*(h1|h2|h3)" src/ --include="*.css" --include="*.scss" 2>/dev/null | head -10
+```
+
+**CTA count (flag >1 primary per section):**
+```bash
+grep -rEn 'variant="primary"|btn-primary|bg-primary' src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | wc -l
+```
+
+**Spacing groups (within-group 8–16px vs between-group 32–64px):**
+```bash
+grep -rEn "(padding|margin|gap):\s*(8|12|16)px" src/ --include="*.css" 2>/dev/null | head -5
+grep -rEn "(margin-top|margin-bottom|gap):\s*(32|40|48|64)px" src/ --include="*.css" 2>/dev/null | head -5
+```
+
+These patterns supplement the qualitative rubric above — they cannot replace
+visual inspection but reduce false positives during automated audit passes.
+
+### 3. Typography (Weight: 15%)
+
+| Score | Criteria |
+|---|---|
+| 10 | Systematic type scale, harmonious pairing, correct line-height/length, consistent weights |
+| 8–9 | Scale mostly consistent, minor deviations |
+| 5–7 | Ad-hoc sizes, inconsistent weights, or poor pairing |
+| 3–4 | No system evident, mixing too many families, poor readability |
+| 0–2 | Body text below 16px, light weights on small text, unreadable |
+
+Check for:
+- Font sizes from a defined scale (not arbitrary px values)
+- Line height 1.5–1.75 on body
+- Max 2 font families (code font is a 3rd exception)
+- No default-Inter-without-decision
+- Weight hierarchy: bold headings, regular body, medium labels
+
+### 4. Color System (Weight: 15%)
+
+| Score | Criteria |
+|---|---|
+| 10 | Cohesive palette with clear roles (primary, secondary, semantic tokens), dark mode quality, no accidental palette |
+| 8–9 | Mostly consistent, minor token inconsistencies |
+| 5–7 | Ad-hoc color usage, some semantic inconsistency |
+| 3–4 | Multiple shades of same hue used without logic, no clear semantic roles |
+| 0–2 | AI default palette, pure black dark mode, decorative gradient overuse |
+
+Check for:
+- Color semantic consistency (red = danger, ONLY danger)
+- No AI-slop palette (#6366f1 + #8b5cf6 + #06b6d4)
+- Dark mode: desaturated variant colors, not pure black
+- Single primary accent used consistently
+
+### 5. Layout & Spacing (Weight: 10%)
+
+| Score | Criteria |
+|---|---|
+| 10 | Consistent 8pt grid, intentional white space, clear content zones, responsive breakpoints |
+| 8–9 | Mostly grid-aligned, minor inconsistencies |
+| 5–7 | Mixed spacing values, some alignment issues |
+| 3–4 | No evident system, arbitrary spacing |
+| 0–2 | Cramped or chaotic layout, broken mobile layout |
+
+Check for:
+- Spacing values from 4/8/12/16/24/32/48/64 series
+- Content max-width enforced (prose: 65ch, layout: 1200–1440px)
+- Mobile breakpoint respected (no horizontal scroll)
+
+### 6. Anti-Pattern Compliance (Weight: 10%)
+
+Score = 10 − (number of hard-ban violations × 3) − (number of AI-slop tells × 1), minimum 0.
+
+Auto-detect (grep):
+- Side-stripe borders > 1px → BAN violation
+- Gradient text → BAN violation
+- `backdrop-filter: blur` without purpose context → slop signal
+- AI palette colors → slop signal
+- Bounce easing → BAN violation
+
+### 7. Interaction & Motion (Weight: 5%)
+
+| Score | Criteria |
+|---|---|
+| 10 | `prefers-reduced-motion` implemented, motion purposeful, correct easing, no bounce, exit < enter |
+| 8–9 | Minor motion issues, no accessibility violations |
+| 5–7 | Some unnecessary motion or poor easing |
+| 3–4 | Bounce easing, missing reduced-motion, blocking animations |
+| 0–2 | Animates keyboard actions, no reduced-motion, excessive animation |
+
+---
+
+## Weighted Score Calculation
+
+```
+Score = (Accessibility × 0.25)
+      + (Visual Hierarchy × 0.20)
+      + (Typography × 0.15)
+      + (Color × 0.15)
+      + (Layout × 0.10)
+      + (Anti-Patterns × 0.10)
+      + (Motion × 0.05)
+```
+
+| Grade | Score | Meaning |
+|---|---|---|
+| A | 90–100 | Excellent — production ready |
+| B | 75–89 | Good — minor polish needed |
+| C | 60–74 | Acceptable — notable issues to address |
+| D | 45–59 | Poor — significant redesign needed |
+| F | 0–44 | Failing — fundamental problems |
+
+---
+
+## Audit Output Format
+
+```markdown
+## Design Audit — [Project Name]
+Date: [ISO 8601]
+Baseline score: [N/100]
+
+### Category Scores
+| Category | Score | Weight | Weighted |
+|---|---|---|---|
+| Accessibility | /10 | 25% | |
+| Visual Hierarchy | /10 | 20% | |
+| Typography | /10 | 15% | |
+| Color | /10 | 15% | |
+| Layout | /10 | 10% | |
+| Anti-Patterns | /10 | 10% | |
+| Motion | /10 | 5% | |
+| **Total** | | | **/100** |
+
+### Findings
+| ID | Severity | Category | Description | Fix |
+|---|---|---|---|---|
+| A-01 | P0 | Accessibility | Body text contrast 3.2:1 (needs 4.5:1) | Change #9CA3AF → #6B7280 |
+| A-02 | P1 | Anti-Pattern | Gradient text on hero heading | Use solid #111827 |
+| A-03 | P2 | Typography | Body line-height 1.3 (needs 1.5+) | Change to 1.6 |
+
+### NNG Heuristic Scores
+| Heuristic | Score /4 | Notes |
+|---|---|---|
+| H-01 Visibility of status | /4 | |
+| H-02 Real world match | /4 | |
+| ... | | |
+| **Total** | /40 | **= NNG Score:** /100 |
+```

package/reference/checklists.md

@@ -0,0 +1,137 @@
+# Pre-Delivery Checklists
+
+Run these before saying "done." Each checklist below is **gated** — if any item fails, you cannot ship.
+
+## Master pre-ship checklist
+
+Use this before any design artifact goes to the user or into a PR.
+
+### Discovery check
+- [ ] Pulled ≥3 real references via refero (or awesome-design-md library if refero unavailable)
+- [ ] Wrote down 3 concrete brand-voice words (not "modern"/"elegant")
+- [ ] Identified 1–2 North Star brand references
+- [ ] Cited references in output so user can redirect
+
+### Context check
+- [ ] `.impeccable.md` exists at project root
+- [ ] `DESIGN.md` exists at project root
+- [ ] Design direction explicitly stated (brutalist / editorial / …)
+- [ ] User approved direction before Phase 3
+
+### AI-slop check (see anti-patterns.md)
+- [ ] Did NOT default to Inter / DM Sans / Space Grotesk / Plus Jakarta Sans
+- [ ] No purple→blue or teal→cyan gradient
+- [ ] No glassmorphism + rounded rect + drop shadow combo
+- [ ] No card-in-card
+- [ ] No `border-left`/`border-right` > 1px on cards/alerts
+- [ ] No gradient text
+- [ ] No sparkline as decoration
+- [ ] No emoji as UI icon
+- [ ] Empty states give context + positive framing + one CTA (not just "No items")
+
+### Accessibility check
+- [ ] Body text ≥ 16px; contrast ≥ 4.5:1
+- [ ] UI components contrast ≥ 3:1
+- [ ] `:focus-visible` style defined (2–3px ring)
+- [ ] Touch targets ≥ 44×44pt iOS / 48×48dp Android
+- [ ] No color-only meaning (pair with icon/text)
+- [ ] `prefers-reduced-motion` respected on all animations
+- [ ] Keyboard can reach and operate every interactive element
+- [ ] Form labels above fields (not placeholder-only)
+- [ ] Semantic heading hierarchy (h1→h6, no skipping)
+
+### Motion check (if any animations)
+- [ ] All animations use transform / opacity (not width/height/top/left)
+- [ ] Custom easing curves (not built-in `ease`)
+- [ ] Exit duration ~75% of enter duration
+- [ ] No animation on keyboard-initiated actions
+- [ ] No `scale(0)` entries (min `scale(0.95)` + opacity)
+- [ ] Popovers use `transform-origin: var(...content-transform-origin)`, not `center`
+
+### Token check
+- [ ] No raw hex in component files (all colors via `var(--...)`)
+- [ ] No `padding: 13px` (off 4pt grid)
+- [ ] All interactive components have: default / hover / focus-visible / active / disabled / loading / error / success
+- [ ] Dark mode defined (not inverted light; tinted oklch 14-18% base)
+- [ ] Typography uses the committed scale (no one-off sizes)
+
+### Copy check (if any text)
+- [ ] Button labels are verb-first and outcome-specific (not "OK" / "Submit" / "Click here")
+- [ ] Error messages: what happened + how to fix (not just what's wrong)
+- [ ] Empty state acknowledges state + explains value + one CTA
+- [ ] No "Oops!" / forced cheer in errors
+- [ ] No 3-adjective pile-up ("beautiful, seamless, intuitive")
+- [ ] Placeholders show format, not restated label
+
+### Technical check (code artifacts)
+- [ ] Browser: running in preview; no console errors
+- [ ] Dev server responds with HTTP 200 on expected routes
+- [ ] Mobile viewport tested (or `impeccable-adapt` run)
+- [ ] Tap delay removed (`touch-action: manipulation`)
+- [ ] Images use WebP/AVIF + `srcset` + lazy-loading where appropriate
+
+### Handoff check (if cross-team)
+- [ ] Ran `Skill(design:design-handoff)` to produce spec sheet
+- [ ] Spec lists every state, every token, every breakpoint
+- [ ] Figma and code token names match (or explicit rename map documented)
+- [ ] Known-unimplemented edge cases flagged with severity
+
+---
+
+## Quick checklist — Small changes
+
+When the change is a single-screen tweak, use this shortened list:
+
+- [ ] Pulled 1–2 references before touching code
+- [ ] Change respects `.impeccable.md` direction (didn't sneak in a different tone)
+- [ ] Interactive element has all 8 states
+- [ ] No item on the absolute-ban list (anti-patterns.md)
+- [ ] Contrast AA
+- [ ] Focus ring present
+- [ ] Touch target ≥ 44pt
+- [ ] Tested in the preview browser
+- [ ] Review presented as Before/After table
+
+---
+
+## Checklist for design system contributions
+
+When adding tokens/components to the design system:
+
+- [ ] New tokens follow `[category].[variant].[property].[state]` naming
+- [ ] No primitive token used directly in a component — route through semantic
+- [ ] Component has full anatomy doc (slots + variants + states + behavior + platform notes + do/don't)
+- [ ] Figma spec frame exists OR explicit note that it doesn't
+- [ ] Component validated against: same-structure-variant rule, not-a-new-component rule
+- [ ] 30-min audit performed — no off-grid spacings, no duplicate color tokens
+
+---
+
+## Checklist for presentations
+
+Before presenting to stakeholders:
+
+- [ ] 6-step narrative spine applied (Orient → Shape → Decision → Why → Defuse → Ask)
+- [ ] Opened with a decision, not exploration
+- [ ] Anticipated top 2–3 objections with pre-addressed slides
+- [ ] Design language translated to business language (efficiency, conversion, a11y reach)
+- [ ] Closed with ONE specific ask (not "thoughts?")
+- [ ] Parking lot section ready if detail derail starts
+- [ ] Decision log slide referenced if revisiting prior choices
+
+---
+
+## Mega-smoke-test for full pages/features
+
+For flagship work:
+
+1. **Squint test.** Blur the screen; most important element still identifiable? Second most? Groupings?
+2. **Zoom to 200%.** No horizontal scroll; nothing clipped; hierarchy holds.
+3. **Tab test.** Tab through every interactive element. Focus visible? Order logical? Nothing skipped?
+4. **Kill CSS test.** Disable all styles. Page still has logical reading order? Headings hierarchical?
+5. **Kill JS test.** Form still submittable via HTML action? Content still visible?
+6. **Throttle test.** Simulate 3G. Skeletons/placeholders in place? LCP < 2.5s?
+7. **Dark mode test.** Toggle. Any broken contrast? Any colors that failed to theme?
+8. **Reduced motion test.** Enable it at OS level. Functional animations preserved, spatial ones killed?
+9. **Mobile test.** Real device or Chrome DevTools mobile emulation. Touch targets? Safe areas? Viewport zoom allowed?
+10. **The AI-slop self-check** (see anti-patterns.md). Honest answer: would someone believe this was AI-generated? If yes, which elements? Fix those.