docs(design-system-docs): rewrite typography for EDS 2.0#4866
Conversation
Replace EDS 1.0 named text styles with the modular type scale, density and line-height model. Adds principles, baseline-grid alignment, the Element/Selectable/Container/Page categorisation, and a token reference. Embeds the Storybook UIText and LongFormText stories as live demos. Closes #4861
Typography in Figma is a single component driven by variable modes on the instance, not per-layer text styles or frame-level modes. Mirrors how the matching CSS variables resolve in code.
Cascade only applies while modes remain at default; explicit mode overrides on an instance break the inheritance.
Renders the modular scale at every step in both Inter and Equinor inline, using rem values from spacious density. Replaces the static 'Inter scale' and 'Equinor scale' Figma exports — the specimen stays accurate to the scale automatically and shows both typefaces together so the x-height adjustment is visible.
Adds a px column for both Inter and Equinor so readers can see the rendered size alongside the sample, matching the original Figma layout.
eddiman
requested review from
Chibuzor-Nwemambu,
millus,
pomfrida and
vnys
as code owners
|
@claude review |
|
Claude finished @pomfrida's task in 4m 25s —— View job Review —
|
| Doc claims | Actual token |
|---|---|
--eds-font-weight-lighter / -normal / -bolder |
The --eds-font-weight-* namespace doesn't exist. Font-weight tokens live under typography: globally --eds-typography-font-weight (set by [data-font-weight="lighter|normal|bolder"]) and per family/size: --eds-typography-{family}-{size}-font-weight-{lighter|normal|bolder} (e.g. --eds-typography-ui-body-lg-font-weight-normal). See packages/eds-core-react/src/components/next/Foundation/elements.css:37-42. |
--eds-typography-letter-spacing-tight / -normal / -loose |
The token name uses tracking, not letter-spacing — --eds-typography-tracking-tight|normal|wide|loose. The CSS property the token resolves to is letter-spacing (packages/eds-tokens/src/css/typography.css:30), but the token identifier is tracking. The doc also drops the wide variant — there are four modes, not three. See packages/eds-tokens/src/css/index-variables.css:97-101 and the trackingConfig array in createSpacingAndTypographyVariables.ts:809-814. |
Both rows are user-facing token names — anyone copy-pasting from this table will hit unresolved CSS variables. Fix this →
Should fix
Specimen block fallback fonts (lines 50–106). The inline styles use fontFamily: 'Equinor, serif' for the heading column. Equinor is a sans-serif typeface, so if the font fails to load (deploy preview without eds-uprights-vf.css, browser blocking the CDN, etc.) the fallback will switch to a serif that looks dramatically wrong. Change to Equinor, sans-serif to keep the optical weight in the same family.
Storybook demos only show 7 of 10 steps. Typography.stories.tsx:40 defines sizes = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'], so the embedded iframes don't show 4xl, 5xl or 6xl — but the prose and the table on this page document the full xs–6xl scale. Either extend the array in the story to cover the full scale, or add a one-line note under the iframe explaining the demo is truncated. Fix this →
The x-height explanation reads backwards (line 35). "Equinor is rendered slightly larger at every step than Inter — its taller x-height needs a small upward bump" — Inter has a notably tall x-height; display/heading typefaces like Equinor typically have a shorter x-height, which is why they need to be sized up to match Inter's optical size. As written, the cause and effect are reversed.
Commit Mono dangles. Listed in the typefaces table on line 33 but never appears in the Loading section, the scale, the tokens, or anywhere else. Either describe how/when it's loaded (it isn't part of eds-uprights-vf.css), or note explicitly that monospace is reserved for code blocks and the family stack is up to the consumer.
Nits
- Storybook story panel still exposes
relaxed(Typography.stories.tsx:20) even though the doc deliberately hides it. A reader who toggles the radio in the iframe sees undefined values. Either droprelaxedfromargTypes.optionsor leave adisabled-style note in the story description (theargTypes.density.descriptionalready calls it a POC, which helps — but the option is still selectable). - Tokens table uses
·HTML entities to inline alternatives within a single cell (lines 240, 243). It works, but since the rest of the file uses pure Markdown tables, splitting these into separate rows or a sub-list would be more consistent and easier to scan. - "View in Storybook" links (lines 146, 184) — worth a click on the deploy preview to make sure the path-format URL still resolves; Storybook's URL conventions sometimes change between major versions.
- Density example (line 159) could clarify that
data-densitycascades through the typography axes too — readers may wonder whether they need to also setdata-font-size,data-font-family, etc. on every element. (The text "Components within that ancestor then read the cascaded base" is correct but doesn't make thedata-*axis relationship explicit.)
Verified ✓
- Modular-scale multipliers and resulting pixel values (table, lines 125–136) — math checks out against
pow(2, n/5)rounded to 0.5 px increments. - Line-height formula and per-step values (lines 188–202) —
1.39 − (n/9)³ × 0.29and1.13 − (n/9)³ × 0.13reproduce the table. - Storybook story IDs (
eds-2-0-beta-foundation-typography--ui-text/--long-form-text) matchmeta.title+ story export names. - Density modes (
spaciousdefault,comfortable) match the build pipeline; hidingrelaxedis the right call given its POC status. text-box: trim-both ex alphabeticmatchespackages/eds-tokens/src/css/typography.css:36.- The
eds-uprights-vf.csswarning correctly identifies theequinor-font.css-only failure mode.
- Read the changed file
- Cross-check claims against the codebase (tokens, density modes, type scale)
- Verify embedded Storybook URLs and stories exist
- Check links and anchors
- Post review feedback
·docs/4861-typography-documentation
- Fix Tokens table: correct font-weight to namespaced form, rename letter-spacing to tracking, add header font-size and line-height rows - Reverse x-height explanation: Equinor has shorter x-height than Inter, not taller (verified from font OS/2 metrics: 0.480 vs 0.546) - Switch Equinor specimen fallback from serif to sans-serif - Extract repeated specimen label inline styles into .specimen-label - Add WCAG callout reserving xs for decoration - Convert :::info **Do** / :::danger **Don't** to bracketed-title syntax - Un-indent closing ::: markers so Docusaurus parses them - Drop deprecated frameborder attribute from Storybook iframes - Add note that iframe demos only show xs-3xl - Clarify density cascade reaches every typography axis - Remove Commit Mono until it is properly shipped with tokens
Replace the inline specimen grid (hardcoded fontSize values per row) with
a TypeSpecimen component that resolves fontSize from
--eds-typography-{ui-body,header}-{size}-font-size and reads back the
computed pixel value via getComputedStyle. The label and rendered text
now come from the same source — if the token scale changes, both update.
|
im looking into the lint errors |
Chibuzor-Nwemambu
left a comment
Chibuzor-Nwemambu
left a comment
There was a problem hiding this comment.
Fantastic Work! ✅
Somethings I noticed which aren't a blocker though:
- The px size labels in the specimen grid flash in blank on first render. Initialising with '…' instead of '' would avoid that.
- If the EDS token stylesheet isn't loaded, the size labels would show "NaNpx". A small isNaN check in formatPx would make it fall back gracefully.
Let's Go 🔥 🚚
typescript-eslint cannot resolve React types when linting files under apps/design-system-docs because tsconfig.eslint.json (matched first by **/*.tsx) doesn't include React in its project graph. The codebase already downgrades no-unsafe-return / -assignment / -argument to warn globally; extend the same treatment to no-unsafe-call and no-unsafe-member-access, scoped to the docs app, so CI doesn't fail on hooks usage in docs-only React components.
3 participants
Summary
Rewrites the Typography foundation page to match the EDS 2.0 system. The previous page documented EDS 1.0 named text styles (
H1bold,Body short,Ingress, etc.) which no longer exist — EDS 2.0 uses a modular type scale (xs–6xl) anchored atlgand shifted per density mode.The new page covers:
eds-uprights-vf.cssloading warning kept from the old pagespacious(default) andcomfortable;relaxedis hidden until tokens are finaliseddefaultvssquished, with full multiplier math behind a<details>--eds-typography-*referenceLive demos re-use the existing
Foundation/Typography.stories.tsxstories so the doc stays in sync with the code automatically.Closes #4861
Test plan
pnpm docu:build— clean (only pre-existing photography-page anchor warnings)pnpm docu:serve— typography page returns HTTP 200