Stitch-kit stitch-design-system

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.

install

source · Clone the upstream repo

git clone https://github.com/gabelul/stitch-kit

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/gabelul/stitch-kit "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/stitch-design-system" ~/.claude/skills/gabelul-stitch-kit-stitch-design-system && rm -rf "$T"

manifest: skills/stitch-design-system/SKILL.md

source content

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

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

Download HTML — Run:

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

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.

Call
get_project
with
```
projects/[projectId]
```
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.

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

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
`spacingScale`	spacing multiplier	0=tight (base 2px), 1=compact (base 4px), 2=normal (base 4px), 3=spacious (base 8px)
`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_SANS`	`'Public Sans', system-ui, sans-serif`
`SOURCE_SANS_THREE`	`'Source Sans 3', system-ui, sans-serif`
`MONTSERRAT`	`'Montserrat', system-ui, sans-serif`
`HANKEN_GROTESK`	`'Hanken Grotesk', system-ui, sans-serif`
`ARIMO`	`'Arimo', system-ui, sans-serif`
`BE_VIETNAM_PRO`	`'Be Vietnam Pro', system-ui, sans-serif`
`SPLINE_SANS`	`'Spline Sans', system-ui, sans-serif`
`METROPOLIS`	`'Metropolis', system-ui, sans-serif`
`EB_GARAMOND`	`'EB Garamond', Georgia, serif`
`LITERATA`	`'Literata', Georgia, serif`
`SOURCE_SERIF_FOUR`	`'Source Serif 4', Georgia, serif`
`LIBRE_CASLON_TEXT`	`'Libre Caslon Text', Georgia, serif`
`NEWSREADER`	`'Newsreader', Georgia, serif`
`DOMINE`	`'Domine', Georgia, serif`
`NOTO_SERIF`	`'Noto Serif', Georgia, serif`

Use these as the baseline. Then use HTML analysis (Step 2) only for values the API doesn't provide: motion/transition durations, exact spacing pixel values, shadow definitions, additional colors beyond the namedColors set.

namedColors

is available, skip the color extraction in Step 2 entirely — the API's color map is authoritative and complete. Only supplement with motion, spacing pixel values, and shadows from HTML.

designMd

is available, use it as the foundation for the DESIGN.md output (Step 5). Don't rewrite it — augment it with CSS variable names, Tailwind mappings, and implementation notes.

Step 2: Extract supplementary values from HTML

If Step 1.5 provided

namedColors

and

designMd

, you only need HTML for:

Motion

Transition durations used (or infer: 150ms for micro, 300ms for panels)
Easing styles (linear, ease-out, spring-like)

Spacing pixel values

Exact gap/padding values used in the design
Shadow definitions

Additional colors (rare)

Only if the design uses colors not in

namedColors

— check for gradients, overlays, or custom accent colors.

If Step 1.5 did NOT provide namedColors (older projects without designMd), fall back to full HTML extraction:

Colors (fallback)

Identify every distinct color from the Tailwind config in

<head>

or infer from screenshot. For each, determine semantic role and usage frequency. Aim for 8-12 semantic tokens.

Typography (fallback)

Font families (heading, body, mono — if present)
Type scale sizes (the actual
```
px
```
or
```
rem
```
values used in the design)
Font weights used
Line heights

Spacing & geometry (fallback)

Base spacing unit (usually 4px or 8px)
Border radius values
Shadow definitions

Step 3: Generate

design-tokens.css

Create

design-tokens.css

with full light + dark mode token sets.

Naming convention:

```
--color-*
```
— Color tokens
```
--font-*
```
— Typography
```
--spacing-*
```
— Spacing scale
```
--radius-*
```
— Border radius
```
--shadow-*
```
— Elevation
```
--motion-*
```
— Animation timing

Template (when namedColors is available from API — preferred):

/* =============================================================
   Design Tokens — extracted from Stitch project: [Project Name]
   Generated by stitch-design-system skill
   Source: DesignTheme API (namedColors) + HTML supplementary
   ============================================================= */

