@cube-dev/ui-kit 0.163.0 → 0.165.0

package/docs/Theming.md

@@ -1,16 +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.
 
+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 } },
 });
 ```
@@ -21,16 +30,22 @@ value so this stays true.
 
 ## What is tunable
 
-| Option                       | Scope                                                                                                                                                                 | Default                             |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `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.                                                                     | `100`                               |
-| `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. 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
 
@@ -39,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
@@ -52,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 } },
@@ -64,36 +84,233 @@ setPaletteConfig((config) => ({
 `resetPaletteConfig()` drops all tuning at once — the same as
 `setPaletteConfig({})`, just easier to read at a call site.
 
-### Two hue zones
+### One seed, two ways to spell it
+
+Every zone takes the same `PaletteSeed`, and it comes in two forms:
+
+```ts
+type PaletteSeed = string | { hue?: number; saturation?: number };
+```
+
+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({ accent: '#2F5BFF' });
+// A number arriving next to that takes the zone over, tone and all.
+setPaletteConfig((config) => ({ ...config, accent: { hue: 300 } }));
+```
+
+#### 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).
+
+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:
 
-Hue is split into an **accent** zone and a **base** zone:
+```ts
+setPaletteConfig({ accent: { hue: 235 }, base: { hue: 60 } });
+```
 
-- **Accent** (`hue`) — the `accent-*` family on every theme, `primary` / `purple` /
-  `special`, plus `focus`, the loading faces and the disabled chip.
-- **Base** (`baseHue`) — the neutral chrome: `surface` and its ladder, the
-  `surface-text*` ramp, `border`, `placeholder`.
+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.
 
-`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:
+#### What a color contributes, per zone
+
+The same string means slightly different things by zone, and the differences are the
+point:
 
 ```ts
-setPaletteConfig({ hue: 235, baseHue: 60 });
+setPaletteConfig({ accent: '#2F5BFF', base: '#7A7269' });
 ```
 
-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.
+- **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({ 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
+
+The palette renders the color you asked for, and moves it only as far as it has to. Two
+things can make it move.
+
+First, **exactness is scoped to the light, normal-contrast variant.** That is the one
+that reproduces your color. Dark and high contrast adapt, as every other color in the
+palette does — they are different pages, and a brand pinned across all four would be
+less faithful, not more. What holds everywhere is the floor below.
+
+**The fill answers to two constraints, and they are different sizes.** The `#white`
+label it carries needs **APCA Lc 45** — text strength, because it is text. The page it
+sits on needs only **Lc 25**, because a solid fill is a shape, not text, and Lc 25 is
+what the palette's own shipped fill achieves against a dark page. Both are floors rather
+than targets: a brand already past them is emitted exactly as given, and one that misses
+moves only as far as the nearer requires.
+
+Sizing those two the same is a mistake worth naming, because this palette made it. In
+light `surface` **is** white, so one measurement is both constraints at once and Lc 45
+looks right for the pair. In dark the page is near-black and the same number becomes a
+demand that a filled shape reach text contrast against it — which nothing in the palette
+meets, the shipped fill included. Since a floor can only lighten, the surplus flattened
+the dark half of the tone axis onto a single value: every brand darker than the floor came
+out the same colour. The page floor is now sized for a shape and the label is guaranteed
+separately, by a cap on the seed's tone.
+
+They are APCA rather than WCAG on purpose. A single WCAG ratio means two different
+things depending on the scheme: measured across twelve hues, a fill sitting exactly at
+3:1 comes out at Lc 56 in light but only Lc 23 in dark. That is why light brands kept
+getting crushed while dark ones sailed through the same rule. **A consequence to state
+plainly: the emitted fill can sit below WCAG 3:1.** `#0EA5E9` renders at 2.77:1 against
+a white page and is correct there — the Lc is the guarantee, not the ratio.
+
+High contrast does **not** escalate the page floor. It is a request for separation over
+brand, but not for separation from the page: the same fill carries the 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, ending up with *less* page separation in high contrast than in
+normal, because it darkens the fill toward its label. What does escalate is the label cap,
+which searches the high-contrast variants too.
+
+**`pastel` caps chroma.** The flat, hue-independent ceiling is what makes pastel even
+across hues, and it sits below where a saturated color would land, so under it a color
+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 constraints 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, 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 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 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({ accent: { saturation: 90 }, base: { saturation: 3 } });
+```
+
+Unset, it takes `0.12` — `surface`'s own factor — of whatever the accent zone carries:
+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 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 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', base: { saturation: 25 } });
+```
+
+Two tones is not a lightness change you would name — it is _room_. Everything below
+`surface` is positioned relative to it, so the ladder, the borders and the text ramp
+all follow, and the text's `['AA','AAA']` floors re-solve against the new background
+rather than drifting. The `code-*` family follows too: its mirrored `surface` exists
+to be the page, so it tracks both the tone and the base seed.
+
+**The tinted surfaces move with it.** A status theme's `surface` — and a runtime
+tint's, from `getColorTheme()` — is authored as an offset from the page's rather
+than as an absolute tone, and that offset is exactly the two tones `tinted` shifts
+by. Anchored absolutely they would land on the page's own new tone and a `note`
+banner would stop reading as a banner at all; anchored to the page they keep the
+separation the offset was chosen for, in both schemes. They also pick up a little
+more chroma there, being further from the extreme — so `tinted` makes a status
+surface easier to see, not harder.
+
+The tint stays subtle by construction. Near white the sRGB gamut has very little
+chroma to give, so `tinted` buys a surface that reads as warm or cool rather than
+one that reads as colored — which is the whole ask. For a genuinely colored panel,
+reach for a status theme's `surface` instead.
+
+All of which describes the `pastel: false` path. Under `pastel` there is still one seed
+and it is pinned to `100`, because a flat chroma ceiling is the whole mechanism and a
+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({ accent: { saturation: 65 } }); // your scale, per-hue ceiling
+```
+
+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.
 
-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.
+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
+shadows is ignored with a dev-mode warning. The number is **kept** rather than dropped,
+though: it stays in the sparse config, so turning pastel back off restores it.
 
 ### The `code-*` family is the exception
 
@@ -125,37 +342,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);
 ```
 
