@cube-dev/ui-kit 0.151.0 → 0.153.0

package/docs/Theming.md

@@ -0,0 +1,375 @@
+# 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,
+dark, and high-contrast schemes at once.
+
+```ts
+import { setPaletteConfig } from '@cube-dev/ui-kit';
+
+setPaletteConfig({
+  hue: 210,
+  saturation: 72,
+  themes: { danger: { hue: 12 } },
+});
+```
+
+With no configuration set, the palette is exactly the one the kit ships — the
+defaults below are the shipped seeds, and a snapshot test pins every resolved
+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. | `80` |
+| `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`. | `80` |
+| `pastel` | Global. Relaxes the sRGB-safe chroma limit. | `false` |
+| `contrastLevel` | Global. `'auto'`, or a manual `0`–`100` level. | `'auto'` |
+
+### The setter replaces
+
+`setPaletteConfig()` works like `useState`, not like `glaze.configure()`: the
+config you pass **is** the config, resolved against the shipped defaults. Nothing
+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`
+```
+
+That is what makes the config safe to keep in your own state and re-apply: the
+same object twice does the same thing as once, and `<Root palette>` can un-set a
+field by no longer passing it.
+
+To change one field of the config already in place — a slider in a settings UI —
+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 }));
+
+// Nested seeds need their own spread, or the other themes go with them.
+setPaletteConfig((config) => ({
+  ...config,
+  themes: { ...config.themes, warning: { saturation: 95 } },
+}));
+```
+
+`resetPaletteConfig()` drops all tuning at once — the same as
+`setPaletteConfig({})`, just easier to read at a call site.
+
+### Two hue zones
+
+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
+  `surface-text*` ramp, `border`, `placeholder`.
+
+`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:
+
+```ts
+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.
+
+### 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`.
+
+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.
+
+### The `code-*` family is the exception
+
+Syntax colors are their own theme with their own seed, so neither the brand hue nor
+the palette saturation reaches them. Hues are absolute literals — a brand re-seeded
+toward green would otherwise collide `code-string` with `code-number` (156°) — and
+the saturation is fixed at `80` rather than inheriting, so muting the app cannot
+wash out a code block. Tune it on its own:
+
+```ts
+setPaletteConfig({ themes: { code: { saturation: 60 } } });
+```
+
+They are still *adaptive*: each one is anchored to the real `surface` with an
+`['AA','AAA']` floor, so they re-solve for light, dark and high contrast. Only hue
+and saturation are pinned.
+
+That separate seed is also a hard requirement, not a preference: a Glaze colour can
+never exceed its own theme seed, and four of these sit at factor `1.0`. Inside a
+default theme seeded below 80 they simply could not hold their chroma.
+
+### 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.
+
+Writing the field 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
+
+// Same thing from inside an updater, when the rest of the config must survive.
+setPaletteConfig(({ baseHue, ...config }) => config);
+```
+
+An explicit `baseHue: undefined` is equivalent to omitting it; neither is a value.
+
+`getPaletteConfig()` resolves everything, which loses that distinction — it cannot
+tell you whether `80` 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 pinned = getPaletteConfigInput().baseHue !== 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.
+
+## Palette playground
+
+Drag the brand hue and watch the accent ramp, the neutral surfaces, the buttons,
+the borders and the shadows move together. Nothing re-renders: every color in the
+kit compiles to a CSS custom property, so re-seeding replaces a single rule on
+`body` and the browser repaints.
+
+Two things worth noticing while you tune:
+
+- The **neutral** surfaces carry saturation factors of 0.10–0.175, so they read
+  as a faint tint of the brand hue. That is where the saturation seed is
+  legible — the solid accents hide it.
+- The **syntax** colors do not move at all — they are their own theme with their
+  own seed, so neither the accent hue nor the saturation reaches them.
+
+## 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.
+
+## Contrast level
+
+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.
+
+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: 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
+fine on the page surface can fall apart two panels deep.
+
+## Previewing a theme in a region
+
+`setPaletteConfig()` re-themes the whole document, which is no use for a theme
+picker — you want several themes visible at once, or a dark preview inside a light
+page. `renderColorTokens()` does that: it resolves the palette for **one** config
+and **one** scheme and returns flat literal values, ready to apply to a subtree
+through a tasty `tokens` prop.
+
+```tsx
+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' }),
+  [],
+);
+
+<Region tokens={preview}>…everything in here renders in that theme…</Region>;
+```
+
+The reason this needs its own API: the document palette emits **state maps**
+(`{ '': …, '@dark': …, '@hc': … }`), so a page can only ever show one scheme at a
+time — that is what `@dark` means. Collapsing the palette to a chosen scheme
+removes the conditionality, so several themes can coexist.
+
+| Option | Meaning |
+| --- | --- |
+| every `PaletteConfig` field | merged over the **current** config, so `{ scheme: 'dark' }` previews the active theme in dark |
+| `scheme` | `'light'` (default) or `'dark'` |
+| `highContrast` | resolve that scheme's high-contrast variant. Default `false` |
+
+Nothing is applied globally — the live palette and the stored config are
+untouched, so previews are safe to render anywhere.
+
+Note the one place the merge/replace split matters: this call **layers** over the
+live config, unlike `setPaletteConfig()`, which replaces. A preview means "the
+theme in use, but in dark", so the fields it does not mention have to come from
+the current palette rather than from the defaults. `resolvePaletteConfig()` layers
+the same way.
+
+Notes:
+
+- Real components work inside a region. Every color in the kit compiles to a CSS
+  custom property, so overriding those properties on one element re-colors its
+  whole subtree with no scheme attribute and no second `<Root>`.
+- The legacy aliases come along **by reference** (`'#dark': '#surface-text'`), and
+  so do the shadow tokens and scrollbar colors, whose values embed a palette
+  color. Tasty re-declares them on the region so each `var()` resolves against the
+  region's own values; resolving them up front would freeze them to the outer
+  theme instead.
+- Typography, spacing, sizes and layout are **not** included — nothing in their
+  values references a color, so the region inherits them from `<Root>`.
+- `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.
+  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
+  `#border`, step at every level.
+- Resolving a palette costs a few milliseconds. The last config is memoized, but
+  `useMemo` on the caller side if you drive it from state.
+
+`renderPaletteTokens()` is the same thing without the aliases and companion
+tokens, if you want only the Glaze palette.
+
+## Reading and reacting to the config
+
+```tsx
+import {
+  DEFAULT_PALETTE_CONFIG,
+  getPaletteConfig,
+  resetPaletteConfig,
+  setPaletteConfig,
+  subscribePaletteConfig,
+  usePaletteConfig,
+} from '@cube-dev/ui-kit';
+
+// In React — `useState`-style (including the replacing setter), and re-renders
+// on change. `palette` is the resolved config; the updater's argument is sparse.
+const [palette, setPalette] = usePaletteConfig();
+
+setPalette((config) => ({ ...config, hue: 200 }));
+
+// Outside React.
+getPaletteConfig(); // every field resolved to a concrete value
+subscribePaletteConfig(() => {
+  /* … */
+});
+```
+
+`getPaletteConfig()` always returns the fully resolved form, so
+`getPaletteConfig().themes.danger.saturation` is a number even if nobody ever set
+it. `DEFAULT_PALETTE_CONFIG` is the shipped baseline in the same shape.
+
+## `<Root palette>`
+
+`<Root>` accepts the same config as a prop, applied during render so the first
+paint is already correct:
+
+```tsx
+<Root palette={{ hue: userAccentHue }}>
+  <App />
+</Root>
+```
+
+Because the setter replaces, the prop describes the **whole** palette: drop a
+field from the object and that customization goes away on the next render, which
+is what you want from a declarative prop.
+
+Removing the prop entirely is the one thing that does *not* reset the palette —
+`<Root>` with no `palette` leaves whatever is configured alone, so that the common
+case cannot clobber a host's imperative `setPaletteConfig()` call. Pass
+`palette={{}}` if you do want the default.
+
+This is a convenience wrapper over `setPaletteConfig()`, not a separate scope.
+**The palette is process-global** — Glaze's own config is, and so is the single
+`body` rule the tokens are injected into. One palette per process, not per tree
+and not per request:
+
+- Two `<Root>`s with different `palette` props will fight over the same tokens.
+- Under SSR, apply the palette in code that runs on **both** server and client.
+  A client-only `setPaletteConfig` disposes and replaces the server-rendered
+  token block on the first render, which is visible as a flash. Per-request
+  palettes are not supported.
+
+## Caveats
+
+**`pastel: true` is a redesign, not a filter.** It changes every resolved color.
+The per-color saturation factors in this palette were tuned for the non-pastel
+space — pastel equalizes chroma across hues, so a pastel palette on the shipped
+seeds resolves more saturated than you may expect. Re-tune the seeds alongside
+it.
+
+**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.
+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
+event.
+
+**If you call Glaze directly, tell the kit.** `glaze.configure({ darkTone })` and
+friends invalidate Glaze's own caches, but the kit's token maps are memoized
+against the palette config version:
+
+```ts
+import { glaze, invalidatePaletteTokens } from '@cube-dev/ui-kit';
+
+glaze.configure({ darkDesaturation: 0.2 });
+invalidatePaletteTokens(); // only needed once the kit is already mounted
+```
+
+`contrastLevel` is the one field the kit writes to Glaze's global config, and it
+only ever does so if you asked for a level. A host that sets its own
+`glaze.configure({ contrastLevel })` and never passes `contrastLevel` here keeps
+it.
+
+**Some things are not tunable at all.** Tasty locks its configuration on the
+first style injection, so the `@dark` / `@hc` state definitions and the
+`colorSpace` (both set in `Root`) are fixed for the lifetime of the page. Only
+token *values* stay mutable — which is all re-seeding needs.
+
+## See also
+
+- [Colors](./Colors.md) — how to pair surfaces with
+  foregrounds, and what each token family is for.
+- [Usage](./Usage.md) — the full token reference.

