SKILL.md
---
name: visual-design
description: "Create DESIGN.md files — structured markdown visual design systems (colors, typography, spacing, components) that AI coding agents read to generate consistent UI. Use when the user mentions DESIGN.md, visual design, design system, design tokens, extracting a design from a website, or documenting UI tokens. Also triggers on 'make it look like [brand]', 'capture the design of [site]', 'extract design tokens'. Note: this is NOT for architectural design docs (use /ship:write-docs for those) or system design thinking (use /ship:arch-design for that)."
---
# Visual Design
Create production-quality DESIGN.md files following the **awesome-design-md** format — a 9-section markdown standard for describing visual design systems that AI agents (and Google Stitch) can read and faithfully reproduce.
A DESIGN.md is like AGENTS.md for visual identity: drop it in your project root and any AI coding agent generates UI that matches your design language. No Figma exports, no JSON schemas — just markdown.
## Three Modes
Determine which mode applies, then read the corresponding reference file for the full process.
### A. From Scratch
The user describes their vision — mood, colors, fonts, brand references. You explore the vision through structured discovery, propose 2-3 directions, and build the DESIGN.md incrementally with user validation at each stage.
**Read `references/from-scratch.md` for the full process.**
### B. From a Website URL
The user provides a URL and wants the site's design system captured. You clarify scope and intent, inspect the DOM for actual values, validate the extracted foundation with the user, and assemble the DESIGN.md.
**Read `references/from-url.md` for the full process.**
### C. From Current Codebase
The user has an existing project and wants a DESIGN.md extracted from the code. You discover the tech stack, systematically extract tokens, validate with the user, fill gaps, and document what the project actually looks like.
**Read `references/from-codebase.md` for the full process.**
## The 9-Section Format
Every DESIGN.md follows this exact structure. The H1 is always:
```
# Design System Inspiration of [Name]
```
Then 9 numbered H2 sections. See `references/template.md` for the full template with placeholders, and `references/section-guide.md` for detailed writing guidance.
| # | Section | What It Contains |
|---|---------|-----------------|
| 1 | Visual Theme & Atmosphere | 2-3 paragraphs of design philosophy + Key Characteristics bullet list |
| 2 | Color Palette & Roles | Colors grouped by role (Primary, Accent, Surface, Neutral, Semantic) |
| 3 | Typography Rules | Font families, hierarchy table, typographic principles |
| 4 | Component Stylings | Buttons, cards, inputs, navigation, badges, distinctive components |
| 5 | Layout Principles | Spacing system, grid, whitespace philosophy, border-radius scale |
| 6 | Depth & Elevation | Shadow levels table + shadow philosophy |
| 7 | Do's and Don'ts | 7-10 specific directives each, referencing actual values |
| 8 | Responsive Behavior | Breakpoints, touch targets, collapsing strategy |
| 9 | Agent Prompt Guide | Quick color reference, 5 example prompts, iteration guide |
## Formatting Conventions
These conventions make the file parseable by both humans and AI agents:
- **Hex codes** always in backticks: `` `#533afd` ``
- **RGBA values** in backticks: `` `rgba(50,50,93,0.25)` ``
- **Font names** in backticks: `` `sohne-var` ``
- **CSS values** in backticks: `` `0px 30px 45px -30px` ``
- **Metrics** in backticks: `` `8px` ``, `` `1.40` ``
- **Color names** in bold: **Stripe Purple**, **Deep Navy**
- **Size dual notation**: `56px (3.50rem)` — pixel with rem equivalent
- **Color entry format**: `- **Descriptive Name** (\`#hex\`): Role and usage context.`
- **Component property format**: `- Property: \`value\` (contextual note)`
- Tables use standard markdown pipe syntax
- No YAML frontmatter in the DESIGN.md output (the file is pure markdown)
- No code fences wrapping design content (fences only for inline CSS values)
## Quality Checklist
Before presenting the DESIGN.md, verify:
- [ ] H1 follows `# Design System Inspiration of [Name]`
- [ ] All 9 sections present and numbered
- [ ] Every color has a descriptive name, hex in backticks, and usage description
- [ ] Typography table has all columns: Role, Font, Size, Weight, Line Height, Letter Spacing
- [ ] At least 3 button variants documented (primary, secondary/ghost, tertiary)
- [ ] Shadow table has 4-6 levels with actual CSS values
- [ ] Do's and Don'ts reference specific hex values and measurements
- [ ] Section 9 has 5 concrete example component prompts with real values from the system
- [ ] Breakpoints table covers mobile through large desktop
- [ ] Colors are semantically grouped (not just listed)
- [ ] No orphan values — every color/token referenced in Section 9's Quick Reference appears in Section 2
## Generating Preview HTML
After completing the DESIGN.md, generate a companion `preview.html` — a self-contained HTML file that visually demonstrates the design system.
Read `references/preview-template.html` for the HTML scaffold. The preview should contain:
1. **Navigation bar** — brand name + CTA button in the design system's style
2. **Hero section** — headline and subtitle demonstrating the type scale
3. **Color palette** — swatches for every color in Section 2, labeled with name and hex
4. **Typography scale** — samples at each hierarchy level from Section 3
5. **Button variants** — all button styles from Section 4
6. **Card examples** — 2-3 cards with proper shadows and borders
7. **Form inputs** — default, focus, and error states
8. **Spacing scale** — visual representation of the spacing system
9. **Border radius** — examples at each scale value
10. **Elevation/shadows** — cards at each shadow level
The HTML must be fully self-contained (inline CSS, no external dependencies) and use CSS custom properties for all design tokens. Include a responsive media query so it renders well on mobile too.
If the design system has a dark mode or dark sections, also generate `preview-dark.html` with dark surface backgrounds.
## Execution Handoff
Output the report card:
```
## [Visual Design] Report Card
| Field | Value |
|-------|-------|
| Status | <DONE / BLOCKED> |
| Summary | DESIGN.md created via <mode: scratch / url / codebase> |
### Metrics
| Metric | Value |
|--------|-------|
| Mode | <From Scratch / From URL / From Codebase> |
| Sections completed | <N>/9 |
| Colors documented | <N> |
| Typography levels | <N> |
| Component variants | <N> |
| Preview generated | <yes / no> |
| Dark mode preview | <yes / no / n/a> |
### Artifacts
| File | Purpose |
|------|---------|
| DESIGN.md | Visual design system (9-section format) |
| preview.html | Self-contained HTML preview of the design system |
| preview-dark.html | Dark mode variant (if applicable) |
```
## Reference Files
Read these as needed — they contain the detailed templates, mode processes, and examples:
- **`references/from-scratch.md`** — Full process for creating a DESIGN.md from scratch through collaborative discovery.
- **`references/from-url.md`** — Full process for extracting a design system from a live website.
- **`references/from-codebase.md`** — Full process for reverse-engineering a design system from existing code.
- **`references/template.md`** — The complete 9-section template with fill-in placeholders. Read this when writing any DESIGN.md.
- **`references/section-guide.md`** — Deep guidance on what makes each section excellent. Read this for quality standards and common pitfalls.
- **`references/preview-template.html`** — HTML scaffold for the preview file. Read this when generating the preview.
references/from-codebase.md
# Mode C: From Current Codebase
Reverse-engineer the implicit design system from existing code — make explicit what's already there through systematic extraction, user validation, and structured documentation.
## Checklist — complete in order
1. **Clarify scope** — understand what parts of the codebase to extract from
2. **Discover the tech stack** — find where design tokens live
3. **Extract design tokens** — systematically pull colors, typography, spacing, shadows, radii, components
4. **Present extracted foundation** — show palette + typography for validation before writing all 9 sections
5. **Resolve ambiguities** — ask about inconsistencies and intentional vs accidental choices
6. **Fill gaps** — handle framework defaults, undeclared tokens, and missing values
7. **Build DESIGN.md + preview.html** — only after foundation is validated
8. **Quality gate** — run the Quality Checklist, present with diff summary for final approval
## Clarifying scope
Before scanning files, ask **one scoping question** if the answer isn't obvious from context:
- **Monorepo / multi-app** — "This repo has a marketing site and a dashboard app — should I document both as one system, or focus on one?"
- **Partial extraction** — "Should I document the whole app's design, or just the component library / a specific area?"
- **Intent** — "Are you documenting what exists (warts and all), or creating a cleaned-up target design system?" This changes whether inconsistencies are preserved or resolved.
If the project is a single app with one styling approach, skip to discovery.
## Discovering the tech stack
Search the workspace for signals of the styling approach:
- `tailwind.config.*` / `tailwind.css` — Tailwind CSS (most common in modern projects)
- `theme.ts` / `theme.js` / `theme/` — custom theme objects (MUI, Chakra, styled-components)
- `variables.css` / `_variables.scss` / `tokens.css` — CSS custom properties or Sass variables
- `*.module.css` / `*.styled.ts` — CSS Modules or CSS-in-JS
- `global.css` / `globals.css` / `app.css` — global stylesheets
- `package.json` — check for UI framework deps (e.g., `@mui/material`, `@chakra-ui/react`, `shadcn`, `ant-design`, `@radix-ui`)
## Extracting design tokens
Read the files you found and systematically pull out:
### Colors
- Tailwind: read the `extend.colors` block in `tailwind.config.*`, also check for CSS variable definitions in `globals.css` / `app.css` (e.g., `--primary: 222.2 47.4% 11.2%` in HSL notation — convert to hex)
- Theme objects: read the `colors` / `palette` keys
- CSS variables: grep for `--color-`, `--bg-`, `--text-`, `--border-` patterns
- Sass: grep for `$color-`, `$bg-`, `$brand-` patterns
- If colors are defined as HSL (`hsl(222.2, 47.4%, 11.2%)`), Oklch, or other formats, convert them to hex for the DESIGN.md
### Typography
- Tailwind: `extend.fontFamily`, also check `@import` or `<link>` tags for Google Fonts / local font files
- Look for `font-size`, `line-height`, `letter-spacing`, `font-weight` patterns in CSS or theme config
- Check `layout.tsx` / `_app.tsx` / `index.html` for `<link>` font imports or Next.js `next/font` usage
- Read actual component files to see which font sizes are used in practice (h1, h2, body, caption patterns)
### Spacing & Layout
- Tailwind: `extend.spacing`, check for `container` config, common padding/margin classes used across components
- Theme objects: `spacing` / `space` keys
- CSS: grep for repeated `padding`, `margin`, `gap` values to identify the implicit scale
### Shadows & Elevation
- Tailwind: `extend.boxShadow`
- CSS: grep for `box-shadow` declarations
- Theme objects: `shadows` / `elevation` keys
### Border Radius
- Tailwind: `extend.borderRadius`
- CSS: grep for `border-radius` patterns to find the actual scale in use
### Components
- Read a few representative component files (buttons, cards, inputs, navigation) to see how tokens are applied in practice
- Look for component libraries: if using shadcn/ui, check `components/ui/button.tsx`, `components/ui/card.tsx`, etc.
- For MUI/Chakra, the theme object contains component overrides
## Presenting the extracted foundation
Before writing all 9 sections, present the **extracted palette and typography** for validation:
1. **Extracted palette** — list every color found, grouped by role. Name each one descriptively (not the Tailwind class name). Note which are from config vs hardcoded in components. Ask: "Does this capture your project's colors? Anything missing or wrong?"
2. **Extracted typography** — font families, size hierarchy, weight usage. Ask: "Does this look right?"
This catches errors early — e.g., extracting unused config colors that aren't actually in the UI, or missing hardcoded values that bypass the theme.
## Resolving ambiguities
Real codebases are messy. When you encounter inconsistencies, **ask rather than assume**:
- "I see both `rounded-lg` and `rounded-xl` on cards — is there a distinction or should I standardize?"
- "The theme defines `colors.blue` but no component uses `blue-*` classes — should I include it or leave it out?"
- "I found 3 different `box-shadow` values across components — are these intentional elevation levels or drift?"
## Filling gaps
Real codebases rarely have every design token explicitly defined — some values are inherited from framework defaults, some are scattered across component files:
- If using Tailwind with default config, note which default values are being used (e.g., Tailwind's default `slate` scale)
- Scan 3-5 actual page/component files to observe the de facto patterns — what colors, spacings, and fonts appear most frequently?
- Check for a running dev server — if the project has one, start it and use browser inspection to verify actual rendered values
- Where values are completely absent (e.g., no explicit breakpoints), document the framework defaults in use and note them as inherited
## After validation — writing the DESIGN.md
- Read `references/template.md` for the exact 9-section structure
- Read `references/section-guide.md` for quality standards per section
- Name and organize: give every color a descriptive name that reflects its role, not its Tailwind class name. `bg-slate-900` becomes **Ink Black** (`#0f172a`): "Primary background for dark surfaces"
- Group by semantic role, not by source file
- Document the actual values being used, not what the config *could* support
- Generate the companion `preview.html` using `references/preview-template.html`
- Run the Quality Checklist (defined in SKILL.md) before presenting
**Present with a diff summary** — show the user what you found and any gaps or inconsistencies:
- "Your codebase uses 14 distinct colors. 3 appear to be unused in the theme config."
- "I found two different shadow patterns — `shadow-sm` on cards and a custom `shadow-card` in globals.css. I documented both."
- "No explicit breakpoints defined — I used Tailwind defaults (sm/md/lg/xl/2xl)."
## Handling framework-specific patterns
- **Tailwind + shadcn/ui:** The definitive source of truth is usually `globals.css` (CSS variables in `:root` and `.dark`) plus `tailwind.config.*`. shadcn components consume these variables, so read the variables first, then check a few components for how they're used.
- **MUI / Chakra / Mantine:** Read the `createTheme()` / `extendTheme()` call. The theme object maps directly to DESIGN.md sections (palette → Section 2, typography → Section 3, spacing → Section 5, shadows → Section 6).
- **Plain CSS / Sass:** Grep broadly for color values (`#[0-9a-fA-F]{3,8}`, `rgb(`, `hsl(`), font declarations, and shadow values. Deduplicate and organize by frequency of use.
- **CSS-in-JS (styled-components, emotion):** Look for a theme provider and its theme object, plus any `css` tagged templates with hardcoded values.
## Key principles
- **Document reality, not potential** — prefer observed values over config defaults; if a color is defined but never used, leave it out
- **Validate the foundation** — palette and typography are the highest-leverage checkpoints; get sign-off before writing 9 sections
- **Ask about inconsistencies** — the user knows which are intentional design choices and which are drift
- **Name semantically** — `bg-slate-900` is a Tailwind class; **Ink Black** is a design token
- **Note the provenance** — in the diff summary, distinguish between explicit config values, observed-in-components values, and inherited framework defaults
references/from-scratch.md
# Mode A: From Scratch
Collaborative design exploration — turn a vague vision into a complete DESIGN.md through structured discovery and incremental validation.
<HARD-GATE>
Do NOT write the DESIGN.md until you have explored the user's vision, proposed design directions, and received approval on the overall direction. A "simple" design system is where unexamined assumptions cause the most wasted iteration. The discovery can be brief for clear visions, but you MUST present a direction and get approval.
</HARD-GATE>
## Checklist — complete in order
1. **Explore project context** — check existing files (CSS, theme configs, package.json) for constraints
2. **Offer visual companion** — if the project has a dev server or you can serve preview.html, offer to show live previews as you iterate (this is its own message, not combined with a question)
3. **Discovery questions** — one at a time, understand the design vision
4. **Propose 2-3 design directions** — with trade-offs and your recommendation
5. **Present design incrementally** — core sections first, get feedback before completing all 9
6. **Write DESIGN.md + preview.html** — only after direction is validated
7. **Quality gate** — run the Quality Checklist, then present for final approval
## Discovery — understanding the vision
- Check the project first — existing colors, fonts, or framework choices are constraints, not blank-slate decisions
- Ask questions **one at a time** to refine the vision
- Prefer **multiple choice** when possible — easier to answer than open-ended
- Focus on these dimensions (in roughly this order):
1. **Mood & atmosphere** — "Which best describes the feel you want?" (minimal/clean, warm/approachable, bold/energetic, premium/sophisticated, playful/creative)
2. **Light or dark** — light background, dark background, or both?
3. **Color direction** — any brand colors already decided? Warm or cool palette? Specific colors they love or hate?
4. **Typography feel** — geometric/modern (Inter, DM Sans) vs humanist/warm (Source Sans, Nunito) vs editorial/distinctive (Playfair, Fraunces)? Serif or sans-serif headings?
5. **Component style** — sharp corners or rounded? Dense or airy? Flat or elevated (shadows)?
6. **Target audience & platform** — developer tool, consumer app, marketing site, dashboard?
7. **References** — any sites or brands they admire? ("Make it feel like Stripe but warmer")
- If they reference a brand, internalize the sensibility but create original values — never copy another brand's exact hex codes or font stack
- If the vision is already crystal clear ("I want exactly the Linear aesthetic but with green as primary"), you can compress discovery to 2-3 confirming questions
## Exploring directions
- Once you understand the vision, propose **2-3 design directions** with distinct personalities
- For each direction, describe: color mood (with example hex), typography approach, component style, and the overall feel
- Lead with your recommendation and explain why it fits their stated goals
- Example: "Direction A: *Midnight Professional* — dark navy surfaces, weight-300 headings, subtle chromatic shadows. Direction B: *Warm Editorial* — cream backgrounds, serif headings, generous whitespace. I'd recommend A because you mentioned wanting a developer-tool feel."
## Presenting the design incrementally
- After the user picks a direction, build the design section by section
- Present the **foundation sections first** and get feedback before completing all 9:
- **Section 2 (Colors)** — present the full palette with names and roles. This is the highest-impact decision. Get approval before proceeding.
- **Section 3 (Typography)** — font choices, hierarchy table. Get approval.
- **Sections 4-6 (Components, Layout, Elevation)** — present together as the "component layer." Get approval.
- **Sections 1, 7-9 (Atmosphere, Do's/Don'ts, Responsive, Agent Guide)** — complete after the core is validated.
- Scale each presentation to its complexity — a few sentences if straightforward, detailed walkthrough if nuanced
- Be ready to go back and revise. "The blues feel too cold" means revisiting Section 2 before continuing.
## Visual companion
When you anticipate that visual feedback would help the user evaluate choices (color palettes, typography pairings, component styles), offer to show a live preview:
> "I can generate a live preview as we go so you can see how colors, fonts, and components look together. Want me to open a preview in your browser?"
This offer MUST be its own message — do not combine with other questions. If they accept:
- Generate `preview.html` early with the foundation tokens (even before all 9 sections are complete)
- Update the preview as you iterate on sections
- Use `references/preview-template.html` as the scaffold
If they decline, proceed with text-only descriptions.
## After validation — writing the DESIGN.md
- Read `references/template.md` for the exact 9-section structure
- Read `references/section-guide.md` for quality standards per section
- Generate the companion `preview.html` (and optionally `preview-dark.html`) using `references/preview-template.html`
- Run the Quality Checklist (defined in SKILL.md) before presenting the final result
- Present both files to the user for final approval
## Key principles
- **One question at a time** — don't overwhelm with a wall of questions
- **Multiple choice preferred** — "Which of these 3 palettes?" beats "What colors do you want?"
- **Show, don't describe** — if visual companion is available, show a palette swatch instead of listing 10 hex codes
- **Foundation first** — colors and typography define 80% of the feel; get those right before detailing components
- **Be opinionated** — always lead with your recommendation; the user hired a design system, not a menu
- **Revise willingly** — going back to fix the palette after seeing components is normal, not failure
references/from-url.md
# Mode B: From a Website URL
Extract a real site's design system into a DESIGN.md through systematic inspection, user validation, and incremental assembly.
## Checklist — complete in order
1. **Clarify scope and intent** — understand what pages to inspect and how the output will be used
2. **Inspect the site** — extract actual values from the DOM, not guesses
3. **Present extracted foundation** — show palette + typography for validation before writing all 9 sections
4. **Resolve ambiguities** — ask about inconsistencies, not assume
5. **Build DESIGN.md + preview.html** — only after foundation is validated
6. **Quality gate** — run the Quality Checklist, then present for final approval
## Clarifying scope and intent
Before opening the browser, ask **two quick questions** (can be combined in one message):
1. **Scope** — "Which pages should I extract from?" The homepage alone? The dashboard? Docs? Pricing page? Different pages on the same site can have noticeably different design treatments. If the user says "the whole site," focus on the homepage + one inner page and note where they diverge.
2. **Intent** — "How will you use this DESIGN.md?" This changes what you capture:
- *Recreating the look* → extract exact values, maximize fidelity
- *Taking inspiration* → capture the spirit and key tokens, note where you'd recommend departing
- *Building something similar but distinct* → extract the system's structure and proportions, but flag values the user should customize
If the user's intent is clear from context ("capture the design of stripe.com for our project"), you can compress to one confirming question.
## Inspecting the site
- Visit the site using browser tools. Take screenshots at **desktop and mobile** widths.
- Inspect the DOM to extract **actual values** — don't guess from screenshots:
- **Colors**: exact hex codes from computed styles (not approximations)
- **Typography**: font families (full `font-family` stack from CSS), sizes, weights, line heights, letter spacing
- **Spacing**: padding/margin patterns on key elements (nav, hero, cards, sections)
- **Borders**: border-radius values, border colors
- **Shadows**: exact `box-shadow` computed values (multi-layer shadows are common)
- **Gradients**: full CSS gradient definitions
- If the site uses a custom font, identify it precisely — check the CSS `font-family` stack, look for `@font-face` declarations or Google Fonts / Typekit links
- Accuracy matters more than speed. `#0a0f1a` is different from `#000000`. Inspect rather than eyeball.
## Presenting the extracted foundation
Before writing all 9 sections, present the **two highest-impact extractions** for validation:
1. **Extracted palette** — list every color you found, grouped by role (primary, surface, text, semantic, border, shadow). Name each one descriptively. Ask: "Does this capture the site's palette, or did I miss/misidentify anything?"
2. **Extracted typography** — font families, the hierarchy of sizes you observed, weights used. Ask: "Does this look right?"
This catches misidentifications early — e.g., confusing a hover-state color with the primary, or missing a secondary font used only in the hero.
## Resolving ambiguities
Real sites are messy. When you encounter inconsistencies, **ask rather than assume**:
- "I found 8 different gray shades — should I document all of them, or consolidate to the 4-5 most prominent?"
- "The hero uses `Inter` but the blog uses `Georgia` — should I document both as part of the system, or treat one as the primary?"
- "Cards on the homepage have `box-shadow: 0 4px 6px rgba(0,0,0,0.1)` but the pricing page uses `0 25px 50px rgba(0,0,0,0.25)` — are these two elevation levels, or an inconsistency?"
For values that aren't directly inspectable (design philosophy, the *why* behind choices), infer from the overall aesthetic but mark these as your interpretation.
## After validation — writing the DESIGN.md
- Read `references/template.md` for the exact 9-section structure
- Read `references/section-guide.md` for quality standards per section
- Name every color descriptively — not "Color 1" but "Midnight Navy" or "Signal Green". The name should evoke the color and hint at its role.
- Generate the companion `preview.html` using `references/preview-template.html`
- Run the Quality Checklist (defined in SKILL.md) before presenting the final result
- Present both files to the user for final approval
## Key principles
- **Inspect, don't guess** — computed styles over eyeballed approximations
- **Validate the foundation** — palette and typography are the highest-leverage checkpoints; get sign-off before writing 9 sections
- **Ask about ambiguity** — real sites have inconsistencies; the user knows which are intentional
- **Name everything** — descriptive color names make the DESIGN.md usable; "Stripe Purple" beats "#635bff"
- **Match the intent** — exact extraction for recreation, interpreted extraction for inspiration
references/preview-template.html
<!--
DESIGN.md Preview Template
Usage: Copy this template and replace all {{PLACEHOLDER}} values with actual
design tokens from the DESIGN.md you just created. CSS custom properties are
already wired up — just fill in the :root block.
The template is fully self-contained (no external dependencies).
Sections: Nav, Hero, Colors, Typography, Buttons, Cards, Forms, Spacing,
Border Radius, Elevation.
-->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Design System Preview — {{BRAND_NAME}}</title>
<style>
/* ===== DESIGN TOKENS — FILL THESE IN ===== */
:root {
/* Primary */
--color-primary: {{PRIMARY_HEX}};
--color-primary-hover: {{PRIMARY_HOVER_HEX}};
--color-heading: {{HEADING_HEX}};
--color-body: {{BODY_TEXT_HEX}};
--color-muted: {{MUTED_TEXT_HEX}};
/* Surfaces */
--color-bg: {{BG_HEX}};
--color-surface: {{SURFACE_HEX}};
--color-surface-elevated: {{ELEVATED_SURFACE_HEX}};
/* Accent */
--color-accent: {{ACCENT_HEX}};
--color-accent-light: {{ACCENT_LIGHT_HEX}};
/* Semantic */
--color-success: {{SUCCESS_HEX}};
--color-warning: {{WARNING_HEX}};
--color-error: {{ERROR_HEX}};
/* Borders */
--color-border: {{BORDER_HEX}};
--color-border-active: {{BORDER_ACTIVE_HEX}};
/* Shadows */
--shadow-subtle: {{SHADOW_SUBTLE_CSS}};
--shadow-standard: {{SHADOW_STANDARD_CSS}};
--shadow-elevated: {{SHADOW_ELEVATED_CSS}};
/* Typography */
--font-primary: {{FONT_PRIMARY}};
--font-mono: {{FONT_MONO}};
/* Radii */
--radius-sm: {{RADIUS_SM}}px;
--radius-md: {{RADIUS_MD}}px;
--radius-lg: {{RADIUS_LG}}px;
/* Spacing base */
--space-unit: {{SPACE_BASE}}px;
}
/* ===== RESET & BASE ===== */
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
html { font-size: 16px; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
body {
font-family: var(--font-primary), -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
color: var(--color-body);
background: var(--color-bg);
line-height: 1.5;
}
/* ===== NAV ===== */
.nav {
position: sticky; top: 0; z-index: 100;
display: flex; align-items: center; justify-content: space-between;
padding: 16px 32px;
background: var(--color-bg);
border-bottom: 1px solid var(--color-border);
backdrop-filter: blur(12px);
}
.nav-brand { font-size: 20px; font-weight: 600; color: var(--color-heading); text-decoration: none; }
.nav-cta {
padding: 8px 20px; border-radius: var(--radius-md);
background: var(--color-primary); color: #fff;
font-size: 14px; font-weight: 500; border: none; cursor: pointer;
}
.nav-cta:hover { background: var(--color-primary-hover); }
/* ===== LAYOUT ===== */
.container { max-width: 1080px; margin: 0 auto; padding: 0 32px; }
section { padding: 64px 0; }
section + section { border-top: 1px solid var(--color-border); }
.section-title {
font-size: 13px; font-weight: 600; text-transform: uppercase;
letter-spacing: 1.5px; color: var(--color-muted); margin-bottom: 32px;
}
/* ===== HERO ===== */
.hero { text-align: center; padding: 80px 0; }
.hero h1 {
font-size: 56px; font-weight: 300; color: var(--color-heading);
line-height: 1.1; letter-spacing: -1.4px; margin-bottom: 16px;
}
.hero p { font-size: 18px; color: var(--color-body); line-height: 1.5; max-width: 600px; margin: 0 auto 32px; }
.hero-buttons { display: flex; gap: 12px; justify-content: center; flex-wrap: wrap; }
/* ===== COLORS ===== */
.color-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 16px; }
.color-swatch {
border-radius: var(--radius-md); overflow: hidden;
border: 1px solid var(--color-border);
}
.color-swatch-block { height: 80px; }
.color-swatch-info { padding: 12px; background: var(--color-surface); }
.color-swatch-name { font-size: 14px; font-weight: 600; color: var(--color-heading); }
.color-swatch-hex { font-size: 12px; color: var(--color-muted); font-family: var(--font-mono), monospace; }
.color-swatch-role { font-size: 12px; color: var(--color-body); margin-top: 4px; }
/* ===== TYPOGRAPHY ===== */
.type-sample { margin-bottom: 24px; padding-bottom: 24px; border-bottom: 1px solid var(--color-border); }
.type-sample:last-child { border-bottom: none; }
.type-label { font-size: 11px; font-weight: 500; text-transform: uppercase; letter-spacing: 1px; color: var(--color-muted); margin-bottom: 4px; }
.type-meta { font-size: 12px; color: var(--color-muted); font-family: var(--font-mono), monospace; margin-top: 4px; }
/* ===== BUTTONS ===== */
.button-row { display: flex; gap: 16px; flex-wrap: wrap; align-items: center; margin-bottom: 24px; }
.btn {
display: inline-flex; align-items: center; justify-content: center;
padding: 10px 20px; border-radius: var(--radius-md);
font-size: 16px; font-weight: 500; font-family: inherit;
cursor: pointer; border: none; transition: all 0.15s ease;
}
.btn-primary { background: var(--color-primary); color: #fff; }
.btn-primary:hover { background: var(--color-primary-hover); }
.btn-ghost { background: transparent; color: var(--color-primary); border: 1px solid var(--color-border-active); }
.btn-ghost:hover { background: var(--color-surface-elevated); }
.btn-subtle { background: var(--color-surface-elevated); color: var(--color-heading); }
.btn-subtle:hover { opacity: 0.85; }
.btn-sm { padding: 6px 14px; font-size: 14px; }
.btn-label { font-size: 12px; color: var(--color-muted); min-width: 100px; }
/* ===== CARDS ===== */
.card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 24px; }
.card {
background: var(--color-surface);
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
padding: 24px;
}
.card-elevated { box-shadow: var(--shadow-standard); }
.card-deep { box-shadow: var(--shadow-elevated); }
.card h3 { font-size: 20px; font-weight: 500; color: var(--color-heading); margin-bottom: 8px; }
.card p { font-size: 14px; color: var(--color-body); line-height: 1.5; }
/* ===== BADGES ===== */
.badge-row { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 16px; }
.badge {
display: inline-flex; align-items: center;
padding: 2px 8px; border-radius: var(--radius-sm);
font-size: 12px; font-weight: 500;
}
.badge-success { background: rgba(21,190,83,0.15); color: var(--color-success); }
.badge-warning { background: rgba(245,166,35,0.15); color: var(--color-warning); }
.badge-error { background: rgba(220,38,38,0.15); color: var(--color-error); }
.badge-neutral { background: var(--color-surface-elevated); color: var(--color-body); }
/* ===== FORMS ===== */
.form-group { margin-bottom: 20px; max-width: 400px; }
.form-label { display: block; font-size: 14px; font-weight: 500; color: var(--color-heading); margin-bottom: 6px; }
.form-input {
width: 100%; padding: 10px 12px;
border: 1px solid var(--color-border); border-radius: var(--radius-md);
font-size: 14px; font-family: inherit; color: var(--color-heading);
background: var(--color-surface); outline: none; transition: border-color 0.15s;
}
.form-input:focus { border-color: var(--color-primary); box-shadow: 0 0 0 3px rgba(83,58,253,0.1); }
.form-input-error { border-color: var(--color-error); }
.form-hint { font-size: 12px; color: var(--color-muted); margin-top: 4px; }
.form-error { font-size: 12px; color: var(--color-error); margin-top: 4px; }
/* ===== SPACING ===== */
.spacing-scale { display: flex; gap: 16px; flex-wrap: wrap; align-items: flex-end; }
.spacing-item { text-align: center; }
.spacing-block { background: var(--color-primary); border-radius: 2px; opacity: 0.7; margin-bottom: 4px; }
.spacing-label { font-size: 11px; color: var(--color-muted); font-family: var(--font-mono), monospace; }
/* ===== BORDER RADIUS ===== */
.radius-grid { display: flex; gap: 24px; flex-wrap: wrap; }
.radius-item { text-align: center; }
.radius-block {
width: 80px; height: 80px;
background: var(--color-surface-elevated);
border: 2px solid var(--color-primary);
margin-bottom: 8px;
}
.radius-label { font-size: 12px; color: var(--color-muted); }
.radius-value { font-size: 11px; color: var(--color-muted); font-family: var(--font-mono), monospace; }
/* ===== ELEVATION ===== */
.elevation-grid { display: flex; gap: 32px; flex-wrap: wrap; }
.elevation-item { text-align: center; }
.elevation-block {
width: 120px; height: 80px;
background: var(--color-surface);
border-radius: var(--radius-md);
display: flex; align-items: center; justify-content: center;
font-size: 12px; color: var(--color-muted);
margin-bottom: 8px;
}
.elevation-label { font-size: 12px; color: var(--color-heading); font-weight: 500; }
.elevation-value { font-size: 11px; color: var(--color-muted); max-width: 140px; }
/* ===== FOOTER ===== */
.footer {
text-align: center; padding: 48px 32px;
font-size: 12px; color: var(--color-muted);
border-top: 1px solid var(--color-border);
}
/* ===== RESPONSIVE ===== */
@media (max-width: 768px) {
.hero h1 { font-size: 36px; letter-spacing: -0.8px; }
.hero p { font-size: 16px; }
section { padding: 40px 0; }
.container { padding: 0 16px; }
.color-grid { grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); }
.card-grid { grid-template-columns: 1fr; }
}
</style>
</head>
<body>
<!-- NAV -->
<nav class="nav">
<a href="#" class="nav-brand">{{BRAND_NAME}}</a>
<button class="nav-cta">Get Started</button>
</nav>
<!-- HERO -->
<div class="container">
<div class="hero">
<h1>{{BRAND_NAME}} Design System</h1>
<p>A comprehensive design system preview showcasing colors, typography, components, and spatial relationships.</p>
<div class="hero-buttons">
<button class="btn btn-primary">Primary Action</button>
<button class="btn btn-ghost">Secondary Action</button>
</div>
</div>
</div>
<!-- COLORS -->
<section>
<div class="container">
<div class="section-title">Color Palette</div>
<div class="color-grid">
<!--
For each color in Section 2 of the DESIGN.md, add a swatch:
<div class="color-swatch">
<div class="color-swatch-block" style="background: #HEX;"></div>
<div class="color-swatch-info">
<div class="color-swatch-name">Color Name</div>
<div class="color-swatch-hex">#HEX</div>
<div class="color-swatch-role">Role description</div>
</div>
</div>
-->
</div>
</div>
</section>
<!-- TYPOGRAPHY -->
<section>
<div class="container">
<div class="section-title">Typography Scale</div>
<!--
For each row in the Section 3 hierarchy table, add a sample:
<div class="type-sample">
<div class="type-label">ROLE NAME</div>
<div style="font-size: XXpx; font-weight: WGT; line-height: LH; letter-spacing: LS; color: var(--color-heading);">
The quick brown fox jumps over the lazy dog
</div>
<div class="type-meta">XXpx / weight WGT / line-height LH / letter-spacing LS</div>
</div>
-->
</div>
</section>
<!-- BUTTONS -->
<section>
<div class="container">
<div class="section-title">Buttons</div>
<div class="button-row">
<span class="btn-label">Primary</span>
<button class="btn btn-primary">Button</button>
<button class="btn btn-primary btn-sm">Small</button>
</div>
<div class="button-row">
<span class="btn-label">Ghost</span>
<button class="btn btn-ghost">Button</button>
<button class="btn btn-ghost btn-sm">Small</button>
</div>
<div class="button-row">
<span class="btn-label">Subtle</span>
<button class="btn btn-subtle">Button</button>
<button class="btn btn-subtle btn-sm">Small</button>
</div>
</div>
</section>
<!-- BADGES -->
<section>
<div class="container">
<div class="section-title">Badges & Tags</div>
<div class="badge-row">
<span class="badge badge-success">Success</span>
<span class="badge badge-warning">Warning</span>
<span class="badge badge-error">Error</span>
<span class="badge badge-neutral">Neutral</span>
</div>
</div>
</section>
<!-- CARDS -->
<section>
<div class="container">
<div class="section-title">Cards & Elevation</div>
<div class="card-grid">
<div class="card">
<h3>Flat Card</h3>
<p>A card with no shadow, using only border for definition. Suitable for dense layouts where elevation would be overwhelming.</p>
</div>
<div class="card card-elevated">
<h3>Elevated Card</h3>
<p>Standard shadow for interactive cards, content panels, and dropdowns. The primary card treatment for most use cases.</p>
</div>
<div class="card card-deep">
<h3>Deep Card</h3>
<p>Maximum elevation for modals, popovers, and hero feature cards. Use sparingly to maintain hierarchy.</p>
</div>
</div>
</div>
</section>
<!-- FORMS -->
<section>
<div class="container">
<div class="section-title">Form Inputs</div>
<div class="form-group">
<label class="form-label">Default Input</label>
<input class="form-input" type="text" placeholder="Enter a value..." />
<div class="form-hint">Helper text for this field</div>
</div>
<div class="form-group">
<label class="form-label">Focused Input</label>
<input class="form-input" type="text" value="Active value" autofocus />
</div>
<div class="form-group">
<label class="form-label">Error Input</label>
<input class="form-input form-input-error" type="text" value="Invalid value" />
<div class="form-error">This field has an error</div>
</div>
</div>
</section>
<!-- SPACING -->
<section>
<div class="container">
<div class="section-title">Spacing Scale</div>
<div class="spacing-scale">
<!--
For each value in the spacing scale, add a block:
<div class="spacing-item">
<div class="spacing-block" style="width: Xpx; height: Xpx;"></div>
<div class="spacing-label">Xpx</div>
</div>
-->
</div>
</div>
</section>
<!-- BORDER RADIUS -->
<section>
<div class="container">
<div class="section-title">Border Radius Scale</div>
<div class="radius-grid">
<!--
For each radius value, add a block:
<div class="radius-item">
<div class="radius-block" style="border-radius: Xpx;"></div>
<div class="radius-label">Category</div>
<div class="radius-value">Xpx</div>
</div>
-->
</div>
</div>
</section>
<!-- ELEVATION -->
<section>
<div class="container">
<div class="section-title">Shadow Elevation</div>
<div class="elevation-grid">
<!--
For each shadow level, add a block:
<div class="elevation-item">
<div class="elevation-block" style="box-shadow: SHADOW_VALUE;">Level N</div>
<div class="elevation-label">Level Name</div>
<div class="elevation-value">CSS value preview</div>
</div>
-->
</div>
</div>
</section>
<!-- FOOTER -->
<div class="footer">
Design System Preview — Generated from DESIGN.md
</div>
</body>
</html>
references/section-guide.md
# Section Guide: Writing Excellent DESIGN.md Sections
This guide explains what makes each of the 9 sections great, with common pitfalls to avoid.
## Table of Contents
1. [Visual Theme & Atmosphere](#1-visual-theme--atmosphere)
2. [Color Palette & Roles](#2-color-palette--roles)
3. [Typography Rules](#3-typography-rules)
4. [Component Stylings](#4-component-stylings)
5. [Layout Principles](#5-layout-principles)
6. [Depth & Elevation](#6-depth--elevation)
7. [Do's and Don'ts](#7-dos-and-donts)
8. [Responsive Behavior](#8-responsive-behavior)
9. [Agent Prompt Guide](#9-agent-prompt-guide)
---
## 1. Visual Theme & Atmosphere
**Purpose:** Set the emotional and philosophical foundation. An AI agent reading this section should immediately understand the *vibe* — is it playful or serious? Minimal or rich? Technical or warm?
**What makes it excellent:**
- Specific, not vague. "Clean white foundation with deep navy headings" beats "professional and modern."
- References actual values inline: mention hex codes, font names, specific weight choices.
- Explains *why* choices work, not just what they are. "Weight 300 creates ethereal, almost whispered authority" tells the agent how to interpret the weight.
- The Key Characteristics bullet list is a scannable summary — 7-8 items, each a distinct trait.
**Common pitfalls:**
- Generic adjectives without substance ("sleek", "modern", "clean" with no specifics)
- No hex codes or font names — the atmosphere section should ground the abstract in the concrete
- Key Characteristics that repeat what the paragraphs say instead of distilling new traits
---
## 2. Color Palette & Roles
**Purpose:** Give every color a name, a code, and a job. An agent should be able to look up "what color do I use for body text?" and get an exact answer.
**What makes it excellent:**
- Every color has a **descriptive, evocative name** — not "Blue 1" but "Midnight Navy" or "Signal Green"
- Colors grouped semantically: Primary, Accent, Surface, Neutral, Semantic, Border, Shadow
- Each entry follows the format: `- **Name** (\`#hex\`): Role description`
- Role descriptions are specific: "Primary heading color; dark blue adding warmth" not just "used for headings"
- Includes RGBA values for shadows and semi-transparent colors
- Gradients described with full CSS notation
- Complete coverage: every color visible on the site should appear here
**Common pitfalls:**
- Missing shadow colors — shadows are part of the palette
- Vague role descriptions ("accent color" — accent for what?)
- Colors without names (just hex codes)
- Forgetting semi-transparent variants (hover states, overlays, backdrop-filter colors)
- Not including enough neutrals — most sites use 4-6 shades of gray/neutral
**Naming colors well:**
Good names hint at both the color and its personality:
- "Carbon Dark" (dark, industrial feel)
- "Frosted Glass" (light, transparent, cool)
- "Emerald Signal" (green, attention-grabbing)
- "Warm Sand" (beige, comfortable, organic)
Avoid: "Primary Blue", "Secondary Gray", "Color A"
---
## 3. Typography Rules
**Purpose:** Define the complete type system so an agent can render any text element correctly.
**What makes it excellent:**
- Font Family subsection lists the full fallback stack
- The Hierarchy table includes ALL columns: Role, Font, Size, Weight, Line Height, Letter Spacing, Notes
- Size uses dual notation: `56px (3.50rem)` for both px and rem
- Line height as decimal: `1.10`, `1.40` (not percentage)
- Letter spacing in pixels: `-1.4px`, `0px`, `normal`
- Roles cover the full range: from Display Hero down to Micro/Nano, plus Code variants
- The Principles subsection explains the *why* — not just "use weight 300" but "light weight at display sizes creates understated authority rather than conventional bold impact"
- Notes about OpenType features (ss01, tnum, liga) when relevant
**Common pitfalls:**
- Missing the code/monospace font — if the site has any code, document its type treatment
- Only documenting 3-4 roles when the actual system has 10+
- Line height as percentage instead of decimal
- Missing letter-spacing (especially negative tracking at large sizes — this is critical for display type)
- Not mentioning font-feature-settings when the font uses them
---
## 4. Component Stylings
**Purpose:** Give the agent exact recipes for building UI components.
**What makes it excellent:**
- Each button variant is a named recipe: Primary CTA, Ghost, Tertiary, etc.
- Properties listed as bullets with `Property: \`value\`` format
- Includes hover/focus states — these define the interaction feel
- Cards include background, border, radius, shadow, and padding — the full recipe
- Inputs document all states: default, focus, error, disabled
- Navigation describes the full structure: sticky behavior, link treatment, CTA placement, mobile adaptation
- Distinctive Components section captures anything unique to this design system
**Common pitfalls:**
- Only documenting one button variant (most systems have 3-4)
- Missing hover states — interaction design matters
- Not documenting focus rings/outlines (accessibility)
- Generic card descriptions without actual shadow values
- Forgetting badges/tags/pills — these are common and have specific treatments
---
## 5. Layout Principles
**Purpose:** Define the spatial system — how things are sized, spaced, and arranged.
**What makes it excellent:**
- Base unit declared (usually 4px or 8px)
- Full spacing scale listed (not just the base unit)
- Grid documented: max width, columns, gutter
- Border Radius Scale as a table: Micro, Subtle, Standard, Comfortable, Large, Pill, Circle
- Whitespace Philosophy explains the *feel* of spacing — dense vs airy, symmetric vs asymmetric
**Common pitfalls:**
- Listing only the base unit without the full scale
- Missing border-radius scale — this strongly defines visual personality (sharp vs round)
- No max content width — agents need this to constrain layouts
---
## 6. Depth & Elevation
**Purpose:** Define how elements appear to stack in z-space.
**What makes it excellent:**
- Table with exact columns: Level, Treatment, Use
- 4-6 levels from Flat through Deep, plus Focus Ring for accessibility
- Treatment column contains complete CSS shadow values in backticks
- Multi-layer shadows documented as-is: `rgba(50,50,93,0.25) 0px 30px 45px -30px, rgba(0,0,0,0.1) 0px 18px 36px -18px`
- Shadow Philosophy explains the aesthetic: chromatic vs neutral, tight vs diffuse, how shadows tie to the color palette
**Common pitfalls:**
- Generic "light shadow" / "medium shadow" without actual values
- Missing the focus ring level (accessibility requirement)
- Not explaining *why* the shadow approach was chosen
- Forgetting that shadow colors are part of the brand palette
---
## 7. Do's and Don'ts
**Purpose:** Guardrails that prevent an agent from going off-brand. The most actionable section.
**What makes it excellent:**
- 7-10 items per list
- Every item references specific values: "Use `#061b31` for headings instead of pure black"
- Don'ts explain *why not*: "Don't use large border-radius (12px+) — the system relies on subtle 4-8px curves for precision feel"
- Items cover typography, color, spacing, shadows, and components
- Items are non-obvious — don't just repeat what earlier sections say. Focus on the mistakes an agent would actually make without this guidance.
**Common pitfalls:**
- Vague directives: "Use consistent spacing" (this says nothing)
- No specific values referenced
- Don'ts without reasoning
- Repeating obvious rules from earlier sections
---
## 8. Responsive Behavior
**Purpose:** Define how the design adapts across screen sizes.
**What makes it excellent:**
- Breakpoints table covers 4-5 sizes with Key Changes column
- Touch Targets section ensures mobile usability (44px minimum, etc.)
- Collapsing Strategy describes how each major component adapts
- Image Behavior covers responsive images, shadow treatment at mobile
**Common pitfalls:**
- Only defining 2 breakpoints (need at least 4: mobile, tablet, desktop, large)
- Missing touch target minimums
- Not describing how navigation collapses
- No guidance on typography scaling across breakpoints
---
## 9. Agent Prompt Guide
**Purpose:** The cheat sheet. An agent should be able to read just this section and produce on-brand components.
**What makes it excellent:**
- Quick Color Reference: simple key-value list with the 10 most important colors
- 5 Example Component Prompts that are complete, copy-paste-ready instructions: "Create a dark card: #181818 background, 8px radius. Title at 16px weight 700, white text..."
- Each prompt includes specific pixel values, colors, weights, and spacing
- Iteration Guide: 6-8 numbered steps for getting from zero to on-brand
**Common pitfalls:**
- Quick Reference that lists every single color (defeats the purpose — pick the top 10)
- Example prompts that are vague: "make a nice card" (needs exact values)
- Iteration Guide that's too abstract
- Not including enough prompts (5 is the target: hero, card, badge, nav, dark section)
---
## General Writing Tips
1. **Be specific over generic.** Every value should be something an AI agent can directly apply to CSS. Prefer `rgba(50,50,93,0.25) 0px 30px 45px -30px` over "subtle blue shadow."
2. **Name everything.** Colors, elevation levels, spacing values, button variants. Named things are memorable and referenceable.
3. **Explain the why.** When a design choice is non-obvious, a sentence of reasoning helps the agent make good judgment calls in edge cases.
4. **Maintain internal consistency.** If Section 2 defines a color as "Midnight Navy," Section 7 and 9 should use that same name. If Section 3 says heading weight is 300, Section 4's button descriptions shouldn't randomly use 600.
5. **Test the Agent Prompt Guide.** Read Section 9 in isolation — could you build a component from just those prompts? If not, the prompts need more specifics.
references/template.md
# Template: DESIGN.md
Use this as the structural scaffold when creating any DESIGN.md. Replace all `[bracketed]` placeholders with real values. Remove any placeholder sections that don't apply, but aim to fill all 9 sections.
---
# Design System Inspiration of [Brand/Project Name]
## 1. Visual Theme & Atmosphere
[2-3 paragraphs describing the design philosophy, mood, and visual identity. Reference specific hex values inline in backticks. Describe what makes this design system distinctive — its personality, the feeling it evokes, the principles driving its aesthetic choices. Mention the primary font and signature color by name.]
[Second paragraph expanding on the visual approach — how light/dark balance works, what the shadow philosophy communicates, how typography choices reinforce the brand personality.]
**Key Characteristics:**
- [Distinctive trait 1 — e.g., "Custom variable font with geometric OpenType alternates"]
- [Distinctive trait 2 — e.g., "Weight 300 as signature headline weight for understated authority"]
- [Distinctive trait 3 — e.g., "Blue-tinted chromatic shadows instead of neutral gray"]
- [Distinctive trait 4 — e.g., "Deep navy (`#061b31`) headings instead of pure black"]
- [Distinctive trait 5 — e.g., "Conservative border-radius (4px-8px) for precision feel"]
- [Distinctive trait 6 — e.g., "Alternating light/dark section rhythm"]
- [Distinctive trait 7 — e.g., "Monospace companion font for code and data"]
## 2. Color Palette & Roles
### Primary
- **[Primary Color Name]** (`[#hex]`): [Role — e.g., "Primary brand color, CTA backgrounds, link text, interactive highlights"]
- **[Secondary Primary Name]** (`[#hex]`): [Role — e.g., "Primary heading color; dark warm neutral"]
- **[Tertiary Primary Name]** (`[#hex]`): [Role — e.g., "Page background, card surfaces, button text on primary"]
### Secondary & Accent
- **[Accent Color 1 Name]** (`[#hex]`): [Role and usage context]
- **[Accent Color 2 Name]** (`[#hex]`): [Role and usage context]
- **[Accent Light Name]** (`[#hex]`): [Role — tinted surface variant]
### Surface & Background
- **[Background Name]** (`[#hex]`): [Role — e.g., "Primary page background"]
- **[Surface Name]** (`[#hex]`): [Role — e.g., "Card and container background"]
- **[Elevated Surface Name]** (`[#hex]`): [Role — e.g., "Hover state backgrounds, subtle highlights"]
### Neutrals & Text
- **[Heading Text Name]** (`[#hex]`): [Role — primary headings and nav text]
- **[Label Text Name]** (`[#hex]`): [Role — form labels and secondary headings]
- **[Body Text Name]** (`[#hex]`): [Role — secondary text and descriptions]
- **[Muted Text Name]** (`[#hex]`): [Role — captions, timestamps, placeholder text]
### Semantic & Status
- **[Success Name]** (`[#hex]`): [Role — success indicators, positive actions]
- **[Warning Name]** (`[#hex]`): [Role — warnings, caution states]
- **[Error Name]** (`[#hex]`): [Role — errors, destructive actions]
- **[Info Name]** (`[#hex]`): [Role — informational highlights]
### Borders & Dividers
- **[Default Border Name]** (`[#hex]`): [Role — standard border for cards and containers]
- **[Active Border Name]** (`[#hex]`): [Role — selected/focused state borders]
- **[Subtle Border Name]** (`[#hex]`): [Role — dividers, light separators]
### Shadow Colors
- **[Primary Shadow Name]** (`[rgba value]`): [Role — primary branded shadow]
- **[Secondary Shadow Name]** (`[rgba value]`): [Role — secondary depth layer]
- **[Ambient Shadow Name]** (`[rgba value]`): [Role — soft ambient lift]
### Gradient System
- [Describe gradient patterns, e.g., "Linear gradient from `#ea2261` to `#f96bee` for hero decorations"]
- [Additional gradient if applicable]
## 3. Typography Rules
### Font Family
- **Primary**: `[font-name]` with fallback `[fallback-stack]`
- **Secondary**: `[font-name]` with fallback `[fallback-stack]` (if applicable)
- **Monospace**: `[font-name]` with fallback `[fallback-stack]` (if applicable)
- **OpenType Features**: [e.g., `"ss01"` globally, `"tnum"` for tabular numbers]
### Hierarchy
| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
|------|------|------|--------|-------------|----------------|-------|
| Display Hero | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | [Xpx] | [notes] |
| Display Large | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | [Xpx] | |
| Section Heading | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | [Xpx] | |
| Sub-heading | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | [Xpx] | |
| Body Large | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | normal | |
| Body | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | normal | |
| Button | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | normal | |
| Link | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | normal | |
| Caption | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | normal | |
| Small / Micro | [font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | [Xpx] | |
| Code | [mono-font] | [XX]px ([X.XX]rem) | [weight] | [X.XX] | normal | |
### Principles
- [Principle 1 — e.g., "Light weight at display sizes for understated authority"]
- [Principle 2 — e.g., "Letter-spacing tightens progressively with size increases"]
- [Principle 3 — e.g., "Two-weight system: 300 for content, 400 for interactive elements"]
- [Principle 4 — e.g., "Monospace font reserved for code blocks and data tables"]
## 4. Component Stylings
### Buttons
**Primary CTA**
- Background: `[#hex]`
- Text: `[#hex]`
- Padding: [X]px [X]px
- Radius: [X]px
- Font: [X]px [font] weight [X]
- Hover: [hover treatment]
- Use: [when to use this variant]
**Secondary / Ghost**
- Background: transparent
- Text: `[#hex]`
- Padding: [X]px [X]px
- Radius: [X]px
- Border: `[border value]`
- Hover: [hover treatment]
- Use: [when to use]
**Tertiary / Subtle**
- Background: transparent or `[#hex]`
- Text: `[#hex]`
- Padding: [X]px [X]px
- Radius: [X]px
- Border: `[border value]`
- Use: [when to use]
### Cards & Containers
- Background: `[#hex]`
- Border: `[border value]`
- Radius: [X]px
- Shadow: `[full CSS shadow value]`
- Padding: [X]px
- [Additional card variants if applicable]
### Badges / Tags / Pills
**[Variant Name]**
- Background: `[#hex or rgba]`
- Text: `[#hex]`
- Padding: [X]px [X]px
- Radius: [X]px
- Border: `[border value]`
- Font: [X]px weight [X]
### Inputs & Forms
- Border: `[border value]`
- Radius: [X]px
- Focus: `[focus ring/border value]`
- Error: `[error state treatment]`
- Label: `[#hex]`, [X]px [font]
- Input Text: `[#hex]`
- Placeholder: `[#hex]`
### Navigation
- [Describe nav structure — horizontal/vertical, sticky behavior]
- Brand: [logo/logotype placement]
- Links: [X]px [font] weight [X], `[#hex]`
- CTA: [describe nav CTA treatment]
- Mobile: [hamburger/drawer/bottom nav]
### Image Treatment
- [Border-radius for images]
- [Shadow treatment]
- [Aspect ratio conventions]
### Distinctive Components
[Describe any unique components specific to this design system — code blocks, pricing cards, testimonial cards, feature grids, etc.]
## 5. Layout Principles
### Spacing System
- Base unit: [X]px
- Scale: [list the full spacing scale, e.g., "2px, 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px"]
- Component padding: [describe padding conventions]
- Section spacing: [describe vertical rhythm between sections]
### Grid & Container
- Max content width: [X]px
- Column count: [X] columns
- Gutter: [X]px
- Hero: [describe hero layout]
- Content sections: [describe typical section layouts]
### Whitespace Philosophy
- [Principle 1 — e.g., "Generous whitespace around headlines creates breathing room"]
- [Principle 2 — e.g., "Dense data packing with spacious chrome surroundings"]
- [Principle 3 — e.g., "Section padding increases with viewport width"]
- [Principle 4 — e.g., "Asymmetric padding — more top than bottom to create forward momentum"]
### Border Radius Scale
| Category | Radius | Use |
|----------|--------|-----|
| Micro | [X]px | [use case] |
| Subtle | [X]px | [use case] |
| Standard | [X]px | [use case] |
| Comfortable | [X]px | [use case] |
| Large | [X]px | [use case] |
| Pill | [X]px or 9999px | [use case] |
| Circle | 50% | [use case] |
## 6. Depth & Elevation
| Level | Treatment | Use |
|-------|-----------|-----|
| Flat (Level 0) | No shadow | [use case] |
| Subtle (Level 1) | `[shadow value]` | [use case] |
| Standard (Level 2) | `[shadow value]` | [use case] |
| Elevated (Level 3) | `[shadow value]` | [use case] |
| Deep (Level 4) | `[shadow value]` | [use case] |
| Focus Ring | `[outline/ring value]` | Keyboard accessibility |
**Shadow Philosophy**: [2-3 sentences about the shadow approach — are shadows warm/cool/neutral? Single or multi-layer? What mood do they create? How do they tie to the color palette?]
### Decorative Depth
- [Describe any non-shadow depth techniques — gradient overlays, dark sections, backdrop-filter, etc.]
## 7. Do's and Don'ts
### Do
- [Specific directive referencing actual values — e.g., "Use `#061b31` for headings instead of pure black"]
- [Directive 2]
- [Directive 3]
- [Directive 4]
- [Directive 5]
- [Directive 6]
- [Directive 7]
### Don't
- [Specific prohibition with reasoning — e.g., "Don't use weight 700 for headlines — the system relies on light weights"]
- [Prohibition 2]
- [Prohibition 3]
- [Prohibition 4]
- [Prohibition 5]
- [Prohibition 6]
- [Prohibition 7]
## 8. Responsive Behavior
### Breakpoints
| Name | Width | Key Changes |
|------|-------|-------------|
| Mobile Small | <[X]px | [changes] |
| Mobile | [X]-[X]px | [changes] |
| Tablet | [X]-[X]px | [changes] |
| Desktop | [X]-[X]px | [changes] |
| Large Desktop | >[X]px | [changes] |
### Touch Targets
- [Minimum size guideline]
- [Button padding on mobile]
- [Link spacing on mobile]
- [Interactive element guidelines]
### Collapsing Strategy
- [How hero adapts — font size changes]
- [How navigation adapts — hamburger/drawer]
- [How grids collapse — column count changes]
- [How spacing reduces]
- [How images behave]
### Image Behavior
- [Responsive image approach]
- [Shadow treatment at mobile sizes]
- [Aspect ratio handling]
- [Loading behavior]
## 9. Agent Prompt Guide
### Quick Color Reference
- Background: [Name] (`[#hex]`)
- Surface: [Name] (`[#hex]`)
- Primary: [Name] (`[#hex]`)
- Accent: [Name] (`[#hex]`)
- Heading text: [Name] (`[#hex]`)
- Body text: [Name] (`[#hex]`)
- Border: [Name] (`[#hex]`)
- Link: [Name] (`[#hex]`)
- Success: [Name] (`[#hex]`)
- Error: [Name] (`[#hex]`)
### Example Component Prompts
- "[Complete prompt for creating a hero section with specific values from this system]"
- "[Complete prompt for creating a card component with shadow, border, typography values]"
- "[Complete prompt for creating a badge/tag with exact colors, padding, radius]"
- "[Complete prompt for creating a navigation bar with font, color, layout values]"
- "[Complete prompt for creating a dark/branded section with background, text colors, card treatment]"
### Iteration Guide
1. [Step for establishing base tokens — fonts, colors]
2. [Step for typography scale]
3. [Step for shadows and elevation]
4. [Step for component tokens]
5. [Step for heading vs body color distinction]
6. [Step for data/number formatting]
7. [Step for dark/branded sections]
8. [Step for code/monospace treatment]