qualia-framework 4.3.0 → 4.5.0

package/templates/DESIGN.md

@@ -1,475 +1,269 @@
-# Design System — {Project Name}
+# DESIGN — {Project Name}
 
-> Source of truth for all frontend work. Builder agents read this before writing any component.
-> `/qualia-new` fills this during project setup. Update as design evolves.
-> Format inspired by [awesome-design-md](https://github.com/VoltAgent/awesome-design-md).
+> Visual contract for `{project}`. Every Qualia agent reads this before any frontend work.
+> `/qualia-new` generates the skeleton. Update as visual decisions firm up.
+> Required pair: `PRODUCT.md` (sets the brief). This file (`DESIGN.md`) realizes it visually.
 
-## 1. Visual Theme & Atmosphere
+## 1. Direction (mandatory commit, before any color or font)
 
-<!-- 2-3 paragraphs describing the FEEL of the site. Not what it does — what it FEELS like.
-     What mood does it create? What's the design philosophy? What makes it distinctive?
-     Example: "The site opens on a deep charcoal canvas with copper accents that feel
-     like a luxury watch brand crossed with a fintech terminal. The custom variable font
-     runs at weight 300 for headlines — light as confidence, not weakness." -->
+```
+Aesthetic direction:  {editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...}
+Color strategy:       {Restrained · Committed · Full palette · Drenched}
+Scene sentence:       {one sentence: who uses this, where, ambient light, mood}
+Differentiation:      {what someone remembers 24 hours later}
+```
+
+This block is the brief in 4 lines. Every other section in this file flows from it. If any other section disagrees, the brief wins or the brief gets rewritten.
+
+## 2. Color (OKLCH only)
+
+> No `#hex`. No `rgb()`. No `hsl()`. OKLCH is the source. Translations happen at build time if at all.
+> No pure `#000` or `#fff` — every neutral tinted toward the brand hue (chroma 0.005-0.015).
+
+### Tokens
+
+```css
+:root {
+  /* Surfaces — tinted toward {hue} */
+  --bg:        oklch(0.16 0.012 {hue});  /* page background */
+  --bg-2:      oklch(0.20 0.014 {hue});  /* raised surface */
+  --surface:   oklch(0.24 0.014 {hue});  /* card */
+  --surface-2: oklch(0.28 0.014 {hue});  /* card on card (rare — depth max 2) */
+
+  /* Text */
+  --text:      oklch(0.94 0.006 {hue});  /* body */
+  --muted:     oklch(0.66 0.010 {hue});  /* secondary */
+  --dim:       oklch(0.50 0.012 {hue});  /* tertiary, captions */
+
+  /* Lines */
+  --line:      oklch(0.32 0.012 {hue});
+  --line-soft: oklch(0.27 0.010 {hue});
+
+  /* Accent — the brand color */
+  --accent:    oklch({L} {C} {H});       /* primary CTA, brand */
+  --accent-2:  oklch({L-0.08} {C-0.01} {H});  /* hover */
+  --accent-bg: oklch({L} {C} {H} / 0.18);     /* tinted bg */
+
+  /* Semantic (Product register only) */
+  --ok:    oklch(0.78 0.14 152);
+  --warn:  oklch(0.78 0.13 65);
+  --kill:  oklch(0.66 0.16 22);
+}
+```
+
+### Accent rules
+
+- Brand register: ≤10% surface coverage IF Restrained, otherwise per strategy
+- Product register: ≤10% surface coverage (Restrained default)
+- Accent must be **sharp** — not a desaturated pastel-of-the-brand
+- Accent contrast vs `--bg`: ≥4.5:1 (WCAG AA for text), ≥3:1 (UI components)
+
+### Contrast verification
 
-{Write the visual narrative here. Be specific about mood, density, and what makes this site NOT look AI-generated.}
+```
+{role} on {role} — {ratio} (WCAG {AA · AA Large · FAIL})
+text on bg       — 12.4:1 (AA)
+muted on bg      — 5.8:1 (AA)
+accent on bg     — 6.2:1 (AA)
+text on accent   — 4.7:1 (AA)
+```
 
-**Key Characteristics:**
-- {Font choice and why — e.g., "Outfit at weight 300 for headlines — geometric, modern, not overused"}
-- {Color signature — e.g., "Deep charcoal (#1a1a2e) backgrounds with copper (#c9784e) accents"}
-- {Shadow approach — e.g., "Warm-tinted multi-layer shadows, not flat or neutral gray"}
-- {Border-radius philosophy — e.g., "Conservative 4-8px, nothing pill-shaped"}
-- {Layout approach — e.g., "Full-bleed sections, asymmetric grids, no card monotony"}
-- {One signature detail — e.g., "Noise texture overlay at 2% on hero, grain filter on images"}
+## 3. Typography
 
-## 2. Color Palette & Roles
+```
+Display:  {font name} — {weight axis} — {use case}
+Body:     {font name} — {weight axis} — {use case}
+Mono:     {font name} — {weight axis} — {use case}
+```
 
-<!-- Every color must have a name, hex value, AND its role. No unnamed colors in code. -->
+**Banned (per `design-laws.md`):** Inter, Roboto, Arial, system-ui, Space Grotesk, Helvetica.
 
-### Primary
-- **{Brand Color Name}** (`#{hex}`): Primary brand identity. Used for {where}.
-- **{Heading Color}** (`#{hex}`): All headings. Not pure black — {warm/cool undertone}.
-- **{Background}** (`#{hex}`): Page background.
+### Scale
 
-### Accent & CTA
-- **{Accent Name}** (`#{hex}`): CTAs, interactive highlights, links.
-- **{Accent Hover}** (`#{hex}`): Hover state for accent elements.
-- **{Secondary Accent}** (`#{hex}`): {role — badges, decorative, gradients}.
+| Token | Size | Line height | Letter spacing | Use |
+|---|---|---|---|---|
+| display | clamp(2.5rem, 5.5vw, 4.25rem) | 1.02 | -0.035em | hero |
+| h1 | clamp(1.8rem, 3.6vw, 2.75rem) | 1.1 | -0.025em | section |
+| h2 | clamp(1.4rem, 2.6vw, 2.1rem) | 1.15 | -0.02em | subsection |
+| h3 | 1.25rem | 1.25 | -0.015em | card title |
+| body | 0.95rem | 1.55 | 0 | paragraphs |
+| small | 0.82rem | 1.5 | 0 | meta |
+| caption | 0.7rem | 1.4 | +0.08em | labels (uppercase) |
 
-### Neutral Scale
-- **{Text Primary}** (`#{hex}`): Body text, paragraphs.
-- **{Text Muted}** (`#{hex}`): Secondary text, descriptions, captions.
-- **{Text Subtle}** (`#{hex}`): Placeholders, hints, disabled text.
-- **{Border Default}** (`#{hex}`): Card borders, dividers.
-- **{Border Subtle}** (`#{hex}`): Faint separators, inactive states.
+### Numerals
 
-### Semantic
-- **Success** (`#{hex}`): With icon. Background: `{rgba}`. Border: `{rgba}`.
-- **Warning** (`#{hex}`): With icon. Background: `{rgba}`. Border: `{rgba}`.
-- **Error** (`#{hex}`): With icon. Background: `{rgba}`. Border: `{rgba}`.
-- **Info** (`#{hex}`): With icon. Background: `{rgba}`. Border: `{rgba}`.
+```css
+.tabular { font-feature-settings: "tnum" 1, "cv11" 1; }
+```
 
-### Shadow Colors
-- **Primary Shadow** (`{rgba}`): {e.g., "Brand-tinted — warm brown-gray, not neutral"}.
-- **Secondary Shadow** (`{rgba}`): Reinforcement layer for depth.
-- **Ambient Shadow** (`{rgba}`): Soft lift for subtle elevation.
+Apply to any column of numbers (tables, financial data, stats).
 
-### CSS Variables
+### Body line length
 
 ```css
-:root {
-  /* Brand */
-  --color-primary: #{hex};
-  --color-primary-hover: #{hex};
-  --color-primary-subtle: #{hex};
+.prose { max-width: 65ch; }
+```
 
-  /* Accent */
-  --color-accent: #{hex};
-  --color-accent-hover: #{hex};
+Cap at 65-75ch. Beyond that, eyes lose the line.
 
-  /* Backgrounds */
-  --color-bg: #{hex};
-  --color-bg-subtle: #{hex};
-  --color-bg-muted: #{hex};
+## 4. Spacing
 
-  /* Text */
-  --color-text: #{hex};
-  --color-text-muted: #{hex};
-  --color-text-subtle: #{hex};
-
-  /* Borders */
-  --color-border: #{hex};
-  --color-border-subtle: #{hex};
-
-  /* Semantic */
-  --color-success: #{hex};
-  --color-warning: #{hex};
-  --color-error: #{hex};
-  --color-info: #{hex};
-
-  /* Shadows */
-  --shadow-primary: {rgba};
-  --shadow-secondary: {rgba};
-  --shadow-ambient: {rgba};
-}
+8px grid, fluid where appropriate.
 
