Google Stitch design system: diagnose drift and verify handoff

Google describes DESIGN.md as a portable way to import and export design rules. It can hold shared decisions about color roles, typography, spacing, layout principles, component treatment, and visual constraints. That portability matters: the rules can travel between projects and platforms instead of living only in one conversation.

The file has a narrower job. It states rules. It doesn't prove that every generated screen followed them, that a prompt didn't override them, or that exported code preserved them. Nor does it certify task completeness, accessibility, responsive behavior, generated-code quality, or production readiness. Those need separate checks.

Stitch changes quickly, and search results mix product documentation, tutorials, and user reports. Label each workflow claim by evidence class. This keeps a confident tutorial or isolated failure report from becoming an accidental product contract.

For any capability that matters to the handoff, use current first-party documentation to establish availability and your own recorded observations to establish behavior. Keep third-party instructions provisional until you've reproduced them. Community reports are test ideas, not forecasts.

Consistency gets expensive when several artifacts look authoritative at once. A reference site suggests one type scale, DESIGN.md names another, a generated screen introduces a third, and someone manually corrects the exported code. Without a precedence record, the latest visible result tends to win even when it shouldn't.

For each unresolved conflict, record the competing values, the owning layer, the person who decides, and the evidence they need. Don't settle it by copying whichever value appeared in the newest generation.

Before asking Stitch to generate more screens, write down the decisions that must stay stable. Use observable language. "Keep it cohesive" isn't testable. "Use the same primary navigation structure on the account, billing, and analytics screens" is.

• Navigation: structure, placement, selected state, collapse behavior, and permitted variations.
• Icons: source style, stroke or fill treatment, size rules, and where text labels are required.
• Color mode: allowed modes, the default mode, semantic roles, and whether a screen may switch independently.
• Typography: family by role, available weights, scale, line-height intent, and treatment of data or code.
• Spacing and layout: container widths, gutters, section rhythm, grid behavior, and density.
• Components: shared button, input, card, table, feedback, and focus treatments.
• Exceptions: the exact screen, state, reason, approver, and limit of each deviation.

Don't check only the most polished screen. Choose a representative set that includes the main shell, a dense data screen, a form, a destructive or error state, and any screen with an approved exception. If mobile or dark mode is in scope, include those states explicitly.

When two screens diverge, find the first point where their evidence differs. Regenerating every screen immediately can hide the cause and introduce fresh changes.

1. 1

   Check whether the governing rule is complete

   Find the relevant DESIGN.md rule. If it only says "use consistent navigation," it doesn't define structure, states, or exceptions. Revise the rule at its owning layer before correcting screens.

2. 2

   Compare the prompts and accepted suggestions

   Record the original prompt, follow-up instructions, and any automatic or manual suggestions. A screen-specific instruction may have overridden the shared rule. Remove or narrow that override, then retry only the affected case.

3. 3

   Check for an approved exception

   A legitimate difference isn't drift when its screen, state, reason, and scope were approved. If the exception is undocumented, pause and get an ownership decision instead of normalizing it after the fact.

4. 4

   Locate the first divergent artifact

   Compare representative Stitch screens before you inspect downstream code. If the screens agree but the export differs, route the finding to the export or implementation boundary. If the screens already disagree, keep the fix upstream.

5. 5

   Change one owner-controlled variable

   Apply one narrow rule change, such as the default color mode or navigation selection treatment. Don't bundle typography, spacing, and component revisions into the same test.

6. 6

   Assign a disposition

   Pass when the intended change appears where expected with no material unrelated drift. Revise when the governing rule or prompt is incomplete. Block when ownership, evidence, or downstream parity remains unresolved.

A controlled change tests whether a declared rule reaches the places it should. It's narrower than a general visual review. Pick one rule with an observable result, name the screens and export surface in scope, then capture both the intended and unintended effects.

Controlled change

Project:
Observed date:
Reviewer:

Governing layer:
Rule identifier:
Current rule:
Proposed rule:
Reason for change:
Owner and approver:

Representative screens:
- Screen / state:
  Expected change:
  Actual observation:
  Evidence reference:
- Screen / state:
  Expected change:
  Actual observation:
  Evidence reference:

Approved exceptions:
- Screen / state:
  Exception and reason:
  Expected to remain unchanged: yes / no

Exported artifact:
Artifact and version:
Expected change:
Actual observation:
Evidence reference:

Unrelated drift:
- Navigation:
- Icons:
- Color mode:
- Typography:
- Spacing and layout:
- Component treatment:

