design-md-format

# DESIGN.md Format Skill > Skill by [ara.so](https://ara.so) — Design Skills collection. DESIGN.md is a format specification for describing visual identity to coding agents. It combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose), giving agents persistent, structured understanding of design systems. ## Installation ```bash npm install @google/design.md ``` For direct CLI usage without installation: ```bash npx @google/design.md lint DESIGN.md ``` **Windows note**: When using the CLI in `package.json` scripts on Windows, use the `designmd` alias instead of `design.md` to avoid file association issues: ```json { "scripts": { "design:lint": "designmd lint DESIGN.md" } } ``` ## File Structure A DESIGN.md file has two layers: 1. **YAML front matter** — Machine-readable tokens (colors, typography, spacing, etc.) 2. **Markdown body** — Human-readable rationale organized into specific sections ```md --- name: Heritage colors: primary: "#1A1C1E" secondary: "#6C7278" tertiary: "#B8422E" neutral: "#F7F5F2" typography: h1: fontFamily: Public Sans fontSize: 3rem body-md: fontFamily: Public Sans fontSize: 1rem rounded: sm: 4px md: 8px spacing: sm: 8px md: 16px components: button-primary: backgroundColor: "{colors.tertiary}" textColor: "#ffffff" rounded: "{rounded.sm}" padding: 12px --- ## Overview Architectural Minimalism meets Journalistic Gravitas. ## Colors - **Primary (#1A1C1E):** Deep ink for headlines and core text. - **Tertiary (#B8422E):** "Boston Clay" — interaction driver. ``` ## Creating a DESIGN.md File ### Complete Token Schema ```yaml version: <string> # optional, current: "alpha" name: <string> # required description: <string> # optional colors: <token-name>: <Color> # "#" + hex (sRGB) typography: <token-name>: <Typography> rounded: <scale-level>: <Dimension> spacing: <scale-level>: <Dimension | number> components: <component-name>: <property>: <value | token reference> ``` ### Token Types **Color**: Hex format with `#` prefix ```yaml colors: primary: "#1A1C1E" accent: "#B8422E" on-primary: "#FFFFFF" ``` **Typography**: Object with font properties ```yaml typography: h1: fontFamily: Public Sans fontSize: 3rem fontWeight: 700 lineHeight: 1.2 letterSpacing: -0.02em body-md: fontFamily: Public Sans fontSize: 1rem fontWeight: 400 lineHeight: 1.5 ``` **Dimension**: Number + unit (`px`, `em`, `rem`) ```yaml rounded: sm: 4px md: 8px lg: 16px spacing: xs: 4px sm: 8px md: 16px lg: 24px ``` **Token Reference**: `{path.to.token}` ```yaml components: button-primary: backgroundColor: "{colors.tertiary}" textColor: "{colors.on-tertiary}" rounded: "{rounded.sm}" ``` ### Component Tokens Valid component properties: - `backgroundColor` - `textColor` - `typography` - `rounded` - `padding` - `size` - `height` - `width` ```yaml components: button-primary: backgroundColor: "{colors.tertiary}" textColor: "#ffffff" typography: "{typography.label-caps}" rounded: "{rounded.sm}" padding: 12px button-primary-hover: backgroundColor: "{colors.tertiary-container}" card: backgroundColor: "{colors.neutral}" rounded: "{rounded.md}" padding: "{spacing.md}" ``` ### Section Order Markdown sections use `##` headings and must appear in this order (all optional): 1. **Overview** (or "Brand & Style") 2. **Colors** 3. **Typography** 4. **Layout** (or "Layout & Spacing") 5. **Elevation & Depth** (or "Elevation") 6. **Shapes** 7. **Components** 8. **Do's and Don'ts** ```md ## Overview Brief description of the design philosophy. ## Colors Rationale for each color token and when to use it. - **Primary (#1A1C1E):** Deep ink for headlines - **Tertiary (#B8422E):** Interaction driver ## Typography Font selection rationale and hierarchy guidance. ## Components How to apply component tokens in context. ``` ## CLI Commands ### Lint Validate a DESIGN.md file for structural correctness, broken references, and WCAG contrast issues: ```bash # Validate from file npx @google/design.md lint DESIGN.md # From stdin cat DESIGN.md | npx @google/design.md lint - # Specify output format (only json currently) npx @google/design.md lint --format json DESIGN.md ``` **Output**: JSON with findings array and summary ```json { "findings": [ { "severity": "warning", "path": "components.button-primary", "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA." } ], "summary": { "errors": 0, "warnings": 1, "info": 1 } } ``` **Exit codes**: - `0`: No errors - `1`: Errors found ### Diff Compare two DESIGN.md versions to detect token changes and regressions: ```bash npx @google/design.md diff DESIGN.md DESIGN-v2.md npx @google/design.md diff --format json old.md new.md ``` **Output**: Token-level changes ```json { "tokens": { "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] }, "typography": { "added": [], "removed": [], "modified": [] } }, "regression": false } ``` **Exit codes**: - `0`: No regressions - `1`: Regressions detected (more errors/warnings in "after") ### Export Convert DESIGN.md tokens to other formats: ```bash # Tailwind v3 JSON config npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json # alias # Tailwind v4 CSS theme npx @google/design.md export --format css-tailwind DESIGN.md > theme.css # W3C Design Tokens Format (DTCG) npx @google/design.md export --format dtcg DESIGN.md > tokens.json # From stdin cat DESIGN.md | npx @google/design.md export --format dtcg - > tokens.json ``` **Tailwind v3 JSON output** (`json-tailwind`): ```json { "colors": { "primary": "#1A1C1E", "secondary": "#6C7278", "tertiary": "#B8422E" }, "fontFamily": { "sans": ["Public Sans", "sans-serif"] }, "fontSize": { "h1": "3rem", "body-md": "1rem" }, "borderRadius": { "sm": "4px", "md": "8px" }, "spacing": { "sm": "8px", "md": "16px" } } ``` **Tailwind v4 CSS output** (`css-tailwind`): ```css @theme { --color-primary: #1A1C1E; --color-secondary: #6C7278; --color-tertiary: #B8422E; --font-sans: "Public Sans", sans-serif; --text-h1: 3rem; --text-body-md: 1rem; --radius-sm: 4px; --radius-md: 8px; --spacing-sm: 8px; --spacing-md: 16px; } ``` ### Spec Output the DESIGN.md specification (useful for agent prompts): ```bash # Full spec npx @google/design.md spec # Spec + linting rules npx @google/design.md spec --rules # Only linting rules npx @google/design.md spec --rules-only # JSON format npx @google/design.md spec --rules-only --format json ``` ## Programmatic API ### Linting ```typescript import { lint } from '@google/design.md/linter'; const markdownString = ` --- name: MyDesign colors: primary: "#1A1C1E" components: button: backgroundColor: "{colors.primary}" textColor: "#ffffff" --- ## Overview Modern design system. `; const report = lint(markdownString); console.log(report.findings); // [ // { // severity: 'warning', // path: 'components.button', // message: 'textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.' // } // ] console.log(report.summary); // { errors: 0, warnings: 1, info: 1 } console.log(report.designSystem); // Parsed DesignSystemState object ``` ### Parsing and Validation ```typescript import { lint, type Finding } from '@google/design.md/linter'; function validateDesignFile(content: string): boolean { const report = lint(content); const hasErrors = report.findings.some((f: Finding) => f.severity === 'error'); if (hasErrors) { console.error('Validation failed:'); report.findings .filter((f: Finding) => f.severity === 'error') .forEach((f: Finding) => console.error(` ${f.path}: ${f.message}`)); return false; } return true; } ``` ## Common Patterns ### Creating a Design System from Scratch ```md --- version: alpha name: ProductName description: Modern SaaS design system colors: primary: "#2563eb" secondary: "#64748b" tertiary: "#0ea5e9" neutral: "#f8fafc" on-primary: "#ffffff" on-tertiary: "#ffffff" typography: h1: fontFamily: Inter fontSize: 2.5rem fontWeight: 700 lineHeight: 1.2 h2: fontFamily: Inter fontSize: 2rem fontWeight: 600 lineHeight: 1.3 body: fontFamily: Inter fontSize: 1rem fontWeight: 400 lineHeight: 1.5 label: fontFamily: Inter fontSize: 0.875rem fontWeight: 500 rounded: sm: 4px md: 8px lg: 12px full: 9999px spacing: xs: 4px sm: 8px md: 16px lg: 24px xl: 32px components: button-primary: backgroundColor: "{colors.primary}" textColor: "{colors.on-primary}" typography: "{typography.label}" rounded: "{rounded.md}" padding: 12px 24px button-primary-hover: backgroundColor: "#1d4ed8" card: backgroundColor: "{colors.neutral}" rounded: "{rounded.lg}" padding: "{spacing.lg}" input: backgroundColor: "{colors.neutral}" textColor: "{colors.primary}" rounded: "{rounded.sm}" padding: "{spacing.sm}" --- ## Overview Clean, modern SaaS interface prioritizing readability and trust. ## Colors - **Primary (#2563eb):** Brand blue for primary actions - **Secondary (#64748b):** Slate for secondary text and borders