/* ---- Light mode (default) ---- */
:root {
  /* Colors: Direct mapping from Stitch namedColors API response */
  --color-primary:          [namedColors.primary];
  --color-on-primary:       [namedColors.on_primary];
  --color-primary-container: [namedColors.primary_container];
  --color-secondary:        [namedColors.secondary];
  --color-on-secondary:     [namedColors.on_secondary];
  --color-tertiary:         [namedColors.tertiary];
  --color-on-tertiary:      [namedColors.on_tertiary];
  --color-error:            [namedColors.error];
  --color-on-error:         [namedColors.on_error];
  --color-background:       [namedColors.background];
  --color-on-background:    [namedColors.on_background];
  --color-surface:          [namedColors.surface];
  --color-on-surface:       [namedColors.on_surface];
  --color-surface-variant:  [namedColors.surface_variant];
  --color-on-surface-variant: [namedColors.on_surface_variant];
  --color-surface-container: [namedColors.surface_container];
  --color-surface-container-low: [namedColors.surface_container_low];
  --color-surface-container-high: [namedColors.surface_container_high];
  --color-surface-container-highest: [namedColors.surface_container_highest];
  --color-outline:          [namedColors.outline];
  --color-outline-variant:  [namedColors.outline_variant];
  --color-inverse-surface:  [namedColors.inverse_surface];
  --color-inverse-on-surface: [namedColors.inverse_on_surface];
  --color-inverse-primary:  [namedColors.inverse_primary];
  --color-surface-tint:     [namedColors.surface_tint];

  /* Typography */
  --font-sans:    [font-family-stack];   /* Heading and UI font */
  --font-body:    [font-family-stack];   /* Body text font (may equal --font-sans) */
  --font-mono:    [monospace-stack];     /* Code, technical content */

  /* Type scale */
  --text-xs:   0.75rem;   /* 12px */
  --text-sm:   0.875rem;  /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg:   1.125rem;  /* 18px */
  --text-xl:   1.25rem;   /* 20px */
  --text-2xl:  1.5rem;    /* 24px */
  --text-3xl:  1.875rem;  /* 30px */
  --text-4xl:  2.25rem;   /* 36px */

  /* Spacing scale (base 4px) */
  --space-1:  0.25rem;   /* 4px */
  --space-2:  0.5rem;    /* 8px */
  --space-3:  0.75rem;   /* 12px */
  --space-4:  1rem;      /* 16px */
  --space-6:  1.5rem;    /* 24px */
  --space-8:  2rem;      /* 32px */
  --space-12: 3rem;      /* 48px */
  --space-16: 4rem;      /* 64px */

  /* Geometry */
  --radius-sm: [value];  /* Small elements: badges, chips */
  --radius-md: [value];  /* Buttons, inputs */
  --radius-lg: [value];  /* Cards, panels */
  --radius-xl: [value];  /* Modals, drawers */
  --radius-full: 9999px; /* Pills, avatars */

  /* Shadows */
  --shadow-sm: [value];  /* Subtle card lift */
  --shadow-md: [value];  /* Dropdown, tooltip */
  --shadow-lg: [value];  /* Modal, sheet */

  /* Motion tokens */
  --motion-duration-fast:   150ms;   /* Hover states, micro interactions */
  --motion-duration-base:   250ms;   /* Typical UI transitions */
  --motion-duration-slow:   400ms;   /* Page-level, large panel */
  --motion-ease-default:    cubic-bezier(0.4, 0, 0.2, 1);  /* Material ease */
  --motion-ease-out:        cubic-bezier(0, 0, 0.2, 1);    /* Entries */
  --motion-ease-in:         cubic-bezier(0.4, 0, 1, 1);    /* Exits */
  --motion-ease-spring:     cubic-bezier(0.34, 1.56, 0.64, 1); /* Bouncy open */
}

/* ---- Dark mode ---- */
/* Applied via .dark class (Next.js + next-themes) or [data-theme="dark"] (Svelte) */
.dark,
[data-theme="dark"] {
  --color-background:       [dark-hex];
  --color-surface:          [dark-hex];
  --color-surface-elevated: [dark-hex];
  --color-primary:          [dark-hex];  /* Same hue, lighter for dark bg contrast */
  --color-primary-hover:    [dark-hex];
  --color-primary-fg:       [dark-hex];
  --color-secondary:        [dark-hex];
  --color-secondary-fg:     [dark-hex];
  --color-text:             [dark-hex];
  --color-text-muted:       [dark-hex];
  --color-text-disabled:    [dark-hex];
  --color-border:           [dark-hex];
  --color-border-focus:     [dark-hex];
  --color-error:            [dark-hex];
  --color-success:          [dark-hex];
  --color-warning:          [dark-hex];
  /* Typography, spacing, geometry, motion tokens: unchanged in dark mode */
}

Step 4: Generate

