@withmata/blueprints 0.3.5 → 0.4.0

package/blueprints/discovery/design-system/BLUEPRINT.md

@@ -0,0 +1,1479 @@
+# Design System Blueprint — Visual Identity & Tailwind Tokens
+
+## Tier
+
+Discovery — produces documentation and actionable CSS, not application code.
+
+## Problem
+
+Technical founders scaffolding projects with the blueprint system get functional, accessible UI components — but every project looks identical. The Tailwind v4 blueprint provides a solid token structure (31 semantic color tokens, radius scale, font variables) but fills them with generic shadcn defaults. Without a deliberate design system, products lack visual identity: the colors don't reflect the brand, the typography doesn't match the audience, the spacing and rounding don't communicate the right personality. This blueprint defines a product's visual identity through a structured design conversation and outputs actual Tailwind CSS that replaces the defaults — so when UI components render, they look like YOUR product, not a template.
+
+## Status
+
+Complete.
+
+## Blueprint Dependencies
+
+| Blueprint | Type | Why |
+|-----------|------|-----|
+| `discovery/product-discovery` | recommended | Provides product type, customer archetypes, brand personality, and competitive landscape. The design system is strongest when grounded in validated product research. Without it, context is gathered conversationally. |
+| `discovery/marketing-copywriting` | recommended | Provides brand voice and tone. Helps align visual identity with how the product communicates — a playful brand voice shouldn't live inside a corporate-looking interface. |
+
+## Output
+
+```
+docs/
+└── design/
+    ├── design-system.md              # The "why" + "how to use" document
+    └── shared-styles.css             # Actual Tailwind v4 CSS tokens
+```
+
+The `shared-styles.css` is consumed by `/scaffold-tailwind` — if it exists when tailwind is scaffolded, it replaces the generic defaults. It follows the exact same CSS structure as the Tailwind v4 blueprint template: `@import` directives, `@custom-variant`, `@theme inline {}`, `@theme {}`, `:root {}`, `.dark {}`, and `@layer base {}`.
+
+**File naming rules:**
+- Output files go in `docs/design/` — this is the design system's source of truth
+- `shared-styles.css` is a real, valid CSS file — not pseudocode or documentation
+- `design-system.md` is the reference document explaining every decision
+- Do NOT create files beyond what's specified above
+
+---
+
+## Process
+
+This is a CONVERSATIONAL blueprint. Claude Code guides the user through a structured design session that produces a complete visual identity system and actionable Tailwind CSS tokens. The process adapts based on available context — product discovery docs, marketing copy docs, or direct conversation.
+
+### Phase 1: Context Gathering
+
+**Goal:** Understand the product, audience, and personality before making any visual decisions.
+
+Design without context produces decoration. Design with context produces identity. This phase maps everything known about the product into design-relevant inputs.
+
+#### Path 1: Product Docs Available (recommended)
+
+Auto-read `.project-context.md` + `docs/product/` + `docs/pages/` if available. Map them to design inputs:
+
+- **Product type** -> aesthetic direction
+  - SaaS dashboard -> structured, information-dense, calm backgrounds, clear hierarchy
+  - Consumer app -> bold personality, playful interactions, memorable colors
+  - Developer tool -> monospace accents, high contrast, minimal chrome, dark-mode-first
+  - Marketplace -> warm and trustworthy, card-heavy, image-friendly layouts
+  - Content/media -> editorial typography, generous whitespace, reading-optimized
+  - Enterprise B2B -> conservative palette, accessibility-first, dense but organized
+
+- **Primary archetype** -> audience sensibility
+  - Technical users -> appreciate subtlety, dislike gratuitous decoration, value density
+  - Non-technical users -> need visual cues for hierarchy, prefer clear affordances
+  - Enterprise buyers -> expect polish, trust conservative palettes, notice rough edges
+  - Startup users -> tolerate experimentation, respond to personality, forgive imperfection
+  - Young audience -> expects modern aesthetics, dark mode, bold color, animation
+  - Mature audience -> values clarity, readable typography, restrained color, stability
+
+- **Core pillars** -> what the design should communicate
+  - "Speed" -> sharp edges, minimal decoration, fast transitions, reduced visual weight
+  - "Trust" -> blue-shifted palette, consistent spacing, conservative rounding, ample whitespace
+  - "Simplicity" -> limited palette, generous spacing, large type, few shadows
+  - "Power" -> deep colors, dense layouts, detailed controls, visible complexity
+  - "Creativity" -> vibrant accents, asymmetry, unexpected color, playful rounding
+  - "Warmth" -> earth tones, soft rounding, friendly type, textured surfaces
+
+- **Brand voice** (from marketing copy if available) -> visual tone alignment
+  - Casual/playful voice -> rounded corners, warm colors, bouncy animations
+  - Professional/authoritative voice -> sharp geometry, cool colors, subtle transitions
+  - Technical/precise voice -> monospace accents, systematic spacing, minimal decoration
+  - Friendly/approachable voice -> medium rounding, warm neutrals, soft shadows
+
+After reading, summarize what you found:
+- "From your product discovery, I can see your product is a [type], your primary audience is [archetype description], and your core pillars are [X, Y, Z]. This tells me the design should communicate [qualities]. I'll use that as the foundation for creative direction."
+
+Then ask only what's missing:
+- Do you have any visual references — screenshots, sites you admire, or brands whose look you'd want to echo?
+- Are there any colors you know you want or know you want to avoid?
+- Is there an existing brand identity (logo, brand colors) this needs to work with?
+
+#### Path 2: No Product Docs Available
+
+Gather context conversationally. Ask about these four dimensions:
+
+**Product Identity:**
+- What does your product do in one sentence?
+- Who is your primary user? (Job title, company size, technical level)
+- What 3 words should someone use to describe your product's personality?
+- Is this a dashboard, consumer app, developer tool, marketplace, content site, or something else?
+
+**Brand Constraints:**
+- Do you have an existing logo or brand colors? (If yes, the design system works around them)
+- Are there brands whose visual style you admire? (This reveals aesthetic preferences faster than abstract questions)
+- Are there visual styles you actively dislike? (Equally valuable — narrows the space)
+
+**Audience Expectations:**
+- What tools/apps does your audience use daily? (Reveals their visual baseline)
+- Is your audience more Notion or more Bloomberg Terminal? More Linear or more Salesforce?
+- Are they using your product under pressure (speed matters) or reflectively (calm matters)?
+
+**Practical Needs:**
+- Does your product have a lot of data density? (Tables, charts, dashboards)
+- Is dark mode critical for your audience? (Developers, designers, night-use)
+- Will you have a marketing site that needs to look different from the app?
+
+**Push back when:**
+- Personality words are generic ("modern, clean, professional" — that describes everything)
+- No user context ("it's for everyone" — no product is for everyone)
+- Visual references are wildly contradictory (ask them to pick a direction)
+- They want to "look like Apple" without understanding what that means structurally
+
+---
+
+### Phase 2: Creative Direction
+
+**Goal:** Define a Creative North Star — a one-paragraph description of the visual identity that guides every subsequent decision.
+
+**Announce framework:** "I'm going to propose 2-3 creative directions based on what we've discussed. Each direction is a coherent visual personality — not just colors, but a whole way of looking and feeling. Your job is to pick one, or tell me which elements from different directions to combine. This becomes the Creative North Star that guides every decision in the design system."
+
+Propose 2-3 creative direction options based on context. Each direction includes:
+- **A name** — something evocative that captures the mood
+- **A North Star paragraph** — a vivid description of how the product should feel
+- **A mood** — 3-5 adjective clusters
+- **Why it fits** — specific reasoning tied to the product, audience, and pillars
+
+Example directions (adapt these to the actual product — never use these verbatim):
+
+**"Cognitive Sanctuary"**
+> A space that feels calm and expansive. Soft backgrounds with breathing room between elements. Muted violet tinted with warmth. Typography that's generous but never sprawling. Shadows that suggest depth without drama. The product feels like a quiet library with perfect lighting — focused, restful, and deeply functional.
+>
+> *Mood:* soft, breathing, violet-tinted, unhurried, precise
+> *Why:* Your audience is knowledge workers under constant cognitive pressure. The product should feel like relief — a sanctuary from noisy, demanding interfaces. The violet primary differentiates from the sea of blue SaaS tools while retaining professionalism.
+
+**"Precision Engine"**
+> Every pixel earns its place. Sharp edges, systematic spacing, and a navy-slate palette that communicates engineering discipline. Monospace accents in headers. Minimal shadows — hierarchy comes from weight and space, not decoration. The product feels like a precision instrument — powerful, exact, and confidence-inspiring.
+>
+> *Mood:* sharp, structured, navy/slate, disciplined, exact
+> *Why:* Your audience is technical — they notice details, respect systems, and distrust gratuitous decoration. The sharp aesthetic mirrors the precision they bring to their own work. Navy differentiates from the startup-blue default while feeling established.
+
+**"Warm Workshop"**
+> A product that feels handcrafted rather than manufactured. Rounded corners, amber and earth tones, friendly typography that invites exploration. Shadows are soft and warm. Interactions have a slight bounce — nothing stiff. The product feels like walking into a well-organized workshop where everything has its place but nothing feels sterile.
+>
+> *Mood:* rounded, amber/earth, friendly, handcrafted, inviting
+> *Why:* Your audience is non-technical and potentially intimidated by tools. Warmth reduces anxiety. The rounded, friendly aesthetic signals "this won't bite" — critical for adoption when users have a choice to avoid the tool entirely.
+
+**User picks one or mixes elements.** Document the final Creative North Star.
+
+**Explain WHY each direction fits (or doesn't fit) the product's audience.** This is educational — the user should understand how audience characteristics translate to visual decisions:
+- Enterprise audience -> conservative palette, because enterprise buyers equate visual conservatism with stability and reliability
+- Developer audience -> high information density, because developers are comfortable scanning dense UIs and frustrated by "dumbed-down" interfaces
+- Consumer audience -> memorable primary color, because consumer products need brand recognition in a crowded market
+- Young audience -> dark mode first, because younger users overwhelmingly prefer dark interfaces and associate them with modernity
+
+---
+
+### Phase 3: Color System
+
+**Goal:** Define every color token in the design system with oklch values, covering light mode, dark mode, and the reasoning behind each choice.
+
+**Announce framework:** "I'm going to build the full color system now. We'll start with the primary color — the single most important decision — and build outward from there. Every color in the system will be in oklch, which is a perceptually uniform color space. That means: consistent vibrancy across the spectrum, better dark mode translations, and gradients that don't go muddy in the middle."
+
+#### Primary Color Selection
+
+Research: what colors do competitors and similar products use? This matters because:
+- If every competitor uses blue, choosing blue makes you invisible in screenshots and reviews
+- If the space expects blue (finance, enterprise), deviating too far signals "unserious"
+- The right primary color balances audience expectation with competitive differentiation
+
+Propose the primary color based on:
+
+**Product personality:**
+- Blue (hue ~240-260) -> trust, reliability, calm — universal enterprise default for a reason, but also the most overused
+- Green (hue ~145-165) -> growth, health, nature, money — strong for fintech, health, sustainability
+- Violet/purple (hue ~280-310) -> creativity, premium, imagination — differentiates from blue while retaining professionalism
+- Orange (hue ~60-80) -> energy, warmth, urgency — bold and memorable, but can feel aggressive at high chroma
+- Rose/pink (hue ~0-20) -> warmth, empathy, care — strong for health, community, consumer
+- Teal (hue ~180-200) -> clarity, freshness, balance — modern alternative to blue
+- Amber/gold (hue ~85-100) -> warmth, craft, quality — premium without being cold
+
+**Audience expectations:**
+- Enterprise expects blue/gray/green — deviating requires confidence and brand strength
+- Consumer apps can be bold — personality matters more than convention
+- Developer tools trend toward violet, teal, or desaturated palettes
+- Health/wellness tends toward green, teal, or warm neutrals
+
+**Competitive differentiation:**
+- List the colors 3-5 direct competitors use
+- Identify the gap — which hues are underrepresented?
+- Propose a primary that occupies defensible visual territory
+
+#### Full Palette Definition
+
+Define all 31 semantic tokens in oklch. Explain the reasoning behind each group:
+
+**Core tokens (6):**
+- `--primary` + `--primary-foreground` — the brand color and text that sits on top of it
+- `--secondary` + `--secondary-foreground` — complement or neutral, for supporting elements
+- `--accent` + `--accent-foreground` — highlight color for emphasis, selection states, hover
+
+*Why these three tiers:* Primary carries brand identity. Secondary provides visual rest — elements that need to be visible but shouldn't compete with primary. Accent is the "notice me" color used sparingly for interactive states and highlights. Without this hierarchy, everything screams at the same volume and nothing stands out.
+
+**Feedback tokens (2):**
+- `--destructive` — error and danger states. Red-shifted (hue ~20-30) regardless of brand, because red=danger is a universal human association. Adjust lightness to ensure WCAG AA contrast against both light and dark backgrounds.
+
+*Why destructive is always red-adjacent:* Cultural universals in color semantics are rare, but red=danger/stop is one of them. Fighting this convention to match a brand palette creates confusion in critical moments (delete confirmations, error states, data loss warnings). Brand identity yields to safety signaling.
+
+**Neutral tokens (6):**
+- `--background` + `--foreground` — page-level backdrop and default text
+- `--muted` + `--muted-foreground` — subdued backgrounds and secondary text
+- `--card` + `--card-foreground` — surface for card components
+
+*Why separate card from background:* Surface hierarchy. When a card sits on the page background, it needs to be visually distinct. In light mode, cards are often the same white as the background (differentiated by shadow or border). In dark mode, cards are typically one step lighter than the background. Having separate tokens enables this without conditional logic.
+
+**Container tokens (4):**
+- `--popover` + `--popover-foreground` — floating elements (dropdowns, tooltips, popovers)
+- `--border` — lines separating elements
+- `--input` — input field borders (often slightly different from general borders)
+
+*Why popover is separate from card:* Popovers float above the page and need stronger visual separation. In dark mode, popovers are often lighter than cards to signal elevation. Separate tokens let you fine-tune this hierarchy.
+
+**Interactive tokens (1):**
+- `--ring` — focus ring color for keyboard navigation accessibility
+
+*Why ring exists as a separate token:* Focus rings serve a specific accessibility purpose — they must be visible against ANY background in the application. A dedicated token lets you choose a ring color with guaranteed contrast, independent of the brand palette.
+
+**Sidebar tokens (8):**
+- `--sidebar`, `--sidebar-foreground` — sidebar background and text
+- `--sidebar-primary`, `--sidebar-primary-foreground` — active item in sidebar
+- `--sidebar-accent`, `--sidebar-accent-foreground` — hover/selected states
+- `--sidebar-border` — sidebar divider lines
+- `--sidebar-ring` — focus ring within sidebar context
+
+*Why sidebar gets its own tokens:* Sidebars often have a different visual treatment than the main content area — slightly darker in light mode, slightly lighter in dark mode, or tinted with the brand color. Separate tokens enable sidebar-as-distinct-zone without CSS hacks.
+
+**Chart tokens (5):**
+- `--chart-1` through `--chart-5` — data visualization colors
+
+*Why 5 chart colors:* Most data visualizations use 3-5 series. Beyond 5, colors become hard to distinguish and the chart needs a different approach (labels, patterns). These 5 should be harmonized with the primary color but distinct enough for accessibility. A good approach: spread across 60-120 degrees of hue from the primary, maintaining consistent lightness and chroma.
+
+**Radius token (1):**
+- `--radius` — the base radius from which all other radii are calculated
+
+*Why a base radius:* The radius scale in `@theme inline` calculates `--radius-sm` through `--radius-4xl` from this single value. Changing `--radius` from `0.625rem` to `1rem` transforms the entire application from moderate to round. One variable, total control.
+
+#### Dark Mode Strategy
+
+Dark mode is NOT "just invert the lightness." Every color needs deliberate adjustment:
+
+**Background strategy:**
+- Dark background should be around L=0.12-0.18 in oklch — true black (L=0) causes eye strain and makes cards invisible
+- Card surfaces 1-2 steps lighter (L=0.18-0.24) for visible elevation
+- Popover surfaces another step lighter — floating elements must feel elevated
+
+**Color adjustments for dark mode:**
+- Primary color: reduce chroma slightly (saturated colors on dark backgrounds feel neon/electric), shift lightness up slightly for readability
+- Muted foreground: increase lightness to ~0.65-0.72 (gray text on dark needs more contrast than gray text on light)
+- Borders: use `oklch(1 0 0 / 10%)` (white at 10% opacity) for subtle, adaptive borders
+- Input borders: slightly higher opacity (~15%) so input fields are clearly delineated
+- Destructive: increase lightness (a dark red on a dark background is invisible)
+
+**What NOT to do in dark mode:**
+- Don't use pure black (`oklch(0 0 0)`) as background — it causes halation (text blooms) on OLED screens
+- Don't keep the same chroma as light mode — saturated colors on dark backgrounds cause visual vibration
+- Don't just flip lightness values — the relationship between surface layers matters more than individual values
+- Don't forget sidebar tokens — a dark sidebar on a dark background becomes invisible without separate values
+
+#### Surface Hierarchy Philosophy
+
+Explain the "paper layers" approach:
+
+```
+Layer 0: Page background     (--background)     — the base canvas
+Layer 1: Content regions      (--card)            — cards, panels, content areas
+Layer 2: Floating surfaces    (--popover)         — dropdowns, tooltips, modals
+Layer 3: Elevated elements    (sidebar, modals)   — highest visual priority
+```
+
+In light mode, surfaces differentiate through shadow (Layer 1 has shadow-sm, Layer 2 has shadow-lg). In dark mode, surfaces differentiate through lightness stepping (each layer is 2-4% lighter than the one below). This dual strategy ensures hierarchy is clear in both modes.
+
+#### Surface Layering Stack
+
+Document an explicit visual layering model showing which surface sits where:
+
+```
+Layer 0 (deepest):  background    — Page canvas, the base everything rests on
+Layer 1:            sidebar       — Persistent navigation surface  
+Layer 2:            card          — Content containers sitting on the page
+Layer 3:            popover       — Floating elements (dropdowns, tooltips, selects)
+Layer 4:            overlay       — Modal backdrop (semi-transparent)
+Layer 5 (highest):  dialog        — Modal content surface with maximum elevation
+```
+
+**Separation strategies** (in order of preference):
+1. **Tonal shifts** (preferred) — card on background creates natural contrast without explicit borders
+2. **Shadows** (for floating elements) — popovers get shadow-lg, modals get shadow-xl
+3. **Ghost borders** (accessibility fallback) — `ring-1 ring-foreground/10` when tonal shift alone isn't sufficient
+
+This layering model must be applied consistently — a component should never use shadow elevation that doesn't match its layer position.
+
+#### Evocative Color Naming
+
+Every color token gets THREE identifiers: a **descriptive name** (evocative, memorable), the **functional role** (what it's used for), and the **exact value** (oklch). This serves both humans (the name creates emotional association) and AI agents (the functional role + value enables precise application).
+
+Format in design-system.md:
+```
+| Token | Name | Light | Dark | Usage | Tailwind |
+|-------|------|-------|------|-------|----------|
+| primary | Deep Indigo | oklch(0.488 0.243 264) | oklch(0.42 0.18 266) | CTAs, links, active states | `bg-primary` |
+| muted | Whisper Gray | oklch(0.97 0 0) | oklch(0.269 0 0) | Subtle backgrounds, inactive areas | `bg-muted` |
+| destructive | Alert Terracotta | oklch(0.58 0.22 27) | oklch(0.704 0.191 22) | Errors, destructive actions | `bg-destructive` |
+```
+
+Format in shared-styles.css (as comments):
+```css
+--primary: oklch(0.488 0.243 264.376); /* Deep Indigo — CTAs, active states */
+--muted: oklch(0.97 0 0); /* Whisper Gray — subtle backgrounds */
+```
+
+Naming convention: always **evocative adjective(s) + color family**. Never generic ("blue", "red"). Examples:
+- "Deep Muted Teal-Navy" not "dark blue"
+- "Warm Barely-There Cream" not "off-white"  
+- "Alert Terracotta" not "red"
+
+---
+
+### Phase 4: Typography
+
+**Goal:** Select fonts that match the product personality and define the complete type scale.
+
+**Announce framework:** "Typography is the most impactful design decision after color — it's on every screen, in every component, and it sets the tone before anyone reads a word. I'm going to recommend a font pairing (display + body, optionally + mono) and define the complete type scale with Tailwind v4 theme variables."
+
+#### Font Research
+
+Search for actual typefaces based on product personality and audience. Consider:
+
+**Modern tech / SaaS:**
+- Geist — the new standard for tech products (Next.js's house font), geometric but humanist, excellent at small sizes
+- Satoshi — geometric sans with personality, stands out from Inter-sameness
+- Cabinet Grotesk — bold and opinionated for display, clean at body sizes
+- Inter — only recommend if it truly fits. It's the "safe choice" and makes everything look the same. When recommending Inter, be honest about why: "Inter is excellent technically but won't differentiate your product visually."
+
+**Editorial / content-heavy:**
+- Fraunces — a variable display serif with personality, great for headers paired with a clean sans body
+- Newsreader — designed for long-form reading, excellent x-height
+- Lora — workhorse serif with character, works at both display and body sizes
+- Crimson Pro — elegant and readable, strong for premium content
+
+**Friendly / approachable:**
+- Plus Jakarta Sans — friendly geometry with good readability, slightly rounded terminals
+- Nunito — rounded sans with warmth, approachable without being childish
+- Quicksand — geometric with rounded terminals, distinctly friendly
+- DM Sans — the structured friendly option, geometric but warm
+
+**Premium / luxury:**
+- Cormorant — a display serif with dramatic contrast, best paired with a simple sans
+- Playfair Display — high-contrast serif, unmistakably editorial and premium
+- EB Garamond — classic elegance, works at body sizes unlike most display serifs
+
+**Developer / technical:**
+- JetBrains Mono — excellent code font with ligatures, designed for extended reading
+- Fira Code — the programmer favorite, with or without ligatures
+- Berkeley Mono — premium monospace with character (not free)
+- Geist Mono — pairs perfectly with Geist Sans (obviously)
+
+#### Font Pairing Principles
+
+Explain WHY the recommended pairing works:
+
+- **Contrast creates interest** — pair a characterful display font with a neutral body font (or vice versa). Two fonts with similar personality feel redundant; two fonts with different personality create visual rhythm.
+- **Shared structure creates harmony** — fonts should share structural DNA (x-height, stroke weight, proportions) even when their personality differs. A geometric display + geometric body feels more cohesive than geometric display + humanist body.
+- **Body font carries the workload** — the body font appears in most UI text, so it must be readable at 14-16px, have a good set of weights (400, 500, 600, 700 minimum), and look clean at small sizes. Display fonts can be more expressive because they're used at larger sizes.
+- **Mono is optional but valuable** — if the product shows any code, data, or tabular numbers, a dedicated mono font prevents the jarring fallback to system monospace. The mono font should share visual weight with the body font.
+
+Propose the pairing with reasoning:
+- "I recommend [Display] for headlines and [Body] for interface text because [specific reasoning tied to product personality and audience]. The [Display] font's [specific characteristic] communicates [quality], while [Body]'s [characteristic] ensures [practical benefit]."
+
+#### Type Scale Definition
+
+Define the complete scale using Tailwind v4 `@theme` variables. The scale maps to Tailwind's `text-*` utilities:
+
+| Token | Default Value | Line Height | Usage | Tailwind Class |
+|-------|---------------|-------------|-------|----------------|
+| `--text-xs` | 0.75rem (12px) | 1rem | Fine print, captions, badges | `text-xs` |
+| `--text-sm` | 0.875rem (14px) | 1.25rem | Secondary text, form labels, helper text | `text-sm` |
+| `--text-base` | 1rem (16px) | 1.5rem | Body text, default paragraph | `text-base` |
+| `--text-lg` | 1.125rem (18px) | 1.75rem | Emphasized body, section leads | `text-lg` |
+| `--text-xl` | 1.25rem (20px) | 1.75rem | Card titles, small headings | `text-xl` |
+| `--text-2xl` | 1.5rem (24px) | 2rem | Section headings | `text-2xl` |
+| `--text-3xl` | 1.875rem (30px) | 2.25rem | Page headings | `text-3xl` |
+| `--text-4xl` | 2.25rem (36px) | 2.5rem | Hero secondary | `text-4xl` |
+| `--text-5xl` | 3rem (48px) | 1 | Hero headings | `text-5xl` |
+| `--text-6xl` | 3.75rem (60px) | 1 | Display/marketing | `text-6xl` |
+| `--text-7xl` | 4.5rem (72px) | 1 | Large display | `text-7xl` |
+| `--text-8xl` | 6rem (96px) | 1 | Statement display | `text-8xl` |
+| `--text-9xl` | 8rem (128px) | 1 | Extreme display | `text-9xl` |
+
+Adjust the scale based on product needs:
+- Data-dense products may tighten the scale (smaller increments) to fit more hierarchy into less space
+- Marketing-heavy products may stretch the scale (larger display sizes) for dramatic headings
+- Mobile-first products should verify the scale at 320px viewport width
+
+**Weight scale:**
+
+| Token | Value | Usage | Tailwind Class |
+|-------|-------|-------|----------------|
+| `--font-weight-thin` | 100 | Decorative display only | `font-thin` |
+| `--font-weight-extralight` | 200 | Large display text | `font-extralight` |
+| `--font-weight-light` | 300 | De-emphasized text | `font-light` |
+| `--font-weight-normal` | 400 | Body text default | `font-normal` |
+| `--font-weight-medium` | 500 | Labels, navigation items | `font-medium` |
+| `--font-weight-semibold` | 600 | Headings, button text | `font-semibold` |
+| `--font-weight-bold` | 700 | Strong emphasis, primary headings | `font-bold` |
+| `--font-weight-extrabold` | 800 | Hero headings | `font-extrabold` |
+| `--font-weight-black` | 900 | Display/marketing only | `font-black` |
+
+**Tracking (letter spacing):**
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--tracking-tighter` | -0.05em | Large display headings (tighten at large sizes) |
+| `--tracking-tight` | -0.025em | Headings, card titles |
+| `--tracking-normal` | 0em | Body text |
+| `--tracking-wide` | 0.025em | Uppercase labels, badges |
+| `--tracking-wider` | 0.05em | Small uppercase text |
+| `--tracking-widest` | 0.1em | Decorative uppercase, overlines |
+
+**Leading (line height):**
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--leading-none` | 1 | Display headings (tight) |
+| `--leading-tight` | 1.25 | Headings, short text |
+| `--leading-snug` | 1.375 | Cards, compact layouts |
+| `--leading-normal` | 1.5 | Body text default |
+| `--leading-relaxed` | 1.625 | Long-form reading |
+| `--leading-loose` | 2 | Wide-set text, open layouts |
+
+---
+
+### Phase 5: Spacing, Rounding & Borders
+
+**Goal:** Define the spatial personality — how much breathing room, how round the corners, and when lines appear.
+
+#### Base Spacing Unit
+
+The default `--spacing` in Tailwind v4 is `0.25rem` (4px). This means `p-4` = `1rem` (16px), `gap-6` = `1.5rem` (24px), etc. Adjusting `--spacing` scales the entire system:
+
+- `0.25rem` (default) — standard density, works for most applications
+- `0.2rem` — tighter, for data-dense dashboards where screen real estate matters
+- `0.3rem` — looser, for marketing/content sites where breathing room is the priority
+
+*Why base spacing matters:* When every spacing value derives from one unit, the system stays proportional as it scales. Changing `--spacing` from 0.25rem to 0.3rem increases whitespace everywhere uniformly — you don't get the inconsistency of ad-hoc padding adjustments where some elements feel cramped while others feel loose.
+
+#### Rounding Personality
+
+Define the base `--radius` and explain the personality it creates:
+
+**Sharp (--radius: 0-0.25rem / 0-4px):**
+- Components: `rounded-sm` (2px) for buttons, `rounded-md` (4px) for cards, `rounded-none` for tables
+- Personality: corporate, serious, editorial, architectural
+- Best for: enterprise B2B, fintech, legal, media
+- Why: sharp corners communicate precision and formality. They say "we mean business" — there's no softness to hide behind. Editorial design has used sharp corners for centuries because they create clean grid alignment.
+
+**Moderate (--radius: 0.375-0.625rem / 6-10px):**
+- Components: `rounded-md` (6px) for buttons, `rounded-lg` (8px) for cards, `rounded-xl` (12px) for modals
+- Personality: balanced, professional, contemporary, approachable-but-serious
+- Best for: SaaS, productivity tools, developer platforms, general B2B
+- Why: the sweet spot — professional enough for enterprise, friendly enough for startups. This is the default for a reason: it works for most products without making a strong statement in either direction.
+
+**Round (--radius: 0.75-1rem / 12-16px):**
+- Components: `rounded-xl` (12px) for buttons, `rounded-2xl` (16px) for cards, `rounded-3xl` (20px) for modals
+- Personality: friendly, modern, approachable, consumer
+- Best for: consumer apps, social platforms, health/wellness, education
+- Why: rounded corners reduce visual tension. Psychologically, humans prefer curved shapes over angular ones (studies by Bar & Neta, 2006) because sharp corners trigger a threat response. Rounded corners signal safety and approachability.
+
+**Full (--radius: 1.25-1.5rem / 20-24px, pill shapes for buttons):**
+- Components: `rounded-full` for buttons, `rounded-3xl` (24px) for cards, `rounded-4xl` for containers
+- Personality: playful, bold, consumer, distinctive
+- Best for: lifestyle apps, creative tools, social apps targeting younger audiences
+- Why: pill-shaped buttons and aggressively rounded cards are a strong visual statement. This says "we're different" — which is powerful when intentional but distracting when accidental. Only recommend for products where visual personality is a competitive advantage.
+
+#### Component-Specific Radius Mapping
+
+Not every component uses the same radius. Define which components get which:
+
+| Component | Sharp | Moderate | Round | Full |
+|-----------|-------|----------|-------|------|
+| Buttons | `rounded-sm` | `rounded-lg` | `rounded-xl` | `rounded-full` |
+| Input fields | `rounded-sm` | `rounded-md` | `rounded-lg` | `rounded-xl` |
+| Cards | `rounded-md` | `rounded-lg` | `rounded-2xl` | `rounded-3xl` |
+| Modals/Dialogs | `rounded-md` | `rounded-xl` | `rounded-2xl` | `rounded-3xl` |
+| Badges/Tags | `rounded-sm` | `rounded-md` | `rounded-full` | `rounded-full` |
+| Avatars | `rounded-md` | `rounded-full` | `rounded-full` | `rounded-full` |
+| Tooltips | `rounded-sm` | `rounded-md` | `rounded-lg` | `rounded-xl` |
+| Dropdowns | `rounded-md` | `rounded-lg` | `rounded-xl` | `rounded-2xl` |
+
+*Why components scale differently:* Buttons and badges are small — aggressive rounding at small sizes creates pill shapes naturally. Cards and modals are large — the same radius value that looks rounded on a button looks barely curved on a card. The mapping ensures consistent perceived roundness across different-sized components.
+
+#### Border Philosophy
+
+Borders are the most overused visual element in UI design. Every line on screen competes for attention with the content it's supposed to frame. Define the product's border strategy:
+
+**"No-line" approach (Google Material Design / Apple approach):**
+- Boundaries between elements come from tonal shifts (background color differences) and shadows, not lines
+- Cards separate from background through elevation (shadow) or surface color difference
+- Sections separate through whitespace and heading hierarchy
+- When to use: clean, modern, content-focused interfaces
+- Why: lines are visual noise. Every border is a distraction from content. When you remove borders, you force the design to use spacing and color to create hierarchy — which results in a cleaner, more intentional layout.
+
+**"Intentional lines" approach (GitHub / Linear approach):**
+- Borders appear only when they serve a specific purpose: separating interactive elements (table rows), creating containment (input fields), or providing a visual stop (section dividers)
+- Border color is very subtle (low opacity) to avoid competing with content
+- When to use: information-dense interfaces where spatial separation alone isn't sufficient
+- Why: in data-dense UIs, removing all borders creates visual soup — elements blend together. Intentional borders provide just enough structure without the visual weight of a fully-bordered design.
+
+**"Ghost border" fallback for accessibility:**
+- Even in no-line designs, add a very low opacity outline (2-3%) for accessibility
+- This ensures that color-blind users and those with contrast sensitivity can still perceive boundaries
+- Implementation: `border: 1px solid oklch(0 0 0 / 3%)` (light mode) or `border: 1px solid oklch(1 0 0 / 5%)` (dark mode)
+- Why: the WCAG standard for non-text contrast (1.4.11) requires a 3:1 ratio for UI component boundaries. Ghost borders provide this without visible lines for most users.
+
+---
+
+### Phase 5.5: Layout & Responsive Behavior
+
+Define how the design system adapts across viewport sizes.
+
+**Grid System:**
+- Container max-width (typically 1280px or 1440px for desktop)
+- Column count (12-column for flexibility, or simpler 4/8 for constrained layouts)
+- Gutter width (derived from base spacing unit — typically 1rem or 1.5rem)
+- Content max-width for readability (65ch for prose, full-width for dashboards)
+
+**Breakpoints:**
+Define responsive thresholds aligned with Tailwind's defaults or custom:
+- **Mobile:** < 640px (`sm`) — single column, full-width elements, stacked navigation
+- **Tablet:** 640px – 1024px (`sm` to `lg`) — 2-column grids, sidebar may collapse
+- **Desktop:** 1024px – 1440px (`lg` to `2xl`) — full layout, sidebar expanded, multi-column
+- **Large:** > 1440px — content centered, max-width constrains, generous margins
+
+**Touch Targets:**
+- Minimum 44x44px (WCAG AA), recommended 48x48px
+- Interactive elements must have sufficient spacing to prevent mis-taps
+- On mobile, CTAs should be full-width and thumb-reachable
+
+**Responsive Component Behaviors:**
+Document how each major component type adapts:
+
+| Component | Mobile | Tablet | Desktop |
+|-----------|--------|--------|---------|
+| Sidebar | Hidden (hamburger menu) | Icon-only collapsed | Full expanded |
+| Modals/Dialogs | Full-screen with slide-up | Centered, max-w-lg | Centered, max-w-md/lg |
+| Navigation | Bottom tab bar or hamburger | Horizontal, condensed | Full horizontal with labels |
+| Card Grid | 1 column, full width | 2 columns | 3-4 columns |
+| Tables | Horizontal scroll or card view | Horizontal scroll | Full table |
+| CTAs | Full width, sticky bottom | Auto width | Auto width |
+| Forms | Single column, stacked | Single column | Optional 2-column for short fields |
+| Page Header | Stacked (title above action) | Side-by-side | Side-by-side |
+
+**Whitespace Scaling:**
+- Section margins increase with viewport: 2rem (mobile) → 4rem (tablet) → 6-8rem (desktop)
+- Card padding scales: p-4 (mobile) → p-6 (desktop)
+- Typography may shift: text-sm body (mobile) → text-base (desktop)
+
+---
+
+### Phase 6: Component Styling Guidelines
+
+**Goal:** Define specific visual treatment for every major component type, ensuring consistency and eliminating "how should this look?" decisions during development.
+
+**Announce framework:** "Now I'll define how each component type should look in your design system. This goes deeper than just colors and rounding — I'll specify hover states, focus behavior, spacing conventions, and how variants relate to each other. These guidelines ensure that anyone building components produces consistent results without needing to reference screenshots."
+
+#### Buttons
+
+Buttons are the primary interactive element. Their styling communicates interactivity, hierarchy, and state.
+
+**Primary button:**
+- Background: `bg-primary`, text: `text-primary-foreground`
+- Gradient vs flat? Decision based on personality:
+  - Flat (single color) -> clean, professional, developer-friendly
+  - Subtle gradient (2-3% lightness shift top to bottom) -> adds depth without flashiness
+  - Bold gradient (cross-hue, e.g., primary to accent) -> playful, consumer, high-energy
+- Hover: darken background 8-12% (e.g., `bg-primary/90` or adjust oklch lightness)
+- Active (pressed): darken further, slight scale reduction (`scale-[0.98]`)
+- Focus: visible focus ring using `--ring` token, 2px offset
+- Disabled: 50% opacity, `cursor-not-allowed`
+
+**Secondary button:**
+- Background: `bg-secondary`, text: `text-secondary-foreground`
+- Lower visual weight than primary — it should clearly be "not the main action"
+- Hover: subtle background shift toward primary tint
+- Border: optional 1px border for definition in no-line designs
+
+**Ghost/outline button:**
+- Background: transparent, border: 1px `border-border`
+- Hover: `bg-accent` background fill (ghost becomes solid on hover)
+- This is the "de-emphasized" action — use for secondary or tertiary actions
+- The hover state transition should be fast (100-150ms) so it feels responsive
+
+**Destructive button:**
+- Background: `bg-destructive`, text: white
+- Reserve for irreversible actions (delete, remove, cancel subscription)
+- Never place next to a primary button at the same visual weight — the destructive action should be visually subordinate unless it IS the primary action (e.g., a delete confirmation modal)
+
+**Size scale:**
+
+| Size | Padding | Height | Font Size | Icon Size |
+|------|---------|--------|-----------|-----------|
+| sm | `px-3 py-1.5` | 32px | `text-sm` | 16px |
+| default | `px-4 py-2` | 40px | `text-sm` | 18px |
+| lg | `px-6 py-2.5` | 44px | `text-base` | 20px |
+| icon | `p-2` | 40px | — | 20px |
+
+**Icon alignment:** icons in buttons sit 8px from text (gap-2). Left-aligned icons are for actions ("Save", "Download"). Right-aligned icons are for navigation ("Next", "Open"). Icon-only buttons must have an `aria-label`.
+
+#### Cards
+
+Cards are the primary container for grouped content.
+
+- Surface: `bg-card text-card-foreground`
+- Shadow vs border: based on border philosophy (see Phase 5)
+  - Shadow approach: `shadow-sm` for default, `shadow-md` on hover (if interactive)
+  - Border approach: `border border-border` with `rounded-lg`
+  - Tonal approach: card is a step lighter/darker than background, no shadow or border
+- Rounding: use the component-specific radius from Phase 5
+- Padding: `p-6` default (24px). Header/content/footer: `px-6 py-4` for each section
+- Interactive cards: add `hover:shadow-md transition-shadow` and `cursor-pointer`
+- Header: `font-semibold text-lg` with `pb-2` or a bottom border for separation
+- Footer: `pt-4` with optional top border, typically contains actions aligned right
+
+#### Inputs
+
+Inputs are used constantly — their styling affects the entire feel of forms.
+
+- **Fill vs outline style:**
+  - Outline (default): `border border-input bg-transparent` — clean, traditional, works everywhere
+  - Fill: `bg-muted border-transparent` — modern, reduces visual noise, works well when there are many fields
+  - Choice depends on form density: outline for 1-3 fields, fill for long forms
+
+- **Focus state:** the focus state is THE most important input styling decision. It tells users where they are.
+  - Ring approach: `focus:ring-2 ring-ring ring-offset-2` — clear, accessible, standard
+  - Border glow: `focus:border-primary focus:shadow-[0_0_0_3px_var(--primary)/15%]` — softer, modern
+  - Background shift: `focus:bg-accent` — subtle, minimal, clean
+
+- **Label placement:**
+  - Above (default): label sits above the input with `mb-1.5` spacing. Best for most forms.
+  - Floating: label inside the input that floats up on focus. Visually elegant but creates accessibility issues — only use with careful ARIA labeling.
+  - Inline: label and input on the same line. Only for very short forms (login, search).
+
+- **Error state:**
+  - Border: `border-destructive` replaces the normal border
+  - Text: error message below in `text-destructive text-sm`
+  - Background tint: optional `bg-destructive/5` for emphasis on the field itself
+  - Icon: optional error icon inside the input (right-aligned)
+
+- **Placeholder:** `text-muted-foreground` — never use placeholder as a label replacement. Placeholder text disappears on input, which means users lose context after typing.
+
+#### Modals/Dialogs
+
+Modals interrupt the user's flow — they should feel important but not aggressive.
+
+- **Backdrop:** `bg-black/50` with optional `backdrop-blur-sm`
+  - Higher blur (backdrop-blur-md) for a frosted glass effect — modern, premium
+  - Lower opacity (bg-black/30) for less interruption — maintains context awareness
+  - The backdrop click-to-dismiss behavior should match the border philosophy: dismissive (casual) vs protected (enterprise)
+
+- **Shadow depth:** `shadow-xl` or `shadow-2xl` — modals are the highest elevation surface
+- **Max width:** `max-w-md` (448px) for confirmations, `max-w-lg` (512px) for forms, `max-w-2xl` (672px) for complex content
+- **Padding:** `p-6` for content, `px-6 py-4` for header and footer
+- **Entry animation:** fade-in + subtle scale (0.95 -> 1.0) over 200ms with ease-out
+- **Exit animation:** fade-out over 150ms — exits should be faster than entrances
+
+#### Navigation/Sidebar
+
+Navigation sets the persistent visual frame for the entire application.
+
+- **Active state indicator:**
+  - Background fill: `bg-sidebar-accent text-sidebar-accent-foreground` — clear, works everywhere
+  - Left border: `border-l-2 border-sidebar-primary` — minimal, editorial
+  - Icon fill: active icon uses `text-sidebar-primary`, inactive uses `text-sidebar-foreground/70`
+  - Which to use depends on the sidebar width and information density
+
+- **Collapsed behavior:**
+  - Icons only with tooltips on hover
+  - Active state still visible (icon color or background dot)
+  - Transition: 200ms ease for width change
+
+- **Section headers:** `text-xs font-medium uppercase tracking-wide text-sidebar-foreground/50` — section headers should recede, not compete with navigation items
+
+- **Hover state:** `bg-sidebar-accent/50` — a lighter version of the active background, signaling interactivity without implying selection
+
+#### Badges/Tags
+
+Small visual indicators with multiple semantic variants.
+
+- Default: `bg-secondary text-secondary-foreground` — neutral, informational
+- Primary: `bg-primary/10 text-primary` — branded, highlighted (uses transparent primary background so it adapts to surface)
+- Destructive: `bg-destructive/10 text-destructive` — errors, overdue items
+- Outline: `border border-border bg-transparent` — subtle, minimal
+- Size: `px-2.5 py-0.5 text-xs` — badges should be compact
+- Rounding: follow the component-specific radius from Phase 5
+
+#### Tables
+
+Data presentation with clear hierarchy and comfortable density.
+
+- **Header row:** `bg-muted/50 font-medium text-muted-foreground text-sm` — headers should recede visually. They're labels, not content.
+- **Row hover:** `hover:bg-muted/30` — subtle background shift confirms the row the user is looking at
+- **Cell padding:** `px-4 py-3` — enough breathing room for readability without wasting space
+- **Border strategy:**
+  - Full grid: every cell bordered — traditional, high-density, data-focused
+  - Rows only: horizontal borders between rows — cleaner, modern, easier to scan
+  - Minimal: no borders, rows separated by subtle background alternation (`even:bg-muted/20`) — cleanest, works when data is sparse
+  - Choose based on data density: more data = more structure needed
+
+#### Forms
+
+Form layouts combining inputs, labels, and error states into coherent groups.
+
+- **Field group spacing:** `space-y-4` (16px) between fields — enough separation for clarity without excessive scrolling
+- **Section spacing:** `space-y-8` (32px) between form sections — clear grouping
+- **Error state flow:** error messages appear below the field with `mt-1.5 text-sm text-destructive`, pushing content down (not overlaying)
+- **Help text:** `mt-1.5 text-sm text-muted-foreground` — same position as errors but neutral color
+- **Required indicator:** red asterisk after label text `<span class="text-destructive">*</span>` — universal convention, don't reinvent this
+- **Submit button placement:** right-aligned for single-column forms, full-width for mobile or card-embedded forms
+
+---
+
+### Phase 7: Shadows & Depth
+
+**Goal:** Define the shadow scale that creates visual hierarchy — the perception of elements floating above or below others.
+
+**Announce framework:** "Shadows create the illusion of depth. Used well, they communicate hierarchy instantly — users know a dropdown floats above a card without thinking about it. I'll define the full shadow scale with values tuned to your design personality."
+
+#### Shadow Scale
+
+Define `--shadow-xs` through `--shadow-2xl` in the `@theme {}` block:
+
+**Ambient/diffused style (modern, subtle):**
+```css
+--shadow-xs: 0 1px 2px oklch(0 0 0 / 3%);
+--shadow-sm: 0 1px 3px oklch(0 0 0 / 5%), 0 1px 2px oklch(0 0 0 / 3%);
+--shadow: 0 4px 6px oklch(0 0 0 / 5%), 0 2px 4px oklch(0 0 0 / 3%);
+--shadow-md: 0 6px 10px oklch(0 0 0 / 5%), 0 2px 4px oklch(0 0 0 / 2%);
+--shadow-lg: 0 10px 15px oklch(0 0 0 / 5%), 0 4px 6px oklch(0 0 0 / 3%);
+--shadow-xl: 0 20px 25px oklch(0 0 0 / 5%), 0 8px 10px oklch(0 0 0 / 2%);
+--shadow-2xl: 0 25px 50px oklch(0 0 0 / 12%);
+```
+*When to use:* clean, professional, minimal designs. Low-opacity, large-spread shadows feel airy and modern.
+
+**Sharp/dramatic style (bold, high-contrast):**
+```css
+--shadow-xs: 0 1px 2px oklch(0 0 0 / 8%);
+--shadow-sm: 0 2px 4px oklch(0 0 0 / 10%);
+--shadow: 0 4px 8px oklch(0 0 0 / 12%);
+--shadow-md: 0 6px 12px oklch(0 0 0 / 12%);
+--shadow-lg: 0 12px 24px oklch(0 0 0 / 15%);
+--shadow-xl: 0 20px 40px oklch(0 0 0 / 15%);
+--shadow-2xl: 0 25px 50px oklch(0 0 0 / 25%);
+```
+*When to use:* bold, high-personality designs. Higher opacity and tighter spread create more defined edges and stronger depth perception.
+
+**Brand-tinted style (premium, distinctive):**
+- Replace `oklch(0 0 0 / N%)` with tinted shadows using the primary hue at very low chroma
+- Example: `oklch(0.3 0.02 264 / 8%)` instead of pure black
+- *When to use:* premium products where every detail should reinforce the brand. The tint is subtle — most users won't consciously notice it, but it contributes to a cohesive feeling.
+
+#### Shadow Usage Guide
+
+| Shadow | Usage | Example Components |
+|--------|-------|-------------------|
+| `shadow-xs` | Barely perceptible depth | Inline buttons, tags pressed into surface |
+| `shadow-sm` | Default card elevation | Cards at rest, container sections |
+| `shadow` | Default interactive elevation | Buttons, input focus glow |
+| `shadow-md` | Moderate emphasis | Hovered cards, active dropdowns |
+| `shadow-lg` | Floating elements | Dropdown menus, popovers, tooltips |
+| `shadow-xl` | High-priority floating | Modals, command palettes |
+| `shadow-2xl` | Maximum emphasis | Full-page overlays, onboarding modals |
+
+#### Inset Shadows
+
+For elements that feel pressed into the surface (input fields, embedded panels):
+```css
+--shadow-inset: inset 0 2px 4px oklch(0 0 0 / 5%);
+```
+*Use sparingly.* Inset shadows create a "pressed" effect that works for input fields in fill style but looks odd on most other elements.
+
+#### Glassmorphism Recipe (if applicable)
+
+For products with a modern, layered aesthetic:
+```css
+backdrop-filter: blur(12px);
+background: oklch(1 0 0 / 70%); /* light mode */
+background: oklch(0.15 0 0 / 70%); /* dark mode */
+border: 1px solid oklch(1 0 0 / 10%);
+```
+*When to use:* sparingly. Glassmorphism is visually striking but computationally expensive (backdrop-blur triggers compositing layers) and can create readability issues. Best for navigation bars, sidebars, or floating toolbars — NOT for content-heavy cards or modal backdrops.
+
+---
+
+### Phase 8: Animation & Motion
+
+**Goal:** Define how things move — transition timing, easing curves, and keyframe animations that match the product personality.
+
+**Announce framework:** "Motion is the personality of your interface in action. Fast, sharp transitions feel efficient and precise. Slow, bouncy transitions feel playful and friendly. I'll define the timing scale, easing curves, and custom animations, all as Tailwind @theme variables and @keyframes."
+
+#### Transition Duration Scale
+
+Define via `@theme {}`:
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--duration-fast` | 100ms | Hover states, color changes, micro-interactions |
+| `--duration-normal` | 200ms | Focus states, small element transitions, toggles |
+| `--duration-slow` | 300ms | Modal entrances, sidebar expansion, page transitions |
+| `--duration-slower` | 500ms | Complex multi-step animations, onboarding sequences |
+
+*Why these values:* Human perception research shows that transitions under 100ms feel instant, 100-300ms feel responsive, and over 300ms feel deliberate. The scale maps to interaction urgency: hover states need instant feedback (fast), modals can take a beat to establish presence (slow).
+
+#### Custom Easing Curves
+
+```css
+--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+--ease-out: cubic-bezier(0, 0, 0.2, 1);
+--ease-in: cubic-bezier(0.4, 0, 1, 1);
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
+--ease-smooth: cubic-bezier(0.25, 0.1, 0.25, 1);
+```
+
+| Curve | Personality | When to Use |
+|-------|-------------|-------------|
+| `ease-out` | Professional, confident | Entrances — elements arrive confidently and settle |
+| `ease-in-out` | Balanced, smooth | State transitions — toggles, color changes |
+| `ease-in` | Departing, retreating | Exits — elements accelerate away (rarely used alone) |
+| `ease-spring` | Playful, energetic | Fun interactions — toggle switches, badge appearance (only if personality fits) |
+| `ease-bounce` | Very playful, attention-grabbing | Notification badges, celebration moments (use very sparingly) |
+| `ease-smooth` | Subtle, refined | Default for most transitions — unnoticeable in the best way |
+
+#### Custom @keyframes
+
+Define these in the `@theme {}` block:
+
+```css
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes fade-out {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+
+@keyframes slide-up {
+  from { transform: translateY(8px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+@keyframes slide-down {
+  from { transform: translateY(-8px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+@keyframes slide-in-from-left {
+  from { transform: translateX(-100%); }
+  to { transform: translateX(0); }
+}
+
+@keyframes slide-in-from-right {
+  from { transform: translateX(100%); }
+  to { transform: translateX(0); }
+}
+
+@keyframes slide-in-from-top {
+  from { transform: translateY(-100%); }
+  to { transform: translateY(0); }
+}
+
+@keyframes slide-in-from-bottom {
+  from { transform: translateY(100%); }
+  to { transform: translateY(0); }
+}
+
+@keyframes scale-in {
+  from { transform: scale(0.95); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+```
+
+Map to animation utilities:
+
+| Animation | Keyframe | Duration | Easing | Usage |
+|-----------|----------|----------|--------|-------|
+| `animate-fade-in` | `fade-in` | 200ms | ease-out | General element appearance |
+| `animate-fade-out` | `fade-out` | 150ms | ease-in | General element disappearance |
+| `animate-slide-up` | `slide-up` | 200ms | ease-out | Dropdown menus, tooltips from below |
+| `animate-slide-down` | `slide-down` | 200ms | ease-out | Dropdown menus, tooltips from above |
+| `animate-scale-in` | `scale-in` | 200ms | ease-out | Modals, popovers, dialog entrances |
+| `animate-spin` | `spin` | 1000ms | linear | Loading spinners |
+
+#### What Animates vs What Doesn't
+
+**Always animate:**
+- Modal/dialog entrances and exits
+- Dropdown/popover appearance
+- Focus ring transitions
+- Hover state changes on interactive elements
+- Sidebar collapse/expand
+- Toast/notification entrances
+
+**Never animate:**
+- Page load (content should render instantly, not fade in piecemeal)
+- Scrolling behavior (native scroll is always better than JS scroll animations)
+- Text content changes (changing text should be instant, not crossfade)
+- Error state appearance (errors need immediate attention, not a leisurely fade-in)
+
+**Conditionally animate (based on product personality):**
+- Card hover elevation changes (subtle lift effect)
+- Button press feedback (scale down on click)
+- Navigation transitions between routes
+- Data visualization entrance (chart bars growing, lines drawing)
+
+#### Motion Reduction Strategy
+
+Always respect `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+*Why this matters:* Motion sensitivity affects approximately 35% of adults to some degree. Vestibular disorders, migraine sensitivity, and other conditions make animation physically uncomfortable. The `prefers-reduced-motion` media query respects the user's OS-level setting. Setting durations to near-zero (not zero) ensures completion callbacks still fire.
+
+---
+
+### Phase 9: Generate Outputs
+
+**Goal:** Produce the two deliverables — the design system document and the actual CSS file.
+
+#### Step 1: Write `docs/design/design-system.md`
+
+The comprehensive reference document. Follows the structure defined in the Output Format section below. Every design decision is annotated with reasoning — this document is both a reference and a teaching tool.
+
+#### Step 2: Write `docs/design/shared-styles.css`
+
+The actual Tailwind v4 CSS file. Must match the template structure EXACTLY:
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "tailwind-scrollbar-hide/v4";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  /* Color token -> Tailwind utility mappings */
+  /* Radius scale */
+  /* Font family variables */
+}
+
+@theme {
+  /* Shadow scale */
+  /* Easing curves */
+  /* Animation definitions */
+  /* Typography overrides (if any) */
+  /* @keyframes */
+}
+
+:root {
+  /* All light mode CSS variables in oklch */
+}
+
+.dark {
+  /* All dark mode CSS variables in oklch */
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+This structure is non-negotiable — it must be a drop-in replacement for the Tailwind v4 blueprint's generic `shared-styles.css`.
+
+#### Step 3: Update `.project-context.md`
+
+Append the design system entry under `## Installed Blueprints` (or `## Product Discovery` if that section is more appropriate).
+
+#### Step 4: Offer Sync (if applicable)
+
+If `config/tailwind-config/shared-styles.css` (monorepo) or `src/styles/shared-styles.css` (single-repo) already exists from a previous tailwind scaffold, offer to sync immediately:
+
+"I see you already have a tailwind config scaffolded. Would you like me to replace the generic tokens with your new design system tokens now? This will immediately update how all your components look."
+
+#### Step 5: Suggest Component Improvements
+
+Based on the design system decisions, suggest specific improvements to existing UI components:
+- "Your buttons would benefit from the rounded-xl radius we chose — the default rounded-md doesn't match the friendly personality."
+- "Consider adding a subtle hover:shadow-md to your cards — the current flat cards don't use the depth system we defined."
+- "Your sidebar should use the sidebar-specific tokens — right now it's using generic background colors."
+
+---
+
+## Output Format
+
+### design-system.md Structure
+
+```markdown
+# Design System — {Product Name}
+
+## Creative North Star
+[One paragraph defining the visual identity — the "north star" that guides every decision]
+
+## Color Philosophy
+
+### Palette Rationale
+[Why these colors for this product/audience — competitive analysis, audience expectations, personality alignment]
+
+### Surface Hierarchy
+[How surfaces layer: base -> container -> card -> elevated, with light/dark mode differences]
+
+### Dark Mode Strategy
+[How colors adapt — not just invert. Chroma reduction, lightness stepping, border opacity]
+
+### Color Reference
+| Token | Light Value | Dark Value | Usage | Tailwind Class |
+|-------|-------------|------------|-------|----------------|
+| --primary | oklch(...) | oklch(...) | Brand color, primary buttons | bg-primary |
+| ... | ... | ... | ... | ... |
+
+## Typography
+
+### Font Pairing
+[Display + body fonts with reasoning: why this pairing, what it communicates, how it serves the audience]
+
+### Type Scale
+| Size | Value | Line Height | Usage | Tailwind Class |
+|------|-------|-------------|-------|----------------|
+| xs | 0.75rem | 1rem | Captions, badges | text-xs |
+| ... | ... | ... | ... | ... |
+
+### Weight Scale
+| Weight | Value | Usage | Tailwind Class |
+|--------|-------|-------|----------------|
+| normal | 400 | Body text | font-normal |
+| ... | ... | ... | ... |
+
+## Spacing & Rhythm
+
+### Base Unit
+[What it is, why that value, how it scales]
+
+### Spacing Conventions
+[When to use which spacing values — component padding, section gaps, page margins]
+
+## Rounding
+
+### Personality
+[Description of the rounding character and why it fits]
+
+### Radius Scale
+| Token | Value | Usage | Tailwind Class |
+|-------|-------|-------|----------------|
+| --radius | Xrem | Base radius | -- |
+| sm | calc(base - 4px) | Small elements | rounded-sm |
+| ... | ... | ... | ... |
+
+## Elevation & Depth
+
+### Shadow Scale
+| Token | Value | Usage | Tailwind Class |
+|-------|-------|-------|----------------|
+| xs | ... | Tags, subtle depth | shadow-xs |
+| ... | ... | ... | ... |
+
+### Border Philosophy
+[Lines vs tonal shifts vs shadows — when and why]
+
+## Component Guidelines
+
+### Buttons
+[Deep styling: variants, sizes, states, icon alignment, gradient/flat decision]
+
+### Cards
+[Surface treatment, rounding, padding, hover behavior]
+
+### Inputs
+[Fill vs outline, focus states, error states, label placement]
+
+### Modals
+[Backdrop, shadow, animation, sizing]
+
+### Navigation
+[Active states, collapsed behavior, section headers]
+
+### Badges
+[Sizes, variants, color treatments]
+
+### Tables
+[Header styling, row hover, cell padding, border strategy]
+
+### Forms
+[Field spacing, error flow, help text, required indicators]
+
+## Animation & Motion
+
+### Duration Scale
+| Name | Value | Usage |
+|------|-------|-------|
+| fast | 100ms | Hover states |
+| ... | ... | ... |
+
+### Easing Curves
+| Name | Value | Personality | Usage |
+|------|-------|-------------|-------|
+| ease-out | cubic-bezier(...) | Confident | Entrances |
+| ... | ... | ... | ... |
+
+### Custom Animations
+[List of @keyframes with descriptions and usage guidance]
+
+### Motion Reduction
+[prefers-reduced-motion strategy]
+
+## Do's and Don'ts
+
+### Do
+- Use semantic color tokens (`bg-primary`, `text-muted-foreground`) — never raw oklch or hex values in components
+- Test every screen in both light and dark mode before considering it done
+- Use `cn()` for all className composition — never concatenate strings
+- Reference the Creative North Star when making ambiguous design decisions
+- Use the shadow scale consistently: cards=shadow-sm, dropdowns=shadow-lg, modals=shadow-xl
+- Respect the surface layering stack — each layer gets the right elevation treatment
+- Use `data-slot` attributes on every component element for CSS targeting
+- Maintain generous whitespace — if a layout feels empty, leave it
+- Tint neutrals with the brand undertone — never use pure achromatic grays unless the design specifically calls for it
+- Use the translation table to communicate design intent in plain language
+
+### Don't — Common AI Mistakes to Prevent
+- Never use `#000000` or pure black — use the `foreground` token (tinted dark)
+- Never use `#FFFFFF` directly — use the `background` token
+- Never use 1px solid borders to separate content sections — use tonal shifts, spacing, or ghost borders (`ring-1 ring-foreground/10`)
+- Never mix more than 2 typefaces on a single screen
+- Never center-align body text longer than 2 lines — left-align for readability
+- Never add shadows to elements resting on the same surface layer — shadows indicate floating
+- Never animate page-load content (causes layout shift) — reserve animation for user-triggered interactions
+- Never use generic Tailwind grays (`border-gray-200`, `bg-slate-100`) — always use semantic tokens (`border-border`, `bg-muted`)
+- Never create interactive elements without hover, focus, and active states
+- Never use `rounded-none` on interactive elements — minimum `rounded-sm`
+- Don't over-saturate — limit primary accent color to ~10-15% of visible screen area
+- Never skip the mobile viewport — every component must have a defined mobile behavior
+- Never hardcode breakpoint values — use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`)
+
+## How to Use
+
+### Color Tokens in Code
+[Practical examples: bg-primary, text-muted-foreground, etc.]
+
+### Typography in Code
+[Practical examples: text-lg font-semibold tracking-tight, etc.]
+
+### Shadow Scale in Code
+[Practical examples: shadow-sm for cards, shadow-xl for modals]
+
+### Radius in Code
+[Practical examples: rounded-lg for cards, rounded-4xl for buttons]
+
+### Spacing in Code
+[Practical examples: p-4, gap-6, when to use which]
+
+### Dark Mode
+[How class-based dark mode works, what to test, common mistakes]
+
+### Quick Reference
+| What You Need | Token/Class | Example |
+|---------------|-------------|---------|
+| Brand color background | bg-primary | Primary buttons |
+| Subtle text | text-muted-foreground | Helper text, captions |
+| Card container | bg-card rounded-lg shadow-sm | Content cards |
+| Focus ring | ring-ring ring-2 ring-offset-2 | Keyboard focus |
+| ... | ... | ... |
+
+### Design Language Translation
+
+When communicating design intent (in reviews, in the design doc, or when prompting AI), use these translations between technical values and natural language:
+
+| Technical (Tailwind) | Design Language | When to Use |
+|---------------------|-----------------|-------------|
+| `rounded-full` | Pill-shaped | Badges, tags, avatar containers |
+| `rounded-4xl` | Generously rounded | Buttons, search bars |
+| `rounded-2xl` | Softly rounded | Cards, modals |
+| `rounded-xl` | Gently curved | Dropdowns, popovers |
+| `rounded-lg` | Subtly rounded corners | Inputs, smaller containers |
+| `rounded-none` | Sharp, squared-off edges | Avoid on interactive elements |
+| `shadow-2xs` | Barely visible lift | Subtle card definition |
+| `shadow-sm` | Whisper-soft shadow | Resting cards |
+| `shadow-md` | Gentle elevation | Hovered cards |
+| `shadow-lg` | Noticeable depth | Dropdowns, popovers |
+| `shadow-xl` | Prominent floating | Modals, dialogs |
+| `shadow-2xl` | Dramatic elevation | Full-screen overlays |
+| `bg-input/30` | Subtle tinted fill | Input field backgrounds |
+| `ring-1 ring-foreground/10` | Ghost border | When tonal shift alone isn't enough |
+| `font-medium` | Confident but not heavy | Labels, navigation |
+| `font-semibold` | Emphatic, attention-grabbing | Headings, CTAs |
+| `font-bold` | Strong authority | Hero headlines |
+| `tracking-tight` | Compact, modern feel | Display text |
+| `tracking-wide` | Spacious, editorial | Uppercase labels |
+| `leading-relaxed` | Breathing room for readability | Long-form body text |
+| `leading-tight` | Dense, compact | Headlines, UI labels |
+| `text-muted-foreground` | Recessive, supportive | Descriptions, timestamps, metadata |
+| `animate-fade-in` | Gentle appearance | Page section reveals |
+| `animate-slide-up` | Rising entrance | Toast notifications, bottom sheets |
+| `ease-spring` | Bouncy, playful snap | Playful interactions |
+| `ease-smooth` | Refined, buttery | Professional transitions |
+
+## Agent Context — Design System Quick Reference
+
+*This section is formatted for AI agent consumption. When generating UI components, reference this section for quick token lookups and component recipes.*
+
+### Color Map
+[Flat list of every token with oklch value + primary Tailwind class. One line per token. No explanations — just the mapping.]
+```
+- primary: oklch(0.488 0.243 264) → `bg-primary`, `text-primary`, `border-primary`
+- primary-foreground: oklch(0.97 0.014 254) → `text-primary-foreground`
+- background: oklch(1 0 0) → `bg-background`
+- foreground: oklch(0.145 0 0) → `text-foreground`
+[... all 31+ tokens]
+```
+
+### Component Recipes
+[Ready-to-paste Tailwind class combinations for common component patterns. These are the "golden paths" — the exact class strings that produce correct results.]
+```
+Primary Button:     bg-primary text-primary-foreground rounded-4xl h-9 px-3 text-sm font-medium
+Secondary Button:   bg-secondary text-secondary-foreground rounded-4xl h-9 px-3 text-sm font-medium
+Ghost Button:       hover:bg-muted hover:text-foreground rounded-4xl h-9 px-3 text-sm font-medium
+Destructive Button: bg-destructive/10 text-destructive rounded-4xl h-9 px-3 text-sm font-medium
+Card:               bg-card ring-1 ring-foreground/10 rounded-2xl p-6
+Card (compact):     bg-card ring-1 ring-foreground/10 rounded-2xl p-4
+Input:              bg-input/30 border-input rounded-4xl h-9 px-3 text-sm
+Badge:              bg-primary text-primary-foreground rounded-4xl px-2 py-0.5 text-xs font-medium
+Separator:          bg-border h-px w-full
+```
+
+### Spacing Cheat Sheet
+```
+Between form fields:      gap-7
+Within a field (label→input→error): gap-1.5
+Between page sections:    gap-12 or mt-12
+Card internal padding:    p-6 (default), p-4 (compact)
+Page horizontal padding:  px-6 (desktop), px-4 (mobile)
+Between cards in a grid:  gap-4
+Between buttons in a row: gap-2
+```
+
+### Surface Layering
+```
+Page background:     bg-background
+Sidebar:             bg-sidebar
+Card on page:        bg-card
+Input field:         bg-input/30
+Popover/Dropdown:    bg-popover + shadow-lg
+Modal backdrop:      bg-black/50
+Modal content:       bg-background + shadow-xl
+```
+
+### Design Rules (for AI agents)
+```
+1. Always use cn() for className composition
+2. Always use semantic tokens — never raw colors
+3. Never use #000000 — use foreground token
+4. Borders: prefer ring-1 ring-foreground/10 over border
+5. Interactive elements: always include hover + focus states
+6. Shadow usage: cards=shadow-sm, dropdowns=shadow-lg, modals=shadow-xl
+7. Dark mode: test every component in both modes
+8. Mobile: every component must work at 320px width
+9. Typography: max 2 font families per screen
+10. Accent: limit primary color to ~10-15% of visible area
+```
+```
+
+### shared-styles.css Structure
+
+Must match the Tailwind v4 blueprint template structure exactly:
+
+```css
+/* 1. Imports */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "tailwind-scrollbar-hide/v4";
+
+/* 2. Custom variant */
+@custom-variant dark (&:is(.dark *));
+
+/* 3. Theme inline — semantic token -> Tailwind utility mappings */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+  /* ... all 31+ color mappings ... */
+  /* ... radius scale ... */
+}
+
+/* 4. Theme — shadows, easing, animations, keyframes */
+@theme {
+  --shadow-xs: ...;
+  --shadow-sm: ...;
+  /* ... full shadow scale ... */
+
+  --ease-smooth: cubic-bezier(...);
+  --ease-spring: cubic-bezier(...);
+  /* ... custom easing ... */
+
+  --animate-fade-in: fade-in 200ms ease-out;
+  --animate-slide-up: slide-up 200ms ease-out;
+  /* ... animation definitions ... */
+
+  @keyframes fade-in { ... }
+  @keyframes slide-up { ... }
+  @keyframes scale-in { ... }
+  /* ... all keyframes ... */
+}
+
+/* 5. Light mode variables */
+:root {
+  --background: oklch(... ... ...);
+  --foreground: oklch(... ... ...);
+  --primary: oklch(... ... ...);
+  /* ... all 31+ tokens ... */
+  --radius: ...rem;
+  /* ... font variables ... */
+}
+
+/* 6. Dark mode variables */
+.dark {
+  --background: oklch(... ... ...);
+  --foreground: oklch(... ... ...);
+  --primary: oklch(... ... ...);
+  /* ... all 31+ tokens ... */
+}
+
+/* 7. Base layer */
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+---
+
+## Maintenance Hooks
+
+### Design System Hooks
+
+| When you... | Then do... | Why |
+|---|---|---|
+| Change a color token in `docs/design/shared-styles.css` | Sync to `config/tailwind-config/shared-styles.css` (monorepo) or `src/styles/shared-styles.css` (single-repo) | Design source of truth must match deployed tokens |
+| Update light mode color | Update the corresponding dark mode value | Missing dark mode = broken in one mode |
+| Change font families | Ensure fonts are imported in the app layout (Google Fonts link or `@font-face`) | CSS variables reference fonts that must be loaded |
+| Add new CSS variables | Add corresponding entries to `@theme inline {}` | Tailwind utilities only work for mapped tokens |
+| Change the radius base value | Verify all component-specific radius classes still look correct | The entire radius scale recalculates from one value |
+| Update shadow values | Verify both light and dark mode look correct | Shadow opacity that works on white may be invisible on dark |
+
+### Condensed Rules for project maintenance skill
+
+```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
+```
+
+---
+
+## What's Configurable
+
+- **Creative direction** — fully conversational, user picks from proposed options or mixes elements
+- **Primary color hue** — any oklch hue value (0-360), proposed based on product personality and competition
+- **Typography** — any font pairing (display + body + optional mono), researched based on audience
+- **Rounding personality** — sharp (0-4px), moderate (6-10px), round (12-16px), or full (20px+, pill buttons)
+- **Shadow style** — ambient/diffused (modern), sharp/dramatic (bold), or brand-tinted (premium)
+- **Animation personality** — subtle and professional or bouncy and playful
+- **Border philosophy** — no-line (tonal), intentional (sparse borders), or traditional (bordered)
+- **Level of component guideline depth** — comprehensive by default, concise on request
+- **Spacing density** — standard (0.25rem base), tight (0.2rem), or loose (0.3rem)
+
+---
+
+## What's Opinionated
+
+- **Teach the why** — every design decision is annotated with reasoning. "Use blue" is useless. "Use blue because your enterprise audience equates blue with trust, and your competitors at [X] and [Y] already use green and violet, leaving blue as defensible territory" is educational. This blueprint is a design education disguised as a configuration tool.
+
+- **oklch color space** — perceptually uniform, better dark mode translations, wider gamut than hex/RGB. Not negotiable. Colors defined as raw hex values are objectively inferior for design systems because they don't maintain perceptual consistency across lightness adjustments.
+
+- **Semantic tokens, always** — never raw color values in components. Always through `--primary`, `--muted`, `--destructive`, etc. This is what makes themes changeable — swap the token values and every component updates. Hard-coded colors create un-maintainable design debt.
+
+- **Surface hierarchy** — layered surfaces (background -> card -> popover -> elevated), not flat. The human visual system interprets depth naturally. Flat designs without hierarchy make users work harder to understand the structure.
+
+- **Both light AND dark mode** — always, no exceptions. Light-only designs are incomplete. The shared-styles.css file always contains both `:root` and `.dark` blocks with every token defined in both.
+
+- **CSS output matches Tailwind v4 template structure exactly** — the generated `shared-styles.css` is a drop-in replacement for the Tailwind v4 blueprint's generic file. Same imports, same blocks, same variable names. No creative reinterpretation of the structure.
+
+- **Creative direction before any tokens** — the Creative North Star comes first. Without it, color and typography choices are arbitrary. With it, every subsequent decision is evaluated against a coherent vision.
+
+- **Educational annotations** — the user learns design thinking through the process. Every "I recommend X" comes with "because Y, which matters for your product because Z." The goal is not just a design system but a designer who understands it.
+
+- **Honest about tradeoffs** — rounded corners ARE friendlier but DO lose information density. Dark mode IS expected but DOES require more design work. Bold colors DO differentiate but CAN fatigue users. Every recommendation acknowledges what you give up.
+
+---
+
+## Project Context Output
+
+After completion, appends to `.project-context.md` in the target project:
+
+```yaml
+### design-system
+blueprint: design-system
+installed_at: <date>
+creative_direction: "<north star name>"
+primary_color_hue: <oklch hue value>
+font_display: "<font name>"
+font_body: "<font name>"
+rounding: "<personality: sharp/moderate/round/full>"
+artifacts:
+  - docs/design/design-system.md
+  - docs/design/shared-styles.css
+synced_to: config/tailwind-config/shared-styles.css  # if synced
+```
+
+---
+
+## References
+
+- **Tailwind CSS v4 Theme:** https://tailwindcss.com/docs/theme
+- **OKLCH Color Space:** https://oklch.com
+- **OKLCH Color Picker:** https://oklch.com/#70,0.1,200,100
+- **Google Material Design 3:** https://m3.material.io
+- **Practical Typography:** https://practicaltypography.com
+- **Google Fonts:** https://fonts.google.com
+- **Type Scale Calculator:** https://typescale.com
+- **Bar & Neta (2006):** Humans prefer curved visual objects (Psychological Science) — the research behind rounding personality
+- **shadcn/ui Theming:** https://ui.shadcn.com/docs/theming
+- **WCAG Non-text Contrast (1.4.11):** https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html