ima2-gen 2.0.15 → 2.0.16

package/skills/ima2-uiux/references/anti-slop-judgment.md

@@ -0,0 +1,39 @@
+# Anti-Slop Design Judgment
+
+Design-level anti-slop rules. These are JUDGMENT calls made before code —
+implementation enforcement lives in `ima2-front/references/anti-slop-implementation.md`.
+
+## LLM Default Patterns to Reject
+
+These are the patterns AI agents produce when they lack specific direction.
+Reject them on sight:
+
+- **Warm beige/cream backgrounds** with brass/clay accents as "premium" default
+- **Centered hero + three equal feature cards** below
+- **Generic glassmorphism** without functional justification
+- **Inter + slate-900** as the go-to type/color combo
+- **Card-based everything** without layout variety
+- **Purple gradients on white** (old tell, still common)
+- **Gradient mesh backgrounds** as a substitute for real visual content
+
+## 2026 Active Tells
+
+- **Gradient soup** — multiple gradients per viewport, gradients on card grids
+- **One-note dark themes** — terminal green, cyber cyan, CRT amber
+- **Emoji as UI icons** — the #1 signal that AI wrote this
+- **"Elevate your X"** — cliche copy that AI defaults to
+- **Version labels in heroes** ("v3.0", "2.0 Release")
+- **Numbered eyebrows** ("01 — Features", "02 — Pricing")
+- **Fake social proof** ("trusted by teams worldwide", "10,000+ users")
+- **Middle-dot overuse** as a section separator
+- **Duplicate image reuse** across sections
+- **Decorative scroll cues** with no functional purpose
+
+## What to Do Instead
+
+- Use `ima2 gen` to create real, domain-specific visual assets
+- Choose asymmetric or content-weighted layouts
+- Vary section families (at least 4 different per 8 sections)
+- Use domain-appropriate fonts (not Inter unless the project already uses it)
+- Write original copy that names the product's actual value
+- Generate real product photos/illustrations instead of gradient washes

package/skills/ima2-uiux/references/color-system.md

