fix(eds-tokens): emit nested typography TS with inlined size extras (#4915)

* fix(eds-tokens): emit nested typography TS with inlined size extras

Closes #4901.

The per-axis TS files (font-weight-*, line-height-*, tracking-*) and
the per-size files (font-size-*) silently picked one cell of the
family × size matrix because Style Dictionary cannot represent runtime
mode switching. These files are now removed; the two font-family files
become the only TS surface.

Each size cell in font-family-{ui,header}.ts is now self-contained:
nested fontWeight/tracking/lineHeight objects (so consumers can derive
variant types via keyof) plus inlined iconSize/gapHorizontal/gapVertical
extras. Implementation:

- New splitLeafPrefixes option on typescriptNestedFormat splits
  hyphenated leaf segments (font-weight-lighter → fontWeight.lighter)
  before nesting. Affects TS output only; CSS variable names unchanged.
- Per-size builds still emit temporary TS files which a post-step
  parses for the three family-independent extras and splices into each
  size cell of both family files. The regex is line-anchored to avoid
  matching nested-axis closers and throws if a size cell can't be
  located.
- Smoke tests in src/__tests__/typography-shape.test.ts assert the
  emitted structure: every size cell has the expected nested keys,
  inlined extras are family-independent (ui matches header per size),
  and keyof narrows to the expected literal types.

* docs(eds-tokens): document the nested typography TS surface

- README.md: add a "Typography (non-CSS targets)" subsection describing
  direct matrix import via @equinor/eds-tokens/ts/typography/font-family-*,
  with a keyof example for variant types and a React Native note. Also
  fix pre-existing data-text-size → data-font-size typos in the data
  attribute examples.
- CLAUDE.md: expand the Typography output section to explain the
  nested shape, the splitLeafPrefixes mechanism, the build-time splice
  of family-independent size extras, and the build-order dependency on
  build/ts/typography/.
- instructions/typography.md: replace the previous TypeScript Tokens
  section (which documented importing the now-removed per-axis files)
  with Direct token import + Deriving variant types + React Native
  subsections, plus a "What's not exported" note explaining why other
  axis files don't ship as TS.

* refactor(eds-tokens): apply review feedback on typography build

Per Claude review on #4915:

- Replace the local sizeKeyToCamel map with a call to toCamelCase
  (re-exported from @equinor/eds-tokens-build) so the size-key →
  identifier conversion has a single source of truth.
- Derive the splice loop's family list from fontFamilyConfig instead
  of a hardcoded ['ui', 'header'] literal — adding a third family now
  automatically extends the splice.
- Add a smoke-test assertion that build/ts/typography/ contains only
  the two family files, catching cleanup-whitelist regressions.
- Document splitLeafPrefixes first-match-wins semantics on
  BuildNestedObjectOptions.

Emitted font-family-{ui,header}.ts files are byte-identical to before
the refactor — verified by diff against pre-refactor snapshots.

Author: eddiman

packages/eds-tokens-build/src/__tests__/typescriptNested.test.ts

@@ -123,6 +123,108 @@ describe('typescriptNested format', () => {
         },
       })
     })
