Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(picker): build chips per palette — tint on light, saturated on dark

Jack Rudenko1dc7559f701a
diff --git a/ai-docs/architecture/theming.md b/ai-docs/architecture/theming.md
index da84ad25..e4d2c27b 100644
--- a/ai-docs/architecture/theming.md
+++ b/ai-docs/architecture/theming.md
@@ -54,12 +54,17 @@ add-wizard is an absolute overlay that relies on it to occlude the list beneath.
Matching the terminal exactly is how the page becomes invisible while remaining
opaque.
-ONLY `bg` is adopted. `bgAlt` / `bgHighlight` / `bgError` stay from the palette:
-they are panel and selection washes that must remain *distinguishable from* the
-page, and deriving them from an arbitrary terminal colour is a separate problem
-with its own contrast risk. Safe by construction: the mode was classified from
-THIS colour's luminance, so the palette's foregrounds were already chosen
-against it.
+`bg` is adopted, and the NEUTRAL SURFACES move with it — `retintSurfaces`
+transplants each one's per-channel offset from the palette's own page onto the
+real one, so `bgAlt` on a cream terminal becomes a deeper cream rather than a
+grey slab floating on it. `SURFACE_TOKENS` is that list, and it now includes the
+quiet chip fills, which are near-background by construction (see the chip
+section below).
+
+`bgHighlight` / `bgError` and the SIGNAL fills stay from the palette: they carry
+their meaning in their HUE, and re-tinting them would erase the signal they exist
+to send. Safe by construction: the mode was classified from THIS colour's
+luminance, so the palette's foregrounds were already chosen against it.
(`claudeup` in magus-src solves the same problem by painting no page at all —
"accents are chosen to clear 3:1 against both backgrounds, and body text uses
@@ -143,29 +148,88 @@ Prices are printed in body ink. Green is this palette's "ok", the figures are
facts rather than verdicts, and the FREE badge two rows above already says free
in colour.
-## The band an OWNED FILL may occupy is 1.26:1 wide, so the second axis is chroma
-
-Every chip claudish paints is measured against BOTH `CONTRAST_REFERENCE` pages
-(`#FAFAD2`, `#1C1C1E`) at 3:1, and carries white `C.ink` at 4.5:1. Those three
-constraints pin the fill's relative luminance into `L ∈ [0.1351, 0.1833]` — the
-floor is 3:1 on near-black, the ceiling is white ink at 4.5:1 — which is a total
-range of 1.26:1. Two consequences, both of which have now cost a round each:
-
-- **A fill cannot be made "softer" by darkening it.** `C.pillKeyBg` was `#15803d`
- and the owner's verdict as an AREA was "not as bright… softer". Anything
- visibly darker drops under 3:1 on a dark terminal, which is the same defect the
- hex before it (`#2d6e3e`, 2.76:1) shipped. What IS free is saturation:
- `#3f7752` is the same lightness class at CIELAB C* 31.2 instead of 52.5, and
- its page ratios move 4.70/3.39 → 4.95/3.22. Softness is chroma here.
-- **Two fills cannot be told apart by contrast ratio.** The picker's billing
- column now fills every row — `SUB`/`local` positive, `$` neutral — so the
- design depends on the two reading as different. Inside that band they can
- differ in WCAG terms by almost nothing (`#3f7752` vs `#6b7280` is 1.09:1), so
- the assertion is perceptual: ΔE76 ≥ 20 and the neutral at under half the
- positive's chroma, in `theme-contrast.test.ts` alongside a CIELAB helper
- written out independently for the same reason the luminance formula is.
-
-A column of identical fills still fuses — that rule is unchanged, and is why a
-scoped flat-rate roster draws its repeated `SUB` as text (`priceVaries`). What
-changed is the finding that ALTERNATING fills do not, provided the alternation is
-measured rather than assumed.
+## A chip is a CONSTRUCTION, and the page picks which one — superseded, 2026-09-12
+
+**This section replaces the one that preceded it, which is kept below the rule as
+the measurement that forced the change.** The old rule was: one hex per chip,
+measured against BOTH `CONTRAST_REFERENCE` pages at 3:1, carrying white `C.ink`.
+It is gone. What replaces it is two palettes that build a chip *differently*, and
+a gate that measures each against its own page.
+
+### The old rule's arithmetic was correct and its premise was not
+
+3:1 on both pages plus white ink at 4.5:1 pins a fill's relative luminance into
+`L ∈ [0.1351, 0.1833]` — a range of **1.26:1**. So every chip, whatever it meant,
+was forced to be a mid-dark saturated block. The premise justifying that was
+"detection can fail, so a light fill may land on a dark terminal". It cannot:
+`applyTuiTheme` resolves an unknown OSC answer to DARK and never to LIGHT, so a
+light-palette fill is only ever painted on a page we measured and found light.
+The cost was real and the protection was not.
+
+Two rounds were spent inside that band before the constraint itself was
+questioned — a cheap lesson to re-learn, so it is written down here rather than
+in the file.
+
+### What the two palettes now do
+
+| | fill | ink | why |
+|---|---|---|---|
+| **dark** | SATURATED (`pillKeyBg` `#2f8250`) | light (`#ffffff`) | against near-black a colour must bring its own light |
+| **light** | pale TINT of the hue (`#BCE5CD`) | DEEP ink of the SAME hue (`#166534`) | against white a saturated fill is a glaring block |
+
+The owner's two verdicts, in order, are the whole derivation: *"this one is ugly
+for light theme"*, then — after the first fix dropped each hue to its deep
+sibling but kept the dark palette's saturated SHAPE — *"sub has a super green for
+light theme background, that should be not as bright"*. Dropping the hue was not
+enough, because the defect was never the hue. madbench's `internal/tui/theme.go`
+states the same rule one level up: neon reads as brightness against black and as
+glare against white.
+
+**A tint is not a weaker chip; it moves the contrast from the fill to the ink.**
+`SUB` on a light page prints `#166534` at 5.17:1 — text-grade — on a field that
+is only 1.38:1 off white. The old construction had it backwards: it spent all the
+contrast on the block and then had to print white on it.
+
+### Roles, because one bar for everything is what produced the glare
+
+- **SIGNAL** (`pillKeyBg`, `pillOauthBg`, `tabActiveBg`, `red`) — 3:1 against its
+ own palette's reference page.
+- **QUIET** (`pillMutedBg`, both keycap segments) — a near-background fill, and
+ the bar is a FLOOR *and a CEILING*: perceptible (≥ 1.10:1 off the page and off
+ the `bgAlt` panel) and never louder than 3:1. The ceiling is the gate nobody
+ had — a purple keycap at 5.04:1 on cream passed every earlier test, because
+ "too loud" had not been written down as a failure.
+- **Ink** is text-grade (4.5:1) on every chip, under both constructions. That is
+ the one bar that did not move.
+
+Quiet fills are also in `SURFACE_TOKENS`: a near-background fill IS a surface, so
+it must be re-tinted onto a cream terminal exactly as `bgAlt` is. They joined that
+list only when they stopped being saturated blocks.
+
+### Two fills still cannot be told apart by contrast ratio
+
+The picker's billing column fills every row — `SUB`/`local` signal, `$` quiet —
+so the design depends on the two reading as different, and under the tinted
+construction they sit within 0.1 of each other in luminance. The assertion is
+therefore perceptual and it matters MORE than before, not less: ΔE76 ≥ 20 (light
+measures 22.7, dark 54.6) and the quiet fill at under half the signal's chroma,
+in `theme-contrast.test.ts` alongside a CIELAB helper written out independently
+for the same reason the luminance formula is.
+
+A column of identical fills still fuses — unchanged, and why a scoped flat-rate
+roster draws its repeated `SUB` as text (`priceVaries`). ALTERNATING fills do
+not, provided the alternation is measured rather than assumed.
+
+### A keycap is a PILL of two segments
+
+`[ esc ][ quit ]` — the key segment brighter, the label segment quieter, the two
+abutting with no cell between the fills. A single filled block beside bare text
+is not a chip, and the two earlier answers were the same mistake from opposite
+ends: one neutral grey for both themes (1.50:1 on dark, invisible) and then one
+vivid purple for both (5.38:1 on light, the loudest thing on the screen). Both
+failed because one hex served two pages.
+
+The pill costs one cell more per hint than the block did, which is not free:
+`Hints` sets `overflow="hidden"`, so at 80 columns the six-hint footer silently
+clipped to `esc provider`. `hintsWidth` exists so that budget is arithmetic with
+a test rather than a screenshot, and two labels were shortened to pay for it.
diff --git a/packages/cli/src/picker/ModelPicker.test.tsx b/packages/cli/src/picker/ModelPicker.test.tsx
index fa9c927f..74f48537 100644
--- a/packages/cli/src/picker/ModelPicker.test.tsx
+++ b/packages/cli/src/picker/ModelPicker.test.tsx
@@ -35,7 +35,8 @@ import type { ModelInfo, PickerDiscoveryOutcome } from "../model-selector.js";
import type { DescriptionIndex } from "../providers/model-descriptions.js";
import { C } from "../tui/theme.js";
import { ModelPicker } from "./ModelPicker.js";
-import { MAX_DIALOG_ROWS } from "./layout.js";
+import { type Hint, hintsWidth } from "./chrome.js";
+import { MAX_DIALOG_ROWS, deriveDialogLayout } from "./layout.js";
import { CHIP_FILL_CELLS } from "./rows.js";
import type { PickerDataSource, PickerProviderChoice } from "./PickerDataSource.js";
@@ -324,13 +325,82 @@ describe("the dialog", () => {
}
await d.press(["a"]);
await d.until(listPainted);
- for (const hint of ["move", "select", "filter", "custom", "providers"]) {
+ for (const hint of ["move", "select", "filter", "custom", "back"]) {
expect(footer()).toContain(hint);
}
} finally {
d.destroy();
}
});
+
+ test("THE SIX-PILL FOOTER — the widest row any screen builds — is unclipped at 80", async () => {
+ // THE TEST ABOVE CANNOT CATCH THIS. It renders `hasDiscovery: false`, so `r
+ // retry` is absent and the row is FIVE pills. The row that actually overflowed is
+ // the six-pill one a DISCOVERY provider draws: it rendered `esc provider` at 80
+ // columns and nothing reported it, because `Hints` sets `overflow="hidden"` and a
+ // dropped cell is not an error. A screenshot found it, which is the wrong place
+ // to find arithmetic.
+ //
+ // The pill construction is what made the row expensive — each hint went from
+ // `key + label + 3` cells to `key + label + 4`, six of them — and the next hint
+ // anyone adds will cost the same.
+ const d = await draw(
+ <ModelPicker
+ source={fakeSource({ roster: [provider({ hasDiscovery: true })], served: [model()] })}
+ onDone={() => {}}
+ />
+ );
+ try {
+ await d.until(providerListPainted);
+ await d.press(["RETURN"]);
+ await d.until(listPainted);
+ const footer = painted(d.recapture().text).at(-2) ?? "";
+ // `r retry` proves this really is the six-pill row and not the five-pill one.
+ for (const hint of ["move", "select", "filter", "retry", "custom", "back"]) {
+ expect({ hint, footer, present: footer.includes(hint) }).toEqual({
+ hint,
+ footer,
+ present: true,
+ });
+ }
+ } finally {
+ d.destroy();
+ }
+
+ // AND THE BUDGET IS GENUINELY TIGHT — the half that stops the fit above from
+ // being a coincidence. These are the two labels the rows gave up to pay for the
+ // pills; each one, put back, overflows the dialog's inner width on its own.
+ const inner = deriveDialogLayout(80, 24).inner;
+ const withLabel = (hints: Hint[], key: string, label: string): Hint[] =>
+ hints.map((h) => (h.key === key ? { ...h, label } : h));
+ const providerList: Hint[] = [
+ { key: "↑↓", label: "move" },
+ { key: "⏎", label: "open" },
+ { key: "a", label: "all models" },
+ { key: "k", label: "show" },
+ { key: "c", label: "custom" },
+ { key: "esc", label: "quit" },
+ ];
+ const scopedList: Hint[] = [
+ { key: "↑↓", label: "move" },
+ { key: "⏎", label: "select" },
+ { key: "/", label: "filter" },
+ { key: "r", label: "retry" },
+ { key: "c", label: "custom" },
+ { key: "esc", label: "back" },
+ ];
+ expect({
+ providerRowFits: hintsWidth(providerList) <= inner,
+ scopedRowFits: hintsWidth(scopedList) <= inner,
+ needsKeyWouldNotFit: hintsWidth(withLabel(providerList, "k", "needs key")) > inner,
+ providersWouldNotFit: hintsWidth(withLabel(scopedList, "esc", "providers")) > inner,
+ }).toEqual({
+ providerRowFits: true,
+ scopedRowFits: true,
+ needsKeyWouldNotFit: true,
+ providersWouldNotFit: true,
+ });
+ });
});
// ── the chips: a fill is invisible to a character frame ──────────────────────────
@@ -388,7 +458,7 @@ describe("the billing and prefix CHIPS", () => {
// picked up `pillKeyBg` would claim the route costs nothing.
expect(bgOf(chip)).not.toBe(rgb(C.pillKeyBg));
expect(bgOf(chip)).not.toBe(rgb(C.bgAlt));
- expect(chip.fg.toInts().slice(0, 3).join()).toBe(rgb(C.ink));
+ expect(chip.fg.toInts().slice(0, 3).join()).toBe(rgb(C.pillMutedFg));
}
expect(rgb(C.pillMutedBg)).not.toBe(rgb(C.pillKeyBg));
} finally {
@@ -448,9 +518,12 @@ describe("the billing and prefix CHIPS", () => {
text: `${" ".repeat(left + 1)}${label}${" ".repeat(slack - left + 1)}`,
});
}
- // A footer keycap is a DIFFERENT object with the original contract: its fill is
- // exactly `label + 2`, because a row of keys is not a column of states.
- const caps = spansOf(f).filter((sp) => bgOf(sp) === rgb(C.chipKeycapBg));
+ // A footer keycap is a DIFFERENT object with the original contract: each of the
+ // pill's two segments is exactly `text + 2`, because a row of keys is not a
+ // column of states — nothing there has to line up with anything below it.
+ const caps = spansOf(f).filter(
+ (sp) => bgOf(sp) === rgb(C.keycapKeyBg) || bgOf(sp) === rgb(C.keycapLabelBg)
+ );
expect(caps.length).toBeGreaterThan(0);
for (const sp of caps) {
expect({ text: sp.text }).toEqual({ text: ` ${sp.text.trim()} ` });
@@ -460,21 +533,38 @@ describe("the billing and prefix CHIPS", () => {
}
});
- test("A FOOTER KEYCAP IS A VIVID BLOCK WITH WHITE INK, never a grey word", async () => {
- // Grey was measured and rejected once per palette — 1.50:1 on a dark page,
- // 2.38:1 on a light one — so on whichever terminal it was not tuned for the key
- // melted into the background. `captureCharFrame` reads ` k ` either way; only
- // the fill says whether it reads as a key you press.
+ test("A FOOTER KEYCAP IS A TWO-SEGMENT PILL — key filled, label filled, no gap", async () => {
+ // The owner asked for chips, twice. First the key was a grey word (1.50:1 on a
+ // dark page, 2.38:1 on a light one — invisible on whichever terminal it was not
+ // tuned for), then a lone purple block beside bare text. What he asked for is one
+ // pill of two halves: *"the key itself brighter colour and label has backdrop but
+ // not as bright"*.
+ //
+ // `captureCharFrame` reads ` esc quit ` under every one of those builds. Only
+ // the FILLS say whether it is a pill, and only their ADJACENCY says whether it is
+ // one object or two — which is why this asserts the two segments touch.
const d = await draw(<ModelPicker source={fakeSource({ roster })} onDone={() => {}} />);
try {
await d.until(providerListPainted);
- const caps = labelled(d.recapture().frame, "esc");
+ const f = d.recapture().frame;
+ const caps = labelled(f, "esc");
expect(caps.length).toBeGreaterThan(0);
for (const cap of caps) {
- expect(bgOf(cap)).toBe(rgb(C.chipKeycapBg));
+ expect(bgOf(cap)).toBe(rgb(C.keycapKeyBg));
expect(bgOf(cap)).not.toBe(rgb(C.chipKeyBg));
- expect(cap.fg.toInts().slice(0, 3).join()).toBe(rgb(C.ink));
+ expect(cap.fg.toInts().slice(0, 3).join()).toBe(rgb(C.keycapKeyFg));
}
+ // THE SEAM. The label segment is the NEXT span after the key segment, with no
+ // unfilled span between them — a single space on the panel background there is
+ // what splits the pill into two objects, and it is invisible in a char frame.
+ const line = f.lines.find((l) => l.spans.some((sp) => sp.text.trim() === "esc"));
+ expect(line).toBeDefined();
+ const at = line!.spans.findIndex((sp) => sp.text.trim() === "esc");
+ const next = line!.spans[at + 1];
+ expect({ text: next?.text, bg: next === undefined ? null : bgOf(next) }).toEqual({
+ text: " quit ",
+ bg: rgb(C.keycapLabelBg),
+ });
} finally {
d.destroy();
}
diff --git a/packages/cli/src/picker/ModelPicker.tsx b/packages/cli/src/picker/ModelPicker.tsx
index b4934f89..74dc28fd 100644
--- a/packages/cli/src/picker/ModelPicker.tsx
+++ b/packages/cli/src/picker/ModelPicker.tsx
@@ -758,11 +758,19 @@ export function ModelPicker({ source, onDone, onDiscoveryFailure }: ModelPickerP
{ key: "↑↓", label: "move" },
{ key: "⏎", label: "open", on: here !== null },
{ key: "a", label: "all models" },
- // `keyless` SAID THE OPPOSITE OF WHAT IT MEANT. These providers need a
- // key — that is precisely why they are hidden — and "keyless" reads as
- // "no key required". The hint row above already says `need a key`, so
- // the footer now says it too, in 9 of the 76 columns 80 gives us.
- { key: "k", label: revealKeyless ? "hide" : "needs key", on: keyless.length > 0 },
+ // `show` / `hide`, NOT `needs key` — AND THE SHORTENING IS WHAT PAID FOR
+ // THE PILLS. A keycap is two filled segments now (`chrome.tsx`), which
+ // costs one cell per hint, and MEASURED at 80 columns the row ran three
+ // cells past the 72 the dialog has: `esc quit` rendered as `esc qu`.
+ //
+ // This is the label that could shrink without losing anything, because
+ // `needs key` DUPLICATED the row directly above it — `+14 more need a
+ // key · k` says the same thing one line up and says it in full. So the
+ // reason lives where there is room for it and the footer says only what
+ // the key does. (`keyless` was the label before that and said the
+ // OPPOSITE of what it meant: these providers need a key, which is
+ // precisely why they are hidden.)
+ { key: "k", label: revealKeyless ? "hide" : "show", on: keyless.length > 0 },
{ key: "c", label: "custom" },
{ key: "esc", label: "quit" },
]}
@@ -782,19 +790,23 @@ export function ModelPicker({ source, onDone, onDiscoveryFailure }: ModelPickerP
width={layout.width}
marginLeft={0}
>
+ {/* NO SECOND LINE. It said `models appear as soon as they are ready`, which
+ is a sentence about time passing: it names no operation, gives the reader
+ nothing to act on, and would be equally true of any loading screen ever
+ drawn. The owner's verdict was *"that text is silly"*.
+ The information it was standing in for is already on the frame, said
+ precisely and said live — the dialog title names the provider, `status`
+ names the operation (`finding models…`), and each `LoadTasks` row names
+ the request and its elapsed time or deadline. A line under that could
+ only repeat one of them. */}
<LoadTasks
tasks={tasks}
frame={frame}
labelWidth={14}
barWidth={Math.max(8, Math.min(22, layout.inner - 40))}
/>
- <box height={1} flexShrink={0}>
- <text>
- <span fg={tokens.trace}>models appear as soon as they are ready</span>
- </text>
- </box>
<Rule />
- <Hints hints={[{ key: "esc", label: "providers" }]} />
+ <Hints hints={[{ key: "esc", label: "back" }]} />
</Dialog>
</Centred>
);
@@ -913,7 +925,15 @@ export function ModelPicker({ source, onDone, onDiscoveryFailure }: ModelPickerP
{/* ONE KEY PER ACTION, AND EVERY ACTION IN THE ROW. `p` is gone: `esc` is
the way back to the provider list from both model lists, and a second
key for the one destination bought nothing while costing the row the
- columns `r retry` needs at 80. */}
+ columns `r retry` needs at 80.
+
+ `back`, NOT `providers`, AND THE SIX-HINT ROW IS WHY. A keycap is a pill
+ of two fills now (`chrome.tsx`) and costs one cell more per hint, so with
+ `r retry` present this row MEASURED 74 cells against the 72 the dialog has
+ at 80 columns and clipped to `esc provider` — caught in
+ `dialog7-failure-dark-80x24.png`, not by a test. `back` is already this
+ file's word for the same move (the custom dialog's `esc`), so the row now
+ uses one vocabulary and fits with three cells to spare. */}
<Hints
hints={[
{ key: "↑↓", label: "move" },
@@ -921,7 +941,7 @@ export function ModelPicker({ source, onDone, onDiscoveryFailure }: ModelPickerP
{ key: "/", label: "filter" },
...(scope !== null && hasDiscovery ? [{ key: "r", label: "retry" }] : []),
{ key: "c", label: "custom" },
- { key: "esc", label: filter !== "" ? "clear" : "providers" },
+ { key: "esc", label: filter !== "" ? "clear" : "back" },
]}
/>
</Dialog>
diff --git a/packages/cli/src/picker/chrome.tsx b/packages/cli/src/picker/chrome.tsx
index 365b159f..f630506e 100644
--- a/packages/cli/src/picker/chrome.tsx
+++ b/packages/cli/src/picker/chrome.tsx
@@ -17,10 +17,9 @@
import type { ReactNode } from "react";
import { LoadingRow } from "../tui/components/LoadingRow.js";
-import { C } from "../tui/theme.js";
+import { A, C } from "../tui/theme.js";
import { displayWidth, truncate } from "../tui/viz/text.js";
import { tokens } from "../tui/viz/tokens.js";
-import { BadgeSpan } from "../tui/viz/widgets.js";
/**
* The bordered box, with its title composed left-and-right on the border line.
@@ -156,55 +155,94 @@ export interface Hint {
}
/**
- * Keyboard hints as KEYCAPS — a badge per key, then its label in dim text.
+ * What a hint row COSTS, in cells — the arithmetic, without a renderer.
*
- * THE BADGE IS THE HOUSE PATTERN FOR A DISCRETE TOKEN: dark ink on a saturated
- * fill, one space of padding each side (`aesthetics-and-color.md`). Bold white
- * text on the panel background, which is what this row used to be, is the same
- * treatment the model ids two rows above get — so `p` in `p providers` read as a
- * word rather than as a key you press, which is exactly what the owner said when
- * he asked for "better button highlighting".
+ * IT EXISTS BECAUSE THE ROW CLIPS SILENTLY. `Hints` sets `overflow="hidden"`, so a
+ * row one cell too wide loses its last characters and nothing errors: the pill
+ * construction added one cell per hint and the six-hint failure footer rendered
+ * `esc provider` at 80 columns. That was caught in a screenshot, which is the wrong
+ * place to catch arithmetic — so the widest hint set any screen can build is now
+ * pinned against the dialog's inner width in `ModelPicker.test.tsx`.
*
- * `BadgeSpan`, NOT `Badge`: one `<text>` per hint carries both the chip and its
- * label, and a `<text>` cannot nest in a `<text>`.
+ * Each pill is ` key ` + ` label ` with NO cell between the two fills, and the parent
+ * box contributes one column of gap between pills.
+ */
+export function hintsWidth(hints: Hint[]): number {
+ if (hints.length === 0) return 0;
+ const pills = hints.reduce((sum, h) => sum + displayWidth(h.key) + displayWidth(h.label) + 4, 0);
+ return pills + (hints.length - 1);
+}
+
+/**
+ * Keyboard hints as KEYCAP PILLS — two abutting segments per hint: the key you
+ * press, then what it does.
+ *
+ * A CHIP HERE IS TWO SEGMENTS, NOT ONE BLOCK BESIDE BARE TEXT. The owner, on the
+ * shipped build: *"key suggestion, they should be like chips... the key itself
+ * brighter colour and label has backdrop but not as bright, create chips"*. So both
+ * halves are filled and the KEY half is the brighter one — it is the thing you press
+ * — with the label riding a quieter backdrop beside it:
*
- * ONE FILL FOR EVERY KEYCAP, AND IT IS VIVID — NEUTRAL GREY WAS MEASURED AND
- * REJECTED, TWICE, ONCE PER PALETTE. The argument for grey was that every hue in
- * this dialog already means something, so the quietest row should borrow none of
- * them. What that produced is a chip that is not a chip: `C.chipKeyBg` measures
- * 1.50:1 against a dark page and 2.38:1 against a light one, so on whichever
- * terminal it was not tuned for it melts into the background and the key reads as a
- * faintly tinted word. The owner reported exactly that from a live light-theme run,
- * and claudeup records the same measurement and the same conclusion — "the previous
- * neutral-grey chip melted into a light page", with dark slates rejected for
- * dropping to ~2.2 on a dark terminal.
+ * [ esc ][ quit ] [ ↑↓ ][ move ] [ a ][ all models ]
+ * ^brighter ^quieter
*
- * `C.chipKeycapBg` is purple, and purple is spent on nothing else in this program:
- * the accent is blue, failure is red, the positive family is green. So a keycap
- * cannot be mistaken for a focus ring, a status or an error, and it clears 3:1
- * against BOTH reference pages (`theme-contrast.test.ts`).
+ * THE TWO SEGMENTS MUST ABUT. One space of padding sits INSIDE each fill and there is
+ * none BETWEEN them, so the pair reads as one object with two halves; the gap that
+ * separates hints from each other is the parent box's `gap={1}`, outside both fills.
+ * A space between the backgrounds splits the pill in half and the affordance is gone.
+ * This is a sanctioned case of padding inside a fill, for the same reason `ChipCell`
+ * centres inside one: the fill IS the object here, not a highlight on a word.
*
- * `fg={C.ink}` — WHITE, explicitly, rather than `pickInk`'s answer. We choose this
- * fill, so we own its ink too, and a chip whose ink flips with the user's palette is
- * a chip with two different contrast ratios.
+ * ONE `<text>` PER HINT carries both spans — a `<text>` cannot nest in a `<text>`,
+ * and a `<span>` outside a `<text>` renders an error page while the process exits 0.
+ * This replaced `BadgeSpan`, whose `label + width` contract describes one fill.
*
- * AN UNAVAILABLE ACTION LOSES THE CHIP RATHER THAN BEING HIDDEN — dim text, no
- * fill, so "there is a key here but not now" is visibly different from both a live
- * key and an absent one. Every action is one key and every key is here.
+ * THE PILL IS QUIET, AND THE TWO EARLIER ANSWERS WERE THE SAME MISTAKE FROM OPPOSITE
+ * ENDS. First it was one neutral grey for both themes, which is a chip that is not a
+ * chip: `C.chipKeyBg` measures 1.50:1 against a dark page and 2.38:1 against a light
+ * one, so on whichever terminal it was not tuned for it melts and the key reads as a
+ * faintly tinted word — the owner reported exactly that from a live light-theme run.
+ * The fix was one VIVID purple (`#9333ea`) for both themes, which over-corrected:
+ * 5.38:1 on a light page made the footer the loudest thing on a screen whose content
+ * is a list.
+ *
+ * BOTH failures were caused by one hex serving two pages. A keycap is an AFFORDANCE —
+ * it says a key exists, not that anything is notable — so it takes madbench's
+ * near-background idiom (`paramKeyBg` / `paramValBg`: "near-bg", body ink) and it
+ * takes it TWICE, once per palette, because "a shade off the page" points up on black
+ * and down on white. MEASURED, because a pale fill does NOT survive a dark terminal:
+ * `#B8C2D8` is 1.06:1 on true black, worse than the grey already rejected. Dark gets
+ * `#474F63` / `#292D36` (2.57:1 and 1.52:1 off the page, 1.69:1 between them); light
+ * gets `#B8C2D8` / `#E4E8F2` (1.79:1 and 1.23:1, 1.46:1 between). Every one of those
+ * numbers is pinned by `theme-contrast.test.ts`, including a CEILING — the gate that
+ * would have caught the purple.
+ *
+ * THE INKS ARE STATED, never left to `pickInk`, which reads LUMINANCE alone and would
+ * flip on a near-background fill. Each palette declares fill and ink together. All
+ * four are read at RENDER time — a module-level `const` here ships one palette's
+ * whole construction to the other theme.
+ *
+ * AN UNAVAILABLE ACTION LOSES THE PILL RATHER THAN BEING HIDDEN — dim text, no fill,
+ * so "there is a key here but not now" is visibly different from both a live key and
+ * an absent one. Every action is one key and every key is here.
*/
export function Hints({ hints }: { hints: Hint[] }): ReactNode {
return (
<box flexDirection="row" height={1} gap={1} flexShrink={0} overflow="hidden">
- {hints.map((h) => (
- <text key={h.key} flexShrink={0}>
- {h.on === false ? (
- <span fg={tokens.trace}>{` ${h.key} `}</span>
- ) : (
- <BadgeSpan label={h.key} bg={C.chipKeycapBg} fg={C.ink} />
- )}
- <span fg={h.on === false ? tokens.trace : tokens.subtle}>{` ${h.label}`}</span>
- </text>
- ))}
+ {hints.map((h) =>
+ h.on === false ? (
+ <text key={h.key} flexShrink={0}>
+ {/* Same cell count as the pill it replaces, so a hint turning on and off
+ does not shuffle the row. */}
+ <span fg={tokens.trace}>{` ${h.key} ${h.label} `}</span>
+ </text>
+ ) : (
+ <text key={h.key} flexShrink={0}>
+ <span fg={C.keycapKeyFg} bg={C.keycapKeyBg} attributes={A.bold}>{` ${h.key} `}</span>
+ <span fg={C.keycapLabelFg} bg={C.keycapLabelBg}>{` ${h.label} `}</span>
+ </text>
+ )
+ )}
</box>
);
}
diff --git a/packages/cli/src/picker/row-semantics.test.ts b/packages/cli/src/picker/row-semantics.test.ts
index c77be32b..809f413d 100644
--- a/packages/cli/src/picker/row-semantics.test.ts
+++ b/packages/cli/src/picker/row-semantics.test.ts
@@ -210,9 +210,9 @@ describe("billingLabel / readinessGlyph", () => {
test("METERED IS NEUTRAL and SUB IS POSITIVE — neither is a warning", () => {
// `$` states that the route bills per token. That is information about the
// route, not a caution about it: the number that matters is on the model row.
- // Neutral is now carried by the FILL (a near-grey) rather than by the ink, which
- // is white on every chip we paint.
- expect(billingLabel("metered").fg).toBe(C.ink);
+ // Neutral is carried by the FILL — a near-background one, whose ink is the quiet
+ // tier rather than the signal's.
+ expect(billingLabel("metered").fg).toBe(C.pillMutedFg);
for (const mode of ["sub", "local", "metered"] as const) {
const tag = billingLabel(mode);
for (const colour of [tag.bg, tag.fg]) {
@@ -222,17 +222,35 @@ describe("billingLabel / readinessGlyph", () => {
}
});
- test("A FILLED CHIP CARRIES WHITE INK, in both palettes", () => {
- // We choose the fill, so we own the ink: `pickInk` would answer white on the
- // dark palette and BLACK on the light one for the same chip — one chip with two
- // inks, and the worse ratio (4.02 vs 5.02) on the lighter page.
+ test("EVERY CHIP STATES ITS OWN INK, and the ink follows the palette", () => {
+ // We choose the fill, so we own the ink: `pickInk` would answer white on the dark
+ // palette and BLACK on the light one for the same chip — one chip with two inks,
+ // and the worse ratio (4.02 vs 5.02) on the lighter page.
+ //
+ // AND THE INK IS NOT ONE COLOUR ANY MORE. The dark palette builds a chip as a
+ // saturated fill with light ink; the light palette builds it as a pale TINT with
+ // deep ink of the same hue, because a saturated block glares on a white page
+ // (`theme.ts`). So "white on everything" is exactly the rule that had to go, and
+ // what replaces it is: the ink is the fill's OWN declared partner, and the pair
+ // moves together when the theme flips.
for (const mode of ["dark", "light"] as const) {
setThemeMode(mode);
- for (const billing of ["sub", "local", "metered"] as const) {
- expect(billingLabel(billing).fg).toBe(C.ink);
- }
- expect(C.ink).toBe("#ffffff");
+ expect({
+ mode,
+ sub: billingLabel("sub").fg,
+ local: billingLabel("local").fg,
+ metered: billingLabel("metered").fg,
+ }).toEqual({ mode, sub: C.pillKeyFg, local: C.pillKeyFg, metered: C.pillMutedFg });
+ // The two tiers are never the same ink — that would erase the distinction the
+ // quiet chip exists to make.
+ expect(C.pillKeyFg).not.toBe(C.pillMutedFg);
}
+ // And the flip actually MOVED them: a light-palette `SUB` painted in the dark
+ // palette's white ink is the module-level-const bug this repo has found six times.
+ setThemeMode("dark");
+ const darkInk = billingLabel("sub").fg;
+ setThemeMode("light");
+ expect(billingLabel("sub").fg).not.toBe(darkInk);
resetThemeModeForTests();
});
diff --git a/packages/cli/src/picker/rows.tsx b/packages/cli/src/picker/rows.tsx
index f2b44b35..59e905da 100644
--- a/packages/cli/src/picker/rows.tsx
+++ b/packages/cli/src/picker/rows.tsx
@@ -40,9 +40,9 @@
* block, the inactive one is plain muted text with no background at all.
*
* `or@` / `zengo@` subtle TEXT a routing IDENTIFIER, never a status
- * `$` chip on `C.pillMutedBg` metered — the unremarkable default
- * `FREE` / `SUB` chip on `C.pillKeyBg` no per-token charge — the SAME claim
- * `local` chip on `C.pillKeyBg` no charge either, by another mechanism
+ * `$` QUIET chip, near-bg metered — the unremarkable default
+ * `FREE` / `SUB` SIGNAL chip, green no per-token charge — the SAME claim
+ * `local` SIGNAL chip, green no charge either, by another mechanism
* `catalog` warn text NOT the live roster — `DiscoveryNotice`
* `N/A` dead text the catalog does not say
* selection accent + `C.bgHighlight`, and a `▶` so it survives greyscale
@@ -60,11 +60,24 @@
* `$` and `SUB`/`local` partition the roster, so this is a fill on all 17 rows —
* exactly the shape that fused into one grey band when the PREFIX was chipped. What
* failed there was that all 17 fills were the SAME colour; here they alternate, and
- * the two fills are held apart by measurement rather than by hope: `C.pillKeyBg`
- * `#3f7752` is a green at CIELAB C* 31.2, `C.pillMutedBg` `#6b7280` a near-grey at
- * C* 8.6, ΔE76 36.5 — thirty-odd times the just-noticeable difference, and pinned by
+ * the two fills are held apart by measurement rather than by hope: ΔE76 22.7 on the
+ * light palette (`#BCE5CD` vs `#E2E6F0`) and 54.6 on the dark one (`#2f8250` vs
+ * `#2E323D`), where ~2.3 is a just-noticeable difference. Pinned by
* `theme-contrast.test.ts` so a future tweak that collapses them fails a test rather
- * than a screenshot. Verified on `dialog6-*` at 80x24 and 145x45, dark and light.
+ * than a screenshot. Verified on `dialog7-*` at 80x24 and 145x45, dark and light.
+ *
+ * THE LIGHT PAIR IS THE TIGHT ONE, AND DELIBERATELY SO. Both light chips are TINTS
+ * (see `theme.ts`), so they sit within 0.1 of each other in luminance and the whole
+ * distinction is HUE — 22.7 ΔE, ten just-noticeable differences, but a tenth of the
+ * headroom the dark pair has. That is why the banding gate matters MORE under this
+ * construction than under the saturated one it replaces, not less.
+ *
+ * AND THE QUIET HALF IS QUIET BY MEASUREMENT TOO. ΔE alone would accept two equally
+ * loud fills of different hue, which is what shipped: a mid-grey `#6b7280` slab at
+ * 4.53:1 on a light page beside a green at 4.70:1 — the same weight, so the column
+ * read as two competing claims. The gate now also pins that `$` carries less than
+ * half the CHROMA of `SUB` in whichever palette is loaded — the axis that survives
+ * both constructions, since on a light page the two tints barely differ in weight.
*
* ONE FILL WIDTH FOR THE WHOLE COLUMN, WHICH IS THE ONE PLACE PADDING GOES INSIDE A
* FILL. `aesthetics-and-color.md` forbids padding inside the label because 24 `UP`
@@ -175,11 +188,11 @@ export function priceLabel(display: string, billing: BillingMode): string {
*
* A NEON FOREGROUND IS NOT A FILL. `tokens.success` is `C.green`, `#39ff14`, and
* the skill is explicit that a colour tuned to read as text is harsh as a solid
- * block. `C.pillKeyBg` (`#3f7752`) is this repo's already contrast-tuned muted
- * green, shared verbatim by both palettes and measured against BOTH reference pages
- * (`theme-contrast.test.ts`) — and it is ALREADY the `FREE` chip on the session
- * summary card (`session-summary.ts:176`), so this is the same object, not a second
- * invention.
+ * block. `C.pillKeyBg` is this repo's contrast-tuned SIGNAL green — `#2f8250` on the
+ * dark palette and the deeper `#166534` on the light one, each measured against its
+ * own page (`theme-contrast.test.ts`) — and it is ALREADY the `FREE` chip on the
+ * session summary card (`session-summary.ts:176`), so this is the same object, not a
+ * second invention. Read at RENDER time, which is why this is a function.
*/
export function priceChipBg(label: string): string | null {
if (label === "FREE" || label === "SUB" || label === "local") return C.pillKeyBg;
@@ -227,18 +240,23 @@ export function readinessGlyph(r: Readiness): { glyph: string; fg: string } {
* `$` used to be drawn as muted text on the grounds that a fill on every row of the
* column is the banding defect; what the owner saw on the shipped screen was the
* other half of that trade — a 5-cell green chip beside a 1-cell word, so the column
- * had no edges. Two fills that are 36.5 ΔE apart alternate visibly, which a single
- * fill on every row could not. `C.pillMutedBg` is the quiet one deliberately:
- * metered is what a route IS by default, not a caution about it, and the number that
- * matters is on the model row.
+ * had no edges. Two fills 55–67 ΔE apart alternate visibly, which a single fill on
+ * every row could not.
*
- * The ink is `C.ink` on both — we chose both fills, so we own both inks, and neither
- * should change with the user's palette.
+ * THE TWO FILLS ARE NOT TWO SHADES OF ONE IDEA. `SUB`/`local` is a SIGNAL — it
+ * separates hard from the page. `$` is a NEAR-BACKGROUND fill, a measured shade off
+ * the page carrying body ink, because metered is what a route IS by default rather
+ * than a caution about it and the number that matters is on the model row. That is
+ * why each fill states its own ink: `C.pillKeyFg` on the signal, `C.pillMutedFg` on
+ * the quiet one. On DARK that is white on a saturated green; on LIGHT it is deep
+ * green on a pale green TINT, which is the inverted construction a white page needs.
+ * All four are read at RENDER time — a module-level `const` now ships not just the
+ * wrong hex but the wrong recipe to the other theme.
*/
export function billingLabel(mode: BillingMode): { text: string; fg: string; bg: string } {
- if (mode === "sub") return { text: "SUB", fg: C.ink, bg: C.pillKeyBg };
- if (mode === "local") return { text: "local", fg: C.ink, bg: C.pillKeyBg };
- return { text: "$", fg: C.ink, bg: C.pillMutedBg };
+ if (mode === "sub") return { text: "SUB", fg: C.pillKeyFg, bg: C.pillKeyBg };
+ if (mode === "local") return { text: "local", fg: C.pillKeyFg, bg: C.pillKeyBg };
+ return { text: "$", fg: C.pillMutedFg, bg: C.pillMutedBg };
}
const SPACES = " ";
@@ -265,11 +283,14 @@ const gap = (n: number): string => SPACES.slice(0, Math.max(0, n));
function ChipCell({
label,
bg,
+ fg,
width,
align = "left",
}: {
label: string;
bg: string;
+ /** The ink THIS fill carries. Required: the column's two fills take different ink. */
+ fg: string;
width: number;
align?: "left" | "right";
}): ReactNode {
@@ -284,17 +305,13 @@ function ChipCell({
return (
<>
{lead > 0 ? <span>{gap(lead)}</span> : null}
- {/* `fg={C.ink}` — WHITE, not `pickInk`'s answer. We chose this fill, so we own
- both sides of it and its ink should not change with the user's palette:
- MEASURED on the old `#15803d`, `pickInk` returned white on the dark palette
- and BLACK on the light one — the same chip wearing two inks, and the worse
- ratio (4.02 vs 5.02) on the page more likely to be squinted at. */}
- <BadgeSpan
- label={centred}
- bg={bg}
- fg={C.ink}
- {...(align === "right" ? {} : { width: cells })}
- />
+ {/* THE INK IS PASSED, never left to `pickInk`. `pickInk` picks from LUMINANCE
+ alone, and a near-background fill straddles its threshold: measured on the
+ old `#15803d` it answered white on the dark palette and BLACK on the light
+ one for the SAME hex — one chip wearing two inks, at the worse ratio (4.02
+ vs 5.02) on the page more likely to be squinted at. We chose the fill, so we
+ choose its ink, and each palette states both together. */}
+ <BadgeSpan label={centred} bg={bg} fg={fg} {...(align === "right" ? {} : { width: cells })} />
</>
);
}
@@ -399,7 +416,9 @@ export function ModelRow({
{chipBg === null ? (
<span fg={priceFg(price)}>{padStartTo(price, layout.price)}</span>
) : (
- <ChipCell label={price} bg={chipBg} width={layout.price} align="right" />
+ // `C.pillKeyFg` because `priceChipBg` only ever answers the SIGNAL fill — a
+ // price numeral is never chipped, so this column has no quiet half.
+ <ChipCell label={price} bg={chipBg} fg={C.pillKeyFg} width={layout.price} align="right" />
)}
{layout.mark > 0 ? (
<span fg={tokens.warn}>
@@ -494,9 +513,10 @@ export function ProviderRow({
<span fg={tokens.subtle}>{padTo(truncate(shortcut, L.shortcut), L.shortcut)}</span>
{/* BOTH STATES ARE CHIPS AND BOTH ARE `CHIP_FILL_CELLS` WIDE — the owner's
"make $$$ the same width and badge as well". What keeps the column from
- reading as one band is the distance between the two fills, not a gap:
- `theme-contrast.test.ts` pins it. */}
- <ChipCell label={bill.text} bg={bill.bg} width={L.billing} />
+ reading as one band is the distance between the two fills, not a gap, and
+ what keeps `$` from competing with `SUB` is that only one of them is a
+ signal: `theme-contrast.test.ts` pins both. */}
+ <ChipCell label={bill.text} bg={bill.bg} fg={bill.fg} width={L.billing} />
<span fg={readiness === "missing" ? tokens.dead : tokens.subtle}>
{padStartTo(truncate(tail, L.tail), L.tail)}
</span>
diff --git a/packages/cli/src/tui/theme-contrast.test.ts b/packages/cli/src/tui/theme-contrast.test.ts
index 50004adc..ca695ccf 100644
--- a/packages/cli/src/tui/theme-contrast.test.ts
+++ b/packages/cli/src/tui/theme-contrast.test.ts
@@ -99,20 +99,24 @@ describe("light TUI palette contrast", () => {
});
}
- const ownedFills = [
- "pillKeyBg",
- "pillMutedBg",
- "pillOauthBg",
- "tabActiveBg",
- ] as const satisfies ReadonlyArray<keyof TuiPalette>;
+ // The SATURATED fills — the ones that still carry `C.ink` (white) on this page.
+ // The picker's status chips are NOT here any more: on a light page they are tints
+ // with deep ink, and each states its own ink. They are measured as pairs in
+ // `every chip is a fill AND its ink` below.
+ const whiteInkFills = ["pillOauthBg"] as const satisfies ReadonlyArray<keyof TuiPalette>;
- for (const fill of ownedFills) {
+ for (const fill of whiteInkFills) {
it(`keeps ink legible on ${fill}`, () => {
setThemeMode("light");
expect(contrastRatio(C.ink, C[fill])).toBeGreaterThanOrEqual(4.5);
});
}
+ it("keeps the active tab's own ink legible on its fill", () => {
+ setThemeMode("light");
+ expect(contrastRatio(C.tabActiveFg, C.tabActiveBg)).toBeGreaterThanOrEqual(4.5);
+ });
+
for (const latency of [100, 700, 2000, 4000, 10000]) {
it(`keeps latency ink legible at ${latency}ms`, () => {
setThemeMode("light");
@@ -179,57 +183,141 @@ describe("light TUI palette contrast", () => {
});
/**
- * Every fill WE paint, measured against BOTH reference terminals — the rule claudeup
- * enforces in `theme-adaptive-colors.test.ts` and the one this repo was breaking.
+ * THE CHIP GATES — one reference page per palette, and one bar per ROLE.
*
- * A chip lands on a page we do not control. `theme-mode.ts` detects light vs dark and
- * we tune two palettes, but detection can fail (an unknown answer resolves to DARK),
- * tmux can lie about `COLORFGBG`, and a cream or solarized page is neither of our two
- * references. So a fill has to separate from BOTH or it is invisible somewhere real:
- * the rejected keycap grey measured 1.50:1 on the dark reference, which is a chip that
- * is not a chip.
+ * WHAT THIS REPLACED, AND WHY IT HAD TO. Until this pass every fill we paint had to
+ * clear 3:1 against BOTH `#FAFAD2` and `#1C1C1E`, on the grounds that detection can
+ * fail. Add white ink at 4.5:1 and that pins a fill's relative luminance to
+ * L ∈ [0.1351, 0.1833] — a band 1.26:1 wide — so EVERY chip, whatever it meant, was
+ * forced to be a mid-dark saturated block. The consequences were not theoretical:
+ * the `SUB` green could only be softened on the chroma axis, and the quiet `$` had to
+ * be a `#6b7280` slab at 4.53:1 on a light page, as heavy as the chip it was supposed
+ * to recede behind. The owner's verdict on that screen: *"this one is ugly for light
+ * theme"*, then *"sub has a super green for light theme background"*.
*
- * 3:1, NOT 4.5:1, AND THAT IS NOT A RELAXATION. No single colour can clear 4.5:1
- * against both a cream and a near-black page — the luminance bands do not overlap —
- * and 3:1 is WCAG's own bar for a UI component, which is what a chip is. The ink ON
- * the chip is held to 4.5:1 separately, and it is plain white, because we own both
- * sides of a fill and its contrast should not be a function of the user's theme.
+ * The premise was also false. `applyTuiTheme` resolves an UNKNOWN answer to DARK,
+ * never to LIGHT, so a light fill is only ever painted on a page we measured and
+ * found light. Each palette is now measured against its own reference — still the
+ * hostile end of its class (cream, not white; near-black, not black), so a fill that
+ * passes survives a terminal that is not our hardcoded `C.bg`.
+ *
+ * AND THE BAR DEPENDS ON WHAT THE CHIP IS FOR, because 3:1 for everything is what
+ * produced the glare. A SIGNAL marks the notable member of a column and separates
+ * hard. A QUIET chip — the metered `$`, both keycap segments — is a near-background
+ * fill whose job is to be perceptible and no more; holding it to 3:1 would demand the
+ * very block the owner rejected. So a quiet fill gets a FLOOR and a CEILING, and what
+ * has to be text-grade is the INK ON the chip, in every case.
*/
-describe("owned chip fills clear 3:1 on BOTH reference terminals", () => {
- const chipFills = [
- "pillKeyBg", // FREE / SUB / local — the positive family
- "pillMutedBg", // the picker's metered `$` — the quiet half of the same column
- "pillOauthBg", // oauth pills in the config TUI's AUTH column
- "chipKeycapBg", // footer keycaps
- "tabActiveBg", // the active tab pill
- "red", // the `HTTP 401` chip and the discovery-failure rule
- ] as const satisfies ReadonlyArray<keyof TuiPalette>;
+describe("chip gates: fill, ink, role and construction", () => {
+ /** The page a palette is measured against. See this describe's header. */
+ const REFERENCE_FOR_MODE = {
+ light: CONTRAST_REFERENCE.light,
+ dark: CONTRAST_REFERENCE.dark,
+ } as const;
+
+ /**
+ * EVERY CHIP THIS PROGRAM PAINTS, AS A FILL-AND-INK PAIR.
+ *
+ * A fill on its own is not a chip and cannot be judged: the light palette's `SUB`
+ * is a pale tint that would look broken under white ink and reads perfectly under
+ * its own deep green. Listing pairs is what lets one gate cover both constructions.
+ */
+ const CHIPS = [
+ { what: "status SUB/FREE/local", bg: "pillKeyBg", fg: "pillKeyFg", role: "signal" },
+ { what: "status $", bg: "pillMutedBg", fg: "pillMutedFg", role: "quiet" },
+ { what: "keycap KEY segment", bg: "keycapKeyBg", fg: "keycapKeyFg", role: "quiet" },
+ { what: "keycap LABEL segment", bg: "keycapLabelBg", fg: "keycapLabelFg", role: "quiet" },
+ ] as const satisfies ReadonlyArray<{
+ what: string;
+ bg: keyof TuiPalette;
+ fg: keyof TuiPalette;
+ role: "signal" | "quiet";
+ }>;
+
+ /**
+ * A quiet fill must be PERCEPTIBLE (you can see the chip's edge) and no louder.
+ *
+ * 1.10 is a floor on the edge, not on readability — readability is the ink gate,
+ * and under the tinted construction the ink clears 5:1 while the field itself is
+ * barely off the page. That is the point of a tint and it is why demanding 3:1 here
+ * would reject a correct design.
+ */
+ const QUIET_EDGE_FLOOR = 1.1;
+ /**
+ * And the CEILING is the gate nobody had. `#9333ea` measured 5.04:1 on the cream
+ * reference and 3.16:1 on the near-black one and passed every test in this file,
+ * because "loud" was not a failure anyone had written down. It is now.
+ */
+ const QUIET_CEILING = 3;
+
+ it("every chip is a FILL AND ITS INK, and the ink is text-grade on it", () => {
+ // 4.5:1, in BOTH palettes and under BOTH constructions. This is the one bar that
+ // does not move: whatever the fill does, the label on it has to be readable.
+ for (const mode of ["light", "dark"] as const) {
+ setThemeMode(mode);
+ for (const chip of CHIPS) {
+ expect({
+ mode,
+ what: chip.what,
+ ok: contrastRatio(C[chip.fg], C[chip.bg]) >= 4.5,
+ }).toEqual({ mode, what: chip.what, ok: true });
+ }
+ }
+ });
- for (const mode of ["light", "dark"] as const) {
- for (const fill of chipFills) {
- it(`separates ${fill} from both pages in the ${mode} palette`, () => {
- setThemeMode(mode);
- for (const page of Object.values(CONTRAST_REFERENCE)) {
- expect({ fill, page, ok: contrastRatio(C[fill], page) >= 3 }).toEqual({
- fill,
- page,
- ok: true,
- });
- }
- });
+ it("every QUIET fill is perceptible off its own page, and never a beacon", () => {
+ for (const mode of ["light", "dark"] as const) {
+ setThemeMode(mode);
+ const page = REFERENCE_FOR_MODE[mode];
+ for (const chip of CHIPS.filter((c) => c.role === "quiet")) {
+ const off = contrastRatio(C[chip.bg], page);
+ expect({
+ mode,
+ what: chip.what,
+ visible: off >= QUIET_EDGE_FLOOR,
+ quiet: off <= QUIET_CEILING,
+ // And off the PANEL it is actually drawn on, which is a shade nearer than
+ // the page — the surface a chip can vanish into first.
+ offPanel: contrastRatio(C[chip.bg], C.bgAlt) >= QUIET_EDGE_FLOOR,
+ }).toEqual({ mode, what: chip.what, visible: true, quiet: true, offPanel: true });
+ }
}
- }
+ });
+
+ it("THE SIGNAL CHIP IS BUILT DIFFERENTLY PER PALETTE — saturated on dark, a TINT on light", () => {
+ // The construction, asserted rather than described. This is the thing that keeps
+ // regressing: the previous pass correctly dropped each hue to its deep sibling
+ // and then kept the DARK palette's saturated-fill-with-white-ink shape on a white
+ // page, which is what the owner rejected as "super green". A hex check would not
+ // have caught it — the hex was right for a badge on black.
+ setThemeMode("dark");
+ expect({
+ mode: "dark",
+ separatesHard: contrastRatio(C.pillKeyBg, CONTRAST_REFERENCE.dark) >= 3,
+ lightInk: relativeLuminance(C.pillKeyFg) > relativeLuminance(C.pillKeyBg),
+ }).toEqual({ mode: "dark", separatesHard: true, lightInk: true });
+
+ setThemeMode("light");
+ expect({
+ mode: "light",
+ // A TINT: pale enough that it is NOT a block on the page. The bound is the
+ // assertion — anything above it is the saturated construction in disguise.
+ isTint: contrastRatio(C.pillKeyBg, CONTRAST_REFERENCE.light) <= 2,
+ darkInk: relativeLuminance(C.pillKeyFg) < relativeLuminance(C.pillKeyBg),
+ // …and the ink is the fill's OWN hue, not a neutral: a pale green field with
+ // grey text is two colours, not one chip.
+ inkCarriesTheHue: chroma(C.pillKeyFg) > 20,
+ }).toEqual({ mode: "light", isTint: true, darkInk: true, inkCarriesTheHue: true });
+ });
- it("keeps WHITE ink legible on every fill that carries a label", () => {
- // `C.ink` is `#ffffff` in both palettes for exactly this reason: where we choose
- // the fill we choose the ink, so the ratio is deterministic instead of a function
- // of the user's page. TWO fills are excluded and each for its own reason: `C.red`
- // is a NEON on dark (`#ff003c`), bright enough that `pickInk` correctly puts DARK
- // ink on it, and `tabActiveBg` carries its own `tabActiveFg` rather than `C.ink`.
+ it("keeps the SATURATED signal fills at 3:1 on their own page", () => {
+ // These did not change construction and are still blocks with white ink: the
+ // config TUI's oauth pill, the active tab, and the failure hue.
for (const mode of ["light", "dark"] as const) {
setThemeMode(mode);
- for (const fill of ["pillKeyBg", "pillMutedBg", "pillOauthBg", "chipKeycapBg"] as const) {
- expect({ mode, fill, ok: contrastRatio(C.ink, C[fill]) >= 4.5 }).toEqual({
+ const page = REFERENCE_FOR_MODE[mode];
+ for (const fill of ["pillOauthBg", "tabActiveBg", "red"] as const) {
+ expect({ mode, fill, ok: contrastRatio(C[fill], page) >= 3 }).toEqual({
mode,
fill,
ok: true,
@@ -238,6 +326,25 @@ describe("owned chip fills clear 3:1 on BOTH reference terminals", () => {
}
});
+ it("THE KEYCAP IS ONE PILL OF TWO SEGMENTS — the seam reads, and the key leads", () => {
+ // The owner asked for a chip, not a coloured word: *"the key itself brighter
+ // colour and label has backdrop but not as bright"*. Two things can go wrong and
+ // neither shows up in a character frame — the segments can collapse into one flat
+ // block, or they can invert so the label out-shouts the key.
+ for (const mode of ["light", "dark"] as const) {
+ setThemeMode(mode);
+ const page = REFERENCE_FOR_MODE[mode];
+ expect({
+ mode,
+ seamReads: contrastRatio(C.keycapKeyBg, C.keycapLabelBg) >= 1.25,
+ keyLeads: contrastRatio(C.keycapKeyBg, page) > contrastRatio(C.keycapLabelBg, page),
+ // The key half is the pressable one, so it gets a higher floor than the
+ // label: the grey claudeup measured as invisible was 1.50:1 on this page.
+ keyIsPressable: contrastRatio(C.keycapKeyBg, page) >= 1.5,
+ }).toEqual({ mode, seamReads: true, keyLeads: true, keyIsPressable: true });
+ }
+ });
+
it("A KEYCAP IS NEVER THE NEUTRAL GREY AGAIN, in either palette", () => {
// The regression this exists for shipped twice, once per palette: a grey keycap
// reads as a faintly tinted word rather than as a key you press, and the owner
@@ -246,32 +353,32 @@ describe("owned chip fills clear 3:1 on BOTH reference terminals", () => {
// measured against `bgAlt` above — a different object with a different contract.
for (const mode of ["light", "dark"] as const) {
setThemeMode(mode);
- expect({ mode, same: C.chipKeycapBg === C.chipKeyBg }).toEqual({ mode, same: false });
+ expect({ mode, same: C.keycapKeyBg === C.chipKeyBg }).toEqual({ mode, same: false });
}
});
it("HOLDS THE TWO HALVES OF THE STATUS COLUMN APART — the banding gate", () => {
- // The picker's billing column now carries a fill on EVERY row: `SUB`/`local` on
+ // The picker's billing column carries a fill on EVERY row: `SUB`/`local` on
// `pillKeyBg`, `$` on `pillMutedBg`. That is the shape that fused into one solid
// vertical band when the prefix column was chipped — and what failed there was
// that all 17 fills were the SAME colour. Here they alternate, so the whole
// design rests on these two being visibly different fills.
//
- // THE AXIS IS CHROMA, NOT LUMINANCE, AND THAT IS FORCED. Every owned fill must
- // sit in L 0.1351…0.1833 (3:1 on near-black below, white ink at 4.5:1 above), a
- // band only 1.26:1 wide — so two fills can differ in brightness by almost
- // nothing. MEASURED: `#3f7752` is C* 31.2 and `#6b7280` is C* 8.6, ΔE76 36.5
- // apart, where ~2.3 is a just-noticeable difference. The floor below is 20, well
- // under the measured value and far above a tweak that would collapse them.
+ // THIS GATE MATTERS MORE UNDER THE TINTED CONSTRUCTION, NOT LESS. Two saturated
+ // fills were 54.6 ΔE apart on the dark palette; two TINTS sit within 0.1 of each
+ // other in luminance and are 22.7 apart, all of it hue. Ten just-noticeable
+ // differences is plenty to read, and a tenth of the headroom — so the floor stays
+ // at 20 and it is now a floor the light palette is genuinely near.
for (const mode of ["light", "dark"] as const) {
setThemeMode(mode);
expect({
mode,
distinct: C.pillKeyBg !== C.pillMutedBg,
deltaE: deltaE76(C.pillKeyBg, C.pillMutedBg) >= 20,
- // And the METERED one is the QUIET one: a near-grey beside a green. If this
- // inverts, the column is telling the reader that the default state is the
- // notable one.
+ // And the METERED one is the QUIET one: a near-neutral beside a green. CHROMA
+ // is the axis that survives BOTH constructions — on a light page the two
+ // tints barely differ in weight, so a luminance test would say nothing. If
+ // this inverts, the column says the default state is the notable one.
quieter: chroma(C.pillMutedBg) < chroma(C.pillKeyBg) / 2,
}).toEqual({ mode, distinct: true, deltaE: true, quieter: true });
}
@@ -280,10 +387,10 @@ describe("owned chip fills clear 3:1 on BOTH reference terminals", () => {
it("KEEPS THE POSITIVE FILL SOFTER THAN THE TEXT-GRADE GREEN IT CAME FROM", () => {
// `pillKeyBg` was `#15803d` — claudeup's `success`, and also this palette's light
// `green`, which is a TEXT accent held to 4.5:1 on white. The owner's verdict on
- // it as an AREA was "make sub badge not as bright, make it softer". Softness is
- // chroma: C* 52.5 → 31.2, with the page ratios held (4.70/3.39 → 4.95/3.22). The
- // pin is the comparison, not the hex — a future green may be softer still, but it
- // may not climb back to a foreground's saturation.
+ // it as an AREA was "make sub badge not as bright, make it softer", twice, once
+ // per construction. Softness is chroma, and the pin is the COMPARISON rather than
+ // a hex: a future green may be softer still, but it may not climb back to a
+ // foreground's saturation.
for (const mode of ["light", "dark"] as const) {
setThemeMode(mode);
expect({ mode, softer: chroma(C.pillKeyBg) < chroma("#15803d") }).toEqual({
diff --git a/packages/cli/src/tui/theme.ts b/packages/cli/src/tui/theme.ts
index 7c5513b1..3c5b6ee4 100644
--- a/packages/cli/src/tui/theme.ts
+++ b/packages/cli/src/tui/theme.ts
@@ -17,8 +17,12 @@ import { getTerminalBackground, onThemeModeChange } from "../theme/theme-mode.js
* white ink on a wash would vanish.
*
* Token semantics that make both palettes work:
- * - `C.ink` — ink on fills WE paint that stay mid/dark in both themes
- * (pills, latency chips, active tab). Always white.
+ * - `C.ink` — ink on fills WE paint that stay mid/dark in BOTH themes
+ * (latency chips, the oauth pill). Always white. It is NOT the
+ * answer for the picker's chips any more: those are built
+ * differently per palette and each declares its own `*Fg`, because
+ * a light-page chip is a pale tint wearing deep ink. Reaching for
+ * `C.ink` on one of those paints white on near-white.
* - `C.strong` — emphasized text on the PAGE or on wash fills. White on dark,
* near-black on light. Never use `C.white` for page text.
*
@@ -55,35 +59,74 @@ export interface TuiPalette {
tabInactiveBg: string;
tabActiveFg: string;
tabInactiveFg: string;
+ /**
+ * The SIGNAL half of the picker's status column — `SUB` / `FREE` / `local`.
+ *
+ * ITS CONSTRUCTION DIFFERS BY PALETTE, WHICH IS THE WHOLE POINT OF THE PAIR. On
+ * DARK it is a saturated fill with light ink; on LIGHT it is a pale TINT of the
+ * same hue with deep ink of that hue. See the CONSTRUCTION note above `DARK`.
+ */
pillKeyBg: string;
+ /** Ink on `pillKeyBg` — white on dark, the deep sibling of the fill's hue on light. */
+ pillKeyFg: string;
pillOauthBg: string;
/**
- * The QUIET half of a two-tone chip column — the picker's metered `$`.
+ * The QUIET half of the same column — the picker's metered `$`.
*
* A second fill exists because a status column with one fill and one bare word is
- * a ragged column, and the owner asked for both states chipped at one width. The
- * two then have to be told apart by the fill alone, and the only axis left inside
- * the 3:1 band is CHROMA: `pillKeyBg` is a green at C* 31.2, this is a near-grey
- * at C* 8.6, ΔE76 36.5 apart. Grey is also the honest reading — metered is the
- * unremarkable default, not a claim.
+ * a ragged column, and the owner asked for both states chipped at one width. `$`
+ * is the UNREMARKABLE state, so its chip is a NEAR-BACKGROUND fill — a measured
+ * shade off the page carrying body ink — and it holds almost no hue, which is what
+ * makes the green beside it read as the claim.
*/
pillMutedBg: string;
- /** Footer KEYCAP fill. Vivid, white ink, the same hex in both palettes. */
- chipKeycapBg: string;
+ /** Ink on `pillMutedBg`. Dark on the light page, light on the dark one. */
+ pillMutedFg: string;
+ /**
+ * The picker footer's KEYCAP PILL — two abutting segments, not one block.
+ *
+ * `keycapKey*` is the segment carrying the glyph you press and is the BRIGHTER of
+ * the two; `keycapLabel*` is the segment carrying what it does and is quieter. The
+ * owner's words: *"the key itself brighter colour and label has backdrop but not as
+ * bright, create chips"*. madbench's `paramKeyBg`/`paramValBg` is the same idiom.
+ *
+ * They must ABUT. A gap between the two fills splits the pill into two objects, so
+ * the space belongs BETWEEN pills (`Hints`' `gap={1}`) and never inside one.
+ */
+ keycapKeyBg: string;
+ keycapKeyFg: string;
+ keycapLabelBg: string;
+ keycapLabelFg: string;
chipKeyBg: string;
chipLabelBg: string;
}
/**
- * The two backgrounds every OWNED FILL is measured against — `theme-contrast.test.ts`.
+ * The reference page EACH PALETTE is measured against — `theme-contrast.test.ts`.
+ *
+ * ONE REFERENCE PER PALETTE, NOT BOTH FOR BOTH. This used to require every owned
+ * fill to clear 3:1 against BOTH a cream page and a near-black one, on the grounds
+ * that detection can fail. What that actually bought was a self-inflicted trap: the
+ * two bars plus white ink at 4.5:1 pin a fill's relative luminance to
+ * L ∈ [0.1351, 0.1833] — a band 1.26:1 wide — so EVERY chip, whatever it meant, had
+ * to be a mid-dark saturated block. The green could then only be softened on the
+ * chroma axis, and the quiet `$` had to be a heavy mid-grey slab that competed with
+ * `SUB` on a light page. The owner's verdict on the shipped result: *"this one is
+ * ugly for light theme"*.
*
- * A chip we paint lands on a terminal whose page we do not control, so a fill that
- * only separates from one of them is invisible on the other. A single colour CANNOT
- * reach 4.5:1 against both: clearing it on cream needs relative luminance <= ~0.17,
- * clearing it on near-black needs >= ~0.22, and those do not overlap. So the bar for
- * a fill is 3:1 — WCAG's threshold for UI components — which admits exactly the band
- * of mid-dark saturated colours the chips below live in. Borrowed, with the hexes,
- * from claudeup's `src/ui/theme.ts`, whose own test enforces the same rule.
+ * The premise was also wrong. A failed detection resolves to DARK, never to LIGHT
+ * (`applyTuiTheme`), so a LIGHT fill is only ever painted on a page we measured and
+ * found light. Holding it to a near-black reference protects nothing and costs the
+ * whole design. madbench's `internal/tui/theme.go` states the rule this file now
+ * follows: *"lightPalette is NOT the dark palette inverted … each hue drops to its
+ * deep (roughly 600-level) sibling, where it stays distinguishable from its
+ * neighbors AND carries white text when it becomes a badge fill."*
+ *
+ * The bar per palette is still 3:1 — WCAG's threshold for a UI component — and it is
+ * now a bar a colour can be CHOSEN for rather than compromised into. The references
+ * stay the hostile end of each class (a cream page, not white; a near-black page, not
+ * black) so a fill measured here survives a terminal that is not our hardcoded
+ * `C.bg`. Borrowed, with the hexes, from claudeup's `src/ui/theme.ts`.
*/
export const CONTRAST_REFERENCE = {
light: "#FAFAD2",
@@ -123,40 +166,58 @@ const DARK: TuiPalette = {
tabActiveFg: "#ffffff",
tabInactiveFg: "#0088ff",
- // Muted pill backgrounds for AUTH column tags and the picker's state chips. The
- // standard `green` / `cyan` are neon-bright and cause eye strain as a solid fill,
- // so these are lower-saturation forest/teal versions carrying white ink.
+ // ── CHIP CONSTRUCTION: THE PAGE PICKS THE RECIPE, NOT JUST THE HEX ─────────
+ //
+ // A chip is a fill plus its ink, and the two palettes build that pair DIFFERENTLY
+ // rather than swapping one hex:
+ //
+ // DARK — SATURATED fill, LIGHT ink. Against near-black a colour has to bring its
+ // own light, so the fill carries the hue and white sits on it.
+ // LIGHT — PALE TINT of the hue, DEEP ink of the SAME hue. Against white a
+ // saturated fill is a glaring block. The owner saw the saturated version
+ // on a light terminal: *"sub has a super green for light theme
+ // background, that should be not as bright"*.
+ //
+ // That is madbench's rule one level up from colour (`internal/tui/theme.go`): the
+ // light palette is not the dark one inverted, because "neon reads as brightness
+ // against black and as glare against white".
//
- // RAISED FROM `#2d6e3e` / `#1f6d75` TO A MEASURED SET. The old forest green
- // cleared 5.77:1 on a cream page and only 2.76:1 on a near-black one — under the
- // 3:1 a UI component needs — so a `SUB` chip on a dark terminal was a fill that
- // barely separated from the page it sat on. All three clear 3:1 against BOTH
- // reference backgrounds and keep white ink at 4.8+, and all three are shared
- // verbatim by both palettes: a fill measured against both pages needs no
- // per-theme variant.
+ // Within a palette there are then two ROLES. SIGNAL (`pillKeyBg`, `pillOauthBg`,
+ // `tabActiveBg`) marks the notable member of a column. QUIET (`pillMutedBg`, both
+ // keycap segments) is the unremarkable state and the keyboard affordance: a
+ // NEAR-BACKGROUND fill, a measured shade off the page, carrying body ink — which
+ // is why `retintSurfaces` treats those as surfaces rather than as accents. Which
+ // way "off the page" points is itself per-palette: up on black, down on white.
//
- // `pillKeyBg` WAS `#15803d` (claudeup's `success`) AND WAS TOO BRIGHT AS A FILL —
- // the owner's words, "make sub badge not as bright, make it softer". Softness here
- // is CHROMA, not luminance: the band a fill may occupy is L 0.1351…0.1833 (3:1 on
- // near-black sets the floor, white ink at 4.5:1 sets the ceiling), which is only
- // 1.26:1 wide, so a fill cannot be meaningfully darkened without failing one side.
- // MEASURED with `validation/chip-fill-shortlist.ts`: `#15803d` is C* 52.5 at
- // L* 46.9 and `#3f7752` is C* 31.2 at L* 45.4 — 41% less chroma and slightly
- // darker — while the page ratios IMPROVE on cream and hold on near-black
- // (4.70/3.39 → 4.95/3.22). Contrast was not traded for softness.
- pillKeyBg: "#3f7752", // softened forest green; white ink 5.29:1
- pillOauthBg: "#0e7490", // muted teal; white ink reads cleanly on both pages
- // Tailwind's `gray-500`, chosen for what it is NOT: it carries almost no hue
- // (C* 8.6), so beside `pillKeyBg` it reads as the absence of a claim rather than
- // as a second claim. 4.53/3.52 on the two pages, white ink 4.83:1.
- pillMutedBg: "#6b7280",
- // A KEYCAP IS A VIVID BLOCK WITH WHITE INK, in both palettes and at the same hex.
- // Neutral grey was measured and rejected twice: `#3a3a3a` is 1.50:1 on a dark page
- // and `#9ca3af` 2.38:1 on a light one, so whichever way it is tuned the chip melts
- // into one of the two terminals. Purple clears 5.04/3.16 and is spent on nothing
- // else in this program — the accent is blue, so a keycap cannot be mistaken for a
- // focus ring, a status or a failure.
- chipKeycapBg: "#9333ea",
+ // `pillKeyBg` — the BRIGHTER sibling, now that it no longer has to survive a cream
+ // page as well. `#3f7752` was the both-pages compromise: 3.22:1 on near-black,
+ // C* 31.2. Measured with `validation/chip-fill-two-palettes.ts`, `#2f8250` is
+ // 3.59:1 on near-black and 4.43:1 on true black at C* 42.1, and still carries white
+ // ink at 4.74:1. It stays well under the neon `green` (`#39ff14`) and under the
+ // `#15803d` the owner called too bright (C* 52.5) — softer than a foreground,
+ // brighter than a compromise.
+ pillKeyBg: "#2f8250", // forest green, dark-page sibling
+ pillKeyFg: "#ffffff", // 4.74:1 on the fill
+ pillOauthBg: "#0e7490", // muted teal; white ink 5.02:1
+ // NEAR-BG DARK (madbench `paramValBg`). 1.64:1 off true black and 1.47:1 off the
+ // `bgAlt` panel — present as a block, absent as a claim. Its ink is a DIM one, not
+ // white: `$` is what a route is by default and the number that matters is on the
+ // model row. ΔE76 54.6 from `pillKeyBg`, so the alternating column cannot band.
+ pillMutedBg: "#2E323D",
+ pillMutedFg: "#A8B0C4", // 5.90:1 on the fill — legible, not loud
+ // THE KEYCAP PILL — two abutting near-bg segments, key brighter than label.
+ // It replaces a single saturated purple block (`#9333ea`, 3.90:1 off this page and
+ // 5.38:1 off the light one), which made the quietest row on the screen the loudest.
+ // A pale fill CANNOT be borrowed from the light palette here: `#B8C2D8` measures
+ // 1.06:1 on true black, worse than the neutral grey claudeup already rejected as
+ // invisible (`#3a3a3a`, 1.50:1 against the near-black reference). So the dark page
+ // gets its own pair: the key segment at 2.57:1 off the page and 2.08:1 off the
+ // near-black reference, the label at 1.52:1, and 1.69:1 between the two — enough
+ // for the seam to read as one pill with two halves.
+ keycapKeyBg: "#474F63",
+ keycapKeyFg: "#ffffff", // 8.18:1 on the fill
+ keycapLabelBg: "#292D36",
+ keycapLabelFg: "#A8B0C4", // 6.35:1 on the fill
// Monochrome two-tone footer chip. The key sits on the LIGHTER segment and
// the label on the DARKER segment; the two abut into one connected pill.
@@ -202,18 +263,45 @@ const LIGHT: TuiPalette = {
tabActiveFg: "#ffffff",
tabInactiveFg: "#374151",
- // The green/teal/grey pills and the keycap are mid-lightness fills with white ink —
- // they clear 3:1 on BOTH reference pages, so they are shared verbatim with DARK.
- // `pillKeyBg` is deliberately NO LONGER the same hex as `green`: `green` is a page
- // TEXT accent held to 4.5:1 on white, and this is an area fill held to 3:1 on two
- // pages with white ink on top. One number cannot serve both tests.
- pillKeyBg: "#3f7752",
- pillOauthBg: "#0e7490",
- // Same hex as this palette's `dim`, and that is a coincidence rather than a shared
- // meaning: `dim` is page text on white, this is an area fill carrying white ink.
- // They are measured against different references and may diverge.
- pillMutedBg: "#6b7280",
- chipKeycapBg: "#9333ea",
+ // ── CHIPS, RE-VOICED FOR A WHITE PAGE — AND RE-BUILT, NOT RECOLOURED ──────
+ //
+ // EVERY CHIP HERE IS A TINT WITH DEEP INK. That is the inversion of the dark
+ // palette's recipe and it is deliberate; see the CONSTRUCTION note in `DARK`. The
+ // build before this one dropped each hue to its deep sibling but kept the dark
+ // palette's saturated-fill-with-white-ink shape, and a deep green block with white
+ // text is exactly what the owner rejected on a light terminal.
+ //
+ // A TINT IS NOT A WEAKER CHIP. What carries the meaning moves from the fill to the
+ // INK: `SUB` is a pale green field with `#166534` printed on it at 5.17:1, which is
+ // text-grade, while the field itself only has to be perceptible (1.38:1 off white).
+ // The old construction had that backwards — it spent all the contrast on the block
+ // and then had to print white on it.
+ //
+ // SIGNAL — madbench's `diffAddBg` family. Its literal `#CDEEDA` was measured and is
+ // ONE STEP TOO PALE: ΔE76 18.85 from the `$` tint, under the 20 the banding gate
+ // requires, and only 1.13:1 off the `bgAlt` panel. `#BCE5CD` is ΔE76 22.68 and
+ // 1.25:1 off the panel, with the deep ink still at 5.17:1.
+ pillKeyBg: "#BCE5CD",
+ pillKeyFg: "#166534", // madbench `lime` — the matching deep sibling of the tint
+ // `pillOauthBg` KEEPS the saturated construction: it is the config TUI's AUTH
+ // column, not this dialog, and it has not been through the owner's review. Noted so
+ // the inconsistency is a decision rather than an oversight.
+ pillOauthBg: "#0e7490", // deep teal, 5.13:1 on the cream reference
+ // QUIET — madbench's `paramKeyBg`, "near-bg light — still distinct on a cream or
+ // grey page", with `slate` ink at 6.12:1. It carries almost no hue (C* 5.4 against
+ // the green tint's 19.4), which is what makes `$` read as the absence of a claim.
+ // This REPLACES `#6b7280`, a mid-grey slab at 4.53:1 on a light page — as heavy as
+ // the `SUB` chip it was supposed to recede behind.
+ pillMutedBg: "#E2E6F0",
+ pillMutedFg: "#4E5364", // madbench `slate`; 6.12:1 on the fill
+ // THE KEYCAP PILL — two abutting near-bg segments, key brighter than label.
+ // 1.79:1 and 1.25:1 off the page with 1.46:1 between them, against the single
+ // purple block's 5.38:1. The floor is the `#d1d5db` this file already measured as
+ // melting into the band at 1.32:1.
+ keycapKeyBg: "#B8C2D8",
+ keycapKeyFg: "#111827", // 9.92:1 on the fill
+ keycapLabelBg: "#E4E8F2",
+ keycapLabelFg: "#4E5364", // 6.24:1 on the fill
// The config TUI's TWO-TONE footer chip (`Footer.tsx`), and no longer the
// picker's keycap — that one is `chipKeycapBg`, because a neutral grey cannot
@@ -430,11 +518,29 @@ export function registerPaletteRefresher(fn: () => void): void {
* from the page. When the page moves, these must move with it or the seam the
* page adoption removed simply reappears one box further in.
*
+ * THE QUIET CHIP FILLS BELONG HERE, and that follows from what they now are. A
+ * near-background fill IS a surface — its whole content is "a measured shade off the
+ * page" — so on a cream terminal `pillMutedBg` and both keycap segments must become
+ * deeper cream, exactly as `bgAlt` does, or a blue-grey `$` chip floats on cream and
+ * the seam this function exists to remove reappears inside the status column. They
+ * only joined the list when they stopped being saturated blocks.
+ *
* Deliberately excluded: `bgHighlight` (blue selection wash) and `bgError` (red
- * failure wash) carry their meaning in their HUE, and `tabActiveBg` / the pill
- * fills are accents. Re-tinting those would erase the signal they exist to send.
+ * failure wash) carry their meaning in their HUE, and so do `tabActiveBg` and the
+ * SIGNAL pills (`pillKeyBg`, `pillOauthBg`) — including the light palette's pale
+ * GREEN TINT, which is a tint OF a hue and not a neutral. Re-tinting those would
+ * erase the signal they exist to send.
*/
-const SURFACE_TOKENS = ["bgAlt", "border", "tabInactiveBg", "chipKeyBg", "chipLabelBg"] as const;
+const SURFACE_TOKENS = [
+ "bgAlt",
+ "border",
+ "tabInactiveBg",
+ "chipKeyBg",
+ "chipLabelBg",
+ "pillMutedBg",
+ "keycapKeyBg",
+ "keycapLabelBg",
+] as const;
/** `#rrggbb` → `[r, g, b]`, or null for anything that isn't one. */
function hexChannels(hex: string): [number, number, number] | null {