design-md

Author, lint, diff, and export Google DESIGN.md design token spec files.

Updated Aug 21, 2026
One-click install
npx skills add https://github.com/TylerSimons1127/vibe --skill design-md-tylersimons1127
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: design-md
Source: https://github.com/TylerSimons1127/vibe/tree/main/skills/creative/design-md
Command: npx skills add https://github.com/TylerSimons1127/vibe --skill design-md-tylersimons1127

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping a visual identity consistent across projects and coding agents is hard when brand rules live in scattered style guides. This Skill produces a single DESIGN.md file following Google's open spec, combining machine-readable YAML design tokens with human-readable rationale, and validates it for structure and WCAG contrast. ## Core Features & Use Cases - Authoring: Generate a complete DESIGN.md with colors, typography, spacing, rounded corners, and component tokens using {path.to.token} references so the palette stays single-source. - Validation & Diffing: Run npx @google/design.md lint to catch broken token references, out-of-order sections, and WCAG AA contrast failures, and diff to detect regressions between versions. - Exporting: Convert the spec to Tailwind v3 theme JSON, a Tailwind v4 CSS @theme block, or W3C DTCG JSON for direct use in existing projects. - Use Case: A team wants every agent-generated UI to match their brand. You write a DESIGN.md in the project root, lint it to fix a failing button contrast ratio, then export tailwind.theme.json so the design system flows into their Tailwind setup. ## Quick Start Create a DESIGN.md design token spec for my brand with a clay-red accent color, then lint it and export it to Tailwind theme JSON.

Frequently Asked Questions about design-md

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a DESIGN.md design token file?▼

Write a Markdown file with YAML front matter containing colors, typography, rounded, spacing, and components tokens, followed by canonical sections like Overview, Colors, and Components. Always include name and colors, and quote hex values and negative dimensions so YAML parses them correctly.

How do I validate design tokens for WCAG contrast?▼

Run npx -y @google/design.md lint DESIGN.md to check structure, token references, and WCAG AA contrast ratios between component textColor and backgroundColor. Lint exits 1 on errors, while warnings alone exit 0.

Can I export DESIGN.md tokens to Tailwind?▼

Yes, the CLI exports to Tailwind v3 theme JSON with --format json-tailwind and to a Tailwind v4 CSS @theme block with --format css-tailwind. It also supports W3C DTCG JSON via --format dtcg for design token pipelines.

Why does the design.md command not work on Windows?▼

On Windows the design.md bin name collides with the .md file association, causing a silent no-op or opening the file in an editor. Use the dot-free alias instead: npx -y -p @google/design.md designmd lint DESIGN.md.

How should component variants like hover states be defined in DESIGN.md?▼

Define variants as separate sibling component entries with related key names, such as button-primary-hover, rather than nesting them under the base component. Nested variants like button-primary.hover are not supported by the spec.