+
+    describe('with splitLeafPrefixes', () => {
+      it('splits a matching hyphenated leaf into two nested segments', () => {
+        const tokens = [
+          mockToken(['font-family-size', 'xs', 'font-weight-lighter'], '300'),
+          mockToken(['font-family-size', 'xs', 'font-weight-normal'], '400'),
+          mockToken(['font-family-size', 'xs', 'font-weight-bolder'], '500'),
+        ] as TransformedToken[]
+
+        const result = buildNestedObject(tokens, {
+          splitLeafPrefixes: ['font-weight'],
+        })
+
+        expect(result).toEqual({
+          fontFamilySize: {
+            xs: {
+              fontWeight: {
+                lighter: '300',
+                normal: '400',
+                bolder: '500',
+              },
+            },
+          },
+        })
+      })
+
+      it('leaves leaves matching the prefix exactly (no suffix) alone', () => {
+        const tokens = [
+          mockToken(['font-family-size', 'xs', 'font-size'], '12'),
+        ] as TransformedToken[]
+
+        const result = buildNestedObject(tokens, {
+          splitLeafPrefixes: ['font-size'],
+        })
+
+        expect(result).toEqual({
+          fontFamilySize: {
+            xs: {
+              fontSize: '12',
+            },
+          },
+        })
+      })
+
+      it('handles multiple prefixes on different tokens', () => {
+        const tokens = [
+          mockToken(['size', 'xs', 'font-weight-bolder'], '500'),
+          mockToken(['size', 'xs', 'tracking-tight'], '-1'),
+          mockToken(['size', 'xs', 'line-height-default'], '16'),
+          mockToken(['size', 'xs', 'font-size'], '12'),
+        ] as TransformedToken[]
+
+        const result = buildNestedObject(tokens, {
+          splitLeafPrefixes: ['font-weight', 'tracking', 'line-height'],
+        })
+
+        expect(result).toEqual({
+          size: {
+            xs: {
+              fontWeight: { bolder: '500' },
+              tracking: { tight: '-1' },
+              lineHeight: { default: '16' },
+              fontSize: '12',
+            },
+          },
+        })
+      })
+
+      it('only splits the leaf segment, not intermediate segments', () => {
+        const tokens = [
+          mockToken(['font-weight-lighter', 'xs'], '300'),
+        ] as TransformedToken[]
+
+        const result = buildNestedObject(tokens, {
+          splitLeafPrefixes: ['font-weight'],
+        })
+
+        expect(result).toEqual({
+          fontWeightLighter: { xs: '300' },
+        })
+      })
+
+      it('is a no-op when no prefix matches', () => {
+        const tokens = [
+          mockToken(['size', 'xs', 'font-size'], '12'),
+          mockToken(['size', 'xs', 'icon-size'], '16'),
+        ] as TransformedToken[]
+
+        const result = buildNestedObject(tokens, {
+          splitLeafPrefixes: ['font-weight', 'tracking'],
+        })
+
+        expect(result).toEqual({
+          size: {
+            xs: {
+              fontSize: '12',
+              iconSize: '16',
+            },
+          },
+        })
+      })
+    })
   })
 
   describe('typescriptNestedFormat', () => {
@@ -286,6 +388,53 @@ describe('typescriptNested format', () => {
       // Pure numeric keys should still be quoted
       expect(result).toContain("'1': '#111111'")
     })
+
+    it('passes splitLeafPrefixes through to the nested builder', () => {
+      const tokens = [
+        mockToken(['font-family-size', 'xs', 'font-weight-lighter'], '300'),
+        mockToken(['font-family-size', 'xs', 'font-weight-normal'], '400'),
+        mockToken(['font-family-size', 'xs', 'tracking-tight'], '-1.15'),
+        mockToken(['font-family-size', 'xs', 'tracking-normal'], '0'),
+        mockToken(['font-family-size', 'xs', 'line-height-default'], '16'),
+        mockToken(['font-family-size', 'xs', 'font-size'], '12'),
+      ] as TransformedToken[]
+
+      const result = typescriptNestedFormat({
+        dictionary: { allTokens: tokens, tokens: {}, unfilteredTokens: {} },
+        options: {
+          rootName: 'typography',
+          splitLeafPrefixes: ['font-weight', 'tracking', 'line-height'],
+        },
+        file: { destination: 'test.ts' },
+        platform: {},
+      } as unknown as FormatFnArguments)
+
+      expect(result).toMatchInlineSnapshot(`
+        "/**
+         * Do not edit directly, this file was auto-generated.
+         */
+
+        export const typography = {
+          fontFamilySize: {
+            xs: {
+              fontWeight: {
+                lighter: 300,
+                normal: 400,
+              },
+              tracking: {
+                tight: -1.15,
+                normal: 0,
+              },
+              lineHeight: {
+                default: 16,
+              },
+              fontSize: 12,
+            },
+          },
+        } as const
+        "
+      `)
+    })
   })
 })
 

