@halogen-ui/tokens 0.1.0

package/src/contrast-pairs.ts

@@ -0,0 +1,473 @@
+/**
+ * Halogen — the legal-adjacency map.
+ *
+ * Every pair of semantic tokens that can meet inside a component, with the
+ * contrast that pairing must reach. This file is the Phase 1 gate: a token pair
+ * that is not listed here is not permitted to meet, and every pair that is
+ * listed is asserted in both themes on every build.
+ *
+ * The point is exhaustiveness. Spot-checking "orange on black looks fine"
+ * verifies the pair nobody was going to get wrong; the failures live in
+ * tertiary text on a popover, and a boundary on the one surface that is a shade
+ * lighter than the one it was designed against.
+ */
+
+export type ThemeName = 'dark' | 'light';
+
+export interface ContrastPair {
+  fg: string;
+  bg: string;
+  /** Minimum WCAG 2.x contrast ratio. */
+  min: number;
+  /** The success criterion this pairing is held to. */
+  sc: string;
+  context: string;
+  /** Restrict to one theme when the pairing only exists there. */
+  themes?: ThemeName[];
+}
+
+/**
+ * Surfaces a general-purpose text token may legally sit on.
+ *
+ * Deliberately excludes the interactive fills. `surface-subtle` and its hover
+ * and active steps run several ramp steps toward mid-gray, and the only text
+ * that appears on them is a control's own label — which is always
+ * `ink-primary`. Enumerating tertiary or accent text there would assert a
+ * pairing the system never produces, and would force the whole text ramp
+ * lighter to satisfy a case that does not exist.
+ */
+export const TEXT_SURFACES = [
+  'surface-ground',
+  'surface-raised',
+  'surface-overlay',
+  'surface-floating',
+  'surface-modal',
+] as const;
+
+/** Interactive fills. Only a control's own label appears here. */
+export const CONTROL_FILLS = [
+  'surface-subtle',
+  'surface-subtle-hover',
+  'surface-subtle-active',
+  'surface-field',
+] as const;
+
+/**
+ * Surfaces a boundary is asserted against.
+ *
+ * A control's boundary exists to identify the control against the surface it
+ * sits ON — plus its own resting fill, since an input's border separates the
+ * fill from the page. It is deliberately NOT asserted against the hover and
+ * pressed fills: those run several steps toward mid-gray, and requiring 3:1
+ * there would force every border in the system dark enough to fight the
+ * "restrained chrome" the aesthetic direction calls for, to satisfy a moment
+ * when the user's own cursor or finger is on the control and identification is
+ * not in question. State perception on those fills is covered separately.
+ */
+export const BOUNDARY_SURFACES = [...TEXT_SURFACES, 'surface-subtle', 'surface-field'] as const;
+
+const STATUSES = ['success', 'warning', 'error', 'info'] as const;
+
+/** Surfaces a status message can appear on, besides its own chip. */
+const STATUS_HOST_SURFACES = ['surface-ground', 'surface-raised', 'surface-overlay'] as const;
+
+const pairs: ContrastPair[] = [];
+
+const add = (p: ContrastPair): void => {
+  pairs.push(p);
+};
+
+/* ---- Body and supporting text: WCAG 1.4.3 ---- */
+for (const bg of TEXT_SURFACES) {
+  for (const fg of ['ink-primary', 'ink-secondary', 'ink-tertiary'] as const) {
+    add({ fg, bg, min: 4.5, sc: '1.4.3 Contrast (Minimum)', context: `${fg} on ${bg}` });
+  }
+}
+
+/**
+ * The house standard: AAA for primary body text on the two ground surfaces.
+ * Held separately from the AA floor so a regression that drops it below 7:1 but
+ * above 4.5:1 still shows up as a named failure rather than passing quietly.
+ */
+for (const bg of ['surface-ground', 'surface-raised'] as const) {
+  add({
+    fg: 'ink-primary',
+    bg,
+    min: 7,
+    sc: '1.4.6 Contrast (Enhanced) — Halogen house standard',
+    context: `primary body text on ${bg}`,
+  });
+}
+
+/* ---- Control labels sit on the interactive fills, through every state. ---- */
+for (const bg of CONTROL_FILLS) {
+  add({ fg: 'ink-primary', bg, min: 4.5, sc: '1.4.3', context: `control label on ${bg}` });
+}
+
+/* ---- Placeholder text is text. It fails AA in most systems. ---- */
+for (const bg of ['surface-field', 'surface-raised'] as const) {
+  add({ fg: 'ink-placeholder', bg, min: 4.5, sc: '1.4.3', context: `placeholder in an input on ${bg}` });
+}
+
+/* ---- Accent text and links ---- */
+for (const bg of TEXT_SURFACES) {
+  for (const fg of ['ink-accent', 'ink-link', 'ink-link-hover'] as const) {
+    add({ fg, bg, min: 4.5, sc: '1.4.3', context: `${fg} on ${bg}` });
+  }
+}
+
+/* ---- Labels on fills. The near-black-on-warm rule, asserted per state. ---- */
+for (const bg of ['surface-accent', 'surface-accent-hover', 'surface-accent-active'] as const) {
+  add({ fg: 'ink-on-accent', bg, min: 4.5, sc: '1.4.3', context: `button label on ${bg}` });
+}
+/**
+ * The accent-tinted surfaces, at every ink step that legally appears on them.
+ *
+ * This list used to hold `ink-primary` alone, and that gap shipped a real
+ * failure: the notification row put a timestamp in `ink-tertiary` on the unread
+ * row's tint, which measures 4.44:1 in the light theme. axe caught it in the
+ * browser; the token suite had nothing to say, because it had never been asked.
+ * `ink-tertiary` is now forbidden here — see FORBIDDEN_PAIRS, which asserts the
+ * shortfall rather than merely omitting the pair.
+ */
+for (const bg of ['surface-accent-subtle', 'surface-accent-subtle-hover'] as const) {
+  for (const fg of ['ink-primary', 'ink-secondary'] as const) {
+    add({ fg, bg, min: 4.5, sc: '1.4.3 Contrast (Minimum)', context: `${fg} on ${bg}` });
+  }
+}
+// The accent text step appears on the resting tint only: a selected chip does
+// not change ground on hover, so it never meets the deeper hovered step.
+add({
+  fg: 'ink-on-accent-subtle',
+  bg: 'surface-accent-subtle',
+  min: 4.5,
+  sc: '1.4.3 Contrast (Minimum)',
+  context: 'accent text on the quiet accent surface',
+});
+// The accent badge. This pair was missing from the map and axe found it in the
+// browser before the token layer did — a component reached a combination the
+// map had not enumerated, which is exactly the gap in-browser testing exists for.
+add({
+  fg: 'ink-on-accent-subtle',
+  bg: 'surface-accent-subtle',
+  min: 4.5,
+  sc: '1.4.3',
+  context: 'accent badge label on its own chip',
+});
+add({
+  fg: 'line-accent',
+  bg: 'surface-accent-subtle',
+  min: 3,
+  sc: '1.4.11',
+  context: 'accent badge boundary on its own chip',
+});
+add({ fg: 'ink-inverse', bg: 'surface-inverse', min: 4.5, sc: '1.4.3', context: 'text on an intentionally inverted card' });
+
+/* ---- Status ---- */
+for (const s of STATUSES) {
+  add({
+    fg: `status-${s}-ink`,
+    bg: `status-${s}-surface`,
+    min: 4.5,
+    sc: '1.4.3',
+    context: `${s} text on its own chip`,
+  });
+  for (const bg of STATUS_HOST_SURFACES) {
+    add({ fg: `status-${s}-ink`, bg, min: 4.5, sc: '1.4.3', context: `inline ${s} message on ${bg}` });
+  }
+  add({
+    fg: `status-${s}-on-solid`,
+    bg: `status-${s}-solid`,
+    min: 4.5,
+    sc: '1.4.3',
+    context: `label on the ${s} solid fill`,
+  });
+  add({
+    fg: `status-${s}-line`,
+    bg: `status-${s}-surface`,
+    min: 3,
+    sc: '1.4.11 Non-text Contrast',
+    context: `${s} chip boundary`,
+  });
+  for (const bg of STATUS_HOST_SURFACES) {
+    add({ fg: `status-${s}-line`, bg, min: 3, sc: '1.4.11', context: `${s} boundary on ${bg}` });
+  }
+}
+
+/* ---- Boundaries that identify a control: WCAG 1.4.11 ---- */
+for (const bg of BOUNDARY_SURFACES) {
+  for (const fg of ['line-control', 'line-strong', 'line-focus'] as const) {
+    add({ fg, bg, min: 3, sc: '1.4.11 Non-text Contrast', context: `${fg} on ${bg}` });
+  }
+}
+for (const bg of ['surface-ground', 'surface-raised', 'surface-overlay'] as const) {
+  add({ fg: 'line-accent', bg, min: 3, sc: '1.4.11', context: `accent boundary on ${bg}` });
+}
+
+/**
+ * The focus ring must also clear 3:1 against the accent fill it sits on — an
+ * orange ring on an orange button is not a ring. This is where the ring flips
+ * to near-black.
+ */
+add({
+  fg: 'ink-on-accent',
+  bg: 'surface-accent',
+  min: 3,
+  sc: '2.4.11 Focus Appearance',
+  context: 'focus ring on a primary button flips to near-black',
+});
+
+/* ---- Data visualization marks: WCAG 1.4.11 ---- */
+for (const bg of ['surface-ground', 'surface-raised'] as const) {
+  for (let i = 1; i <= 7; i++) {
+    add({ fg: `viz-${i}`, bg, min: 3, sc: '1.4.11', context: `chart series ${i} on ${bg}` });
+  }
+  add({ fg: 'viz-axis', bg, min: 4.5, sc: '1.4.3', context: `axis label on ${bg}` });
+  /**
+   * Only the signal end of a sequential ramp is held to 3:1 — the top two steps.
+   *
+   * A five-step scale running from near-surface to fully saturated necessarily
+   * passes through a mid-tone, and in the light theme that mid-tone cannot clear
+   * 3:1 against white however it is chosen: it is halfway between the page and
+   * the darkest ink by construction. WCAG 1.4.11 covers graphical parts required
+   * to understand the content; in a ramp that job is done by position within the
+   * scale and its labels, not by every cell standing off the page. Requiring all
+   * five would produce a ramp with no low end and no middle.
+   *
+   * The steps that *are* exempt get a different guarantee instead: adjacent
+   * steps must be distinguishable from one another (see the ramp-separation
+   * test), which is the property a sequential scale actually depends on.
+   */
+  for (const i of [3, 4]) {
+    add({ fg: `viz-sequential-${i}`, bg, min: 3, sc: '1.4.11', context: `sequential step ${i} on ${bg}` });
+  }
+  for (const k of ['neg-2', 'neg-1', 'pos-1', 'pos-2']) {
+    add({ fg: `viz-diverging-${k}`, bg, min: 3, sc: '1.4.11', context: `diverging ${k} on ${bg}` });
+  }
+}
+
+export const CONTRAST_PAIRS: readonly ContrastPair[] = pairs;
+
+/**
+ * Pairs that are NOT legal, kept as measured prohibitions rather than silence.
+ *
+ * An omitted pair says nothing — it reads identically whether the combination
+ * was considered and rejected or simply never thought about. `ink-tertiary` on
+ * an accent-tinted surface was the second kind, and it shipped.
+ *
+ * Every entry is asserted to actually fail its threshold. If a future token
+ * change makes one of these pass, the test says so and the prohibition should be
+ * lifted rather than left standing as folklore.
+ */
+export interface ForbiddenPair {
+  fg: string;
+  bg: string;
+  /** The threshold it must fail. */
+  min: number;
+  themes: readonly ('dark' | 'light')[];
+  why: string;
+  /** What a component should reach for instead. */
+  instead: string;
+}
+
+export const FORBIDDEN_PAIRS: readonly ForbiddenPair[] = [
+  {
+    fg: 'ink-tertiary',
+    bg: 'surface-accent-subtle',
+    min: 4.5,
+    themes: ['light'],
+    why:
+      'The quiet accent tint is light enough in the light theme that the tertiary ink step lands at 4.44:1 — a ' +
+      'shortfall of 0.06, invisible to the eye and fatal to the claim. Deepening the tint was rejected: the tint ' +
+      'is a product decision, and the timestamp had no business being the quietest step on a highlighted row.',
+    instead: 'ink-secondary',
+  },
+  {
+    fg: 'ink-tertiary',
+    bg: 'surface-accent-subtle-hover',
+    min: 4.5,
+    themes: ['dark', 'light'],
+    why:
+      'The hovered tint is deeper than the resting one by design, which costs contrast in both themes: 4.19:1 dark ' +
+      'and 3.91:1 light. Any ink step legal on the resting tint must also clear the hovered one, because a row ' +
+      'does not stop being readable while the pointer is over it.',
+    instead: 'ink-secondary',
+  },
+];
+
+/**
+ * Pairings that are knowingly below their requirement.
+ *
+ * A waiver is not a deleted assertion. The pair stays in the map, the shortfall
+ * is measured on every build, and it is reported in the contrast report and the
+ * accessibility statement. The difference between a design system that has one
+ * documented exception and one that quietly dropped a test is the difference
+ * between an honest product and a misleading one.
+ *
+ * Every entry must actually fail — a waiver for something that now passes is
+ * stale and is treated as an error, so this list cannot accumulate cover for
+ * problems that were fixed years ago.
+ */
+export interface ContrastWaiver {
+  fg: string;
+  /** Specific backgrounds, or '*' for every pairing this foreground appears in. */
+  bgs: readonly string[] | '*';
+  themes: readonly ThemeName[];
+  why: string;
+  /** Who made the call. Waivers are product decisions, not engineering ones. */
+  decidedBy: string;
+}
+
+export const CONTRAST_WAIVERS: readonly ContrastWaiver[] = [
+  {
+    fg: 'line-control',
+    bgs: '*',
+    themes: ['dark', 'light'],
+    why:
+      'The control border is set to sit almost on the fill in both themes — neutral-800 on dark, neutral-100 ' +
+      '(matching surface-subtle) on light — giving a near-borderless field. It reads about 1.29:1 on dark and ' +
+      '1.21:1 on light against the field, where WCAG 1.4.11 requires 3:1. Nothing else identifies the control: a ' +
+      'filled input is only 1.28:1 (dark) / 1.12:1 (light) from the page. A field is therefore found by its ' +
+      'label and placeholder rather than by its edge. This is the larger of the two waivers by a wide margin.',
+    decidedBy: 'Product owner, 2026-08-26 (dark) and 2026-08-27 (light), with the measured shortfall stated.',
+  },
+  {
+    fg: 'line-focus',
+    bgs: '*',
+    themes: ['light'],
+    why:
+      'The focus ring uses the brand orange in both themes so the accent does not shift between them. On a white ' +
+      'page that reads 2.96:1 where WCAG 1.4.11 requires 3:1 — a shortfall of roughly 1%, not the 60% of the ' +
+      'border waiver, and visually indistinguishable from a compliant ring. Recorded separately so the two are ' +
+      'never mistaken for equivalent risks. Restoring compliance costs only a slightly deeper orange ' +
+      '(orange.mark-light, solved for exactly 3:1) if that trade is ever preferred.',
+    decidedBy: 'Product owner, 2026-08-27, with the measured shortfall stated.',
+  },
+];
+
+/** True when this exact pairing is covered by a declared waiver. */
+export function isWaived(fg: string, bg: string, theme: ThemeName): ContrastWaiver | undefined {
+  return CONTRAST_WAIVERS.find(
+    (w) => w.fg === fg && w.themes.includes(theme) && (w.bgs === '*' || w.bgs.includes(bg)),
+  );
+}
+
+/**
+ * Ordered ramps. Adjacent steps must be distinguishable from each other, which
+ * is the property a sequential or diverging scale actually relies on — and the
+ * one that replaces the 3:1-against-the-page rule for the ramps' quiet ends.
+ */
+export const RAMP_SEQUENCES: ReadonlyArray<{
+  name: string;
+  steps: string[];
+  /** Minimum OKLCH lightness delta between adjacent steps. */
+  minAdjacentL: number;
+  /** Sequential scales encode magnitude and must be monotonic; diverging ones must not. */
+  monotonic: boolean;
+}> = [
+  {
+    name: 'sequential-heat',
+    steps: ['viz-sequential-0', 'viz-sequential-1', 'viz-sequential-2', 'viz-sequential-3', 'viz-sequential-4'],
+    minAdjacentL: 0.06,
+    monotonic: true,
+  },
+  {
+    // A diverging scale is deliberately NOT monotonic — it recedes to a neutral
+    // midpoint and rises again. Only step separation is meaningful.
+    name: 'diverging',
+    steps: [
+      'viz-diverging-neg-2',
+      'viz-diverging-neg-1',
+      'viz-diverging-0',
+      'viz-diverging-pos-1',
+      'viz-diverging-pos-2',
+    ],
+    minAdjacentL: 0.05,
+    monotonic: false,
+  },
+];
+
+/**
+ * Tokens deliberately exempt from a contrast minimum, with the reason. Listed
+ * explicitly so "it isn't tested" and "it doesn't need testing" are different
+ * states, and so a reviewer can challenge each exemption individually.
+ */
+export const CONTRAST_EXEMPT: ReadonlyArray<{ token: string; why: string }> = [
+  {
+    token: 'line-divider',
+    why: 'Structural separation between regions of one surface — a footer bar, a toolbar edge. WCAG 1.4.11 covers boundaries required to identify a component; a rule between two parts of the same panel is not one. Sized to be clearly visible regardless.',
+  },
+  {
+    token: 'line-subtle',
+    why: 'Decorative dividers and card hairlines. WCAG 1.4.11 applies to boundaries required to identify a component; a divider is not one. Barred from interactive controls by lint.',
+  },
+  {
+    token: 'line-disabled',
+    why: 'Disabled controls are explicitly exempt from 1.4.3 and 1.4.11.',
+  },
+  {
+    token: 'ink-disabled',
+    why: 'Disabled text is explicitly exempt from 1.4.3. Still chosen to remain perceivable.',
+  },
+  {
+    token: 'line-edge-highlight',
+    why: 'Purely an elevation cue standing in for a shadow in dark mode. Carries no information; the surface change beneath it does.',
+  },
+  { token: 'viz-grid', why: 'Chart gridlines are decorative scaffolding; the axis labels carry the information.' },
+  {
+    token: 'viz-sequential-0',
+    why: 'The low end of a sequential ramp is meant to sit near the surface — that is what makes a heatmap readable as a scale. Held instead to the even-spacing and monotonicity rules in RAMP_SEQUENCES.',
+  },
+  {
+    token: 'viz-sequential-1',
+    why: 'Second step of the sequential ramp, same reasoning as step 0. Held to adjacent-step separation.',
+  },
+  {
+    token: 'viz-sequential-2',
+    why: 'The midpoint of the scale. In the light theme a mid-tone cannot clear 3:1 against a white page however it is chosen — it sits halfway between page and ink by construction. Held to even spacing and monotonicity instead.',
+  },
+  {
+    token: 'viz-diverging-0',
+    why: 'The neutral midpoint of a diverging scale represents "no deviation" and is meant to recede. Held to adjacent-step separation.',
+  },
+  {
+    token: 'ink-on-scrim-secondary',
+    why: 'Text over a flat scrim. Same reasoning as ink-on-scrim: the background is a blend, not a token, and the scrim opacity is chosen so this step clears AA over the worst of them.',
+  },
+  {
+    token: 'ink-on-scrim',
+    why: 'Text over a flat scrim. The scrim is translucent and sits over an arbitrary gradient, so there is no single background to assert against — the scrimmed result is what matters, and the scrim opacity is chosen so this token clears AA over every blend.',
+  },
+  {
+    token: 'surface-selection',
+    why: 'A translucent selection wash. The selected text keeps its own color, which is asserted against the surface beneath; the wash only tints what is behind it.',
+  },
+  {
+    token: 'surface-knob',
+    why: 'The switch thumb. Its job is positional, not informational — the state it conveys is where it sits, and it carries a shadow so its edge reads on any track.',
+  },
+  {
+    token: 'surface-state-hover',
+    why: 'A translucent interaction wash. It carries no information of its own — it lightens or darkens whatever surface is beneath it, and the content on top is asserted against that surface.',
+  },
+  {
+    token: 'surface-state-active',
+    why: 'A translucent interaction wash, as above. Pressed rather than hovered.',
+  },
+  {
+    token: 'line-focus-glow',
+    why: 'A soft halo behind the focus ring, at low alpha. The ring itself is the indicator and is contrast-asserted; the glow only emphasizes it.',
+  },
+  {
+    token: 'surface-subtle-hover',
+    why: 'A hover fill carries no information of its own; the label on it is text-primary, which IS asserted against it.',
+  },
+  {
+    token: 'surface-subtle-active',
+    why: 'A pressed fill carries no information of its own; the label on it is text-primary, which IS asserted against it.',
+  },
+  { token: 'surface-scrim', why: 'A scrim has no foreground of its own; contrast is asserted on what sits above it.' },
+  { token: 'surface-disabled', why: 'Disabled surfaces are exempt; their text is text-disabled, also exempt.' },
+  { token: 'gradient-glow', why: 'A background atmosphere field with no text directly on it.' },
+  { token: 'gradient-ground', why: 'A near-invisible page-ground gradient between two adjacent neutral steps.' },
+];