-/* Dark mode — rethink surfaces, don't just invert */
-[data-theme="dark"] {
-  --color-bg: #{hex};
-  --color-bg-subtle: #{hex};
-  --color-text: #{hex};
-  --color-text-muted: #{hex};
-  --color-border: #{hex};
-  /* ... override all tokens ... */
+```css
+:root {
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-16: 64px;
+  --space-24: 96px;
+
+  /* Fluid */
+  --pad-x:        clamp(1rem, 5vw, 4rem);   /* horizontal page padding */
+  --pad-section:  clamp(2rem, 8vw, 6rem);   /* vertical section padding */
+  --pad-card:     1.25rem 1.5rem;            /* card interior */
+  --gap-stack:    1rem;
+  --gap-grid:     1.25rem;
 }
 ```
 
-**Contrast verification:**
-- Body text on background: {ratio} (must be >= 4.5:1)
-- Muted text on background: {ratio} (must be >= 4.5:1)
-- Accent on background: {ratio} (must be >= 3:1 for large text)
-
-## 3. Typography Rules
-
-### Font Families
-- **Display/Heading**: `'{Font Name}'`, {fallback stack}
-- **Body**: `'{Font Name}'`, {fallback stack}
-- **Mono**: `'{Font Name}'`, monospace
-
-**Google Fonts import:** `{URL}`
-
-**Never use:** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk.
-
-### Hierarchy Table
-
-| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
-|------|------|------|--------|-------------|----------------|-------|
-| Display Hero | {display} | {clamp(2.5rem, 1rem + 4vw, 4rem)} | {weight} | 1.05 | {-0.02em} | Largest text on site |
-| Display | {display} | {clamp(2rem, 1rem + 3vw, 3rem)} | {weight} | 1.1 | {-0.015em} | Section heroes |
-| H1 | {heading} | {clamp(1.75rem, 1rem + 2.5vw, 2.5rem)} | {weight} | 1.15 | {-0.01em} | Page titles |
-| H2 | {heading} | {clamp(1.5rem, 0.75rem + 2vw, 2rem)} | {weight} | 1.2 | normal | Section titles |
-| H3 | {heading} | {clamp(1.25rem, 0.75rem + 1.5vw, 1.5rem)} | {weight} | 1.25 | normal | Subsection titles |
-| Body Large | {body} | {1.125rem} | 400 | 1.6 | normal | Intro text, feature descriptions |
-| Body | {body} | {1rem} | 400 | 1.6 | normal | Standard reading text |
-| Body Small | {body} | {0.875rem} | 400 | 1.5 | normal | Secondary text |
-| Caption | {body} | {0.75rem} | 500 | 1.4 | {0.02em} | Labels, metadata |
-| Button | {body} | {0.875rem–1rem} | 500 | 1.0 | {0.01em} | Button text |
-| Code | {mono} | {0.875rem} | 500 | 1.7 | normal | Code blocks |
-
-### Principles
-- {e.g., "Weight 300 at display sizes — light as authority, not shouting"}
-- {e.g., "Progressive tracking: tighter letter-spacing at larger sizes"}
-- {e.g., "Two-weight simplicity: 300 for display, 400 for body/UI, 600 for emphasis only"}
-- Body text max-width: `65ch`. Everything else: fluid full-width.
-- Min body font size: 16px. Never smaller for reading text.
-
-## 4. Component Specifications
-
-### Buttons
-
-**Primary**
-- Background: `var(--color-accent)`
-- Text: `#ffffff`
-- Padding: {8px 20px}
-- Radius: {6px}
-- Font: {size} {font} weight {weight}
-- Hover: `var(--color-accent-hover)`, transition 150ms ease-out
-- Active: `transform: scale(0.98)`
-- Focus: `2px solid var(--color-accent)` offset 2px
-- Disabled: opacity 0.5, `cursor: not-allowed`, `aria-disabled="true"`
-
-**Secondary / Outlined**
-- Background: transparent
-- Text: `var(--color-accent)`
-- Border: `1px solid var(--color-border)`
-- Hover: `var(--color-bg-subtle)` background
-
-**Ghost**
-- Background: transparent
-- Text: `var(--color-text)`
-- Hover: `var(--color-bg-subtle)` background
-
-**Destructive**
-- Background: `var(--color-error)`
-- Text: `#ffffff`
-- Use: Only for irreversible actions with confirmation
-
-**Sizes:** sm (32px height), md (40px), lg (48px)
-
-### Cards & Surfaces
-
-- Background: `var(--color-bg-subtle)`
-- Border: `1px solid var(--color-border-subtle)`
-- Radius: {8px}
-- Shadow (resting): `var(--shadow-ambient) 0px 4px 12px`
-- Shadow (hover): `var(--shadow-primary) 0px 8px 24px, var(--shadow-secondary) 0px 4px 12px`
-- Transition: shadow 200ms ease-out
-- **No identical card grids** — vary layout, size, and emphasis
-
-### Inputs & Forms
-
-- Height: 40px (md), 48px (lg)
-- Border: `1px solid var(--color-border)`
-- Radius: {6px}
-- Focus: `2px solid var(--color-accent)` ring
-- Error: `var(--color-error)` border + error text below with `aria-describedby`
-- Label: visible `<label>` with `htmlFor` — never placeholder-only
-- Placeholder: `var(--color-text-subtle)`
-
-### Badges / Status
-
-- Padding: 2px 8px
-- Radius: {4px}
-- Font: caption size, weight 500
-- Success: `var(--color-success)` bg at 0.15 alpha, text at full, border at 0.3 alpha
-- Warning: same pattern with `var(--color-warning)`
-- Error: same pattern with `var(--color-error)`
-
-### Navigation
-
-- {Sticky header with backdrop-filter blur(12px) / Fixed sidebar / etc.}
-- Logo: {left-aligned / centered}
-- Links: {font, size, weight, color}
-- Active indicator: {underline / background / border-bottom}
-- Mobile: hamburger with drawer, 44px touch target
-- CTA button: accent color, right-aligned
-
-### Toasts / Notifications
-
-- Position: {top-right / bottom-center}
-- `aria-live="polite"` for info, `"assertive"` for errors
-- Auto-dismiss: 5s minimum, dismissible via close button
-- Semantic coloring matching badge pattern
-
-## 5. Layout & Spacing
-
-### Spacing Scale (8px grid)
-
-`4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128`
-
-| Context | Value |
-|---------|-------|
-| Within components | 8–16px |
-| Between related elements | 16–24px |
-| Between sections | `clamp(3rem, 8vw, 6rem)` |
-| Page horizontal padding | `clamp(1rem, 5vw, 4rem)` |
-| Component gap | `clamp(1rem, 3vw, 2rem)` |
-
-### Grid & Layout Strategy
-
-- **Full-width layouts** — no hardcoded `max-width: 1200px` caps
-- Prose/reading content: `max-width: 65ch`
-- Feature sections: varied layouts (side-by-side, staggered, asymmetric, full-bleed)
-- {Specific grid: e.g., "12-column CSS grid with fluid gutters"}
-- Break symmetry where it serves design — offset, overlap, diagonal flow
-
-### Whitespace Philosophy
-
-{e.g., "Dense data, generous chrome. Financial tables are tightly packed, but the UI frame
-around them breathes. Sections alternate between dense content and generous breathing room."}
-
-### Border Radius Scale
-
-| Level | Value | Use |
-|-------|-------|-----|
-| Micro | 2px | Subtle rounding, inline elements |
-| Standard | {4-6px} | Buttons, inputs, badges — the workhorse |
-| Comfortable | {8px} | Cards, containers |
-| Large | {12px} | Featured cards, hero elements |
-| Full | 9999px | Avatars, pills (use sparingly) |
-
-## 6. Depth & Elevation
-
-| Level | Shadow | Use |
-|-------|--------|-----|
-| Flat (0) | none | Page background, inline content |
-| Subtle (1) | `var(--shadow-ambient) 0px 1px 3px` | Resting cards, slight lift |
-| Standard (2) | `var(--shadow-primary) 0px 4px 12px` | Cards, panels |
-| Elevated (3) | `var(--shadow-primary) 0px 8px 24px, var(--shadow-secondary) 0px 4px 12px` | Dropdowns, popovers, hover cards |
-| Overlay (4) | `var(--shadow-primary) 0px 16px 48px, var(--shadow-secondary) 0px 8px 24px` | Modals, dialogs, floating panels |
-| Focus ring | `0 0 0 2px var(--color-accent)` | Keyboard focus (non-negotiable) |
-
-**Shadow philosophy:** {e.g., "Brand-tinted shadows — use warm rgba tones that echo the palette,
-not neutral gray. Multi-layer: branded far shadow + neutral close shadow for depth parallax."}
-
-## 7. Do's and Don'ts
-
-### Do
-- {e.g., "Use weight 300 for display headlines — lightness is the signature"}
-- {e.g., "Apply brand-tinted shadows on all elevated elements"}
-- {e.g., "Use the accent color ONLY for interactive/CTA elements — never decorative"}
-- {e.g., "Keep border-radius within the defined scale — consistency over creativity"}
-- {e.g., "Layer surfaces: bg → subtle → muted, each one shade step apart"}
-- Use `cursor: pointer` on every clickable element
-- Use CSS variables for every color — zero scattered hex values in components
-- Use `clamp()` for fluid typography and spacing
-- Test at 320px, 768px, 1024px, 1440px before shipping
-
-### Don't
-- {e.g., "Don't use bold (700) for headlines — this brand uses light weights"}
-- {e.g., "Don't use pill-shaped buttons (border-radius: 9999px) — conservative rounding only"}
-- {e.g., "Don't use warm accents (orange, yellow) for interactive elements"}
-- Don't use Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk
-- Don't use blue-purple gradients (AI slop tell #1)
-- Don't use identical card grids — vary layout and emphasis
-- Don't use `outline: none` without a visible focus replacement
-- Don't use `max-width: 1200px` or `1280px` containers — go full-width fluid
-- Don't use placeholder-only form inputs — always pair with visible `<label>`
-- Don't ship gray-on-gray text (#999 on #fff fails WCAG)
-
-## 8. Responsive Behavior
-
-### Breakpoints
-
-| Name | Width | Key Changes |
-|------|-------|-------------|
-| Mobile | < 640px | Single column, stacked nav, reduced heading sizes |
-| Tablet | 640–1023px | 2-column grids, condensed nav |
-| Desktop | 1024–1279px | Full layout, expanded nav |
-| Large | >= 1280px | Maximum content width, generous margins |
-
-### Collapsing Strategy
-
-| Element | Desktop | Tablet | Mobile |
-|---------|---------|--------|--------|
-| Navigation | Full horizontal + CTA | Condensed or hamburger | Hamburger + drawer |
-| Hero | {Side-by-side / full-width} | {Stacked, padded} | {Stacked, full-width} |
-| Feature sections | {3-column / asymmetric} | {2-column} | {Single column stacked} |
-| Sidebar | Always visible | Collapsible | Hidden, overlay |
-| Tables | Full table | Scroll with sticky col | Card view |
-| Modals | Centered, max-width | Centered, 80% width | Full screen |
-
-### Touch Targets
-- All interactive elements: 44x44px minimum (48px recommended)
-- Adequate spacing between tap targets (8px minimum gap)
-- Mobile nav toggle: prominent, easy to reach
-
-### Image Behavior
-- `next/image` with explicit `width`/`height` (prevent layout shift)
-- Responsive `srcset` for different densities
-- `max-width: 100%`, `height: auto` on all images
-- Lazy-load below-fold images
-
-## 9. Agent Prompt Guide
-
-### Quick Color Reference
-- Primary CTA: {Name} (`#{hex}`)
-- CTA Hover: {Name} (`#{hex}`)
-- Page background: {Name} (`#{hex}`)
-- Heading text: {Name} (`#{hex}`)
-- Body text: {Name} (`#{hex}`)
-- Muted text: {Name} (`#{hex}`)
-- Border: {Name} (`#{hex}`)
-- Link: {Name} (`#{hex}`)
-- Dark section: {Name} (`#{hex}`)
-- Success: (`#{hex}`)
-- Error: (`#{hex}`)
-
-### Example Component Prompts
-
-**Hero section:**
-"{Describe: background color, headline font/size/weight/color/spacing, subtitle treatment, CTA button specs, layout}"
-
-**Card:**
-"{Describe: background, border, radius, shadow (exact rgba), title font treatment, body text treatment}"
-
-**Form:**
-"{Describe: input border/radius/height, focus ring, label treatment, error state, submit button}"
-
-### Iteration Checklist
-1. Always use CSS variables — never hardcode colors in components
-2. {Font rule — e.g., "Enable ss01 on all display font text"}
-3. {Weight rule — e.g., "Default to 300; use 400 only for UI/buttons"}
-4. {Shadow rule — e.g., "Always use branded rgba, never neutral gray shadows"}
-5. {Heading rule — e.g., "Heading color is deep navy, not black — warmth matters"}
-6. {Radius rule — e.g., "Stay within 4-8px range except avatars"}
-
-## 10. Accessibility (Non-Negotiable)
-
-### Perceivable
-- [ ] All images: descriptive `alt` text (decorative: `alt=""` + `aria-hidden="true"`)
-- [ ] Color contrast: 4.5:1 normal text, 3:1 large text (18px+ bold / 24px+)
-- [ ] Color contrast: 3:1 for UI components and graphical objects
-- [ ] Information not conveyed by color alone — icons, text, patterns as supplements
-- [ ] Text resizable to 200% without loss of content
-- [ ] Content reflows at 320px (no horizontal scroll)
-
-### Operable
-- [ ] All functionality available via keyboard (Tab, Enter, Space, Escape, Arrows)
-- [ ] No keyboard traps (except focus traps in modals)
-- [ ] Visible focus indicator on every interactive element
-- [ ] Skip navigation link: `<a href="#main" class="sr-only focus:not-sr-only">`
-- [ ] Touch targets: 44x44px minimum
-- [ ] Page titles are descriptive and unique
-
-### Understandable
-- [ ] Form inputs have visible `<label>` linked via `htmlFor`
-- [ ] Error messages identify the field and describe the fix
-- [ ] Required fields: `aria-required="true"` + visual indicator
-- [ ] `<html lang="en">` set
-- [ ] Consistent navigation across pages
-
-### Robust
-- [ ] Semantic HTML: `<nav>`, `<main>`, `<article>`, `<section>`, `<header>`, `<footer>`
-- [ ] One `<h1>` per page, sequential heading order
-- [ ] ARIA used correctly when HTML semantics aren't enough
-- [ ] Dynamic content: `aria-live="polite"` for updates, `"assertive"` for errors
-- [ ] Modals: focus trap, close on Escape, `aria-modal="true"`, restore focus on close
-
-## 11. Hardening Criteria
-
-Before shipping, stress-test:
-
-- [ ] **Long text:** 200-character username, 3-paragraph description — does layout hold?
-- [ ] **Empty everywhere:** all lists empty, all data missing — helpful empty states?
-- [ ] **Error everywhere:** every fetch fails — error states visible and recoverable?
-- [ ] **320px viewport:** nothing overflows, clips, or overlaps
-- [ ] **Keyboard only:** Tab through entire app — everything reachable, focus visible?
-- [ ] **Slow network:** loading states visible? Content streams, doesn't flash?
-- [ ] **RTL text:** if applicable, does layout mirror correctly?
-- [ ] **Zoom 200%:** content still usable, nothing hidden?
-
-## 12. Anti-Slop Detection
-
-<!-- These patterns are checked by /qualia-polish grep scans. Any matches = mandatory fix. -->
-
-| Pattern | Check | Fix |
-|---------|-------|-----|
-| Generic fonts | `grep -rn "Inter\|Roboto\|Arial\|Helvetica\|system-ui\|Space.Grotesk"` | Replace with project fonts |
-| Hardcoded containers | `grep -rn "max-w-7xl\|max-w-\[1200\|max-width.*1200"` | Use fluid `clamp()` padding |
-| Blue-purple gradients | `grep -rn "from-blue.*to-purple\|from-purple.*to-blue"` | Use brand colors |
-| Card grid monotony | `grep -rn "grid-cols-3\|grid-cols-4"` in component files | Vary layout and emphasis |
-| Scattered hex colors | `grep -rn "text-\[#\|bg-\[#\|border-\[#"` count > 5 | Use CSS variables |
-| Missing focus styles | `grep -rn "outline: none\|outline:none"` | Add visible focus replacement |
-| Placeholder-only inputs | `<input>` without adjacent `<label>` | Add visible label |
-
-## Motion Reference
-
-### Duration Table
-
-| Action | Duration | Easing |
-|--------|----------|--------|
-| Micro-feedback (press, toggle) | 100ms | ease-out |
-| Hover/focus | 150ms | ease-out |
-| Tooltip, dropdown | 200ms | ease-out |
-| Expand/collapse | 250ms | ease-in-out |
-| Page element enter | 300ms | `cubic-bezier(0, 0, 0.2, 1)` |
-| Page/route transition | 400ms | `cubic-bezier(0.4, 0, 0.2, 1)` |
-| Complex orchestration | 500–800ms | staggered |
-
-### Easing Curves
+**Vary spacing for rhythm.** Same padding everywhere is monotony. Tight within groups, generous between sections.
+
+## 5. Components
+
+Token-driven. Every component composes from above.
+
+### Buttons (Product register: 3 variants max)
+
+```css
+.btn-primary   { background: var(--accent); color: var(--bg); padding: 0.6rem 1.1rem; border-radius: 6px; }
+.btn-secondary { background: var(--surface); border: 1px solid var(--line); color: var(--text); }
+.btn-ghost     { background: transparent; color: var(--text); }
+.btn-danger    { background: var(--kill); color: oklch(0.94 0.006 220); }
+```
+
+### Inputs
+
+- Visible label, never placeholder-only
+- Focus ring: 2px offset, `--accent` color
+- Error: `aria-describedby` linked to inline error text
+
+### Cards
 
 ```css
---ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
---ease-decelerate: cubic-bezier(0, 0, 0.2, 1);
---ease-accelerate: cubic-bezier(0.4, 0, 1, 1);
---ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+.card { background: var(--bg-2); border: 1px solid var(--line); border-radius: 8px; padding: var(--pad-card); }
 ```
 
-### Stagger Pattern
+**Container depth max 2.** No card-on-card.
+
+### Tables (Product register)
+
+- Tabular numerals on numeric columns
+- Sticky header on scroll
+- Right-align numbers, left-align text
+- Sort indicator on hover, persistent on active
+- Row hover background: `--bg-2`
+
+## 6. Depth & elevation
+
+3 levels max. OKLCH-tinted shadows, never neutral gray.
 
 ```css
-@keyframes fadeUp {
-  from { opacity: 0; transform: translateY(12px); }
-  to { opacity: 1; transform: translateY(0); }
+:root {
+  --elev-1: 0 1px 2px oklch(0.10 0.02 {hue} / 0.15);
+  --elev-2: 0 2px 8px oklch(0.10 0.02 {hue} / 0.18);
+  --elev-3: 0 12px 32px oklch(0.10 0.02 {hue} / 0.25);
 }
-.stagger > * { animation: fadeUp 300ms var(--ease-decelerate) both; }
-.stagger > *:nth-child(1) { animation-delay: 0ms; }
-.stagger > *:nth-child(2) { animation-delay: 60ms; }
-.stagger > *:nth-child(3) { animation-delay: 120ms; }
-.stagger > *:nth-child(4) { animation-delay: 180ms; }
-.stagger > *:nth-child(5) { animation-delay: 240ms; }
 ```
 
-### Reduced Motion (mandatory)
+Use elevation semantically: `elev-1` for hovered cards, `elev-2` for popovers, `elev-3` for modals.
+
+## 7. Motion
 
 ```css
+:root {
+  /* Easing */
+  --ease-out-quart: cubic-bezier(0.22, 1, 0.36, 1);
+  --ease-out-expo:  cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-out-std:   cubic-bezier(0, 0, 0.2, 1);
+
+  /* Duration */
+  --d-instant:  100ms;  /* hover, focus */
+  --d-quick:    150ms;  /* tooltip, dropdown */
+  --d-default:  200ms;  /* panel slide */
+  --d-section:  300ms;  /* page transition */
+  --d-feature:  500ms;  /* signature motion */
+}
+
 @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;
   }
 }
 ```
+
+**Don't animate layout properties** (`width`, `height`, `top`, `left`, `margin`, `padding`). Animate `transform` and `opacity` only.
+
+**No bounce. No elastic.** Ease out with exponential curves.
+
+### Signature motion (Brand register only)
+
+Pick ONE. Document below what it is and where it lives.
+
+```
+Signature: {parallax · cursor-follow · letter reveal · scroll scrub · magnetic buttons · morphing shapes · ...}
+Where:     {homepage hero · /work case studies · ...}
+```
+
+## 8. Iconography
+
+```
+Family:   {Lucide · Heroicons · Phosphor · Radix Icons · custom}
+Stroke:   {1.5px · 2px}
+Size:     {16px / 20px / 24px}
+```
+
+ONE icon family. Mixing icon families is the visual equivalent of mixing fonts.
+
+## 9. Responsive
+
+Mobile-first. Test at 375 / 768 / 1280.
+
+```
+Breakpoints:
+  sm:  640px
+  md:  768px
+  lg:  1024px
+  xl:  1280px
+  2xl: 1536px
+
+Touch targets: 44×44px minimum
+Tables on mobile: card view OR horizontal scroll with sticky first col
+Navigation:      hamburger drawer on mobile, full horizontal on lg+
+```
+
+## 10. Anti-pattern checklist (mandatory before commit)
+
+- [ ] No `#000` or `#fff` (only OKLCH)
+- [ ] No banned fonts (Inter, Roboto, Arial, system-ui, Space Grotesk)
+- [ ] No purple-blue gradients
+- [ ] No side-stripe borders (`border-left: ≥2px` decorative)
+- [ ] No gradient text (`background-clip: text`)
+- [ ] No identical card grids of 3
+- [ ] No "Get Started" / "Learn More"
+- [ ] No em dashes in copy (— or `--`)
+- [ ] No `max-w-7xl` or hardcoded width caps
+- [ ] No glassmorphism by default
+- [ ] No modal as first thought
+- [ ] Container depth ≤ 2 on cards/panels
+- [ ] One icon family
+- [ ] `prefers-reduced-motion` respected
+- [ ] Touch targets ≥ 44×44px
+- [ ] WCAG AA contrast verified
+
+`bin/slop-detect.mjs` runs this checklist automatically. Builders run it before every commit.