packages/eds-tokens-build/src/format/typescriptNested.ts

@@ -54,15 +54,61 @@ function formatKey(key: string): string {
 
 type NestedObject = { [key: string]: NestedObject | string }
 
+export type BuildNestedObjectOptions = {
+  /**
+   * Hyphenated prefixes (e.g. `'font-weight'`) that, when found at the start of a
+   * token-path leaf, are split into two segments. `font-weight-lighter` becomes
+   * `['font-weight', 'lighter']`, producing nested output `fontWeight: { lighter }`
+   * instead of flat `fontWeightLighter`.
+   *
+   * Useful when the source token JSON encodes axis variants as hyphenated leaf
+   * keys, and the consuming code wants the axis exposed as a nested object so
+   * variant names can be derived via `keyof`.
+   *
+   * If multiple prefixes could match a leaf (e.g. `'font-weight'` and
+   * `'font-weight-extra'`), array iteration order wins — first match applied.
+   */
+  splitLeafPrefixes?: readonly string[]
+}
+
+/**
+ * If the leaf of `path` starts with one of the given hyphenated prefixes, split
+ * it into `[prefix, rest]` and return a new path. Otherwise return `path`
+ * unchanged. The match requires the prefix be followed by `-` and at least one
+ * more character, so a bare leaf equal to the prefix (e.g. `font-size`) is left
+ * alone.
+ */
+function splitLeafForPrefixes(
+  path: string[],
+  prefixes: readonly string[],
+): string[] {
+  if (path.length === 0) return path
+  const leaf = path[path.length - 1]
+  for (const prefix of prefixes) {
+    const marker = `${prefix}-`
+    if (leaf.startsWith(marker) && leaf.length > marker.length) {
+      return [...path.slice(0, -1), prefix, leaf.slice(marker.length)]
+    }
+  }
+  return path
+}
+
 /**
  * Build a nested object from Style Dictionary tokens using their path arrays.
  * Each path segment is converted to camelCase.
  */
-export function buildNestedObject(tokens: TransformedToken[]): NestedObject {
+export function buildNestedObject(
+  tokens: TransformedToken[],
+  options?: BuildNestedObjectOptions,
+): NestedObject {
   const root: NestedObject = {}
+  const splitPrefixes = options?.splitLeafPrefixes
 
   for (const token of tokens) {
-    const segments = token.path.map(toCamelCase)
+    const rawPath = splitPrefixes
+      ? splitLeafForPrefixes(token.path, splitPrefixes)
+      : token.path
+    const segments = rawPath.map(toCamelCase)
     let current = root
 
     for (let i = 0; i < segments.length - 1; i++) {
@@ -115,13 +161,19 @@ function serializeObject(obj: NestedObject, indent = 2): string {
  *
  * Options:
  * - rootName: the export name (e.g. "color"). Defaults to "tokens".
+ * - splitLeafPrefixes: optional list of hyphenated prefixes (e.g. `'font-weight'`)
+ *   that should be split into a nested key when found at the start of a leaf path
+ *   segment. See `BuildNestedObjectOptions`.
  */
 export function typescriptNestedFormat({
   dictionary,
   options,
 }: FormatFnArguments): string {
   const rootName = (options?.rootName as string) ?? 'tokens'
-  const nested = buildNestedObject(dictionary.allTokens)
+  const splitLeafPrefixes = options?.splitLeafPrefixes as
+    | readonly string[]
+    | undefined
+  const nested = buildNestedObject(dictionary.allTokens, { splitLeafPrefixes })
 
   const header = `/**\n * Do not edit directly, this file was auto-generated.\n */\n`
 

packages/eds-tokens-build/src/main.ts

@@ -3,7 +3,7 @@ export { FONT_QUOTE_NAME } from './transform/fontQuote'
 export { PX_FORMATTED_NAME } from './transform/pxFormatted'
 export { PX_TO_REM_NAME } from './transform/pxToRem'
 export { _extend, tsBuildPath } from './utils'
-export { typescriptNestedFormat } from './format/typescriptNested'
+export { typescriptNestedFormat, toCamelCase } from './format/typescriptNested'
 export { createLightDarkTransform } from './transform/lightDark'
 export { PX_TRANSFORM_NAME } from './transform/pxTransform'
 export { fontQuote } from './transform/fontQuote'

packages/eds-tokens/CLAUDE.md

@@ -109,7 +109,43 @@ Five independent axes, each controlled by a `data-*` attribute:
 - **Line height** (`🅰️ Line height.*.json`) — `data-line-height`: `default`, `squished`
 - **Tracking** (`🅰️ Tracking.*.json`) — `data-tracking`: `tight`, `normal`, `wide`, `loose`
 
-Output: `build/css/typography/` (CSS) and `build/ts/typography/` (TypeScript nested objects)
+Output: `build/css/typography/` (CSS, all five axes) and `build/ts/typography/` (TypeScript: `font-family-{ui,header}.ts` only — two self-contained matrices, one per family).
+
+#### Why TS output is minimal
+
+Style Dictionary cannot represent runtime mode switching (which is what `data-*` cascade gives the CSS output). A TS file for `tracking-wide`, `font-weight-normal`, `line-height-default`, or any single `font-size-md` row would have to bake one cell from the size × family matrix and silently be wrong for any other combination. The build therefore emits TS only for the two family matrices.
+
+Each emitted file is shaped so consumers can read all five axes off a single size cell:
+
+```ts
+typography.fontFamilySize.md = {
+  fontSize: 14,
+  tracking:   { tight, normal, wide },
+  fontWeight: { lighter, normal, bolder },
+  lineHeight: { default, squished },
+  iconSize: 20,         // family-independent, spliced in at build time
+  gapHorizontal: 8.5,
+  gapVertical: 8.5,
+}
+```
+
+The nested axes are produced via `splitLeafPrefixes` on the `typescriptNestedFormat` (declared in `eds-tokens-build`). Source JSON encodes axis variants as hyphenated leaves (`font-weight-lighter`); the format splits those into two segments before nesting. CSS output is unaffected — its format uses the unsplit path for variable naming.
+
+Variant names are derivable directly from the data:
+
+```ts
+type Weight = keyof typeof ui.fontFamilySize.md.fontWeight // 'lighter' | 'normal' | 'bolder'
+```
+
+Figma remains the single source of truth — when a Figma sync regenerates the family files, consumer types track automatically.
+
+#### Build-time splicing of size extras
+
+`createSpacingAndTypographyVariables.ts` runs the per-size font-size builds with `rootName`/`tsBuildPath` set, which produces 10 temporary `font-size-{xs..6xl}.ts` files. A post-step parses each for `iconSize`/`gapHorizontal`/`gapVertical` (Style Dictionary emits them with already-resolved numeric values), injects the three values into the corresponding size cell of `font-family-{ui,header}.ts`, and deletes the temporary per-size files. The injection uses a line-anchored regex over content this same script just emitted, and throws if a size cell can't be located — failures are loud rather than silent. This pragmatic choice avoids the awkwardness of cross-source aggregation in Style Dictionary's resolved-value APIs.
+
+#### Build-order dependency
+
+The smoke test in `src/__tests__/typography-shape.test.ts` imports from `build/ts/typography/`, so those files must exist before `pnpm run test` runs. They are committed to git (build/ is gitignored but tracked), so a fresh `pnpm install && pnpm run build` works. But `pnpm run clean` (which is `rimraf build`) removes them — after a clean, you must run `pnpm run build:variables` before `test` will succeed.
 
 ### Elevation
 

packages/eds-tokens/README.md

@@ -114,6 +114,37 @@ const padding = comfortableSpacing.SPACING_INLINE_MD
 const borderRadius = comfortableSpacing.SPACING_BORDER_RADIUS_ROUNDED
 ```
 
+#### Typography (non-CSS targets)
+
+Typography is composed at runtime from five orthogonal axes. The CSS bundle resolves them via `data-*` attributes; non-CSS consumers (React Native, SSR, design tooling) import the family-keyed matrix directly:
+
+```typescript
+import { typography as ui } from '@equinor/eds-tokens/ts/typography/font-family-ui'
+import { typography as header } from '@equinor/eds-tokens/ts/typography/font-family-header'
+
+const md = ui.fontFamilySize.md
+
+const style = {
+  fontFamily: ui.typography.fontFamily,
+  fontSize: md.fontSize,
+  fontWeight: md.fontWeight.normal,
+  lineHeight: md.lineHeight.default,
+  letterSpacing: md.tracking.normal,
+}
+// { fontFamily: 'Inter', fontSize: 14, fontWeight: 400,
+//   lineHeight: 20, letterSpacing: 0 }
+```
+
+Each size cell exposes `fontSize`, nested `fontWeight` / `tracking` / `lineHeight` objects, and inlined `iconSize` / `gapHorizontal` / `gapVertical` extras for chip- and button-like layouts. Variant names can be derived with `keyof`:
+
+```typescript
+type Weight = keyof typeof ui.fontFamilySize.md.fontWeight // 'lighter' | 'normal' | 'bolder'
+```
+
+For React Native, coerce `fontWeight` to a string at the call site (`String(md.fontWeight.normal)`) so it slots into `<Text style>`.
+
+See [`instructions/typography.md`](./instructions/typography.md) for the full axis model.
+
 ### Importing variables as JSON
 
 The variables are available in two formats:
@@ -167,7 +198,7 @@ The typography system requires two font families: **Equinor** (headings) and **I
 
 ### Typography variables that adapt to data-attributes
   * Font family setup (UI and Header fonts)
-  * Font size data attributes (`[data-text-size='xs']`, `[data-text-size='sm']`, etc.)
+  * Font size data attributes (`[data-font-size='xs']`, `[data-font-size='sm']`, etc.)
   * Line height data attributes (`[data-line-height='default']`, `[data-line-height='squished']`)
   * Font weight data attributes (`[data-font-weight='lighter']`, `[data-font-weight='normal']`, `[data-font-weight='bolder']`)
   * Letter spacing data attributes (`[data-tracking='tight']`, `[data-tracking='normal']`, `[data-tracking='wide']`)
@@ -194,17 +225,17 @@ Set typography properties using data attributes:
 
 ```html
 <!-- UI font with medium size -->
-<p data-font-family="ui" data-text-size="md" data-line-height="default">
+<p data-font-family="ui" data-font-size="md" data-line-height="default">
   UI font text
 </p>
 
 <!-- Header font with extra large size and bolder weight -->
-<h1 data-font-family="header" data-text-size="xl" data-font-weight="bolder">
+<h1 data-font-family="header" data-font-size="xl" data-font-weight="bolder">
   Header font text
 </h1>
 
 <!-- Baseline grid alignment -->
-<p data-font-family="ui" data-text-size="md" data-baseline="grid">
+<p data-font-family="ui" data-font-size="md" data-baseline="grid">
   Aligned to 4px baseline grid
 </p>
 ```
@@ -269,7 +300,7 @@ The foundation CSS includes baseline grid alignment for consistent vertical rhyt
 * `data-baseline="center"` -- Centers text vertically while maintaining 4px grid alignment
 
 ```html
-<p data-font-family="ui" data-text-size="md" data-baseline="grid">
+<p data-font-family="ui" data-font-size="md" data-baseline="grid">
   Text aligned to baseline grid
 </p>
 ```