@cube-dev/ui-kit 0.197.0 → 0.198.1

package/docs/components/fields/Select.md

@@ -69,7 +69,7 @@ Choose a different component when the interaction has another shape:
 - **`isOpen`** `boolean` — Whether the dropdown is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the dropdown is open by default (uncontrolled)
 - **`selectionMode`** `'single'` — Selection mode for the select
-- **`onSelectionChange`** `(key: Key) => void` — Callback fired when the selected option changes
+- **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes. Clearing the selection passes `null`
 - **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the dropdown opens or closes
 - **`onFocus`** `(e: FocusEvent) => void` — Callback fired when the select receives focus
 - **`onBlur`** `(e: FocusEvent) => void` — Callback fired when the select loses focus
@@ -541,20 +541,23 @@ Opened with a pointer, the list focuses the selected option, or the list itself
 
 ### Screen Reader Support
 
-- Component announces as "combobox" or "listbox" to screen readers
+- The trigger announces as a button with a listbox popup, named by the value it shows and its label, and described by its description and error message
 - Current selection is announced when changed
 - Available options are announced during navigation
 - Dropdown state (open/closed) is communicated
 
 ### ARIA Properties
 
+The trigger button carries:
+
 - `aria-label` - Provides accessible label when no visible label exists
-- `aria-labelledby` - References external label elements
-- `aria-describedby` - References additional descriptive text
+- `aria-labelledby` - References the selected value, the label and any `aria-labelledby` you pass
+- `aria-describedby` - References the description and the error message, and your own descriptive text
+- `aria-haspopup="listbox"` - Indicates that the trigger opens a list
 - `aria-expanded` - Indicates if dropdown is open
-- `aria-activedescendant` - References the currently focused option
-- `aria-required` - Indicates if selection is required
-- `aria-invalid` - Indicates validation state
+- `aria-controls` - References the list while it is open
+
+The open list is a `listbox`. Options take DOM focus as you move through them, so the trigger has no `aria-activedescendant`.
 
 ## Best Practices
 
