JoshuaShepherd Stitch token bridge
Wireframe colors are layout proof only. Production uses the tenant's semantic tokens. This skill produces the mapping table every page conversion then follows, so token extraction happens once — not per page.
Run once for the tenant in $ARGUMENTS (default: the current target repo).
Read first
.stitch/designs/design-system.html(or the embeddedtailwind.configin any screen's<head>).{{GLOBALS_CSS}}(defaultsrc/app/globals.css) andtailwind.config.ts.TENANT_MANIFEST.md→{{DESIGN_THEME}},{{DESIGN_CHARTER}}.- The reference design charter if present (
{{REFERENCE_REPO}}/docs/internal/design/DESIGN_CHARTER.md).
Wireframe palette (Stitch — never ship as-is)
| Role | Wireframe hex | Purpose |
|---|---|---|
| Page bg | #FFFFFF / #F7F7F7 |
Alternating sections |
| Text primary | #111111 |
Headlines, body |
| Text secondary | #666666 |
Meta, captions |
| Text tertiary | #999999 |
Labels |
| Border | #E0E0E0 / #CCCCCC |
Hairlines |
| Placeholder media | #E8E8E8 |
Image blocks |
| Primary button | #111111 fill, white text |
CTAs |
Semantic mapping (production)
Map every Stitch color usage to a semantic token (these names are stable across tenants;
the values live in globals.css per {{DESIGN_THEME}}):
| Stitch intent | Tailwind / CSS variable |
|---|---|
| Page background | bg-background |
| Alt section | bg-muted |
| Primary text | text-foreground |
| Secondary text | text-muted-foreground |
| Borders | border-border |
| Primary CTA | bg-primary text-primary-foreground |
| Cards | bg-card border-border |
| Placeholder media | bg-muted text-muted-foreground |
Typography bridge
| Wireframe | Tenant token |
|---|---|
| Serif headlines (Georgia) | font-heading — configure in layout.tsx via next/font |
| Sans body (system-ui) | font-sans |
| Mono routes/metadata | font-mono |
Tasks
- Extract the spacing rhythm from Stitch HTML (
py-16,max-w-1200, 8px grid) and document it indocs/internal/design/SPACING_NOTES.md(create if missing). - Update
globals.cssonly if the tenant tokens lack a required role (card, accent, popover). Ask before changing existing values. - Ensure
tailwind.config.tsfontFamilyextends to thenext/fontCSS variables. - Write the mapping to
docs/build/notes/stitch-token-bridge.md— this is the contractstitch-page-portreads.
Rules
- Do not add wireframe hex to
tailwind.configas named colors. - Do not re-extract tokens per page after this — every page uses this bridge.
- Dark mode: every token used in conversions must have a paired
.dark {}value.
Deliverables
docs/build/notes/stitch-token-bridge.md(the mapping table).- Minimal
globals.css/tailwind.config.tschanges (approved). pnpm typecheckpasses.
Acceptance criteria
- Mapping doc exists
- No raw
#111/#666patterns documented as allowed in component code - Light + dark tokens cover card, muted, primary, border
Stop here — do not convert pages.
Related skills
stitch-intake-audit · stitch-page-port · design-chain / color-audit
(token-violation audits) · tenant-migration-playbook