@@ -0,0 +1,80 @@
+## 1. Color Palette Generation
+
+When the user provides a brand color (or you need to generate a palette from scratch), follow this method.
+
+### From Brand Color to Full Palette
+
+1. **Start with the brand hex.** Compute OKLCH values for precise perceptual steps.
+2. **Generate the scale** (50–900) by adjusting lightness while preserving hue and saturation:
+   - 50: background tint (lightness ~97%)
+   - 100–200: hover/pressed states
+   - 300: borders
+   - 400: disabled text
+   - 500: brand primary (the input color)
+   - 600–700: text on light backgrounds
+   - 800–900: heading text, dark surfaces
+
+3. **Add semantic colors:**
+   - Success: green-based (hue ~145°)
+   - Warning: amber-based (hue ~45°)
+   - Danger: red-based (hue ~25°)
+   - Info: blue-based (hue ~220°)
+   - Generate each as a 50–900 scale.
+
+4. **Neutral ramp:** Pick a subtle hue bias from the brand color. Apply it at very low chroma (0.005–0.01) across the gray scale. This gives "warm grays" or "cool grays" that feel cohesive with the brand.
+
+### Practitioner Notes — Hue Budget & Tinted Neutrals (verified 2026-07-07)
+
+Field-tested extensions to the method above (Korean designer community;
+evidence: repo `devlog/_fin/260707_liquid_glass_motion_trends/000_research.md` §2):
+
+- **Hue budget:** most "AI-generated frontend looks off" complaints trace to
+  too many meaning-carrying hues (Von Restorff effect: emphasize everything,
+  emphasize nothing). Semantic colors (success/warn/danger/info) + bg + text
+  already spend most of the budget — new UI meaning should come from the
+  existing scales' lightness/chroma/alpha steps, not a new hue.
+- **Tinted neutrals:** pure `#000` backgrounds and pure `#FFFFFF` surfaces
+  read flat and strain eyes; production dark modes are rarely pure black.
+  Bias black slightly red or blue, bias white slightly yellow for warmth —
+  this is the same low-chroma neutral-ramp rule applied to the extremes.
+- **Brand-first theming:** decide icon/logo/symbol identity first (or
+  together with the UI), then derive the app theme from the brand color via
+  the scale above — the brand-in-theme IS the frontend color principle.
+- **Tools:** see the vetted toolbox below.
+
+### Color Toolbox 2026 (maintenance-checked 2026-07-07)
+
+Reach for the right tool by job, not by habit:
+
+| Tool | Use when | Status |
+|------|----------|--------|
+| tweakcn (tweakcn.com) | shadcn/ui + Tailwind v4 theme editing/export (OKLCH/HSL) | active (repo 2026-06) |
+| OKLCH Picker (oklch.com) | precise OKLCH picking, hex conversion, gamut checks | active (2026-07) |
+| Harmonizer (harmonizer.evilmartians.com) | generating OKLCH UI palettes with APCA-minded contrast | active (2026-04) |
+| Leonardo (leonardocolor.io) | adaptive, accessibility-aware design-system scales + token export | active (Adobe, 2026-05) |
+| Radix Colors (radix-ui.com/colors) | prebuilt accessible app scales — strong neutral/accent pairs | stable (2025-12) |
+| Adobe Color (color.adobe.com) | fast ideation, harmonies, extract-from-image, non-engineer collab | live |
+| Coolors (coolors.co) | rapid palette gacha, quick exports | live |
+| APCA calc (apcacontrast.com) + Atmos checker (atmos.style/contrast-checker) | perceptual contrast checks alongside WCAG | active |
+
+Judgment: for SYSTEM-quality palettes start from OKLCH tools (Picker →
+Harmonizer/Leonardo/Radix); use Adobe/Coolors for ideation only; for
+shadcn/Tailwind v4 projects finish in tweakcn. Huetone is stale (2023) —
+learning reference only. Contrast stance: **WCAG 2.2 is the compliance gate;
+APCA is advisory** until WCAG 3 (Working Draft as of 2026-07-07) settles.
+Implementation mechanics (token layering, oklch() fallbacks, color-mix(),
+light-dark(), Tailwind/shadcn wiring):
+`dev-frontend/references/core/color-system.md`.
+
+### Dark Mode Token Derivation
+- Do NOT simply invert lightness values. Dark mode has its own logic.
+- Elevation = brightness: higher surfaces are lighter (900→800→700 for bg→surface→elevated).
+- Text: use 100–200 range (not pure white — `#e5e5e5` or `#f5f5f5`).
+- Borders: use 700–800 range at low opacity.
+- Accent colors: may need chroma adjustment for dark backgrounds (slightly more saturated).
+
+### Accessible Pair Generation
+For every text-on-background combination, verify:
+- Normal text (< 24px): 4.5:1 contrast ratio minimum (WCAG AA).
+- Large text (≥ 24px or bold ≥ 18.5px): 3:1 minimum.
+- Interactive components: 3:1 against adjacent colors.

package/skills/ima2-uiux/references/design-isms.md

