@tenphi/tasty 3.10.0 → 3.11.1

package/docs/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,20 @@ 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).
 - ❌ `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 +87,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 +97,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 +107,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 +133,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 +173,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,7 +209,7 @@ 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).

package/docs/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.
 
 ---
 

package/docs/configuration.md

@@ -23,9 +23,8 @@ configure({
 
   // Custom units (merged with built-in units)
   units: {
-    vh: 'vh',
-    vw: 'vw',
-    custom: (n) => `${n * 10}px`, // Function-based unit
+    gu: '4px', // `2gu` → `8px`
+    cols: (n) => `calc(${n} * var(--col-width))`, // function-based unit
   },
 
   // Custom functions — a single map for both flavors, discriminated by value type:
@@ -47,35 +46,35 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 
 ## Options
 
-| Option               | Type                                             | Default                               | Description                                                                                                                                                          |
-| -------------------- | ------------------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nonce`              | `string`                                         | -                                     | CSP nonce for style elements                                                                                                                                         |
-| `maxRulesPerSheet`   | `number`                                         | `8192`                                | Maximum rules per injected stylesheet                                                                                                                                |
-| `forceTextInjection` | `boolean`                                        | auto (`true` in test envs)            | Force text-node CSS injection instead of constructable stylesheets                                                                                                   |
-| `devMode`            | `boolean`                                        | auto                                  | Enable development-mode features: performance metrics and debug info                                                                                                 |
-| `states`             | `Record<string, string>`                         | -                                     | Global state aliases for advanced state mapping                                                                                                                      |
-| `parserCacheSize`    | `number`                                         | `1000`                                | Parser LRU cache size                                                                                                                                                |
-| `units`              | `Record<string, string \| UnitHandler>`          | Built-in                              | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units)                                                                                     |
-| `functions`          | `Record<string, FunctionDefinition \| Function>` | -                                     | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                      |
-| `handlers`           | `Record<string, StyleHandlerDefinition>`         | Built-in                              | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers)                                                                        |
-| `propHandlers`       | `Record<string, PropHandlerDefinition>`          | -                                     | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware)                                                                |
-| `baseStyleProps`     | `readonly string[]`                              | -                                     | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props)                                                                       |
-| `tokens`             | `Record<string, value \| stateMap>`              | -                                     | Design tokens injected as `:root` CSS custom properties                                                                                                              |
-| `replaceTokens`      | `Record<string, string \| number \| boolean>`    | -                                     | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens                                                                        |
-| `keyframes`          | `Record<string, KeyframesSteps>`                 | -                                     | Global keyframes for animations                                                                                                                                      |
-| `properties`         | `Record<string, PropertyDefinition>`             | -                                     | Global CSS @property definitions                                                                                                                                     |
-| `fontFaces`          | `Record<string, FontFaceInput>`                  | -                                     | Global @font-face definitions                                                                                                                                        |
-| `counterStyles`      | `Record<string, CounterStyleDescriptors>`        | -                                     | Global @counter-style definitions                                                                                                                                    |
-| `polyfills`          | `{ functions?: boolean }`                        | `{}`                                  | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time                                             |
-| `autoPropertyTypes`  | `boolean`                                        | `true`                                | Auto-infer and register `@property` types from values                                                                                                                |
-| `recipes`            | `Record<string, RecipeStyles>`                   | -                                     | Predefined style recipes (named style bundles)                                                                                                                       |
-| `presets`            | `Record<string, TypographyPreset>`               | -                                     | Typography presets — shorthand for `generateTypographyTokens()`                                                                                                      |
-| `globalStyles`       | `Record<string, Styles>`                         | -                                     | Global Tasty styles keyed by CSS selector                                                                                                                            |
-| `plugins`            | `TastyPlugin[]`                                  | -                                     | Plugins that bundle any of the above (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md)                        |
-| `gc`                 | `GCConfig`                                       | -                                     | Garbage-collection tuning for unused styles (`{ touchInterval, capacity }`)                                                                                          |
-| `batchInjection`     | `boolean \| 'always'`                            | `false`                               | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection)                                                                     |
-| `colorSpace`         | `'rgb' \| 'hsl' \| 'oklch'`                      | -                                     | **Deprecated** — no longer has any effect. See [Color space](#color-space)                                                                                           |
-| `namePrefix`         | `string`                                         | `'t'` (`tasty`) / `'ts'` (build-time) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix). |
+| Option               | Type                                             | Default                                                                              | Description                                                                                                                                                                                                                                                                                                                             |
+| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nonce`              | `string`                                         | -                                                                                    | CSP nonce for style elements                                                                                                                                                                                                                                                                                                            |
+| `maxRulesPerSheet`   | `number`                                         | `8192`                                                                               | Maximum rules per injected stylesheet                                                                                                                                                                                                                                                                                                   |
+| `forceTextInjection` | `boolean`                                        | `false` (`true` in test environments only while `configure()` has never been called) | Force text-node CSS injection instead of constructable stylesheets. Set it explicitly in test setup                                                                                                                                                                                                                                     |
+| `devMode`            | `boolean`                                        | auto                                                                                 | Enable development-mode features: performance metrics and debug info. Does not turn on dev warnings; those follow `NODE_ENV` (or `localStorage.TASTY_DEBUG = 'true'` in a browser)                                                                                                                                                      |
+| `states`             | `Record<string, string>`                         | -                                                                                    | Global state aliases for advanced state mapping                                                                                                                                                                                                                                                                                         |
+| `parserCacheSize`    | `number`                                         | `1000`                                                                               | Parser LRU cache size                                                                                                                                                                                                                                                                                                                   |
+| `units`              | `Record<string, string \| UnitHandler>`          | Built-in                                                                             | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units)                                                                                                                                                                                                                                                        |
+| `functions`          | `Record<string, FunctionDefinition \| Function>` | -                                                                                    | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                                                                                                                                                                                         |
+| `handlers`           | `Record<string, StyleHandlerDefinition>`         | Built-in                                                                             | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers)                                                                                                                                                                                                                                           |
+| `propHandlers`       | `Record<string, PropHandlerDefinition>`          | -                                                                                    | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware)                                                                                                                                                                                                                                   |
+| `baseStyleProps`     | `readonly string[]`                              | -                                                                                    | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props)                                                                                                                                                                                                                                          |
+| `tokens`             | `Record<string, value \| stateMap>`              | -                                                                                    | Design tokens injected as `:root` CSS custom properties                                                                                                                                                                                                                                                                                 |
+| `replaceTokens`      | `Record<string, string \| number \| boolean>`    | `{ '#clear': 'transparent' }`                                                        | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens                                                                                                                                                                                                                                           |
+| `keyframes`          | `Record<string, KeyframesSteps>`                 | -                                                                                    | Global keyframes for animations                                                                                                                                                                                                                                                                                                         |
+| `properties`         | `Record<string, PropertyDefinition>`             | -                                                                                    | Global CSS @property definitions                                                                                                                                                                                                                                                                                                        |
+| `fontFaces`          | `Record<string, FontFaceInput>`                  | -                                                                                    | Global @font-face definitions                                                                                                                                                                                                                                                                                                           |
+| `counterStyles`      | `Record<string, CounterStyleDescriptors>`        | -                                                                                    | Global @counter-style definitions                                                                                                                                                                                                                                                                                                       |
+| `polyfills`          | `{ functions?: boolean }`                        | `{}`                                                                                 | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time                                                                                                                                                                                                                |
+| `autoPropertyTypes`  | `boolean`                                        | `true`                                                                               | Auto-infer and register `@property` types from values                                                                                                                                                                                                                                                                                   |
+| `recipes`            | `Record<string, RecipeStyles>`                   | -                                                                                    | Predefined style recipes (named style bundles)                                                                                                                                                                                                                                                                                          |
+| `presets`            | `Record<string, TypographyPreset>`               | -                                                                                    | Typography presets — shorthand for `generateTypographyTokens()`                                                                                                                                                                                                                                                                         |
+| `globalStyles`       | `Record<string, Styles>`                         | -                                                                                    | Global Tasty styles keyed by CSS selector                                                                                                                                                                                                                                                                                               |
+| `plugins`            | `TastyPlugin[]`                                  | -                                                                                    | Plugins that bundle `functions`, `units`, `states`, `handlers`, `propHandlers`, `baseStyleProps`, `tokens`, `replaceTokens`, `recipes`, `presets`, `globalStyles`, `properties`, `keyframes`, `fontFaces`, and `counterStyles` (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md) |
+| `gc`                 | `GCConfig`                                       | -                                                                                    | Turns on automatic collection of unused styles: `{ touchInterval?, capacity?, grace? }` (defaults `1000`, `1000`, `10000` ms). Without it nothing is collected automatically; call `gc()` yourself                                                                                                                                      |
+| `batchInjection`     | `boolean \| 'always'`                            | `false`                                                                              | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection)                                                                                                                                                                                                                                        |
+| `colorSpace`         | `'rgb' \| 'hsl' \| 'oklch'`                      | -                                                                                    | **Deprecated** — no longer has any effect. See [Color space](#color-space)                                                                                                                                                                                                                                                              |
+| `namePrefix`         | `string`                                         | `'t'` (`tasty`) / `'ts'` (build-time)                                                | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix).                                                                                                                                                                    |
 
 ---
 
@@ -334,8 +333,7 @@ Tokens support state maps for responsive or theme-aware values:
 ```jsx
 configure({
   tokens: {
-    $gap: '4px',
-    $radius: '6px',
+    '$sidebar-width': '280px',
     '#primary': {
       '': '#purple',
       '@dark': '#light-purple',
@@ -350,9 +348,10 @@ configure({
 
 - `$name` keys become `--name` CSS custom properties
 - `#name` keys become `--name-color` custom properties
+- Tokens do not change units: `2x` stays `16px` whatever `$gap` is. To drive a unit from a token, point the unit at it: `units: { x: 'var(--gap)' }` makes `2x` compile to `calc(2 * var(--gap))`
 - Names keep their case, since CSS custom properties are case-sensitive: `$myVar` is `--myVar` and is referenced as `$myVar`. A leading capital is not supported and folds — `$Foo` and `#Purple` become `--foo` and `--purple-color` — so start names lowercase. Kebab-case (`$my-var`) remains the convention.
 
-Tokens are automatically emitted in all delivery modes: client rendering, server rendering, and build-time extraction with the Babel plugin.
+Tokens are emitted by the client injector, by the SSR collector (`TastyRegistry`, `tastyIntegration()`, `runWithCollector()`), by the `withTastyNext()` shared stylesheet, and by the Babel plugin. The inline React Server Component path without a collector does not emit them — see [Server-Side Rendering](ssr.md).
 
 ---
 
@@ -375,6 +374,17 @@ configure({
 
 When a component uses `padding: '$card-padding'`, the parser replaces it with `'4x'` before generating CSS. When a component uses `fill: '#accent'`, it is replaced with `'#purple'`, which in turn resolves to `var(--purple-color)`.
 
+Tasty includes `'#clear': 'transparent'` as a default replace token, available
+without calling `configure()`. It survives `resetConfig()`, and explicit
+`replaceTokens` entries can override it. A replace token resolving to the literal
+`transparent` ignores numeric and custom-property opacity suffixes:
+`#clear`, `#clear.5`, and `#clear.$opacity` all emit `transparent`.
+
+`#clear` no longer reads `--clear-color`, and Tasty no longer registers that
+property by default. If you previously customized `#clear` through `tokens`,
+local token definitions, or CSS, use a different color token or explicitly
+override `replaceTokens['#clear']` instead.
+
 See [Replace Tokens](dsl.md#replace-tokens) in the Style DSL reference.
 
 ---
@@ -471,7 +481,7 @@ See [Functions (`@function`)](dsl.md#functions-function) for inline usage inside
 
 ### Custom color functions
 
-A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `#token.alpha` opacity injection, and `parseColor` — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
+A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `parseColor`, and the `#token.alpha` opacity suffix, which calls the function with a `/ alpha` part appended (read `groups[0].parts[1]`, as below) — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
 
 ```ts
 import { configure, createColorFunc } from '@tenphi/tasty';
@@ -482,8 +492,12 @@ const myColorPlugin = () => ({
   functions: {
     // Hand-written parse function:
     mycolor: (groups) => {
-      const [r, g, b] = groups[0].all;
-      return `rgb(${r} ${g} ${b})`;
+      // `mycolor(255 0 0 / .5)` and `#brand.5` both arrive as two parts
+      const [main, alpha] = groups[0].parts;
+      const [r, g, b] = main.all;
+      return alpha?.all.length
+        ? `rgb(${r} ${g} ${b} / ${alpha.output})`
+        : `rgb(${r} ${g} ${b})`;
     },
   },
 });
@@ -690,10 +704,16 @@ Override or extend the built-in style property handlers. A handler definition ca
 | Single dep    | `['styleName', handler]`           | Triggered by the specified style property                       |
 | Multi dep     | `[['dep1', 'dep2', ...], handler]` | Triggered by any of the listed properties; receives all of them |
 
-The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy). Use `defineHandler` for it and the dependency types are inferred from the dependency list, so a typo in the destructure is a type error instead of a silent `undefined`.
+The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy). A handler whose dependencies include a built-in style takes over that style's whole group — see [Replacing a built-in handler](#replacing-a-built-in-handler). Use `defineHandler` for it and the dependency types are inferred from the dependency list, so a typo in the destructure is a type error instead of a silent `undefined`.
 
 ```jsx
-import { configure, defineHandler, styleHandlers } from '@tenphi/tasty';
+import {
+  configure,
+  defineHandler,
+  parseColor,
+  parseStyle,
+  styleHandlers,
+} from '@tenphi/tasty';
 
 configure({
   handlers: {
@@ -717,6 +737,10 @@ configure({
         'backgroundPosition',
         'backgroundSize',
         'backgroundRepeat',
+        'backgroundAttachment',
+        'backgroundOrigin',
+        'backgroundClip',
+        'background',
       ],
       (props) => {
         if (
@@ -729,12 +753,18 @@ configure({
       },
     ),
 
-    // Multi dep — handler reads multiple style properties
-    gap: defineHandler(['display', 'flow', 'gap'], ({ display, flow, gap }) => {
-      if (!gap) return;
-      const isGrid = String(display ?? '').includes('grid');
-      return { gap: isGrid ? gap : `/* custom logic for ${flow} */` };
-    }),
+    // Multi dep — triggered by either name, receives both
+    stripe: defineHandler(
+      ['stripe', 'stripeColor'],
+      ({ stripe, stripeColor }) => {
+        if (!stripe) return;
+        const width = parseStyle(String(stripe)).output;
+        const color = stripeColor
+          ? parseColor(String(stripeColor)).color
+          : 'currentcolor';
+        return { 'border-left': `${width} solid ${color}` };
+      },
+    ),
   },
 });
 ```
@@ -745,6 +775,7 @@ A handler returns a `CSSMap`, an array of them, or nothing:
 
 - Keys are **kebab-case** CSS property names (`'background-color'`, not `backgroundColor`) or `--custom-property` names. A camelCase key warns in development and is emitted verbatim, which the browser ignores.
 - Values are stringified, so numbers are fine (`{ '-webkit-line-clamp': 3 }`).
+- An array value emits one declaration per entry, in order, so the browser keeps the last one it supports: `{ width: ['-webkit-fill-available', '-moz-available', 'stretch'] }` emits three `width` declarations.
 - The reserved `$` key is a **selector suffix**: `{ $: '& > *:not(:last-child)', 'margin-right': gap }` applies the declarations to a nested selector. It accepts an array to fan out over several.
 - Return an array of maps to emit several declaration sets, each with its own `$`.
 
@@ -756,12 +787,17 @@ Built-in handlers are shared across several style names. Registering a handler f
 
 The shared groups worth knowing:
 
-| Registering a handler for      | Also takes over                                                                                           |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `fill`                         | `backgroundColor`, `image`, `backgroundImage`, `backgroundPosition`, `backgroundSize`, `backgroundRepeat` |
-| `display`                      | `hide`, `overflow`, `whiteSpace`, `textOverflow`, `flow`, `gap`                                           |
-| `preset`                       | `font`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textTransform`             |
-| `padding` / `margin` / `inset` | their `*Top`/`*Right`/`*Bottom`/`*Left`/`*Block`/`*Inline` longhands                                      |
+| Registering a handler for | Also takes over                                                                                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fill`                    | `backgroundColor`, `image`, `backgroundImage`, `backgroundPosition`, `backgroundSize`, `backgroundRepeat`, `backgroundAttachment`, `backgroundOrigin`, `backgroundClip`, `background` |
+| `display`                 | `hide`, `whiteSpace`, `textOverflow`, `flow`, `gap`                                                                                                                                   |
+| `flow`                    | `gap`                                                                                                                                                                                 |
+| `preset`                  | `font`, `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textTransform`                                                                           |
+| `padding` / `margin`      | their `Top`/`Right`/`Bottom`/`Left` longhands (`paddingTop`, `marginLeft`, …)                                                                                                         |
+| `inset`                   | `top`, `right`, `bottom`, `left`                                                                                                                                                      |
+| `width` / `height`        | `minWidth`/`maxWidth`, `minHeight`/`maxHeight`                                                                                                                                        |
+
+A multi-dep handler takes over every group its dependencies touch: `defineHandler(['display', 'flow', 'gap'], …)` takes over `display`, `flow`, and `gap` together, so it must emit `display` and `flex-flow` itself.
 
 Either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a name that isn't shared.
 
@@ -822,18 +858,98 @@ Each name costs one property check per render of every component, and the effect
 
 ---
 
-## Extending Style Types (TypeScript)
+## TypeScript
 
-Use module augmentation to extend the `StylesInterface`:
+Component props are typed from the `tasty()` definition with no setup. Module augmentation adds the names your design system defines and the extensions your plugins add.
+
+### Component props
+
+| In `tasty({ … })`                                                     | Adds the props                                                                                                                                                        |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `styleProps: ['gap', 'padding'] as const`                             | `gap`, `padding`, each typed like the style: a value or a state map                                                                                                   |
+| `modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const }` | `isLoading?: boolean`, `size?: 'sm' \| 'md' \| 'lg'` (`String` gives `string`, `Number` gives `number`)                                                               |
+| `modProps: ['isLoading'] as const`                                    | `isLoading?: ModValue`                                                                                                                                                |
+| `tokenProps: ['progress', 'accentColor'] as const`                    | `progress?: TokenValue`, `accentColor?: TokenValue`                                                                                                                   |
+| `variants: { default: {…}, danger: {…} }`                             | `variant?: 'default' \| 'danger'`                                                                                                                                     |
+| `elements: { Title: 'h3' }`                                           | `Card.Title`, with the `h3` props plus `qa`, `qaVal`, `mods`, `tokens`, `isDisabled`, `isHidden`, `isChecked`, and a `ref` typed as `HTMLHeadingElement`; no `styles` |
+| `as: SomeComponent`                                                   | `SomeComponent`'s own props, required ones still required                                                                                                             |
+
+Write the array forms with `as const`. Without it, `modProps: ['isLoading']` widens to `string[]` and every prop on the component is typed `ModValue`, so an `onClick` handler no longer type-checks. A `modProps` value list without `as const` widens to `string`.
+
+`tasty(Base, { … })` keeps `Base`'s prop types and sub-elements, and adds the props and sub-elements its own options above declare. Its `variant` accepts both its own variant names and `Base`'s. See [Extend an existing component](react-api.md#extend-an-existing-component).
+
+### Registering your names and extensions
+
+```ts
+// tasty.d.ts — keep the import: it makes this file a module, so the block
+// below extends '@tenphi/tasty' instead of replacing it.
+import '@tenphi/tasty';
 
-```tsx
-// tasty.d.ts
 declare module '@tenphi/tasty' {
+  interface TastyNamedColors {
+    surface: true;
+    text: true;
+    primary: true;
+  }
+  interface TastyPresetNames {
+    h1: true;
+    t2: true;
+  }
+  interface TastyThemeNames {
+    danger: true;
+    success: true;
+  }
   interface StylesInterface {
-    elevation?: string;
-    gradient?: string;
+    stripe?: string;
+  }
+  interface TastyCustomProps {
+    glaze: 'soft' | 'strong' | { tone: string; intensity?: number };
+  }
+  interface TastyBaseStylePropNames {
+    radius: true;
+    stripe: true;
   }
 }
 ```
 
+| Interface                 | Register                                                             | What it types                                                            |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `TastyNamedColors`        | Color token names from `tokens` and `replaceTokens`, without the `#` | Suggestions for `#name` and `#name.50` in `fill`, `color`, and `svgFill` |
+| `TastyPresetNames`        | `presets` names                                                      | The `preset` style and prop                                              |
+| `TastyThemeNames`         | Theme names                                                          | The `theme` prop (rendered as `data-theme`)                              |
+| `StylesInterface`         | Style properties added with `handlers`                               | Their value type in `styles`, `styleProps`, and base style props         |
+| `TastyCustomProps`        | Props added with `propHandlers`                                      | An optional prop on every `tasty()` component (not on sub-elements)      |
+| `TastyBaseStylePropNames` | Names passed to `baseStyleProps`                                     | A prop on every component, typed like the style it names                 |
+
+- The first three add autocomplete, not checking: any other string still type-checks (`preset: 'h9'` compiles). The ESLint plugin is what reports unknown names.
+- In `StylesInterface`, declare the plain value type (`stripe?: string`). Tasty adds state-map support itself, as it does for built-in styles.
+- A custom style name in `styles` type-checks without augmentation, but `styleProps` and `TastyBaseStylePropNames` accept only names in `StylesInterface`. A base style prop name missing from it adds no prop.
+- `TastyCustomProps` types the component prop, not the handler. A prop handler receives `Record<string, unknown>`, so cast inside it (`rest.styles as Styles`).
+- State keys, `$` value tokens, units, and recipe names have no TypeScript types. The ESLint plugin checks them against `tasty.config.ts`.
+
+### `tasty.config.ts`
+
+TypeScript augmentation does not reach the linter or the editor. [`@tenphi/eslint-plugin-tasty`](https://github.com/tenphi/eslint-plugin-tasty) and the Tasty VS Code extension read a `tasty.config.ts` (or `.js`, `.json`) at the project root instead. It only lists names: it is not passed to `configure()`, and it is unrelated to the Babel plugin's `configFile` (such as `tasty-zero.config.ts`).
+
+```ts
+// tasty.config.ts
+import type { TastyExtensionConfig } from '@tenphi/tasty';
+import type { TastyValidationConfig } from '@tenphi/eslint-plugin-tasty';
+
+export default {
+  tokens: ['#surface', '#text', '#primary', '$sidebar-width'],
+  units: ['cols'],
+  states: ['@mobile', '@dark'],
+  presets: ['h1', 't2'],
+  recipes: ['card', 'elevated'],
+  styles: ['stripe'],
+  importSources: ['@my-org/ui'],
+  presetDescriptions: { h1: 'Heading 1 (32px, bold)' },
+} satisfies TastyExtensionConfig & TastyValidationConfig;
+```
+
+`TastyExtensionConfig` from `@tenphi/tasty` types the fields the VS Code extension reads: `extends`, `tokens`, `units`, `functions`, `states`, `presets`, `styles`, `presetDescriptions`, and `stateDescriptions`. It has no `recipes`, `importSources`, `ownedSources`, or `styleFunctions`, so annotating the file with it alone rejects those ESLint fields; intersect it with the plugin's `TastyValidationConfig`, as above. An omitted list is not checked; `tokens: false`, `units: false`, or `functions: false` turns a check off even when an `extends` parent sets it.
+
+Keep it in step with `configure()`: token names with their `#` or `$`, custom units, parse-function names, state aliases, presets, recipes, and custom style names.
+
 See [Style DSL](dsl.md) for state maps, tokens, units, and extending semantics, and [React API](react-api.md) for `tasty()`, style functions, and component props.