-An explicit `baseHue: undefined` is equivalent to omitting it; neither is a value.
+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:
 
-`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:
+```ts
+const input = getPaletteConfigInput();
+const accentMode = typeof input.accent === 'string' ? 'color' : 'numbers';
+const baseIsOwn = input.base !== undefined;
+```
+
+`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 `{ 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, 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
 
@@ -174,8 +414,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
 
@@ -183,29 +454,135 @@ By default contrast is a two-tier switch: normal colors plus a separate
 high-contrast set, selected by `<html data-contrast="high">` or a
 `prefers-contrast: more` preference.
 
-A manual `contrastLevel` replaces both tiers with a single 0–100 slider. Because
-the level already carries the contrast preference, **no separate high-contrast
-variant is emitted** — which means `data-contrast="high"` and
-`prefers-contrast: more` stop having any effect while a level is set. Levels `0`
-and `100` reproduce the normal and high-contrast palettes bit for bit, so the
-slider is a continuous interpolation between exactly what the two tiers ship
-today.
+A manual `contrastLevel` adds a 0–100 slider that positions the **normal** colors,
+for a product that wants to offer its own contrast control. Level `0` is the
+shipped palette and `100` is the high-contrast one, bit for bit, so the slider
+interpolates between exactly what the two tiers already ship.
+
+The two **compose**; the slider does not replace the switch. The high-contrast
+tier stays the true high-contrast resolution at every level — identical to what
+`'auto'` emits — so `data-contrast="high"` and `prefers-contrast: more` keep
+working and escalate on top of wherever the slider has put the baseline.
 
-That is a real accessibility trade-off: leave `contrastLevel` at `'auto'` unless
-you are giving users their own contrast control.
+The one exception is level `100`: there the normal colors already _are_ the
+high-contrast ones, so a second tier would only duplicate them and a single
+light/dark set is emitted.
+
+Because level `0` reproduces `'auto'` exactly, tier included, shipping the slider
+and defaulting it off costs a consumer nothing.
 
 ## Theme builder
 
 The `Theme Builder` story puts the whole config behind controls and renders the
-result into a single region: pick **Light / Dark**, then either a contrast **mode**
-(Normal / High) or a **custom** 0–100 level, and the preview shows exactly that
-variant while the page around it stays as it is.
-
-There is no `Auto` for scheme or contrast mode, on purpose. `Auto` means "follow
-the OS" — a _preference_, and a flat token value cannot express one. A preview
-renders one concrete variant, so it has to name which. The contrast _level_ keeps
-its `Auto`, because there the choice is between the two-tier model and a hand-set
-number rather than between following and not following the system.
+result into a single region, with one line drawn through the middle of the page:
+**the left column is the theme, the two switches over the preview are the
+viewing conditions.** Everything on the left writes to the palette config and
+would ship with the product; **Light / Dark** and **Normal / High contrast**
+write nothing at all — the same theme renders in all four combinations, and
+moving between them is how you check a theme rather than how you change one.
+
+Those two switches start on whatever the surrounding page is already showing and
+keep following it until you press one, after which they are yours. There is no
+`Auto` option to press: `Auto` means "follow the OS" — a _preference_ — and the
+preview resolves to flat token values, which can only express one concrete
+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`,
+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.
+
+Those headings are also why the field labels are bare. `Seeded by` and `Hue` appear
+in both zones, and the heading above them is what says which — repeating it in
+every label was two words of noise on every line of a narrow column.
+
+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
+[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
+printed on the chip: it belongs to the slider that sets it, and carrying it there
+cost the whole row, since `success — 157°` is wide enough that four of them have
+to stack.
+
+**Reset**, **Export** and **JSON** sit at the top of the column, not the bottom.
+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 `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
+than a paragraph under it. A tuner is a dense column of controls, and prose between
+them pushes the next knob off the screen to explain something you need once.
+
+### Three states, one tab bar
+
+An unlabelled tab bar spans the top of the panel, and everything below reads as the state
+it has selected:
+
+|              | **Pastel**              | **Advanced**                         | **Color**                 |
+| ------------ | ----------------------- | ------------------------------------ | ------------------------- |
+| **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                     | Color                     |
+| **Syntax**   | Saturation              | Saturation                           | Saturation                |
+
+`Advanced` and `Color` are the **same chroma space** — the per-hue ceiling — and differ
+only in what you hand it. `Pastel` is the other space, and it takes hues because a flat
+ceiling has nothing to do with a color.
+
+It began as two controls, a `pastel` switch and a per-zone **Seeded by**, which described
+a 2×2 grid with one impossible cell: pastel cannot honour a color, so one of the two spent
+its life disabled. Three tabs spend three buttons on the three reachable states, and make
+Pastel → Color one press instead of two. The bar carries no label, because naming it would
+mean finding a word for "the palette" — and both candidates, _Mode_ and _Surfaces_, are
+spoken for further down.
+
+Two rules follow from it:
+
+- **`pastel` gates saturation.** It is one flat, hue-independent ceiling, which is what
+  makes the palette even across hues and what leaves nothing for a saturation scale to
+  do. There is no saturation control in that state except the syntax one, which `pastel`
+  never reaches.
+- **A derived control is not shown.** Whatever a seed already supplies, its slider goes
+  away rather than sitting on screen disabled. A disabled slider under a color seed is a
+  read-out dressed as a control, and it cost two rows to repeat what the color field
+  above it already said.
+
+The base zone keeps its own **Follow accent | Own**, which is orthogonal to the tabs: it
+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. 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
+repeated beside them: the field above holds it, with a swatch of its own.
+
+The **preset** buttons show which one is active, and stop showing it the moment you
+touch a control. The setter replaces rather than merges, so a preset is either the
+whole config or it is not the config at all; anything else would claim a theme is
+still `Ocean` after you had re-seeded half of it.
 
 The preview deliberately shows all three surface levels with their own text ramps
 (`#surface-text`, `#surface-2-text`, `#surface-3-text`), because a theme that looks
@@ -225,7 +602,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' }),
   [],
 );
 
