@withmata/blueprints 0.3.5 → 0.4.0

package/.claude/skills/design-system/SKILL.md

@@ -0,0 +1,970 @@
+---
+name: design-system
+description: Define visual identity and generate Tailwind v4 design tokens through a structured design conversation
+---
+
+# Define Design System
+
+Define a complete visual identity and generate production-ready Tailwind v4 CSS design tokens through a structured design conversation. This is an educational, conversational process — every decision teaches the user WHY a choice works for their product and audience. The output is both a design reference document and a drop-in CSS file that powers the entire UI.
+
+This skill covers visual identity definition and token generation. For scaffolding the Tailwind configuration package, use `/scaffold-tailwind`. For building UI components that consume these tokens, use `/scaffold-ui`.
+
+## Step 1: Read the Blueprint
+
+Read the full design system blueprint:
+
+```
+~/.withmata/blueprints/blueprints/discovery/design-system/BLUEPRINT.md
+```
+
+If not found, run `npx @withmata/blueprints` to install.
+
+The BLUEPRINT.md contains the complete methodology: creative direction frameworks, color theory, typography pairing strategy, component styling philosophy, and output specifications. Follow it precisely.
+
+## Step 2: Read Context
+
+Check if `.project-context.md` exists in the target project root. If it contains product discovery or other relevant sections, read the available docs:
+
+- `docs/product/product-thesis.md` — for product pillars, positioning, value proposition
+- `docs/product/product-brief.md` — for competitive landscape, target market, differentiation
+- `docs/product/users/archetype-*.md` — for audience sensibility, demographics, technical sophistication
+- `docs/pages/landing/*.md` — for brand voice and messaging tone (from marketing copy if available)
+
+Map discovery findings to design inputs:
+
+- **Product type** → aesthetic direction (SaaS dashboard vs. consumer app vs. developer tool vs. e-commerce vs. content platform — each has distinct visual conventions and user expectations)
+- **Primary archetype** → audience sensibility (technical users expect information density and precision; non-technical users expect clarity and guidance; enterprise buyers expect trust signals and polish)
+- **Core pillars** → what the design should communicate (if "speed" is a pillar, the design should feel fast — tight spacing, sharp corners, minimal animation; if "trust" is a pillar — conservative palette, ample whitespace, professional typography)
+- **Brand voice** (from marketing copy docs if available) → visual tone (a playful voice maps to rounded corners, saturated colors, and generous spacing; a professional voice maps to neutral palettes and structured layouts)
+- **Competitive landscape** → differentiation opportunities (if all competitors use blue, consider a different hue; if all competitors feel corporate, consider a more human approach)
+
+Check for existing design work:
+
+- If `docs/design/` exists, this is **upgrade mode** — read `docs/design/design-system.md` and `docs/design/shared-styles.css`, show the user what exists, and offer to refine rather than replace
+- If `config/tailwind-config/shared-styles.css` (monorepo) or `src/styles/shared-styles.css` (single-repo) exists from a previous `/scaffold-tailwind` run, note this — the generated tokens will need to be synced there
+
+Ask: "Do you have any existing UI work you'd like me to reference? You can share screenshots — I'll analyze the visual language and incorporate elements you like."
+
+If the user provides screenshots, analyze them for:
+- Color palette (dominant, accent, neutral tones)
+- Typography style (geometric vs. humanist, weight usage, scale)
+- Spacing density (compact vs. airy)
+- Corner rounding (sharp vs. rounded)
+- Shadow and depth approach
+- Overall mood and personality
+
+If no product docs exist, note what context is missing. Gather it conversationally before proceeding — at minimum, understand the product type, target audience, and desired personality.
+
+## Step 3: Creative Direction
+
+Present 2-3 creative direction options based on the product context. Each direction is a coherent visual world — not just a color, but a complete aesthetic philosophy that connects to the product and audience.
+
+```
+Based on [product context summary], here are 3 creative directions:
+
+1. **"[Evocative Name]"** — [One paragraph describing the complete visual world: colors,
+   typography feel, spacing philosophy, animation personality, and the emotional response
+   it creates. Paint a picture the user can see in their mind.]
+   *Why it fits: [Specific connection to the product's audience, positioning, or
+   competitive differentiation. Reference discovery findings if available.]*
+
+2. **"[Evocative Name]"** — [description]
+   *Why it fits: [reasoning]*
+
+3. **"[Evocative Name]"** — [description]
+   *Why it fits: [reasoning]*
+
+Which direction resonates? You can also mix elements from multiple —
+"I like the colors from 1 but the typography feeling from 3."
+```
+
+The directions should be meaningfully different — not three shades of the same idea. Each should represent a distinct strategic choice about how the product presents itself to its audience.
+
+The chosen direction (or hybrid) becomes the **Creative North Star** — a short phrase and paragraph that guides every subsequent decision. Reference it throughout the remaining steps.
+
+Wait for the user to choose or combine before proceeding.
+
+## Step 4: Color System
+
+This is the most impactful design decision. Colors create immediate emotional responses, establish brand recognition, and directly affect usability. Take time here.
+
+### Research Phase
+
+- Use web search to research competitors' visual identities — note their primary hues, saturation levels, and overall palette temperature
+- Identify color differentiation opportunities (if every competitor in the space uses blue, a violet or teal primary creates instant visual distinction)
+- Research color psychology relevant to the product domain (finance → trust/stability, health → calm/clean, creativity → energy/warmth, developer tools → precision/depth)
+
+### Primary Color Proposal
+
+Propose the primary color with full oklch rationale:
+
+```
+**Primary Color: oklch(0.55 0.22 270)**
+
+**Hue rationale:** Violet (270°) signals creativity and premium quality.
+Your competitors [X, Y, Z] all use blue (220-240°). Shifting to violet
+maintains the trust association of the blue family while creating visual
+distinction and a more modern, premium feel.
+
+**Audience alignment:** Your primary archetype [name] values [quality].
+Violet communicates sophistication without feeling corporate — it says
+"thoughtfully designed" rather than "enterprise procurement approved."
+
+**Competitive differentiation:** In a landscape of blue SaaS dashboards,
+violet is immediately recognizable. When your users see that hue, they
+know they're in your product.
+```
+
+**Generate evocative names:**
+For each color token, create a descriptive name using the pattern: **evocative adjective(s) + color family**. Never use generic names.
+
+Examples:
+- "Deep Indigo" not "primary blue"
+- "Whisper Gray" not "light gray"
+- "Alert Terracotta" not "red"
+- "Warm Barely-There Cream" not "off-white"
+
+These names serve dual purposes: they create emotional association for humans and provide AI agents with richer context about the color's character.
+
+**Present surface layering stack:**
+Show the explicit elevation model:
+```
+Layer 0: background    — Page canvas
+Layer 1: sidebar       — Persistent navigation
+Layer 2: card          — Content containers
+Layer 3: popover       — Floating elements
+Layer 4: overlay       — Modal backdrop
+Layer 5: dialog        — Modal content (highest)
+```
+
+Explain separation strategies: tonal shifts (preferred) → shadows (floating) → ghost borders (accessibility).
+
+### Full Palette Construction
+
+Build the complete palette — all 31+ semantic tokens in oklch format. Explain the relationship between tokens:
+
+**Semantic color tokens (light mode):**
+
+| Token | Value | Usage | Relationship |
+|-------|-------|-------|-------------|
+| `--background` | `oklch(...)` | Page background | Lightest surface |
+| `--foreground` | `oklch(...)` | Primary text | Maximum contrast on background |
+| `--card` | `oklch(...)` | Card surfaces | One step above background |
+| `--card-foreground` | `oklch(...)` | Text on cards | Matches foreground or slightly lighter |
+| `--popover` | `oklch(...)` | Dropdown/popover surfaces | Matches card or slightly elevated |
+| `--popover-foreground` | `oklch(...)` | Text in popovers | Matches card-foreground |
+| `--primary` | `oklch(...)` | Primary actions, links | The brand color |
+| `--primary-foreground` | `oklch(...)` | Text on primary surfaces | High contrast on primary |
+| `--secondary` | `oklch(...)` | Secondary actions | Desaturated primary or neutral |
+| `--secondary-foreground` | `oklch(...)` | Text on secondary surfaces | Readable on secondary |
+| `--muted` | `oklch(...)` | Subtle backgrounds | Very low contrast surface |
+| `--muted-foreground` | `oklch(...)` | Subdued text, placeholders | Deliberately lower contrast |
+| `--accent` | `oklch(...)` | Hover states, highlights | Subtle emphasis |
+| `--accent-foreground` | `oklch(...)` | Text on accent surfaces | Readable on accent |
+| `--destructive` | `oklch(...)` | Error states, delete actions | Red family, high urgency |
+| `--border` | `oklch(...)` | Borders, dividers | Subtle separation |
+| `--input` | `oklch(...)` | Input borders | Slightly more visible than border |
+| `--ring` | `oklch(...)` | Focus rings | Visible but not jarring |
+| `--sidebar` | `oklch(...)` | Sidebar background | Slightly different from main bg |
+| `--sidebar-foreground` | `oklch(...)` | Sidebar text | Readable on sidebar |
+| `--sidebar-primary` | `oklch(...)` | Active sidebar items | Brand color variant |
+| `--sidebar-primary-foreground` | `oklch(...)` | Text on active sidebar items | High contrast |
+| `--sidebar-accent` | `oklch(...)` | Sidebar hover states | Subtle highlight |
+| `--sidebar-accent-foreground` | `oklch(...)` | Text on sidebar hover | Readable |
+| `--sidebar-border` | `oklch(...)` | Sidebar borders | Matches or subtler than main border |
+| `--sidebar-ring` | `oklch(...)` | Sidebar focus rings | Matches or subtler than main ring |
+| `--chart-1` through `--chart-5` | `oklch(...)` | Data visualization | Perceptually uniform steps |
+
+**Surface hierarchy:** Explain the elevation model — how surfaces layer from base → container → card → elevated → popover, and how each level uses color/shadow to communicate depth.
+
+### Dark Mode
+
+Build dark mode variants thoughtfully — not mechanical inversion:
+
+- Backgrounds darken, but not to pure black (too harsh on eyes — use `oklch(0.14-0.20 ...)`)
+- Foregrounds lighten, but not to pure white (use `oklch(0.95-0.99 ...)`)
+- Primary color may need lightness/chroma adjustment to maintain contrast ratios
+- Borders shift to semi-transparent white (`oklch(1 0 0 / 10%)`) for natural layering
+- Destructive red shifts warmer and lighter to maintain visibility without screaming
+- Chart colors may need chroma boost to maintain vibrancy on dark backgrounds
+
+Present both light and dark palettes side by side. Confirm the complete color system before proceeding.
+
+## Step 5: Typography
+
+Typography is the voice of the interface. It carries more information than any other visual element — every word the user reads passes through the type choices.
+
+### Research Phase
+
+- Use web search to research font pairings based on the Creative North Star
+- Search Google Fonts and font directories for options that match the product personality
+- Consider the practical requirements: language support, variable font availability, loading performance, licensing
+
+### Propose 2-3 Pairings
+
+Each pairing should include a display/heading font and a body font, with clear rationale:
+
+```
+**Option A:** Plus Jakarta Sans (display) + Manrope (body)
+*Classification: Geometric sans + Geometric sans (single-family feel, different optical sizes)*
+*Why: The clean geometry signals modern tech, while Manrope's open apertures ensure
+long-form readability. Good for SaaS dashboards where users spend extended time
+reading data and documentation. Both are variable fonts — excellent loading performance.*
+*Google Fonts: fonts.google.com/specimen/Plus+Jakarta+Sans + fonts.google.com/specimen/Manrope*
+
+**Option B:** Inter (display + body) + JetBrains Mono (code)
+*Classification: Neo-grotesque sans (single family)*
+*Why: Inter was designed specifically for computer screens. Its large x-height and
+open apertures make it readable at every size. The tabular numbers are perfect for
+data-heavy interfaces. Boring? Maybe. But boring typography lets the content shine.
+This is the "get out of the way" choice.*
+*Google Fonts: fonts.google.com/specimen/Inter*
+
+**Option C:** Instrument Sans (display) + Source Sans 3 (body)
+*Classification: Contemporary sans + Humanist sans*
+*Why: Instrument Sans has subtle personality in its letterforms — just enough character
+to feel distinctive without competing with content. Source Sans 3 is Adobe's workhorse:
+neutral, readable, professional. The contrast between contemporary display and
+humanist body creates visual hierarchy naturally.*
+*Google Fonts: fonts.google.com/specimen/Instrument+Sans + fonts.google.com/specimen/Source+Sans+3*
+```
+
+### Type Scale
+
+Define the complete type scale using CSS custom properties:
+
+```
+--font-sans: "[chosen font]", system-ui, sans-serif;
+--font-mono: "[chosen mono font]", ui-monospace, monospace;
+```
+
+Explain the scale rationale (e.g., major third ratio 1.25, or custom scale based on product needs).
+
+Wait for the user to confirm their font choice before proceeding.
+
+## Step 6: Spacing, Rounding & Borders
+
+These three decisions create the "personality" of the interface — they're what makes a UI feel sharp, soft, playful, or professional.
+
+### Spacing Base Unit
+
+Propose the base spacing unit (typically 4px or 8px) with rationale connected to the creative direction.
+
+### Rounding Personality
+
+Present rounding options with vivid visual descriptions so the user can picture each:
+
+```
+**Sharp (radius: 0.25rem / 4px)**
+Clean cuts, editorial precision. Communicates efficiency and seriousness.
+Think Bloomberg Terminal, Linear, Figma. Best for: developer tools, data
+platforms, professional B2B.
+
+**Moderate (radius: 0.5rem / 8px)**
+Professional but approachable. The most versatile choice — reads as
+"designed" without being playful. Think Notion, Stripe Dashboard, Vercel.
+Best for: SaaS products, productivity tools, most B2B.
+
+**Round (radius: 0.625rem / 10px)**
+Friendly and modern. Softens the interface without feeling childish.
+Think Stripe Marketing, Linear Marketing, Raycast. Best for: consumer-
+facing SaaS, marketplaces, creative tools.
+
+**Full (radius: 1rem+ / 16px+)**
+Playful and warm. Creates a casual, consumer-friendly feeling.
+Think Duolingo, Headspace, Notion AI. Best for: consumer apps,
+education, wellness, entertainment.
+```
+
+Recommend the option that best matches the Creative North Star, but let the user choose.
+
+### Border Philosophy
+
+Propose the border approach:
+
+- **Minimal borders** — rely on spacing and surface color for separation (modern, clean)
+- **Subtle borders** — light borders define containers, inputs get clear boundaries (structured, professional)
+- **Defined borders** — visible borders on most containers (traditional, data-dense UIs)
+
+Define the radius scale tokens:
+
+```
+--radius: [base value];
+/* These are derived automatically: */
+--radius-sm: calc(var(--radius) - 4px);
+--radius-md: calc(var(--radius) - 2px);
+--radius-lg: var(--radius);
+--radius-xl: calc(var(--radius) + 4px);
+--radius-2xl: calc(var(--radius) + 8px);
+--radius-3xl: calc(var(--radius) + 12px);
+--radius-4xl: calc(var(--radius) + 16px);
+```
+
+Confirm before proceeding.
+
+## Step 7: Layout & Responsive Behavior
+
+Define how the design system adapts across viewport sizes.
+
+**Propose grid system:**
+- Container max-width (1280px for content-focused, 1440px for dashboards)
+- Column structure (12-column for complex layouts, simpler for marketing pages)
+- Gutter width (typically 1rem or 1.5rem, derived from base spacing)
+
+**Define breakpoints:**
+Present the responsive strategy with Tailwind breakpoint mapping:
+```
+Mobile:  < 640px  (sm)  — single column, stacked, thumb-friendly
+Tablet:  640-1024px (sm-lg) — 2 columns, sidebar may collapse
+Desktop: 1024-1440px (lg-2xl) — full layout, sidebar expanded
+Large:   > 1440px — content max-width, generous margins
+```
+
+**Document responsive component behaviors:**
+Present a table showing how each major component adapts:
+
+| Component | Mobile | Tablet | Desktop |
+|-----------|--------|--------|---------|
+| Sidebar | Hidden (hamburger) | Icon-only collapsed | Full expanded |
+| Modals | Full-screen, slide-up | Centered, max-w-lg | Centered |
+| Navigation | Bottom tabs or hamburger | Horizontal condensed | Full horizontal |
+| Card Grid | 1 column | 2 columns | 3-4 columns |
+| Tables | Horizontal scroll | Horizontal scroll | Full table |
+| CTAs | Full width, sticky | Auto width | Auto width |
+
+**Touch targets:** Minimum 44x44px (WCAG AA), recommended 48x48px.
+
+Confirm layout/responsive decisions before proceeding.
+
+## Step 8: Component Styling Guidelines
+
+For each component type, propose specific styling decisions. These are deep, opinionated guidelines that connect back to the Creative North Star. Present as a structured guide the user confirms.
+
+### Buttons
+
+- **Primary:** gradient vs. flat fill, shadow on hover or not, active state (scale-down or darken)
+- **Secondary:** outline vs. subtle fill, border weight, hover behavior
+- **Ghost:** hover background (muted or accent), text color change on hover
+- **Destructive:** red intensity, when to use outline vs. fill
+- **Padding per size:** sm / default / lg with specific values
+- **Icon alignment:** gap between icon and label, icon-only button sizing
+- **State transitions:** duration, easing, which properties animate
+- **Disabled state:** opacity level, cursor style, how to communicate "not clickable" accessibly
+
+### Cards
+
+- **Surface color:** card token vs. background token, when to elevate
+- **Shadow level:** none / xs / sm — connected to the depth philosophy
+- **Rounding:** uses radius-lg or radius-xl
+- **Internal spacing:** header padding, content padding, footer padding
+- **Border:** visible border or shadow-only separation
+- **Hover state (interactive cards):** shadow lift, border highlight, or subtle background shift
+
+### Inputs
+
+- **Style:** filled (muted background) vs. outlined (border only) vs. hybrid (border + subtle fill)
+- **Focus state:** ring glow (primary tinted) vs. border color change vs. both
+- **Error state:** destructive border + helper text, icon indicator, background tint
+- **Label placement:** above (standard) vs. floating vs. inline
+- **Size variants:** sm / default / lg with specific height/padding values
+
+### Modals / Dialogs
+
+- **Backdrop:** color and blur intensity (e.g., `oklch(0 0 0 / 50%)` + `backdrop-blur-sm`)
+- **Surface:** card token, elevated shadow
+- **Enter animation:** scale-in + fade or slide-up + fade
+- **Exit animation:** reverse of enter, slightly faster
+- **Rounding:** typically radius-xl or radius-2xl (larger than cards)
+
+### Navigation
+
+- **Active indicator:** background highlight, left/bottom border accent, or text weight change
+- **Hover behavior:** background shift, text color change
+- **Collapsed state (sidebar):** icon-only with tooltip, active indicator persists
+- **Mobile behavior:** bottom tab bar vs. hamburger drawer
+
+### Badges
+
+- **Rounding:** full radius (pill) vs. matching component radius
+- **Size variants:** sm / default / lg
+- **Color mapping:** which semantic colors map to which badge meanings (success=green, warning=amber, etc.)
+
+### Tables
+
+- **Header treatment:** bold text + muted background, or bold text + bottom border only
+- **Row hover:** subtle background highlight
+- **Border approach:** horizontal lines only, full grid, or minimal (zebra striping)
+- **Sticky header behavior:** shadow on scroll
+
+### Forms (Layout)
+
+- **Field spacing:** gap between form fields (typically 1.5rem-2rem)
+- **Section grouping:** how to visually separate form sections (heading + border, or spacing only)
+- **Error display:** inline below field, toast notification, or summary at top
+- **Required field indicator:** asterisk, "(required)" text, or mark optional fields instead
+
+Present the complete component guide and wait for confirmation before proceeding.
+
+## Step 9: Shadows & Depth
+
+Shadows create spatial hierarchy — they tell the user what's "above" what. The shadow system should feel intentional, not arbitrary.
+
+### Shadow Scale
+
+Propose the complete shadow scale:
+
+```
+--shadow-xs:  [very subtle, for borders/pressed states]
+--shadow-sm:  [cards, containers — resting state]
+--shadow-md:  [raised cards, interactive hover states]
+--shadow-lg:  [dropdowns, popovers, floating elements]
+--shadow-xl:  [modals, command palettes]
+--shadow-2xl: [toasts, notifications — highest elevation]
+```
+
+### Shadow Color Decision
+
+- **Neutral shadows:** `oklch(0 0 0 / N%)` — safe, works everywhere
+- **Tinted shadows:** `oklch([hue of primary] / N%)` — more cohesive, adds subtle warmth/coolness
+- Recommend based on creative direction
+
+### Component-Shadow Mapping
+
+Map shadow levels to specific component usage:
+
+| Component | Resting | Hover | Active |
+|-----------|---------|-------|--------|
+| Card | shadow-sm | shadow-md | — |
+| Button (primary) | shadow-xs | shadow-sm | none |
+| Dropdown | — | — | shadow-lg |
+| Modal | — | — | shadow-xl |
+| Toast | — | — | shadow-2xl |
+| Input | none | none | none (uses ring) |
+
+### Glassmorphism (if applicable)
+
+If the creative direction calls for glass/translucent effects, define the recipe:
+
+```
+background: oklch(1 0 0 / 70%);
+backdrop-filter: blur(12px);
+border: 1px solid oklch(1 0 0 / 20%);
+```
+
+Confirm before proceeding.
+
+## Step 10: Animation & Motion
+
+Motion gives the interface life — it communicates state changes, guides attention, and creates a sense of craft. But motion that's too slow or too frequent becomes annoying. The goal is motion that feels inevitable, not decorative.
+
+### Duration Scale
+
+```
+--duration-fast:   100ms   (micro-interactions: hover, focus, toggle)
+--duration-normal: 200ms   (state changes: expand, collapse, fade)
+--duration-slow:   350ms   (major transitions: modal enter, page transition)
+```
+
+### Easing Curves
+
+Propose custom easing curves with personality descriptions:
+
+```
+--ease-out:    cubic-bezier(0.16, 1, 0.3, 1)       — snappy deceleration, feels responsive
+--ease-in-out: cubic-bezier(0.76, 0, 0.24, 1)      — smooth, balanced movement
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1)   — slight overshoot, playful energy
+```
+
+Adjust based on creative direction — sharp/professional UIs use ease-out only; playful UIs can use spring easing.
+
+### Keyframe Animations
+
+Define the standard animation set:
+
+```
+@keyframes fade-in       — opacity 0 → 1
+@keyframes fade-out      — opacity 1 → 0
+@keyframes slide-up      — translateY(4px) + opacity 0 → translateY(0) + opacity 1
+@keyframes slide-down    — translateY(-4px) + opacity 0 → translateY(0) + opacity 1
+@keyframes scale-in      — scale(0.95) + opacity 0 → scale(1) + opacity 1
+@keyframes scale-out     — scale(1) + opacity 1 → scale(0.95) + opacity 0
+@keyframes spin          — rotate(0deg) → rotate(360deg)
+@keyframes accordion-down — height 0 → var(--radix-accordion-content-height)
+@keyframes accordion-up   — reverse of accordion-down
+```
+
+### Animation Tokens
+
+Map keyframes to utility-ready animation tokens:
+
+```
+--animate-fade-in:       fade-in [duration] [easing]
+--animate-fade-out:      fade-out [duration] [easing]
+--animate-slide-up:      slide-up [duration] [easing]
+--animate-slide-down:    slide-down [duration] [easing]
+--animate-scale-in:      scale-in [duration] [easing]
+--animate-scale-out:     scale-out [duration] [easing]
+--animate-spin:          spin 1s linear infinite
+--animate-accordion-down: accordion-down [duration] [easing]
+--animate-accordion-up:   accordion-up [duration] [easing]
+```
+
+### Motion Philosophy
+
+Define what animates and what doesn't:
+
+- **Always animates:** hover/focus states, modal enter/exit, dropdown open/close, accordion expand/collapse, route transitions (if SPA)
+- **Never animates:** initial page render content, scroll position, text content changes
+- **Reduced motion:** all animations respect `prefers-reduced-motion: reduce` — either disabled entirely or replaced with a simple opacity fade
+
+Confirm before proceeding to output generation.
+
+## Step 11: Generate Outputs
+
+Write both files in the target project:
+
+### File 1: `docs/design/design-system.md`
+
+Full design reference document with 14 sections:
+
+1. Creative North Star
+2. Color Philosophy (with evocative naming table + surface layering diagram)
+3. Typography
+4. Spacing & Rhythm
+5. Rounding
+6. Layout & Responsive (grid, breakpoints, component adaptation table)
+7. Elevation & Depth
+8. Component Guidelines
+9. Animation & Motion
+10. Do's and Don'ts (includes "Common AI Mistakes to Prevent" with specific negative constraints)
+11. How to Use (includes Design Language Translation table mapping Tailwind classes to natural language)
+12. Agent Context — Design System Quick Reference
+
+The Agent Context section (section 12) includes:
+- **Color Map:** flat list of every token with oklch value + Tailwind class
+- **Component Recipes:** ready-to-paste class combinations for buttons, cards, inputs, badges, etc.
+- **Spacing Cheat Sheet:** common spacing patterns with exact values
+- **Surface Layering:** quick reference for which bg-* class to use at each layer
+- **Design Rules (for AI):** 10 imperative rules distilled from Do's and Don'ts
+
+Document structure:
+
+```markdown
+# [Product Name] Design System
+
+## Creative North Star
+[The chosen direction name and description — the emotional/aesthetic guiding principle]
+
+## Color Philosophy
+[Palette rationale — why these hues, how they connect to the audience and product]
+
+### Color Reference
+
+| Token | Light Mode | Dark Mode | Usage | Tailwind Class |
+|-------|-----------|-----------|-------|---------------|
+| background | oklch(...) | oklch(...) | Page background | `bg-background` |
+| foreground | oklch(...) | oklch(...) | Primary text | `text-foreground` |
+| ... all 31+ tokens ... |
+
+### Surface Hierarchy
+[Base → container → card → elevated → popover explanation]
+
+## Typography
+[Font pairing rationale + import instructions]
+
+### Type Scale
+| Level | Font | Size | Weight | Line Height | Tailwind Class |
+|-------|------|------|--------|-------------|---------------|
+| ... |
+
+## Spacing & Rhythm
+[Base unit, scale, usage guidelines]
+
+## Rounding
+[Personality choice + rationale]
+
+### Radius Scale
+| Token | Value | Usage | Tailwind Class |
+|-------|-------|-------|---------------|
+| radius-sm | ... | Small elements | `rounded-sm` |
+| ... |
+
+## Layout & Responsive
+[Grid system, breakpoints, and component adaptation table from Step 7]
+
+### Grid System
+| Property | Value | Rationale |
+|----------|-------|-----------|
+| Container max-width | ... | ... |
+| Columns | ... | ... |
+| Gutter | ... | ... |
+
+### Breakpoints
+| Name | Range | Tailwind | Layout Behavior |
+|------|-------|----------|----------------|
+| Mobile | < 640px | sm | ... |
+| Tablet | 640-1024px | sm-lg | ... |
+| Desktop | 1024-1440px | lg-2xl | ... |
+| Large | > 1440px | 2xl+ | ... |
+
+### Component Responsive Behaviors
+| Component | Mobile | Tablet | Desktop |
+|-----------|--------|--------|---------|
+| Sidebar | ... | ... | ... |
+| ... |
+
+## Elevation & Depth
+[Shadow philosophy + scale]
+
+### Shadow Scale
+| Token | Value | Usage | Tailwind Class |
+|-------|-------|-------|---------------|
+
+### Border Philosophy
+[When to use borders vs. shadows vs. spacing]
+
+## Component Guidelines
+[Deep, per-component styling guide from Step 8 — buttons, cards, inputs, modals,
+navigation, badges, tables, forms]
+
+## Animation & Motion
+[Philosophy + practical guide]
+
+### Duration Scale
+| Token | Value | Usage |
+|-------|-------|-------|
+
+### Easing Curves
+| Token | Value | Personality |
+|-------|-------|------------|
+
+### Animation Tokens
+| Token | Value | Usage |
+|-------|-------|-------|
+
+## Do's and Don'ts
+[Practical guidelines — what to do, what to avoid, common mistakes]
+
+### Common AI Mistakes to Prevent
+[Specific negative constraints for AI agents generating UI with this design system.
+Examples: "Never use bg-gray-100 — always use bg-muted", "Never hardcode
+colors — always use semantic tokens", "Never mix rounded-full with rounded-lg
+in the same component group"]
+
+## How to Use
+[Practical guide with Tailwind class examples for each token category.
+This is the bridge between design decisions and development.]
+
+### Colors
+`bg-primary`, `text-primary-foreground`, `border-border`, `ring-ring`, etc.
+
+### Typography
+`font-sans`, `font-mono`, how to apply the type scale
+
+### Spacing
+How to use the spacing scale consistently
+
+### Rounding
+`rounded-sm`, `rounded-md`, `rounded-lg`, etc. — when to use which
+
+### Shadows
+`shadow-xs`, `shadow-sm`, etc. — component mapping
+
+### Animation
+`animate-fade-in`, `animate-slide-up`, etc. — when to use which
+
+### Design Language Translation
+| Natural Language | Tailwind Classes | When to Use |
+|-----------------|-----------------|-------------|
+| "Make it feel elevated" | `shadow-md bg-card` | Cards that need visual prominence |
+| "Subtle container" | `bg-muted/50 rounded-lg` | Background sections, grouped content |
+| "Call to action" | `bg-primary text-primary-foreground` | Primary buttons, key links |
+| "De-emphasized" | `text-muted-foreground` | Helper text, timestamps, metadata |
+| "Danger zone" | `bg-destructive text-destructive-foreground` | Delete actions, error states |
+| ... comprehensive mapping of design intent to classes ... |
+
+### Quick Reference
+| I want to... | Use this class |
+|--------------|---------------|
+| Set page background | `bg-background` |
+| Style primary text | `text-foreground` |
+| Style a primary button | `bg-primary text-primary-foreground` |
+| Style a card | `bg-card text-card-foreground rounded-lg shadow-sm` |
+| ... comprehensive mapping ... |
+
+## Agent Context — Design System Quick Reference
+
+### Color Map
+| Token | Light oklch | Dark oklch | Evocative Name | Tailwind Class |
+|-------|------------|-----------|----------------|---------------|
+| background | oklch(...) | oklch(...) | [name] | `bg-background` |
+| ... all tokens ... |
+
+### Component Recipes
+```
+Primary Button:   bg-primary text-primary-foreground rounded-[radius] shadow-xs hover:shadow-sm
+Secondary Button: bg-secondary text-secondary-foreground rounded-[radius]
+Card:             bg-card text-card-foreground rounded-lg shadow-sm border
+Input:            bg-background border border-input rounded-md ring-ring
+Badge:            bg-primary/10 text-primary rounded-full text-xs px-2 py-0.5
+```
+
+### Spacing Cheat Sheet
+| Pattern | Value | Usage |
+|---------|-------|-------|
+| Component gap | ... | Between sibling elements |
+| Section gap | ... | Between page sections |
+| Card padding | ... | Inside card containers |
+| Input height | ... | Form field height |
+
+### Surface Layering
+| Layer | Token | Tailwind Class | Usage |
+|-------|-------|---------------|-------|
+| 0 | background | `bg-background` | Page canvas |
+| 1 | sidebar | `bg-sidebar` | Persistent navigation |
+| 2 | card | `bg-card` | Content containers |
+| 3 | popover | `bg-popover` | Floating elements |
+| 4 | — | `bg-black/50` | Modal backdrop |
+| 5 | popover | `bg-popover` | Modal/dialog content |
+
+### Design Rules (for AI)
+[10 imperative rules distilled from Do's and Don'ts. Examples:]
+1. ALWAYS use semantic color tokens (`bg-primary`) — NEVER use raw colors (`bg-blue-500`)
+2. ALWAYS pair foreground with its matching background (`text-card-foreground` on `bg-card`)
+3. NEVER mix border-radius scales within a component group
+4. ALWAYS apply both light and dark mode tokens together
+5. ALWAYS use the shadow scale for elevation — NEVER use arbitrary shadow values
+6. ... 5 more project-specific rules ...
+```
+
+### File 2: `docs/design/shared-styles.css`
+
+Production-ready Tailwind v4 CSS that is a **drop-in replacement** for the tailwind-v4 template. Include descriptive comments with evocative names for every color token:
+
+```css
+--primary: oklch(0.488 0.243 264.376); /* Deep Indigo — CTAs, active states */
+--muted: oklch(0.97 0 0); /* Whisper Gray — subtle backgrounds */
+--destructive: oklch(0.58 0.22 27); /* Alert Terracotta — errors, danger */
+```
+
+This makes the CSS self-documenting and gives AI agents context when reading the raw file. Same structure, same variable names, same `@theme` block — only the values change.
+
+The file MUST follow this exact structure:
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "tailwind-scrollbar-hide/v4";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  /* Map all semantic CSS variables to Tailwind utility classes */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+}
+
+@theme {
+  /* Extended tokens: shadows, easing, duration, animations */
+  --shadow-xs: ...;
+  --shadow-sm: ...;
+  --shadow-md: ...;
+  --shadow-lg: ...;
+  --shadow-xl: ...;
+  --shadow-2xl: ...;
+
+  --ease-out: cubic-bezier(...);
+  --ease-in-out: cubic-bezier(...);
+  --ease-spring: cubic-bezier(...);
+
+  --animate-fade-in: fade-in ...;
+  --animate-fade-out: fade-out ...;
+  --animate-slide-up: slide-up ...;
+  --animate-slide-down: slide-down ...;
+  --animate-scale-in: scale-in ...;
+  --animate-scale-out: scale-out ...;
+  --animate-spin: spin 1s linear infinite;
+  --animate-accordion-down: accordion-down ...;
+  --animate-accordion-up: accordion-up ...;
+
+  @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
+  @keyframes fade-out { from { opacity: 1; } to { opacity: 0; } }
+  @keyframes slide-up { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: translateY(0); } }
+  @keyframes slide-down { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: translateY(0); } }
+  @keyframes scale-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } }
+  @keyframes scale-out { from { opacity: 1; transform: scale(1); } to { opacity: 0; transform: scale(0.95); } }
+  @keyframes spin { to { transform: rotate(360deg); } }
+  @keyframes accordion-down { from { height: 0; } to { height: var(--radix-accordion-content-height); } }
+  @keyframes accordion-up { from { height: var(--radix-accordion-content-height); } to { height: 0; } }
+}
+
+:root {
+  --background: oklch(...);
+  --foreground: oklch(...);
+  --card: oklch(...);
+  --card-foreground: oklch(...);
+  --popover: oklch(...);
+  --popover-foreground: oklch(...);
+  --primary: oklch(...);
+  --primary-foreground: oklch(...);
+  --secondary: oklch(...);
+  --secondary-foreground: oklch(...);
+  --muted: oklch(...);
+  --muted-foreground: oklch(...);
+  --accent: oklch(...);
+  --accent-foreground: oklch(...);
+  --destructive: oklch(...);
+  --border: oklch(...);
+  --input: oklch(...);
+  --ring: oklch(...);
+  --chart-1: oklch(...);
+  --chart-2: oklch(...);
+  --chart-3: oklch(...);
+  --chart-4: oklch(...);
+  --chart-5: oklch(...);
+  --radius: ...;
+  --font-sans: "...", system-ui, sans-serif;
+  --font-mono: "...", ui-monospace, monospace;
+  --sidebar: oklch(...);
+  --sidebar-foreground: oklch(...);
+  --sidebar-primary: oklch(...);
+  --sidebar-primary-foreground: oklch(...);
+  --sidebar-accent: oklch(...);
+  --sidebar-accent-foreground: oklch(...);
+  --sidebar-border: oklch(...);
+  --sidebar-ring: oklch(...);
+}
+
+.dark {
+  --background: oklch(...);
+  --foreground: oklch(...);
+  /* ... all dark mode tokens with thoughtful adjustments ... */
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+All `oklch(...)` values must be filled with the actual colors confirmed in Step 4. All shadow, easing, and animation values must reflect the confirmed decisions from Steps 9-10. The `--font-sans` and `--font-mono` must use the confirmed fonts from Step 5.
+
+### Sync Check
+
+After writing both files, check if `config/tailwind-config/shared-styles.css` (monorepo) or `src/styles/shared-styles.css` (single-repo) already exists from a previous `/scaffold-tailwind` run. If it does:
+
+"I see you already have a scaffolded shared-styles.css at [path]. Would you like me to copy the new design tokens there now? This will replace the default palette with your custom design system."
+
+If the user confirms, copy `docs/design/shared-styles.css` to the scaffolded location.
+
+### Update Project Context
+
+Update `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### design-system
+blueprint: design-system
+installed_at: <date>
+creative_direction: "<north star name>"
+primary_color_hue: <oklch hue value>
+font_display: "<display font name>"
+font_body: "<body font name>"
+rounding: "<personality name>"
+artifacts:
+  - docs/design/design-system.md
+  - docs/design/shared-styles.css
+```
+
+### Append to Project Maintenance Skill
+
+Append to `<project>/.claude/skills/project-maintenance/SKILL.md`:
+
+```markdown
+### design-system maintenance
+- When design tokens change in docs/design/shared-styles.css, sync to config/tailwind-config/shared-styles.css (monorepo) or src/styles/shared-styles.css (single-repo)
+- When updating colors/shadows/radius: verify both light and dark mode tokens are updated together
+- When changing font families: ensure fonts are imported in the app layout (Google Fonts link or @font-face)
+- When adding new CSS variables: add corresponding entries to the @theme inline {} block
+- docs/design/design-system.md is the source of truth for design decisions — update it when making visual changes
+- Run /design-system to regenerate tokens after significant brand or audience changes
+```
+
+## Step 12: Summary
+
+Tell the user:
+
+- What was created — design system document (`docs/design/design-system.md`) and production CSS tokens (`docs/design/shared-styles.css`)
+- Key design decisions and why:
+  - Creative direction chosen and what it communicates
+  - Primary color hue and differentiation rationale
+  - Font pairing and why it fits the audience
+  - Rounding personality and what it signals
+  - Shadow/depth approach
+- **Font import instructions** — the exact Google Fonts `<link>` tag or `@import` URL to add to the app's `layout.tsx` or `<head>`:
+  ```
+  Add this to your layout.tsx <head> or app/layout.tsx:
+  <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet" />
+  ```
+- **Tailwind sync status** — whether tokens were synced to the scaffolded `shared-styles.css`, or whether the user needs to run `/scaffold-tailwind` first
+- **Suggested next steps:**
+  - If tailwind is not yet scaffolded: "Run `/scaffold-tailwind` — it will auto-detect your design tokens from `docs/design/shared-styles.css`"
+  - If tailwind is scaffolded but UI is not: "Run `/scaffold-ui` — components will use your custom design tokens"
+  - If both are already scaffolded: "Your design tokens are live. Components will pick up the new palette on next build."
+- **Suggested UI improvements** — based on the design system decisions, note any component-specific suggestions (e.g., "Your round personality would look great with pill-shaped badges — consider updating badge radius if you've already scaffolded UI")
+
+## Important Rules
+
+- **Every decision teaches WHY.** This is an educational process. The user is learning design thinking through each step. Don't just propose a color — explain color psychology, competitive context, and audience alignment. Don't just suggest a font — explain what its letterforms communicate and why that matters for this product.
+- **Accept and analyze screenshots.** The user may share existing work, competitor sites, or inspiration images. Analyze the visual language (palette, typography, spacing, depth, mood) and incorporate elements they respond to.
+- **Research fonts for real.** Use web search to find typefaces that match the product personality. Don't default to Inter for everything. Consider the product domain, audience expectations, and competitive landscape when recommending fonts.
+- **oklch format is mandatory.** All colors must use `oklch()` for perceptual uniformity and high-quality dark mode. Never use hex, rgb, or hsl. oklch provides uniform lightness perception across hues, which means a "50% lightness blue" and a "50% lightness yellow" actually look the same brightness — this is impossible with hsl.
+- **The CSS must be a drop-in replacement.** Same import structure, same `@custom-variant`, same `@theme inline {}` variable names, same `:root` and `.dark` token names, same `@layer base` rules as the tailwind-v4 template. Only the VALUES change. The `@theme {}` block adds extended tokens (shadows, easing, animations) that the template doesn't include.
+- **Dark mode is never skipped.** Every project gets both light and dark tokens. Dark mode is not optional — it's an accessibility and user preference requirement.
+- **The "How to Use" section in design-system.md is critical.** It bridges design decisions and development. Include actual Tailwind class examples for every token category, a quick-reference mapping table, and practical patterns like "to style a card, use `bg-card text-card-foreground rounded-lg shadow-sm border`."
+- **Component guidelines must be deep.** Don't just say "buttons use primary color." Specify padding, transition timing, hover behavior, disabled opacity, icon gap, size variants. A developer should be able to implement any component from the guidelines alone.
+- **Confirm at every major step.** Present colors, fonts, rounding, components, shadows, and animations each as a checkpoint. Wait for user confirmation before proceeding. Never rush through multiple decisions without feedback.
+- **Never fabricate brand assets.** If the user mentions an existing logo or brand, ask for specifics rather than assuming colors or fonts.
+- **Respect the Creative North Star.** Once chosen, reference it in every subsequent decision. "This shadow approach aligns with our 'Minimal Precision' direction because..." — it keeps the system coherent.