@@ -0,0 +1,194 @@
+## 1. Design Ism Vocabulary
+
+When the user references a design style or movement, or when selecting an aesthetic direction, use this vocabulary. Each ism includes a CSS signature for rapid implementation.
+
+### 1.1 Flat Design
+Minimalist 2D. No shadows, gradients, or textures. Bold saturated solids, clean geometry, ample whitespace.
+```css
+background: #3498db; border: none; border-radius: 0-4px; box-shadow: none;
+font-family: system-ui, sans-serif; font-weight: 400-600;
+```
+**Use:** Content-heavy, mobile-first, government/public services. **Avoid:** Complex data-dense UI, luxury.
+
+### 1.2 Material Design
+Flat + physics-based elevation. Z-axis surfaces with systematic shadows, ripple animations, 8dp grid.
+```css
+box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); /* dp=1 */
+border-radius: 4px; transition: box-shadow 0.3s cubic-bezier(0.25,0.8,0.25,1);
+```
+**Use:** Cross-platform apps, enterprise SaaS, form-heavy workflows. **Avoid:** Distinctive brand identity, Apple-ecosystem.
+
+### 1.3 Glassmorphism
+Frosted-glass with `backdrop-filter: blur()`, transparency, and subtle borders over colorful backgrounds.
+```css
+background: rgba(255,255,255,0.1); backdrop-filter: blur(10px);
+border: 1px solid rgba(255,255,255,0.2); border-radius: 12px;
+```
+**Use:** Over rich backgrounds, navigation overlays, media players, macOS-aligned products. **Avoid:** Plain white backgrounds, text-heavy reading, low-powered devices.
+
+### 1.4 Neumorphism
+Extruded/inset elements from monochromatic background. Paired light+dark soft shadows. Soft plastic/clay feel.
+```css
+background: #e0e0e0;
+box-shadow: 5px 5px 10px #bebebe, -5px -5px 10px #ffffff;
+border-radius: 20px;
+```
+**Use:** Smart home dashboards, music players, single-purpose widgets, low-density internal tools. **Avoid:** Accessibility-critical (WCAG fails on low contrast), data-dense, e-commerce.
+
+### 1.5 Neobrutalism
+Thick black borders, flat bright backgrounds, no blur, oversized bold type, deliberately raw.
+```css
+border: 3px solid #000; background: #ff6b6b;
+box-shadow: 4px 4px 0 #000; border-radius: 0; font-weight: 800-900;
+```
+**Use:** Creative agencies, indie products, developer portfolios, youth-facing. **Avoid:** Finance, healthcare, government, enterprise B2B, luxury.
+
+### 1.6 Claymorphism
+3D clay-like. Thick soft pastel shadows, vibrant rounded elements, cartoon-like inflated depth.
+```css
+background: linear-gradient(135deg, #ff6b9d, #feca57);
+box-shadow: 10px 10px 20px rgba(0,0,0,0.1), -5px -5px 15px rgba(255,255,255,0.7);
+border-radius: 25px;
+```
+**Use:** Children's apps, gamification, onboarding, playful consumer. **Avoid:** Professional tools, finance, healthcare, enterprise.
+
+### 1.7 Art Deco
+Bold geometry, symmetry, metallic finishes, strong vertical emphasis, luxurious ornamentation.
+```css
+font-family: 'Playfair Display', serif; text-transform: uppercase; letter-spacing: 0.15em;
+color: #c9a96e; background: #1a1a2e; border-radius: 0;
+```
+**Use:** Luxury brands, hospitality, jewelry/fashion, event landing pages. **Avoid:** SaaS, developer tools, casual consumer apps.
+
+### 1.8 Bauhaus
+"Form follows function." Reductive, geometric, primary colors (red/yellow/blue) + black/white, grid-based asymmetric.
+```css
+font-family: 'DM Sans', sans-serif; font-weight: 700;
+display: grid; grid-template-columns: 2fr 1fr;
+border: 2px solid #000; border-radius: 0;
+```
+**Use:** Design portfolios, museum/gallery sites, educational platforms. **Avoid:** Complex data interfaces, general consumer apps.
+
+### 1.9 Swiss / International Typographic Style
+Maximum clarity. Grid systems, Helvetica/sans-serif, asymmetric layouts, objective photography, mathematical spacing.
+```css
+font-family: 'Helvetica Neue', 'Inter', sans-serif;
+display: grid; gap: 1.5rem; color: #111; background: #fff;
+```
+**Use:** Corporate identities, developer documentation, data dashboards. **Avoid:** Playful consumer products, entertainment.
+
+### 1.10 Memphis Design
+Anarchic 1980s. Clashing colors, squiggly lines, geometric confetti, deliberately "ugly" compositions.
+```css
+background: #ff6b6b; border-radius: 50% 0 50% 0;
+/* SVG confetti/geometric shapes as background-image */
+```
+**Use:** Event promotions, youth marketing, creative agency sites, social media graphics. **Avoid:** Professional software, finance, healthcare.
+
+### 1.11 Skeuomorphism
+Real-world materials in digital. Leather, wood, metal textures. Realistic shadows, bevels, highlights.
+```css
+background: linear-gradient(to bottom, #e8e8e8, #d0d0d0);
+box-shadow: 0 2px 4px rgba(0,0,0,0.3), inset 0 1px 0 rgba(255,255,255,0.6);
+border: 1px solid #999; border-radius: 8px;
+```
+**Use:** Onboarding for non-technical users, music/audio apps, nostalgic products. **Avoid:** Developer tools, dashboards, SaaS, responsive layouts.
+
+### 1.12 Liquid Glass (Apple, 2025-2026)
+Glassmorphism's successor as a SYSTEM material, not a card style (Apple HIG
+Materials, verified 2026-07-07). Dynamic translucent layer reserved for
+floating controls/navigation; content scrolls beneath and peeks through.
+Adapts to context and user settings (reduced transparency, increased
+contrast). Named material states (canonical: `ima2-front` `liquid-glass.md`):
+`pill-at-top` (~70-80% opacity, only over an authored calm bar zone),
+`pill-scrolled` (85-95% + blur, the default text-bearing chrome state),
+`media-overlay` (the older canvas-55% recipe, media/photo overlays only), and
+`clear` (no blur; sparse controls over rich media). Bar-spawned dropdowns and
+popovers are unconditionally near-opaque, blur-free solid.
+```css
+/* pill-scrolled state */
+background: color-mix(in oklab, canvas 90%, transparent);
+backdrop-filter: blur(16px) saturate(1.4);
+border: 1px solid rgba(255,255,255,0.18); border-radius: 16px;
+box-shadow: inset 0 1px 0 rgba(255,255,255,0.12);
+```
+**Judgment gate vs 1.3 Glassmorphism:** 1.3 styles individual cards over
+colorful backgrounds; Liquid Glass is a two-layer hierarchy decision —
+functional chrome floats as glass, content NEVER does. If someone asks for
+"glass cards" in the content layer, that is 1.3 (and usually slop); reserve
+Liquid Glass for sticky headers, tab bars, sidebars, floating toolbars,
+players. A blur-free variant (near-opaque pills over photographic/pastel
+washes) delivers the same 2026 language at lower cost.
+**Use:** macOS/iOS-aligned products, media-rich consumer apps, floating chrome over scrollable content. **Avoid:** content-layer cards, text-heavy reading surfaces, data-dense dashboards, low-powered targets.
+Implementation recipes, perf budget, and a11y gates: `dev-frontend/references/core/liquid-glass.md`.
+
+### 1.13 Liquid Editorial (2026 no-brief default kit)
+The composite kit behind SKILL.md §1 UX-DEFAULT-ISM-01 (decided 2026-07-07
+from Tier-2 trend research: Apple Liquid Glass 2025-06-09 announcement + HIG
+restraint guidance; Figma/Creative Bloq/Fireart 2026 forecasts naming
+expressive typography, tactile anti-AI texture, and authored color as the
+premium direction). Structure: type-led asymmetric composition OR light
+centered display (FE-HERO-LIGHT-CENTER-01: centered, weight 300-400, over
+full-width real media backdrop; see `ima2-front` `layout-discipline.md`).
+Both carry a Liquid Glass accent layer — the "fancy" lives in the chrome, the
+authorship in the type.
+```css
+/* signature: oversized authored headline + tactile wash + pill chrome */
+h1 { font-size: clamp(2.5rem, 8vw, 6rem); letter-spacing: 0; text-wrap: balance; }
+.wash { background: url(texture-or-photo) / oklch-tinted pastel; }
+.chrome { border-radius: 9999px; background: rgb(255 255 255 / .92); } /* or pill-scrolled state on nav */
+/* children inside pill chrome: fills/tints only, no capsule borders at rest (FE-PILL-NEST-01) */
+:root { --accent: oklch(0.6 0.2 <one hue>); }
+```
+**Use:** no-brief expressive surfaces (landing, consumer, creative, AI-product) as a stated assumption. **Avoid:** any quiet/repeated-work domain; briefs that name another direction; reusing it so uniformly that it becomes the new generic default — vary texture, hue, and the single signature motion per project.
+Related: 1.12 (material rules), `product-personalities.md` Aside profile (chip vocabulary), `ima2-front` `liquid-glass.md` + `motion.md` (implementation).
+
+---
+### 1.14 AI Serif Editorial (2024-2026 serif renaissance)
+The AI-brand serif turn (verified 2026-07-09): display serif at LIGHT weights +
+sans UI + mono technical accent — never "make everything serif". Measured:
+claude.ai `Anthropic Serif` 56px/weight 330 (identity by Geist: Styrene +
+Tiempos); Perplexity's Comet leads with Editorial New (Studio Freight);
+manus.im Libre Baskerville 36px/400; precedent medium.com GT Super 120px/400 +
+Sohne UI. Semiotics: books/scholarship/human-hand trust against AI coldness,
+often with a warm off-white page metaphor.
+```css
+h1, .display { font-family: "Tiempos Headline", "Editorial New", "GT Super", serif;
+  font-weight: 350; font-size: clamp(2.5rem, 5vw, 4.5rem); line-height: 1.15; }
+body, button, input { font-family: var(--sans); }  /* UI stays sans */
+code, .meta { font-family: var(--mono); }          /* technical accent */
+:root { --page: #faf9f5; }                          /* warm off-white page */
+```
+**Use:** AI-product, research, editorial, publication, trust/human-warmth
+brands WITH real editorial structure (long-form typography, page-like
+surfaces, restrained palette). **Avoid:** dashboards, dense tools, SaaS
+layouts wearing a serif as premium shorthand — that is "tasteslop" (WIRED
+2026-06-05); heavy bold display serif (the pattern is 330-400).
+Related: `ima2-front` `aesthetics.md § Serif Discipline`,
+`korea-2026.md § Korean Serif / Myeongjo Display` (MaruBuri pairing).
+
+---
+
+### 1.15 Organic Capsule (OpenAI announcement grammar)
+The OpenAI model-card/hero grammar (in-house Feb-2025 rebrand led by Veit
+Moeller/Shannon Jager; OpenAI Sans by ABC Dinamo; motion/sound by Studio
+Dumbar/DEPT): a soft-focus organic photographic field (natural palettes,
+film grain, some Sora-generated texture) carrying an OPAQUE white capsule
+label with bold warm-sans text. Two strict layers: expressive background
+(no functional text) vs functional capsule/copy (no decoration). Kin to
+Apple's WWDC25 capsule system but opaque, not glass.
+```css
+.field { background: url(soft-focus-organic.jpg) center/cover; }
+.field::after { content:""; position:absolute; inset:0; opacity:.15;
+  /* grain: noise image or feTurbulence */ mix-blend-mode: multiply; }
+.capsule { border-radius: 9999px; background: #fff; color: #111;
+  padding: .4em 1em; font-weight: 700; }
+```
+**Use:** announcement cards, model/product reveals, campaign heroes for
+warm-tech brands; pairs with restrained type-led pages. **Avoid:** mixing the
+layers (text on raw busy background, texture on the capsule), more than one
+organic field per viewport (gradient/texture budget), tools/dashboards.
+Related: `ima2-front` `motion.md § Soft-Focus Organic Background + Capsule
+Label`, `aesthetics.md § Expressive vs Functional Layers`.
+
+---

