📚 Update token documentation

[emirgens]

Description

Update and extend the token documentation to reflect all the redefined-token changes. The designer interviews made "documentation of intent" the #1 ask: abstract t-shirt sizes are only acceptable alongside a style guide with contextual examples showing when to use each — ideally in Storybook (the source of truth).

Scope

• Disabled-state (alpha-channel) approach + rationale.
• Updated colour values; the "static only, don't mix" story and its rationale.
• Density rename (compact / comfortable) rationale.
• Naming updates; required-vs-nice-to-have clarity.
• Text-trim removal rationale.
• Extended typography usage docs with contextual examples in Storybook.
• Must be usable by AI agents (and tested by one).

Definition of Done

• Documentation updated for the disabled-state approach
• Updated colour token values reflected
• Density rename documented
• Naming updates included
• Typography usage docs extended with contextual examples (Storybook)
• Published and shared with the team
• Tested by an AI agent

[eddiman]

Rationale: why the trim-based baseline grid & text-trim were dropped

Capturing this for the "text-trim removal rationale" DoD item — and the closely-related baseline-grid removal, since they're the same mechanism. The reasoning currently lives mostly in the 23 Jun token decision notes and designer interviews; consolidating here so the docs can cite it. (design-system-internal/docs/decisions.md has been updated to stop describing the removed approach as current.)

What existed, and why

A 4px baseline grid was a foundational EDS 2.0 principle — mandated in ADR 0004 (spacing) and ADR 0005 (typography) — to give type and spacing one shared vertical rhythm (print-typesetting heritage). It was implemented via a Figma typography component using cap-size / vertical trim + padding to snap each text block to a 4px multiple, and in code via text-box: trim-both ex alphabetic behind an @supports progressive enhancement (ADR 0005). text-trim was the mechanism that made the baseline grid possible — so dropping one drops the other.

Why it was dropped (23 Jun 2026 token decision)

• Not worth the cost. The interconnected system bought "visual perfection" (4px snapping, text-box trimming, icon/text-size coupling), but no clear end-user advantage was identified to justify the complexity for maintainers or consumers.
• The typography component was the core designer pain point (interviews): hard to nest, styles hard to copy, and it doesn't translate cleanly to code (Figma negative margins vs. CSS) — causing headaches and shipping delays. It isn't even used in the 2.0 components.
• It produced inconsistency, not consistency — 3 designers applied typography 3+ different ways.
• Baking trim into token values makes line-height dishonest — a "16px" token that renders ~10px tall misleads designers.
• It blocked unification — removing trim lets web and mobile share one typography set (Align mobile on the unified typography #5123).

What remains

• Baseline alignment survives at the component/CSS layer: multiline prose sits on the baseline of its grid-snapped box; single-line UI labels are centred (Typography system – CSS-first, no typography component #4655, two-axis model).
• Optical text-box trimming may return later as a component-layer progressive enhancement that never touches token values (CSS text-box-trim is shipping). Watch for the short-term loss of vertical optical centering in buttons/inputs during the repad pass (🧩 Component migration (colour, then spacing & typography) #5119).

Sources

• ADR 0004 (spacing), ADR 0005 (typography) — where the 4px baseline grid was mandated.
• ADR 0006 (token variable architecture) — records text-trim removed.
• Discussion equinor/design-system-internal#215 (Figma Typography Component — first flagged as not optimal).
• Issues: Typography system – CSS-first, no typography component #4655 (CSS-first, no typography component), Re-define Typography, Spacing & Corner Radius tokens #5107 (typography redefinition — trim removed), 🧩 Component migration (colour, then spacing & typography) #5119 (component repad), Align mobile on the unified typography #5123 (mobile alignment), Create Opinionated Typography System #4045 (original opinionated typography system).
• Internal: 23 Jun 2026 token decision meeting; 23 Jun designer interviews (Tristan & Emilie); 2 Jul critical review.