create-design-mdby Julien Thibeaut

Create Design MD Skill.

A Claude Code and Codex skill for brand and design-system work: creates or updates a DESIGN.md from an existing product repository or public website.

Brand & Design Systems
DESIGN.md

Download OpenDesign View usage guide

ibelick/ui-skills · skills/create-design-md/SKILL.mdSKILL.md

--- name: create-design-md description: Create or update a DESIGN.md from an existing product repository or public website. Use when asked to document an interface's design language, reconstruct its visual system, extract design tokens and guidance from current evidence, or give coding agents persistent UI context. Do not modify product source or promote accidental implementation patterns into design decisions. --- ## Boundaries ## 1. Choose the mode ## Shared evidence pipeline ## 2. Trace the evidence ## 3. Decide what belongs ## 4. Write the document

Front matter and section headings read from the upstream file on 2026-09-14 · 16,176 characters in full

01 What it does

What the create-design-md Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

Turns an existing product into a written design contract. In repository mode it audits a local product's tokens, themes, shared primitives and rendered routes and writes DESIGN.md at that product's root; in URL mode it reconstructs a draft from the DOM, computed styles and loaded stylesheets at desktop and mobile widths.

Both modes share one evidence pipeline — role, value, source, scope, recurrence, confidence — and one flat token schema, with css-tailwind, json-tailwind or dtcg export targets. Values survive only if a governing source names them or they pass a three-proof gate, and the document is not released until lint and export succeed. It changes nothing but DESIGN.md.

What it produces

A reconstructed DESIGN.md draft written into the current workspace in URL mode, labelled as a draft.
A report listing the mode and audited product or URL, the governing sources used, and the conflicts or unsupported areas left out of the document.
The final lint and export results, which must both pass before the document is handed back.

See the example prompt ↗

How It Works

01
Choose the Mode
Repository mode when a local product repository is available, writing DESIGN.md at that product's root; URL mode when only a public URL is given, producing a reconstructed draft in the current workspace.
02
Collect Evidence and Record Provenance
Each candidate is recorded with its source, scope and recurrence before anything is normalized, so both modes feed the same record pipeline.
03
Normalize into the DESIGN.md Schema
Candidates that are uncertain, local without a contract, or not implementation-relevant are dropped; the rest are mapped into the canonical flat token schema.
04
Gate the Draft Behind Validation
Markdown is written only after the parsed frontmatter passes shape checks, so prose is never drafted first and retrofitted onto the YAML.
05
Lint and Export
Structural linting runs first, then one compatibility export in the selected target, and every populated category must appear in the output.
06
Report Mode, Sources and Gaps
The report names the mode and audited product or URL, the governing sources used, anything omitted as unsupported, and the lint and export results.

02 Find your fit

When to Use the create-design-md Skill

Use the create-design-md skill in Claude Code or Codex when the job is brand and design-system work of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

Documenting an interface's design language and reconstructing its visual system from current evidence in the codebase.
Giving coding agents persistent UI context instead of repeating design decisions per task.
A public site with no source available, where a reconstructed draft from DOM, computed styles and loaded CSS is acceptable.

Know the Boundaries

Editing product source, dependencies or configuration to match the documented design — only the DESIGN.md file is in scope.
Reading internal token names, component ownership or undocumented intent out of a live website: URL evidence cannot establish those.
Working without rendered browser inspection; screenshots or source files must be requested instead of inferring from copy or HTML.
Dumping every token or component discovered — exhaustive inventories are explicitly out of scope.

What to Provide

Which product, if the repo ships severalThe user must name the deployable product being documented; if ownership is ambiguous the skill asks before writing.
A public URL plus rendered browser accessURL mode inspects the DOM, computed styles and publicly loaded stylesheets at desktop and mobile widths; screenshots alone cannot establish exact values.
A non-default export target, if anyURL output defaults to css-tailwind unless the user specifies another target, since token names must stay valid for it.

03 Inside the skill

Rules the create-design-md Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Touch Only the Document
Repository mode must not change product source, dependencies, configuration or generated files, and must not promote accidental implementation patterns into design decisions.
Prefer Repository Evidence
Repository mode is chosen whenever source is available; a supplied URL may verify rendered presentation but never replaces repository evidence.
One Schema, Mapping Shapes Only
Token groups are mappings, never sequences, and both modes must use the same flat token names with no second schema introduced.
Pick the Export Target Before Writing
css-tailwind for Tailwind v4, json-tailwind for Tailwind v3, and dtcg otherwise; token names must be valid for the chosen target.
Three Proofs for URL Claims
A URL-mode claim needs observation, basis and consequence; if any proof is missing the claim is omitted rather than guessed.
Emit Only regex-valid Token Names
Every emitted token name must match ^[a-zA-Z0-9][a-zA-Z0-9-]*$; any key that fails is rejected and rewritten.
Normalize a Single group-level Token
A lone source token such as --radius becomes rounded.base; sm, md, lg and xl are never derived from utility classes or repeated values.
No Release on Failed Validation
The document is never returned while lint or export fails, and a populated category missing from the export is treated as a schema failure.

04 Put it to work

Install create-design-md in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add create-design-md to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/ibelick/ui-skills --skill create-design-md

Generic skills CLI form for skills/create-design-md/SKILL.md; the repository may document its own path.

Give the Skill a First Brand and design-system Work Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Here's the repo for [product] — please document its design language in a DESIGN.md at the root. Pull the token names, typography scales and radius values out of our theme file, and leave out anything our shared components don't actually render. We ship on Tailwind v4, so keep the export compatibility in mind.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Run exactly one compatibility export in the target selected earlier and inspect the output.
For css-tailwind, confirm colors map to --color-, family to --font-, size to --text-, rounded to --radius- and spacing to --spacing-; a populated typography block emitting neither --font- nor --text-* means the document must be rewritten.
Before saving, read the parsed frontmatter back and self-reject scalar typography children or rounded keys absent from the governing source.
When updating an existing document, keep the original contents temporarily and diff it against the new file, restoring any accepted decision that was removed.
Check the installed specification before encoding theme modes, and fall back to a Themes table only if modes are unsupported.

In OpenDesign import create-design-md from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Julien Thibeaut
Repository: github.com/ibelick/ui-skills Branch main
Skill file: skills/create-design-md/SKILL.md Content checksum recorded at verification; commit 79081ab
License: MIT From LICENSE.
Repository stars: 8,402 GitHub snapshot taken 2026-09-14 for the whole ibelick/ui-skills repository, which contains 5 skills in this catalog. Not a rating or usage count for create-design-md.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

BoundariesOnly DESIGN.md changes; no competing schema, no dumping every discovered token.
1. Choose the modeRepository versus URL mode, what each can prove, and when to ask first.
Shared evidence pipelineSix-step record pipeline and omission gates both modes must obey.
2. Trace the evidenceInspection order for repos; sampling list, proofs and evidence ledger for URLs.
3. Decide what belongsSchema shaping, export target choice, theme handling and what prose may claim.
4. Write the documentMinimal frontmatter, allowed section order, and what to delete before saving.
5. ValidateLint, one export, category checks, and diffing an updated document.
6. ReportWhat to return: mode, audited target, sources, omissions, validation results.

The Skill's Own Description

“Create or update a DESIGN.md from an existing product repository or public website. Use when asked to document an interface's design language, reconstruct its visual system, extract design tokens and guidance from current evidence, or give coding agents persistent UI context. Do not modify product source or promote accidental implementation patterns into design decisions.”

Front-matter description from SKILL.md. The full file is about 16,176 characters. Read the full file on GitHub.

Create Design MD

Run create-design-md on a Real Brand and design-system Work Task.

Download OpenDesign, import create-design-md from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills

Terminal

npx skills add https://github.com/ibelick/ui-skills --skill create-design-md

What the create-design-md Skill Does in Claude Code and Codex

In the Skill's Own Terms

How It Works

When to Use the create-design-md Skill

Good Fit

Know the Boundaries

What to Provide

Rules the create-design-md Skill Gives Claude Code and Codex

Touch Only the Document

Prefer Repository Evidence

One Schema, Mapping Shapes Only

Pick the Export Target Before Writing

Three Proofs for URL Claims

Emit Only regex-valid Token Names

Normalize a Single group-level Token

No Release on Failed Validation