@rafters/color-utils 0.4.4 → 0.4.5

package/README.md

@@ -77,6 +77,16 @@ everywhere, `p3` needs a wide-gamut screen, `out` is displayable nowhere.
   `{ color, tier }`: the snapped OKLCH and the tier it landed in.
 - `computeGamutBoundaries(hue, steps?)` — the boundary points a picker draws
   against.
+- `toGamutCeiling(oklch, ceiling)` — map one color into `'srgb'` or `'p3'`;
+  unchanged when already inside.
+- `mapScaleToGamut(scale, ceiling)` — map every step of a scale into the
+  ceiling, keeping lightness strictly falling.
+- `ALLOW_P3` — whether a family may keep Display P3 steps; `false`.
+
+`buildColorValue` builds every family inside a ceiling its seed sets: `'p3'`
+only when the seed is a P3 color and `ALLOW_P3` is on, else `'srgb'`. The
+result records each step's tier in `gamut`, and `seedAdjusted` whenever the
+seed was moved (by the lightness bounds or into the gamut).
 
 Boundary checks run through `colorjs.io`, so sRGB and P3 agree with what the
 browser will render.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafters/color-utils",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "OKLCH color manipulation utilities for Rafters design system",
   "homepage": "https://rafters.studio",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "apca-w3": "^0.1.9",
     "colorjs.io": "^0.5.2",
     "zod": "^4.1.12",
