create-design-system

Create design system

Design system creation instructions: Design systems are folders on the file system containing typography guidelines, colors, assets, brand style and tone guides, css styles, and React recreations of UIs, decks, etc. They give design agents the ability to create designs against a company's existing products, and create assets using that company's brand. Design systems should contain real visual assets (logos, brand illustrations, etc), low-level visual foundations (e.g. typography specifics; color system, shadow, border, spacing systems), reusable UI components, and high-level UI kits (full screens).

No need to invoke the create_design_system skill; this is it.

An automated compiler reads this project, bundles the components into a runtime library, and indexes the styles. It discovers everything from file content and sibling relationships — not from folder names — so the only fixed location is:

• styles.css at the project root (or index.css / globals.css / global.css / main.css / theme.css / tokens.css — first match wins). This is the global-CSS entry point; consumers link this one file. Keep it as a list of @import lines only. Everything it transitively @imports is shipped to consumers; @font-face rules anywhere in that closure declare the webfonts.

Organize everything else however suits the brand. A sensible default layout (use it unless the attached codebase or brand has its own convention):

• tokens/ — CSS custom properties, one file per concern (colors.css, typography.css, spacing.css, …), each @imported from styles.css.
• components/<group>/ — reusable React UI primitives.
• ui_kits/<product>/ — full-screen click-through recreations of real product views.
• guidelines/ — foundation specimen cards and deeper-dive prose.
• assets/ — logos, icons, illustrations, imagery.
• readme.md (root) — the design guide and manifest.

What the compiler looks for, regardless of path:

• A component is any <Name>.jsx / <Name>.tsx (PascalCase stem) with a sibling <Name>.d.ts in the same directory. Add <Name>.prompt.md alongside, and one @dsCard-tagged .html per directory (its first line is <!-- @dsCard group="…" -->; details under "Components" below).
• A token is any --* custom property declared under :root (or a single-selector theme scope) in a file reachable from styles.css.
• A font is any @font-face rule in that same closure; its src: url(…) targets are the binaries shipped to consumers.

To begin, create a todo list with the tasks below, then follow it:

• Explore provided assets and materials to gain a high-level understanding of the company/product context, the different products represented, etc. Read each asset (codebase, figma, file etc) and see what they do. Find some product copy; examine core screens; find any design system definitions.
• Create a readme.md (root) with the high-level understanding of the company/product context, the different products represented, etc. Mention the sources you were given: full Figma links, GitHub repos, codebase paths, etc. Do not assume the reader has access, but store in case they do.
• Call set_project_title with a short name derived from the brand/product (e.g. "Acme Design System"). This replaces the generic placeholder so the project is findable.
• IF any slide decks attached, use your repl tool to look at them, extract key assets + text, write to disk.
• Explore the codebase and/or figma design contexts and write the token CSS files — CSS custom properties on :root, both base values (--fg-1, --font-serif-display) and semantic aliases (--text-body, --surface-card). Copy any webfonts/ttfs into the project and write the @font-face rules in a CSS file. Then write the root styles.css as a list of @import lines only (never inline rules there) that reaches every token and font-face file.
• Explore, then update readme.md with a CONTENT FUNDAMENTALS section: how is copy written? What is tone, casing, etc? I vs you, etc? are emoji used? What is the vibe? Include specific examples
• Explore, update readme.md with VISUAL FOUNDATIONS section that talks about the visual motifs and foundations of the brand. Colors, type, spacing, backgrounds (images? full-bleed? hand-drawn illustrations? repeating patterns/textures? gradients?), animation (easing? fades? bounces? no anims?), hover states (opacity, darker colors, lighter colors?), press states (color? shrink?), borders, inner/outer shadow systems, protection gradients vs capsules, layout rules (fixed elements), use of transparency and blur (when?), color vibe of imagery (warm? cool? b&w? grain?), corner radii, what do cards look like (shadow, rounding, border), etc. whatever else you can think of. answer ALL these questions.
• If you are missing font files, find the nearest match on Google Fonts. Flag this substitution to the user and ask for updated font files.
• As you work, create foundation specimen cards (small HTML files) that populate the Design System tab. Target ~700×150px each (400px max) — err toward MORE small cards, not fewer dense ones. Split at the sub-concept level: separate cards for primary vs neutral vs semantic colors; display vs body vs mono type; spacing tokens vs a spacing-in-use example. A typical foundations set is 12–20+ cards. Skip titles and framing — the card name renders OUTSIDE the card, so just show the swatches/specimens/tokens directly with minimal decoration. Each card links styles.css (relative path from wherever you put it) so it picks up the real tokens. Tag each card with <!-- @dsCard group="<Group>" viewport="700x<height>" subtitle="<one line>" name="<Card name>" --> as its first line — the Design System tab renders every tagged .html in the project, grouped verbatim by group. Suggested groups: "Type", "Colors", "Spacing", "Brand" — title-cased, consistent.
• Copy logos, icons and other visual assets into assets/. If the provided sources contain no logo, do not create one: render the brand name in plain type wherever a mark would go and note the absence in readme.md. Never draw, reconstruct, or approximate a company's real logo or brand mark from memory — even when the company seems identifiable from font names or sample content — and never rebrand the design system with a company identity the user didn't provide. Update readme.md with an ICONOGRAPHY section describing the brand's approach to iconography. Answer ALL these and more: are certain icon systems used? is there a builtin icon font? are there SVGs used commonly, or png icons? (if so, copy them in!) Is emoji ever used? Are unicode chars used as icons? Make sure to copy key logos, background images, maybe 1-2 full-bleed generic images, and ALL generic illustrations you find. NEVER draw your own SVGs or generate images; COPY icons programmatically if you can.
• For icons: FIRST copy the codebase's own icon font/sprite/SVGs into assets/ if you can. Otherwise, if the set is CDN-available (e.g. Lucide, Heroicons), link it from CDN. If neither, substitute the closest CDN match (same stroke weight / fill style) and FLAG the substitution. Document usage in ICONOGRAPHY.
• Author the reusable components (see the Components section). Each directory's card HTML must carry <!-- @dsCard group="Components" … --> on line 1.
• For each product given (e.g. app and website), create a UI kit — {README.md, index.html, Screen1.jsx, …} in its own directory; see the UI kits section. Verify visually. Make one todo list item for each product/surface.
• If you were given a slide template, create sample slides — {index.html, TitleSlide.jsx, ComparisonSlide.jsx, BigQuoteSlide.jsx, …} in their own directory. If no sample slides were given, don't create them. Create an HTML file per slide type; if decks were provided, copy their style. Use the visual foundations and bring in logos + other assets. Tag each slide HTML with <!-- @dsCard group="Slides" viewport="1280x720" --> on line 1 so the 16:9 frame scales to fit the card.
• Tag each UI kit's index.html with <!-- @dsCard group="<Product>" viewport="<design width>x<above-fold height>" --> — the declared height caps what's shown, so pick the portion worth previewing.
• Update readme.md with a short "index" pointing the reader to the other files available. This should serve as a manifest of the root folder, plus a list of components, ui kits, etc.
• Create SKILL.md file (details below)
• You are done! The Design System tab shows every registered card. Do NOT summarize your output; just mention CAVEATS (e.g. things you were unable to do or unsure) and have a CLEAR, BOLD ASK for the user to help you ITERATE to make things PERFECT.