design-systems

# Design Systems Design systems store brand identity tokens (colors, fonts, spacing, logos) that are applied to all designs in a project. Before creating or applying a system, read the `creative-context` skill and retrieve approved brand primitives separately from factual, visual, and layout examples. Apply its exact reuse ladder before inventing new primitives. A context pack is an immutable generation snapshot; it is not a design system and must not be silently promoted into one. Preserve the chosen `contextPackId` and reuse labels on the generation session/screens, and require an explicit user decision before making a retrieved pattern a durable design-system default. ## Data Model Design systems are stored in the `design_systems` SQL table. Each has: - `id` — unique identifier - `title` — display name (e.g., "Acme Corp Brand") - `description` — optional description - `data` — JSON string containing `DesignSystemData` tokens - `assets` — JSON string containing `DesignSystemAsset[]` (logos, fonts, images) - `is_default` — boolean, whether this is the user's default design system - `owner_email` — auto-set from session - `org_id` — organization scope - `visibility` — defaults to `org` inside an organization, otherwise `private` ### DesignSystemData Schema ```typescript interface DesignSystemData { colors: { primary: string; // Main background (#0F172A) secondary: string; // Secondary background (#1E293B) accent: string; // Accent/CTA color (#0EA5E9) background: string; // Page background (#0F172A) surface: string; // Card/panel background (#1E293B) text: string; // Primary text (#F8FAFC) textMuted: string; // Secondary text (#94A3B8) }; typography: { headingFont: string; // Google Fonts name ("Space Grotesk") bodyFont: string; // Google Fonts name ("DM Sans") headingWeight: string; // e.g., "700" bodyWeight: string; // e.g., "400" headingSizes: { h1: string; // e.g., "64px" h2: string; // e.g., "40px" h3: string; // e.g., "28px" }; }; spacing: { pagePadding: string; // e.g., "80px 110px" elementGap: string; // e.g., "24px" }; borders: { radius: string; // e.g., "12px" accentWidth: string; // e.g., "4px" }; defaults: { background: string; // e.g., "#0F172A" labelStyle: "uppercase" | "lowercase" | "capitalize" | "none"; }; logos: { url: string; name: string; variant: "light" | "dark" | "auto"; }[]; imageStyle?: { referenceUrls: string[]; styleDescription: string; // e.g., "Clean, minimal product photography" }; customCSS?: string; // Extra CSS injected into designs notes?: string; // Free-form brand notes } ``` `imageStyle.styleDescription` is not just metadata — fold it into every `generate-asset` prompt for a design linked to this system, alongside the subject/composition/lighting direction described in the design-generation skill's Imagery section. This is what keeps generated photography/illustration on-brand instead of drifting to a generic stock look each time. ## Actions ### Creating a Design System ```bash pnpm action create-design-system \ --title "Acme Corp Brand" \ --description "Corporate brand identity" \ --data '{ "colors": { "primary": "#0F172A", "secondary": "#1E293B", "accent": "#2563EB", "background": "#0F172A", "surface": "#1E293B", "text": "#F8FAFC", "textMuted": "#94A3B8" }, "typography": { "headingFont": "<HEADING_FONT>", "bodyFont": "<BODY_FONT>", "headingWeight": "700", "bodyWeight": "400", "headingSizes": { "h1": "64px", "h2": "40px", "h3": "28px" } }, "spacing": { "pagePadding": "80px 110px", "elementGap": "24px" }, "borders": { "radius": "12px", "accentWidth": "4px" }, "defaults": { "background": "#0F172A", "labelStyle": "uppercase" }, "logos": [] }' ``` `<HEADING_FONT>` / `<BODY_FONT>` are placeholders — pick a real Google Fonts pairing per the design-generation skill's Font Recommendations table (or the brand's actual extracted fonts) rather than defaulting to Space Grotesk/DM Sans every time; that pairing is this skill's own most common convergence fingerprint. If this is the user's first design system in the active organization, it is automatically set as the default. Organization-scoped systems are shared with that organization by default. ### Starting from an established public system Use the curated production templates instead of recreating familiar systems from memory: ```bash pnpm action create-design-system --templateId material-3 pnpm action create-design-system --templateId carbon-white pnpm action create-design-system --templateId primer-light ``` Each template is a source-linked, versioned snapshot with real semantic tokens, type scales, spacing, shapes, CSS variables, state guidance, attribution, and brand-misrepresentation guardrails. The action may accept a custom `title`, `description`, or additional `customInstructions`, but it intentionally rejects `data` overrides when `templateId` is present so the named snapshot cannot silently become a lookalike. Use `get-design-system` after creation when the full stored snapshot is needed. ### Reading a Design System ```bash pnpm action get-design-system --id <designSystemId> ``` Returns the full `data` and `assets` JSON. ### Listing All Design Systems ```bash pnpm action list-design-systems pnpm action list-design-systems --compact true ``` ### Updating Tokens ```bash pnpm action update-design-system --id <id> --data '<updated JSON>' ``` Only provided fields are updated. You can also update `--title`, `--description`, or `--assets`. ### Setting Default ```bash pnpm action set-default-design-system --id <id> ``` Pass `--isDefault false` to clear the current default. Setting a system as the default unsets the previous default in the same user and organization scope. ### Deleting a Design System ```bash pnpm action delete-design-system --id <id> ``` Requires admin access or higher — the owner, or anyone holding an `admin` share role. That is the same `canManage` flag `list-design-systems` returns and the Design Systems page renders its Delete control from. Removes the system and its shares, and clears `designSystemId` on every linked design and saved template the caller can edit — a design system's admin share does not grant write access to every design or template that happens to reference it, so ones the caller can't edit keep a dangling reference instead, reported back as `designsSkippedForAccess` / `templatesSkippedForAccess` (both `get-design-template` and `list-design-templates` already resolve a dangling `designSystemId` back to `null` rather than erroring). Those designs keep the tokens already baked into their HTML, so a design can still look on-brand while no longer linked to a system. If the deleted system was the owner's default, another of their design systems is promoted to default so future design creation doesn't silently drop to "no design system". ## Multi-Source Import Flow The design system setup page collects brand assets from multiple sources. When the user clicks "Continue to generation", a structured message is sent to the agent with all sources. Process each source type with the appropriate action: ### Source: Website URL ```bash pnpm action import-from-url --url "https://acme.com" ``` Renders the live page in a real browser first, then returns a bounded design.md-style visual system: computed semantic colors, typography, spacing, radii, shadows, representative component styles, CSS variables, logo references, screenshots evidence metadata, and reusable Brand Kit data. This works for React/CSS-in-JS/Tailwind pages because it reads the computed cascade; it reports an explicit static SSRF-safe fallback when no browser is available. ### Source: GitHub Repository ```bash pnpm action index-design-system-with-builder --githubSources '[{"repoUrl":"https://github.com/acme/ui","ref":"main","include":["src/styles","design.md"]}]' ``` Starts one Builder design-system job with one or more GitHub sources. Each source can pin a branch, tag, or commit and include repository-relative files or folders. Unscoped public repositories stay native Builder sources so large codebases are not truncated; private repos and scoped refs stay server-side and use the saved `GITHUB_TOKEN` without exposing it to the browser or Builder. Builder is the source of truth for the indexed brand kit, generated docs, and usage guidance. If Builder is not connected, stop and ask the user to connect Builder. The legacy `githubRepoUrl` argument remains compatible for one unscoped repo. For a saved GitHub-backed system, use `sync-design-system-with-builder --id <localDesignSystemId>` to replay the stored repository/ref/scope after upstream changes. Do not create a second local copy. ### Source: Local Code Files ```bash pnpm action index-design-system-with-builder --codeFiles '[{"filename":"globals.css","content":"..."}]' ``` Uploads code/design files to Builder and starts design-system indexing. Do not create a local design system from uploaded code files unless the user explicitly asks for a manual local fallback. For the active design's Tokens panel, use `import-design-tokens` when the user wants to pull reusable CSS vars/tokens straight into the open design without creating a full design system: ```bash pnpm action import-design-tokens \ --designId "design_123" \ --source files \ --files '[{"filename":"design.md","content":"Primary color: #2563eb"}]' ``` Supported sources are `files`, `paste`, and `current-design`. The action parses CSS variables, design.md-style labeled lines, Tailwind/theme JSON, DTCG (W3C design tokens) JSON, colors, spacing, radii, and fonts, then persists them through the design's `tweakSelections` so the canvas updates like any other token edit. DTCG `$type`s become token types (see below), and `{group.token}` references become `var(--group-token)`. Treat manual `apply-design-token-edit` calls as a last-resort one-off edit after import has been tried or ruled out. When you do create a token with `apply-design-token-edit`, pass `type` (`color`, `font-family`, `font-weight`, `font-size`, `line-height`, `letter-spacing`, `spacing`, `container`, `breakpoint`, `radius`, `shadow`, `opacity`) — the same types the Tokens panel `+` menu offers. It is stored in `designs.data.tokenTypes`; without it the type is guessed from the name, which often gets the font types and opacity wrong. Each type belongs to one panel section (font types go under Typography, opacity under Shadows & Effects). Omit `type` when only changing an existing token's value. ### Source: Documents (DOCX, PPTX, PDF) ```bash pnpm action import-document --files '[{"filename":"brand.pptx","fileType":"application/pptx","sizeBytes":1234}]' ``` Returns content-type-aware design hints and agent instructions. Presentations are the strongest signal for brand colors/fonts. ### Source: Existing Project or Design System ```bash pnpm action import-design-project --designId "abc123" pnpm action import-design-project --designId _ --designSystemId "ds-456" ``` Extracts CSS tokens from a project's generated HTML, or clones an existing design system for forking. ### Source: Figma file ```bash pnpm action index-design-system-with-builder \ --projectName "Acme Figma system" \ --codeFiles '[{"filename":"figma-summary.md","content":"<extracted tokens / styles summary>"}]' ``` Builder is the required extraction/indexing path for Figma-backed design systems. If a connected Figma MCP is available (tools like `get_variable_defs`, `get_design_context`, `get_metadata`, `get_screenshot`), call those on the file/selection first to pull real variables, color/text styles, and screenshot notes, then pass that summary to `index-design-system-with-builder` as an uploaded text context file. Do not build a local design system from the Figma summary unless the user explicitly asks for a manual local fallback. **When the user uploads a raw `.fig` file on the Design System Setup page**, send it to Builder design-system indexing through the setup page upload route. Do not parse `.fig` files locally for this flow and do not call `create-design-system` from raw `.fig` output; Builder owns the indexed brand kit, generated docs, and usage guidance. This is unchanged and is specifically about **token/brand-kit extraction**. **When the user uploads a raw `.fig` file in the Design editor's Import panel** (not Design System Setup), it takes a different, narrower path: the server decodes the container/Kiwi document locally (`fig-file-decoder.ts`) and maps its `NodeChange` tree to editable HTML screens (`fig-file-to-html.ts`, `fig-file-import.ts`) through the same `saveImportedDesignFiles` path as other Design imports — no Builder connection required. This is explicitly scoped to **screens only**, not tokens: it does not create or update a design system, and it is separate from (and does not reopen) the Design System Setup `.fig` upload above. Treat it as experimental — the `.fig` container is a proprietary, undocumented format, so unsupported node types, geometry, or schema variants fail closed with an explicit warning/placeholder rather than a silent approximation. Read the returned `fidelityReport` (`stats`, `warnings`) and explain the conversion coverage and any listed fallbacks. See `FIGMA_INTEROPERABILITY.md` for supported import and export workflows. **When the user wants a native component drawer inside Design**, use `list-design-native-assets` to choose an editable primitive/component/layout, then `insert-design-native-asset` to insert it into the active screen. These entries are Design-native HTML stamped with component/layer metadata. **When the user wants reusable Figma components/assets**, do not run design-system indexing just to insert a component. Use `list-figma-library-assets` with a Figma file URL/key, then `insert-figma-library-asset` with the returned `renderUrl`, `fileKey`, `nodeId`, `componentKey`, and `sourceUrl`. This inserts a rendered component/component set with provenance. Styles and variables still belong in the Builder-backed design-system path above. ### Import from a Figma URL or file **When the user pastes a Figma frame/screen link and wants an editable Design screen** (not a component insert), use `import-figma-frame` instead of `list-figma-library-assets` + `insert-figma-library-asset`: ```bash pnpm action import-figma-frame --figmaUrl "https://www.figma.com/design/<fileKey>/<name>?node-id=<id>" # or pnpm action import-figma-frame --fileKey "<fileKey>" --nodeId "12:34" --designId "<designId>" ``` - Accepts a full Figma URL (design/file/proto share links, including `/branch/<key>/` branch URLs — the branch's own key is used automatically) or an explicit `fileKey` + `nodeId`. If `nodeId` is omitted, the first `FRAME` node on the file's first page is imported. - Maps the node tree to real HTML/CSS: exact position/size, auto-layout as flexbox, text (font, line-height, letter-spacing, case, decoration, align), fills (solid/gradient/image, correctly layered and gradient-angle-derived, not a default angle), strokes (including the CENTER/INSIDE/OUTSIDE distinction), per-corner radii, shadows/blur, opacity, and blend modes. Vector networks, boolean operations, and other structurally unsupported node types are rendered as an exact PNG at 2x scale instead of an approximated shape guess. - Saves the result as a new screen via the same import path as other Design imports (`saveImportedDesignFiles`), placed on the overview canvas. - Returns a `fidelityReport` — `exactCount`, `approximated` (properties CSS can only approximate: rotation, per-side stroke weights, radial/angular/