@cube-dev/ui-kit 0.0.0-canary-8d79305 → 0.0.0-canary-ed0ffec

package/docs/Theming.md

@@ -1,20 +1,25 @@
 # Theming
 
-The whole palette is generated by [Glaze](https://github.com/tenphi/glaze) from a
-handful of seeds: an accent hue, a base hue, a saturation, and a hue per status
-theme. Those seeds are tunable at runtime — change one and every token re-resolves, in light,
+The whole palette is generated by [Glaze](https://github.com/tenphi/glaze) from a handful
+of seeds, one per **zone**: the accent, the base, and each of the four status themes.
+Those seeds are tunable at runtime — change one and every token re-resolves, in light,
 dark, and high-contrast schemes at once.
 
-The accent and base zones can each be seeded by a **color** instead of a hue, which is
-usually what you have: `accentColor: '#2F5BFF'` rather than `hue: 266`. See
-[Two zones, two ways to seed them](#two-zones-two-ways-to-seed-them).
+Every zone takes the same seed, and it comes in two forms: a **color**, which is usually
+what you actually have, or the **numbers** behind one. Never both — a zone is seeded one
+way or the other. See [One seed, two ways to spell it](#one-seed-two-ways-to-spell-it).
 
 ```ts
 import { setPaletteConfig } from '@cube-dev/ui-kit';
 
 setPaletteConfig({
-  hue: 210,
-  saturation: 72,
+  accent: '#2F5BFF',
+  themes: { danger: '#b91c1c' },
+});
+
+// The same shape, said in numbers.
+setPaletteConfig({
+  accent: { hue: 210, saturation: 72 },
   themes: { danger: { hue: 12 } },
 });
 ```
@@ -25,20 +30,22 @@ value so this stays true.
 
 ## What is tunable
 
-| Option                       | Scope                                                                                                                                                                 | Default                             |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `accentColor`                | **Accent** zone seeded by a color. Derives the hue, the saturation (with `pastel` off) and the accent **tone**, so the brand fill renders as the color you passed.    | unset                               |
-| `baseColor`                  | **Base** zone seeded by a color. Hue **and saturation** (clipped to 50); its tone is discarded.                                                                       | unset                               |
-| `hue`                        | **Accent** hue in degrees — the brand. Drives the `accent-*` family, `primary` / `purple` / `special`, and the brand-tinted `focus`, loading faces and disabled chip. | `280.3`                             |
-| `baseHue`                    | **Base** hue in degrees — the neutral chrome: `surface` and its ladder, the `surface-text*` ramp, `border`, `placeholder`.                                            | inherits `hue`                      |
-| `saturation`                 | Seed saturation (0–100) for the `default` theme, and the fallback for every theme that sets none. Setting it **turns `pastel` off**, which is the path it belongs to. | `100`                               |
-| `baseSaturation`             | Seed saturation (0–100) of the **base** zone — the same family `baseHue` governs. On the same scale as `saturation`; the shipped chrome is `12`.                      | `baseColor`'s, clipped to 50, else `(accentColor ?? saturation) × 0.12` |
-| `surfaceMode`                | Global. `'tinted'` moves the neutral surface ramp two tones off the end of the tone scale, which is what gives `baseSaturation` room to reach the page surface.        | `'neutral'`                         |
-| `themes.<status>.hue`        | Hue for `success` / `danger` / `warning` / `note`.                                                                                                                    | `156.9` / `23.1` / `84.3` / `302.3` |
-| `themes.<status>.saturation` | Saturation for that status theme.                                                                                                                                     | inherits `saturation`               |
-| `themes.code.saturation`     | Saturation for the `code-*` syntax family. Hues are fixed, and this does **not** inherit `saturation`, nor track its default.                                         | `80`                                |
-| `pastel`                     | Global. Relaxes the sRGB-safe chroma limit, and **pins `saturation` to 100**. Wins wherever both are set. Every theme except `code`.                                  | `true`                              |
-| `contrastLevel`              | Global. `'auto'`, or a manual `0`–`100` level.                                                                                                                        | `'auto'`                            |
+Every zone below takes a `PaletteSeed`: either a color string, or `{ hue?, saturation? }`.
+
+| Option                       | Scope                                                                                                                                                                                       | Default                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `accent`                     | The **accent** zone — the brand. Drives the `accent-*` family on every theme, `primary` / `purple` / `special`, and the brand-tinted `focus`, loading faces and disabled chip.               | `{ hue: 280.3 }`                    |
+| `accent` as a color          | Contributes hue, chroma **and tone**, so the brand fill renders as the color you passed. Its chroma reaches the accent family through Glaze's `from`, not through the zone's seed.           | unset                               |
+| `accent.saturation`          | Seed saturation (0–100) for the `default` theme, and the fallback every status theme inherits. Setting it **turns `pastel` off**, which is the path it belongs to.                            | `100`                               |
+| `base`                       | The **base** zone — the neutral chrome: `surface` and its ladder, the `surface-text*` ramp, `border`, `placeholder`. Omit it and the zone follows the accent.                                 | follows `accent`                    |
+| `base` as a color            | Contributes hue **and saturation**, clipped to 50; its tone is discarded.                                                                                                                    | unset                               |
+| `base.saturation`            | Seed saturation (0–100) of the base zone, on the same scale as the accent's. The shipped chrome is `12`.                                                                                      | `(accent's chroma) × 0.12`          |
+| `themes.<status>`            | Seed for `success` / `danger` / `warning` / `note`.                                                                                                                                          | `156.9` / `23.1` / `84.3` / `302.3` |
+| `themes.<status>` as a color | All three components, and its chroma **does** become the theme's seed — unlike the accent's. See [Status themes](#status-themes).                                                             | unset                               |
+| `themes.code.saturation`     | Saturation for the `code-*` syntax family. Hues are fixed, it takes no color, and it does **not** inherit the accent's saturation nor track its default.                                      | `80`                                |
+| `surfaceMode`                | Global. `'tinted'` moves the neutral surface ramp two tones off the end of the tone scale, which is what gives the base saturation room to reach the page surface.                            | `'neutral'`                         |
+| `pastel`                     | Global. Relaxes the sRGB-safe chroma limit, and **pins the accent's saturation to 100**. Wins wherever both are set. Every theme except `code`.                                              | `true`                              |
+| `contrastLevel`              | Global. `'auto'`, or a manual `0`–`100` level.                                                                                                                                              | `'auto'`                            |
 
 ### The setter replaces
 
@@ -47,8 +54,8 @@ config you pass **is** the config, resolved against the shipped defaults. Nothin
 accumulates, so removing a customization means removing it from the object:
 
 ```ts
-setPaletteConfig({ hue: 200, baseHue: 60 });
-setPaletteConfig({ hue: 200 }); // baseHue is gone — back to inheriting `hue`
+setPaletteConfig({ accent: { hue: 200 }, base: { hue: 60 } });
+setPaletteConfig({ accent: { hue: 200 } }); // `base` is gone — follows accent again
 ```
 
 That is what makes the config safe to keep in your own state and re-apply: the
@@ -60,9 +67,14 @@ pass an updater. It receives the config **as written**, sparse, so spreading it
 preserves which fields are pinned and which still inherit:
 
 ```ts
-setPaletteConfig((config) => ({ ...config, saturation: 55 }));
+// A zone holds ONE seed, so a one-field control spreads that seed too — writing a bare
+// `{ hue }` would unpin the saturation beside it.
+setPaletteConfig((config) => ({
+  ...config,
+  accent: { ...config.accent, saturation: 55 },
+}));
 
-// Nested seeds need their own spread, or the other themes go with them.
+// Nested seeds need their own spread as well, or the other themes go with them.
 setPaletteConfig((config) => ({
   ...config,
   themes: { ...config.themes, warning: { saturation: 95 } },
@@ -72,63 +84,84 @@ setPaletteConfig((config) => ({
 `resetPaletteConfig()` drops all tuning at once — the same as
 `setPaletteConfig({})`, just easier to read at a call site.
 
-### Two zones, two ways to seed them
+### One seed, two ways to spell it
 
-Hue is split into an **accent** zone and a **base** zone:
+Every zone takes the same `PaletteSeed`, and it comes in two forms:
 
-- **Accent** (`hue` / `accentColor`) — the `accent-*` family on every theme, `primary` /
-  `purple` / `special`, plus `focus`, the loading faces and the disabled chip.
-- **Base** (`baseHue` / `baseColor`) — the neutral chrome: `surface` and its ladder, the
-  `surface-text*` ramp, `border`, `placeholder`.
+```ts
+type PaletteSeed = string | { hue?: number; saturation?: number };
+```
 
-`baseHue` inherits `hue`, so out of the box the chrome carries a faint tint of the
-brand. Set it to decouple them — a warm grey UI under a cool blue brand:
+A string is a color — anything Glaze parses: hex, `rgb()`, `hsl()`, `okhsl()`, `okhst()`,
+`oklch()`. CSS color keywords (`rebeccapurple`) are not supported; an unparseable value
+warns once and falls back to the numeric path.
+
+**The union is the exclusivity.** A zone is seeded one way or the other — there is no
+precedence rule to learn, and no way to write a hue that half-overrides a hex. A patch
+that switches form therefore *replaces* rather than merges; layering happens within a
+path:
 
 ```ts
-setPaletteConfig({ hue: 235, baseHue: 60 });
+setPaletteConfig({ accent: '#2F5BFF' });
+// A number arriving next to that takes the zone over, tone and all.
+setPaletteConfig((config) => ({ ...config, accent: { hue: 300 } }));
 ```
 
-Only the `default` theme is affected. A colored theme's tinted `surface`
-deliberately follows _its own_ hue, because a danger banner should read as red.
+#### The zones
+
+- **Accent** (`accent`) — the `accent-*` family on every theme, `primary` / `purple` /
+  `special`, plus `focus`, the loading faces and the disabled chip. Its saturation is
+  also the fallback every status theme inherits.
+- **Base** (`base`) — the neutral chrome: `surface` and its ladder, the `surface-text*`
+  ramp, `border`, `placeholder`.
+- **Status** (`themes.success` / `danger` / `warning` / `note`) — one seed each. See
+  [Status themes](#status-themes).
+- **Syntax** (`themes.code`) — the exception: a saturation and nothing else. See
+  [The `code-*` family is the exception](#the-code--family-is-the-exception).
 
-Either zone can take a **color** instead, which is usually the form a brand arrives in.
-Anything Glaze parses works — hex, `rgb()`, `hsl()`, `okhsl()`, `okhst()`, `oklch()`.
-CSS color keywords (`rebeccapurple`) are not supported; an unparseable value warns and
-falls back to the numeric seed.
+Omit `base` and the chrome follows the accent, so out of the box the greys carry a faint
+tint of the brand. Seed it to decouple them — a warm grey UI under a cool blue brand:
 
 ```ts
-setPaletteConfig({ accentColor: '#2F5BFF', baseColor: '#7A7269' });
+setPaletteConfig({ accent: { hue: 235 }, base: { hue: 60 } });
 ```
 
-The two are not symmetric, and the difference is the point:
+Only the `default` theme is affected. A colored theme's tinted `surface` deliberately
+follows _its own_ hue, because a danger banner should read as red.
 
-- `accentColor` contributes hue, saturation **and tone**. The tone is what makes the
-  brand fill actually _be_ your color. Without it the fill is authored as a fixed tone
-  step off white, so every accent hue lands at roughly the same lightness — a yellow
-  brand comes out olive. The chroma reaches the accent family through Glaze's `from`
-  rather than through the `saturation` seed, which is what stops a brand from
-  re-chromatising the chrome and the status themes.
-- `baseColor` contributes **hue and saturation**; its **tone** is discarded, because the
-  chrome's own lightness ladder is the design. A base color says which way the greys lean
-  and how far, not how dark they are.
+#### What a color contributes, per zone
 
-The base color's saturation is **clipped to 50**. Naming a base color says "the chrome
-_is_ this color", so it lands near it rather than at the 12% share `baseSaturation`
-otherwise inherits — but a fully saturated chrome stops being chrome, and the base colors
-begin to converge above 25 anyway (see [Tinted surfaces](#tinted-surfaces)). The tuner's
-manual slider shares the same ceiling, so the two routes agree on what the top of the
-range means.
+The same string means slightly different things by zone, and the differences are the
+point:
 
 ```ts
-setPaletteConfig({ baseColor: '#6e7076' }); // near-grey in, near-grey chrome out
-setPaletteConfig({ baseColor: '#FFD400' }); // saturation 100 in, clipped to 50
+setPaletteConfig({ accent: '#2F5BFF', base: '#7A7269' });
 ```
 
-The numeric fields still win where both are set, and the tone keeps coming from the
-color either way — so a preview can rotate the hue without losing the brand's lightness:
+- **Accent** — hue, chroma **and tone**. The tone is what makes the brand fill actually
+  _be_ your color. Without it the fill is authored as a fixed tone step off white, so
+  every accent hue lands at roughly the same lightness — a yellow brand comes out olive.
+  The chroma reaches the accent family through Glaze's `from` rather than through the
+  zone's seed, which is what stops a brand from re-chromatising the chrome and all four
+  status themes.
+- **Base** — hue and saturation; the **tone is discarded**, because the chrome's own
+  lightness ladder is the design. A base color says which way the greys lean and how far,
+  not how dark they are.
+- **Status** — hue, chroma and tone, and its chroma **does** become that theme's seed.
+  Nothing inherits from a status theme, so there is nothing to re-chromatise, and moving
+  the seed is what keeps the banner in proportion to the button.
+
+The base color's saturation is **clipped to 50**. Naming a base color says "the chrome
+_is_ this color", so it lands near it rather than at the 12% share it would otherwise
+inherit — but a fully saturated chrome stops being chrome, and the base colors begin to
+converge above 25 anyway (see [Tinted surfaces](#tinted-surfaces)). The tuner's manual
+slider shares the same ceiling, so the two routes agree on what the top of the range
+means. A base **number** is not clipped: a number is the more specific instruction.
 
 ```ts
-setPaletteConfig({ accentColor: '#2F5BFF', hue: 300 }); // hue 300, tone still #2F5BFF's
+setPaletteConfig({ base: '#6e7076' }); // near-grey in, near-grey chrome out
+setPaletteConfig({ base: '#FFD400' }); // saturation 100 in, clipped to 50
+setPaletteConfig({ base: { saturation: 100 }, pastel: false }); // 100 stays 100
 ```
 
 ### A color seed is a request
@@ -165,61 +198,66 @@ across hues, and it sits below where a saturated color would land, so under it a
 seed can never resolve to itself: `#EF4444` renders `#c47069`. Under pastel the color
 contributes its hue and its tone; turn pastel off to get its chroma too.
 
+All of it applies per zone. A status color answers to the same two floors on its own
+`#<theme>-accent-surface`, including the label cap — every `type="primary"` item on a
+status theme paints `#white` on that fill too, so a pale `danger` color is pulled down
+rather than shipped as a white label on white.
+
 Read the result back from the tokens themselves — `#accent-surface` is the fill,
 `#accent-text-soft` the rest link color — or watch the requested/resolved chips in the
 [Theme builder](#theme-builder).
 
 ### One saturation scale per theme
 
-Saturation is _not_ split per token, deliberately: `saturation` is the theme's
-**seed**, and every color's own `saturation` is a 0–1 factor of it. `surface` sits
-at `0.12`, `border` at `0.175`, the text ramp at `0.2`, the accent family at
-~`1.0`.
+Saturation is _not_ split per token, deliberately: a zone's `saturation` is its theme's
+**seed**, and every color's own `saturation` is a 0–1 factor of it. `surface` sits at
+`0.12`, `border` at `0.175`, the text ramp at `0.2`, the accent family at ~`1.0`.
 
-So the palette has one saturation _scale_, and everything on it keeps its
-proportions: turning `saturation` down mutes the brand fills and the neutral tint
-together, in the ratios the palette was designed around. That is the point — the
-relationship between a subtle surface tint and a saturated accent is part of the
-design, not something to tune per token.
+So a theme has one saturation _scale_, and everything on it keeps its proportions:
+turning the seed down mutes the brand fills and the neutral tint together, in the ratios
+the palette was designed around. That is the point — the relationship between a subtle
+surface tint and a saturated accent is part of the design, not something to tune per
+token. It is also why a status **color** takes over its theme's seed rather than reaching
+only its fill: chroma arriving absolutely through `from` while the seed stayed put is
+exactly how those ratios come apart.
 
-The one seam is the **base zone**, and it is the same seam `baseHue` opens: the
-chrome is the one family whose job is _not_ to look like the brand. `baseSaturation`
-gives it its own seed, on the same 0–100 scale, so a vivid accent over near-grey
-chrome — or a muted accent over visibly warm chrome — is one number rather than a
-choice between them:
+The one seam is the **base zone**, and it is the same seam its own hue opens: the chrome
+is the one family whose job is _not_ to look like the brand. `base.saturation` gives it
+its own seed, on the same 0–100 scale, so a vivid accent over near-grey chrome — or a
+muted accent over visibly warm chrome — is one number rather than a choice between them:
 
 ```ts
-setPaletteConfig({ pastel: false, saturation: 90, baseSaturation: 3 });
+setPaletteConfig({ accent: { saturation: 90 }, base: { saturation: 3 } });
 ```
 
 Unset, it takes `0.12` — `surface`'s own factor — of whatever the accent zone carries:
-the `saturation` seed, or an `accentColor`'s own chroma when one is set. So leaving it
-alone reproduces the shipped palette exactly, a muted `saturation` still mutes the
-chrome along with everything else, and a near-grey brand hex leaves near-grey chrome
-rather than 12% of a saturation nobody asked for. A `baseColor` overrides all of that
-with its own, clipped to 50.
+its seed saturation, or an accent color's own chroma when one is set. So leaving it alone
+reproduces the shipped palette exactly, a muted accent still mutes the chrome along with
+everything else, and a near-grey brand hex leaves near-grey chrome rather than 12% of a
+saturation nobody asked for. A base color overrides all of that with its own, clipped to
+50.
 
 **The shipped value is `12`** — a faint tint is what a neutral surface _is_ — so the
 interesting range is the low end. The base colors keep their proportions to one another
 until the highest of them (`0.475`, `surface-inverse`) hits the top of the scale, around
 `25`; past that they converge.
 
-Note the asymmetry with `saturation`: writing `baseSaturation` does **not** turn
-`pastel` off. How much hue the chrome carries says nothing about which chroma space
-the palette is in.
+Note the asymmetry with the accent's saturation: writing the base's does **not** turn
+`pastel` off. How much hue the chrome carries says nothing about which chroma space the
+palette is in.
 
 ### Tinted surfaces
 
 A neutral `surface` sits at the extreme of the tone scale — pure white in light,
 the darkest step the dark tone window allows in dark. Chroma needs distance from
-the extreme to exist at all, so on a light page `surface` is white whatever
-`baseSaturation` asks for. The base seed reaches `surface-2`…`surface-4`, `border`,
+the extreme to exist at all, so on a light page `surface` is white whatever the base
+saturation asks for. The base seed reaches `surface-2`…`surface-4`, `border`,
 `placeholder` and the text ramp, and stops at the page itself.
 
 `surfaceMode: 'tinted'` moves the whole ramp two tones inward:
 
 ```ts
-setPaletteConfig({ surfaceMode: 'tinted', baseSaturation: 25 });
+setPaletteConfig({ surfaceMode: 'tinted', base: { saturation: 25 } });
 ```
 
 Two tones is not a lightness change you would name — it is _room_. Everything below
@@ -248,12 +286,15 @@ second scale on top of it would only undo the evenness. So there are two paths:
 
 ```ts
 setPaletteConfig({ pastel: true }); // even across hues; saturation is 100, full stop
-setPaletteConfig({ saturation: 65 }); // your scale, per-hue ceiling — pastel goes off
+setPaletteConfig({ accent: { saturation: 65 } }); // your scale, per-hue ceiling
 ```
 
-Note the second line does not mention `pastel`. **Setting a `saturation` turns pastel
-off**, because tuning a saturation is the non-pastel path by definition — so you pick a
-path by asking for what you want from it, not by setting a flag first.
+Note the second line does not mention `pastel`. **Setting the accent's `saturation` turns
+pastel off**, because tuning a saturation is the non-pastel path by definition — so you
+pick a path by asking for what you want from it, not by setting a flag first. A *color*
+does not answer that question and does not turn pastel off: `accent: '#FFD400'` on its
+own still resolves under the flat ceiling, contributing its hue and tone but not its
+chroma.
 
 State `pastel` only to override that. It is the coarser of the two choices — a color
 space rather than a value on one — so it wins wherever both are set, and a saturation it
@@ -290,51 +331,60 @@ also why the pinned seed is a floor to respect rather than a number to tidy up.
 
 ### Inherited vs pinned
 
-Every per-theme field starts out **inheriting** the palette-level value, so
-`baseHue` tracks `hue` until something sets it, and `themes.<status>.saturation`
-tracks `saturation`. Moving the accent hue therefore appears to move the base hue
-too — they are not linked, `baseHue` simply has no value of its own yet.
+Every zone's seed starts out **inheriting**: the base zone follows the accent until
+something seeds it, and a status theme's saturation tracks the accent's. Moving the accent
+hue therefore appears to move the base hue too — they are not linked, the base zone simply
+has no value of its own yet.
 
-Writing the field pins it; leaving it out of the config unpins it, so it inherits
-again:
+Writing a seed pins it; leaving it out of the config unpins it, so it inherits again:
 
 ```ts
-setPaletteConfig({ baseHue: 60 }); // pin
-setPaletteConfig((config) => ({ ...config, hue: 235 })); // baseHue stays at 60
-setPaletteConfig({ hue: 235 }); // baseHue dropped — inherits again → 235
+setPaletteConfig({ base: { hue: 60 } }); // pin
+setPaletteConfig((config) => ({ ...config, accent: { hue: 235 } })); // base stays at 60
+setPaletteConfig({ accent: { hue: 235 } }); // base dropped — follows again → 235
 
 // Same thing from inside an updater, when the rest of the config must survive.
-setPaletteConfig(({ baseHue, ...config }) => config);
+setPaletteConfig(({ base, ...config }) => config);
 ```
 
-The color seeds are pinned fields too, which makes the base zone three-state: unset and
-it follows the accent, `baseHue` and it is pinned to a number, `baseColor` and it is
-derived from a color. A settings UI reads the sparse config to know which of its own
-controls is in charge:
+A zone is therefore **three-state**, and one field answers all three: absent and it
+inherits, an object and it is pinned to numbers, a string and it is derived from a color.
+A settings UI reads the sparse config to know which of its own controls is in charge:
 
 ```ts
 const input = getPaletteConfigInput();
-const accentMode = input.accentColor !== undefined ? 'color' : 'hue';
+const accentMode = typeof input.accent === 'string' ? 'color' : 'numbers';
+const baseIsOwn = input.base !== undefined;
 ```
 
-Swapping one form for the other counts as a change even when the numbers agree — a
-`hue: 45` replaced by a color that derives hue 45 resolves identically, but the UI still
-has to re-render to move its mode control.
+`base: {}` and no `base` at all resolve to the same colors, but they are not the same
+config — one has a seed of its own that pins nothing, the other has no seed. The two read
+back differently and both count as changes, because that distinction is exactly what a
+**Follow accent / Own** control is.
+
+Swapping one form for the other counts as a change even when the numbers agree — an
+`accent: { hue: 45 }` replaced by a color that derives hue 45 resolves identically, but
+the UI still has to re-render to move its mode control. So does replacing one unparseable
+string with another, which is why the colors are compared by value rather than by
+presence.
 
-An explicit `baseHue: undefined` is equivalent to omitting it; neither is a value.
+An explicit `{ hue: undefined }` inside a seed is equivalent to omitting the field;
+neither is a value.
 
-`getPaletteConfig()` resolves everything, which loses that distinction — it cannot
-tell you whether `100` was chosen or inherited. `getPaletteConfigInput()` returns the
-sparse config as set, which is what a settings UI needs to render an inherited value
-as inherited and offer a way back:
+`getPaletteConfig()` resolves everything, which loses that distinction — it cannot tell
+you whether `100` was chosen or inherited, and it always reports flat numbers whichever
+way a zone was seeded. `getPaletteConfigInput()` returns the sparse config as set, which
+is what a settings UI needs to render an inherited value as inherited and offer a way
+back:
 
 ```ts
-const pinned = getPaletteConfigInput().baseHue !== undefined;
+const seed = getPaletteConfigInput().base;
+const pinnedHue = typeof seed === 'object' ? seed.hue : undefined;
 ```
 
-Pinning a field to the value it already inherited resolves to the same colors but
-still counts as a change, so a UI reading the sparse config re-renders. Re-applying
-an _already pinned_ value is a true no-op and costs nothing.
+Pinning a field to the value it already inherited resolves to the same colors but still
+counts as a change, so a UI reading the sparse config re-renders. Re-applying an _already
+pinned_ value is a true no-op and costs nothing.
 
 ## Palette playground
 
@@ -353,8 +403,39 @@ Two things worth noticing while you tune:
 
 ## Status themes
 
-Each status theme is a Glaze `extend()` of the default theme with its own hue, so
-tuning one moves only its own `#<theme>-*` family.
+Each status theme is a Glaze `extend()` of the default theme with its own seed, so tuning
+one moves only its own `#<theme>-*` family.
+
+That seed is a `PaletteSeed` like any other, so `danger` can be the red your product
+already ships rather than a hue you reverse-engineered from it:
+
+```ts
+setPaletteConfig({ themes: { danger: '#b91c1c', success: { hue: 150 } } });
+```
+
+A status color behaves like the brand's in the ways that matter — the light,
+normal-contrast fill reproduces it, dark and high contrast adapt, and the softened APCA
+floors apply instead of the white-anchored ladder's WCAG ones, including the cap that
+keeps the `#white` label on a `type="primary"` button readable.
+
+**One thing is deliberately different: its chroma becomes the theme's seed.** An accent
+color's does not, because all four status themes inherit the accent's saturation and
+raising it would re-chromatise every one of them. Nothing inherits from a status theme,
+so there is nothing to protect — and moving the seed is what holds the rest of the theme
+in proportion to the fill. The tinted banner surface, the border and the text ramp are
+authored as factors of the seed (`0.2`, `0.3`, `0.25`), so with the seed left at `100`
+beside a muted fill the banner would read as fully tinted under a washed-out button.
+Moving it keeps the shipped `1.0 : 0.2 : 0.3 : 0.25` ratio exactly.
+
+Two consequences worth stating. A vivid status color under a muted palette gives one
+vivid theme beside muted siblings — that is the point of naming a color. And under
+`pastel` the flat ceiling can hold the fill below the color's own chroma while the banner
+still sits at `0.2` of it, so the ratio drifts slightly; turn pastel off for an exact
+color, exactly as with the brand.
+
+A muted seed *beside* an accent color is not expressible, because the zone is seeded one
+way or the other: a color there leaves the inherited saturation at its default. Mute the
+status themes individually if you want that.
 
 ## Contrast level
 
@@ -397,7 +478,7 @@ variant. Following is the default behaviour rather than a third choice.
 
 On the theme side, the panel is grouped by **what a knob reaches** rather than by
 what it is named after: **Global** for the ones that govern both zones — `pastel`,
-`saturation`, `surfaceMode` and `contrastLevel` — then **Accent** and **Base** for
+the accent saturation, `surfaceMode` and `contrastLevel` — then **Accent** and **Base** for
 the ones that do not. `surfaceMode` files under Global despite moving the *base*
 surfaces, because the status themes' tinted surfaces follow it too, and so does the
 mirrored surface the syntax palette solves against.
@@ -410,7 +491,7 @@ The **contrast level** needs no on/off switch: level `0` and `'auto'` are
 output-identical, tier included, so the slider at rest _is_ the shipped palette.
 
 Status themes are four chips on one line rather than eight sliders. Each chip is a
-`theme="current"` `Button` colored by its own theme with a
+`type="current"` `Button` colored by its own theme with a
 [ColorSwatch](./components/fields/ColorSwatch.md) of its accent, so the group answers
 the question you actually have — do these four still read as four different
 things — at a glance; press one to open its hue and saturation. The hue is not
@@ -423,7 +504,7 @@ The one button you reach for when an experiment goes wrong should not be behind
 the controls that caused it. `Export` opens the config as a `setPaletteConfig()`
 call to copy; `JSON` downloads `palette.json` on the press, with no intermediate
 state worth a second click. Both carry the config _as written_ rather than the
-resolved one, so an inherited `baseHue` stays inherited instead of being frozen to
+resolved one, so an inherited `base` stays inherited instead of being frozen to
 whatever the accent happened to be.
 
 Every caveat on the panel is an **InfoBadge** beside the control it qualifies rather
@@ -439,7 +520,7 @@ it has selected:
 | ------------ | ----------------------- | ------------------------------------ | ------------------------- |
 | **Accent**   | Hue                     | Hue + Saturation                     | Color (hue+chroma+tone)   |
 | **Base**     | Hue, or _Follow accent_ | Hue + Saturation, or _Follow accent_ | Color, or _Follow accent_ |
-| **Status**   | Hue                     | Hue + Saturation                     | Hue + Saturation          |
+| **Status**   | Hue                     | Hue + Saturation                     | Color                     |
 | **Syntax**   | Saturation              | Saturation                           | Saturation                |
 
 `Advanced` and `Color` are the **same chroma space** — the per-hue ceiling — and differ
@@ -470,7 +551,18 @@ is about whether the chrome has a seed at all, not about how a seed is spelled.
 Every transition hands the incoming controls the values the outgoing ones were displaying,
 so switching changes who is in charge without repainting on the way. Leaving `Color`
 therefore pins each zone at what its color derived and drops the hex — including on the
-way to `Pastel`, which cannot honour a color at all.
+way to `Pastel`, which cannot honour a color at all. Status themes pin their **hue** only:
+a saturation pinned on the way out would survive into `Pastel`, where it is inert but
+still in effect, and that is not a state to manufacture on a tab press.
+
+The two halves of the way *in* differ, and both are deliberate. The brand zones open on a
+fixed sample hex, so the flip changes which control is in charge rather than reading the
+page back to itself. The four status themes convert instead — each to the fill it is
+already emitting — because four sample hexes would repaint every banner on a tab press,
+and a status theme's identity is a *meaning* a sample color has no business overwriting.
+Coming from `Advanced`, the same chroma space, that conversion lands the banner back where
+it was; coming from `Pastel` the palette repaints regardless, since the tabs turn `pastel`
+off and a change of chroma space is the one thing no hand-over can carry across.
 
 In color mode the panel shows where the color actually landed — **Accent Fill** and
 **Accent Text**, the two tokens the seed's tone reaches. The requested color is not
@@ -499,7 +591,7 @@ import { renderColorTokens, tasty } from '@cube-dev/ui-kit';
 const Region = tasty({ styles: { fill: '#surface', color: '#surface-text' } });
 
 const preview = useMemo(
-  () => renderColorTokens({ hue: 210, scheme: 'dark' }),
+  () => renderColorTokens({ accent: { hue: 210 }, scheme: 'dark' }),
   [],
 );
 
@@ -571,7 +663,7 @@ import {
 // on change. `palette` is the resolved config; the updater's argument is sparse.
 const [palette, setPalette] = usePaletteConfig();
 
-setPalette((config) => ({ ...config, hue: 200 }));
+setPalette((config) => ({ ...config, accent: { ...config.accent, hue: 200 } }));
 
 // Outside React.
 getPaletteConfig(); // every field resolved to a concrete value
@@ -590,7 +682,7 @@ it. `DEFAULT_PALETTE_CONFIG` is the shipped baseline in the same shape.
 paint is already correct:
 
 ```tsx
-<Root palette={{ hue: userAccentHue }}>
+<Root palette={{ accent: userBrandColor }}>
   <App />
 </Root>
 ```
@@ -626,10 +718,10 @@ therefore re-tunes nothing — a seed picked in one space lands somewhere else i
 other, and the warm statuses move most. Re-tune the seeds alongside it, in whichever
 direction you flip.
 
-It also owns `saturation` outright — pinned to `100`, so a number passed _explicitly
-alongside_ it is inert and warned about (a number passed on its own turns pastel off
-instead). And it caps an `accentColor` short of itself: the ceiling sits below where a
-saturated color lands, so `#EF4444` resolves to `#c47069`. Both are visible in the
+It also owns the accent's `saturation` outright — pinned to `100`, so a number passed
+_explicitly alongside_ it is inert and warned about (a number passed on its own turns
+pastel off instead). And it caps a color seed short of itself: the ceiling sits below
+where a saturated color lands, so `#EF4444` resolves to `#c47069`. Both are visible in the
 [Theme builder](#theme-builder), the first as a disabled slider and the second as the
 requested/resolved chips.