@primitiv-ui/tokens 0.1.28 → 0.1.30

package/src/dark-mode-content.test.ts

@@ -24,6 +24,13 @@ function intentColor(mode: Mode, token: string): string {
   return value.startsWith('{') ? resolveRef(mode, value) : value
 }
 
+// These two are for the properties only this file can see — a background that
+// fails to track the theme, a state ramp running the wrong way, a pair that must
+// stay consistent ACROSS modes. Every accessibility *floor* moved to
+// `crates/harmoni-core/tests/intent_roles.rs`, where it is measured with the
+// engine's own contrast maths against the step the engine derives, so a role
+// cannot pass here and be wrong there.
+
 /** WCAG relative luminance (sRGB, 0-1). */
 function luminance(hex: string): number {
   const channel = (value: number) => {
@@ -52,15 +59,110 @@ function contrastRatio(a: string, b: string): number {
 // Dark ramp — not re-swapping the index a second time. Several tokens were
 // swapped a second time, cancelling the intended flip and landing both
 // modes on the same (or a same-toned) colour.
-describe.each(['content/primary', 'content/secondary'] as const)('%s', (token) => {
+// `content/muted` and `action/link/foreground/default` were added after a
+// contrast audit (docs/interface-audit.md, 2026-08-15 `better-colors`) found
+// both failing in dark mode while passing in light — 4.20:1 and 3.78:1 against
+// `surface/default`, missing 4.5:1. Neither was covered here, which is why the
+// guard above did not catch them.
+//
+// CORRECTION (2026-08-17): an earlier version of this comment claimed the link's
+// hover and active steps were "already correctly theme-inverted (dark 500 → 300 →
+// 200 lighter)". They were not — in the DARK ramp a higher step is lighter, so
+// 500 → 300 → 200 descends toward black and measured 5.95:1 → 1.74:1 → 1.33:1.
+// The whole dark state set was broken, not just `default`, and fixing `default`
+// alone made the jump to a near-black hover more obvious rather than less.
+//
+// The lesson is in the `action/link/foreground` describe block at the end of this
+// file: a per-token contrast check cannot see a state ramp running the wrong way,
+// because it only ever measures the resting value.
+describe.each([
+  'content/primary',
+  'content/secondary',
+  'content/muted',
+  'action/link/foreground/default',
+] as const)('%s', (token) => {
   it('resolves to a different colour in light vs dark mode', () => {
     expect(intentColor('light', token)).not.toBe(intentColor('dark', token))
   })
 
-  it('meets WCAG AA (4.5:1) against surface/default in both modes', () => {
+})
+
+// The neutral alpha ramp (Path A): the mode's veil colour — the neutral ramp's
+// 900 end (soft-black in light, soft-white in dark) — held constant across all
+// ten steps while only the alpha byte climbs. Guards both the anchor (the rgb
+// part must be the veil, so the ramp inverts with the theme) and the curve
+// (strictly increasing opacity).
+describe('color/neutral-alpha ramp', () => {
+  const steps = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900'] as const
+
+  it.each(['light', 'dark'] as const)("%s mode anchors every step on the mode's veil colour", (mode) => {
+    const veil = resolveRef(mode, '{color.neutral.900}')
+    for (const step of steps) {
+      expect(resolveRef(mode, `{color.neutral-alpha.${step}}`).slice(0, 7)).toBe(veil)
+    }
+  })
+
+  it.each(['light', 'dark'] as const)('%s mode climbs a strictly increasing alpha curve', (mode) => {
+    const alphas = steps.map((step) => parseInt(resolveRef(mode, `{color.neutral-alpha.${step}}`).slice(7, 9), 16))
+    for (let i = 1; i < alphas.length; i++) {
+      expect(alphas[i]).toBeGreaterThan(alphas[i - 1])
+    }
+  })
+
+  // The inverse companion: every step is the OTHER theme's neutral-alpha step,
+  // so each mode carries the opposite veil (soft-white in light, soft-black in
+  // dark). It exists for Figma's dark step-swap idiom — the file resolves the
+  // Palette collection through Light mode even on dark frames, so dark Intent
+  // variables alias neutral-alpha-inverse to reach the white veil — and the
+  // exact mirror keeps a variables backup a no-op.
+  it.each([
+    ['light', 'dark'],
+    ['dark', 'light'],
+  ] as const)("neutral-alpha-inverse in %s mode mirrors the %s mode's neutral-alpha ramp exactly", (mode, other) => {
+    for (const step of steps) {
+      expect(resolveRef(mode, `{color.neutral-alpha-inverse.${step}}`)).toBe(
+        resolveRef(other, `{color.neutral-alpha.${step}}`),
+      )
+    }
+  })
+})
+
+// The brand alpha ramp: the same construction as neutral-alpha (one anchor
+// colour, ten climbing alpha bytes) but anchored on `color.brand.500`, which is
+// the SAME hex in both themes. That is what makes this ramp the exception to the
+// mirror rule above — a `brand-alpha-inverse` companion would be identical to
+// `brand-alpha`, so it does not exist. Added for `action/primary/soft`, the
+// Stepper's current-step halo: `border/focus` and `action/primary/default` both
+// resolve to #236ce1, so a primary ring on the current marker would be
+// pixel-identical to the focus ring; a soft tint is what separates them.
+describe('color/brand-alpha ramp', () => {
+  const steps = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900'] as const
+
+  it.each(['light', 'dark'] as const)('%s mode anchors every step on the brand colour', (mode) => {
+    const brand = resolveRef(mode, '{color.brand.500}')
+    for (const step of steps) {
+      expect(resolveRef(mode, `{color.brand-alpha.${step}}`).slice(0, 7)).toBe(brand)
+    }
+  })
+
+  it.each(['light', 'dark'] as const)('%s mode climbs a strictly increasing alpha curve', (mode) => {
+    const alphas = steps.map((step) => parseInt(resolveRef(mode, `{color.brand-alpha.${step}}`).slice(7, 9), 16))
+    for (let i = 1; i < alphas.length; i++) {
+      expect(alphas[i]).toBeGreaterThan(alphas[i - 1])
+    }
+  })
+
+  // The reason there is no `brand-alpha-inverse`: unlike the neutral veil, the
+  // anchor does not flip with the theme, so both modes already agree.
+  it('resolves identically in light and dark mode, so it needs no inverse companion', () => {
+    for (const step of steps) {
+      expect(resolveRef('light', `{color.brand-alpha.${step}}`)).toBe(resolveRef('dark', `{color.brand-alpha.${step}}`))
+    }
+  })
+
+  it('backs action/primary/soft in both modes', () => {
     for (const mode of ['light', 'dark'] as const) {
-      const ratio = contrastRatio(intentColor(mode, token), intentColor(mode, 'surface/default'))
-      expect(ratio).toBeGreaterThanOrEqual(4.5)
+      expect(intentColor(mode, 'action/primary/soft')).toBe(resolveRef(mode, '{color.brand-alpha.300}'))
     }
   })
 })
@@ -71,12 +173,14 @@ describe.each([
   'surface/subtle',
   'surface/raised',
   'surface/overlay',
+  'surface/floating',
   'surface/inverse',
   'surface/sunken',
   'border/subtle',
   'border/default',
   'table/row/stripe',
   'table/row/hover',
+  'table/row/selected',
   'action/secondary/default',
   'action/secondary/hover',
   'action/secondary/active',
@@ -85,6 +189,10 @@ describe.each([
   'action/secondary/border/default',
   'action/secondary/border/hover',
   'action/secondary/border/disabled',
+  'action/ghost/hover',
+  'action/ghost/active',
+  'tree/row/hover',
+  'tree/row/selected',
 ] as const)('%s', (token) => {
   it('resolves to a different colour in light vs dark mode', () => {
     expect(intentColor('light', token)).not.toBe(intentColor('dark', token))
@@ -103,11 +211,62 @@ describe('surface/selected and content/on-selected', () => {
       expect(ratio).toBeLessThan(1.25)
     }
   })
+})
 
-  it('content/on-selected meets WCAG AA (4.5:1) against surface/selected in both modes', () => {
-    for (const mode of ['light', 'dark'] as const) {
-      const ratio = contrastRatio(intentColor(mode, 'content/on-selected'), intentColor(mode, 'surface/selected'))
-      expect(ratio).toBeGreaterThanOrEqual(4.5)
-    }
+// The swapped-index guard above only asserts light ≠ dark, which is too weak for
+// an OPAQUE background: `table/row/selected` was light #cbe5ff / dark #c8edff —
+// two different pale blues, so it passed that check while rendering a glaring
+// pale row on a dark surface. This is the assertion that actually pins the role:
+// an opaque background that tracks the theme must be light in light mode and dark
+// in dark mode, not merely different.
+//
+// Deliberately opaque-only. The alpha state layers (`*/row/hover`,
+// `tree/row/selected`, `action/ghost/*`) invert their ink by design — light mode
+// tints with dark ink, dark mode with light ink — and `surface/overlay` is an
+// inverse surface on purpose, so neither belongs here.
+describe.each([
+  'surface/subtle',
+  'surface/raised',
+  'surface/floating',
+  'surface/sunken',
+  'action/secondary/default',
+  'table/row/stripe',
+  'table/row/selected',
+  'choice-card/selected/background',
+] as const)('%s (opaque, theme-tracking background)', (token) => {
+  it('is light in light mode and dark in dark mode', () => {
+    expect(luminance(intentColor('light', token))).toBeGreaterThan(0.5)
+    expect(luminance(intentColor('dark', token))).toBeLessThan(0.5)
   })
 })
+
+/*
+ * Interactive foreground states must gain contrast, not lose it.
+ *
+ * This exists because a per-token contrast check is not enough. The dark link
+ * ramp descended — default → hover → active resolved #5291f9 → #033a8c →
+ * #022968, i.e. 5.95:1 → 1.74:1 → 1.33:1 — and the earlier guard passed
+ * throughout, because it only ever measured `default`.
+ *
+ * The cause was reading the step numbers as if both ramps ran the same way. They
+ * do not: in the LIGHT ramp a higher step is darker, in the DARK ramp a higher
+ * step is lighter. So "500 → 300 → 200" gains contrast against white and loses
+ * it against black, and the same alias pattern that is right in one mode is
+ * exactly wrong in the other.
+ *
+ * Asserting the DIRECTION rather than the values is what makes this robust: it
+ * holds whichever steps a future palette picks, and it is mode-agnostic, so the
+ * inverted ramp cannot fool it again.
+ */
+describe('action/link/foreground interactive states', () => {
+  it.each(['light', 'dark'] as const)(
+    '%s mode: hover and active are more prominent than the resting state',
+    (mode) => {
+      const bg = intentColor(mode, 'surface/default')
+      const at = (state: string) =>
+        contrastRatio(intentColor(mode, `action/link/foreground/${state}`), bg)
+      expect(at('hover')).toBeGreaterThan(at('default'))
+      expect(at('active')).toBeGreaterThan(at('hover'))
+    },
+  )
+})

package/src/dtcg.ts

@@ -70,7 +70,7 @@ export type AliasResolver = (variableId: string) => string[]
  *
  * Variables whose `variableCollectionId` does not match are skipped, so
  * callers can pass the full variable list. Slash-separated names become
- * nested objects (`font-family/heading` → `{ "font-family": { heading: {…} } }`).
+ * nested objects (`font-family/heading` → `{ "font-family": { heading: {...} } }`).
  * Values are read from the collection's `defaultModeId`; multi-mode
  * support is deferred until DTCG token sets land.
  *

package/src/heading-tracking.test.ts

@@ -0,0 +1,88 @@
+import context from './context.json'
+import primitives from './primitives.json'
+
+/*
+ * Heading letter-spacing (docs/interface-audit.md, 2026-08-15 `better-typography`:
+ * large headings want slightly negative tracking, and the `letter-spacing.tight` /
+ * `.tighter` primitives existed with nothing consuming them).
+ *
+ * Why this needs a test at all: tracking here is **absolute** (the primitive ramp
+ * emits `rem`, matching its `font-size` / `line-height` siblings in the same
+ * family), so the correct step differs per density mode — `heading.h1` is 18px in
+ * Dense and 88px in Spacious. That makes the source a 24-cell alias table, and a
+ * mis-keyed cell is invisible by inspection: `{letter-spacing.tighter}` looks just
+ * as plausible at h6 as at h1. The band assertion below is what ties each cell
+ * back to the reason it was chosen.
+ */
+
+type Mode = 'dense' | 'compact' | 'comfortable' | 'spacious'
+type DtcgNode = { $type?: string; $value?: unknown; [key: string]: unknown }
+
+const MODES: Mode[] = ['dense', 'compact', 'comfortable', 'spacious']
+const LEVELS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const
+
+/**
+ * The conventional band for display tracking, relative to the level's own font
+ * size. `LOOSEST` is the point below which a negative value stops being visible
+ * as tracking at all (so a level either sits in the band or is exactly normal);
+ * `TIGHTEST` is where letterforms start to collide. These are the two numbers the
+ * alias table was chosen against, named here so a failure reads as "this cell
+ * left the band" rather than "this cell is not -0.03".
+ */
+const BAND = { loosest: -0.01, tightest: -0.035 } as const
+
+/** Resolve a DTCG alias (`{letter-spacing.snug}`) against the primitive tree. */
+function resolvePrimitive(ref: string): number {
+  const path = ref.slice(1, -1).split('.')
+  let node: DtcgNode = primitives as DtcgNode
+  for (const key of path) node = node[key] as DtcgNode
+  return node.$value as number
+}
+
+/** A heading member's value in `mode`, resolved through its alias to a raw number. */
+function headingValue(mode: Mode, level: string, member: string): number {
+  const heading = (context as Record<Mode, DtcgNode>)[mode].heading as DtcgNode
+  const node = (heading[level] as DtcgNode)[member] as DtcgNode | undefined
+  if (node === undefined) throw new Error(`context.${mode}.heading.${level}.${member} is missing`)
+  const value = node.$value
+  return typeof value === 'string' ? resolvePrimitive(value) : (value as number)
+}
+
+describe('heading letter-spacing', () => {
+  it.each(MODES)('%s mode: every level declares a letter-spacing', (mode) => {
+    for (const level of LEVELS) {
+      expect(() => headingValue(mode, level, 'letter-spacing')).not.toThrow()
+    }
+  })
+
+  // The band is the whole point of the token: negative tracking at display sizes,
+  // nothing at reading sizes. Expressed relative to the level's own font size,
+  // because that is the quantity the eye judges — an absolute -1.2px is a
+  // comfortable -0.025em at 48px and an unreadable -0.067em at 18px.
+  it.each(MODES)('%s mode: tracking is either normal or inside the band', (mode) => {
+    for (const level of LEVELS) {
+      const em = headingValue(mode, level, 'letter-spacing') / headingValue(mode, level, 'font-size')
+      expect(em).toBeLessThanOrEqual(0)
+      if (em !== 0) {
+        expect(em).toBeLessThanOrEqual(BAND.loosest)
+        expect(em).toBeGreaterThanOrEqual(BAND.tightest)
+      }
+    }
+  })
+
+  it.each(MODES)('%s mode: tracking loosens as the heading level descends', (mode) => {
+    const track = LEVELS.map((level) => headingValue(mode, level, 'letter-spacing'))
+    for (let i = 1; i < track.length; i++) {
+      expect(track[i]).toBeGreaterThanOrEqual(track[i - 1])
+    }
+  })
+
+  it.each(LEVELS)('%s: tracking tightens as the density mode grows', (level) => {
+    // MODES is ordered smallest type to largest, so tracking must never loosen
+    // along it — the guard against a cell copied from the wrong mode's column.
+    const track = MODES.map((mode) => headingValue(mode, level, 'letter-spacing'))
+    for (let i = 1; i < track.length; i++) {
+      expect(track[i]).toBeLessThanOrEqual(track[i - 1])
+    }
+  })
+})