package/src/namespaces.ts

@@ -0,0 +1,59 @@
+/**
+ * Halogen — the Tailwind namespaces the system owns.
+ *
+ * ONE source of truth, imported by both the emitter and the test that verifies
+ * the emitter. It used to be two: `fan-out.ts` held the real list and
+ * `contrast.test.ts` held a hand-copied duplicate. Adding `aspect` to the
+ * emitter made the test fail — correctly, but for the wrong reason: it was
+ * reporting that its own copy was stale. Two lists that must agree will
+ * eventually disagree, and the failure looks like a bug in the thing being
+ * tested.
+ */
+/**
+ * Every Tailwind namespace Halogen owns is reset to initial before ours are
+ * declared. That is what turns "use tokens" from a guideline into a compile
+ * error: after this block there is no bg-blue-500, no p-7, no rounded-3xl
+ * — those utilities do not exist.
+ */
+export const REPLACED_NAMESPACES = [
+  'color', 'spacing', 'radius', 'font', 'text', 'font-weight', 'tracking',
+  'leading', 'shadow', 'ease', 'breakpoint', 'container',
+  // `duration-*` reads from `--transition-duration-*`, not `--duration-*`.
+  // Getting that wrong is invisible: `duration-fast` compiles to nothing and
+  // the transition silently falls back to the browser default.
+  'transition-duration',
+  // Media ratios. Tailwind ships aspect-video and aspect-square; replacing the
+  // namespace means those come from the token scale instead, and a fourth ratio
+  // has to be added to the scale rather than written inline.
+  'aspect',
+  // Stacking order and text measure. Both were reachable as CSS variables and
+  // invisible as utilities: `z-sticky` and `max-w-measure` compiled to nothing.
+  'z-index',
+];
+
+/**
+ * Reset with NOTHING declared back — deliberately, so these utilities cannot
+ * compile at all.
+ *
+ * This is the aesthetic direction enforced by the compiler rather than by a
+ * code review. §36 rejects glassmorphism and excessive blur outright, so
+ * backdrop-blur-md should not be a thing a developer can reach for and be
+ * talked out of later; it should not exist. Same for keyframe animation: Halogen
+ * motion is transitions, and animate-bounce is on the anti-pattern list.
+ *
+ * Adding a value here is a design decision, not a convenience. Phase 4's spinner
+ * will need one keyframe, and it will be added as a named token on purpose.
+ */
+export const ABOLISHED_NAMESPACES = ['blur'];
+
+/**
+ * Reset, then reopened to an explicit whitelist — nothing else in the namespace
+ * can compile.
+ *
+ * animate exists for exactly one thing: a loading spinner, which is a genuine
+ * product need that cannot be expressed as a transition. animate-spin works;
+ * animate-bounce and animate-pulse still do not exist, because the aesthetic
+ * direction rejects bounce and constant movement. Widening this list is a design
+ * decision that has to be argued for, which is the point of keeping it a list.
+ */
+export const BOUNDED_NAMESPACES: Record<string, string[]> = { animate: ['spin', 'pulse'] };