# How to Maintain Design Token Consistency Across Multiple Converted Pages in Stitch Skills

> Ensure design token consistency across converted Stitch Skills pages. Learn how a central DESIGN.md and validation gates maintain synchronization, preventing conversion errors.

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

---

**Stitch Skills enforces design token consistency across converted pages by using a centralized [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file as the single source of truth and implementing strict Phase 2 validation gates that abort conversion if token files are not synchronized with the current project.**

The `google-labs-code/stitch-skills` repository solves the challenge of maintaining design token consistency across multiple converted pages through an automated pipeline that extracts tokens from Stitch projects and validates them before code generation. This system ensures that colors, typography, spacing, and other UI primitives remain synchronized across React components, Vite dashboards, and native applications derived from the same design source.

## Architecture of the Token Consistency Pipeline

### Centralized Source of Truth

The pipeline centers on **[`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md)**, a file generated by the `design-md` skill located at [`plugins/stitch-utilities/skills/design-md/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/SKILL.md). This skill queries the Stitch MCP API using methods like `list_projects`, `get_screen`, and `get_project` to extract the `designTheme` object and parse HTML/CSS metadata. The resulting markdown file contains the complete canonical definition of all design tokens for a specific project.

### Framework-Specific Token Sync

Each conversion skill writes extracted tokens into framework-specific files before generating code. The `react-components` skill (defined 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)) outputs to [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/resources/style-guide.json), while React Native conversions use [`src/theme.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/theme.ts) and shadcn-ui projects utilize [`src/design-tokens.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/design-tokens.ts). These files serve as the exclusive source of token values for downstream templates.

### Phase 2 Validation Gates

Every conversion skill implements a **Phase 2 gate** that validates token freshness. The skill aborts with an error if the target token file contains values from a previous project or stale extraction. For example, the React components skill explicitly requires [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/resources/style-guide.json) to match the current [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) tokens before proceeding.

## Enforcing Consistency Through Validation

### Gate Checks and Fail-Fast Safety

The validation gates operate as mandatory checkpoints. Phase 2 completes only when the token file has been updated with tokens extracted from the current project. If the gate detects mismatched tokens—such as hex color values hard-coded instead of theme token references—the conversion fails immediately, preventing stale designs from propagating to generated code.

### Automated CI Enforcement

The repository includes [`.github/workflows/validate-skills.yml`](https://github.com/google-labs-code/stitch-skills/blob/main/.github/workflows/validate-skills.yml) to automate consistency checks in continuous integration. This workflow runs each skill in isolation and asserts that all token files are up-to-date before allowing pull request merges. Any discrepancy triggers a pipeline abort, blocking deployment of inconsistent designs.

## Practical Implementation Workflow

### Step 1: Generate the Token Definition

Extract the complete token set from your Stitch project using the `design-md` skill:

```bash
stitch skill run design-md \
  --project-id 1234567890 \
  --output DESIGN.md

```

This command contacts the MCP server, extracts the `designTheme` metadata, parses associated HTML/CSS, and writes the canonical token list to [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md).

### Step 2: Sync Tokens for React Components

Convert screens to React components while enforcing token consistency:

```bash
stitch skill run react-components \
  --design-md DESIGN.md \
  --project-id 1234567890

```

The skill reads [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) and produces [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/resources/style-guide.json). The Phase 2 gate fails the operation if the JSON file does not reflect the current token set.

### Step 3: Build a Vite Dashboard

Generate a React + Vite dashboard that references shared tokens:

```bash
stitch skill run react-vite-dashboard \
  --design-md DESIGN.md \
  --project-id 1234567890 \
  --output src/

```

Generated components import constants from [`src/design-tokens.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/design-tokens.ts), ensuring all UI elements respect the centralized design system.

### Step 4: Validate in CI

Automate consistency checks using GitHub Actions:

```yaml

# .github/workflows/validate-skills.yml

- name: Validate token consistency
  run: |
    stitch skill run react-components --design-md DESIGN.md --project-id $PROJECT_ID
    stitch skill run react-vite-dashboard --design-md DESIGN.md --project-id $PROJECT_ID

```

If any skill detects outdated token files, the job aborts and blocks the merge.

## Summary

- **Single Source of Truth**: The [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file generated by [`plugins/stitch-utilities/skills/design-md/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/SKILL.md) centralizes all design tokens extracted from the Stitch project metadata.
- **Framework-Specific Sync**: Token files like [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/resources/style-guide.json), [`src/theme.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/theme.ts), and [`src/design-tokens.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/design-tokens.ts) serve as the exclusive input for code generation templates.
- **Fail-Fast Validation**: Phase 2 gates in each skill enforce that token files match the current project state, aborting conversions that would introduce inconsistencies.
- **Automated CI Checks**: The [`validate-skills.yml`](https://github.com/google-labs-code/stitch-skills/blob/main/validate-skills.yml) workflow prevents merging code with stale design tokens.

## Frequently Asked Questions

### What happens if I convert multiple pages without updating the DESIGN.md file?

The conversion will fail during Phase 2 validation. Each skill checks that its output token files (such as [`resources/style-guide.json`](https://github.com/google-labs-code/stitch-skills/blob/main/resources/style-guide.json) or [`src/theme.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/theme.ts)) contain tokens extracted from the current project specified in [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md). If the tokens match a previous project version, the skill aborts with an error.

### Can I use hard-coded color values instead of design tokens?

No. The validation pipeline explicitly prohibits hard-coded hex values. Templates must use token variables like `{{color-primary}}` and `{{spacing-md}}` referencing the synchronized token files. The CI workflow flags any hard-coded values as failures.

### How does the system handle different frameworks like React Native and shadcn-ui?

Each framework-specific skill outputs tokens to a standard location. React Native uses [`src/theme.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/theme.ts) as defined in [`plugins/stitch-build/skills/react-native/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-native/SKILL.md), while shadcn-ui projects use [`src/design-tokens.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/src/design-tokens.ts) according to [`plugins/stitch-build/skills/shadcn-ui/resources/customization-guide.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/shadcn-ui/resources/customization-guide.md). All skills read from the same [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) source.

### Does the pipeline support continuous synchronization with design changes?

Yes. You can configure the skill pipeline to run on every commit or via CI steps. The [`validate-skills.yml`](https://github.com/google-labs-code/stitch-skills/blob/main/validate-skills.yml) workflow ensures that any changes to the Stitch project are immediately reflected in [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) and propagated to all generated pages before deployment.