@cube-dev/ui-kit 0.163.0 → 0.165.0

package/dist/tokens/palette.js

@@ -1,7 +1,7 @@
-/** @license MIT | @cube-dev/ui-kit v0.163.0 | Cube Dev Team */
-import { getPaletteConfig, getPaletteVersion, resolvePaletteConfig } from "./palette-config.js";
+/** @license MIT | @cube-dev/ui-kit v0.165.0 | Cube Dev Team */
+import { SURFACE_SATURATION_SHARE, getPaletteConfig, getPaletteVersion, resolvePaletteConfig } from "./palette-config.js";
 import { lazyStyles } from "./lazy-styles.js";
-import { glaze } from "@tenphi/glaze";
+import { apcaContrast, glaze, okhslToLinearSrgb, variantToOkhsl } from "@tenphi/glaze";
 
 //#region src/tokens/palette.ts
 /**
@@ -30,12 +30,334 @@ const CODE_STRING_HUE = 280.3;
 * Saturation factor of the neutral `surface`.
 *
 * Shared with the code theme, which mirrors `surface` to solve its contrast floors
-* against the real page background — the two must not drift apart.
+* against the real page background — the two must not drift apart. Shared with the
+* config too, which needs it to work out the share of the accent zone's chroma the
+* chrome takes when no base COLOR names one outright; it lives there because the
+* config cannot import from here, and is re-exported under this name because that is
+* what the recipe calls it.
 */
