DESIGN.md: Visual Design System and Token Reference

DESIGN.md is the visual design system file for projects with a user interface. It exists as a single, version-controlled document that both humans and AI agents can read: the first half is machine-readable YAML design tokens; the second half is human-readable prose that explains the intent behind those tokens. When the AI needs to create a new UI component, it reads this file first and extrapolates coherently from the established system rather than inventing a new visual direction.

DESIGN.md applies to any project with a user interface — web, mobile, or desktop. For projects without a UI (CLI tools, libraries, background services), this file can be omitted entirely. If the project has a UI and this file does not yet exist, the AI creates and fills it during the /spec phase.

📐 Inspired by the design.md open standard from Google Labs — an open format for describing visual identities to AI coding agents.

Document Header

# 🎨 Design System: [Project Name]

> **Phase:** `/spec` (Visual Specification)
> **Status:** Draft / Validated
> **Last Revision:** [Date]
> **Applies to:** Projects with user interface (web, mobile, desktop).
>                 Optional for projects without UI.

Part 1: YAML Design Tokens

The first half of DESIGN.md is a YAML block that contains all design tokens. These are the atomic values — colors, sizes, spacing — from which all components are built. The AI reads these tokens when generating or reviewing UI code, ensuring visual consistency without re-interpreting design intent on every task. Below is the complete token structure with all categories:

# ────────────────────────────────────────────────
# DESIGN TOKENS — Machine and AI readable
# ────────────────────────────────────────────────
version: alpha
name: "[Project Name]"
description: "[Brief description of the visual style. E.g.: Editorial
  minimalism with emphasis on clarity and contrast.]"

# COLORS
# Use HEX codes. The "on-X" field is the text color that goes on top of "X".
colors:
  primary:      "#[hex]"   # Primary brand color
  secondary:    "#[hex]"   # Secondary / complementary color
  accent:       "#[hex]"   # Call-to-action color (CTAs, highlights)
  neutral:      "#[hex]"   # Base neutral background
  surface:      "#[hex]"   # Background for cards and containers
  on-primary:   "#[hex]"   # Text on "primary" (usually white or very light)
  on-surface:   "#[hex]"   # Primary text on "surface"
  on-neutral:   "#[hex]"   # Secondary / muted text
  error:        "#[hex]"   # Red for errors and destructive alerts
  success:      "#[hex]"   # Green for confirmations and success states
  warning:      "#[hex]"   # Yellow/orange for warnings

# DARK MODE — Optional but recommended
# Only define overrides. Unlisted tokens inherit their light-mode values.
dark:
  primary:      "#[hex]"
  secondary:    "#[hex]"
  accent:       "#[hex]"
  neutral:      "#[hex]"   # e.g., "#111111" — main dark background
  surface:      "#[hex]"   # e.g., "#1E1E1E" — cards on dark background
  on-primary:   "#[hex]"
  on-surface:   "#[hex]"
  on-neutral:   "#[hex]"

# TYPOGRAPHY
# fontFamily: exact Google Fonts name or system font name.
typography:
  heading:
    fontFamily: "[e.g., Inter]"
    fontSize:   2rem
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: "-0.02em"
  subheading:
    fontFamily: "[e.g., Inter]"
    fontSize:   1.25rem
    fontWeight: 600
    lineHeight: 1.3
  body:
    fontFamily: "[e.g., Inter]"
    fontSize:   1rem
    fontWeight: 400
    lineHeight: 1.6
  label:
    fontFamily: "[e.g., Inter]"
    fontSize:   0.875rem
    fontWeight: 500
    letterSpacing: "0.01em"
  caption:
    fontFamily: "[e.g., Inter]"
    fontSize:   0.75rem
    fontWeight: 400

# BORDERS AND RADII
rounded:
  none: 0px
  sm:   4px
  md:   8px
  lg:   16px
  xl:   24px
  full: 9999px

# SPACING (4px base scale)
spacing:
  xs:  4px
  sm:  8px
  md:  16px
  lg:  24px
  xl:  48px
  xxl: 96px

# COMPONENTS — Token-to-UI-element mapping
# Use {path.to.token} references to guarantee consistency.
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor:       "{colors.on-primary}"
    typography:      "{typography.label}"
    rounded:         "{rounded.md}"
    padding:         "12px 24px"
  button-primary-hover:
    backgroundColor: "{colors.primary}"
  button-secondary:
    backgroundColor: "transparent"
    textColor:       "{colors.accent}"
    rounded:         "{rounded.md}"
    padding:         "12px 24px"
    border:          "1.5px solid {colors.accent}"
  card:
    backgroundColor: "{colors.surface}"
    rounded:         "{rounded.lg}"
    padding:         "{spacing.lg}"
  input:
    backgroundColor: "{colors.surface}"
    textColor:       "{colors.on-surface}"
    rounded:         "{rounded.md}"
    padding:         "10px 14px"
    border:          "1px solid {colors.on-neutral}"
  input-focus:
    border:          "2px solid {colors.accent}"

