@cube-dev/ui-kit 0.0.0-canary-694a764 → 0.0.0-canary-dcbc0fb

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-694a764 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-dcbc0fb | 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-694a764 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.0.0-canary-dcbc0fb | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.0.0-canary-694a764";
+const VERSION = "0.0.0-canary-dcbc0fb";
 const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/Theming.md

@@ -5,6 +5,10 @@ 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';
 
@@ -23,13 +27,17 @@ 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.                                                                     | `100`                               |
+| `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. Every theme except `code`.                                                                                                | `true`                              |
+| `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'`                            |
 
 ### The setter replaces
@@ -64,13 +72,13 @@ setPaletteConfig((config) => ({
 `resetPaletteConfig()` drops all tuning at once — the same as
 `setPaletteConfig({})`, just easier to read at a call site.
 
-### Two hue zones
+### Two zones, two ways to seed them
 
 Hue is split into an **accent** zone and a **base** zone:
 
-- **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
+- **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`.
 
 `baseHue` inherits `hue`, so out of the box the chrome carries a faint tint of the
@@ -83,11 +91,81 @@ 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, 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: `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
@@ -95,6 +173,84 @@ 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
@@ -142,6 +298,20 @@ 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
@@ -183,29 +353,124 @@ 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`,
+`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.
 
 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
@@ -267,8 +532,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
@@ -350,9 +617,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 `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` 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

package/docs/components/fields/ColorSwatch.md

@@ -0,0 +1,148 @@
+# ColorSwatch
+
+A square of color. It is the smallest piece of the color family —
+[ColorPicker](./ColorPicker.md),
+[ColorInput](./ColorInput.md) and
+[ColorSwatchGroup](./ColorSwatchGroup.md) all draw one, and it is
+exported so a legend, a list row or a table cell can draw the same one.
+
+It is decorative on its own: it carries no text and no accessible name. Pair it
+with the value written out, or put it in a control that names it.
+
+## When to Use
+
+- Next to a color value in a list, a table or a chart legend
+- In the `icon` / `rightIcon` / `prefix` / `suffix` slot of an `Item` or `Button`
+- As the color part of a custom control built on top of the color fields
+
+## Component
+
+---
+
+### Properties
+
+- **`color`** `string | ColorValue | null` — The color to show. Anything the color fields accept — `#7a4dbf`, `rgb(122 77 191)`, `oklch(…)`. `null`, or a string that cannot be parsed, shows the empty state
+- **`size`** `'small' | 'medium' | 'large'` — The edge of the swatch: `20px`, `24px` or `28px`. Left unset, the swatch tracks the control around it (see below)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the swatch itself. `width` and `height` set here win over both the
+`size` prop and the automatic sizing.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type      | Description                                                    |
+| -------- | --------- | -------------------------------------------------------------- |
+| `empty`  | `boolean` | No color to show — drawn as the conventional diagonal stroke     |
+
+## Sizes
+
+- `small` — `20px`
+- `medium` — `24px`
+- `large` — `28px`
+
+### Sizing inside a control
+
+Leave `size` off and the swatch sizes itself to whatever it sits in. `Item`,
+`Button` and the text inputs publish their own height as the `$size` custom
+property, and the swatch reads it and lands `8px` inside — `20px` in a `small`
+control, `24px` in a `medium` one, `32px` in a `large` one. Nothing has to be
+passed between the two, so a control that changes size takes its swatch with it.
+
+Outside a control there is nothing to read, and the swatch falls back to
+`medium`.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<ColorSwatch color="#7a4dbf" />
+```
+
+### In a control
+
+```jsx
+<Button icon={<ColorSwatch color={color} />}>{color}</Button>
+
+<Item icon={<ColorSwatch color={color} />} suffix={<ColorSwatch color={hover} />}>
+  Accent
+</Item>
+```
+
+### With the value spelled out
+
+The swatch has no accessible name of its own, so the text beside it is what a
+screen reader announces.
+
+```jsx
+<Space gap="1x" placeItems="center start">
+  <ColorSwatch color={value} />
+  <Text>{value}</Text>
+</Space>
+```
+
+### A fixed size
+
+```jsx
+<ColorSwatch size="large" color="#26fcb2" />
+```
+
+### Any other shape
+
+```jsx
+<ColorSwatch color="#26fcb2" radius="round" width="6x" height="6x" />
+```
+
+## Accessibility
+
+`ColorSwatch` renders a plain `div` with no role and no name — a color on its
+own is not information a screen reader can use, and an announced hex is rarely
+what the user wants to hear.
+
+- **Do** put the value, or the name of the thing the color belongs to, next to it
+- **Do** rely on the surrounding control's `aria-label` when the swatch is its icon
+- **Don't** use color as the only way to tell two rows apart
+
+## Best Practices
+
+1. **Do**: let a swatch inside a control size itself
+
+   ```jsx
+   <Button size="small" icon={<ColorSwatch color={color} />}>
+     {color}
+   </Button>
+   ```
+
+2. **Don't**: hand-tune the box to match a control
+
+   ```jsx
+   <Button size="small" icon={<ColorSwatch color={color} width="2.5x" height="2.5x" />}>
+     {color}
+   </Button>
+   ```
+
+3. **Accessibility**: never let the swatch be the only carrier of the meaning
+
+## Related Components
+
+- [ColorPicker](./ColorPicker.md) — a swatch that opens the color popover
+- [ColorInput](./ColorInput.md) — the color as editable text, with a swatch inside
+- [ColorSwatchGroup](./ColorSwatchGroup.md) — a selectable grid of swatches