@@ -663,7 +666,6 @@ function Example() {
 - Add support for multi-selection mode with visual badges
 - Implement virtual scrolling for very large option lists (1000+ items)
 - Built-in async loading support with loading states per scroll position
-- Enhanced keyboard shortcuts for power users (e.g., type to jump to option)
 - Custom empty state component when no options are available
 - Support for option groups with visual separators beyond sections
 
@@ -673,7 +675,7 @@ function Example() {
 - [FilterPicker](./FilterPicker.md) - For button-triggered selection with a visible search field
 - [ComboBox](./ComboBox.md) - For an input-based searchable field that keeps one selected value
 - [SearchComboBox](./SearchComboBox.md) - For search-and-act flows that clear after each result
-- [ListBox](./ListBox.md) - The underlying list component used in Select
+- [ListBox](./ListBox.md) - A standalone, always-visible list. Select renders its own list, not ListBox
 - [RadioGroup](./RadioGroup.md) - For visible selection options with fewer choices
 - [Menu](../actions/Menu.md) - For action-oriented or navigation dropdowns
 - [Item](../content/Item.md) - The base component used for rendering items

package/docs/components/fields/Switch.md

@@ -96,14 +96,13 @@ The `mods` property accepts the following modifiers you can override:
 ```jsx
 const [isEnabled, setIsEnabled] = useState(false);
 
-<Switch
-  isSelected={isEnabled}
-  onChange={setIsEnabled}
->
-  Feature enabled: {isEnabled ? 'On' : 'Off'}
+<Switch isSelected={isEnabled} onChange={setIsEnabled}>
+  Feature enabled
 </Switch>
 ```
 
+Keep the label the same in both states. The switch announces its own on/off state, so a label that also states it makes screen readers announce the state twice.
+
 ### All Sizes
 
 ### With Validation

package/docs/components/overlays/AlertDialog.md

@@ -19,7 +19,7 @@ A modal dialog for important messages that require user acknowledgment. Extends
   - `cancel` — Cancel button props or `true` to show (default: hidden, uses `{ children: 'Cancel' }`). Set a button's text with `children`; `label` still works but is deprecated
   - `secondary` — Optional secondary button props
 - **`size`** `'S' | 'M' | 'L' | 'small' | 'medium' | 'large'` — The size of the dialog
-- **`isDismissable`** `boolean` (default: `false`) — Whether the dialog is dismissable
+- **`isDismissable`** `boolean` (default: `false`) — Whether the dialog shows its close button
 - **`closeIcon`** `ReactElement` — Custom close icon element
 - **`closeButtonStyles`** `Styles` — Custom styles for the close button
 

package/docs/components/overlays/Dialog.md

@@ -20,7 +20,7 @@ Dialogs are windows containing contextual information, tasks, or workflows that
 - **`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)
+- **`isDismissable`** `boolean` (default: from its `DialogTrigger` or `DialogContainer`) — Whether the dialog shows its close button. Inside a `DialogTrigger` or `DialogContainer` it takes their `isDismissable` (default `true`), except in a popover. A popover or a standalone dialog shows no close button unless you set this prop. `Escape` and outside presses follow the trigger's or container's `isDismissable`, not this one
 - **`onDismiss`** `function` — Callback fired when the dialog is dismissed
 - **`closeIcon`** — Custom close icon element
 - **`role`** `'dialog' | 'alertdialog'` (default: `dialog`) — ARIA role for the dialog
@@ -85,7 +85,7 @@ A `styles` override on a slot is merged into the slot's own styles rather than r
 
 The `mods` property accepts the following modifiers you can override:
 
-- **`dismissable`** `boolean` — Applied when the dialog can be dismissed with close button or Escape key
+- **`dismissable`** `boolean` — Applied when the dialog shows its close button
 
 `Footer` inside a dialog carries one modifier of its own:
 
@@ -137,7 +137,7 @@ The body is the `Content` that is a direct child of the dialog or of a direct-ch
     <Title>Dismissable Dialog</Title>
   </Header>
   <Content>
-    <Paragraph>You can close this dialog with the close button or Escape key.</Paragraph>
+    <Paragraph>You can close this dialog with the close button.</Paragraph>
   </Content>
 </Dialog>
 ```
@@ -178,14 +178,14 @@ The body is the `Content` that is a direct child of the dialog or of a direct-ch
 
 - `Tab` - Moves focus between interactive elements within the dialog
 - `Shift + Tab` - Moves focus backward between interactive elements
-- `Escape` - Dismisses the dialog if `isDismissable` is true
+- `Escape` - Closes the dialog when its `DialogTrigger` or `DialogContainer` is dismissable (`isDismissable`, on by default) and `isKeyboardDismissDisabled` is not set
 - `Enter/Space` - Activates focused buttons or interactive elements
 
 ### Screen Reader Support
 
 - Dialog announces as "dialog" or "alertdialog" based on role, with its title as its name
 - An alert dialog also reads its `Content`, the message, as its description. A plain dialog reads only its title on open, so a form inside it is not read field by field; link a short description with `aria-describedby` when the title alone is not enough
-- Focus moves into the dialog when it opens: to an input marked `data-autofocus`, or to a submit or primary button, otherwise to the dialog itself. In an alert dialog this never picks a destructive (`danger`) button
+- Focus moves into the dialog when it opens: to the last control marked `data-autofocus` that can take focus (the kit's inputs, buttons, `Select` and `CommandMenu` mark themselves with `autoFocus`; a `CommandMenu` focuses its search after the others, so it wins), otherwise to a submit or primary button, otherwise to the dialog itself. In an alert dialog that button is never a destructive (`danger`) one
 - Focus is contained within the dialog from the moment it opens, including while it animates in. A `panel` dialog does not contain focus, nor does a popover opened by a `DialogTrigger` with `isDismissable={false}`
 - Focus returns to the trigger element when dialog closes
 
@@ -241,7 +241,7 @@ The body is the `Content` that is a direct child of the dialog or of a direct-ch
    Only a **direct child** `Form` is treated this way. A form nested deeper, or a plain `<form>` element, is your own layout and is left alone. The layout is the form's own state rather than a rule in `Dialog`, so `styles` on the form still win: `<Form styles={{ gap: '1x' }}>` puts `1x` between the slots.
 
 4. **Accessibility**: Always provide a meaningful title for screen readers
-5. **Dismissal**: Use `isDismissable` for dialogs that users can close voluntarily
+5. **Dismissal**: Set `isDismissable` on the `DialogTrigger` or `DialogContainer` to let users close a dialog with `Escape` or an outside press; Dialog's own `isDismissable` only shows the close button
 6. **Focus Management**: Ensure focus moves to the most important action when dialog opens
 
 ## Integration with Overlays

package/docs/components/overlays/DialogContainer.md

@@ -23,7 +23,7 @@ A DialogContainer accepts a single Dialog as a child, and manages to show and hi
 - **`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
-- **`hideOnClose`** `boolean` (default: `false`) — Whether the dialog should be hidden when closed
+- **`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
 
 ### Base Properties
 
@@ -183,6 +183,25 @@ The Dialog's `isDismissable={false}` hides its built-in visible Close button. Th
 - Focus is trapped within the dialog when open
 - Focus management is handled automatically
 
+### Focus with `hideOnClose`
+
+A dialog kept mounted while closed moves focus as one that mounts on open does, with these exceptions:
+
+- **Unmarked `autoFocus`.** `autoFocus` on a `Menu`, `ListBox`, `Calendar`, `RangeCalendar` or `PeriodCalendar`, and a native `autoFocus` on an element of your own, act once, when the dialog first mounts while hidden, and never on an open. The kit's inputs, buttons, `Select` and `CommandMenu` mark the element they focus with `data-autofocus`, and the dialog focuses the last marked element on every open. Without `hideOnClose`, a `CommandMenu` takes focus over any other autofocused control, wherever it sits, because it focuses its search field after them. Mark an element of your own the same way. On a wrapper, the dialog focuses the wrapper's first tabbable element:
+
+  ```jsx
+  <Dialog>
+    <input data-autofocus aria-label="Name" />
+  </Dialog>
+  ```
+
+- **Focus left on `<body>` on close.** This happens for a dialog opened from a context menu's item (`useContextMenu`, `useAnchoredMenu`) and for one reopened from a dialog it opened (a wizard's Back step). It also happens for one that replaces the dialog that opened it (a wizard's Next step), unless both use `hideOnClose` and neither is rendered inside the other. Move focus yourself after closing it in those cases.
+- **Reopened from a menu item,** a modal dialog focuses the control that was focused when it last closed. Leave `hideOnClose` off such a dialog when it must open on its first control, or move focus yourself after opening it.
+- **Opened from a button in a popover,** it holds focus only once the popover has finished closing, about a third of a second later. Until then focus goes back to that button, so a screen reader announces it again. Escape pressed in that moment does nothing, and Tab moves out of a panel to the page; in a modal it is lost. Leave `hideOnClose` off a dialog opened this way where that matters.
+- **Opened from inside another open modal,** it must be rendered inside that modal's dialog. Rendered elsewhere, focus stays in the modal behind it, so a keyboard user can neither reach nor close the dialog on top. A dialog that replaces the modal is the exception above.
+- **Tab from the last control, opened with nothing to return to.** A panel, or a popover that is not dismissable, opened while focus is on `<body>` or from a control that hides itself, lets Tab past its last control move natively, but that control's own key handling never sees the key, so a `CommandTextArea` does not accept its suggestion on Tab. This happens only when another element had focus when the dialog first mounted. Open it from a control that stays on the page, or leave `hideOnClose` off.
+- **Nested in another overlay,** it opens above that overlay only in browsers that support `Element.moveBefore`. In other browsers it opens behind it, so leave `hideOnClose` off a nested dialog where those browsers matter.
+
 ### ARIA Properties
 
 - `aria-modal` - Not set. While a modal, fullscreen or tray dialog is open, the page behind it is `aria-hidden` instead, so a screen reader's reading cursor stays in the dialog. Lists, menus and popovers opened from the dialog render outside it and stay readable, which `aria-modal` would prevent. Popover and panel dialogs leave the page readable

package/docs/components/overlays/DialogTrigger.md

@@ -30,7 +30,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`containerPadding`** `number` (default: `12`) — The padding between the edge of the overlay and the boundary
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the overlay should flip positions when insufficient space
 - **`shouldUpdatePosition`** `boolean` — Whether the overlay position should update on scroll or resize
-- **`hideOnClose`** `boolean` — Whether to hide the overlay instead of unmounting on close
+- **`hideOnClose`** `boolean` — Whether to hide the overlay instead of unmounting on close. Focus moves as for a dialog that mounts on open ([what still differs](./DialogContainer.md#focus-with-hideonclose))
 - **`onOpenChange`** `function` — Callback fired when the dialog open state changes
 - **`onDismiss`** `function` — Callback fired when the dialog is dismissed
 - **`targetRef`** — The ref of the element the Dialog should visually attach itself to. A popover closes when this element scrolls, as one attached to its trigger does
@@ -165,11 +165,13 @@ function ControlledDialog() {
 
 ### ARIA Properties
 
-- `aria-haspopup` - Automatically applied to trigger element
-- `aria-expanded` - Indicates dialog open state
+- `aria-expanded` - Set on the trigger of a popover dialog: whether the popover is open
+- `aria-controls` - Set on the trigger of an open popover dialog, referencing the dialog
 - `aria-labelledby` - Links dialog to its title
 - `aria-describedby` - Set for an alert dialog, linking its message; see [Dialog](./Dialog.md#aria-properties)
 
+Triggers of every other type get neither `aria-expanded` nor `aria-controls`, and DialogTrigger adds `aria-haspopup` to no trigger.
+
 ## Best Practices
 
 1. **Do**: Provide clear trigger labels

package/docs/tasty/README.md

@@ -16,7 +16,7 @@ Use this hub to move from the core idea to a working component, then into design
 
 - **Application developer using an existing design system**: [Getting Started](getting-started.md), then [React API](react-api.md).
 - **Design-system author**: [Methodology](methodology.md), [Building a Design System](design-system.md), [Configuration](configuration.md), and [Adoption Guide](adoption.md).
-- **Platform or tooling engineer**: [Configuration](configuration.md), [Build-Time Extraction (`tastyStatic`)](tasty-static.md), [Server-Side Rendering](ssr.md), and [Debug Utilities](debug.md).
+- **Platform or tooling engineer**: [Configuration](configuration.md), [Plugins & Extension Points](plugins.md), [Build-Time Extraction (`tastyStatic`)](tasty-static.md), [Server-Side Rendering](ssr.md), and [Debug Utilities](debug.md).
 
 ## By Styling Approach
 
@@ -29,6 +29,9 @@ Use this hub to move from the core idea to a working component, then into design
 ## By Task
 
 - **Learn the style language**: [Style DSL](dsl.md)
+- **Set up linting and autocomplete**: [Getting Started — ESLint plugin](getting-started.md#eslint-plugin) and [TypeScript autocomplete](getting-started.md#typescript-autocomplete)
+- **Design a component's public API** (`styleProps`, `modProps`, `tokenProps`, variants, sub-elements): [React API](react-api.md), then [Methodology](methodology.md)
+- **Generate a color palette with contrast solving**: [Glaze](../README.md#glaze)
 - **Brief an AI agent (or yourself) on writing correct styles**: [Style Rules for AI Agents](ai-agents.md)
 - **Look up a property handler**: [Style Properties](styles.md)
 - **Define tokens, units, recipes, keyframes, properties, functions, or polyfills globally**: [Configuration](configuration.md)

package/docs/tasty/adoption.md

@@ -24,7 +24,8 @@ Product code
 - The DSL and value parser (tokens, custom units, auto-calc, color opacity)
 - State compilation (mutually exclusive selectors from state maps)
 - Style injection and deduplication (runtime or build-time)
-- The `tasty()` component factory and hooks API
+- The `tasty()` component factory and style functions (`useStyles`, `useGlobalStyles`, …)
+- The lint rules and TypeScript extension interfaces that check usage against your vocabulary
 
 **What the DS team owns:**
 
@@ -64,16 +65,18 @@ For a detailed comparison with Tailwind, Panda CSS, vanilla-extract, StyleX, Sti
 
 Tasty provides the engine. The DS team defines the language that runs on it. Here is what that typically involves:
 
-| Layer              | What you define                                            | Where                                      |
-| ------------------ | ---------------------------------------------------------- | ------------------------------------------ |
-| **Tokens**         | Color names, spacing scale, border widths, radii           | `configure({ tokens })`                    |
-| **Units**          | Custom multiplier units (`x`, `r`, `bw`, or your own)      | `configure({ units })`                     |
-| **State aliases**  | Responsive breakpoints, theme modes, feature flags         | `configure({ states })`                    |
-| **Recipes**        | Reusable style bundles (card, elevated, input-reset)       | `configure({ recipes })`                   |
-| **Typography**     | Preset definitions (h1-h6, t1-t4, etc.)                    | `configure({ presets: { ... } })`          |
-| **Style props**    | Which CSS properties each component exposes as React props | `styleProps` in each component             |
-| **Sub-elements**   | Inner parts of compound components (Title, Icon, Content)  | `elements` + capitalized keys in `styles`  |
-| **Override rules** | How product engineers extend or constrain components       | Styled wrappers via `tasty(Base, { ... })` |
+| Layer              | What you define                                                                     | Where                                               |
+| ------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **Tokens**         | Color names and named values (`#surface`, `$sidebar-width`)                         | `configure({ tokens })`                             |
+| **Units**          | Spacing step, radius, border and outline widths (`x`, `r`, `bw`, `ow`, or your own) | `configure({ units })`                              |
+| **State aliases**  | Responsive breakpoints, theme modes, feature flags                                  | `configure({ states })`                             |
+| **Recipes**        | Reusable style bundles (card, elevated, input-reset)                                | `configure({ recipes })`                            |
+| **Typography**     | Preset definitions (h1-h6, t1-t4, etc.)                                             | `configure({ presets: { ... } })`                   |
+| **Style props**    | Which CSS properties each component exposes as React props                          | `styleProps` in each component                      |
+| **Sub-elements**   | Inner parts of compound components (Title, Icon, Content)                           | `elements` + capitalized keys in `styles`           |
+| **Component API**  | Typed props for states, values, and looks                                           | `modProps`, `tokenProps`, `variants`                |
+| **Override rules** | How product engineers extend or constrain components                                | Styled wrappers via `tasty(Base, { ... })`          |
+| **Guardrails**     | The names the linter and TypeScript check against                                   | `tasty.config.ts`, `declare module '@tenphi/tasty'` |
 
 The same engine can power a minimal design system with a handful of tokens:
 
@@ -155,18 +158,23 @@ configure({
     '#surface': '#white',
     '#text': '#111',
     '$card-padding': '4x',
+    $gap: '8px',
+    $radius: '6px',
+    '$border-width': '1px',
   },
-  // Common units (x, r, bw, ow, cr) are built-in.
-  // A DS typically redefines them to use CSS custom properties
-  // so that the actual scale is controlled via CSS, not JS:
+  // Built-in units (x, r, cr, bw, ow) compile to fixed values by default.
+  // A DS often points them at the custom properties above, so the scale
+  // is controlled by CSS at runtime rather than fixed at build time:
   units: {
-    x: 'var(--gap)', // 2x → calc(var(--gap) * 2)
+    x: 'var(--gap)', // 2x → calc(2 * var(--gap))
     r: 'var(--radius)',
     bw: 'var(--border-width)',
   },
 });
 ```
 
+Turn on the guardrails in the same step. Add [`@tenphi/eslint-plugin-tasty`](https://github.com/tenphi/eslint-plugin-tasty) with `tasty.configs.recommended` and a `tasty.config.ts` that lists the tokens, units, states, presets, and recipes as you define them, and register the same color and preset names for TypeScript autocomplete (`TastyNamedColors`, `TastyPresetNames`). Every component you migrate from here on is checked against the vocabulary. See [Getting Started — ESLint plugin](getting-started.md#eslint-plugin).
+
 ### Phase 3 -- State aliases and recipes
 
 Define the state vocabulary your components will share. This is where you start encoding your team's conventions.
@@ -175,7 +183,7 @@ Define the state vocabulary your components will share. This is where you start
 configure({
   states: {
     '@mobile': '@media(w < 768px)',
-    '@tablet': '@media(w < 1024px)',
+    '@tablet': '@media(768px <= w < 1024px)',
     '@dark':
       '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
   },
@@ -252,7 +260,7 @@ const Card = tasty({
 
 ### Phase 7 -- Expand to full DS coverage
 
-Migrate the remaining components, add the [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) to enforce style conventions at lint time, and choose between [server-only `tasty()`](ssr.md) and [`tastyStatic()` build-time extraction](tasty-static.md) when a page should ship no Tasty styling runtime.
+Migrate the remaining components, switch the [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) to `tasty.configs.strict` to also catch unknown `$` tokens and state aliases, and choose between [server-only `tasty()`](ssr.md) and [`tastyStatic()` build-time extraction](tasty-static.md) when a page should ship no Tasty styling runtime.
 
 ---
 

package/docs/tasty/ai-agents.md

@@ -10,6 +10,8 @@ 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`.
+
 ## 1. Where styles go
 
 ```jsx
@@ -64,19 +66,21 @@ The last row goes the other way — longhands over the shorthand — because `fl
 
 ### Tokens
 
-| Syntax                | Meaning                                                                   |
-| --------------------- | ------------------------------------------------------------------------- |
-| `#name`               | color token → `var(--name-color)`                                         |
-| `#name.50`            | token at 50% opacity (`0`–`100`)                                          |
-| `#name.$opacity`      | opacity from a custom property                                            |
-| `#clear` / `#current` | `transparent` / `currentcolor`                                            |
-| `$name`               | custom property → `var(--name)`                                           |
-| `(#a, #b)`            | fallback chain                                                            |
-| `$$name` / `##name`   | the custom property _name_ (not its value) — inside `transition`          |
-| `$$name(…)`           | call a CSS `@function` declared via `@function`, `useFunction`, or config |
-
-- ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
+| Syntax                | Meaning                                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------------------- |
+| `#name`               | color token → `var(--name-color)`                                                                  |
+| `#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`                                                                     |
+| `$name`               | custom property → `var(--name)`                                                                    |
+| `(#a, #b)`            | fallback chain                                                                                     |
+| `$$name` / `##name`   | the custom property _name_ (not its value) — inside `transition`                                   |
+| `$$name(…)`           | call a CSS `@function` declared via `@function`, `useFunction`, or config                          |
+
+- ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `okhst(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
+- CSS system colors (`Canvas`, `CanvasText`, `Highlight`, `ButtonText`, `GrayText`, …) are the exception, for `forced-colors` styles: hold one in a token (`'#forced-border': 'CanvasText'`) or write it under a `@media(forced-colors: active)` state.
 - ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
+- `#clear` is a default replace token for `transparent`, so `#clear.5` and `#clear.$opacity` stay transparent. It does not read `--clear-color`; override it through `replaceTokens` if needed.
 - A `$name` must be declared as a `'$name': value` key in the same styles object, or in the config.
 - Names are case-sensitive and start lowercase — `$myVar` → `--myVar`; a leading capital folds (`$Foo` → `--foo`). Prefer kebab-case.
 - A `$name` reference is untyped: it fills the first free slot in a shorthand (`border: '1bw $my-style'` → the line style). Write colors as `#name`; `$name-color` is a fallback for pointing at a raw CSS custom property that holds a color.
@@ -84,7 +88,7 @@ The last row goes the other way — longhands over the shorthand — because `fl
 
 ### Units
 
-Tasty units: `x` (gap multiple), `r` (radius), `cr` (card radius), `bw` (border width), `ow` (outline width), `sf` (`minmax(0, Nfr)`). All CSS units work too, plus anything in `units` in the config. Any other unit is an error.
+Tasty units and their defaults: `x` 8px spacing step, `r` 6px radius, `cr` 10px card radius, `bw` 1px border width, `ow` 3px outline width, `sf` → `minmax(0, Nfr)`. They compile to literal values; change them through `units` in the config, not with `$gap`/`$radius` tokens. All CSS units work too, plus anything in `units` in the config. Any other unit is an error. Inside `@media(…)` / `@(…)` conditions units resolve to their literal length (`@media(w < 40x)` → `width < 320px`), unless the project points that unit at a custom property; then write query lengths in `px`, `em`, or `rem`.
 
 Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'` → `'1r'`; `border: '1px …'` → `'1bw …'`.
 
@@ -94,7 +98,7 @@ Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'
 
 ### `true`
 
-`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `scrollMargin`, `scrollPadding`, and the enhanced logical category styles listed above, plus `hide`. Anywhere else it is an error.
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `color`, `fade`, `preset`, `font`, `scrollbar`, `scrollMargin`, `scrollPadding`, and the enhanced logical category styles listed above, plus `hide`. Anywhere else it is an error.
 
 ### `!important`
 
@@ -104,21 +108,23 @@ Never use it. Tasty owns specificity through doubled selectors and state orderin
 
 A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). A group that names **direction** modifiers takes a **single** value, applied to every direction it names — per-side values come from comma groups. A group naming no direction keeps plain CSS shorthand order (1–4 values). (`inset` + `dock` is the one exception: a second value insets the spanned sides.) Only the modifiers a property knows are valid:
 
-| Property                             | Modifiers                                                                                                  |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `padding`, `margin`, `inset`, `fade` | `top` `right` `bottom` `left`                                                                              |
-| `border`                             | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden` |
-| logical axis spacing/inset styles    | `start` `end`                                                                                              |
-| `blockBorder`, `inlineBorder`         | `start` `end` + the border style keywords above                                                            |
-| `outline`                            | the style keywords above                                                                                   |
-| `radius`                             | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf`                                 |
-| `width`, `height`, `blockSize`, `inlineSize` | `min` `max` `fixed`                                                                                |
-| `flow`                               | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense`                                      |
-| `overflow`                           | `visible` `hidden` `scroll` `clip` `auto` `overlay`                                                        |
-| `position`                           | `static` `relative` `absolute` `fixed` `sticky`                                                            |
-| `shadow`                             | `inset`                                                                                                    |
-| `preset`                             | `name / strong` (or `bold`) `italic` `icon` `tight`                                                        |
-| box properties                       | `longhand` — emit CSS longhands instead of the shorthand                                                   |
+| Property                                     | Modifiers                                                                                                                                          |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `padding`, `margin`, `fade`                  | `top` `right` `bottom` `left`                                                                                                                      |
+| `inset`                                      | the four directions + `dock`                                                                                                                       |
+| `border`                                     | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden`                                         |
+| logical axis spacing/inset styles            | `start` `end`                                                                                                                                      |
+| `blockBorder`, `inlineBorder`                | `start` `end` + the border style keywords above                                                                                                    |
+| `outline`                                    | the style keywords above                                                                                                                           |
+| `radius`                                     | `top` `right` `bottom` `left`, corners `top-left` `top-right` `bottom-right` `bottom-left`, `inherit` + shapes `round` `ellipse` `leaf` `backleaf` |
+| `width`, `height`, `blockSize`, `inlineSize` | `min` `max` `fixed`                                                                                                                                |
+| `flow`                                       | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense`                                                                              |
+| `overflow`                                   | `visible` `hidden` `scroll` `clip` `auto` `overlay`                                                                                                |
+| `position`                                   | `static` `relative` `absolute` `fixed` `sticky`                                                                                                    |
+| `shadow`                                     | `inset`                                                                                                                                            |
+| `preset`                                     | `name / strong` (or `bold`) `italic` `icon` `tight` `normal`                                                                                       |
+| `scrollbar`                                  | `thin` `auto` `none` `stable` `both-edges` `always`                                                                                                |
+| box properties                               | `longhand` — emit CSS longhands instead of the shorthand                                                                                           |
 
 Directional modifiers beat placeholder zeros:
 
@@ -128,11 +134,11 @@ 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` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
+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).
 
 ### `transition`
 
-Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
+Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset`.
 
 ❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill'`
 
@@ -168,13 +174,13 @@ Precedence `!` > `^` > `|` > `&`; use parentheses to override.
 
 Rules:
 
-1. **`''` comes first.** The bare default is the lowest-priority state; placing it later would override everything above it.
+1. **`''` comes first.** The bare default is the lowest-priority state. Written later, it triggers a `MISPLACED_DEFAULT_STATE` warning and Tasty moves it to the front.
 2. **Every state map needs `''` or `_`** — except when extending (`tasty(Parent, …)`), where omitting `''` merges into the parent's states and including `''` replaces them wholesale.
 3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be _unknown_ (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
 4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
 5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
 6. **Write keys Tasty can fully read.** Names start with a letter (a single letter is fine: `x` → `[data-x]`); join states with an operator (`hovered & focused`, not `hovered focused`); no space between `@media` and `(`. Tasty warns (`INVALID_STATE_KEY`) and skips what it cannot read.
-7. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
+7. **Prefer automatic native states:** use `disabled`, `checked`, and `hidden` in Tasty component styles instead of `[disabled]`, `[checked]`, and `[hidden]`. Tasty sets `data-disabled`, `data-checked`, and `data-hidden` from the native props automatically.
 
 ```jsx
 color: { '': '#text', hovered: '#accent', disabled: '#text.40' }
@@ -204,11 +210,13 @@ When extending a parent's state map: `'@inherit'` reuses the parent's value for
 A **capitalized** key targets `[data-element="Name"]`, and its value must be a style object.
 
 ```jsx
-styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent' } }
+styles: { Title: { preset: 'h3' }, Icon: { $: '>', color: { '': '#text', '@own(:last-child)': '#accent' } } }
 ```
 
 ❌ nested-selector keys (`'& .title'`, `'&:hover'`) → ✅ sub-elements and state maps. Use the `$` affix property inside a sub-element to control how its selector attaches (`>` direct child, `@` placeholder for the element itself, `&::before` for a root pseudo-element).
 
+When `$` ends in a pseudo-element, `@own(…)` is the pseudo-element's own state (`'@own(:focus)'` → `::part(label):where(:focus)`). A pseudo-element has no attributes, classes, or tree position, so `@own([open])`, `@own(hovered)`, or `@own(:first-child)` there is ignored with a warning. Put a condition on the element before the pseudo-element in `$`: `$: 'a[rel="next"]::before'`.
+
 ## 6. Special top-level keys
 
 | Key              | Shape                                                                                                       |

package/docs/tasty/comparison.md

@@ -6,7 +6,7 @@ Tasty is CSS-in-JS for React design systems. It is built for the point where reu
 
 Its distinctive guarantee is narrow and concrete: each property’s state map compiles into selectors that cannot compete, so one declared branch wins regardless of CSS source order.
 
-That does not require a big upfront configuration step. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
+That does not require a big upfront configuration step. Tasty's built-in units and normal CSS color values work out of the box, and the built-in `okhsl(...)` and `okhst(...)` color functions are available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
 
 Most styling tools focus on one of these layers:
 
@@ -95,11 +95,12 @@ That makes Tasty less of a "better way to write CSS objects" and more of a **sta
 
 Beyond state resolution, Tasty also provides several structural capabilities that reinforce the design-system layer:
 
-- **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. This keeps layout and composition controls inside a governed component API instead of pushing teams back to ad hoc styling escapes.
-- **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and `data-element` attributes. States, tokens, and recipes apply across the entire element tree from a single definition. See [React API — Sub-element Styling](react-api.md#sub-element-styling).
+- **Typed component APIs** — `styleProps` exposes selected style properties as normal props (`<Button placeSelf="end">`, with state maps for responsive values), `modProps` turns modifiers into typed props (`size: ['sm', 'md', 'lg'] as const`), `tokenProps` passes per-instance values without generating new CSS, and `variants` gives a typed `variant` prop. Layout and composition controls stay inside a governed component API instead of pushing teams back to ad hoc styling escapes.
+- **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and the `elements` option, which produces typed sub-components (`<Card.Title>`) that share the root's state context. States, tokens, and recipes apply across the entire element tree from a single definition. See [React API — Sub-element Styling](react-api.md#sub-element-styling).
+- **Modern CSS as state keys** — Container queries, `@supports`, `:has()`, root and parent states, and `@starting-style` live in the same state maps as `:hover`, and `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` are built in.
 - **Auto-inferred `@property`** — When a custom property is assigned a concrete value, Tasty infers the CSS `@property` syntax and registers it automatically, enabling smooth transitions on custom properties without manual declarations.
 - **AI-friendly style definitions** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, refactor, and generate Tasty styles as confidently as a human — no hidden cascade logic or implicit ordering to second-guess.
-- **Companion ecosystem** — An [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) with 27 lint rules, a [VS Code extension](https://github.com/tenphi/tasty-vscode-extension) for syntax highlighting, and [Glaze](https://github.com/tenphi/glaze) for OKHSL color theme generation with automatic WCAG contrast solving.
+- **Companion ecosystem** — An [ESLint and oxlint plugin](https://github.com/tenphi/eslint-plugin-tasty) with 40+ rules that validate styles against your project's `tasty.config.ts`, TypeScript augmentation for autocompleting your own token and preset names, a [VS Code extension](https://github.com/tenphi/tasty-vscode-extension) for syntax highlighting and snippets, and [Glaze](https://github.com/tenphi/glaze) for OKHST palette generation with WCAG and APCA contrast solving.
 
 ---
 
@@ -184,7 +185,7 @@ Every new state doubles the selector count. Miss one intersection and you ship a
 )}>
 ```
 
-The `theme` branch is runtime JS, not CSS. Intersections like `disabled + hover` need manual `!important` or extra utilities to override correctly.
+The `theme` branch is runtime JS, not CSS. Tailwind resolves `hover:` against `disabled:` by its global variant order, not per component; when your priority differs from that order, or two base utilities conflict (`bg-primary` vs `bg-danger`), you need `tailwind-merge`, `!` modifiers, or more conditional class logic.
 
 **Tasty** — each property declares all its states in one map. The engine generates mutually exclusive selectors:
 
@@ -196,10 +197,10 @@ const Button = tasty({
       '': '#primary',
       ':hover': '#primary-hover',
       ':active': '#primary-pressed',
-      disabled: '#surface',
       'theme=danger': '#danger',
       'theme=danger & :hover': '#danger-hover',
       'theme=danger & :active': '#danger-pressed',
+      disabled: '#surface',
     },
     color: {
       '': '#on-primary',
@@ -213,7 +214,7 @@ const Button = tasty({
 });
 ```
 
-`disabled` always wins over `:hover` because Tasty emits negation selectors — no source-order dependence, no manual intersection management, no `!important`.
+`disabled` is declared last, so it wins over `:hover`, `:active`, and `theme=danger`: Tasty guards every earlier branch with `:not([data-disabled])` — no source-order dependence, no manual intersection management, no `!important`.
 
 ---
 
@@ -328,7 +329,7 @@ That makes it narrower in audience, but deeper in architectural ambition.
 
 There is also a fundamental architectural difference: Emotion and styled-components rely on React context and hooks internally, which means they require `'use client'` in modern React and cannot run as React Server Components. Tasty's style functions and `tasty()` components are hook-free, so they work as server components by default and ship no Tasty styling runtime in server-only contexts. This is not a minor compatibility detail — it means Tasty-based components stay as server components until _your_ code needs interactivity, while Emotion and styled-components force the client boundary at the styling layer.
 
-For teams evaluating runtime styling at scale, Tasty also documents its runtime benchmarks and caching model in the main [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
+For teams evaluating runtime styling at scale, Tasty publishes reproducible [Runtime Benchmarks](runtime-benchmarks.md) and summarizes its caching model in the [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
 
 ---