Unresolved conflicts:
Owner:
Next evidence required:

Disposition: pass / revise / block
Disposition reason:

"No unrelated drift observed" is valid only for the named screens and artifact. It doesn't mean the entire project is consistent. Where your workflow permits, attach references to screenshots, screen versions, prompt text, DESIGN.md revisions, and exported commits or archives.

This intake record shows how to bring a bounded source into the process without inventing Stitch results. Ambient Sage is a free, published Identity Forge kit. Its documented typography uses Plus Jakarta Sans for body and heading roles at weights 400, 500, 600, and 700, plus JetBrains Mono for the mono role at weights 400, 500, and 700. The published scale is compact-product.

Artifact intake: Ambient Sage

Source state
- Public kit page: documented
- Kit access: free and published
- Typography roles: documented
- Body and heading family: Plus Jakarta Sans
- Body and heading weights: 400, 500, 600, 700
- Mono family: JetBrains Mono
- Mono weights: 400, 500, 700
- Typography scale: compact-product
- DESIGN.md: available
- Semantic light and dark tokens: available
- Delivery formats: shadcn, Tailwind, CSS, and DTCG

Stitch evidence state
- DESIGN.md imported into Stitch: not tested
- Import warnings or transformations: not tested
- Generated-screen adherence: not tested
- Navigation consistency: not tested
- Icon consistency: not tested
- Light and dark mode behavior: not tested
- Typography and spacing parity: not tested
- Exported-artifact parity: not tested
- Controlled-change result: not tested

Handoff disposition
- Status: block pending evidence
- Reason: the source artifact is documented, but no Stitch-specific behavior or source-to-export parity has been observed
- Next action: import through the currently documented Stitch workflow, capture any transformation, then run one controlled change across representative screens and the chosen export

Hand over the governing DESIGN.md, machine-readable tokens or implementation artifacts, exception register, controlled-change record, and exported code together. Give each item a version or stable evidence reference. The developer should be able to trace a visible value to a semantic role or written rule and see which differences were approved.

• Name the DESIGN.md revision and token artifact used for generation.
• List representative screens and their recorded states.
• Include exact approved exceptions and unresolved conflicts.
• Record the export method and resulting artifact version.
• Separate verified parity from areas that weren't tested.
• Route downstream corrections back to the owning rule when they represent shared design decisions.

If a developer changes a shared color, spacing value, or component treatment only in exported code, treat it as downstream drift until the governing source accepts the change. If it's an implementation detail with no design-system consequence, keep it in code and explain why it doesn't need to travel upstream.

Pass the design-system handoff when the governing rule and owner are clear, representative screens show the expected result, approved exceptions stay bounded, the exported artifact preserves the checked change, and no material unrelated drift appears in scope.

Choose revise when the evidence points to an incomplete DESIGN.md rule, a broad prompt override, or a poorly defined exception that the current owner can correct. Choose block when sources conflict without an owner, Stitch-specific behavior hasn't been observed, the exported artifact breaks a governing rule, or the evidence record is too weak to reproduce the decision.

For a new project, fill in the four-layer authority record before generating another screen. For an existing project, pick one visible inconsistency, route it to its owning layer, and run the controlled-change worksheet before you accept or regenerate the rest.

• Stitch's DESIGN.md format is now open-source so you can use it across platforms: Google documents DESIGN.md as a portable format for importing and exporting design rules between projects and platforms.
• Introducing "vibe design" with Stitch: Google describes the current Stitch workflow as combining an AI-native canvas, a design agent, DESIGN.md support, iteration, and developer-delivery surfaces.
• From idea to app: Introducing Stitch, a new way to design UIs: Google's launch article documents generation from text or images, interactive refinement, transfer to Figma, and frontend-code export.
• Design system or design guideline on Stitch project: A community thread reports inconsistent icons, navigation, and color mode across generated screens. A Google-tagged response recommends more explicit prompts and protecting selected elements.
• How to Use Google Stitch to Build a Website Design System in Minutes: This third-party tutorial describes URL extraction, multi-page prototype generation, iteration, and export, but its claims aren't a first-party product contract.
• Ambient Sage Design Kit: The public Ambient Sage kit provides a source-bounded design example with DESIGN.md, machine-readable delivery artifacts, documented typography roles, and a compact product-oriented visual system.
• AI UI review checklist: test generated interfaces before you ship: Identity Forge's published review checklist separates design-system conformance from broader readiness and uses representative states, controlled changes, evidence records, and explicit dispositions.