Token Categories Explained

Category	Purpose
`colors`	Full color palette with semantic naming. The `on-X` convention ensures accessible text contrast is always explicit.
`dark`	Dark mode overrides only. Tokens not listed here inherit their light-mode values, avoiding duplication.
`typography`	Five text styles covering all standard UI text roles. Headings use negative tracking (`-0.02em`) for a premium feel; body uses `lineHeight: 1.6` for readability.
`rounded`	Six border-radius steps from `0px` to `9999px` (full pill shape).
`spacing`	Six-step scale based on a 4px grid, covering everything from tight inline spacing to full-section margins.
`components`	Pre-assembled token combinations for the most common UI elements. References use `{path}` notation to stay in sync with token changes automatically.

Part 2: Prose Sections

The prose half of DESIGN.md explains the reasoning behind the tokens. This is where the designer’s intent lives — the “why” that the YAML cannot express.

Visual Overview

A 2–3 sentence description of the interface’s emotional register and design philosophy. Example:

“The interface combines editorial minimalism with touches of warmth. Every element communicates clarity and confidence, evoking the best professional SaaS tools. The user should feel they are using something built to last.”

Colors

Explain the role of each color and how it should (and should not) be used:

Primary — Main brand color. Use in headers and key navigation elements. Never as a full-page background.
Secondary — Supporting color for borders, secondary states, and supporting elements.
Accent — The single engine of interaction. All CTAs, links, and active elements use this color. Reserve it for actions, not decoration.
Neutral — Base for all pages. Warmer than pure white to reduce visual fatigue.
Surface — For cards, modals, and panels that lift content above the neutral background.
Error / Success / Warning — Semantic feedback colors only. Never use these as decoration.

Dark Mode strategy: Describe whether dark mode is a full inversion, a custom palette, or a selective override. Example: “Backgrounds use deep grays (not pure black) to avoid halos. Brand colors are maintained but with increased luminosity to meet WCAG AA contrast on dark surfaces.”

Typography

Justify the font choices and explain the scale:

Primary font — e.g., Inter, chosen for screen readability at all sizes and a wide weight family.
Fallback — e.g., System UI for instant loading without layout shift.
Scale — The typographic scale follows a 1.25 modular progression. Headings use negative tracking for a premium appearance. Body uses lineHeight: 1.6 for maximum readability.
Prohibitions — e.g., Never mix more than 2 font families. Never use font-weight: 300 for text under 16px on a dark background.

Key Components

Describe design decisions for the most important components: Buttons

Primary — Accent background, white text, rounded.md. One per screen. It is the shout — only one element should shout.
Secondary — Transparent with accent border. For important but non-primary actions.
Ghost / Text — No border, no background. For tertiary actions or in information-dense contexts.

Cards

Surface background, rounded.lg, soft shadow (box-shadow: 0 2px 8px rgba(0,0,0,0.08)). No border. Minimum internal padding: spacing.lg (24px).

Forms

Inputs with a 1px neutral border. On focus, the border increases to 2px and changes to the accent color. Never use colored backgrounds in form fields.

Motion & Interaction

The framework defines a consistent motion system:

Parameter	Value	Use case
Micro-interactions	`200ms`	Hover states, focus rings, toggles
Page transitions / modals	`350ms`	Modal open/close, page entrance
Standard easing	`cubic-bezier(0.4, 0, 0.2, 1)`	Most animations (Material Design Standard)
Element entrance	`ease-out`	Elements that “fall” into view
Element exit	`ease-in`	Elements that “leave” the screen

Core principle: Animations are functional, not decorative. If removing an animation does not reduce comprehension, remove it. Accessibility: Always respect prefers-reduced-motion. Replace transitions with instantaneous changes or very short fades (50ms).

AI Instruction

The closing instruction binds the AI to this design system:

**AI Instruction:** Read and respect the tokens and decisions defined in this
file. If you need to create a component not defined here, extrapolate
coherently from the existing tokens and log the new decision as a
"Design Decision" in this same file with the date and justification.
For projects without UI, this file may be omitted.

When the AI adds a new component definition to DESIGN.md, it must include a log entry with the date and justification. This keeps the design system auditable and prevents silent visual drift over time.

File Reference

Templates

DESIGN.md: Visual Design System and Token Reference

Document Header

Part 1: YAML Design Tokens

Token Categories Explained

Part 2: Prose Sections

Visual Overview

Colors

Typography

Key Components

Motion & Interaction

AI Instruction

Build docs developers (and LLMs) love

File Reference

Templates

Documentation Index

​Document Header

​Part 1: YAML Design Tokens

​Token Categories Explained

​Part 2: Prose Sections

​Visual Overview

​Colors

​Typography

​Key Components

​Motion & Interaction

​AI Instruction

Build docs developers (and LLMs) love

Document Header

Part 1: YAML Design Tokens

Token Categories Explained

Part 2: Prose Sections

Visual Overview

Colors

Typography

Key Components

Motion & Interaction

AI Instruction