| name | cavekit-design-system |
| description | How to write and maintain DESIGN.md as the visual specification layer for Cavekit projects. Nine-section format, design tokens, accessibility, integration with kits/plans. Use when defining or revising visual identity, importing a third-party design system, or auditing UI code against design tokens. |
| allowed-tools | ["read","grep","edit"] |
| effort | medium |
Design System: DESIGN.md for AI Agents
Core Principle: DESIGN.md Describes WHAT It Looks Like, Not HOW to Build It
DESIGN.md is the visual equivalent of kits. It defines the project's visual language — colors, typography, spacing, components, responsive behavior — in a format AI agents can read and apply consistently. It is a parallel constraint layer that all Hunt phases consult.
| Document | Defines | Audience |
|---|
| CLAUDE.md | How to build the project | Coding agents |
| Kits | What must be true (behavior) | All agents |
| DESIGN.md | What it looks like (visual) | UI-building agents |
| Plans | How to build it (tasks) | Builder agents |
Why a Dedicated Design System Document?
Without DESIGN.md, visual decisions scatter across kits, plans, and code:
- Colors get hardcoded differently per component
- Typography choices vary between agents and sessions
- Spacing becomes inconsistent across the UI
- New components reinvent patterns that already exist
DESIGN.md centralizes these decisions. Every agent reads it before writing UI code.
The 9-Section Stitch Format
DESIGN.md follows the Google Stitch format — 9 sections that together define a complete visual language. Every DESIGN.md must contain all 9 sections.
Section 1: Visual Theme & Atmosphere
The design philosophy, mood, and overall aesthetic. Use evocative, specific language — not generic terms like "clean and modern."
## 1. Visual Theme & Atmosphere
This is a warm editorial experience built on natural materials. Think: a well-curated
bookshop with soft overhead lighting and carefully chosen display shelves. The density
is low — generous whitespace signals confidence and clarity. Every element earns its
place; nothing decorative exists without functional purpose.
**Key attributes:** Warm, unhurried, editorial, confident
**Density:** Low — generous whitespace, single-column focus
**Personality:** Thoughtful librarian, not flashy storefront
What good looks like: A new designer reading this section could sketch a rough layout without seeing any other section.
Anti-pattern: "Clean, modern, and professional" — this describes nothing specific.
Section 2: Color Palette & Roles
Every color needs three things: a semantic name, a hex value, and a functional role.
## 2. Color Palette & Roles
### Primary
| Name | Hex | Role |
|------|-----|------|
| Terracotta Brand | #c96442 | Primary CTA, active states, brand anchors |
| Terracotta Hover | #b85838 | Hover/pressed state for primary actions |
### Neutral
| Name | Hex | Role |
|------|-----|------|
| Near Black | #141413 | Primary text, headings |
| Olive Gray | #5e5d59 | Secondary text, captions |
| Parchment | #f5f4ed | Page background, default canvas |
| Ivory White | #ffffff | Card surfaces, overlays |
### Semantic
| Name | Hex | Role |
|------|-----|------|
| Success Green | #2d7d46 | Confirmation, success states |
| Warning Amber | #c27217 | Warnings, attention needed |
| Error Red | #c24132 | Errors, destructive actions |
| Info Blue | #3b6fb5 | Informational states, links |
### Dark Mode (if applicable)
| Light Name | Dark Equivalent | Hex |
|------------|----------------|-----|
| Parchment | Deep Charcoal | #1a1a1a |
| Near Black | Off White | #e8e8e8 |
Rules:
- Every hex value must be verified against the actual design or live site
- Every color must have a clear functional role — no orphan colors
- Name colors semantically (by role), not by hue ("Primary CTA" not "Orange")
- If dark mode exists, map every light color to its dark equivalent
Section 3: Typography Rules
Complete type hierarchy with specific values — no "roughly 16px" or "medium weight."
## 3. Typography Rules
### Font Stack
- **Display/Heading:** "Anthropic Serif", Georgia, "Times New Roman", serif
- **Body:** "Anthropic Sans", -apple-system, BlinkMacSystemFont, sans-serif
- **Code:** "Anthropic Mono", "SF Mono", "Fira Code", monospace
### Type Scale
| Level | Size | Weight | Line Height | Letter Spacing | Font |
|-------|------|--------|-------------|----------------|------|
| H1 | 48px / 3rem | 500 | 1.10 | -0.02em | Serif |
| H2 | 36px / 2.25rem | 500 | 1.15 | -0.01em | Serif |
| H3 | 24px / 1.5rem | 500 | 1.25 | 0 | Serif |
| H4 | 20px / 1.25rem | 600 | 1.30 | 0 | Sans |
| Body | 16px / 1rem | 400 | 1.60 | 0 | Sans |
| Small | 14px / 0.875rem | 400 | 1.50 | 0.01em | Sans |
| Caption | 12px / 0.75rem | 500 | 1.40 | 0.02em | Sans |
### Principles
- Headings use serif for warmth and authority
- Body text uses sans-serif for readability at small sizes
- Maximum line length: 65ch for body text
- Minimum font size: 14px (never go below)
Rules:
- Every level in the scale must have all 5 values (size, weight, line-height, letter-spacing, font)
- Use rem alongside px for accessibility
- Include font stack fallbacks
Section 4: Component Stylings
Concrete styling for common components including interaction states.
## 4. Component Stylings
### Buttons
**Primary:**
- Background: Terracotta Brand (#c96442)
- Text: Ivory White (#ffffff), 16px Sans, weight 500
- Padding: 12px 24px
- Border radius: 8px
- Hover: Terracotta Hover (#b85838), translateY(-1px), shadow-sm
- Active: translateY(0), shadow-none
- Disabled: opacity 0.5, cursor not-allowed
- Transition: all 150ms ease-out
**Secondary:**
- Background: transparent
- Border: 1px solid Olive Gray (#5e5d59)
- Text: Near Black (#141413)
- Hover: background Parchment (#f5f4ed)
### Cards
- Background: Ivory White (#ffffff)
- Border: 1px solid rgba(0,0,0,0.06)
- Border radius: 12px
- Padding: 24px
- Shadow: 0 1px 3px rgba(0,0,0,0.04)
- Hover: shadow 0 4px 12px rgba(0,0,0,0.08), translateY(-2px)
### Inputs
- Border: 1px solid #d0d0d0
- Border radius: 8px
- Padding: 10px 14px
- Focus: border Terracotta Brand, ring 2px rgba(201,100,66,0.2)
- Error: border Error Red, ring 2px rgba(194,65,50,0.2)
### Navigation
...
Rules:
- Include hover, focus, active, and disabled states
- Specify transition durations and easing
- Include touch-target minimum sizes (44x44px)
Section 5: Layout Principles
Spacing system, grid, containers, and whitespace philosophy.
## 5. Layout Principles
### Spacing Scale (base: 4px)
| Token | Value | Usage |
|-------|-------|-------|
| space-1 | 4px | Tight gaps, icon margins |
| space-2 | 8px | Related element spacing |
| space-3 | 12px | Component internal padding |
| space-4 | 16px | Standard gap between elements |
| space-6 | 24px | Section padding, card padding |
| space-8 | 32px | Between major sections |
| space-12 | 48px | Page-level vertical rhythm |
| space-16 | 64px | Hero/banner spacing |
### Grid
- Max content width: 1200px
- Column count: 12
- Gutter: 24px (space-6)
- Margin: 16px mobile, 24px tablet, auto desktop
### Border Radius Scale
| Token | Value | Usage |
|-------|-------|-------|
| radius-sm | 4px | Badges, tags |
| radius-md | 8px | Buttons, inputs |
| radius-lg | 12px | Cards, panels |
| radius-xl | 16px | Modals, dialogs |
| radius-full | 9999px | Avatars, pills |
Section 6: Depth & Elevation
Shadow system and visual layering.
## 6. Depth & Elevation
### Shadow Scale
| Level | Value | Usage |
|-------|-------|-------|
| shadow-none | none | Flat elements |
| shadow-sm | 0 1px 2px rgba(0,0,0,0.04) | Subtle lift (cards at rest) |
| shadow-md | 0 4px 12px rgba(0,0,0,0.08) | Hover states, active cards |
| shadow-lg | 0 8px 24px rgba(0,0,0,0.12) | Dropdowns, popovers |
| shadow-xl | 0 16px 48px rgba(0,0,0,0.16) | Modals, dialogs |
### Surface Hierarchy
1. **Base** — page background (Parchment)
2. **Raised** — cards, panels (Ivory White + shadow-sm)
3. **Floating** — dropdowns, tooltips (Ivory White + shadow-lg)
4. **Overlay** — modals, dialogs (Ivory White + shadow-xl + scrim)
Section 7: Do's and Don'ts
Concrete examples with code — not just prose rules.
## 7. Do's and Don'ts
### DO: Use semantic color names
```css
/* Good */
.button-primary { background: var(--color-terracotta-brand); }
DON'T: Hardcode color values
.button-primary { background: #c96442; }
DO: Follow the spacing scale
.card { padding: var(--space-6); margin-bottom: var(--space-8); }
DON'T: Use arbitrary spacing
.card { padding: 19px; margin-bottom: 37px; }
DO: Include all interaction states
DON'T: Skip hover/focus states on interactive elements
DO: Use the type scale for all text
DON'T: Introduce new font sizes not in the scale
### Section 8: Responsive Behavior
Breakpoints, mobile patterns, and adaptation rules.
```markdown
## 8. Responsive Behavior
### Breakpoints
| Name | Width | Target |
|------|-------|--------|
| mobile | < 640px | Phones |
| tablet | 640–1024px | Tablets, small laptops |
| desktop | > 1024px | Laptops, monitors |
### Touch Targets
- Minimum interactive element size: 44x44px
- Minimum spacing between targets: 8px
### Mobile Adaptations
- Navigation collapses to hamburger menu below 640px
- Cards stack single-column below 640px
- Font sizes: H1 reduces to 32px on mobile, H2 to 28px
- Side padding: 16px on mobile, 24px tablet, auto-center desktop
### Behavior Patterns
- Horizontal scrolling: never (use stacking or truncation)
- Images: responsive with srcset, max-width: 100%
- Tables: horizontal scroll wrapper below tablet breakpoint
Section 9: Agent Prompt Guide
How AI agents should use this document when generating UI.
## 9. Agent Prompt Guide
### Quick Reference
- Primary CTA color: Terracotta Brand (#c96442)
- Background: Parchment (#f5f4ed)
- Heading font: Serif, weight 500
- Body font: Sans, weight 400
- Standard spacing: 24px (space-6)
- Card radius: 12px (radius-lg)
### How to Use This Document
1. Before writing any UI code, read the full DESIGN.md
2. Reference specific section names when implementing: "Following Section 4: Buttons"
3. Use design token names in CSS (var(--color-terracotta-brand)), not raw hex values
4. Check Section 7 (Do's and Don'ts) before submitting
5. If a component is not covered, create it following existing patterns and flag for DESIGN.md update
### Example Component Prompt
"Create a hero section on Parchment (#f5f4ed) with a headline at H1 scale
(48px Serif weight 500, line-height 1.10). Use Near Black (#141413) text.
Add a subtitle in Olive Gray (#5e5d59) at Body scale (16px Sans, line-height 1.60).
Place a Terracotta Brand (#c96442) primary button with Ivory text, radius-md (8px)."
### Iteration Guide
- Change one component at a time
- Reference specific color names and token values
- Describe the component's state (default, hover, active, disabled)
- Specify responsive behavior for the component
Design Token Conventions
Tokens are the bridge between DESIGN.md and code. Consistent naming ensures agents can translate design specs into CSS/Tailwind variables.
Naming Pattern
--{category}-{name}[-{modifier}]
| Category | Examples |
|---|
color- | --color-terracotta-brand, --color-near-black, --color-success-green |
space- | --space-1, --space-4, --space-8 |
text- | --text-h1, --text-body, --text-caption |
radius- | --radius-sm, --radius-md, --radius-lg |
shadow- | --shadow-sm, --shadow-md, --shadow-lg |
font- | --font-serif, --font-sans, --font-mono |
Mapping to CSS Custom Properties
DESIGN.md tokens map directly to CSS custom properties:
:root {
--color-terracotta-brand: #c96442;
--space-6: 24px;
--radius-lg: 12px;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.04);
}
Mapping to Tailwind
When using Tailwind, DESIGN.md tokens map to tailwind.config.js extensions. The builder agent should configure this once and reference throughout.
Integration with Kits
When DESIGN.md exists and kits contain UI requirements, acceptance criteria should reference design tokens by section and name. This creates a traceable chain:
DESIGN.md → Cavekit acceptance criterion → Plan task → Implementation
How to Reference
| In Cavekit Acceptance Criteria | Design Reference |
|---|
| "CTA button uses primary brand styling" | DESIGN.md Section 4: Buttons, primary variant |
| "Headings follow the type hierarchy" | DESIGN.md Section 3: Type Scale |
| "Cards have subtle resting elevation" | DESIGN.md Section 6: shadow-sm |
| "Layout uses the standard grid" | DESIGN.md Section 5: Grid |
| "Colors adapt for dark mode" | DESIGN.md Section 2: Dark Mode mapping |
Do NOT duplicate DESIGN.md content into kits. Reference by section/token name only. If a color changes in DESIGN.md, kits should not need updating.
When No Design Reference Exists
If a cavekit needs a visual pattern not in DESIGN.md, the acceptance criterion should note this:
- [ ] Component uses a card-like container [DESIGN.md: pattern not yet defined — flag for design update]
This tells the inspect phase to check whether DESIGN.md needs a new pattern.
Integration with Plans (Architect Phase)
When the architect generates task descriptions for UI work, each task should include:
**Design Reference:** DESIGN.md Section {N} — {section name}
This tells the task-builder which DESIGN.md sections to read before implementing.
Integration with Build Phase
Task-builder agents follow this protocol for UI work:
- Before implementing: Read DESIGN.md (or the specific sections referenced in the task)
- During implementation: Use design tokens, not hardcoded values
- In commit messages: Note which DESIGN.md sections were followed
- If a new pattern is needed: Implement it following existing DESIGN.md conventions and flag for design update
Revision Patterns
When visual fixes are made manually (outside the Hunt loop), /ck:revise traces them back to DESIGN.md:
Visual Fix Classification
| Fix Type | DESIGN.md Action |
|---|
| Color change that should apply globally | Update DESIGN.md Section 2 with corrected value |
| New component pattern not in DESIGN.md | Add to DESIGN.md Section 4 |
| Spacing adjustment revealing wrong scale | Update DESIGN.md Section 5 scale |
| Typography fix | Update DESIGN.md Section 3 type scale |
| Responsive behavior change | Update DESIGN.md Section 8 |
Revision Protocol
- Identify the visual change in the diff
- Check if DESIGN.md covers this pattern
- If not covered: add the pattern to the appropriate section
- If covered but wrong: update the token/value
- Log the change to
context/designs/design-changelog.md
Collection Import
The awesome-design-md repository contains 54+ curated design systems extracted from real products. These serve as starting points.
Import Workflow
- Choose a template:
vercel, claude, stripe, github, linear, etc.
- Fetch the raw DESIGN.md from the collection
- Present to the user as a starting point — not a finished product
- Walk through each section for customization (brand colors, typography, specific component needs)
- Write the customized version to project root
After Import
The imported DESIGN.md becomes the project's own. Future updates are made directly — the import is a seed, not a dependency.
Quality Standards
Completeness Checklist
Specificity Requirements
Every value in DESIGN.md must be concrete and unambiguous:
| Too Vague | Specific Enough |
|---|
| "a warm blue" | #3b6fb5 (Info Blue) |
| "medium spacing" | 24px (space-6) |
| "slightly rounded" | 8px (radius-md) |
| "subtle shadow" | 0 1px 2px rgba(0,0,0,0.04) (shadow-sm) |
| "large heading" | 48px / 3rem, weight 500, line-height 1.10 |
Consistency Rules
- Tokens used in Section 4 (Components) must exist in Sections 2, 3, 5, 6
- Dark mode mappings must cover every color used in components
- Responsive changes must reference defined breakpoints
- All spacing values must be multiples of the base unit
Anti-Patterns
- Generic atmosphere — "Clean, modern, professional" describes every SaaS app and none
- Missing interaction states — A button without hover/focus is incomplete
- Orphan colors — Colors defined in the palette but never used in components
- Arbitrary spacing — Values that don't follow the spacing scale
- Missing dark mode — If the app supports dark mode, every light color needs a mapping
- Hex-only references in components — Use semantic names, not raw values
- No Agent Prompt Guide — Section 9 is what makes DESIGN.md actionable for AI agents
- Duplicating DESIGN.md into kits — Reference by section/token name only
