docs: add token code / output architecture ADR

[pomfrida]

Description

Adds ADR 0009 — the code / output architecture for the redefined token system (Tokens Studio export, build pipeline, CSS + TypeScript output shape). This is the sibling of ADR 0007 (Figma variable structure, #5161) and the umbrella over ADR 0008 (TS-token generation).

Key decisions recorded:

• Source of truth & sync: Tokens Studio is canonical; pull-based consumption via the studio CLI, release-triggered CI, export configs referenced by ID, hourly backup branch.
• Output targets: raw sets + CSS export (the single evaluation source) + DTCG export, with TypeScript generated by combining DTCG structure and CSS values (mechanics in ADR 0008).
• Naming transform: one deterministic path → --eds-* / nested camelCase mapping, incl. digit-leading tiers (2xl → twoXl); the heading/header discrepancy is flagged as a Studio-source fix.
• One resolved tree per density mode; per-colour-scheme splitting is data-driven.
• Font composition & body typography: mechanism decided (family/weight composed per role; body/* = ui × 1.5 as derived output in CSS + TS), implementation pending — the 1.5 ratio stays code-owned per the ADR 0007 ownership boundary.
• CSS specificity: published bundle wrapped in @layer eds-tokens with a shared @layer eds-tokens, eds-elements, eds-components; order statement. The legacy-unlayered-beats-layered collision risk is recorded as a consequence with a required collision check.

All claims about the generated output are verified against the tokens-studio-release branch.

Status is Proposed — moves to Accepted after design + engineering review per the issue's DoD.

Closes #5140

Follow-ups (separate issues, not in this PR)

• Implement font/body emission in generate-ts-tokens.mjs + CSS output
• Implement the @layer bundle step and wire src/tokens/* into the package exports map

[pomfrida]

@claude review

[claude]

Claude finished @pomfrida's task in 2m 20s —— View job

---

Review — ADR 0009: Token code / output architecture

• Read the ADR
• Cross-check sibling ADRs (0007, 0008) for consistency
• Verify factual claims against the repo / workflows
• Check ADR format & conventions
• Post review

This is a well-structured, unusually precise ADR — the options are genuinely weighed (each rejected option has a real technical reason, not a strawman), the ownership boundary is crisp, and the consequences are honest about the sharp edges (!important inversion, legacy-unlayered collision). Format matches 0000-template.md exactly. Below are verification results, one substantive inconsistency worth reconciling, and a few nits.

---

✅ Claims verified against the repo

I checked the factual assertions against the workflow files on this branch:

Claim (ADR)	Verified
repository_dispatch type tokens-release triggers tokens_studio_release.yaml	✓ types: [tokens-release]
GitHub OIDC auth	✓ id-token: write
Export configs referenced by ID, never by name	✓ CSS 39d37416…, DTCG 019463d4…
studio tokens pull → raw sets; CSS → src/tokens/css; DTCG → src/tokens/dtcg; then TS gen	✓ steps present, incl. generate:ts-tokens
Loud failure + Slack alert	✓ act10ns/slack@v2 step
Hourly backup to orphan branch tokens-studio-backup	✓ cron: '23 * * * *', branch confirmed
Components side declares @layer eds-elements, eds-components;	✓ exact match in components/next/index.css:3
Density modes compact · comfortable · relaxed, base comfortable	✓ matches ADR-0007's canonical set
Specificity (0,1,0) for [data-color-scheme='dark'] vs :root	✓ correct

One thing I could not verify: the ADR states everything is "grounded in the actual generated output on the tokens-studio-release branch." This is a shallow checkout, so I couldn't fetch that branch's tree to confirm the src/tokens/{ts,css,dtcg} output shape directly. The pipeline that produces it is confirmed; the output claims I'm taking on trust.

---

⚠️ Inconsistency with ADR-0007 — heading vs header

This is the one thing I'd resolve before merge. The two ADRs contradict each other on the current state of the source:

• ADR-0009 (line 114): "The current export still carries font/family/heading where ADR-0007 unified the spelling to header; this is fixed in the Studio source, not papered over in the codegen." — and the PR body lists "Fix heading → header in the Tokens Studio source" as a pending follow-up.
• ADR-0007 (line 161): "The type domain uses header consistently … (An earlier heading spelling on the family token was unified to header at the source.)" — stated in the past tense, as already done.

So ADR-0007 asserts the source rename is complete, while ADR-0009 says the export still emits heading and the fix is outstanding. Both can't be true. Since 0009 is grounded in the actual current export, ADR-0007's parenthetical looks premature. Recommend aligning them — e.g. soften ADR-0007's line to "is being unified to header at the source (tracked in #5140 follow-up)", or note explicitly in 0009 that 0007 documents the target end-state. Fix this →

---

Nits (non-blocking)

• Diagram vs workflow paths. The Decision diagram (lines 99–102) shows src/tokens/…, but the release workflow writes with --out src/tokens/css relative to packages/eds-tokens, and the PR-body/consequences reference the full packages/eds-tokens/src/tokens/…. Worth one line clarifying the paths are relative to the eds-tokens package root, so a reader doesn't look for src/tokens at repo root.
• "generated by packages/eds-tokens/scripts/generate-ts-tokens.mjs" (line 109). The workflow invokes it via the generate:ts-tokens package script, not the file path directly. Fine as-is, but if that script name ever changes the ADR reference to the .mjs file stays valid while the CI wiring is a level of indirection away — minor.
• Line 133 "baseline since 2022". @layer shipped in all evergreen engines in 2022; "Baseline" (the formal web.dev status) for cascade layers is fine but the capitalised term has a specific meaning — reads fine either way, just flagging.
• Follow-ups accuracy. The PR body lists "wire src/tokens/* into the package exports map" as pending — good to see it's not claimed as done in the ADR. The ADR correctly scopes itself to architecture, not the exports wiring.

---

Overall: accurate, self-consistent internally, and honest about its risks. The only real action item is reconciling the heading/header state with ADR-0007. Everything else is polish.
· docs/adr-token-code-output-architecture