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

Stitch Skills enforces design token consistency across converted pages by using a centralized 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, a file generated by the design-md skill located at 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) outputs to resources/style-guide.json, while React Native conversions use src/theme.ts and shadcn-ui projects utilize 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 to match the current 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 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:

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.

Step 2: Sync Tokens for React Components

Convert screens to React components while enforcing token consistency:

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

The skill reads DESIGN.md and produces 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:

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

Generated components import constants from src/design-tokens.ts, ensuring all UI elements respect the centralized design system.

Step 4: Validate in CI

Automate consistency checks using GitHub Actions:

# .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 file generated by 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, src/theme.ts, and 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 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 or src/theme.ts) contain tokens extracted from the current project specified in 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 as defined in plugins/stitch-build/skills/react-native/SKILL.md, while shadcn-ui projects use src/design-tokens.ts according to plugins/stitch-build/skills/shadcn-ui/resources/customization-guide.md. All skills read from the same 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 workflow ensures that any changes to the Stitch project are immediately reflected in DESIGN.md and propagated to all generated pages before deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}