Skip to content

fix: site-tokens - Write line heights and font weights as loose semantic roles #4039

Open

Description

@ZaredRogers

Found in scaffold end-to-end test run 2 (10 Nov 2026, step 3d, finding P2).

Problem

write-token-export.ts writes:

  • one line height per font size: Line-Heights/<size name>, with code syntax --wp--custom--line-height--100 … 900;
  • one weight per element: Weights/body, h1 … h4, button, link, nav, input, with code syntax --wp--custom--font-weight--h1 and so on.

The TSP Figma file has the same shape, with code syntax that isn't WordPress (--line-heights/headings/h2). These are element-specific tokens, and theme.json can't reuse them across blocks. On TSP, every element weight came out as 400, so the nine weight tokens hold one value.

Decision (Zared, 10 Nov)

  • Line heights have loose semantic names used in many places: snug, heading, body and so on. Never per element (H1, H2) or per font size.
  • Font weights have loose semantic names too. Use the block theme scaffold's set: thin, extra-light, light, regular, medium, semi-bold, bold, extra-bold, black (100 to 900).

Fix

  • Group the measured line heights into the scaffold's roles (snug, heading, button, body), with code syntax --wp--custom--line-height--<role>. Report the measured value behind each role, and add a role only with the reviewer's approval.
  • Write only the weights the live site uses, under the scaffold's names (--wp--custom--font-weight--regular for 400), and record which elements use each one in the report.
  • figma-to-block-theme: map these to settings.custom.lineHeight and settings.custom.fontWeight, the scaffold's keys.

Done when

On the TSP crawl, the export has line heights snug, heading, button and body (or the subset in use), and weights under the scaffold's names, with no per-element or per-size tokens.

Agent notes
  • skills/site-to-design-tokens/scripts/write-token-export.ts (about lines 185 to 205) and propose-tokens.ts. Document it in references/target-structure.md.
  • The TSP Figma file (dsDojfcCaLQSwLZaYqM0qu) needs the same rename. That's a separate Figma change.
  • The run 2 test theme tsp-scaffold-test-2 got the per-size and per-element values in step 3b. Remove them after this fix.
  • Findings log: ~/Studio/the-safari-partners/docs/scaffold-test-2026-11-findings.md, run 2 step 3d.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

Medium

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions