@cube-dev/ui-kit 0.0.0-canary-dcbc0fb → 0.0.0-canary-ff4bf70

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-dcbc0fb | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-ff4bf70 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-dcbc0fb | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-ff4bf70 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.0.0-canary-dcbc0fb";
+const VERSION = "0.0.0-canary-ff4bf70";
 const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/Theming.md

@@ -5,10 +5,6 @@ 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,
 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).
-
 ```ts
 import { setPaletteConfig } from '@cube-dev/ui-kit';
 
@@ -27,17 +23,13 @@ value so this stays true.
 
 | 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'`                         |
+| `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, and **pins `saturation` to 100**. Wins wherever both are set. Every theme except `code`.                                  | `true`                              |
+| `pastel`                     | Global. Relaxes the sRGB-safe chroma limit. Every theme except `code`.                                                                                                | `true`                              |
 | `contrastLevel`              | Global. `'auto'`, or a manual `0`–`100` level.                                                                                                                        | `'auto'`                            |
 
 ### The setter replaces
@@ -72,13 +64,13 @@ 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
+### Two hue zones
 
 Hue is split into an **accent** zone and a **base** zone:
 
-- **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
+- **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`.
 
 `baseHue` inherits `hue`, so out of the box the chrome carries a faint tint of the
@@ -91,81 +83,11 @@ setPaletteConfig({ hue: 235, baseHue: 60 });
 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.
 
-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.
-
-```ts
-setPaletteConfig({ accentColor: '#2F5BFF', baseColor: '#7A7269' });
-```
-
-The two are not symmetric, and the difference is the point:
-
-- `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.
-
-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.
-
-```ts
-setPaletteConfig({ baseColor: '#6e7076' }); // near-grey in, near-grey chrome out
-setPaletteConfig({ baseColor: '#FFD400' }); // saturation 100 in, clipped to 50
-```
-
-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:
-
-```ts
-setPaletteConfig({ accentColor: '#2F5BFF', hue: 300 }); // hue 300, tone still #2F5BFF's
-```
-
-### 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 has a 3:1 floor against the page.** That is WCAG's non-text floor: enough
-that a button reads as a shape on the surface. It is a floor and not a target — a brand
-already at 5:1, or 17:1, is emitted exactly as given, and one that misses moves only as
-far as the floor. `#FFD400` cannot clear 3:1 on a white page, so it darkens to
-`#b09200`; `#7A4DBF` measures 5.8:1 and is left alone.
-
-High contrast tightens it further, deliberately: there the floor goes back to AAA
-whatever you passed, because that tier is selected by `prefers-contrast: more` or an
-explicit `data-contrast="high"` — anyone reading it has asked for separation over brand.
-
-**`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.
-
-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, 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`.
 
 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
@@ -173,84 +95,6 @@ together, in the ratios the palette was designed around. That is the point — t
 relationship between a subtle surface tint and a saturated accent is part of the
 design, not something to tune per token.
 
-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:
-
-```ts
-setPaletteConfig({ pastel: false, saturation: 90, baseSaturation: 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.
-
-**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.
-
-### 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`,
-`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 });
-```
-
-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({ saturation: 65 }); // your scale, per-hue ceiling — pastel goes off
-```
-
-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.
-
-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
 
 Syntax colors are their own theme with their own seed, so neither the brand hue nor
@@ -298,20 +142,6 @@ setPaletteConfig({ hue: 235 }); // baseHue dropped — inherits again → 235
 setPaletteConfig(({ baseHue, ...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:
-
-```ts
-const input = getPaletteConfigInput();
-const accentMode = input.accentColor !== undefined ? 'color' : 'hue';
-```
-
-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.
-
 An explicit `baseHue: undefined` is equivalent to omitting it; neither is a value.
 
 `getPaletteConfig()` resolves everything, which loses that distinction — it cannot
@@ -353,124 +183,29 @@ 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` 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.
+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.
 
-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.
+That is a real accessibility trade-off: leave `contrastLevel` at `'auto'` unless
+you are giving users their own contrast control.
 
 ## Theme builder
 
 The `Theme Builder` story puts the whole config behind controls and renders the
-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`,
-`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
-`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
-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 `baseHue` 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                     | Hue + Saturation          |
-| **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.
-
-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.
+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.
 
 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
@@ -532,10 +267,8 @@ 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. `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.
+  schemes. Because a manual level leaves no separate high-contrast tier,
+  `highContrast: true` correctly 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
@@ -617,18 +350,9 @@ 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
-[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` 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.
+A manual `contrastLevel` is cheaper, since it skips both high-contrast passes.
 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