/stitch-design-system

name: stitch-design-system
description: Extracts a Stitch design and generates production code artifacts — CSS custom properties with dark mode tokens, a Tailwind v4 @theme block, and a semantic design system document. Run this before framework conversion skills.
allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"
  - "Write"

Stitch → Design System Code Artifacts

You are a design systems engineer. You analyze Stitch designs and generate **code artifacts** — not just documentation. While the `design-md` skill produces a human-readable markdown file, this skill produces files you actually import into your codebase: CSS custom properties with dark mode, Tailwind v4 configuration, and typography tokens.

**Use this skill first, before `stitch-nextjs-components` or `stitch-svelte-components`.** The generated tokens become the foundation for all subsequent component generation.

When to use this skill

Use this skill when:

• Starting a new project from a Stitch design
• The user mentions "design tokens", "CSS variables", "dark mode tokens", "Tailwind config"
• Running before framework conversion skills to ensure design consistency
• Updating an existing project's design system after a Stitch design update

What this skill generates

Three output files:

| File | Purpose | |------|---------| | `design-tokens.css` | CSS custom properties — import this in your framework's global CSS | | `tailwind-theme.css` | Tailwind v4 `@theme` block — paste into your `globals.css` | | `DESIGN.md` | Extended design document (richer than `design-md`, includes dark mode + animation tokens) |

Step 1: Retrieve the Stitch design

1. **Namespace discovery** — Run `list_tools` to find the Stitch MCP prefix. 2. **Fetch screen** — Call `[prefix]:get_screen` with `projectId` and `screenId`. 3. **Download HTML** — Run:

   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"

4. **Visual reference** — Check `screenshot.downloadUrl` to see the full design intent.

If multiple screens exist, retrieve all of them. Run `[prefix]:list_screens` and fetch each one to ensure the token set covers every pattern in the design.

Step 1.5: Read project DesignTheme (ground truth)

Before parsing HTML, get the authoritative design data from the Stitch API. This eliminates guesswork — the API knows the exact primary color, fonts, and full semantic color map.

1. **Call `get_project`** with `projects/[projectId]` 2. **Check for `designMd`** — if present, it's a full markdown design system document that Stitch auto-generated. Parse it for typography rules, color philosophy, component patterns, spacing guidelines, and do's/don'ts. This is the most valuable single field. 3. **Extract `namedColors`** — a 40+ token semantic color map. This gives you the ENTIRE color system pre-computed:

• Primary: `primary`, `on_primary`, `primary_container`, `on_primary_container`, `primary_fixed`, `primary_fixed_dim`
• Secondary: `secondary`, `on_secondary`, `secondary_container`, `on_secondary_container`
• Tertiary: same pattern
• Surfaces: `surface`, `surface_dim`, `surface_bright`, `surface_container_lowest`, `surface_container_low`, `surface_container`, `surface_container_high`, `surface_container_highest`, `surface_tint`, `surface_variant`
• Utility: `background`, `on_background`, `on_surface`, `on_surface_variant`, `outline`, `outline_variant`
• States: `error`, `on_error`, `error_container`, `on_error_container`
• Inverse: `inverse_surface`, `inverse_on_surface`, `inverse_primary`

4. **Extract structural values:**

| DesignTheme field | → CSS token | Mapping | |---|---|---| | `customColor` | `--color-primary` | Hex seed — but prefer `namedColors.primary` if available | | `overridePrimaryColor` | `--color-primary` | Takes precedence over customColor | | `overrideSecondaryColor` | `--color-secondary` | Exact hex override | | `overrideTertiaryColor` | `--color-tertiary` | Exact hex override | | `overrideNeutralColor` | `--color-neutral` | Base for surface hierarchy | | `backgroundLight` | `--color-background` (light) | Light mode page background | | `backgroundDark` | `--color-background` (dark) | Dark mode page background | | `headlineFont` | `--font-sans` / heading | Map enum → font-family stack (see table below) | | `bodyFont` | `--font-body` | Map enum → font-family stack | | `labelFont` | `--font-label` | Map enum → font-family stack | | `roundness` | `--radius-md` baseline | ROUND_FOUR=4px, ROUND_EIGHT=8px, ROUND_TWELVE=12px, ROUND_FULL=9999px (ROUND_TWO also exists but is deprecated/unused) | | `spacingScale` | spacing multiplier | 0=tight (base 2px), 1=compact (base 4px), 2=normal (base 4px), 3=spacious (base 8px) | | `spacing` | `--space-*` overrides | Optional map of spacing token name → CSS value (e.g. `{"sm": "8px"}`) — use in place of `spacingScale` when present | | `typography` | `--text-*` / `--font-*` overrides | Optional map of level name (`h1`, `body`, etc.) → Typography token (`fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, `lineHeight`) | | `colorVariant` | informs palette approach | e.g., FIDELITY means stick to brand colors, VIBRANT means boost saturation |

**Font enum → CSS font-family mapping:**

| Stitch enum | CSS font-family | |---|---| | `INTER` | `'Inter', system-ui, sans-serif` | | `DM_SANS` | `'DM Sans', system-ui, sans-serif` | | `GEIST` | `'Geist', system-ui, sans-serif` | | `SPACE_GROTESK` | `'Space Grotesk', system-ui, sans-serif` | | `MANROPE` | `'Manrope', system-ui, sans-serif` | | `PLUS_JAKARTA_SANS` | `'Plus Jakarta Sans', system-ui, sans-serif` | | `WORK_SANS` | `'Work Sans', system-ui, sans-serif` | | `IBM_PLEX_SANS` | `'IBM Plex Sans', system-ui, sans-serif` | | `RUBIK` | `'Rubik', system-ui, sans-serif` | | `SORA` | `'Sora', system-ui, sans-serif` | | `EPILOGUE` | `'Epilogue', system-ui, sans-serif` | | `NUNITO_SANS` | `'Nunito Sans', system-ui, sans-serif` | | `LEXEND` | `'Lexend', system-ui, sans-serif` | | `PUBLIC_SA