@@ -267,8 +644,10 @@ Notes:
 - `contrastLevel` works per region, so the whole 0–100 ramp can be shown at once —
   something a document cannot do, since it is only ever at one level. Level `0`
   reproduces the normal tier and `100` the high-contrast tier exactly, in both
-  schemes. Because a manual level leaves no separate high-contrast tier,
-  `highContrast: true` correctly returns the same colors as the normal variant.
+  schemes. `highContrast: true` still returns the genuine high-contrast
+  resolution at any level below `100`, because the level moves the baseline and
+  the tier escalates from where `'auto'` would put it; at `100` the two coincide
+  and it returns the same colors as the normal variant.
   Note that tokens carrying a contrast _floor_ (most text) can sit still over part
   of the ramp — the floor is solved, not approximated, so the value only moves once
   the interpolated target does. Tokens positioned by a plain tone pair, like
@@ -295,7 +674,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
@@ -314,7 +693,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>
 ```
@@ -350,9 +729,18 @@ 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 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.
+
 **Re-seeding costs about 10 ms.** Rebuilding the eight themes and re-solving
 ~156 tokens across four scheme variants is not free, though it is inside a frame.
-A manual `contrastLevel` is cheaper, since it skips both high-contrast passes.
+A manual `contrastLevel` costs the same — it runs the same four passes — except
+at level `100`, which skips the two high-contrast ones because the normal pass
+already produced those values.
 Setting the config to a value it already holds is free — it does not even bump
 the version. If you are driving it from a slider, let the input coalesce to
 frames (a pointer-driven `onChange` already does) rather than writing on every