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

> Extract Tailwind design tokens from Stitch HTML to style-guide.json with this simple two-step process. Automatically detect configurations for colors, spacing, and typography.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-16

---

**Stitch skills automatically detect Tailwind configurations in extracted HTML pages and export color, spacing, and typography tokens to [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-static-html/scripts/extract_inline_html.ts) performs three critical operations:

- Detects the presence of [`tailwind.config.js`](https://github.com/google-labs-code/stitch-skills/blob/main/tailwind.config.js) or [`tailwind.config.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/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:

```bash
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`](https://github.com/google-labs-code/stitch-skills/blob/main/.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`](https://github.com/google-labs-code/stitch-skills/blob/main/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:

```bash
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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/style-guide.json), verify the output contains expected values:

```bash
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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/SKILL.md), this skill requires [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/extract_inline_html.ts) script uses `autoDetectTailwind` to scan the project directory for [`tailwind.config.js`](https://github.com/google-labs-code/stitch-skills/blob/main/tailwind.config.js) or [`tailwind.config.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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.