| name | create-design-system |
| description | Use when the user asks to produce a reusable design system or UI kit from an existing brand, codebase, or product. Writes to ./opendesign/design-systems/<name>/ so opendesign can auto-discover it in future sessions. |
Loaded when the user asks you to produce a reusable design system or UI kit from an existing brand, codebase, or product.
Where design systems live
All design systems for a project live under ./opendesign/design-systems/<name>/. Multiple systems can coexist — for example, ./opendesign/design-systems/marketing/, ./opendesign/design-systems/product/, ./opendesign/design-systems/deck-template/. The name is required and descriptive of what the system is for (brand surface, product surface, deck template, co-brand partner). Never use design-system/ singular or generic names like main.
A folder is recognized as a design system if it contains either a SKILL.md or a tokens file (colors_and_type.css at the root, or tokens/colors_and_type.css nested). opendesign accepts either marker when detecting systems. Always write both: the SKILL.md makes the folder portable as a standalone agent skill, and the tokens file is the canonical output of this skill.
Required paths (non-negotiable)
Every generated system MUST write to these exact paths, relative to project root. opendesign auto-discovery depends on them — deviating breaks detection.
./opendesign/design-systems/<name>/SKILL.md — portable skill marker../opendesign/design-systems/<name>/tokens/colors_and_type.css — canonical tokens file. Nested under tokens/, not at the folder root. This is the discovery marker../opendesign/design-systems/<name>/README.md — human-facing index.
Do not write the tokens file to any other path (no colors.css, no styles/tokens.css, no flat colors_and_type.css at the root of the system folder). Do not omit SKILL.md. Do not rename the design-systems/ parent inside opendesign/.
What a design system folder contains
opendesign/design-systems/<name>/
README.md
tokens/
colors_and_type.css
fonts/
[font files the brand actually ships]
assets/
logos/
icons/
imagery/
brand/
voice-and-tone.md
style-notes.md
ui-kit-<product>/
components/ # JSX components, one per file
index.html # interactive showcase of core screens
sample-slides/ # only if a deck template was provided
Process
- Explore provided assets. Read the codebase, the Figma file (via its design context API when available), screenshots, decks. Prefer codebase source and Figma data over screenshots in every case.
- Write the README. State your understanding of the brand, list every source you consulted, and provide an index into the rest of the folder.
- Extract tokens. Write color and type tokens to exactly
./opendesign/design-systems/<name>/tokens/colors_and_type.css — not the folder root, not a renamed file. Also write ./opendesign/design-systems/<name>/SKILL.md so the folder is recognized and portable. Define raw variables (--fg-1, --fg-2, --bg-1, --accent-1, font families, weights, size steps) and semantic variables (--h1, --h2, --body, --caption, --surface-primary, --border-subtle, etc.). Semantic vars reference raw vars.
- Document content fundamentals. Voice, tone, casing (title case vs sentence case), punctuation rules, emoji use, numeric formatting, how the brand talks to users versus about itself.
- Document visual foundations. Color (roles, not just swatches), type (scale, pairing, usage rules), spacing (scale + when to apply), backgrounds (treatments and when each appears), motion (timings, easing, common patterns), hover and press states, borders, shadows, radii, card patterns, imagery vibe.
- Document iconography. Icon fonts, SVG sprites, raster assets, emoji policy, unicode usage. Copy the real asset files into
assets/. Never hand-draw.
- Build UI kits per product. Pixel-perfect recreations of existing components as JSX, one component per file, token-driven. Provide
index.html that assembles the core screens so the kit can be reviewed interactively.
- Build sample slides. Only if a deck template was given. Use the deck skill's conventions.
Hard rules
- Never recreate UIs from screenshots alone when the codebase is available. Codebase is source of truth; screenshots are lossy.
- Never read SVG source files. They burn context for no benefit. Copy the file into
assets/ and reference it by filename.
- Never hand-draw SVGs. Copy the real assets.
- Never invent components. UI kits recreate what exists. If a component is not in the source, leave it out or stub it with a labeled placeholder. Do not fill gaps with your own interpretation.
- Stop and ask if key resources (codebase, Figma file, brand guidelines) are inaccessible. Do not proceed on guesswork.
- Avoid visual motif defaults the industry has exhausted: bluish-purple gradients, emoji-as-feature-cards, rounded cards with a colored left-border accent strip.
Ending the task
Close with a clear ask to iterate: list the parts you were confident about, the parts you were unsure about, and the decisions you want the user to confirm before the system is considered canonical.
