create-design-system

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

1. 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.
2. Write the README. State your understanding of the brand, list every source you consulted, and provide an index into the rest of the folder.
3. 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.
4. 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.
5. 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.
6. Document iconography. Icon fonts, SVG sprites, raster assets, emoji policy, unicode usage. Copy the real asset files into assets/. Never hand-draw.
7. 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.
8. 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.