design-md

Author, lint, and export Google's DESIGN.md design token specification files.

Updated May 13, 2026
One-click install
npx skills add https://github.com/superfhp/lumi-agent-body --skill design-md-superfhp
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: design-md
Source: https://github.com/superfhp/lumi-agent-body/tree/main/skills/creative/design-md
Command: npx skills add https://github.com/superfhp/lumi-agent-body --skill design-md-superfhp

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @google/design.md.

What problem does it solve? Teams struggle to keep visual identity consistent across projects and coding agents. This Skill creates and validates DESIGN.md files — Google's open spec combining machine-readable design tokens with human-readable rationale — so colors, typography, and components stay single-sourced and accessible. ## Core Features & Use Cases - Authoring: Generate a complete DESIGN.md with YAML token frontmatter (colors, typography, rounded, spacing, components) and canonical Markdown sections in the enforced order. - Linting & Accessibility: Run npx @google/design.md lint to catch broken token references, duplicate sections, invalid values, and WCAG AA/AAA contrast failures. - Export & Diff: Convert tokens to Tailwind theme JSON or W3C DTCG JSON, and diff two versions to detect regressions. - Use Case: A user pastes their brand palette and asks for a design system spec; the Skill writes DESIGN.md, lints it for contrast issues, and exports tailwind.theme.json for their existing project. ## Quick Start Ask the agent to create a DESIGN.md design token spec for your brand with your accent color and font, then lint it and export it to Tailwind format.

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 frontmatter containing name, colors, typography, rounded, spacing, and components tokens, followed by canonical sections like Overview, Colors, and Components. Use token references like {colors.primary} in component definitions instead of repeating hex values.

How do I validate design tokens and check WCAG contrast?▼

Run npx -y @google/design.md lint DESIGN.md to validate structure, token references, and color formats. The wcag-contrast rule checks component textColor against backgroundColor for WCAG AA (4.5:1) and AAA (7:1) ratios, reporting warnings or info.

Can I export DESIGN.md tokens to Tailwind or DTCG format?▼

Yes, the CLI exports to both formats. Use npx @google/design.md export --format tailwind for a Tailwind theme JSON, or --format dtcg for W3C Design Tokens Format Module JSON. All commands also accept stdin via the - argument.

Why does my DESIGN.md lint fail with broken references?▼

Broken-ref errors occur when a token reference like {colors.missing} points to a non-existent token. References resolve by full dotted path, so {colors.primary} works but {primary} does not. Also quote hex colors and negative dimensions to avoid YAML parsing issues.

How should component variants like hover states be defined?▼

Define variants as separate sibling component entries with related key names, such as button-primary-hover alongside button-primary. Nesting variants like button-primary.hover is invalid and rejected by the spec.

When should I use DESIGN.md instead of a regular style guide?▼

Use DESIGN.md when coding agents or multiple tools need machine-readable tokens plus rationale in one file. For pure visual inspiration or one-off prototype design, a formal token spec is unnecessary overhead.