create-design-md — DESIGN.md Generator Skill

Experimental: This skill is a work in progress. Behavior may change as the Google design.md specification evolves.

A Claude Code skill that generates a DESIGN.md file in the project root following the Google design.md specification. Supports four source modes — codebase exploration, Figma URL, existing DESIGN.md URL, or pasted design spec content — and validates the output with the design.md linter.

---

What this is

DESIGN.md is a machine-readable design specification that lives alongside your code. It encodes design tokens (colors, typography, spacing, border radius) and component guidelines in a structured YAML frontmatter + Markdown body format, making them accessible to AI coding agents without requiring a Figma file open.

This skill automates the creation of that file. Point it at your codebase, a Figma design, or an existing DESIGN.md from another project, and it generates a spec-compliant file, then runs the linter to catch any issues automatically.

Codebase / Figma URL / DESIGN.md URL / Paste  →  create-design-md  →  DESIGN.md (lint-validated)

---

The 4 source modes

Mode	When to use
Explore codebase	The project already has CSS tokens (@theme block) and components you want to document
Figma URL	You have a Figma design file with Variables defined
Existing DESIGN.md URL	You want to adopt a published DESIGN.md from another project (e.g. a GitHub raw URL)
Paste	The source URL requires authentication or triggers a direct download — paste the content directly into the conversation

---

Repo structure

skills/
  create-design-md/
    SKILL.md          — skill definition loaded by Claude Code

---

Getting started

1. Clone this repo

git clone https://github.com/gaspanik/create-design-md-skill

2. Install the skill into Claude Code

Copy the skill directory into your Claude Code skills folder:

cp -r skills/create-design-md ~/.claude/skills/

3. Run the skill

Invoke with a slash command or natural language — both work:

/create-design-md

/create-design-md https://www.figma.com/design/<fileKey>/...?node-id=1-2

/create-design-md https://raw.githubusercontent.com/<user>/<repo>/main/DESIGN.md

Generate a DESIGN.md from the current codebase.

このコードベースから DESIGN.md を作って

このFigmaのURLから DESIGN.md 作って: https://www.figma.com/design/...

If no argument is provided, the skill asks you to choose a source mode interactively.

The report is written in whatever language you are using in the conversation — no configuration needed.

---

Tips

• Audit your Figma file before running in Figma mode. The quality of the generated DESIGN.md depends directly on how well the Figma file is structured. Before running this skill, use figma-audit-skill to check frame-level AI-readiness (layer naming, auto-layout, variables, component structure), and figma-component-audit-skill to audit component and variant structure. Fixing issues flagged by those skills — especially undefined Variables — leads to significantly better token coverage in the output.

• Figma mode works best with Variables defined. Files with color, typography, and spacing Variables produce richer token output. The more structured the Figma file, the better the DESIGN.md.

• After generating, Claude reads it automatically. Add the following to your CLAUDE.md so Claude consults DESIGN.md before any UI implementation:

  ## Design System
  
  If `DESIGN.md` exists in the project root, read it before implementing any UI changes.
  It contains the design tokens (colors, typography, spacing, border radius) and component
  guidelines for this project.

• Lint runs automatically. Any errors are fixed before the skill completes. Warnings are reviewed and resolved where possible.

---

Agent settings

• The linter is invoked automatically using the package manager detected in the project (npx, pnpm dlx, yarn dlx, etc.).
• Figma mode requires the official Figma MCP server to be connected in Claude Code settings.

---

Troubleshooting

Issue	Fix
broken-ref lint error	A component references a token that doesn't exist. The skill auto-fixes this, but if it recurs, check the token names in the frontmatter.
missing-primary lint warning	colors.primary is not defined. Add it to the colors section.
Figma mode returns no variables	The Figma file has no Variables defined. Use codebase mode instead, or define Variables in Figma first.
Linter not found	Ensure pnpm is available in the project, or run npx @google/design.md lint DESIGN.md manually.

---

Built by Masaaki Komori - @cipher · Skill for Claude Code