tailwind-theme.css

For projects using Tailwind v4 (no

tailwind.config.js

), generate a

@theme

block.

Important: Tailwind v4 uses

@theme

in CSS, not a JS config file. Map tokens to Tailwind's namespace:

/* tailwind-theme.css — paste into your globals.css or import it */
@import "tailwindcss";

@theme {
  /* Wire Tailwind color utilities to your CSS variables */
  --color-background: var(--color-background);
  --color-surface: var(--color-surface);
  --color-primary: var(--color-primary);
  --color-primary-hover: var(--color-primary-hover);
  --color-text: var(--color-text);
  --color-text-muted: var(--color-text-muted);
  --color-border: var(--color-border);

  /* Fonts */
  --font-sans: var(--font-sans);
  --font-mono: var(--font-mono);

  /* Radius */
  --radius-sm: var(--radius-sm);
  --radius-md: var(--radius-md);
  --radius-lg: var(--radius-lg);

  /* Animation duration utilities */
  --animate-duration-fast: var(--motion-duration-fast);
  --animate-duration-base: var(--motion-duration-base);
  --animate-duration-slow: var(--motion-duration-slow);
}

For Tailwind v3 projects (with

tailwind.config.js

), instead generate a

tailwind.config.js

section using the extracted hex values directly.

Step 5: Generate

DESIGN.md

Produce an extended design document. It has all sections from the standard

design-md

skill plus:

# Design System: [Project Name]

> Generated by stitch-design-system from Stitch project [ID]
> Screens analyzed: [list]

## 1. Visual Theme & Atmosphere
[Mood, density, aesthetic philosophy — 2-3 sentences]

## 2. Color Palette & Roles
| Token | Light | Dark | Role |
|-------|-------|------|------|
| --color-primary | #... | #... | Main CTA, key actions |
| --color-background | #... | #... | Page background |
| ... | | | |

## 3. Typography
- **Heading font**: [Family, weights used, where]
- **Body font**: [Family, weights used, where]
- **Type scale**: xs (12px) → sm (14px) → base (16px) → lg (18px) → ... → 4xl (36px)

## 4. Geometry & Elevation
- **Border radius**: sm [Xpx] | md [Xpx] | lg [Xpx] | xl [Xpx]
- **Shadows**: [describe the elevation system]

## 5. Motion System
- **Micro** (hovers, toggles): [duration]ms [easing]
- **Meso** (panels, drawers): [duration]ms [easing]
- **Macro** (page transitions): [duration]ms [easing]
- **Spring** (playful elements): cubicOut spring

## 6. Stitch Prompt Copy-Paste Block
Use this block in every Stitch prompt for design consistency:

[Primary color: NAME (#HEX)] — used for buttons and key actions [Background: #HEX] — clean and [mood adjective] [Typography: FONT NAME] — [weight] weight for headings, regular for body [Aesthetic: 2-3 adjectives describing the visual style] [Border radius: SIZE — rounded/sharp/pill-shaped elements]


## 7. Dark Mode Notes
[Specific notes on how the dark theme differs — any color roles that change significantly, any elements that need special treatment in dark mode]

Step 6: Output & integration

Write all three files to the project root (or wherever the user specifies):

```
design-tokens.css
```
```
tailwind-theme.css
```
```
DESIGN.md
```

Then tell the user how to use them:

For Next.js:

// app/globals.css
@import '../design-tokens.css';
@import '../tailwind-theme.css';

For SvelteKit:

<!-- src/app.css -->
@import '$lib/design-tokens.css';

For the Stitch loop:

Copy Section 6 from
DESIGN.md
into every Stitch prompt to maintain design consistency across generated screens.

Troubleshooting

Issue	Fix
Can't determine dark mode hex values	Use the light-mode hue, desaturate slightly, and increase lightness by 30-40%
Font not loading	Add Google Fonts `@import` to `design-tokens.css`
Tailwind v3 vs v4 confusion	Check `package.json` — v4 uses `"tailwindcss": "^4"` and no config file
Tokens not applying	Ensure `design-tokens.css` is imported BEFORE component CSS

Integration with other skills

Run this skill before

stitch-nextjs-components

stitch-svelte-components

The framework skills will import
```
design-tokens.css
```
instead of hardcoding values
The
```
DESIGN.md
```
Section 6 feeds into
```
stitch-loop
```
for multi-page consistency

References

```
resources/tokens-template.css
```
— Full template with all token categories