Get the FREE Ultimate OpenClaw Setup Guide →

stitch-design-system

npx machina-cli add skill gabelul/stitch-kit/stitch-design-system --openclaw
Files (1)
SKILL.md
11.6 KB

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:

FilePurpose
design-tokens.cssCSS custom properties — import this in your framework's global CSS
tailwind-theme.cssTailwind v4 @theme block — paste into your globals.css
DESIGN.mdExtended 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 2: Extract raw design values

From the Stitch HTML and screenshot, extract:

Colors

Identify every distinct color. For each, determine:

  • Exact hex value (from Tailwind config in <head>, or infer from screenshot)
  • Semantic role: What does this color DO? (primary action, surface, text, border, error, success...)
  • Usage frequency: How dominant is it?

Aim for 8-12 semantic tokens, not 50 specific shades.

Typography

  • 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

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

Motion

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

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:

/* =============================================================
   Design Tokens — extracted from Stitch project: [Project Name]
   Generated by stitch-design-system skill
   ============================================================= */

/* ---- Light mode (default) ---- */
:root {
  /* Colors: Semantic roles, not visual names */
  --color-background:       [hex];  /* Page background */
  --color-surface:          [hex];  /* Card, panel backgrounds */
  --color-surface-elevated: [hex];  /* Tooltip, dropdown backgrounds */
  --color-primary:          [hex];  /* Primary CTA, key actions */
  --color-primary-hover:    [hex];  /* Primary at hover state */
  --color-primary-fg:       [hex];  /* Text/icon on primary bg */
  --color-secondary:        [hex];  /* Secondary actions, accents */
  --color-secondary-fg:     [hex];  /* Text/icon on secondary bg */
  --color-text:             [hex];  /* Body text */
  --color-text-muted:       [hex];  /* Secondary, supporting text */
  --color-text-disabled:    [hex];  /* Disabled element text */
  --color-border:           [hex];  /* Dividers, input borders */
  --color-border-focus:     [hex];  /* Focus ring color */
  --color-error:            [hex];  /* Error states */
  --color-success:          [hex];  /* Success states */
  --color-warning:          [hex];  /* Warning states */

  /* 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

IssueFix
Can't determine dark mode hex valuesUse the light-mode hue, desaturate slightly, and increase lightness by 30-40%
Font not loadingAdd Google Fonts @import to design-tokens.css
Tailwind v3 vs v4 confusionCheck package.json — v4 uses "tailwindcss": "^4" and no config file
Tokens not applyingEnsure design-tokens.css is imported BEFORE component CSS

Integration with other skills

  • Run this skill before stitch-nextjs-components or 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

Source

git clone https://github.com/gabelul/stitch-kit/blob/main/skills/stitch-design-system/SKILL.mdView on GitHub

Overview

Converts Stitch designs into production-ready code artifacts. It outputs CSS custom properties with dark mode tokens, a Tailwind v4 @theme block, and a richer DESIGN.md, forming the foundation for all subsequent component generation. Run this before framework conversion skills to ensure design consistency.

How This Skill Works

The skill first retrieves the Stitch design by discovering the MCP prefix, fetching screens, downloading HTML, and reviewing a visual reference. It then extracts raw design values for colors, typography, spacing, and motion, producing three outputs: design-tokens.css, tailwind-theme.css, and DESIGN.md. These artifacts are intended to be imported into your codebase and used to drive framework-specific components.

When to Use It

  • 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
  • Preparing tokens before generating framework-specific components such as stitch-nextjs-components or stitch-svelte-components

Quick Start

  1. Step 1: Retrieve the Stitch design: discover namespaces, fetch screens, and download HTML using Stitch tools
  2. Step 2: Extract values and generate artifacts: colors, typography, spacing, motion; create design-tokens.css, tailwind-theme.css, DESIGN.md
  3. Step 3: Integrate outputs into codebase: import design-tokens.css in global CSS, paste tailwind-theme.css into globals.css, review DESIGN.md for updates

Best Practices

  • Keep token sets to 8-12 semantic colors with exact hex values and semantic roles
  • Define typography tokens including font families, type scale, weights, and line heights
  • Capture base spacing, radii, shadows, and motion timings with a consistent naming scheme
  • Provide light and dark mode tokens in design-tokens.css and align with Tailwind @theme
  • Validate tokens against the DESIGN.md and ensure tokens are ready for component generation

Example Use Cases

  • New SaaS dashboard designed from Stitch provides design-tokens.css and tailwind-theme.css for rapid integration
  • Dark mode tokens updated to support night theme across a marketing site
  • Tailwind v4 theme block created for an e commerce storefront
  • Semantic color tokens established for error and success states across forms
  • DESIGN.md enriched with typography, motion, and animation tokens used by components

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