DESIGN.md

What it is

DESIGN.md lives at the root of this repo. It collects every token value, every component's CSS class, its props, and its component tokens into a single file. When you give it to a coding assistant at the start of a session, the assistant can generate components that match Source without needing to guess at naming conventions or token values.

The format follows the https://stitch.withgoogle.com/docs/design-md/overview: a plain markdown file structured for machines first, humans second.

Setup by tool

Claude Code

Add DESIGN.md to your CLAUDE.md quick reference. Claude Code reads CLAUDE.md at startup, so it will load the design spec automatically when you start a session in this repo.

# CLAUDE.md
## Quick reference
- `DESIGN.md` — full design spec: tokens, components, and guardrails

You can also reference it explicitly in a prompt:

Read DESIGN.md, then generate a new Notification component
following the same token and class naming conventions as the existing components.

Cursor

Reference DESIGN.md from your .cursorrules file, or attach it manually in chat with @DESIGN.md.

# .cursorrules
# Source design system — full spec at DESIGN.md
# Read it before generating components or modifying tokens.

Any other assistant

Paste the raw file content directly into your prompt. The file is under 10KB so it fits comfortably in any context window.

Example: generating a new component

With DESIGN.md loaded as context, ask for a new component the same way you would describe one to a developer:

Read DESIGN.md. Generate a Callout component for Source.

It should:
- Accept a `palette` prop matching the existing status palettes
  (neutral, success, warning, danger, info)
- Use --source-color-<status> for the left border color
- Use --source-color-<status>-subtle for the background
- Use the source- class prefix and define its own component tokens
- Follow the same file structure as the Badge component

Because the assistant has the full token table and component conventions in context, it will produce a component that slots directly into the system without requiring manual correction of class names or token references.

What it covers

Visual identity Neutral palette character, theme system, dark mode mechanics.

Color tokens All primitives and semantic tokens with light/dark values. Status and accent tokens.

Typography Font families, size scale, weights, and line heights.

Spacing and radius Full spacing scale and border radius tokens.

Component patterns Root CSS class, props, and component tokens for every component in the library.

Design guardrails Rules that must hold for any generated or modified code: no Tailwind, two-level token structure, naming conventions.