Design System Spec

Design System Spec

Adapted from https://raw.githubusercontent.com/ai-boost/awesome-prompts/main/prompts/design_system_spec_architect.txt (ai-boost/awesome-prompts, GPL-3.0) — rewritten, not copied.

Overview

A DESIGN.md is a CLAUDE.md for visual identity: one file an agent reads before generating any UI, so buttons, cards, and inputs come out consistent instead of reinvented per prompt. This skill writes that file — tokens plus the reasoning behind them, one component at a time, each carrying its full set of interaction states.

Local fit: the installed awesome-design skill reads DESIGN.md files, but nothing in this workspace currently writes one with this level of rigor — that gap is what this skill fills. Keep the output's section headings compatible with what awesome-design expects (Brand Identity, Color System, Typography, Spacing & Layout, Component Patterns, Motion & Interaction, Do / Don't), so either skill can read or extend the same file. forgegui's style-reference lock — a palette/border/aesthetic pinned across one generation session — is this same idea applied informally; this skill makes it durable and checkable.

When to use

• Starting UI work with no design system file in the project.
• An existing DESIGN.md needs a new component or a dark-mode variant.
• A project's UI looks inconsistent across screens or generation sessions and needs one source of truth.

Core rules

1. Tokens are the source of truth; prose explains why a value was chosen — it never overrides a token with a guess.
2. Every component color reference points at a semantic token (primary, on-primary, neutral) — never a raw hex value repeated inline.
3. Every interactive component defines all of: default, hover, active/pressed, disabled, focus.
4. Every text/background pair hits WCAG 2.2 AA — 4.5:1 contrast minimum. Check it; don't assume it.
5. No orphaned tokens — if a token isn't used by at least one component or rule, cut it.

Process

1. Clarify inputs: existing brand assets or a reference URL? target framework (Tailwind, CSS variables, SwiftUI)? an accessibility bar beyond AA? an existing component library to align to?
2. Get or invent tokens. From a screenshot or URL, extract colors and name them semantically — primary/secondary/neutral/error/success — never literally (blue/gray/red). From scratch, ask one or two brand-adjective questions first ("editorial and minimal, or playful and bold?") before inventing values.
3. Write the rationale before the values, for color and typography especially — settle the voice, then derive the hex code or font from it, not the reverse.
4. Define the five to ten most common components first, full state matrix on each, before adding anything exotic.
5. Validate: every text/background pair at or above 4.5:1, every token referenced somewhere, every token reference resolving to a value that actually exists.
6. Emit the file plus a one-line validation summary — contrast pass/fail count, orphaned-token count, component count.

Output skeleton

# DESIGN.md — [Project]

## Brand Identity
- Personality / Voice / Positioning

## Color System
- primary / secondary / neutral / on-* / error / success / warning — hex + usage rule each

## Typography
- Heading / body / mono fonts, scale, weight rules

## Spacing & Layout
- Base unit, grid, breakpoints, max content width, radius scale

## Component Patterns
- Per component: purpose, state matrix (default/hover/active/disabled/focus), token references, accessibility notes

## Motion & Interaction
- Transition duration/easing, hover behavior, loading pattern, reduced-motion fallback

## Do / Don't
- 3-5 concrete pairs, each naming the rule it enforces (usually a contrast or token rule)

Dark mode

A dark-mode request gets a second DESIGN.md, same structure, with inverted surface/text tokens — not a .dark class bolted onto the light-mode values.

Related: awesome-design (reads/consumes DESIGN.md), forgegui (style-reference lock for one-off generation sessions).