-    "@rafters/shared": "0.4.4"
+    "@rafters/shared": "0.4.5"
   },
   "devDependencies": {
     "@types/node": "24.10.0",

package/src/accessibility.ts

@@ -1,11 +1,23 @@
 /**
- * Accessibility contrast calculation and compliance checking functions
+ * Accessibility contrast calculation and compliance checking functions.
+ *
+ * Every colour is measured as stored, in the gamut it is stored in (sRGB or
+ * Display P3), never through a clipped sRGB copy.
+ *
+ * - WCAG 2.2 contrast: relative luminance is the colour's CIE XYZ (D65) Y
+ *   (colorjs.io 'xyz-d65'). Y exists for any colour, so no gamut mapping is
+ *   needed, and an sRGB colour's ratio matches the sRGB-channel formula.
+ * - APCA contrast (informational): luminance from APCA's own per-space
+ *   function -- sRGBtoY for an sRGB colour (0-255 channels), displayP3toY for
+ *   a P3 colour (0-1 channels) -- chosen by getGamutTier. A colour beyond P3
+ *   is first mapped into P3 with toGamutCeiling(colour, 'p3').
  */
 
 import type { ColorValue, OKLCH } from '@rafters/shared';
-import { APCAcontrast, sRGBtoY } from 'apca-w3';
+import { APCAcontrast, displayP3toY, sRGBtoY } from 'apca-w3';
 import Color from 'colorjs.io';
 import { z } from 'zod';
+import { getGamutTier, toGamutCeiling } from './gamut.js';
 
 /** White reference color for contrast calculations. */
 export const CONTRAST_WHITE: OKLCH = { l: 1, c: 0, h: 0, alpha: 1 };
@@ -13,7 +25,7 @@ export const CONTRAST_WHITE: OKLCH = { l: 1, c: 0, h: 0, alpha: 1 };
 /** Black reference color for contrast calculations. */
 export const CONTRAST_BLACK: OKLCH = { l: 0, c: 0, h: 0, alpha: 1 };
 
-/** WCAG 2.1 minimum contrast ratios, by conformance level and text size. */
+/** WCAG 2.2 minimum contrast ratios, by conformance level and text size. */
 const WCAG_CONTRAST_THRESHOLDS = {
   AA: { normal: 4.5, large: 3.0 },
   AAA: { normal: 7.0, large: 4.5 },
@@ -50,29 +62,15 @@ export function minFontSizeForAPCA(contrast: number): number {
 }
 
 /**
- * Convert OKLCH to relative luminance for WCAG calculations
+ * Relative luminance for WCAG 2.2: the colour's CIE XYZ (D65) Y, read from
+ * the colour itself with no sRGB step, so a P3 colour is measured as stored.
  */
 function getRelativeLuminance(oklch: OKLCH): number {
-  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
-  const srgb = color.to('srgb');
-
-  // WCAG formula for relative luminance
-  const toLinear = (val: number): number => {
-    if (val <= 0.03928) {
-      return val / 12.92;
-    }
-    return ((val + 0.055) / 1.055) ** 2.4;
-  };
-
-  const r = toLinear(srgb.r);
-  const g = toLinear(srgb.g);
-  const b = toLinear(srgb.b);
-
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  return new Color('oklch', [oklch.l, oklch.c, oklch.h]).to('xyz-d65').coords[1] ?? 0;
 }
 
 /**
- * Calculate WCAG 2.1 contrast ratio between two colors
+ * Calculate WCAG 2.2 contrast ratio between two colors
  */
 export function calculateWCAGContrast(foreground: OKLCH, background: OKLCH): number {
   const l1 = getRelativeLuminance(foreground);
@@ -85,31 +83,37 @@ export function calculateWCAGContrast(foreground: OKLCH, background: OKLCH): num
 }
 
 /**
- * Calculate APCA contrast for modern accessibility
- * Uses the official APCA algorithm via apca-w3 library
+ * A channel of an in-gamut colour, guarded only against float noise: colorjs
+ * can return a value a hair outside [0, 1] for a colour inside the gamut, and
+ * apca-w3 raises each channel to 2.4, which is NaN for a negative base. This
+ * is not a gamut clip -- the colour is already inside the space measured.
  */
-export function calculateAPCAContrast(foreground: OKLCH, background: OKLCH): number {
-  // Convert OKLCH to RGB arrays for APCA
-  const foregroundColor = new Color('oklch', [foreground.l, foreground.c, foreground.h]);
-  const backgroundColorObj = new Color('oklch', [background.l, background.c, background.h]);
-
-  const fgRgb = foregroundColor.to('srgb');
-  const bgRgb = backgroundColorObj.to('srgb');
-
-  // Convert to 0-255 RGB values for apca-w3
-  const fgR = Math.max(0, Math.min(255, (fgRgb.r || 0) * 255));
-  const fgG = Math.max(0, Math.min(255, (fgRgb.g || 0) * 255));
-  const fgB = Math.max(0, Math.min(255, (fgRgb.b || 0) * 255));
-  const bgR = Math.max(0, Math.min(255, (bgRgb.r || 0) * 255));
-  const bgG = Math.max(0, Math.min(255, (bgRgb.g || 0) * 255));
-  const bgB = Math.max(0, Math.min(255, (bgRgb.b || 0) * 255));
+function inGamutChannel(value: number | null | undefined): number {
+  return Math.min(1, Math.max(0, value ?? 0));
+}
 
-  // Calculate luminance values
-  const fgY = sRGBtoY([fgR, fgG, fgB]);
-  const bgY = sRGBtoY([bgR, bgG, bgB]);
+/**
+ * APCA luminance of a colour in the gamut it is stored in: sRGBtoY (0-255
+ * channels) for an sRGB colour, displayP3toY (0-1 channels) for a P3 colour.
+ * A colour beyond P3 is mapped into P3 with toGamutCeiling first.
+ */
+function getAPCALuminance(oklch: OKLCH): number {
+  const tier = getGamutTier(oklch);
+  if (tier === 'srgb') {
+    const [r, g, b] = new Color('oklch', [oklch.l, oklch.c, oklch.h]).to('srgb').coords;
+    return sRGBtoY([inGamutChannel(r) * 255, inGamutChannel(g) * 255, inGamutChannel(b) * 255]);
+  }
+  const inP3 = tier === 'out' ? toGamutCeiling(oklch, 'p3') : oklch;
+  const [r, g, b] = new Color('oklch', [inP3.l, inP3.c, inP3.h]).to('p3').coords;
+  return displayP3toY([inGamutChannel(r), inGamutChannel(g), inGamutChannel(b)]);
+}
 
-  // Use official APCA calculation
-  const result = APCAcontrast(fgY, bgY);
+/**
+ * Calculate APCA contrast (informational) via the apca-w3 library, from
+ * each colour's luminance in the gamut it is stored in.
+ */
+export function calculateAPCAContrast(foreground: OKLCH, background: OKLCH): number {
+  const result = APCAcontrast(getAPCALuminance(foreground), getAPCALuminance(background));
   return typeof result === 'number' ? result : 0;
 }
 
@@ -229,6 +233,14 @@ export function generateAccessibilityMetadata(scale: OKLCH[]): AccessibilityMeta
   return metadata;
 }
 
+/**
+ * The step a family's on-white/on-black figures are measured on: the 600
+ * step, where the seed lands (after any seed adjustment). buildColorValue and
+ * rebakeAccessibility both read it, so re-baking an unchanged family is a
+ * no-op.
+ */
+export const REFERENCE_STEP_INDEX = 6;
+
 /**
  * Assemble the WCAG half of ColorValue.accessibility for a scale: pair
  * matrices plus on-white/on-black ratios and pass flags for a reference
@@ -271,7 +283,7 @@ export function assembleWcagAccessibility(
  */
 export function rebakeAccessibility(value: ColorValue): ColorValue {
   if (!('scale' in value) || !Array.isArray(value.scale)) return value;
-  const reference = value.scale[5] ?? value.scale[0];
+  const reference = value.scale[REFERENCE_STEP_INDEX] ?? value.scale[0];
   if (!reference) return value;
   return { ...value, accessibility: assembleWcagAccessibility(value.scale, reference) };
 }

package/src/analysis.ts

@@ -13,10 +13,10 @@ export function isLightColor(color: OKLCH): boolean {
   // Base threshold at 50% lightness
   let threshold = 0.5;
 
-  // Adjust threshold based on chroma
-  // High chroma colors appear darker due to the Helmholtz-Kohlrausch effect
+  // Adjust threshold based on chroma. Helmholtz-Kohlrausch: at equal
+  // lightness a saturated colour looks lighter, so the threshold drops.
   if (color.c > 0.15) {
-    threshold += color.c * 0.3; // Increase threshold for high chroma
+    threshold -= color.c * 0.3;
   }
 
   // Very low chroma colors are essentially gray, use simple lightness
@@ -125,7 +125,10 @@ export function calculatePerceptualWeight(color: OKLCH): {
   const hue = color.h;
   let hueWeight = 0.5;
 
-  if (hue >= 345 || hue <= 15)
+  // An achromatic colour has no hue to weigh (its h is 0, which would read as
+  // red); same neutral threshold as getColorTemperature.
+  if (color.c < 0.04) hueWeight = 0.5;
+  else if (hue >= 345 || hue <= 15)
     hueWeight = 0.9; // Red - heaviest
   else if (hue <= 45)
     hueWeight = 0.8; // Red-Orange

package/src/builder.ts

@@ -15,6 +15,7 @@ import {
   CONTRAST_BLACK,
   CONTRAST_WHITE,
   minFontSizeForAPCA,
+  REFERENCE_STEP_INDEX,
 } from './accessibility.js';
 import {
   calculateAtmosphericWeight,
@@ -22,7 +23,15 @@ import {
   getColorTemperature,
   isLightColor,
 } from './analysis.js';
-import { generateHarmony, generateOKLCHScale } from './harmony.js';
+import {
+  ceilingForSeed,
+  getGamutTier,
+  mapScaleToGamut,
+  storedTier,
+  toGamutCeiling,
+} from './gamut.js';
+import { boundSeedLightness, generateHarmony, generateOKLCHScale } from './harmony.js';
+import { roundOKLCH } from './conversion.js';
 import { generateColorName } from './naming/index.js';
 import { SCALE_POSITIONS } from './scale-positions.js';
 import { generateSemanticColorSuggestions } from './semantic.js';
@@ -82,18 +91,42 @@ export interface BuildColorValueOptions {
  * ```
  */
 export function buildColorValue(oklch: OKLCH, options: BuildColorValueOptions = {}): ColorValue {
-  // Generate the 11-position scale
-  const scaleRecord = generateOKLCHScale(oklch);
-  const scale = SCALE_POSITIONS.map((pos) => scaleRecord[pos]).filter(
-    (v): v is OKLCH => v !== undefined,
+  // The seed the family is built from: inside the lightness bounds first,
+  // then, for a P3 seed above the ceiling (P3 not allowed), mapped into sRGB
+  // before the scale is built. Every step, the seed's included, is then mapped
+  // into the ceiling. Any move of the seed is recorded below.
+  const bounded = boundSeedLightness(oklch);
+  const ceiling = ceilingForSeed(bounded);
+  const seed = getGamutTier(bounded) === 'p3' ? toGamutCeiling(bounded, ceiling) : bounded;
+
+  // Generate the 11-position scale and map every step into the ceiling
+  const scaleRecord = generateOKLCHScale(seed);
+  const scale = mapScaleToGamut(
+    SCALE_POSITIONS.map((pos) => scaleRecord[pos]).filter((v): v is OKLCH => v !== undefined),
+    ceiling,
   );
+  const gamut = scale.map(storedTier);
+
+  // The seed lands on the 600 step. Any difference from the requested seed
+  // (beyond the rounding every step gets) is a move, and is recorded.
+  const landed = scale[REFERENCE_STEP_INDEX];
+  const requested = roundOKLCH(oklch);
+  const seedAdjusted: ColorValue['seedAdjusted'] =
+    landed && (landed.l !== requested.l || landed.c !== requested.c || landed.h !== requested.h)
+      ? {
+          from: { ...oklch },
+          to: { ...landed },
+          reason: bounded !== oklch ? 'lightness-bounds' : 'gamut',
+        }
+      : undefined;
 
   // Generate harmonies
   const harmony = generateHarmony(oklch);
 
   // WCAG accessibility (pair matrices + on-white/on-black) via the shared
-  // assembler; APCA is layered on below, builder-only.
-  const wcagAccessibility = assembleWcagAccessibility(scale, oklch);
+  // assembler, measured on the step the seed landed on (the same step
+  // rebakeAccessibility uses); APCA is layered on below, builder-only.
+  const wcagAccessibility = assembleWcagAccessibility(scale, landed ?? oklch);
   const apcaOnWhite = calculateAPCAContrast(oklch, CONTRAST_WHITE);
   const apcaOnBlack = calculateAPCAContrast(oklch, CONTRAST_BLACK);
 
@@ -115,6 +148,8 @@ export function buildColorValue(oklch: OKLCH, options: BuildColorValueOptions =
   const colorValue: ColorValue = {
     name,
     scale,
+    gamut,
+    ...(seedAdjusted && { seedAdjusted }),
     tokenId: `color-${oklch.l.toFixed(3)}-${oklch.c.toFixed(3)}-${Math.round(oklch.h)}`,
 
     // Optional metadata from options

package/src/gamut.ts

@@ -68,6 +68,109 @@ export function toNearestGamut(oklch: OKLCH): { color: OKLCH; tier: GamutTier }
   };
 }
 
+/**
+ * Whether Display P3 steps are allowed in a family. Current choice (Sean,
+ * 2026-10-17; revisable): one constant, off by default, so every family is
+ * built in sRGB until a setting exists to turn it on.
+ */
+export const ALLOW_P3 = false;
+
+/** The gamut a family is built inside: the space every one of its steps fits in. */
+export type GamutCeiling = 'srgb' | 'p3';
+
+function inCeiling(oklch: OKLCH, ceiling: GamutCeiling): boolean {
+  return new Color('oklch', [oklch.l, oklch.c, oklch.h]).inGamut(ceiling);
+}
+
+/**
+ * Map one colour into a gamut ceiling: unchanged when already inside, else
+ * colorjs.io toGamut into that space.
+ */
+export function toGamutCeiling(oklch: OKLCH, ceiling: GamutCeiling): OKLCH {
+  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
+  if (color.inGamut(ceiling)) return { ...oklch };
+  const [l, c, h] = color.toGamut({ space: ceiling }).to('oklch').coords;
+  return {
+    l: l ?? oklch.l,
+    c: c ?? 0,
+    h: h === undefined || Number.isNaN(h) ? oklch.h : h,
+    alpha: oklch.alpha,
+  };
+}
+
+/**
+ * Round a colour the way stored steps are rounded, then take chroma off in
+ * 0.001 steps until the rounded colour is inside the ceiling. Rounding hue to
+ * a whole degree and chroma to three places can carry a boundary colour back
+ * out; this keeps what is stored inside.
+ */
+function roundInside(oklch: OKLCH, ceiling: GamutCeiling): OKLCH {
+  const rounded = roundOKLCH(oklch);
+  let c = rounded.c;
+  while (c > 0 && !inCeiling({ ...rounded, c }, ceiling)) {
+    c = Math.round((c - 0.001) * 1000) / 1000;
+  }
+  return { ...rounded, c: Math.max(0, c) };
+}
+
+/** Keep the step's lightness and hue; reduce chroma only, to the ceiling's edge. */
+function reduceChromaOnly(oklch: OKLCH, ceiling: GamutCeiling): OKLCH {
+  const maxC = findMaxChroma(oklch.l, oklch.h, ceiling);
+  return roundInside({ ...oklch, c: Math.min(oklch.c, maxC) }, ceiling);
+}
+
+/**
+ * Map every step of a scale into the ceiling, keeping lightness order.
+ *
+ * A step already inside the ceiling is not moved. A step outside is mapped
+ * with colorjs.io toGamut; where that mapping would break the scale's
+ * strictly falling lightness, the step keeps its lightness and loses chroma
+ * only. Steps already inside are never re-marked, so the loop ends: at worst
+ * every outside step keeps its lightness, and the input order holds.
+ */
+export function mapScaleToGamut(scale: readonly OKLCH[], ceiling: GamutCeiling): OKLCH[] {
+  const chromaOnly = new Set<number>();
+  const mapStep = (step: OKLCH, i: number): OKLCH => {
+    if (inCeiling(step, ceiling)) return { ...step };
+    if (chromaOnly.has(i)) return reduceChromaOnly(step, ceiling);
+    return roundInside(toGamutCeiling(step, ceiling), ceiling);
+  };
+  let mapped = scale.map(mapStep);
+  for (;;) {
+    let marked = false;
+    for (let i = 1; i < mapped.length; i++) {
+      const prev = mapped[i - 1];
+      const cur = mapped[i];
+      if (prev === undefined || cur === undefined || cur.l < prev.l) continue;
+      for (const j of [i - 1, i]) {
+        const original = scale[j];
+        if (original && !chromaOnly.has(j) && !inCeiling(original, ceiling)) {
+          chromaOnly.add(j);
+          marked = true;
+        }
+      }
+    }
+    if (!marked) return mapped;
+    mapped = scale.map(mapStep);
+  }
+}
+
+/**
+ * The ceiling a family is built inside, set by its seed: 'p3' only when the
+ * seed is a Display P3 colour and ALLOW_P3 is on; otherwise 'srgb'.
+ */
+export function ceilingForSeed(seed: OKLCH): GamutCeiling {
+  return ALLOW_P3 && getGamutTier(seed) === 'p3' ? 'p3' : 'srgb';
+}
+
+/**
+ * The tier of a step mapScaleToGamut returned. Every such step is inside its
+ * ceiling, which is at most Display P3, so a step outside sRGB is a P3 step.
+ */
+export function storedTier(oklch: OKLCH): GamutCeiling {
+  return isInSRGBGamut(oklch) ? 'srgb' : 'p3';
+}
+
 /**
  * Snap an OKLCH into sRGB and round it -- the shape every generated color is
  * emitted in. Lives here because both halves are gamut/conversion concerns;

package/src/harmony.ts

@@ -2,7 +2,10 @@
  * Harmony generation for design systems using pure OKLCH hue rotation.
  *
  * Rule: harmonies are PURE HUE ROTATIONS. L and C are never mutated.
- * Only H changes. Every output goes through toNearestGamut() then roundOKLCH().
+ * Only H changes. Every harmony output goes through toNearestGamut() then
+ * roundOKLCH(). The scale is different: generateOKLCHScale returns unmapped
+ * steps, and buildColorValue maps them into the family's ceiling with
+ * mapScaleToGamut (gamut.ts).
  */
 
 import type { ColorHarmonies, OKLCH } from '@rafters/shared';
@@ -111,6 +114,17 @@ function validateScaleGeneration(baseColor: OKLCH): {
   return { isValid: true };
 }
 
+/**
+ * The seed a scale is actually built from: unchanged inside the lightness
+ * bounds, else moved to the suggested lightness (0.7 or 0.4). Exposed so
+ * buildColorValue can record the move instead of making it in silence.
+ */
+export function boundSeedLightness(baseColor: OKLCH): OKLCH {
+  const validation = validateScaleGeneration(baseColor);
+  if (validation.isValid || validation.suggestedLightness === undefined) return baseColor;
+  return { ...baseColor, l: validation.suggestedLightness };
+}
+
 /**
  * Generate lightness progression using mathematical functions.
  * Base color positioned at 600, with 6 lighter steps above + 4 darker + 950.
@@ -160,14 +174,8 @@ function generateLightnessProgression(baseLightness: number): Record<string, num
  * Chroma reduced only at extreme lightness to avoid perceptual artifacts.
  */
 export function generateOKLCHScale(baseColor: OKLCH): Record<string, OKLCH> {
-  const validation = validateScaleGeneration(baseColor);
-
-  if (!validation.isValid) {
-    const adjustedColor = validation.suggestedLightness
-      ? { ...baseColor, l: validation.suggestedLightness }
-      : baseColor;
-    return generateOKLCHScale(adjustedColor);
-  }
+  const bounded = boundSeedLightness(baseColor);
+  if (bounded !== baseColor) return generateOKLCHScale(bounded);
 
   const lightnessSteps = generateLightnessProgression(baseColor.l);
 

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   calculateAPCAContrast,
   calculateWCAGContrast,
   generateAccessibilityMetadata,
+  REFERENCE_STEP_INDEX,
   rebakeAccessibility,
 } from './accessibility.js';
 
@@ -42,12 +43,16 @@ export {
 
 // Gamut
 export {
+  ALLOW_P3,
   computeGamutBoundaries,
   type GamutBoundaryPoint,
+  type GamutCeiling,
   type GamutTier,
   getGamutTier,
   isInP3Gamut,
   isInSRGBGamut,
+  mapScaleToGamut,
+  toGamutCeiling,
   toNearestGamut,
 } from './gamut.js';
 

package/src/semantic.ts

@@ -26,6 +26,7 @@ import type {
   SemanticColorSuggestions,
   SemanticStatusRole,
 } from '@rafters/shared';
+import { calculateWCAGContrast } from './accessibility.js';
 import { roundOKLCH } from './conversion.js';
 import { clampColor } from './gamut.js';
 import { clamp01, normalizeHue } from './internal/math.js';
@@ -56,6 +57,10 @@ export interface PairRequest {
   from: string;
   level?: 'AA' | 'AAA';
   dark?: boolean;
+  /** ring only: the colour the ring sits on (the mode's background). */
+  surface?: OKLCH;
+  /** foreground only: the family to fall back to when no in-family pair meets AA (the neutral family). */
+  fallback?: ColorValue;
 }
 
 export interface SemanticContext {
@@ -84,7 +89,11 @@ export const STATE_USES: readonly StateUse[] = [
   'subtle',
 ];
 
-/** Rank step per state on the AAA ladder. sign: 1 for light (darker), -1 for dark (lighter). */
+/**
+ * Rank step per state on the AA ladder (steps with an in-family partner of at least 4.5:1). sign: 1 for light (darker), -1 for dark (lighter).
+ * Without a surface a ring copies its base; with one, statePair searches the
+ * whole family instead (see ringOnSurface).
+ */
 const STATE_RANK_STEP: Record<
   StateUse,
   (rank: number, ladder: readonly number[], sign: number) => number
@@ -98,6 +107,34 @@ const STATE_RANK_STEP: Record<
   subtle: (rank, _l, s) => rank - 2 * s,
 };
 
+/**
+ * States whose target is reflected back into the ladder when it would leave
+ * it: the step goes the same distance the other way, so a base at an end of
+ * the ladder never collapses onto itself. disabled and ring never step off.
+ */
+const REFLECTED_STATES: ReadonlySet<StateUse> = new Set([
+  'hover',
+  'active',
+  'focus',
+  'border',
+  'subtle',
+]);
+
+/** The minimum contrast a focus indicator needs against its surface (WCAG 2.2). */
+const RING_MIN_CONTRAST = 3;
+
+/**
+ * Bring a target rank inside a ladder of `length` rungs: reflect it about the
+ * base rank (when the state reflects), then clamp what is still outside.
+ */
+function rankInLadder(use: StateUse, baseRank: number, target: number, length: number): number {
+  const last = length - 1;
+  const inside = (rank: number): boolean => rank >= 0 && rank <= last;
+  const reflected =
+    !inside(target) && REFLECTED_STATES.has(use) ? baseRank - (target - baseRank) : target;
+  return Math.max(0, Math.min(last, reflected));
+}
+
 /** Escape hatches the generators may precompute onto a family. */
 type FamilyWithReferences = ColorValue & {
   foregroundReferences?: { auto?: { family: string; position: string } };
@@ -106,6 +143,20 @@ type FamilyWithReferences = ColorValue & {
 
 type PairMatrix = readonly (readonly number[])[];
 
+const STANDARD_RANK: Record<PairStandard, number> = { none: 0, AA: 1, AAA: 2 };
+
+/** The highest WCAG standard (normal text) a contrast ratio meets. */
+function standardFor(ratio: number): PairStandard {
+  if (ratio >= 7) return 'AAA';
+  if (ratio >= 4.5) return 'AA';
+  return 'none';
+}
+
+/** The highest WCAG standard (normal text) two colours meet, measured. */
+function standardOf(a: OKLCH, b: OKLCH): PairStandard {
+  return standardFor(calculateWCAGContrast(a, b));
+}
+
 function partnerForBase(pairs: PairMatrix | undefined, base: number): number | undefined {
   if (!pairs) return undefined;
   for (const [p1, p2] of pairs) {
@@ -257,13 +308,72 @@ export function semanticFor(family: ColorValue, options?: { name?: string }): Se
   const aaaPairs = family.accessibility?.wcagAAA?.normal;
   const aaPairs = family.accessibility?.wcagAA?.normal;
 
-  function foregroundPair(from: string, level: 'AA' | 'AAA'): Pair {
+  /** Contrast between two steps of this family, by scale index. */
+  function contrastOf(a: number, b: number): number {
+    const colorA = family.scale[a];
+    const colorB = family.scale[b];
+    if (!colorA || !colorB) return 1;
+    return calculateWCAGContrast(colorA, colorB);
+  }
+
+  /** The colour a leg names, when this context holds that family. */
+  function colorOf(leg: PairLeg): OKLCH | undefined {
+    if (leg.family !== familyName && leg.family !== family.name) return undefined;
+    const index = POSITION_TO_INDEX[leg.position];
+    return index === undefined ? undefined : family.scale[index];
+  }
+
+  /**
+   * The highest standard a pair's own two steps meet, measured on the two
+   * colours the legs resolve to. A leg whose colour this context does not
+   * hold cannot be measured, so it claims no standard.
+   */
+  function measuredStandard(fromPosition: string, to: PairLeg): PairStandard {
+    const fromColor = colorOf({ family: familyName, position: fromPosition });
+    const toColor = colorOf(to);
+    if (!fromColor || !toColor) return 'none';
+    return standardOf(fromColor, toColor);
+  }
+
+  /**
+   * The fallback family's step with the highest contrast against this
+   * family's step at `base`, labelled by its measured standard.
+   */
+  function fallbackForeground(from: string, base: number, fallback: ColorValue): Pair {
+    const baseColor = family.scale[base];
+    let bestIndex = -1;
+    let bestRatio = 0;
+    for (let index = 0; index < fallback.scale.length; index++) {
+      const candidate = fallback.scale[index];
+      if (!baseColor || !candidate) continue;
+      const ratio = calculateWCAGContrast(baseColor, candidate);
+      if (ratio > bestRatio) {
+        bestRatio = ratio;
+        bestIndex = index;
+      }
+    }
+    if (bestIndex === -1) {
+      throw new SemanticSelectionError(
+        familyName,
+        `has no step at ${from}, or fallback "${fallback.name}" has no steps`,
+      );
+    }
+    return {
+      from: { family: familyName, position: from },
+      to: { family: fallback.name, position: requirePosition(bestIndex, fallback.name) },
+      standard: standardFor(bestRatio),
+      tier: 'pair-nearest',
+    };
+  }
+
+  function foregroundPair(from: string, level: 'AA' | 'AAA', fallback?: ColorValue): Pair {
     const auto = refs.foregroundReferences?.auto;
     if (auto) {
+      const to = { family: auto.family, position: auto.position };
       return {
         from: { family: familyName, position: from },
-        to: { family: auto.family, position: auto.position },
-        standard: level,
+        to,
+        standard: measuredStandard(from, to),
         tier: 'reference',
       };
     }
@@ -272,52 +382,115 @@ export function semanticFor(family: ColorValue, options?: { name?: string }): Se
     const aaa = exactAAA ?? nearestPartner(aaaPairs, base);
     const exactAA = partnerForBase(aaPairs, base);
     const aa = exactAA ?? nearestPartner(aaPairs, base);
-    const partner = level === 'AAA' ? (aaa ?? aa) : aa;
-    if (partner === undefined) {
+
+    // Candidates in the order they are tried: the AAA matrix's partner (when
+    // AAA is asked for), then the AA matrix's.
+    const candidates: { partner: number; exact: boolean }[] = [];
+    if (level === 'AAA' && aaa !== undefined) {
+      candidates.push({ partner: aaa, exact: exactAAA !== undefined });
+    }
+    if (aa !== undefined) candidates.push({ partner: aa, exact: exactAA !== undefined });
+    if (candidates.length === 0) {
       throw new SemanticSelectionError(
         familyName,
         `has no WCAG pair partner for position ${from} (accessibility metadata required)`,
       );
     }
-    const fromAAA = level === 'AAA' && aaa !== undefined;
+
+    const measured = candidates.map((candidate) => ({
+      ...candidate,
+      ratio: contrastOf(base, candidate.partner),
+    }));
+    const targets: readonly PairStandard[] = level === 'AAA' ? ['AAA', 'AA'] : ['AA'];
+    const passing = targets
+      .map((target) =>
+        measured.find((m) => STANDARD_RANK[standardFor(m.ratio)] >= STANDARD_RANK[target]),
+      )
+      .find((m) => m !== undefined);
+    // No in-family pair meets AA: the fallback family (the neutral) serves.
+    if (!passing && fallback) return fallbackForeground(from, base, fallback);
+    const chosen = passing ?? measured.reduce((best, m) => (m.ratio > best.ratio ? m : best));
     return {
       from: { family: familyName, position: from },
-      to: { family: familyName, position: requirePosition(partner, familyName) },
-      standard: fromAAA ? 'AAA' : 'AA',
-      tier: (fromAAA ? exactAAA : exactAA) !== undefined ? 'pair-exact' : 'pair-nearest',
+      to: { family: familyName, position: requirePosition(chosen.partner, familyName) },
+      standard: standardFor(chosen.ratio),
+      tier: chosen.exact ? 'pair-exact' : 'pair-nearest',
     };
   }
 
-  function statePair(use: StateUse, from: string, dark?: boolean): Pair {
+  /**
+   * A ring that stands out from `surface`: starting at the base and moving
+   * away from the surface's lightness, the first step at least 3:1 against
+   * the surface; when no step reaches 3:1, the step with the highest contrast.
+   */
+  function ringOnSurface(from: string, surface: OKLCH): Pair {
+    const base = requireIndex(from, familyName);
+    const baseColor = family.scale[base];
+    if (!baseColor) {
+      throw new SemanticSelectionError(familyName, `has no step at ${from}`);
+    }
+    // Scale index grows darker: a surface lighter than the base sends the
+    // search toward darker steps, otherwise toward lighter ones.
+    const step = surface.l > baseColor.l ? 1 : -1;
+    const ratioAt = (index: number): number => {
+      const color = family.scale[index];
+      return color ? calculateWCAGContrast(color, surface) : 0;
+    };
+    let chosen: number | undefined;
+    for (let index = base; index >= 0 && index < family.scale.length; index += step) {
+      if (ratioAt(index) >= RING_MIN_CONTRAST) {
+        chosen = index;
+        break;
+      }
+    }
+    if (chosen === undefined) {
+      let best = base;
+      for (let index = 0; index < family.scale.length; index++) {
+        if (ratioAt(index) > ratioAt(best)) best = index;
+      }
+      chosen = best;
+    }
+    return {
+      from: { family: familyName, position: from },
+      to: { family: familyName, position: requirePosition(chosen, familyName) },
+      standard: standardFor(contrastOf(base, chosen)),
+      tier: 'ladder',
+    };
+  }
+
+  function statePair(request: PairRequest & { use: StateUse }): Pair {
+    const { use, from, dark, surface } = request;
     const precomputed = refs.stateReferences?.[use];
     if (precomputed) {
+      const to = { family: precomputed.family, position: String(precomputed.position) };
       return {
         from: { family: familyName, position: from },
-        to: { family: precomputed.family, position: String(precomputed.position) },
-        standard: 'AAA',
+        to,
+        standard: measuredStandard(from, to),
         tier: 'reference',
       };
     }
-    if (!aaaPairs || aaaPairs.length === 0) {
+    if (use === 'ring' && surface) return ringOnSurface(from, surface);
+    if (!aaPairs || aaPairs.length === 0) {
       throw new SemanticSelectionError(
         familyName,
-        'has no accessibility.wcagAAA.normal ladder (color generator must emit accessibility metadata)',
+        'has no accessibility.wcagAA.normal ladder (color generator must emit accessibility metadata)',
       );
     }
     const base = requireIndex(from, familyName);
-    const ladder = collectLadder(aaaPairs);
+    const ladder = collectLadder(aaPairs);
     const baseRank = closestRankTo(ladder, base);
     const sign = dark ? -1 : 1;
     const targetRank = STATE_RANK_STEP[use](baseRank, ladder, sign);
-    const clampedRank = Math.max(0, Math.min(ladder.length - 1, targetRank));
-    const targetIndex = ladder[clampedRank];
+    const rank = rankInLadder(use, baseRank, targetRank, ladder.length);
+    const targetIndex = ladder[rank];
     if (targetIndex === undefined) {
-      throw new SemanticSelectionError(familyName, `ladder lookup failed at rank ${clampedRank}`);
+      throw new SemanticSelectionError(familyName, `ladder lookup failed at rank ${rank}`);
     }
     return {
       from: { family: familyName, position: from },
       to: { family: familyName, position: requirePosition(targetIndex, familyName) },
-      standard: 'AAA',
+      standard: standardFor(contrastOf(base, targetIndex)),
       tier: 'ladder',
     };
   }
@@ -339,10 +512,7 @@ export function semanticFor(family: ColorValue, options?: { name?: string }): Se
     // advisory here because the cascade re-derives it as contrast against the
     // dark background. Sum-scoring let a distant fg leg drag the bg to the
     // wrong side of the scale.
-    for (const [pairs, standard] of [
-      [aaaPairs, 'AAA'],
-      [aaPairs, 'AA'],
-    ] as const) {
+    for (const pairs of [aaaPairs, aaPairs]) {
       if (!pairs || pairs.length === 0) continue;
       let best: { from: number; to: number; fromDist: number; toDist: number } | null = null;
       for (const [p1, p2] of pairs) {
@@ -365,7 +535,7 @@ export function semanticFor(family: ColorValue, options?: { name?: string }): Se
         return {
           from: { family: familyName, position: requirePosition(best.from, familyName) },
           to: { family: familyName, position: requirePosition(best.to, familyName) },
-          standard,
+          standard: standardFor(contrastOf(best.from, best.to)),
           tier: best.fromDist === 0 && best.toDist === 0 ? 'pair-exact' : 'pair-nearest',
         };
       }
@@ -376,7 +546,7 @@ export function semanticFor(family: ColorValue, options?: { name?: string }): Se
     return {
       from: { family: familyName, position: requirePosition(fromTarget, familyName) },
       to: { family: familyName, position: requirePosition(toFallback, familyName) },
-      standard: 'none',
+      standard: standardFor(contrastOf(fromTarget, toFallback)),
       tier: 'inversion',
     };
   }
@@ -384,12 +554,15 @@ export function semanticFor(family: ColorValue, options?: { name?: string }): Se
   return {
     pair(request: PairRequest): Pair {
       const level = request.level ?? 'AAA';
-      if (request.use === 'foreground') return foregroundPair(request.from, level);
-      return statePair(request.use, request.from, request.dark);
+      const { use } = request;
+      if (use === 'foreground') return foregroundPair(request.from, level, request.fallback);
+      return statePair({ ...request, use });
     },
     states(from: string, dark?: boolean): Record<StateUse, Pair> {
       const out = {} as Record<StateUse, Pair>;
-      for (const use of STATE_USES) out[use] = statePair(use, from, dark);
+      for (const use of STATE_USES) {
+        out[use] = statePair({ use, from, ...(dark === undefined ? {} : { dark }) });
+      }
       return out;
     },
     invert,