package/skills/ima2-uiux/references/design-read-example.md

@@ -0,0 +1,33 @@
+# Design Read Example
+
+Use this as a filled-in model for `SKILL.md` §2. Adapt the specifics to the brief; do not copy it as a default style.
+
+## 1. Filled-In Design Read
+
+```yaml
+---
+name: ops-review-console
+colors:
+  primary: "#1f4fd8"
+  accent: "#21a67a"
+  background: "#f7f8fb"
+typography:
+  heading: { fontFamily: "Geist", fontSize: "32px" }
+  body: { fontFamily: "Inter", fontSize: "14px" }
+---
+```
+
+Reading this as: a queue review tool for internal operations teams, with a precise, low-noise command-center language.
+
+The reference is closer to Linear's density and keyboard-first posture than to a SaaS landing page. The first screen should expose live workload, blocked items, and one primary review action without marketing composition.
+
+Do's: compact tables, strong status hierarchy, visible empty/error/loading states, one restrained accent for action and focus.
+
+Don'ts: oversized hero type, decorative cards, purple gradients, fake activity, hover-only controls, or hiding critical status behind tabs.
+
+```
+DESIGN_VARIANCE: 3
+MOTION_INTENSITY: 2
+Product density profile: D5
+Reasoning: repeated operational review needs dense scanning, fast keyboard use, and minimal motion.
+```