-const SURFACE_SATURATION = .12;
+const SURFACE_SATURATION = SURFACE_SATURATION_SHARE;
 const TINTED_SURFACE_SATURATION = .2;
 const TINTED_SURFACE_TONE_OFFSET = 2;
 /**
+* How far `surfaceMode: 'tinted'` moves the neutral ramp off the end of the tone
+* scale.
+*
+* Small on purpose. Two tones is below the threshold where a page reads as
+* "grey" rather than "white", and it is not lightness this buys: chroma needs
+* distance from the extreme to exist at all, so at tone 100 a light surface is
+* white whatever saturation it asks for. Two tones is the cheapest room in which
+* the base hue becomes visible.
+*
+* Everything under `surface` is positioned relative to it, so the shift carries
+* the whole ladder — and the text ramp's contrast floors re-solve against the new
+* background instead of drifting.
+*/
+const TINTED_SURFACE_TONE_SHIFT = 2;
+/** Tone of the neutral `surface`, per {@link ResolvedPaletteConfig.surfaceMode}. */
+function surfaceTone(config) {
+	return config.surfaceMode === "tinted" ? 100 - TINTED_SURFACE_TONE_SHIFT : 100;
+}
+/**
+* Tone of a TINTED `surface` — a status theme's, or a runtime tint's —
+* as `[light, highContrast]`.
+*
+* A tinted surface is a banner sitting *on* the page, so its tone is authored as
+* an offset from the page's rather than as an absolute. Under
+* `surfaceMode: 'tinted'` the page itself moves down to 98, which is exactly where
+* these used to sit: a `note` banner would come out the same tone as the surface
+* behind it and stop reading as a banner at all. Anchoring both on
+* {@link surfaceTone} keeps the separation the offset was chosen for.
+*
+* The text ramps on these themes are relative (`base: 'surface'`), so they follow
+* on their own — only the absolute tone needs the anchor.
+*/
+function tintedSurfaceTone(config) {
+	const page = surfaceTone(config);
+	return [page - TINTED_SURFACE_TONE_OFFSET, page - TINTED_SURFACE_TONE_OFFSET * 2];
+}
+/**
+* Rescale the base-zone saturation factors onto the base zone's own seed.
+*
+* Every color's `saturation` is a 0–1 factor of its **theme's** seed, and the
+* neutral family shares a theme instance with the accent one — it has to, since
+* `accent-surface` is positioned against `surface`. A separate base seed therefore
+* cannot be a second theme; it arrives as a scale over the authored factors.
+*
+* The scale is anchored on `surface`: dividing by `SURFACE_SATURATION` turns each
+* factor into its share *of the surface's tint*, and multiplying by
+* `baseSaturation / saturation` re-expresses that share against the base seed.
+* `surface` therefore lands on exactly `baseSaturation` on the 0–100 scale, and
+* every sibling keeps its proportion to it. At the shipped
+* `baseSaturation = saturation × 0.12` the scale is `1` and nothing moves.
+*
+* Clamped because Glaze reads the factor as 0–1, which is also why the proportions
+* converge at the top: `surface-inverse` (the highest at `0.475`) saturates first,
+* around `baseSaturation: 25`.
+*
+* A palette seed of `0` leaves no chroma for any factor to scale, so the base zone
+* is grey there whatever it asks for — the ceiling belongs to the theme instance,
+* not to this scale.
+*/
+function baseSaturationScale(config) {
+	return config.saturation > 0 ? config.baseSaturation / (SURFACE_SATURATION * config.saturation) : 0;
+}
+/**
+* How far a pinned brand FILL has to separate from the page it sits on — APCA Lc 25, in
+* both tiers.
+*
+* The base is `surface`, and `roleToPolarity('surface')` gives this the `bg` polarity,
+* so Glaze solves `apcaContrast(surface, fill)`.
+*
+* **This number is page separation and nothing else**, and getting that wrong is what
+* made the dark scheme unusable. It reads differently by scheme — in light `surface` IS
+* white, so the same measurement happens to be the white-label pair, which invited the
+* value to be set for the LABEL at Lc 45 (`large` text) with 60 in high contrast. In
+* dark the page is near-black and the same number is a demand that a filled shape reach
+* text-grade contrast against it. Nothing in the palette meets that: measured on the
+* emitted tokens, the SHIPPED `accent-surface` — the white-anchored ladder every primary
+* button used before color seeds existed — sits at **Lc 25.5** off the dark page, and at
+* **Lc 19.3** in dark high contrast, where the ladder darkens the fill toward its label.
+* So 45/60 held a color-seeded fill to 1.8x and 3.1x what the design system's own button
+* achieves.
+*
+* Because a floor can only LIGHTEN in dark, that surplus flattened the tone axis: every
+* seed below the floor solved to the same fill. Measured across the axis at one hue, the
+* dark fill was pinned at tone 66 for every seed from 5 to 65 — a brand's whole dark half
+* collapsed onto one lavender — and in dark high contrast the floor met
+* {@link ACCENT_LABEL_LC}'s ceiling and left a window of a single value. At Lc 25 the
+* same sweep tracks the seed from tone 47 up, and 47 is where the shipped fill sits in
+* dark, so the floor now coincides with the palette's own reference point instead of
+* overshooting it.
+*
+* The label is not left unguarded by this — it never depended on this number. The white
+* `type="primary"` label is guaranteed by {@link accentToneCeiling}, which caps the seed
+* against pure white across all four variants, with {@link ACCENT_LABEL_MARGIN} covering
+* the lightening this floor can still add. A LOWER floor lightens less, so it makes that
+* margin safer rather than riskier.
+*
+* What the floor cannot do is invent contrast that a dark page has no room for. A brand
+* darker than the shipped fill's own dark tone still lands on the floor, because a fill
+* beneath it is not a shape on that page. The fix is that the floor now sits where the
+* design system already put it, not two tiers above.
+*
+* Still a FLOOR, not a target: a brand already past it is emitted exactly as given —
+* which is why light is untouched by this change. A dark brand on a white page measures
+* Lc 100+, so this never bound there; the ceiling is what light answers to.
+*
+* Why APCA and not a WCAG ratio. WCAG 2.x is polarity-blind, so one number means two
+* very different things: the previous `3` measured Lc 56 in light but only Lc 23 in
+* dark (12 hues, spread under 2 Lc — hue is not a factor, polarity is). That is 2.4x
+* stricter in light than in dark, which is why light brands kept getting crushed while
+* dark ones sailed through under the same rule. An Lc is one number that means one
+* thing in both schemes.
+*
+* The pair is written out with BOTH entries equal, and that is the whole reason it is a
+* pair: stating one level would let APCA's automatic +15 Lc enhancement fire in high
+* contrast, which is the escalation this must not make. High contrast is a request for
+* separation over brand, but not for separation from the PAGE — the same fill carries a
+* white label, and driving it off the page drives the label off it. The shipped ladder
+* makes the same trade and lands the other side of it, at Lc 19.3: *less* page separation
+* in high contrast than in normal, because it darkens the fill toward its label. Here the
+* label is protected by {@link accentToneCeiling} instead, which searches the
+* high-contrast variants too, so the tier can leave this number alone.
+*/
+const ACCENT_FILL_CONTRAST = { apca: [25, 25] };
+/**
+* Floors for the two brand TEXT tokens: rest, then hover — APCA `content` and `body`.
+*
+* Also "from white", in the same sense as {@link ACCENT_FILL_CONTRAST}: both solve
+* against `accent-selected-fill`, which is `oklch(0.975 0.0037 284.4)` in light — white
+* for every practical purpose, and the surface these labels actually sit on. These are
+* foreground spots, so they keep the default `fg` polarity and Glaze solves
+* `apcaContrast(text, base)`.
+*
+* Lc 60 is APCA's `content` tier, the floor for ordinary body text, which is what a
+* link is. The hover takes `body`/75 so the rest→hover intensify stays visible; one
+* preset step apart is what keeps the two from solving onto the same color.
+*
+* The HC entries are spelled `85` and `92` rather than left to Glaze's +15, for the
+* same reason as {@link ACCENT_FILL_CONTRAST}, and they stay apart so the rest→hover
+* intensify survives the tier that needs it most. They replace the hand-measured
+* `[4.5, 9]` pair, whose `9` existed only because a WCAG ratio that high is unreachable
+* for a saturated hue against a chromatic base: `#FFD400` in dark high contrast used to
+* pin to pure black and come out a hover link *less* readable than its rest state. An
+* Lc target is reachable in both schemes because it is polarity-aware, so the
+* pathological case has no equivalent here.
+*/
+const ACCENT_TEXT_CONTRAST = { apca: [60, 85] };
+const ACCENT_TEXT_HOVER_CONTRAST = { apca: [75, 92] };
+/**
+* Tone steps of the brand fill ramp, measured from `accent-surface`.
+*
+* They reproduce the white-anchored `-49 / -52 / -55 / -58` ladder exactly once the
+* fill is pinned, because those four deltas share an anchor and differ by 3 / 6 / 9.
+*/
+const ACCENT_RAMP = {
+	surface2: "-3",
+	surface3: "-6",
+	hover: "-9"
+};
+/**
+* How far the hover brand text sits past the rest one, in tone.
+*
+* Both are pinned to the caller's tone otherwise, and a pair at the same tone behind
+* the same floor resolves to one color — which would silently delete the rest→hover
+* intensify that `accent-text` exists for. Tone is contrast-uniform, so one step is
+* one step in either scheme.
+*/
+const ACCENT_TEXT_HOVER_STEP = 6;
+/**
+* The white label's own floor on the brand fill, as an APCA Lc.
+*
+* The same 45 as {@link ACCENT_FILL_CONTRAST}, and deliberately so: it is the same
+* surface being constrained, just against the other thing that has to survive on it.
+*
+* Two floors rather than one because in dark they pull opposite ways, and dropping
+* either one produces the mirror image of the other's failure. The fill has to be dark
+* enough for the `#white` label every `type="primary"` item paints on it, and light
+* enough to separate from a dark page. In light mode the page IS white, so both
+* collapse into the single measurement Glaze already makes and this cap never fires.
+*
+* Measured, in dark, with only the page floor: `#FFFFFF` clears it at WCAG 14.4 while
+* the label lands on **Lc 0** — the label is exactly its own fill. With only the white
+* floor the failure mirrors: `#111827` puts the fill at **Lc 0.0 against the page**, a
+* blazing white label on a shape that is not there. The border does not stand in for
+* the fill here — it is deliberately low-contrast — so the fill has to carry it.
+*/
+const ACCENT_LABEL_LC = 45;
+/**
+* How far above {@link ACCENT_LABEL_LC} the ceiling actually searches.
+*
+* The ceiling is computed on the bare seed, but the emitted `accent-surface` then goes
+* through the page floor, which can only LIGHTEN — and a lighter fill is a weaker white
+* label, so the solve eats into the margin the ceiling just established. Measured worst
+* case across 3072 hue/chroma/tone/scheme/tier combinations is 1.8 Lc, in dark high
+* contrast where the page floor pushes hardest; 3 covers it with room.
+*/
+const ACCENT_LABEL_MARGIN = 3;
+/**
+* Keyed on the palette VERSION as well as the seed, because the search resolves
+* through Glaze's global settings — the dark tone window among them. A caller that
+* runs `glaze.configure(...)` and then `invalidatePaletteTokens()` has changed the
+* answer without changing the seed, and a cache keyed on the color alone would hand
+* back a cap computed against the old settings. Versioning it is what makes the
+* invalidation API mean what it says.
+*
+* Bounded for the same reason `colorSeed`'s cache is: a color picker drag resolves a
+* distinct seed per frame, and stale versions accumulate keys nobody reads again.
+*/
+const accentCapCache = /* @__PURE__ */ new Map();
+const ACCENT_CAP_CACHE_LIMIT = 256;
+/** APCA Lc of pure white on one resolved variant. */
+function labelLcOf(variant) {
+	const { h, s, l } = variantToOkhsl(variant);
+	const gamma = (c) => c <= .0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - .055;
+	const y = (rgb) => {
+		const [r, g, b] = rgb.map((c) => Math.max(0, Math.min(1, gamma(c))));
+		return .2126 * r ** 2.4 + .7152 * g ** 2.4 + .0722 * b ** 2.4;
+	};
+	return Math.abs(apcaContrast(y([
+		1,
+		1,
+		1
+	]), y(okhslToLinearSrgb(h, s, l, false))));
+}
+/**
+* Pull a brand tone down until a white label survives on every variant of the fill.
+*
+* The search runs against Glaze's own fixed-mode resolution — the same mapping
+* `accent-surface` goes through — rather than reimplementing the dark tone window, and
+* checks all four variants so the cap is a property of the seed and not of one scheme.
+*
+* Only ever lowers, so a brand already dark enough comes back untouched.
+*/
+function capAccentTone(hue, saturation, tone) {
+	return Math.min(tone, accentToneCeiling(hue, saturation));
+}
+/**
+* The lightest tone at this hue and chroma that a white label still survives on.
+*
+* A property of the hue/chroma pair alone, NOT of the tone being asked for — which is
+* what makes it cacheable, and what the first cut got wrong: it only searched when the
+* requested tone already failed, so a dark tone probed first cached "no ceiling" and
+* every later light tone at the same hue escaped uncapped.
+*/
+function accentToneCeiling(hue, saturation) {
+	const key = `${hue}|${saturation}|${getPaletteVersion()}`;
+	const cached = accentCapCache.get(key);
+	if (cached !== void 0) return cached;
+	const labelLc = (candidate) => {
+		const resolved = glaze.color({
+			from: {
+				h: hue,
+				s: saturation / 100,
+				t: candidate / 100
+			},
+			mode: "fixed"
+		}).resolve();
+		return Math.min(labelLcOf(resolved.light), labelLcOf(resolved.dark), labelLcOf(resolved.lightContrast), labelLcOf(resolved.darkContrast));
+	};
+	let ceiling = 100;
+	const target = ACCENT_LABEL_LC + ACCENT_LABEL_MARGIN;
+	if (labelLc(100) < target) {
+		let low = 0;
+		let high = 100;
+		for (let i = 0; i < 24; i++) {
+			const mid = (low + high) / 2;
+			if (labelLc(mid) >= target) low = mid;
+			else high = mid;
+		}
+		ceiling = low;
+	}
+	if (accentCapCache.size >= ACCENT_CAP_CACHE_LIMIT) accentCapCache.clear();
+	accentCapCache.set(key, ceiling);
+	return ceiling;
+}
+/**
+* A color seed as the three numbers Glaze consumes, with its tone capped.
+*
+* Takes the RESOLVED components rather than the caller's literal because the tone is
+* capped — {@link capAccentTone} only ever lowers it — and a capped tone means rebuilding
+* the color regardless. Passing `from: <the original string>` would emit the tone the
+* white label cannot survive.
+*
+* Shared by the accent zone and by any status theme on the color path: they resolve their
+* components differently, but a fill is a fill once the numbers are in hand.
+*/
+function cappedAccent(hue, saturation, tone) {
+	const capped = capAccentTone(hue, saturation, tone);
+	return {
+		color: {
+			h: hue,
+			s: saturation / 100,
+			t: capped / 100
+		},
+		tone: capped
+	};
+}
+/**
+* Opaque stand-in for the BASE selected fill used by outline / outline-2 / clear Item
+* types (`#surface|#surface-2|#surface-3` + `#accent-surface.09`).
+*
+* Anchors the `accent-text*` contrast. `value: 9` matches the `.09` alpha overlay;
+* `space: 'srgb'` approximates CSS two-layer compositing. Inherited so colored themes
+* re-resolve against their own `surface` + `accent-surface` (default `surface-2` /
+* `surface-3` are `inherit: false` and can't be the mix base). Primary's tinted
+* `surface` makes this slightly harder than default clear-selected, covering
+* outline / outline-2 selected fills as well.
+*
+* The same in both accent arrangements — it is defined by its two ends, and both of
+* those move with the seed on their own.
+*/
+const ACCENT_SELECTED_FILL = { "accent-selected-fill": {
+	type: "mix",
+	base: "surface",
+	target: "accent-surface",
+	value: 9,
+	space: "srgb"
+} };
+/**
 * Syntax highlighting for `PrismCode`, as its own theme.
 *
 * A small palette of *adaptive* colored tokens. Each one is anchored to `surface`
@@ -127,14 +449,14 @@ const CODE_COLORS = {
 function buildCodeTheme(config, instanceConfig) {
 	const codeSaturation = config.themes.code.saturation;
 	const theme = glaze(config.hue, codeSaturation, instanceConfig);
-	let mirrorFactor = SURFACE_SATURATION * (config.saturation / codeSaturation);
+	let mirrorFactor = config.baseSaturation / codeSaturation;
 	if (mirrorFactor > 1) {
-		console.warn(`[cube-ui-kit] themes.code.saturation (${codeSaturation}) is too low for saturation ${config.saturation}: the mirrored code surface would need a factor of ${mirrorFactor.toFixed(3)}. Clamped to 1; raise the code saturation to keep syntax contrast accurate.`);
+		console.warn(`[cube-ui-kit] themes.code.saturation (${codeSaturation}) is too low for baseSaturation ${config.baseSaturation}: the mirrored code surface would need a factor of ${mirrorFactor.toFixed(3)}. Clamped to 1; raise the code saturation to keep syntax contrast accurate.`);
 		mirrorFactor = 1;
 	}
 	theme.colors({
 		surface: {
-			tone: 100,
+			tone: surfaceTone(config),
 			saturation: mirrorFactor
 		},
 		...CODE_COLORS
@@ -160,19 +482,17 @@ glaze.configure({
 	darkDesaturation: 0
 });
 /**
-* Per-colored-theme overrides on top of the default theme:
-*   - `surface` — bumped saturation so the banner bg is visibly tinted.
-*   - `border`  — bumped saturation so OUTLINE-variant borders pick up the
-*     theme hue (used by `#<theme>-border` in `item-themes.ts`). Mirrors the
-*     default-theme `border` shape (`base: 'surface'`, tone window) but
-*     with higher saturation. Glaze's `extend({ colors })` redefines each
-*     listed color from scratch, so we restate the full definition here.
+* The config-free half of a colored theme's overrides — everything anchored to
+* the theme's own `surface` with a *relative* tone, so it follows wherever
+* {@link tintedSurfaceTone} puts that surface.
+*
+*   - `border` — bumped saturation so OUTLINE-variant borders pick up the theme
+*     hue (used by `#<theme>-border` in `item-themes.ts`). Mirrors the
+*     default-theme `border` shape (`base: 'surface'`, tone window) but with
+*     higher saturation. Glaze's `extend({ colors })` redefines each listed color
+*     from scratch, so we restate the full definition here.
 */
