how-to-guide

How to Extract Tailwind Design Tokens from Stitch HTML for style-guide.json

July 16, 2026 google-labs-code/stitch-skills ↗

Stitch skills automatically detect Tailwind configurations in extracted HTML pages and export color, spacing, and typography tokens to resources/style-guide.json through a two-step extraction process.

The google-labs-code/stitch-skills repository provides specialized skills for design system extraction. When working with Tailwind-based projects, you can transform raw HTML snapshots into structured design tokens that downstream build skills consume for component generation.

Two-Step Extraction Workflow

Extracting Tailwind tokens requires sequential execution of two distinct skills. The first creates a self-contained HTML artifact, and the second parses that artifact to generate the token file.

Step 1: Extract Static HTML

Run the extract-static-html skill to capture a complete page snapshot. This script inlines Tailwind CSS and detects the project's configuration through the autoDetectTailwind utility.

During extraction, the script located at plugins/stitch-design/skills/extract-static-html/scripts/extract_inline_html.ts performs three critical operations:

  • Detects the presence of tailwind.config.js or tailwind.config.ts
  • Inlines Tailwind utility classes into a <style> block
  • Injects a <style type="text/tailwindcss"> block when @apply directives are present

Execute the snapshot command:

npx tsx plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts \
  --url http://localhost:5173 \
  --output .stitch/home.html \
  --wait 2000

This produces .stitch/home.html, a self-contained file with all Tailwind classes resolved and ready for token analysis.

Step 2: Extract Design Tokens

Run the extract-design-md skill on the HTML file to parse the <head> section and extract the design system. According to plugins/stitch-design/skills/extract-design-md/SKILL.md, this skill reads the Tailwind configuration and maps theme.extend values to a standardized JSON structure.

Execute the extraction command:

npx tsx plugins/stitch-design/skills/extract-design-md/scripts/extract_design.ts \
  --html .stitch/home.html \
  --out resources/style-guide.json

The resulting resources/style-guide.json contains categorized tokens including:

  • colors — derived from theme.extend.colors or default Tailwind palette
  • spacing — margin and padding scales from theme.extend.spacing
  • fontFamily — typography stacks from theme.extend.fontFamily

Understanding the Token Extraction Process

The extraction logic bridges the gap between Tailwind's configuration-based tokens and Stitch's standardized resource format.

Tailwind Config Detection

When processing HTML, the skill searches for indicators of Tailwind usage in the document <head>. It locates the tailwind.config.* file relative to the project root and parses the JavaScript/TypeScript configuration to access the theme object.

The skill specifically handles:

  • Extended themes: Values inside theme.extend take precedence over defaults
  • Nested scales: Color palettes with semantic names (e.g., primary.500) preserve their hierarchy
  • Responsive breakpoints: Container and spacing tokens maintain their breakpoint relationships

Token Mapping

The extraction script transforms Tailwind's JavaScript configuration into a static JSON resource. This mapping occurs in plugins/stitch-design/skills/extract-design-md/scripts/extract_design.ts, where utility classes found in the HTML are correlated against the config values to determine which tokens are actually utilized in the design.

Reference documentation in plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md details specific extraction patterns for complex token types like gradients and shadows.

Verification and Downstream Consumption

After generating style-guide.json, verify the output contains expected values:

cat resources/style-guide.json | jq .

The React-components skill enforces token synchronization through a gate check. As documented in plugins/stitch-build/skills/react-components/SKILL.md, this skill requires resources/style-guide.json to be updated for the current project before proceeding to component generation. Stale or missing tokens will halt the build process until the extraction is re-run on current HTML.

Summary

  • Extract static HTML using the extract-static-html skill to inline Tailwind CSS and detect configurations via autoDetectTailwind in plugins/stitch-design/skills/extract-static-html/scripts/extract_inline_html.ts.
  • Generate tokens by running the extract-design-md skill, which writes theme.extend values (colors, spacing, fonts) to resources/style-guide.json.
  • Verify sync before building components, as downstream skills check for updated tokens before proceeding.
  • Source files involved include extraction scripts in plugins/stitch-design/skills/extract-static-html/scripts/ and token logic in plugins/stitch-design/skills/extract-design-md/.

Frequently Asked Questions

What file format does style-guide.json use?

The file uses standard JSON format with top-level keys for token categories (colors, spacing, fontFamily). Each key contains either flat key-value pairs for simple tokens or nested objects for scales like color palettes or spacing increments. You can inspect the structure using jq or any JSON viewer.

How does Stitch detect the Tailwind configuration?

The extract_inline_html.ts script uses autoDetectTailwind to scan the project directory for tailwind.config.js or tailwind.config.ts files. It then parses the configuration to access the theme and theme.extend objects, which define the custom design tokens beyond Tailwind's defaults.

Can I extract tokens from non-Tailwind projects?

Yes, the extract-design-md skill can parse standard CSS custom properties (variables) from the HTML <head> even without Tailwind. However, the automated mapping of semantic tokens (colors, spacing scales) works best with Tailwind's structured configuration format. For non-Tailwind projects, tokens may require manual curation in style-guide.json.

Why does the React-components skill require an updated style-guide.json?

As implemented in plugins/stitch-build/skills/react-components/SKILL.md, the skill performs a synchronization check (gate 2) to ensure generated components match the current design system. Stale tokens would produce components using outdated colors or spacing, breaking visual consistency. Re-running the extraction workflow ensures the component generation skills reference the current design tokens.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →