What is the create-design-md skill?
Create-design-md is a skill in the ibelick/ui-skills repository. It makes an AI coding agent write or update a DESIGN.md file from your repository or from a rendered website, record each token with its source and confidence, and validate the result with the DESIGN.md spec, lint and export commands.
It is a skill that produces a DESIGN.md file, a written design system an AI coding agent can read before it builds an interface. It works in two modes. Repository mode reads your code, and URL mode reads a rendered website.
What changes in your agent's output
- The only file modified is DESIGN.md.
- Each finding is recorded as role, value, source, scope, recurrence and confidence, so every token has evidence behind it.
- URL mode needs rendered browser access and samples up to 3 same-origin pages.
- A claim must pass a 3-proof gate in URL mode before it is written down.
- A single source
--radiusbecomesrounded.base.
Structure and validation
Sections follow a fixed order: Overview, Colors, Themes, Typography, Layout, Elevation and Depth, Shapes, Components, then Do's and Don'ts. Typography entries must be mappings with canonical fields.
- You pick an export target: css-tailwind, json-tailwind or dtcg.
- Validation runs
npx @google/design.mdwith the spec, lint and export commands, and diff when updating an existing file. - The agent reports whether DESIGN.md was created or updated, plus the lint and export results.
Who the skill is for
Best for
- Teams whose design decisions live only in code and need them written down for an AI coding agent.
- Anyone who wants a DESIGN.md that cites where each value came from.
- Projects exporting tokens to Tailwind or the DTCG format.
Not for
- Sites you do not have the right to analyze. URL mode samples a live site, so use it on your own or permitted sites.
- Applying design rules to code. For that, use baseline-ui or stitch-design-taste.
- Cloning a site's look in one pass. See firecrawl-website-design-clone.
For tools that extract design tokens from a site, see design-extract-mcp and dembrandt-mcp.
How to install Create DESIGN.md Skill for AI Coding Agents
git clone https://github.com/ibelick/ui-skills.gitClone the repository
Run
git clone https://github.com/ibelick/ui-skills.git. The skill is the skills/create-design-md folder.Copy the skill folder
Copy skills/create-design-md into your AI coding agent's skills folder.
Choose a mode
Ask for repository mode inside your project, or give a URL for URL mode, which needs rendered browser access.
Pick an export target
Say whether you want css-tailwind, json-tailwind or dtcg, then review the lint and export results the agent reports.
Check that it loaded
Open the DESIGN.md the agent created and confirm the sections appear in the fixed order and that the lint and export commands reported no errors.
Key features
- Repository modeReads your code to derive a design system file from what is actually used.
- URL modeReads a rendered website, with up to 3 same-origin pages sampled, and needs rendered browser access.
- Evidence pipelineEach finding records role, value, source, scope, recurrence and confidence.
- 3-proof claim gateIn URL mode, a claim needs three proofs before it is written into the file.
- One file touchedThe skill modifies only DESIGN.md.
- Export targetsYou choose css-tailwind, json-tailwind or dtcg as the export format.
- Validation commandsThe DESIGN.md spec, lint and export commands run through npx @google/design.md, and diff runs when updating.
- Fixed section orderOverview, Colors, Themes, Typography, Layout, Elevation and Depth, Shapes, Components, Do's and Don'ts.
- Token mapping rulesTypography entries are mappings with canonical fields, and a single source --radius becomes rounded.base.
Frequently asked questions
What is the create-design-md skill?
It is a skill in the ibelick/ui-skills repository that writes or updates a DESIGN.md file from your repository or a live URL. Each token is recorded with evidence, and the result is validated with lint and export commands.
How do I install it?
Clone ibelick/ui-skills and copy the skills/create-design-md folder into your AI coding agent's skills folder. Then ask the agent to create a DESIGN.md for your repository, or give it a URL to analyze.
What is the difference between repository and URL mode?
Repository mode reads your own code. URL mode reads a rendered website, needs browser access that can render pages, and samples up to 3 same-origin pages, with a 3-proof gate before any claim is recorded.
Which export formats are supported?
The skill picks an export target of css-tailwind, json-tailwind or dtcg. The agent runs the DESIGN.md export command for the chosen target and reports the result alongside the lint output.
Does it change my other files?
No. The skill says it modifies only DESIGN.md. Your source files, styles and configuration are left alone, which makes it safe to run before you decide how to use the design system.
How are values traced back to a source?
Every finding is stored with its role, value, source, scope, recurrence and confidence, so a reader can see where a token came from and how often it appeared, instead of trusting an unexplained number.
Where does the file get used afterwards?
Give DESIGN.md to your agent before it builds screens, or pair it with baseline-ui for rule-based audits. It then works as a written reference for colors, type, spacing and components.