@cube-dev/ui-kit 0.204.0 → 0.206.0

package/docs/components/content/TextItem.md

@@ -20,7 +20,7 @@ TextItem renders one line truncated with an ellipsis, so Text's `ellipsis` and `
 - **`highlight`** `string` — String to highlight within children (only works when children is a plain string)
 - **`highlightCaseSensitive`** `boolean` (default: `false`) — Whether highlight matching is case-sensitive
 - **`highlightStyles`** `Styles` — Custom styles for highlighted text portions
-- **`tooltip`** `string | boolean | TooltipProviderProps` (default: `true`) — Tooltip configuration. `true` enables auto tooltip on overflow, a string shows fixed tooltip text, an object supports advanced configuration.
+- **`tooltip`** `string | boolean | TooltipProviderProps` (default: `true`) — Tooltip configuration. `true` enables auto tooltip on overflow for string children, a string shows fixed tooltip text, an object supports advanced configuration. `{ title, auto: true }` shows `title` only on overflow, for any children (see [Overflow Tooltip for an Element Label](#overflow-tooltip-for-an-element-label)).
 - **`tooltipPlacement`** `Placement` (default: `top`) — Default tooltip placement
 - **`monospace`** `boolean` — Use monospace font
 - **`italic`** `string` — Font style (e.g. `'italic'`)
@@ -66,6 +66,18 @@ When text overflows its container, hovering reveals a tooltip with the full cont
 </Block>
 ```
 
+### Overflow Tooltip for an Element Label
+
+The automatic tooltip shows the text that is cut off, so it needs string children. When the label is built from elements, such as a commit hash coloured apart from its message, give the tooltip its own `title` with `auto: true`. It then shows only while the label is cut off:
+
+```jsx
+<TextItem tooltip={{ title: `${hash}: ${message}`, auto: true }}>
+  <Text color="#dark">{hash}:</Text> {message}
+</TextItem>
+```
+
+Only the label's own box is measured. A child that clips its own text, such as a nested `Text` with its own `ellipsis`, never makes the label overflow, so it shows no tooltip. The check reruns when the label resizes or the `title` text changes, so derive a string `title` from the same text as the label.
+
 ### Text Highlighting
 
 Highlight matching text within the content - useful for search results:

package/docs/components/data/ItemTable.md

@@ -215,7 +215,7 @@ const Compact = tasty(ItemTable, {
 });
 ```
 
-Rows publish their paint as inherited custom properties — `#row-base`, `#row-overlay`, `$row-overlay-weight`, `#row-text` and `$dim` — which cells consume. `#row-overlay` is an opaque color that cells mix into `#row-base` at `$row-overlay-weight` (a percentage), so each cell paints one solid background color. That is what lets a pinned (and therefore opaque) cell match its row's state without duplicating the state matrix.
+Rows publish their paint as inherited custom properties — `#row-base`, `#row-overlay`, `$row-overlay-weight`, `#row-text` and `$dim` — which cells consume. `#row-overlay` is an opaque color that cells layer over `#row-base` at `$row-overlay-weight`, a number from 0 to 1 read as its opacity (`#row-base+#row-overlay.$row-overlay-weight`), so each cell paints one solid background color. That is what lets a pinned (and therefore opaque) cell match its row's state without duplicating the state matrix.
 
 Geometry runs through tokens too: `$row-height`, `$header-height`, `$cell-padding-x` (16px) and `$cell-padding-y`. Height lives on the **cells**, not the `<tr>` — table layout ignores `min-height` on a row and sizes it from its cells instead.
 

package/docs/components/fields/RadioGroup.md

@@ -100,6 +100,7 @@ The `mods` property accepts the following modifiers you can override:
 
 - **`horizontal`** `boolean` — Whether the radio group is oriented horizontally
 - **`tabs`** `boolean` — Whether the radio group uses tabs styling
+- **`segmented`** `boolean` — Set with `tabs`: the segmented control look, shared with `Tabs type="radio"`, applies to it. Each `Radio` in the group carries it too
 - **`inside-form`** `boolean` — Whether the radio group is inside a form field
 - **`side-label`** `boolean` — Whether the label is positioned at the side
 - **`fill-width`** `boolean` — Set when the group's style props size its field's width (`width`, `inlineSize`, `flex*`); the group then fills it
@@ -112,7 +113,7 @@ Each `Radio` carries **`readonly`** while its group is `isReadOnly`. A classic r
 
 - `radio` - Traditional radio button appearance (default)
 - `button` - Button-style radio options with spacing
-- `tabs` - Connected tab-style buttons (compact, clear styling)
+- `tabs` - A segmented control. It takes the look of [Tabs](../navigation/Tabs.md) `type="radio"` from one shared style definition: the track, the white chip on the selected option, hover, the keyboard focus ring on the focused option, the disabled look (the selected chip stays, the labels fade) and the text size. Recolor it through the tokens [Tabs → Theming](../navigation/Tabs.md#theming) lists. An invalid or valid group also tints its idle labels. Only the layout differs: its options size to their labels, while tabs share the track equally.
 
 **Default Orientation:**
 
@@ -141,10 +142,10 @@ Controls the size of all radio buttons in the group:
 
 **Size Mapping in Tabs Mode:** When `type="tabs"`, sizes are automatically mapped to maintain visual consistency:
 
-- `large` → `medium`
-- every other size → `xsmall`
+- `large` → `medium` (a 40px control, t3m text)
+- every other size → `xsmall` (a 32px control, t4 text)
 
-Only `large` is carried through; `xsmall`, `small`, `medium` and `xlarge` all collapse to `xsmall`. This ensures tab groups remain compact and cohesive.
+Only `large` is carried through; `xsmall`, `small`, `medium` and `xlarge` all collapse to `xsmall`. These are the sizes `Tabs type="radio"` uses, so the two controls match at either size.
 
 ### Button Type
 

package/docs/components/form/Form.md

@@ -158,6 +158,8 @@ A thrown/rejected save error appears through `Form.SubmitError`. Validation erro
 
 A `Form` placed directly in a `Dialog`, wrapping its `Content` and `Footer`, lays itself out as the dialog's slot column: a flex column that grows into the dialog, lets `Content` scroll, and adds no space between the slots. That is the form's own `@in-dialog` state, so `styles` on the form still override it property by property. You can also name the state to change only the in-dialog case: `<Form styles={{ gap: { '': '2x', '@in-dialog': '1x' } }}>`. A form nested inside `Content` is an ordinary form.
 
+A modern `Form` anywhere in a dialog reports the user's unsaved edits to the dialog's `DialogTrigger` or `DialogContainer`, as `DialogForm` does, so Escape, a click outside and the close button ask "Discard changes?" first. A value set from code is not an edit, and a successful submit saves what it carried. Set `confirmDismiss={false}` on the trigger or container where backing out loses nothing. See [Unsaved edits](../overlays/DialogTrigger.md#unsaved-edits).
+
 ## React Compiler
 
 The modern controller, subscriptions, input binding, and dialog workflows are tested with React Compiler on React 19.3. The published library is compiled using React’s native compiler runtime; consumers do not need to enable Compiler. Consumer render code must use `Form.useValue`, `Form.useFieldState`, or selectors to subscribe; imperative getters do not subscribe. This does not make legacy mutable instance reads Compiler-safe.

package/docs/components/form/ModernForm.md

@@ -287,4 +287,8 @@ function EditProfileDialog({ initialProfile, save }) {
 }
 ```
 
-The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive. See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.
+The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive.
+
+While a field the user edited differs from its default, Escape, a click outside and the close button ask "Discard changes?" first. That holds for a `<Form>` you place in a `Dialog` yourself too: the root reports its edits to the `DialogTrigger` or `DialogContainer` that owns the dialog, with no wiring. A value set from code is not an edit, and a successful submit saves what it carried, so a dialog that stays open after saving (to show a created key, say) closes at once until the user types again. Set `confirmDismiss={false}` on the trigger or container when backing out loses nothing. See [Unsaved edits](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogtrigger--docs#unsaved-edits).
+
+See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.

package/docs/components/navigation/Tabs.md

@@ -85,6 +85,7 @@ These properties allow direct style application without using the `styles` prop:
 The `mods` property accepts the following modifiers:
 
 - **`type`** `'default' \| 'narrow' \| 'file' \| 'radio'` — Current tab type
+- **`segmented`** `boolean` — True for the `radio` type, the segmented control it shares with `Radio.Tabs`
 - **`placement`** `'top' \| 'bottom' \| 'left' \| 'right'` — Current bar placement
 - **`deletable`** `boolean` — True when onDelete callback is provided
 - **`scrolling`** `boolean` — True when tabs are being scrolled
@@ -95,6 +96,7 @@ The `mods` property accepts the following modifiers:
 For individual tabs:
 
 - **`type`** `'default' \| 'narrow' \| 'file' \| 'radio'` — Current tab type
+- **`segmented`** `boolean` — True for a `radio` tab, a segment of the shared segmented control
 - **`active`** `boolean` — True when the tab is selected
 - **`deletable`** `boolean` — True when delete button is visible
 - **`disabled`** `boolean` — True when tab is disabled
@@ -159,16 +161,16 @@ A navigation strip with no panels, themed with your own tokens:
 - `default` - Standard tabs with selection indicator below (default)
 - `narrow` - Same as default but with collapsed horizontal label padding for compact layouts
 - `file` - File-style tabs with border bottom highlight on selection, delimiter between tabs
-- `radio` - Radio button style for tab selection. This is the right choice for a compact switcher that is _not_ a form field — a view toolbar, a segmented control over page content. [`Radio.Tabs`](../fields/RadioGroup.md) looks the same but is a form control, so keep it for choices inside a `Form`
+- `radio` - Radio button style for tab selection. This is the right choice for a compact switcher that is _not_ a form field — a view toolbar, a segmented control over page content. [`Radio.Tabs`](../fields/RadioGroup.md) takes the same segmented look from one shared style definition (only the layout differs: its options size to their labels, while tabs share the track equally), but it is a form control, so keep it for choices inside a `Form`
 
 ### Sizes
 
 - `xsmall` - Extra small size with t4 typography
-- `small` - Small size with t3m typography (default)
+- `small` - Small size with t3m typography
 - `medium` - Default size with t3m typography
 - `large` - Larger tabs with t3m typography
 
-**Note:** Radio type supports `large` (default, 40px total) and `medium` (32px total) sizes, mapped to Item button sizes `medium` (32px) and `xsmall` (24px) respectively. A radio tab given less room than its title (an explicit `width`, say) truncates the title and shows it in a tooltip.
+**Note:** Radio type supports `medium` (default, 32px total) and `large` (40px total) sizes, mapped to Item button sizes `xsmall` (24px, t4 text) and `medium` (32px, t3m text) respectively. `Radio.Tabs` maps its sizes the same way. A radio tab given less room than its title (an explicit `width`, say) truncates the title and shows it in a tooltip.
 
 ### Placement / Vertical Tabs
 

package/docs/components/overlays/DialogContainer.md

@@ -21,7 +21,7 @@ A DialogContainer accepts a single Dialog as a child, and manages to show and hi
 - **`styles`** `Styles` — Styles for the overlay content shell
 - **`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
-- **`confirmDismiss`** `boolean` — Whether Escape, an outside click and the close button ask "Discard changes?" before they call `onDismiss`. Unset, they ask while a `DialogForm` inside has unsaved edits; `true` always asks, `false` never does. Closing it from code (`isOpen`, removing the child) never asks. See [Unsaved edits](./DialogTrigger.md#unsaved-edits)
+- **`confirmDismiss`** `boolean` — Whether Escape, an outside click and the close button ask "Discard changes?" before they call `onDismiss`. Unset, they ask while a form inside (a `DialogForm`, or a modern `Form`) has unsaved edits; `true` always asks, `false` never does. Closing it from code (`isOpen`, removing the child) never asks. See [Unsaved edits](./DialogTrigger.md#unsaved-edits)
 - **`isOpen`** `boolean` — Whether the modal is open or not
 - **`onDismiss`** `function` — Handler called when the x button of a dismissible Dialog is clicked
 - **`hideOnClose`** `boolean` (default: `false`) — Whether the dialog should be hidden when closed. Focus moves as for a dialog that mounts on open: in on every open, and on close back to the element that opened it, or to the trigger of the menu or popover it sat in once that has closed. [Focus with `hideOnClose`](#focus-with-hideonclose) lists what still differs

package/docs/components/overlays/DialogTrigger.md

@@ -23,7 +23,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`mobileViewport`** `number` (default: `700`) — The screen breakpoint for the mobile type
 - **`isDismissable`** `boolean` (default: `true`) — Whether passive dismissal (Escape or an outside click) can close the dialog. Explicit dialog actions, such as Submit and Cancel, can still close it. A popover that is not dismissable leaves outside presses alone: the control pressed still receives the press, and a text field there can take focus, because such a popover does not hold focus. It stays open when another popover opens, and closes when a modal, tray, fullscreen or panel dialog opens from another `DialogTrigger`.
 - **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
-- **`confirmDismiss`** `boolean` — Whether Escape, an outside click and the close button ask "Discard changes?" before they close the dialog. Unset, they ask while a `DialogForm` inside has unsaved edits; `true` always asks, `false` never does. Explicit actions (Submit, Cancel, the `close` function) never ask, and neither does a popover. See [Unsaved edits](#unsaved-edits)
+- **`confirmDismiss`** `boolean` — Whether Escape, an outside click and the close button ask "Discard changes?" before they close the dialog. Unset, they ask while a form inside (a `DialogForm`, or a modern `Form`) has unsaved edits; `true` always asks, `false` never does. Explicit actions (Submit, Cancel, the `close` function) never ask, and neither does a popover. See [Unsaved edits](#unsaved-edits)
 - **`isOpen`** `boolean` — Whether the dialog is open (controlled)
 - **`defaultOpen`** `boolean` (default: `false`) — Whether the dialog is open by default (uncontrolled)
 - **`offset`** `number` (default: `8`) — The gap between the trigger and a popover, along the main axis. `0` places the popover flush against the trigger
@@ -133,7 +133,7 @@ These properties allow direct style application without using the `styles` prop:
 
 A dialog that holds unsaved edits asks before a passive dismissal discards them: Escape from any control, a click outside the dialog, or its close button opens a "Discard changes?" confirmation instead of closing. **Discard** closes the dialog and calls `onDismiss`; **Keep editing**, Escape or a click outside the confirmation returns to the dialog with its edits and focus where they were.
 
-A `DialogForm` turns this on while a field the user edited differs from its default, so a form dialog needs no wiring; a value set from code doesn't count. For any other dialog, bind `confirmDismiss` to its own state:
+A form inside turns this on while a field the user edited differs from its default, so a form dialog needs no wiring: a `DialogForm`, or a modern `Form` in a dialog you lay out yourself. A value set from code doesn't count, and a successful submit saves the edits it carried, so a dialog that stays open after saving closes at once until the user types again. The dialog asks while any of its forms has unsaved edits. For any other dialog, bind `confirmDismiss` to its own state:
 
 ```jsx
 <DialogTrigger confirmDismiss={notes !== savedNotes}>

package/docs/components/overlays/Notifications.md

@@ -279,6 +279,23 @@ const { total, unread } = useNotificationsCount();
 
 Maximum 5 notifications are visible at once. When a new notification arrives and the cap is reached, the oldest notification is evicted (dismissed) to make room. This ensures the most recent notifications are always visible. Evicted persistent notifications are moved to the persistent list.
 
+## Positioning
+
+Toasts and notifications share one stack, fixed at the top center of the viewport, 16px below the top edge. An app with its own fixed bar at the top can push the stack below it with the `$overlay-inset-top` custom property (`--overlay-inset-top`, default `0px`), added to those 16px. Set it from the component that renders the bar, for as long as the bar is shown:
+
+```tsx
+import { useGlobalStyles } from '@cube-dev/ui-kit';
+
+function TopBar() {
+  // The bar is 6x tall, plus its 1bw bottom border.
+  useGlobalStyles(':root', { '$overlay-inset-top': '(6x + 1bw)' });
+
+  return <BarElement>…</BarElement>;
+}
+```
+
+A collapsed toast stack still slides up to the viewport's top edge, so the 10px strip it leaves sits over the bar, which stays clickable through it.
+
 ## Duration Defaults
 
 - **Non-persistent overlay** — 3000ms

package/docs/components/overlays/Toast.md

@@ -234,7 +234,7 @@ Maximum 3 toasts are visible at once. When the limit is exceeded, the oldest toa
 
 ### Positioning
 - Fixed at top center of the viewport
-- 16px from the top edge
+- 16px from the top edge, plus `$overlay-inset-top` when the app sets it (see [Notification → Positioning](./Notifications.md#positioning))
 - Toasts stack vertically (newest at bottom)
 
 ### Collapse on Hover

package/docs/modern-form-guide.md

@@ -287,4 +287,8 @@ function EditProfileDialog({ initialProfile, save }) {
 }
 ```
 
-The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive. See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.
+The dialog closes only after successful submission, including `form.submit()` and controller-configured callbacks. Validation or save errors keep it open. Closing cancels pending submission; late responses cannot close a reopened session. By default, ending the session resets values. Use `preserve` to retain the draft in a controller owned outside the dialog. `preserve` does not keep an unmounted controller alive.
+
+While a field the user edited differs from its default, Escape, a click outside and the close button ask "Discard changes?" first. That holds for a `<Form>` you place in a `Dialog` yourself too: the root reports its edits to the `DialogTrigger` or `DialogContainer` that owns the dialog, with no wiring. A value set from code is not an edit, and a successful submit saves what it carried, so a dialog that stays open after saving (to show a created key, say) closes at once until the user types again. Set `confirmDismiss={false}` on the trigger or container when backing out loses nothing. See [Unsaved edits](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogtrigger--docs#unsaved-edits).
+
+See the [DialogForm reference](https://cube-ui-kit.vercel.app/?path=/docs/overlays-dialogform--docs) for custom actions, container lifecycle, and legacy behavior.

package/docs/tasty/ai-agents.md

@@ -10,7 +10,7 @@ Notation: ❌ wrong → ✅ correct.
 
 Color tokens (`#name`), custom properties (`$name`), `preset` names, `recipe` names, state aliases (`@mobile`) and extra units are **project-defined** in `tasty.config.ts` or a `configure({ … })` call. Look them up before writing styles. Never invent a name — reuse an existing one, or add it to the config.
 
-Only Tasty's built-ins exist without config: `#white`, `#black`, `#border`, `#outline`, `#current`, `#clear`, and `$gap`, `$radius`, `$border-width`, `$outline-width`, `$transition`, `$sharp-radius`, `$bold-font-weight`, `$font-sans-fallback`, `$font-mono-fallback`.
+Only Tasty's built-ins exist without config: `#white`, `#black`, `#border`, `#outline`, `#current`, `#clear`, and `$gap`, `$radius`, `$border-width`, `$outline-width`, `$transition`, `$sharp-radius`, `$bold-font-weight`, `$icon-size` (only where a `preset` applies), `$font-sans-fallback`, `$font-mono-fallback`.
 
 ## 1. Where styles go
 
@@ -72,6 +72,7 @@ The last row goes the other way — longhands over the shorthand — because `fl
 | `#name.50`            | token at 50% opacity — digits are a decimal fraction: `.5` = `.50` = 50%, `.05` = 5%, `.100` = 10% |
 | `#name.$opacity`      | opacity from a custom property                                                                     |
 | `#clear` / `#current` | `transparent` / `currentcolor`                                                                     |
+| `#a+#b.04`            | `#b` at 4% opacity over `#a`, as one color; layers stack left to right (`#a+#b.1+#c.04`)           |
 | `$name`               | custom property → `var(--name)`                                                                    |
 | `(#a, #b)`            | fallback chain                                                                                     |
 | `$$name` / `##name`   | the custom property _name_ (not its value) — inside `transition`                                   |
@@ -134,7 +135,7 @@ Directional modifiers beat placeholder zeros:
 - ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
 - ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
 
-Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `fill`, `color`, `caretColor`, and `accentColor` take a color only (use `#clear` for transparent). `fill` also mixes two colors with a comma, the weight as a percentage: ❌ `fill: '#surface #dark.04'` (deprecated overlay layer) · ❌ `fill: '#dark.04, #surface'` (half-transparent mix) → ✅ `fill: '#dark 4%, #surface'`.
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `fill`, `color`, `caretColor`, and `accentColor` take a color only (use `#clear` for transparent). An overlay is a compound color, in any color slot: ❌ `fill: '#surface #dark.04'` (deprecated overlay layer) · ❌ `fill: '#dark.04, #surface'` (half-transparent mix) → ✅ `fill: '#surface+#dark.04'`. Write it as one word, with no spaces around `+`. Every layer after the first needs an opacity suffix, and its token must be opaque: a translucent layer token, or one that is `#clear` in some state, leaves the result see-through, so vary the suffix (`#surface+#dark.$hover`) or the whole compound per state instead. A comma mix in `fill` is deprecated too: ❌ `fill: '#dark 4%, #surface'` → ✅ `fill: '#surface+#dark.04'`. For any other mix, write `color-mix()` itself: ✅ `fill: 'color-mix(in srgb, #dark $weight, #surface)'`.
 
 ### `transition`
 

package/docs/tasty/dsl.md

@@ -168,6 +168,7 @@ color: '#purple.5',         // 50% opacity
 color: '#purple.05',        // 5% opacity
 color: '#purple.$fade',     // Opacity from a custom property
 fill: '#current',           // → currentcolor
+fill: '#surface+#dark.04',  // #dark at 4% opacity over #surface, as one color
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
@@ -255,6 +256,57 @@ clamped, and rectangular, so there is no hue to interpolate against
 `transparent`. Nothing configures it — see
 [Color space](configuration.md#color-space).
 
+### Compound colors
+
+Join color tokens with `+` to paint each one, at its own opacity, over the
+colors before it. The result is one color, so it works anywhere a token does:
+
+```jsx
+fill: '#surface+#dark.04',
+// → color-mix(in srgb, var(--dark-color) 4%, var(--surface-color))
+
+border: '1bw #border+#dark.1',
+color: 'light-dark(#primary+#black.2, #primary+#white.2)',
+'#hover-surface': '#surface-2+#surface-text.03',
+```
+
+Read it left to right, bottom layer first: `#surface+#accent.1+#dark.04` paints
+`#accent` at 10% over `#surface`, then `#dark` at 4% over that. Every operand is
+an ordinary token — `#current`, `#clear`, a hex color, a replace token — and
+takes its opacity suffix as it does anywhere: `#surface+#dark.$hover` reads the
+opacity from `$hover`, and a faded base such as `#surface.5+#dark.04` is layered
+as it is.
+
+The layers mix in sRGB, the space browsers composite in, so the color is exactly
+what stacking them as layers would show — but it is one color, which contrast
+checkers can read and transitions interpolate. A faded base is exact too:
+`#surface.5+#dark.04` is as translucent as the two layers would be.
+
+Every layer's token has to be opaque. The mix counts a layer's own alpha as well
+as its opacity suffix, and lowers the alpha of the whole color, so a layer token
+that holds a translucent color, or turns transparent in some state, leaves the
+result see-through: with `'#overlay': { '': '#clear', hovered: '#dark' }`,
+`'#surface+#overlay.04'` is 96% opaque at rest. Vary the opacity instead
+(`'#surface+#dark.$hover'`), or give each state its own color
+(`fill: { '': '#surface', hovered: '#surface+#dark.04' }`).
+
+- Write it as one word: `#surface + #dark.04` is three separate values, and
+  Tasty warns in development.
+- A layer without an opacity covers everything before it: `#surface+#dark` is
+  `#dark`, with a development warning.
+- A layer Tasty can see is transparent — `#clear`, a fade to `.0`, a color with
+  a zero alpha — is left out: `#surface+#clear` is `#surface`.
+- Over a transparent base, a layer is just its fade: `#clear+#dark.04` compiles
+  to `#dark.04`.
+- A `+` joining anything but color tokens (`#surface+1x`) is not a compound: the
+  token is dropped, with a development warning, and the style renders as if
+  that color were not there.
+
+A `+` joins tokens only. To fade a whole compound, give it a token
+(`'#hover-surface': '#surface+#dark.04'`) and fade that (`#hover-surface.5`). For
+a mix that is not a layer over another color, such as an even blend in OKLCH,
+write `color-mix()` itself.
+
 ---
 
 ## CSS Color Functions

package/docs/tasty/styles.md

@@ -303,52 +303,64 @@ Avoid setting physical and logical declarations that resolve to the same edge in
 
 Background color with design token support. Preferred over `backgroundColor` and `background`.
 
-**Syntax:** `[color]`, or two colors mixed with a comma: `[color] [weight%], [color]`
+**Syntax:** `[color]`
 
 | Value | Effect |
 |-------|--------|
 | `"#purple"` | Token-based background color |
 | `"#purple.10"` | Token color at 10% opacity |
-| `"#dark 4%, #surface"` | `#dark` mixed into `#surface` at 4% — the color `#dark` at 4% opacity over `#surface` would show |
+| `"#surface+#dark.04"` | `#dark` at 4% opacity over `#surface`, as one color — see [Compound colors](dsl.md#compound-colors) |
 | `"rgb(255 128 0)"` | CSS color value |
 | `"color-mix(in oklab, #primary 50%, #surface)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 
-#### Mixing two colors
+#### Overlays
 
-A comma between two colors mixes them into one:
+An overlay over a base color is a [compound color](dsl.md#compound-colors):
 
 ```jsx
-fill: '#dark 4%, #surface'
-// → background-color: color-mix(in srgb, var(--dark-color) 4%, var(--surface-color));
+fill: { '': '#surface', hovered: '#surface+#dark.04', pressed: '#surface+#dark.08' }
+// hovered → background-color: color-mix(in srgb, var(--dark-color) 4%, var(--surface-color));
 ```
 
-The comma-separated parts are the arguments of `color-mix()`, as written, mixed in sRGB: the space browsers composite layers in. When the weighted color is opaque, the mix is exactly what drawing it at that opacity over the other color shows. And because it is one `background-color`:
+The overlay token has to be opaque, with its opacity in the suffix: a translucent
+token, or one that turns `#clear` in some state, leaves the background
+see-through. Because the result is one `background-color`:
 
 - contrast checkers such as axe-core and Lighthouse can read it;
 - it transitions and animates between states like any other color;
 - an `image` on the same element stays the only `background-image` layer.
 
-The weight can come from a token or an expression: `'#dark $hover-weight, #surface'`, `'#dark ($hover * 100%), #surface'`.
-
-Give the weight as a percentage, not as an opacity. A color without a percentage takes half the weight, and its own alpha weighs it down again, so the mix comes out see-through: `'#dark.04, #surface'` is 52% opaque, not `#dark` at 4% over `#surface`. In development Tasty warns about a `#name.N` or `#clear` part without a percentage. It can't see into a token, though, so a token holding a translucent color mixes the same way with no warning: keep the token opaque and put its weight in the percentage.
-
-A mix takes two colors. Any more are ignored, with a development warning.
-
 #### Two colors separated by a space (deprecated)
 
 `fill: '#surface #dark.04'` paints the first color as `background-color` and the second as a `linear-gradient()` layer over it, through the `--tasty-second-fill-color` custom property. It still works, with a development warning, and is going away in the next major version: contrast checkers can't see through a `background-image`, so axe-core reports every text node over the layer as *incomplete*.
 
+Put a `+` where the space is:
+
 | Before | After |
 |--------|-------|
-| `'#surface #dark.04'` | `'#dark 4%, #surface'` |
+| `'#surface #dark.04'` | `'#surface+#dark.04'` |
 | `'#surface #clear'` | `'#surface'` |
 | `'#surface #accent'` (an opaque overlay) | `'#accent'` |
-| `'#base #overlay'` (a token holding a translucent color) | `'#overlay $overlay-weight, #base'`, with `#overlay` opaque and `$overlay-weight` a percentage |
+| `'#base #overlay'` (a token holding a translucent color) | `'#base+#overlay.$overlay-alpha'`, with `#overlay` opaque and `$overlay-alpha` its opacity as a number |
 
 The rewrites are exact when the overlay token is opaque. A state map no longer needs the same two-color shape in every state to transition smoothly: every state is now a plain background color.
 
 If an overlay has to stay a translucent token, draw the layer yourself with `fill: '#base', image: 'linear-gradient(#overlay, #overlay)'`. Contrast checkers can't read that either.
 
+#### Two colors mixed with a comma (deprecated)
+
+`fill: '#dark 4%, #surface'` mixes the two colors in sRGB, as the arguments of `color-mix()`: `color-mix(in srgb, var(--dark-color) 4%, var(--surface-color))`. It still works, with a development warning, and is going away in the next major version. A compound color is the same mix, in every color slot, and `color-mix()` itself covers what a compound can't write. `tasty/prefer-fill-mix` in [`@tenphi/eslint-plugin-tasty`](https://github.com/tenphi/eslint-plugin-tasty) rewrites each mix to the same color.
+
+| Before | After |
+|--------|-------|
+| `'#dark 4%, #surface'`, `'#surface, #dark 4%'` | `'#surface+#dark.04'` |
+| `'#accent 10%, #surface+#dark.04'` | `'#surface+#dark.04+#accent.1'` |
+| `'#dark $hover-weight, #surface'` (a percentage) | `'#surface+#dark.$hover-alpha'`, with `$hover-alpha` the opacity as a number — or `'color-mix(in srgb, #dark $hover-weight, #surface)'` |
+| `'#dark, #surface'`, `'rgb(0 0 0) 4%, #surface'`, and any other mix | `'color-mix(in srgb, #dark, #surface)'` — the same parts, in `color-mix()` |
+| `'#dark.04, #surface'` (a translucent part without a percentage) | `'#surface+#dark.04'` |
+
+Every rewrite but the last row's is the same color. `'#dark.04, #surface'` mixed a translucent color in by half and came out 52% opaque, so its rewrite paints what it was most likely meant to: `#dark` at 4% over `#surface`.
+
 There is no default fill color, so `fill: true` is ignored with a development warning. Use `false` for no fill.
 
 **Related deprecated props:** `backgroundColor` (use `fill`), `background` (overrides all background props when set — avoid).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.204.0",
+  "version": "0.206.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -34,7 +34,8 @@
     "docs/tasty",
     "docs/glaze",
     "docs/*.md",
-    "tasty.config.ts"
+    "tasty.config.ts",
+    "tasty.config.generated.ts"
   ],
   "keywords": [
     "uikit"
@@ -59,7 +60,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "2.0.0",
-    "@tenphi/tasty": "3.15.0",
+    "@tenphi/tasty": "3.17.1",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",
@@ -198,6 +199,7 @@
     "add-icons": "cd src/icons && node add-new-icon.js && pnpm fix",
     "audit-docs": "node scripts/audit-docs.mjs",
     "audit-defaults": "UPDATE_DEFAULTS=1 vitest run src/eslint-plugin/defaults.test.ts && prettier --write src/eslint-plugin/defaults.generated.ts",
+    "generate:tasty-config": "UPDATE_TASTY_CONFIG=1 vitest run src/tokens/tasty-config.test.ts && prettier --write tasty.config.generated.ts",
     "diagnostics:compiler": "node scripts/compiler/report.mjs",
     "diagnostics:form": "node scripts/form-diagnostics.mjs",
     "diagnostics:complexity": "node scripts/complexity-report.mjs",