package/skills/ima2-uiux/references/design-system-bootstrap.md

@@ -0,0 +1,133 @@
+## 1. Design System Bootstrap
+
+When starting a new project or establishing a design system, use this token architecture template.
+
+### Token Template
+```css
+:root {
+  /* Spacing (4px base) */
+  --space-0: 0; --space-1: 4px; --space-2: 8px; --space-3: 12px;
+  --space-4: 16px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px;
+
+  /* Radius */
+  --radius-none: 0; --radius-sm: 4px; --radius-md: 8px;
+  --radius-lg: 12px; --radius-xl: 16px; --radius-full: 9999px;
+
+  /* Elevation */
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 2px 4px rgba(0,0,0,0.06), 0 1px 2px rgba(0,0,0,0.04);
+  --shadow-lg: 0 4px 12px rgba(0,0,0,0.08), 0 2px 4px rgba(0,0,0,0.04);
+
+  /* Timing — canonical values in Motion Tokens below */
+  --duration-fast: 150ms; --duration-normal: 250ms; --duration-slow: 400ms;
+  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+
+  /* Typography */
+  --font-sans: 'Geist', system-ui, -apple-system, sans-serif;  /* Never default to Inter — see SKILL.md font rules */
+  --font-mono: 'Geist Mono', 'SF Mono', monospace;
+  --text-xs: 0.75rem; --text-sm: 0.875rem; --text-base: 1rem;
+  --text-lg: 1.125rem; --text-xl: 1.25rem; --text-2xl: 1.5rem; --text-3xl: 2rem;
+}
+```
+
+### Component Hierarchy
+- **Atoms:** Button, Input, Badge, Avatar, Icon, Toggle, Checkbox, Radio
+- **Molecules:** Form Field (label + input + error), Card, Menu Item, Search Bar, Stat Card
+- **Organisms:** Navigation Bar, Sidebar, Data Table, Form Section, Modal/Dialog, Command Palette
+
+### Motion Tokens
+
+```css
+:root {
+  /* Easing */
+  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
+
+  /* Duration */
+  --duration-instant: 100ms;
+  --duration-fast: 150ms;
+  --duration-normal: 250ms;
+  --duration-slow: 400ms;
+  --duration-glacial: 600ms;
+
+  /* Composed */
+  --transition-default: var(--duration-normal) var(--ease-default);
+  --transition-enter: var(--duration-normal) var(--ease-out);
+  --transition-exit: var(--duration-fast) var(--ease-in);
+}
+```
+
+### Z-Index Scale
+
+```css
+:root {
+  --z-base: 0;
+  --z-dropdown: 100;
+  --z-sticky: 200;
+  --z-overlay: 300;
+  --z-modal: 400;
+  --z-popover: 500;
+  --z-toast: 600;
+  --z-tooltip: 700;
+  --z-max: 9999;          /* debug overlays only */
+}
+```
+
+- Never use raw z-index numbers — always token reference
+- `z-max` reserved for dev tools
+- Modal backdrop = `--z-modal - 1` (399)
+
+### Breakpoint Tokens
+
+```css
+/* Reference values — use in @media or container queries */
+--bp-sm: 640px;
+--bp-md: 768px;
+--bp-lg: 1024px;
+--bp-xl: 1280px;
+--bp-2xl: 1536px;
+```
+
+Note: CSS custom properties cannot be used in `@media` queries directly. These are reference values for documentation and JS usage. For CSS, use raw values with a comment referencing the token name.
+
+### Token Naming Convention
+
+| Pattern | Example | Use |
+|---------|---------|-----|
+| Semantic | `--color-text-primary`, `--spacing-section` | Component usage |
+| Scale | `--space-4`, `--radius-lg` | Design system primitives |
+| Composed | `--transition-enter` = `duration + ease` | Shorthand combinations |
+
+Semantic tokens reference scale tokens. Components use semantic tokens. Never reference scale tokens directly in components.
+
+### Extending Existing Systems (shadcn/ui)
+- Inspect existing installed components before adding new ones.
+- Use the project's `components.json`, aliases, tokens, and registry conventions.
+- Do not hallucinate components — verify against local source.
+- New components must use the same token variables as existing ones.
+
+### DESIGN.md Format
+
+A project-root `DESIGN.md` persists design tokens and decisions across sessions. Structure:
+
+```markdown
+# Design System — [Project Name]
+
+## Tokens
+<!-- Paste the Token Template and Motion Tokens from above -->
+
+## Colors
+<!-- Semantic color palette: --color-text-primary, --color-bg-surface, etc. -->
+
+## Components
+<!-- Component inventory with variants and states -->
+
+## Rules
+<!-- Project-specific constraints: font stacks, icon system, motion policy -->
+```
+
+Keep `DESIGN.md` under 300 lines. Reference it from SKILL.md routing table, not inline.
+