-const TINTED_SURFACE_OVERRIDE = {
-	surface: {
-		tone: [100 - TINTED_SURFACE_TONE_OFFSET, 100 - TINTED_SURFACE_TONE_OFFSET * 2],
-		saturation: TINTED_SURFACE_SATURATION
-	},
+const TINTED_SURFACE_RAMP = {
 	border: {
 		base: "surface",
 		tone: ["-10", "-30"],
@@ -198,13 +518,31 @@ const TINTED_SURFACE_OVERRIDE = {
 	}
 };
 /**
+* Per-colored-theme overrides on top of the default theme: a `surface` bumped in
+* saturation so the banner background is visibly tinted, plus
+* {@link TINTED_SURFACE_RAMP}.
+*
+* A function of the config because the surface's tone is — see
+* {@link tintedSurfaceTone}.
+*/
+function tintedSurfaceOverride(config) {
+	return {
+		surface: {
+			tone: tintedSurfaceTone(config),
+			saturation: TINTED_SURFACE_SATURATION
+		},
+		...TINTED_SURFACE_RAMP
+	};
+}
+/**
 * A tinted surface, a banding step, and text guaranteed to read on both.
 *
 * The recipe behind {@link getColorTheme} in `./color-theme.ts`, which builds
 * one-off themes at runtime from an arbitrary hue. It lives here so it shares
 * `TINTED_SURFACE_SATURATION`, the tone offsets and the text ramp with
-* {@link TINTED_SURFACE_OVERRIDE} above rather than forking them — a runtime tint
-* and a built-in theme's `surface` should be the same colour for the same hue.
+* {@link tintedSurfaceOverride} above rather than forking them — a runtime tint
+* and a built-in theme's `surface` should be the same colour for the same hue,
+* which also means both have to follow the page when `surfaceMode` moves it.
 *
 * Three colours, because that is what banded, readable table column needs:
 * `surface` for even rows, `surface-2` one tone step down for odd rows and
@@ -216,29 +554,185 @@ const TINTED_SURFACE_OVERRIDE = {
 * clears it on both bands. The neutral ramp's own `surface-2-text` is shaped the
 * same way for the same reason.
 */
-const TINT_RECIPE = {
-	surface: {
-		tone: [100 - TINTED_SURFACE_TONE_OFFSET, 100 - TINTED_SURFACE_TONE_OFFSET * 2],
-		saturation: TINTED_SURFACE_SATURATION
-	},
-	"surface-2": {
-		base: "surface",
-		tone: ["-2", "-4"],
-		saturation: TINTED_SURFACE_SATURATION
-	},
-	"surface-2-text": {
-		base: "surface-2",
-		tone: `${TEXT_TONE - TINTED_SURFACE_TONE_OFFSET - SURFACE_2_TEXT_OFFSET}`,
-		saturation: .25,
-		contrast: ["AA", "AAA"]
-	},
-	"surface-2-text-soft": {
-		base: "surface-2",
-		tone: `${TEXT_SOFT_TONE - TINTED_SURFACE_TONE_OFFSET - SURFACE_2_TEXT_OFFSET}`,
-		saturation: .25,
-		contrast: ["AA", "AAA"]
-	}
-};
+function tintRecipe(config) {
+	return {
+		surface: {
+			tone: tintedSurfaceTone(config),
+			saturation: TINTED_SURFACE_SATURATION
+		},
+		"surface-2": {
+			base: "surface",
+			tone: ["-2", "-4"],
+			saturation: TINTED_SURFACE_SATURATION
+		},
+		"surface-2-text": {
+			base: "surface-2",
+			tone: `${TEXT_TONE - TINTED_SURFACE_TONE_OFFSET - SURFACE_2_TEXT_OFFSET}`,
+			saturation: .25,
+			contrast: ["AA", "AAA"]
+		},
+		"surface-2-text-soft": {
+			base: "surface-2",
+			tone: `${TEXT_SOFT_TONE - TINTED_SURFACE_TONE_OFFSET - SURFACE_2_TEXT_OFFSET}`,
+			saturation: .25,
+			contrast: ["AA", "AAA"]
+		}
+	};
+}
+/**
+* The brand family, in one of two arrangements.
+*
+* **`null`** — the shipped one, verbatim. Every fill hangs off a fixed white
+* `accent-surface-text` at a relative tone delta behind an `['AA','AAA']` floor, and
+* the text pair hangs off `accent-selected-fill` at `-49`. Those floors are
+* load-bearing rather than decorative: relaxing them moves the shipped `accent-text`
+* light tone from 38.76 to 48.63 and the `accent-surface` high-contrast tone from
+* 36.08 to 51.00. Nothing on this path may change — `palette.test.ts` snapshots it.
+*
+* **A color** — the caller handed us one, and the job is to render *that*. Glaze's
+* `from` takes the value directly: it supplies the hue, the tone, and an absolute
+* saturation that does not answer to the theme seed, and it reproduces the value
+* exactly in the light/normal-contrast variant. The floors drop to
+* {@link ACCENT_FILL_CONTRAST} on top, because anchored the shipped way every accent
+* lands at roughly tone 50 whatever went in, and a 4.5 floor then crushes anything
+* light besides.
+*
+* Two details worth keeping straight:
+*
+* - **The ramp carries no floor.** Re-anchored onto the fill, an `['AA','AAA']` floor
+*   is measured against the *fill* rather than white and collapses all three steps to
+*   near-black. A plain tone step is what the relationship actually is.
+* - **The text pair stays `mode: 'auto'`.** Link text has to invert on a dark page, so
+*   exactness belongs to the fill; the text is a brand-toned companion of it.
+*/
+function accentFillColors(accent) {
+	if (accent == null) return {
+		"accent-surface-text": {
+			tone: 100,
+			mode: "fixed"
+		},
+		"accent-surface": {
+			base: "accent-surface-text",
+			tone: "-49",
+			contrast: ["AA", "AAA"],
+			mode: "fixed"
+		},
+		"accent-surface-2": {
+			base: "accent-surface-text",
+			tone: "-52",
+			contrast: ["AA", "AAA"],
+			mode: "fixed"
+		},
+		"accent-surface-3": {
+			base: "accent-surface-text",
+			tone: "-55",
+			contrast: ["AA", "AAA"],
+			mode: "fixed"
+		},
+		"accent-surface-hover": {
+			base: "accent-surface-text",
+			tone: "-58",
+			contrast: ["AA", "AAA"],
+			mode: "fixed"
+		},
+		"accent-surface-border": {
+			base: "accent-surface",
+			tone: "+13",
+			mode: "fixed"
+		}
+	};
+	return {
+		"accent-surface-text": {
+			tone: 100,
+			mode: "fixed"
+		},
+		"accent-surface": {
+			from: accent.color,
+			base: "surface",
+			contrast: ACCENT_FILL_CONTRAST,
+			mode: "fixed"
+		},
+		"accent-surface-2": {
+			base: "accent-surface",
+			tone: ACCENT_RAMP.surface2,
+			mode: "fixed"
+		},
+		"accent-surface-3": {
+			base: "accent-surface",
+			tone: ACCENT_RAMP.surface3,
+			mode: "fixed"
+		},
+		"accent-surface-hover": {
+			base: "accent-surface",
+			tone: ACCENT_RAMP.hover,
+			mode: "fixed"
+		},
+		"accent-surface-border": {
+			base: "accent-surface",
+			tone: "+13",
+			mode: "fixed"
+		}
+	};
+}
+/**
+* The brand FOREGROUNDS — text on a neutral surface, and the icon.
+*
+* Split from {@link accentFillColors} because the two have different audiences: the
+* fill ramp is shared with the standalone `special` theme, which builds its own
+* purpose-made subset and must not gain tokens it does not consume. Only the default
+* theme (and the colored themes that inherit from it) takes these.
+*
+* These stay `mode: 'auto'` in both arrangements — a link has to invert on a dark page,
+* so exactness belongs to the fill and these are its brand-toned companions.
+*/
+function accentTextColors(accent) {
+	if (accent == null) return {
+		...ACCENT_SELECTED_FILL,
+		"accent-text": {
+			base: "accent-selected-fill",
+			tone: "-49",
+			saturation: 1,
+			contrast: [6, 11]
+		},
+		"accent-text-soft": {
+			base: "accent-selected-fill",
+			tone: "-49",
+			saturation: 1,
+			contrast: ["AA", "AAA"]
+		},
+		"accent-icon": {
+			base: "surface",
+			tone: "-38",
+			saturation: .9375
+		}
+	};
+	return {
+		...ACCENT_SELECTED_FILL,
+		"accent-text": {
+			from: accent.color,
+			base: "accent-selected-fill",
+			tone: Math.max(0, accent.tone - ACCENT_TEXT_HOVER_STEP),
+			contrast: ACCENT_TEXT_HOVER_CONTRAST
+		},
+		"accent-text-soft": {
+			from: accent.color,
+			base: "accent-selected-fill",
+			contrast: ACCENT_TEXT_CONTRAST
+		},
+		"accent-icon": {
+			from: accent.color,
+			base: "surface",
+			contrast: ACCENT_TEXT_CONTRAST
+		}
+	};
+}
+/** Every accent token the default theme carries — fills, foregrounds, and the mix. */
+function accentColors(accent) {
+	return {
+		...accentFillColors(accent),
+		...accentTextColors(accent)
+	};
+}
 /**
 * Build the full palette from a resolved config.
 *
@@ -248,7 +742,11 @@ const TINT_RECIPE = {
 * seed and a `GlazePalette` has no mutation API, so re-seeding means rebuilding.
 */
 function buildPalette(config, options = {}) {
-	const { hue, baseHue, saturation, pastel, themes, contrastLevel } = config;
+	const { hue, baseHue, saturation, accentColor, accentTone, accentSaturation, pastel, themes, contrastLevel } = config;
+	const accent = accentColor !== null && accentTone !== null && accentSaturation !== null ? cappedAccent(hue, accentSaturation, accentTone) : null;
+	const baseTone = surfaceTone(config);
+	const baseScale = baseSaturationScale(config);
+	const baseChroma = (factor) => Math.min(1, factor * baseScale);
 	const sharedOverrides = options.isolateContrastLevel ? { contrastLevel } : {};
 	const overrides = {
 		...sharedOverrides,
@@ -262,43 +760,43 @@ function buildPalette(config, options = {}) {
 	const defaultTheme = glaze(hue, saturation, instanceConfig);
 	defaultTheme.colors({
 		surface: {
-			tone: 100,
-			saturation: SURFACE_SATURATION,
+			tone: baseTone,
+			saturation: baseChroma(SURFACE_SATURATION),
 			hue: baseHue
 		},
 		"surface-2": {
 			hue: baseHue,
 			base: "surface",
 			tone: ["-2", "-4"],
-			saturation: .1,
+			saturation: baseChroma(.1),
 			inherit: false
 		},
 		"surface-3": {
 			hue: baseHue,
 			base: "surface",
 			tone: ["-4", "-8"],
-			saturation: .1,
+			saturation: baseChroma(.1),
 			inherit: false
 		},
 		"surface-4": {
 			hue: baseHue,
 			base: "surface",
 			tone: ["-6", "-12"],
-			saturation: .1,
+			saturation: baseChroma(.1),
 			inherit: false
 		},
 		"surface-text": {
 			hue: baseHue,
 			base: "surface",
 			tone: `${TEXT_TONE - 2}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"]
 		},
 		"surface-text-soft": {
 			hue: baseHue,
 			base: "surface",
 			tone: `${TEXT_SOFT_TONE - 2}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"],
 			inherit: false
 		},
@@ -306,7 +804,7 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface",
 			tone: `${TEXT_SOFT2_TONE - 2}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"],
 			inherit: false
 		},
@@ -314,7 +812,7 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface-2",
 			tone: `${TEXT_TONE + SURFACE_2_TEXT_OFFSET}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"],
 			inherit: false
 		},
@@ -322,7 +820,7 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface-2",
 			tone: `${TEXT_SOFT_TONE + SURFACE_2_TEXT_OFFSET}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"],
 			inherit: false
 		},
@@ -330,7 +828,7 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface-3",
 			tone: `${TEXT_TONE + SURFACE_3_TEXT_OFFSET}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"],
 			inherit: false
 		},
@@ -338,7 +836,7 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface-3",
 			tone: `${TEXT_SOFT_TONE + SURFACE_3_TEXT_OFFSET}`,
-			saturation: .2,
+			saturation: baseChroma(.2),
 			contrast: ["AA", "AAA"],
 			inherit: false
 		},
@@ -346,13 +844,13 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface",
 			tone: ["-10", "-30"],
-			saturation: .175
+			saturation: baseChroma(.175)
 		},
 		placeholder: {
 			hue: baseHue,
 			base: "surface",
 			tone: "-33",
-			saturation: .175,
+			saturation: baseChroma(.175),
 			inherit: false
 		},
 		focus: {
@@ -370,7 +868,7 @@ function buildPalette(config, options = {}) {
 			hue: baseHue,
 			base: "surface",
 			tone: "-3.5",
-			saturation: .2,
+			saturation: baseChroma(.2),
 			inherit: false
 		},
 		"disabled-surface-text": {
@@ -382,67 +880,11 @@ function buildPalette(config, options = {}) {
 		"surface-inverse": {
 			hue: baseHue,
 			tone: 12,
-			saturation: .475,
+			saturation: baseChroma(.475),
 			mode: "fixed",
 			inherit: false
 		},
-		"accent-surface-text": {
-			tone: 100,
-			mode: "fixed"
-		},
-		"accent-surface": {
-			base: "accent-surface-text",
-			tone: "-49",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-2": {
-			base: "accent-surface-text",
-			tone: "-52",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-3": {
-			base: "accent-surface-text",
-			tone: "-55",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-hover": {
-			base: "accent-surface-text",
-			tone: "-58",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-border": {
-			base: "accent-surface",
-			tone: "+13",
-			mode: "fixed"
-		},
-		"accent-selected-fill": {
-			type: "mix",
-			base: "surface",
-			target: "accent-surface",
-			value: 9,
-			space: "srgb"
-		},
-		"accent-text": {
-			base: "accent-selected-fill",
-			tone: "-49",
-			saturation: 1,
-			contrast: [6, 11]
-		},
-		"accent-text-soft": {
-			base: "accent-selected-fill",
-			tone: "-49",
-			saturation: 1,
-			contrast: ["AA", "AAA"]
-		},
-		"accent-icon": {
-			base: "surface",
-			tone: "-38",
-			saturation: .9375
-		},
+		...accentColors(accent),
 		"accent-disabled-surface": {
 			base: "surface",
 			tone: "-13",
@@ -455,22 +897,33 @@ function buildPalette(config, options = {}) {
 			saturation: .4,
 			mode: "fixed"
 		},
+		"accent-disabled-text": {
+			base: "surface",
+			tone: "-23",
+			saturation: .6
+		},
 		"loading-face-1": {
+			hue: baseHue,
 			base: "surface",
 			tone: "-2",
-			saturation: .3,
+			saturation: baseChroma(.2),
+			contrast: [1.2, 1.35],
 			inherit: false
 		},
 		"loading-face-2": {
+			hue: baseHue,
 			base: "surface",
-			tone: "-9",
-			saturation: .62,
+			tone: "-2",
+			saturation: baseChroma(.2),
+			contrast: [1.65, 2.1],
 			inherit: false
 		},
 		"loading-face-3": {
+			hue: baseHue,
 			base: "surface",
-			tone: "-21",
-			saturation: .66,
+			tone: "-2",
+			saturation: baseChroma(.2),
+			contrast: [2.4, 3.2],
 			inherit: false
 		},
 		"shadow-sm": {
@@ -501,26 +954,59 @@ function buildPalette(config, options = {}) {
 			hue: baseHue
 		}
 	});
-	const primaryTheme = defaultTheme.extend({ colors: TINTED_SURFACE_OVERRIDE });
+	const tintedSurface = tintedSurfaceOverride(config);
+	const primaryTheme = defaultTheme.extend({ colors: tintedSurface });
+	/**
+	* One status theme's overrides, on whichever path its own seed is on.
+	*
+	* **Its own color** — the family becomes that color, exactly as the accent zone's does,
+	* so the softened APCA floors in `accentColors`' color arm come with it rather than
+	* being restated here. The theme's Glaze seed is the color's chroma (see
+	* `ResolvedThemeSeed.saturation`), so the tinted surface, the border and the text ramp
+	* re-solve at their shipped factors OF that chroma — the banner keeps its proportion to
+	* the button instead of drifting relative to a fill whose chroma arrives absolute.
+	*
+	* **No color of its own, but the ACCENT has one** — the accent color's tone is taken
+	* back out. The tone is the brand's, and only the brand's. Inherited, a light brand
+	* would put `#danger-accent-surface` at tone 88 in a red hue — a pale pink danger
+	* button, which is not a danger button. A status theme carries a *meaning* its hue
+	* exists to signal, so absent an instruction of its own it keeps the white-anchored
+	* derivation that lands every hue at a comparable weight. `extend({ colors })`
+	* redefines each listed color from scratch, so restating the null arrangement is enough
+	* to undo it.
+	*
+	* **Neither** — the tinted-surface override itself, so the shipped palette is provably
+	* untouched.
+	*/
+	const statusColors = (theme) => {
+		if (theme.color !== null && theme.colorTone !== null) return {
+			...tintedSurface,
+			...accentColors(cappedAccent(theme.hue, theme.saturation, theme.colorTone))
+		};
+		return accent == null ? tintedSurface : {
+			...tintedSurface,
+			...accentColors(null)
+		};
+	};
 	const successTheme = defaultTheme.extend({
 		hue: themes.success.hue,
 		saturation: themes.success.saturation,
-		colors: TINTED_SURFACE_OVERRIDE
+		colors: statusColors(themes.success)
 	});
 	const dangerTheme = defaultTheme.extend({
 		hue: themes.danger.hue,
 		saturation: themes.danger.saturation,
-		colors: TINTED_SURFACE_OVERRIDE
+		colors: statusColors(themes.danger)
 	});
 	const warningTheme = defaultTheme.extend({
 		hue: themes.warning.hue,
 		saturation: themes.warning.saturation,
-		colors: TINTED_SURFACE_OVERRIDE
+		colors: statusColors(themes.warning)
 	});
 	const noteTheme = defaultTheme.extend({
 		hue: themes.note.hue,
 		saturation: themes.note.saturation,
-		colors: TINTED_SURFACE_OVERRIDE
+		colors: statusColors(themes.note)
 	});
 	const specialTheme = glaze(hue, saturation, instanceConfig);
 	specialTheme.colors({
@@ -529,39 +1015,7 @@ function buildPalette(config, options = {}) {
 			saturation: .475,
 			mode: "fixed"
 		},
-		"accent-surface-text": {
-			tone: 100,
-			mode: "fixed"
-		},
-		"accent-surface": {
-			base: "accent-surface-text",
-			tone: "-49",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-2": {
-			base: "accent-surface-text",
-			tone: "-52",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-3": {
-			base: "accent-surface-text",
-			tone: "-55",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
-		"accent-surface-border": {
-			base: "accent-surface",
-			tone: "+13",
-			mode: "fixed"
-		},
-		"accent-surface-hover": {
-			base: "accent-surface-text",
-			tone: "-58",
-			contrast: ["AA", "AAA"],
-			mode: "fixed"
-		},
+		...accentFillColors(accent),
 		"accent-text": {
 			base: "accent-surface-text",
 			tone: "-58",
@@ -750,5 +1204,5 @@ function renderPaletteTokens(options = {}) {
 const PALETTE_TOKENS = lazyStyles(getPaletteTokens);
 
 //#endregion
-export { PALETTE_TOKENS, TINT_RECIPE, getCodeTheme, getPalette, getPaletteTokens, renderPaletteTokens };
+export { PALETTE_TOKENS, getCodeTheme, getPalette, getPaletteTokens, renderPaletteTokens, tintRecipe };
 //# sourceMappingURL=palette.js.map