@adea-ai/themes 0.2.0 → 0.3.0

package/src/generated/themes.ts

@@ -77,57 +77,61 @@ export const generatedThemes: readonly AdeaThemeRecord[] = Object.freeze([
     "name": "Adea Light",
     "appearance": "light",
     "colors": {
-      "background": "oklch(1 0 0)",
-      "foreground": "oklch(0.2645 0 0)",
-      "surface": "oklch(1 0 0)",
-      "surfaceElevated": "oklch(1 0 0)",
-      "surfaceHover": "oklch(0.9761 0 0)",
-      "surfaceActive": "oklch(0.9551 0 0)",
-      "border": "oklch(0.9401 0 0)",
-      "borderMuted": "oklch(0.9612 0 0)",
-      "text": "oklch(0.2645 0 0)",
-      "textMuted": "oklch(0.5417 0 0)",
-      "textSubtle": "oklch(0.5658 0 0)",
-      "accent": "oklch(0.325 0 0)",
-      "accentForeground": "oklch(0.9911 0 0)",
-      "success": "oklch(0.5244 0.1401 148.04)",
-      "warning": "oklch(0.5538 0.1207 66.44)",
-      "error": "oklch(0.5551 0.1765 30.46)",
-      "info": "oklch(0.5198 0.0936 223.13)"
+      "background": "oklch(0.933 0.016 261.79)",
+      "foreground": "oklch(0.4017 0.0285 266.52)",
+      "surface": "oklch(0.898 0.0108 261.79)",
+      "surfaceElevated": "oklch(0.868 0.0151 261.79)",
+      "surfaceHover": "oklch(0.833 0.0209 261.79)",
+      "surfaceActive": "oklch(0.798 0.0245 261.79)",
+      "border": "oklch(0.783 0.0144 261.79)",
+      "borderMuted": "oklch(0.838 0.0096 261.79)",
+      "text": "oklch(0.4017 0.0285 266.52)",
+      "textMuted": "oklch(0.4737 0.0245 265.01)",
+      "textSubtle": "oklch(0.5679 0.0216 263.92)",
+      "accent": "oklch(0.4713 0.1518 253.31)",
+      "accentForeground": "oklch(0.9513 0.0074 260.73)",
+      "success": "oklch(0.4511 0.1809 145.62)",
+      "warning": "oklch(0.4756 0.1401 79.91)",
+      "error": "oklch(0.4905 0.1626 25.78)",
+      "info": "oklch(0.5115 0.1155 202.14)"
     },
     "ansi": {
-      "black": "oklch(0.2373 0.0113 254.06)",
-      "red": "oklch(0.5054 0.1905 27.52)",
-      "green": "oklch(0.4606 0.1227 148.77)",
-      "yellow": "oklch(0.5091 0.0985 68.76)",
-      "blue": "oklch(0.4949 0.1992 260.6)",
-      "magenta": "oklch(0.4773 0.185 347.85)",
-      "cyan": "oklch(0.5198 0.0936 223.13)",
-      "white": "oklch(0.4849 0.0196 251.02)",
-      "brightBlack": "oklch(0.4849 0.0196 251.02)",
-      "brightRed": "oklch(0.5864 0.1586 23.34)",
-      "brightGreen": "oklch(0.6127 0.1559 150.57)",
-      "brightYellow": "oklch(0.6026 0.1091 71.79)",
-      "brightBlue": "oklch(0.6231 0.188 259.81)",
-      "brightMagenta": "oklch(0.5889 0.1701 345.97)",
-      "brightCyan": "oklch(0.6089 0.1109 221.72)",
-      "brightWhite": "oklch(0.2785 0.0132 253.04)"
-    },
-    "cursor": "oklch(0.2785 0.0132 253.04)",
-    "selection": "oklch(0.8363 0.081 271.45)",
+      "black": "oklch(0.3792 0.029 266.47)",
+      "red": "oklch(0.4905 0.1626 25.78)",
+      "green": "oklch(0.4511 0.1809 145.62)",
+      "yellow": "oklch(0.4756 0.1401 79.91)",
+      "blue": "oklch(0.4713 0.1518 253.31)",
+      "magenta": "oklch(0.4883 0.1668 301.69)",
+      "cyan": "oklch(0.5115 0.1155 202.14)",
+      "white": "oklch(0.7399 0.0172 262.74)",
+      "brightBlack": "oklch(0.4523 0.0352 264.13)",
+      "brightRed": "oklch(0.5574 0.1134 25.81)",
+      "brightGreen": "oklch(0.5277 0.188 145.48)",
+      "brightYellow": "oklch(0.5464 0.1386 85.24)",
+      "brightBlue": "oklch(0.5417 0.1153 246.66)",
+      "brightMagenta": "oklch(0.5565 0.1275 305.86)",
+      "brightCyan": "oklch(0.5596 0.1107 201.78)",
+      "brightWhite": "oklch(0.9513 0.0074 260.73)"
+    },
+    "cursor": "oklch(0.7337 0.0627 217.58)",
+    "selection": "oklch(0.8733 0.0164 262.75)",
     "family": "adea",
     "familyLabel": "Adea",
     "label": "Light",
-    "description": "The default light theme. A neutral ladder with a monochrome accent.",
+    "description": "The default light theme. Nord Light's cool canvas, with the same hues as Adea Dark.",
     "provenance": {
       "project": "Adea",
       "url": "https://github.com/adea-ai/themes",
-      "license": "Apache-2.0"
+      "license": "Apache-2.0",
+      "bootstrappedFrom": [
+        "Nord Light (iTerm2-Color-Schemes)",
+        "GitHub Dark Default (iTerm2-Color-Schemes)"
+      ]
     },
     "tags": [
       "light",
-      "neutral",
-      "default"
+      "default",
+      "cool"
     ]
   },
   {
@@ -630,7 +634,7 @@ export const generatedThemes: readonly AdeaThemeRecord[] = Object.freeze([
       "borderMuted": "oklch(0.3749 0.0074 232.92)",
       "text": "oklch(0.8299 0.0405 86.05)",
       "textMuted": "oklch(0.7099 0.0315 133.05)",
-      "textSubtle": "oklch(0.7447 0.0252 133.52)",
+      "textSubtle": "oklch(0.6054 0.025 166.83)",
       "accent": "oklch(0.7732 0.0906 125.78)",
       "accentForeground": "oklch(0.2799 0.0123 232.92)",
       "success": "oklch(0.7732 0.0906 125.78)",
@@ -683,15 +687,15 @@ export const generatedThemes: readonly AdeaThemeRecord[] = Object.freeze([
     "appearance": "light",
     "colors": {
       "background": "oklch(0.9371 0.0307 98.87)",
-      "foreground": "oklch(0.4754 0.0212 232.87)",
+      "foreground": "oklch(0.4114 0.0212 232.87)",
       "surface": "oklch(0.9021 0.0201 98.87)",
       "surfaceElevated": "oklch(0.8721 0.0282 98.87)",
       "surfaceHover": "oklch(0.8371 0.0394 98.87)",
       "surfaceActive": "oklch(0.8021 0.0462 98.87)",
       "border": "oklch(0.7871 0.0276 98.87)",
       "borderMuted": "oklch(0.8421 0.0184 98.87)",
-      "text": "oklch(0.4754 0.0212 232.87)",
-      "textMuted": "oklch(0.4743 0.0242 189.99)",
+      "text": "oklch(0.4114 0.0212 232.87)",
+      "textMuted": "oklch(0.4731 0.0242 189.99)",
       "textSubtle": "oklch(0.5707 0.0252 133.52)",
       "accent": "oklch(0.518 0.0915 125.92)",
       "accentForeground": "oklch(0.9879 0.0163 91.55)",
@@ -1295,15 +1299,15 @@ export const generatedThemes: readonly AdeaThemeRecord[] = Object.freeze([
     "appearance": "dark",
     "colors": {
       "background": "oklch(0.2673 0.0486 219.82)",
-      "foreground": "oklch(0.7017 0.0197 205.26)",
+      "foreground": "oklch(0.7857 0.0197 205.26)",
       "surface": "oklch(0.3023 0.0588 219.82)",
       "surfaceElevated": "oklch(0.3323 0.06 219.82)",
       "surfaceHover": "oklch(0.3673 0.06 219.82)",
       "surfaceActive": "oklch(0.4023 0.06 219.82)",
       "border": "oklch(0.4173 0.0438 219.82)",
       "borderMuted": "oklch(0.3623 0.0292 219.82)",
-      "text": "oklch(0.7017 0.0197 205.26)",
-      "textMuted": "oklch(0.7001 0.029 209.92)",
+      "text": "oklch(0.7857 0.0197 205.26)",
+      "textMuted": "oklch(0.7007 0.029 209.92)",
       "textSubtle": "oklch(0.5954 0.051 216.2)",
       "accent": "oklch(0.6437 0.1019 187.38)",
       "accentForeground": "oklch(0.2673 0.0486 219.82)",
@@ -1356,16 +1360,16 @@ export const generatedThemes: readonly AdeaThemeRecord[] = Object.freeze([
     "appearance": "light",
     "colors": {
       "background": "oklch(0.9735 0.0261 90.1)",
-      "foreground": "oklch(0.5002 0.0285 221.9)",
+      "foreground": "oklch(0.4382 0.0285 221.9)",
       "surface": "oklch(0.9385 0.0125 90.1)",
       "surfaceElevated": "oklch(0.9085 0.0187 90.1)",
       "surfaceHover": "oklch(0.8735 0.0273 90.1)",
       "surfaceActive": "oklch(0.8385 0.0332 90.1)",
       "border": "oklch(0.8235 0.0234 90.1)",
       "borderMuted": "oklch(0.8785 0.0156 90.1)",
-      "text": "oklch(0.5002 0.0285 221.9)",
-      "textMuted": "oklch(0.4999 0.0277 179.72)",
-      "textSubtle": "oklch(0.2673 0.0486 219.82)",
+      "text": "oklch(0.4382 0.0285 221.9)",
+      "textMuted": "oklch(0.4996 0.0277 179.72)",
+      "textSubtle": "oklch(0.5965 0.0272 149.41)",
       "accent": "oklch(0.5764 0.2025 355.89)",
       "accentForeground": "oklch(0.9735 0.0261 90.1)",
       "success": "oklch(0.5424 0.1508 118.6)",
@@ -1417,15 +1421,15 @@ export const generatedThemes: readonly AdeaThemeRecord[] = Object.freeze([
     "appearance": "light",
     "colors": {
       "background": "oklch(0.9135 0.0068 277.16)",
-      "foreground": "oklch(0.4661 0.1563 264.1)",
+      "foreground": "oklch(0.4021 0.1563 264.1)",
       "surface": "oklch(0.8785 0.0053 277.16)",
       "surfaceElevated": "oklch(0.8485 0.0072 277.16)",
       "surfaceHover": "oklch(0.8135 0.0098 277.16)",
       "surfaceActive": "oklch(0.7785 0.0109 277.16)",
       "border": "oklch(0.7635 0.0062 277.16)",
       "borderMuted": "oklch(0.8185 0.0041 277.16)",
-      "text": "oklch(0.4661 0.1563 264.1)",
-      "textMuted": "oklch(0.4626 0.1085 268.28)",
+      "text": "oklch(0.4021 0.1563 264.1)",
+      "textMuted": "oklch(0.4633 0.1085 268.28)",
       "textSubtle": "oklch(0.5556 0.0451 278.01)",
       "accent": "oklch(0.5001 0.1031 230.51)",
       "accentForeground": "oklch(0.9135 0.0068 277.16)",

package/src/normalize.ts

@@ -150,6 +150,15 @@ const REPAIR_BUDGET = Object.freeze({
 /** The accent preference order, best first. */
 const ACCENT_PREFERENCE = ['blue', 'magenta', 'cyan', 'green'] as const satisfies readonly AnsiKey[]
 
+/**
+ * How much stronger body text must be than the secondary rung.
+ *
+ * Small on purpose. The requirement is that the two are *distinguishable*, not that
+ * there is a wide gulf — 0.4 of a contrast ratio is a visible difference without
+ * making secondary text unnecessarily faint.
+ */
+const MINIMUM_LADDER_GAP = 0.4
+
 /** The smallest chroma a colour needs before it reads as "a colour" rather than grey. */
 const MINIMUM_ACCENT_CHROMA = 0.035
 
@@ -176,6 +185,14 @@ export interface ThemeSourceSpec {
    * on the entry that makes it.
    */
   palette?: Partial<Record<Base24Slot, string>>
+  /**
+   * Transpose the palette's hues onto the canvas.
+   *
+   * Set when a composition borrows one palette's hues for another palette's canvas.
+   * See {@link transposeHues} for why the move is common to every hue rather than
+   * applied per hue.
+   */
+  hueTranspose?: { floor: number }
   /** Which ANSI role supplies the accent, when the family's identity demands one. */
   accentSlot?: AnsiKey
   /** Explicit roles for authored themes, applied after derivation. */
@@ -666,6 +683,108 @@ function repairRole(
   return { repair: lightness, blended: false }
 }
 
+
+/**
+ * The Base24 slots that carry a hue rather than a grey.
+ *
+ * `base09` and `base0F` are included even though neither donor publishes them: they
+ * are synthesised from red and yellow, and leaving them behind would put an
+ * untransposed orange next to a transposed red.
+ */
+const CHROMATIC_SLOTS = [
+  'base08',
+  'base09',
+  'base0A',
+  'base0B',
+  'base0C',
+  'base0D',
+  'base0E',
+  'base0F',
+  'base12',
+  'base13',
+  'base14',
+  'base15',
+  'base16',
+  'base17',
+] as const satisfies readonly Base24Slot[]
+
+/** The six slots whose bright siblings make a normal/bright pair. */
+const NORMAL_HUE_SLOTS = ['base08', 'base0A', 'base0B', 'base0C', 'base0D', 'base0E'] as const
+
+/**
+ * Moves every hue in a palette by one common lightness step, so a hue set authored
+ * against one canvas becomes legible on another.
+ *
+ * This exists because a composition can put a palette's hues on somebody else's
+ * background. GitHub's dark hues measure between 2.5:1 and 4.1:1 on a light canvas —
+ * fine as accents, unusable as terminal text — and repairing each hue *independently*
+ * to the floor destroys the thing that makes an ANSI palette an ANSI palette: the
+ * bright variants would converge onto their normal siblings, because a bright variant
+ * differs from its normal one mainly in lightness and the repair would land them all
+ * on the same lightness.
+ *
+ * Moving the group by one step instead transposes the whole set: every hue keeps its
+ * angle and chroma exactly, every relative lightness is preserved, and the palette
+ * stays internally consistent. The step is the smallest one that brings every *normal*
+ * hue to the floor, measured in the canonical form the catalogue commits so that
+ * rounding cannot push one back under.
+ */
+function transposeHues(
+  themeId: string,
+  palette: Record<Base24Slot, Oklch>,
+  floor: number,
+  findings: NormalizationFinding[]
+): Partial<Record<Base24Slot, Oklch>> {
+  const background = palette.base00
+  const worst = (step: number): number =>
+    Math.min(
+      ...NORMAL_HUE_SLOTS.map((slot) =>
+        contrastRatio(canonical(shiftLightness(palette[slot], step)), background)
+      )
+    )
+
+  const initial = worst(0)
+  if (initial >= floor) return {}
+
+  // Both directions are tried, nearest first, as in `repairContrast`: a dark canvas
+  // needs its hues lightened and a light canvas needs them darkened, and a palette
+  // moved to the other kind of canvas is the whole point of the operation.
+  const step = 0.002
+  let chosen: number | undefined
+  for (let index = 1; index <= Math.floor(0.45 / step) && chosen === undefined; index += 1) {
+    for (const direction of [1, -1] as const) {
+      const candidate = step * index * direction
+      const probe = shiftLightness(palette[NORMAL_HUE_SLOTS[0]], candidate)
+      if (probe.l <= 0.02 || probe.l >= 0.98) continue
+      if (worst(candidate) >= floor) {
+        chosen = candidate
+        break
+      }
+    }
+  }
+
+  if (chosen === undefined) {
+    findings.push({
+      themeId,
+      role: 'hues',
+      kind: 'budget-exceeded',
+      message: `no single lightness step brings every hue to ${floor}:1 against the canvas`,
+    })
+    return {}
+  }
+
+  findings.push({
+    themeId,
+    role: 'hues',
+    kind: 'repaired',
+    message: `transposed all ${CHROMATIC_SLOTS.length} hue slots by ${chosen.toFixed(3)} in lightness to reach ${floor}:1 on the borrowed canvas; hue and chroma unchanged`,
+  })
+
+  return Object.fromEntries(
+    CHROMATIC_SLOTS.map((slot) => [slot, shiftLightness(palette[slot], chosen as number)])
+  ) as Partial<Record<Base24Slot, Oklch>>
+}
+
 /** The catalogued result of normalizing one source. */
 export interface NormalizedTheme {
   record: AdeaThemeRecord
@@ -699,6 +818,16 @@ export function normalizeTheme(source: ThemeSourceSpec): NormalizedTheme {
     })
   }
 
+  // The hue transpose, applied at the same stage as the corrections and for the same
+  // reason: the semantic roles derive from these slots, so transposing afterwards
+  // would leave `error` built from the untransposed red and the two disagreeing.
+  if (source.hueTranspose) {
+    const transposed = transposeHues(source.id, palette, source.hueTranspose.floor, findings)
+    for (const [slot, value] of Object.entries(transposed)) {
+      palette[slot as Base24Slot] = value
+    }
+  }
+
   const background = palette.base00
 
   const appearance: ThemeAppearance = ladderDirection(background) === 1 ? 'dark' : 'light'
@@ -770,7 +899,7 @@ export function normalizeTheme(source: ThemeSourceSpec): NormalizedTheme {
   // OKLCH rather than alpha-compositing keeps the result a real colour that CSS can
   // use without a backdrop.
   const mutedRepair = repairAcrossSurfaces(
-    mix(palette.base05, background, 0.32),
+    mix(textRepair.color, background, 0.32),
     surfaces,
     CONTRAST_FLOORS.textMuted,
     0.3
@@ -779,15 +908,50 @@ export function normalizeTheme(source: ThemeSourceSpec): NormalizedTheme {
   colors.textMuted = muted.value
   if (muted.finding) findings.push(muted.finding)
 
-  const subtleRepair = repairAcrossSurfaces(
+  /*
+   * The ladder is derived in order — body, secondary, tertiary — and each rung is
+   * held to being dimmer than the one above it.
+   *
+   * Sourcing the tertiary rung from `base03` is faithful to Base24, which defines that
+   * slot as comments and invisibles, and for most palettes it is exactly right: the
+   * value the author chose for dim text. But a few publish a `base03` that is not a dim
+   * grey at all — Solarized's light scheme carries its near-black `base03`, Nord Light's
+   * is a mid slate — and taking it on trust produced a *tertiary* role that was the
+   * most prominent text on the screen, at 13.9:1 against a canvas whose body text
+   * measures 5.5:1. So the slot is used when it cooperates and a blend replaces it when
+   * it does not, and either way the rung is reported.
+   */
+  const mutedContrast = contrastRatio(mutedRepair.color, background)
+  const fromPalette = repairAcrossSurfaces(
     palette.base03,
     surfaces,
     CONTRAST_FLOORS.textSubtle,
     0.3
   )
+  const paletteSubtleContrast = contrastRatio(fromPalette.color, background)
+
+  const subtleFromPalette = paletteSubtleContrast < mutedContrast
+  const subtleRepair =
+    subtleFromPalette
+      ? fromPalette
+      : repairAcrossSurfaces(
+          mix(textRepair.color, background, 0.55),
+          surfaces,
+          CONTRAST_FLOORS.textSubtle,
+          0.3
+        )
+
   const subtle = emit(source.id, 'textSubtle', subtleRepair, CONTRAST_FLOORS.textSubtle)
   colors.textSubtle = subtle.value
   if (subtle.finding) findings.push(subtle.finding)
+  if (!subtleFromPalette) {
+    findings.push({
+      themeId: source.id,
+      role: 'textSubtle',
+      kind: 'substituted',
+      message: `base03 measures ${paletteSubtleContrast.toFixed(1)}:1, no dimmer than textMuted's ${mutedContrast.toFixed(1)}:1, so the tertiary rung is a blend rather than the palette's comment colour`,
+    })
+  }
 
   /**
    * The status roles, each with fallback candidates.
@@ -803,6 +967,39 @@ export function normalizeTheme(source: ThemeSourceSpec): NormalizedTheme {
    * The order is not "brightest first" — on a light canvas the bright variants are
    * worse, so the declared ANSI colour is always tried before its bright sibling.
    */
+  /*
+   * Body text gets enough headroom above the secondary rung to stay the stronger of the
+   * two.
+   *
+   * The secondary rung is repaired against the *raised* surfaces, which is the binding
+   * constraint, so on a palette whose foreground is itself only a little above the floor
+   * the repair can push secondary text past the body text — Tokyo Night Day came out
+   * with 5.6:1 for a caption and 5.5:1 for the paragraph, which collapses the two roles
+   * into one. The fix is to give the body text room rather than to weaken the secondary
+   * floor, and it is a small move: the foreground is already above its own floor, so this
+   * only ever fires on a palette that was already tight.
+   */
+  const bodyContrast = contrastRatio(textRepair.color, background)
+  const mutedAgainstCanvas = contrastRatio(mutedRepair.color, background)
+  if (mutedAgainstCanvas + MINIMUM_LADDER_GAP > bodyContrast) {
+    const lifted = repairAcrossSurfaces(
+      textRepair.color,
+      surfaces,
+      mutedAgainstCanvas + MINIMUM_LADDER_GAP,
+      REPAIR_BUDGET.text
+    )
+    if (lifted.satisfied) {
+      colors.text = formatOklch(lifted.color)
+      colors.foreground = colors.text
+      findings.push({
+        themeId: source.id,
+        role: 'text',
+        kind: 'repaired',
+        message: `lightness moved a further ${lifted.delta.toFixed(3)} so body text (${lifted.ratio.toFixed(1)}:1) stays clear of the secondary rung (${mutedAgainstCanvas.toFixed(1)}:1)`,
+      })
+    }
+  }
+
   const statusCandidates = {
     error: [palette.base08, palette.base12],
     success: [palette.base0B, palette.base14],
@@ -913,13 +1110,25 @@ export function normalizeTheme(source: ThemeSourceSpec): NormalizedTheme {
   colors.accentForeground = formatOklch(accentForeground.value)
   findings.push(...accentForeground.findings)
 
-  // The selection is the palette's own, repaired only if it is invisible against
-  // the canvas. Adapters handle making text legible on top of it.
-  const selectionSource = source.selection
-    ? (palette.base02 as Oklch)
-    : (palette.base02 as Oklch)
+  /*
+   * The selection is the palette's own where the source declares one, and the floor
+   * applies to it either way.
+   *
+   * A composition can carry its structure donor's selection explicitly, and taking that
+   * on trust is how Adea Light shipped a selection measuring 1.11:1 against its own
+   * canvas — Nord's is deliberately subtle, and subtle is not the same as invisible. An
+   * invisible selection is a functional defect rather than a matter of taste: the user
+   * cannot see what they have selected. So the declared value is used as given and still
+   * measured, and moving it is reported.
+   *
+   * The cursor is deliberately *not* treated this way. It has no floor — a cursor is an
+   * affordance rather than text, and several palettes in the catalogue give it a colour
+   * of its own — so the adapters derive a legible glyph for it instead
+   * (see `adapters/xterm.ts`).
+   */
+  const declaredSelection = source.selection ? parseColor(source.selection) : undefined
   const selectionRepair = repairContrast(
-    selectionSource,
+    declaredSelection ?? (palette.base02 as Oklch),
     background,
     CONTRAST_FLOORS.selection,
     0.5
@@ -952,9 +1161,9 @@ export function normalizeTheme(source: ThemeSourceSpec): NormalizedTheme {
       cursor: source.cursor
         ? authoredColor(source.id, 'cursor', source.cursor)
         : formatOklch(palette.base05),
-      selection: source.selection
-        ? authoredColor(source.id, 'selection', source.selection)
-        : selection.value,
+      // The repaired value, not the declared one: `selectionRepair` above started from
+      // whatever the source declared.
+      selection: selection.value,
       family: source.family,
       familyLabel: source.familyLabel,
       label: source.label,

package/src/oklch.ts

@@ -199,20 +199,6 @@ export function formatOklch(color: Oklch): string {
   return `oklch(${l} ${c} ${h})`
 }
 
-/**
- * The colour as it will actually be written.
- *
- * Repairs must be measured against this rather than against their own working
- * value. {@link formatOklch} rounds lightness to four decimals, and rounding can
- * move a pairing from 4.5001:1 to 4.4998:1 — so a repair that converges on the
- * exact floor and is then rounded ships a value that fails the floor it was
- * computed to satisfy. Measuring the canonical form closes that gap by making the
- * thing measured and the thing committed the same thing.
- */
-export function canonical(color: Oklch): Oklch {
-  return parseColor(formatOklch(color)) ?? color
-}
-
 /**
  * Relative luminance of an sRGB colour, per WCAG 2.1.
  *
@@ -244,6 +230,20 @@ export function contrastDirection(foreground: Oklch, background: Oklch): 1 | -1
   return foreground.l >= background.l ? 1 : -1
 }
 
+/**
+ * The colour as it will actually be written.
+ *
+ * Repairs must be measured against this rather than against their own working
+ * value. {@link formatOklch} rounds lightness to four decimals, and rounding can
+ * move a pairing from 4.5001:1 to 4.4998:1 — so a repair that converges on the
+ * exact floor and is then rounded ships a value that fails the floor it was
+ * computed to satisfy. Measuring the canonical form closes that gap by making the
+ * thing measured and the thing committed the same thing.
+ */
+export function canonical(color: Oklch): Oklch {
+  return parseColor(formatOklch(color)) ?? color
+}
+
 export type ContrastRepair = {
   color: Oklch
   ratio: number
@@ -274,7 +274,12 @@ export function repairContrast(
   minimum: number,
   budget = 0.22
 ): ContrastRepair {
-  const initial = contrastRatio(foreground, background)
+  // Measured in the canonical form, for the reason {@link canonical} gives: the caller
+  // commits `formatOklch`'s rounded output, and a repair that converges on the exact
+  // floor of an unrounded value ships a value that fails it. The lower a floor is, the
+  // more this matters, and the scale starts at 1.2:1 — so a selection colour's whole
+  // range is a few rounding steps wide.
+  const initial = contrastRatio(canonical(foreground), background)
   if (initial >= minimum) {
     return { color: foreground, ratio: initial, delta: 0, satisfied: true }
   }
@@ -292,10 +297,10 @@ export function repairContrast(
     for (const direction of [preferred, -preferred] as const) {
       const candidate: Oklch = { ...foreground, l: foreground.l + direction * step * index }
       if (candidate.l <= 0 || candidate.l >= 1) continue
-      const ratio = contrastRatio(candidate, background)
+      const ratio = contrastRatio(canonical(candidate), background)
       if (ratio >= minimum) {
         return {
-          color: candidate,
+          color: canonical(candidate),
           ratio,
           delta: Number((step * index).toFixed(4)),
           satisfied: true,