package/docs/Usage.md

@@ -94,6 +94,8 @@ All color tokens use `#name` syntax in styles. Opacity variants use `#name.NN` (
 
 The palette is generated by [`@tenphi/glaze`](https://github.com/tenphi/glaze) (see `src/tokens/palette.ts`). Every color token is emitted as a state map with `light`, `@dark`, and `@hc` (high-contrast) variants, so the entire UI Kit adapts to dark / high-contrast schemes automatically.
 
+The seeds it is generated from — brand hue, saturation, per-status hues, `pastel`, `contrastLevel` — are tunable at runtime. See [Theming](./Theming.md).
+
 ### Color Schemes
 
 The `@dark` and `@hc` predefined states are wired up in `src/components/Root.tsx` to support both an attribute opt-in and the user's system preference:
@@ -156,10 +158,12 @@ In the `default` theme these tokens are unprefixed (`#accent-surface`). In color
 
 ### Themed Surfaces
 
-Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`) also provides its own tinted `<theme>-surface` (banner / chip background) and `<theme>-surface-text` (banner text):
+Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`) also provides its own tinted `<theme>-surface` (banner / chip background) and `<theme>-surface-text` (banner text).
+
+The hues below are the *defaults*; each is tunable at runtime (see [Theming](./Theming.md)).
 
-| Group | Hue | Purpose |
-|-------|-----|---------|
+| Group | Default hue | Purpose |
+|-------|-------------|---------|
 | `#primary-*` / `#purple-*` | 280.3° | Primary actions, brand color |
 | `#success-*` | 156.9° | Success states, confirmations |
 | `#danger-*` | 23.1° | Errors, destructive actions |
@@ -168,6 +172,29 @@ Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`)
 
 For example, a success banner uses `fill: '#success-surface'` + `color: '#success-surface-text'`, while a primary button uses `fill: '#primary-accent-surface'` + `color: '#primary-accent-surface-text'`.
 
+### Runtime Theming
+
+`setPaletteConfig()` re-seeds the palette after the kit has mounted; every token re-resolves and `<Root>` re-injects the token block. No component re-render is involved, because every color compiles to a CSS custom property.
+
+```ts
+import { resetPaletteConfig, setPaletteConfig } from '@cube-dev/ui-kit';
+
+setPaletteConfig({ hue: 210, themes: { danger: { hue: 12 } } });
+resetPaletteConfig();
+```
+
+Also available: `getPaletteConfig()`, `subscribePaletteConfig()`, the `usePaletteConfig()` hook, a `<Root palette={…}>` prop, `DEFAULT_PALETTE_CONFIG`, and `invalidatePaletteTokens()` for when you drive `glaze.configure(...)` yourself after mount. The palette is process-global — one palette per process, not per tree or per request.
+
+To theme a *region* instead of the document — a theme preview, or a dark panel inside a light page — use `renderColorTokens()`. It resolves one config and one scheme to flat values you apply via a `tokens` prop, without touching the live palette:
+
+```tsx
+<Block tokens={renderColorTokens({ hue: 210, scheme: 'dark' })} fill="#surface">
+  …
+</Block>
+```
+
+Full contract, caveats and a live playground: [Theming](./Theming.md).
+
 ### Legacy Aliases
 
 The previous token names continue to work as aliases (defined at the bottom of `src/tokens/colors.ts`). New code should prefer the Glaze tokens, but existing components do not need to be migrated:

package/docs/components/Root.md

@@ -13,6 +13,7 @@ The root application wrapper. Provides theme context, global styles, portal cont
 - **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
 - **`tracking`** `TrackingProps` — Analytics/tracking event configuration
 - **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
+- **`palette`** `PaletteConfig` — Tune the generated color palette: brand `hue` / `saturation`, per-status theme seeds, `pastel`, `contrastLevel`. Applied during render, so the first paint is already correct. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
 - **`fonts`** `boolean` — Whether to load default fonts
 - **`font`** `string` — Custom font family name
 - **`monospaceFont`** `string` — Custom monospace font family name

package/docs/components/fields/DatePicker.md

@@ -23,7 +23,7 @@ A date picker combines a text input with a calendar interface, allowing users to
 - **`maxValue`** `DateValue` — The maximum allowed date
 - **`granularity`** `'day' | 'hour' | 'minute' | 'second'` (default: `day`) — Determines the smallest selectable unit
 - **`size`** `'small' | 'medium' | 'large' | (string & {})` (default: `medium`) — DatePicker size
-- **`useLocale`** `boolean` (default: `false`) — Whether to use locale-specific date formatting
+- **`useLocale`** `boolean` (default: `undefined`) — Date segment formatting. Leave unset for the kit's own segment order; `true` uses the active locale's order; `false` forces `en-US`. Note that unset and `false` are **not** the same — unset applies extra segment formatting that `false` skips
 - **`maxVisibleMonths`** `number` (default: `1`) — Maximum number of months to display in calendar
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the calendar popover should flip to fit in the viewport
 - **`isOpen`** `boolean` — Whether the calendar popover is open (controlled)

package/docs/components/fields/RadioGroup.md

@@ -20,7 +20,7 @@ A radio group allows users to select exactly one option from a set of mutually e
 - **`value`** `string` — The currently selected value (controlled)
 - **`defaultValue`** `string` — The default selected value (uncontrolled)
 - **`type`** `'radio' | 'button' | 'tabs'` (default: `radio`) — Visual type for all radios in the group (button/tabs default to horizontal)
-- **`orientation`** `undefined | 'vertical' | 'horizontal'` (default: `auto`) — Orientation of the radio group (auto-set based on type)
+- **`orientation`** `undefined | 'vertical' | 'horizontal'` (default: `undefined`) — Orientation of the radio group. When unset it is derived from `type`: `horizontal` for `button` and `tabs`, `vertical` otherwise
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `xsmall`) — Size for all radio buttons in the group
 - **`buttonType`** `'outline' | 'outline-2' | 'clear' | 'primary'` — Button type for button-style radios (ignored in tabs mode). When set to "primary", selected buttons use primary style and non-selected use outline with brand tint. `outline-2` is identical to `outline` but uses `#surface-3` as its base fill, so it stands out when the radio group sits on a `#surface-2` container
 - **`onChange`** `function` — Callback fired when the selected value changes

package/docs/components/fields/Switch.md

@@ -19,7 +19,7 @@ A switch allows users to toggle between two states: on and off. It provides imme
 - **`children`** `string` — The content to display as the switch label
 - **`isSelected`** `boolean` (default: `false`) — Whether the switch is selected (controlled)
 - **`defaultSelected`** `boolean` (default: `false`) — Whether the switch is selected by default (uncontrolled)
-- **`size`** `'small' | 'medium' | 'large'` (default: `large`) — Switch size
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Switch size
 - **`onChange`** — Callback fired when the switch value changes
 - **`onFocus`** — Callback fired when the switch receives focus
 - **`onBlur`** — Callback fired when the switch loses focus

package/docs/components/navigation/Tabs.md

@@ -19,7 +19,7 @@ An accessible tabbed interface for organizing content into multiple panels, show
 - **`activeKey`** `Key` — Controlled active tab key
 - **`defaultActiveKey`** `Key` — Initial active tab key for uncontrolled mode
 - **`type`** `'default' | 'narrow' | 'file' | 'radio'` (default: `'default'`) — Visual style variant
-- **`size`** `'xsmall' | 'small' | 'medium' | 'large'` (default: `'small'`) — Tab size
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large'` (default: `'medium'`) — Tab size
 - **`placement`** `'top' | 'bottom' | 'left' | 'right'` (default: `'top'`) — Where the tab bar sits relative to its panels. `top` / `bottom` keep the bar horizontal; `left` / `right` switch it to a vertical strip. The selection indicator, scrolling, fades, scroll arrows, and per-type visuals (radius, file-style shadow, dividers) all adapt automatically.
 - **`prerender`** `boolean` (default: `false`) — If true, all tab panels are rendered but hidden
 - **`keepMounted`** `boolean` (default: `false`) — If true, visited tab panels stay in DOM

package/docs/components/other/CubeLogo.md

@@ -43,7 +43,33 @@ There are **no baked-in brand hexes**, which is what lets the marks work on any
 
 The mark is two different drawings rather than one drawing recoloured — the dark variant is filled differently so it holds its weight against a dark surface. Both are rendered, and the `@dark` state swaps them in CSS.
 
-That means the swap costs no re-render, needs no scheme prop, and is correct during SSR and before hydration. It also means a snapshot of the DOM always contains both paths; assert on `[data-element="LightMark"]` / `[data-element="DarkMark"]` rather than on a single `path`.
+That means the swap costs no re-render, is correct during SSR and before hydration, and needs no prop in the normal case. It also means a snapshot of the DOM always contains both paths; assert on `[data-element="LightMark"]` / `[data-element="DarkMark"]` rather than on a single `path`.
+
+### Pinning a scheme
+
+`@dark` is a *state*, and it is resolved against the **document**. Where the background is known but the document scheme does not describe it, pass `scheme` to pin one mark:
+
+```jsx
+{/* A fixed-dark panel inside a light app */}
+<Block fill="#surface-inverse">
+  <CubeFullLogo scheme="dark" color="#white" />
+</Block>
+
+{/* A themed region — `tokens` overrides token *values*, so it cannot reach a state */}
+<Block tokens={renderColorTokens({ scheme: 'dark' })} fill="#surface">
+  <CubeFullLogo scheme="dark" />
+</Block>
+```
+
+Use it only when you know the surface. Omitting it is the right default: a pinned scheme stops following the user's own light/dark preference.
+
+## Properties
+
+- **`scheme`** `'light' | 'dark'` — Pin one mark instead of letting the `@dark` state pick. Omit it unless you know the surface; see [Pinning a scheme](#pinning-a-scheme)
+- **`size`** — Maps onto `font-size`. Both axes on `CubeLogo`, height only on `CubeFullLogo`
+- **`color`** — Any color token. Both marks are drawn with `currentColor`, so this is inherited by default
+
+Everything else is `Icon`'s: `stroke`, the style props, and `qa`. Supports [Base properties](../../BaseProperties.md).
 
 ## Accessibility
 

package/docs/components/overlays/Dialog.md

@@ -17,7 +17,7 @@ Dialogs are windows containing contextual information, tasks, or workflows that
 ### Properties
 
 - **`children`** — Dialog content (Header, Content, Footer, etc.)
-- **`size`** `'small' | 'medium' | 'large' | 'S' | 'M' | 'L'` (default: `S`) — Dialog size
+- **`size`** `'small' | 'medium' | 'large' | 'S' | 'M' | 'L'` (default: `M`) — Dialog size (`S`/`M`/`L` are aliases for `small`/`medium`/`large`)
 - **`styles`** — Custom styles for the dialog root
 - **`closeButtonStyles`** — Custom styles for the close button
 - **`isDismissable`** `boolean` (default: `false`) — Whether the dialog is dismissable (shows close button, allows Escape key)

package/docs/components/overlays/DialogContainer.md

@@ -18,7 +18,7 @@ A DialogContainer accepts a single Dialog as a child, and manages to show and hi
 
 - **`children`** — The Dialog to display, if any
 - **`type`** `'modal' | 'fullscreen' | 'fullscreenTakeover' | 'panel'` (default: `modal`) — The type of Dialog that should be rendered
-- **`isDismissable`** `boolean` (default: `false`) — Whether the Dialog is dismissible
+- **`isDismissable`** `boolean` (default: `true`) — Whether the Dialog is dismissible
 - **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
 - **`isOpen`** `boolean` — Whether the modal is open or not
 - **`onDismiss`** `function` — Handler called when the x button of a dismissible Dialog is clicked