# Design System > Govern an existing DESIGN.md — Google's open standard for design tokens (YAML frontmatter + eight prose sections). Auto-activates during UI edits to enforce token-only sourcing for colors, typography, spacing, and corner radius when a DESIGN.md is present; steps aside when none exists — it never forces or authors one (`/award-design` authors it up front, then builds under it). Exposes seven CLI-b… - **Type:** Skill - **Install:** `agentstack add skill-coroboros-agent-skills-design-system` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [coroboros](https://agentstack.voostack.com/s/coroboros) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [coroboros](https://github.com/coroboros) - **Source:** https://github.com/coroboros/agent-skills/tree/main/skills/design-system - **Website:** https://coroboros.com ## Install ```sh agentstack add skill-coroboros-agent-skills-design-system ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Design System Two modes for governing a project's visual identity: 1. **Auto-activate** — when editing UI files (components, pages, layouts, styles, `DESIGN.md`, `tailwind.config.*`) **and a `DESIGN.md` is present**, the skill reads it first and enforces token-only sourcing for colors, typography, spacing, and corner radius. No `DESIGN.md`? It stays out of the way — a one-line pointer to `/award-design`, no enforcement, no block on the edit. 2. **Subcommands** — `/design-system [path]` exposes the full DESIGN.md lifecycle, built on the canonical `@google/design.md` CLI. ## Subcommand routing Parse the first positional token of `$ARGUMENTS`. If it matches a verb below, load the referenced file and follow its workflow. Otherwise proceed with the token-enforcement workflow at the end of this document. | First token | Mode | Reference | |-------------|------|-----------| | `audit` (aliases: `check`, `lint`) | Lint + fix proposals, human-readable report | `references/subcommand-audit.md` | | `diff` | Regression check between versions (git-aware) | `references/subcommand-diff.md` | | `export` | Tokens → Tailwind theme or W3C DTCG `tokens.json` | `references/subcommand-export.md` | | `spec` | Emit the canonical spec from the installed CLI | `references/subcommand-spec.md` | | `migrate` | Port legacy Stitch 9-section DESIGN.md → Google standard | `references/subcommand-migrate.md` | | `init` | Scaffold a minimal valid DESIGN.md (fallback from `/award-design`) | `references/subcommand-init.md` | | `audit-extensions` | Bidirectional drift check — DESIGN.md extension YAML ↔ prose refs ↔ `globals.css` `@theme` | `references/subcommand-audit-extensions.md` | | (none, or a UI file path) | Token enforcement — see the default workflow at the end | (this file) | ## Source of truth When a `DESIGN.md` exists at the project root, read it **before** writing any UI code: every color, font, spacing value, corner radius, and component style comes from this file — the YAML frontmatter tokens (normative values) or the prose explaining when and why to apply them. **No `DESIGN.md`? Step aside.** design-system governs a file; it does not require or create one. It never blocks an edit for lack of a DESIGN.md and never authors a design from scratch — that is `/award-design`'s job (it forces a universe, writes the DESIGN.md up front, then builds the frontend under it). So: - Building or editing UI with no file → proceed. For a designed build, point to `/award-design`, which authors the DESIGN.md up front and builds the frontend under it. - A bare token scaffold is needed now and `/award-design` is unavailable → `/design-system init [archetype]` is a minimal fallback, not the primary path. If a legacy Stitch-format `DESIGN.md` is detected (9 numbered sections, `## Agent Prompt Guide` heading, no YAML frontmatter): suggest `/design-system migrate ` to port it before proceeding. ## The standard DESIGN.md is Google's open format for describing a design system to coding agents. Canonical source: [github.com/google-labs-code/design.md](https://github.com/google-labs-code/design.md). A file has two layers: 1. **YAML frontmatter** — machine-readable design tokens (`colors`, `typography`, `rounded`, `spacing`, `components`). Normative values. 2. **Markdown body** — eight `##` sections explaining rationale. Present sections must appear in order: | # | Section | Aliases | YAML tokens | |---|---------|---------|-------------| | 1 | **Overview** | Brand & Style | — | | 2 | **Colors** | — | `colors:` | | 3 | **Typography** | — | `typography:` | | 4 | **Layout** | Layout & Spacing | `spacing:` | | 5 | **Elevation & Depth** | Elevation | — | | 6 | **Shapes** | — | `rounded:` | | 7 | **Components** | — | `components:` | | 8 | **Do's and Don'ts** | — | — | Full schema, token types, reference syntax, and consumer behavior for unknown content: `references/design-md-spec.md`. Concrete examples: `references/example-claude.md` (warm editorial), `references/example-stripe.md` (minimalist gradient). ## Token references and schema (at a glance) - **Colors**: hex (sRGB) quoted — `primary: "#1A1C1E"` - **Dimensions**: `px` / `em` / `rem` — `48px`, `-0.02em`, `1.5rem` - **Typography**: object — `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` - **Token references**: `{path.to.token}` wrapped in braces — `"{colors.tertiary}"`, `"{rounded.sm}"` - **Component property tokens** (the only accepted set): `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width` - **Variants** (hover, active, pressed): separate entries with related keys — `button-primary`, `button-primary-hover` Recommended but non-normative names: `primary`, `secondary`, `tertiary`, `neutral`, `surface`, `on-surface`, `error`; `headline-lg`, `body-md`, `label-sm`; `none`, `sm`, `md`, `lg`, `xl`, `full`. ## Writing principles DESIGN.md is written for both agents and humans. These principles govern every section: - **Tokens are normative, prose is context.** YAML values are what agents render. Prose tells them *when* and *why*. Both are required — prose without values is a mood board; values without prose is a spreadsheet. - **Descriptive over technical.** Write "whisper-soft shadow" alongside the exact value. Translate CSS into spatial language — `rounded-full` → "pill-shaped". - **Every value has a role.** `#5e5d59` alone is meaningless; `Olive Gray (#5e5d59): secondary body text — warm medium-dark gray` is actionable. - **Name tokens semantically.** `primary`, `tertiary`, `button-primary-hover` — not `blue-500`, `shadow-sm`. - **Show the personality in Overview.** Section 1 sets the tone; every later section should feel written by the same person. - **Exact values are non-negotiable.** Every color, dimension, component property is a concrete token. ## Rules - Colors, fonts, spacing, corner radius come **only** from DESIGN.md YAML tokens - Map tokens to CSS custom properties in the global stylesheet - Map tokens to `tailwind.config.ts theme.extend` — or generate via `/design-system export tailwind` - Never use arbitrary Tailwind values (`text-[13px]`, `bg-[#abc]`) when a token exists - Never introduce values absent from DESIGN.md — use the closest token and flag to the user - **Extended tokens** — values outside the canonical 5 namespaces (`motion`, `shadows`, `aspectRatios`, `heights`, `containers`, `breakpoints`, `zIndex`, `borderWidths`, `opacity`, `scrollTriggers`) live as top-level YAML namespaces — preserved by the Google CLI per `references/design-md-spec.md` *Extending the spec*, validated by convention via `/design-system audit-extensions`. **Components MUST NOT bind to extension namespaces.** The lint rejects unknown property names as `broken-ref` errors — field-tested as 73 errors and 84 warnings cascading from 27 components binding to extension tokens via non-canonical property names like `modal.shadow: "{shadows.lifted}"`. Reference extensions in prose canonically instead (e.g., `{motion.duration-reveal-slow}`); export to `globals.css` `@theme` as 1:1 CSS custom properties (`--duration-reveal-slow`). See `references/extended-tokens.md` - Dark mode: the Google spec has no dedicated mode concept. Use **semantic tokens** in a single DESIGN.md (e.g., `surface`, `on-surface`, `inverse-surface`, `inverse-on-surface`) and let the framework's CSS custom properties map each semantic name to the right value per mode. The Google-published `atmospheric-glass` example follows this pattern — one file, both modes via semantic naming. Avoid dual-file setups (DESIGN.md + DESIGN.dark.md) unless the brand truly diverges between modes - Shared brand across projects: same DESIGN.md, framework-specific implementation. Distribution patterns — pick one and document in each project's CLAUDE.md: - **Monorepo** — `packages/brand/DESIGN.md` consumed by all apps; single PR for cross-cutting changes - **Git submodule** — canonical brand repo included as submodule; atomic updates via submodule bump - **Published package** — `@org/design-tokens` on npm with DESIGN.md + build outputs; versioned, works cross-repo - **Copy + periodic `/design-system diff`** — copies in each repo; periodic diff against the canonical catches drift; simplest tooling, highest drift risk - Monorepo: the spec and this skill assume a single root `DESIGN.md` per project. For monorepos with per-package brand variations, keep each package's DESIGN.md at the package root and adjust the invocation path (`/design-system audit packages/web/DESIGN.md`). The `paths:` auto-activation matches the root file by default - **Post-edit invariant** — after any DESIGN.md mutation (token update during the enforcement flow, `migrate`, `init`, or manual edit via this skill), run `/design-system audit ` and surface findings. A mutation that leaves errors behind is not done - Duplicate section headings are a spec error — reject the file - Unknown section headings are preserved (don't error); unknown component properties are accepted with a warning ## CLI validator — shared surface The canonical `@google/design.md` CLI powers the `audit`, `diff`, `export`, and `spec` subcommands. Each subcommand wraps one CLI invocation with richer UX (fix proposals, git-awareness, human-readable reports). Raw invocations: ```bash npx @google/design.md lint DESIGN.md # validate npx @google/design.md diff before.md after.md # regression check (exit 1 on regression) npx @google/design.md export --format tailwind DESIGN.md npx @google/design.md spec --rules # emit spec + lint rules ``` Eight linting rules: `broken-ref` (error), `missing-primary`, `contrast-ratio`, `orphaned-tokens`, `token-summary`, `missing-sections`, `missing-typography`, `section-order`. Full table with severity, interpretation, and fix strategies: `references/cli-reference.md`. Every subcommand verifies CLI availability first (`command -v npx` + a dry `--help` probe). When unavailable or offline: fall back to manual validation against `references/design-md-spec.md`. The skill still enforces the spec without the CLI — it loses only the deterministic check. ## Framework behavior Detect framework from config files (`astro.config.*`, `next.config.*`, etc.), then follow project instructions (`CLAUDE.md`, `AGENTS.md`, or equivalent) for implementation specifics (component library, font loading, file structure). ## Default workflow — token enforcement When no subcommand is matched — either auto-activated via `paths:` during a UI edit, or invoked directly to discuss enforcement — follow this workflow. ### When there is no DESIGN.md design-system does not author a design file from scratch. A DESIGN.md is born one of two ways: 1. **`/award-design` authors it** (preferred) — it forces a universe and writes the full DESIGN.md up front, then builds the frontend under it. design-system governs the result from there. 2. **`/design-system init [archetype]`** — a minimal token scaffold, only when `/award-design` is unavailable and a bare file is needed now. Either way, once the file exists, the change flow below applies. Atmosphere scores (Density, Variance, Motion) live in Overview prose, not YAML. **How award-design's universe maps to DESIGN.md:** | award-design output | DESIGN.md section | YAML tokens | |---------------------|-------------------|-------------| | Archetype + atmosphere (Density/Variance/Motion) + signature moment + photography direction + copy register | 1. Overview (prose) | — | | Color palette + photography colour guidance | 2. Colors | `colors:` | | Typography + kinetic typography intent | 3. Typography | `typography:` | | Spacing, grid, scroll choreography, responsive system | 4. Layout | `spacing:` + ext: `breakpoints:`, `containers:`, `heights:`, `aspectRatios:`, `motion:`, `scrollTriggers:` | | Shadow language + depth narrative | 5. Elevation & Depth | ext: `shadows:`, `borderWidths:`, `opacity:` | | Corner radius language | 6. Shapes | `rounded:` | | Component specs + variants + micro-interactions + motion philosophy | 7. Components | `components:` (8 property tokens only) + ext: `zIndex:` | | Archetype guardrails + AI-tell rejections + production-hardening rules | 8. Do's and Don'ts | — | Extension namespaces (`ext:` rows above) live as top-level YAML per `references/extended-tokens.md`. Components bind only to the eight canonical property tokens — extension tokens are referenced in prose, never as `components:` keys. Once the file exists (authored or scaffolded), wire it into the project: 1. **Audit** — run `/design-system audit ` (post-edit invariant). Fix errors before proceeding. 2. **Wire into the framework**: `/design-system export tailwind` → merge the result into `tailwind.config.ts theme.extend` (v3) or `globals.css` `@theme` block (v4); set up CSS custom properties in the global stylesheet. 3. **Validate the mirror** — `/design-system audit-extensions ` confirms every extension token in the YAML has its CSS custom property and every prose reference resolves. Run after every export. ### When UI/UX changes are requested Any visual change — colors, typography, spacing, radius, shadows, component styles, layout, responsive behavior — follows this flow. 1. **Check whether the change affects tokens.** New value, modified value, or altered visual system → DESIGN.md first. Pure layout bugs, alt text, content reordering → code only. 2. **Update DESIGN.md first.** - Open DESIGN.md, locate the affected YAML tokens and prose sections - Update values, semantic names, reference paths - Cascade — if the primary color changes, update every `components:` entry referencing it - Sync Do's and Don'ts if the change contradicts an existing guardrail 3. **Audit** — `/design-system audit ` to verify no broken references or contrast regressions (post-edit invariant). 4. **Propagate to code**: - Re-export Tailwind theme (`/design-system export tailwind`) or update `theme.extend` by hand - Update CSS custom properties in the global stylesheet - Update components using raw values — components referencing tokens by name pick up the new value automatically 5. **Shared brand** — if the DESIGN.md is shared across projects, propagate to all, then step 4 in each. Examples of token-affecting changes: - "Change CTA color" → `colors.*` + Colors prose + every `components:` entry referencing the old color - "Make cards more rounded" → `rounded.*` + Shapes prose + `components.card.rounded` - "Darker theme" → `colors.*` + Overview + Elevation & Depth prose - "New badge component" → `components.*` + Components prose - "Increase section spacing" → `spacing.*` + Layout prose ### Re-architecting A fundamental visual change (new archetype, different atmosphere, complete restyle) is a new design, not a token update. Use `/award-design` to rebuild from a fresh archetype — it writes a fresh DESIGN.md and builds under it. Any existing DESIGN.md is replaced whole, never patched in place. ## Gotchas 1. **Components binding to extension-namespace tokens triggers `broken-ref` errors.** Components MUST use only the 8 canonical properties (`backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`). A `components: { modal: { shadow: "{shadows.lifted}" } }` references an extension namespace and fails lint; the error message does not name the canonical-vs-extension distinction. Fix: reference extension tokens only in prose (e.g., `{motion.duration-reveal-slow}` inside a Layout paragraph), never as a component property. 2. **Duplicate `##` section heading breaks spec parsing silently.** Two `## Colors` sections (from a botched re-architect) cause the parser to read only the first; YAML in the second is dropped without warning. Each of the 8 sections must appear exactly once. Fix: prescan for heading duplicates; fail hard with the duplicated name. 3. **`export tailwind` token name mismatches don' … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [coroboros](https://github.com/coroboros) - **Source:** [coroboros/agent-skills](https://github.com/coroboros/agent-skills) - **License:** MIT - **Homepage:** https://coroboros.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-coroboros-agent-skills-design-system - Seller: https://agentstack.voostack.com/s/coroboros - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.