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.

Components

• These are the brand's reusable UI primitives. When a concrete source defines the inventory (a mounted .fig file, a Figma link, a component library in an attached codebase), that inventory IS the component list — build exactly the families the source defines, nothing more. Do not add primitives a design system "usually" has (Toast, Avatar, Tabs, …) when the source doesn't define them; a component with no counterpart in the source is an invention consumers will trust and designers won't recognize. If an addition is genuinely needed (e.g. an Icon wrapper for a glyph set), list it in readme.md under "Intentional additions" with a one-line reason. Only when NO source defines components (brand-guidelines-only or from-scratch runs) should you author a standard set — Button, IconButton, Input, Select, Checkbox, Radio, Switch, Card, Badge, Tag, Tabs, Dialog, Toast, Tooltip — sized to the brand's needs. Either way, group by concern (e.g. forms/, feedback/, navigation/ under whatever parent directory you choose); a single core/ group is fine for a small set.
• Enumerate before you build: list the source's FULL component inventory FIRST (for a mounted .fig, read /METADATA.md's "Component families" section; for a Figma link, list the file's pages and components via get_design_context), put every family on your todo list, and build ALL of them, tracking progress against that list. Do NOT stop at a "core subset". If you cannot finish, end your turn by reporting exactly which families remain unbuilt and ask the user whether to continue — never end silently incomplete.
• Each component is one file <Name>.jsx (or .tsx) with export function <Name>(props) {…} — a named, PascalCase export; that name becomes the public API and the literal export keyword is required so the bundler picks it up. Keep them self-contained: import React only, reference styling via the CSS custom properties (no CSS-in-JS libs, no npm packages). Siblings may import each other with relative paths.
• In the same directory, write <Name>.d.ts with the props interface — the sibling .d.ts is what gives a component its props contract, adherence rules, and starting-point eligibility; a .jsx without one is still bundled and exported under the namespace but gets none of those — and <Name>.prompt.md (first line is a one-sentence "what & when", then a small JSX usage example, then notable variants/props).
• One card HTML per directory (name it whatever you like — e.g. buttons.card.html): first line is <!-- @dsCard group="Components" viewport="700x<height>" name="<Directory label>" -->. Link styles.css via the correct relative path, load the bundle via <script src="…/_ds_bundle.js"> (relative path to project root), then mount with const { <Name> } = window.<Namespace> in a <script type="text/babel"> block — call check_design_system to get the exact <Namespace>. Do NOT <script src> the .jsx directly (its export is unreachable from inline script). Show key states/variants (primary/secondary/ghost; sizes; disabled; with icon; etc.). Make it dense and scannable, not a single default render.
• Do NOT write _ds_bundle.js, _ds_manifest.json, _adherence.oxlintrc.json, or a barrel index.js — those are generated automatically.