# Design System Spec

> Use when authoring or updating a DESIGN.md design-system specification — defining color/type/spacing tokens with rationale, component state variants, and WCAG-safe palettes for a codebase or agent to consume. Trigger when a project has no design system file yet, or an existing DESIGN.md needs new components or a dark-mode variant.

- Skill: `presidenteog/design-system-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add presidenteog/design-system-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/presidenteog/design-system-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: PresidenteOG (https://skillmd.com/u/presidenteog)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/presidenteog/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).