Skip to content
UXClaim
Design Systems

design-md-skill

Auto-generate a spec-conformant DESIGN.md from your design tokens in 30 seconds. Makes your design system AI-readable from theme.json, Tailwind, CSS variable...

View source More in Design Systems

What it does

design-md-skill automatically generates a DESIGN.md file—the open standard for AI-readable design systems—directly from the design tokens already in your codebase. No reverse-engineering, no manual forms, no images needed.

How it works

Run /design-md in Claude Code and the skill auto-detects your project:

  • theme.json (WordPress block themes)
  • tailwind.config.js/ts (Tailwind v3)
  • CSS @theme blocks (Tailwind v4)
  • CSS variables (plain :root { --foo })
  • tokens.json (W3C DTCG format)

It reads your existing tokens, translates them into the canonical DESIGN.md format, and validates the output with the official linter—zero errors guaranteed.

Use cases

  • Communicate design intent to AI agents so Claude Code, Cursor, and other coding assistants stay on-brand without constant style corrections
  • Version control your design system as a single source of truth that travels with your codebase
  • Export to any stack using the official @google/design.md CLI to generate Tailwind v3, Tailwind v4, or W3C DTCG tokens.json
  • Onboard developers faster with a plain-text, human-readable design reference

Who benefits

Designers who code, design systems teams, and anyone using AI agents in their development workflow. Works with WordPress block themes, Tailwind projects, and CSS variable systems.

Frequently asked questions

How do I install design-md-skill?
Copy-paste in your terminal: `git clone https://github.com/s-a-s-k-i-a/design-md-skill ~/.claude/skills/design-md`. Open Claude Code in any project and run `/design-md`. No npm install or build step required.
What file formats does it read?
The skill auto-detects: theme.json (WordPress), tailwind.config.js/ts (Tailwind v3), CSS @theme blocks (Tailwind v4), CSS variables in :root, and W3C DTCG tokens.json. If none exist, it runs a short interview to help you build a starter.
What is DESIGN.md and why does it matter?
DESIGN.md is an open standard from Google Labs that makes your design system readable to AI agents. It's YAML front-matter with your colors, typography, spacing, and component rules, plus markdown prose explaining the 'why'. AI agents read it to stay on-brand without constant correction.
Does it overwrite my existing DESIGN.md?
No. If you already have a DESIGN.md, the skill asks first: overwrite, show a diff, skip, or backup-and-replace. It never silently overwrites.
Can I export DESIGN.md to Tailwind or other formats?
Yes. After generating DESIGN.md, use the official `@google/design.md` CLI to export to Tailwind v3, Tailwind v4, or W3C DTCG tokens.json format without lock-in.
Does design-md-skill work with monorepos?
Yes. The skill detects sub-projects and writes DESIGN.md in the correct directory (e.g., inside a WordPress theme folder) so it ships with the right component.
How is this different from other DESIGN.md tools?
This skill translates design tokens already in your source code—no reverse-engineering from screenshots or websites. Other tools focus on cloning famous brands, vision-based generation, or guided interviews. This respects your existing design system as the single source of truth.
Does the skill validate the output?
Yes. After generating DESIGN.md, it runs the official @google/design.md linter to ensure the file is spec-conformant with zero errors.

Glossary

DESIGN.md
An open standard from Google Labs for writing design systems in plain text. It combines YAML front-matter (typed design tokens like colors, typography, spacing) with markdown prose explaining design intent, making it readable to both humans and AI agents.
Design tokens
The smallest, reusable units of a design system—colors, font sizes, spacing values, border radii, shadows. Often stored in theme.json, Tailwind config, CSS variables, or tokens.json.
W3C DTCG
Design Tokens Community Group—a W3C standard format (tokens.json) for storing and sharing design tokens in a language-agnostic way. Used by Figma Variables, Style Dictionary, and modern design tools.
Claude Code
An AI coding agent built into Claude that can read, write, and refactor code in your editor. It uses files like DESIGN.md to understand project context and constraints.
Spec-conformant
Compliant with an official standard or specification. A spec-conformant DESIGN.md passes validation against the official @google/design.md linter.

More in Design Systems

All →
Design Systems

Arcade Prototyper

Build interactive HTML prototypes using DevRev's production design system and Arcade components in Claude Code.

asundiev-devrev
Design Systems

Awesome Design Skill

Access 54+ brand design systems (Linear, Apple, Stripe, Vercel) for Claude Code UI development with complete design specifications.