@cube-dev/ui-kit 0.151.0 → 0.153.0

package/docs/glaze/api.md

@@ -10,6 +10,7 @@ Full reference for every public method, option, and type exported by `@tenphi/gl
   - [DTCG Resolver-Module](#themedtcgresolveroptions)
   - [Tailwind CSS](#themetailwindoptions)
 - [High-contrast pairs](#high-contrast-pairs)
+- [Manual contrast level](#manual-contrast-level)
 - [Color definitions](#color-definitions)
   - [Dark seed](#dark-seed-darkhue--darksaturation)
 - [Standalone color tokens](#standalone-color-tokens)
@@ -408,6 +409,144 @@ promotion for that color.
 
 ---
 
+## Manual contrast level
+
+`contrastLevel` turns contrast from a two-tier switch into a `0–100` slider.
+It is a config field, so it works globally, per theme, per token, and through
+`extend()`:
+
+```ts
+glaze.configure({ contrastLevel: 60 });
+const theme = glaze(280, 80, { contrastLevel: 60 });
+glaze.color('#26fcb2', { contrastLevel: 60 });
+```
+
+| Value            | Meaning                                                              |
+| ---------------- | -------------------------------------------------------------------- |
+| `'auto'`         | Default. The two-tier model: normal variants plus a high-contrast tier. |
+| `0`              | Normal contrast, with **no** high-contrast tier.                      |
+| `100`            | The high-contrast scheme as the only scheme.                          |
+| anything between | Resolved *at* that level.                                            |
+
+Levels `0` and `100` reproduce the classic `light` / `dark` and
+`lightContrast` / `darkContrast` output **bit for bit**.
+
+### What the level interpolates
+
+Exactly the three things that make a high-contrast variant differ from its
+normal counterpart:
+
+| Mechanism                                                                    | At level `L`                                                             |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Authored `HCPair`s — `tone`, `contrast`, shadow `intensity`, mix `value`      | the two ends are interpolated                                            |
+| The tone-window bypass                                                       | each endpoint moves toward the full range: light `10→0`, dark `15→0 / 95→100` |
+| Contrast escalation — `AA → AAA`, APCA `+15 Lc`                              | the two numeric targets are interpolated (`AA` at level 50 solves for 5.75) |
+
+The interpolated values are then fed through the ordinary resolve, so a
+contrast floor at any level is **solved**, not approximated, and `autoFlip`
+decides once per level.
+
+Everything that does not vary by high contrast today — hue, saturation,
+`darkDesaturation`, `opacity`, `pastel` — is unaffected by the level.
+
+### Un-interpolable tone pairs switch at 50
+
+Two ends of different kinds have no midpoint, because blending them would
+change *which* resolution rule applies partway up the ramp. These switch from
+the normal entry to the high-contrast one at level 50:
+
+```ts
+tone: [50, 'max']; // absolute vs. extreme
+tone: [50, '+20']; // absolute vs. relative
+tone: ['max', 'min']; // opposite extremes
+```
+
+Same-kind pairs (`[30, 20]`, `['-6', '-12']`, `{ wcag: [4.5, 7] }`,
+`[{ apca: 60 }, { apca: 90 }]`) interpolate smoothly.
+
+A `contrast` pair may **not** switch metric — `[4.5, { apca: 75 }]` throws. A
+WCAG ratio and an APCA Lc are different scales, so no target exists between
+them, and even in `'auto'` mode the two variants would be incomparable. Pair
+values inside one metric instead: `{ wcag: [4.5, 7] }` or `{ apca: [60, 90] }`.
+
+### A color never swaps sides mid-slider
+
+[`autoFlip`](#autoflip) decides per solve, and its tie-break — when both
+directions meet the floor, take the one nearer the authored tone — depends on
+the target. Along a ramp of targets that criterion shifts, so a naive
+implementation lets a color leap across its own base as the slider moves.
+
+Under a manual level the side is instead decided once, from the nearer
+endpoint's target, and preferred at every level in that half of the ramp.
+Consequences:
+
+- A color whose two ends land on the same side of its base **never** changes
+  side, at any level.
+- A color whose ends genuinely disagree — no single side can satisfy both its
+  normal and its high-contrast floor — changes side exactly once, at level 50,
+  the same place un-interpolable tone pairs switch.
+- Flipping is not disabled, only re-ordered, so a side that physically cannot
+  reach the requested contrast still falls back to the opposite one. The floor
+  is met at every level.
+
+The underlying solver option is `preferInitial` on
+[`findToneForContrast`](#contrast-solver), should you need the same behavior
+directly.
+
+### High-contrast output
+
+A manual level already carries the contrast preference, so there is no second
+tier to emit:
+
+- `resolve()` still returns four variants, but `lightContrast` / `darkContrast`
+  **mirror** `light` / `dark`.
+- A **global** level turns high-contrast output off outright, so
+  `tokens()` / `tasty()` / `json()` / `dtcg()` / `dtcgResolver()` / `tailwind()`
+  emit no high-contrast tier. `modes.highContrast` goes inert — it reads as
+  "emit a separate high-contrast set *when* contrast is automatic" — so leaving
+  `highContrast: true` set in a build config while a user switches their
+  preference from auto to manual is fine, and silent.
+- `css()` always returns four strings and ignores `modes`, so its
+  `lightContrast` / `darkContrast` strings repeat the normal declarations —
+  an existing `@media (prefers-contrast: more)` block keeps matching the base
+  block as the level changes, with nothing to rewire.
+- A level on a **single theme or token** does not change which modes are
+  emitted. Sibling themes in a palette keep their real high-contrast tier, and
+  the manual one reports its own resolved values there.
+
+### Driving it at runtime
+
+`configure()` bumps the config version, which invalidates every theme and token
+cache, so a slider only needs to re-export:
+
+```ts
+slider.oninput = () => {
+  glaze.configure({ contrastLevel: slider.valueAsNumber });
+  apply(theme.css());
+};
+```
+
+Because a manual level skips the two high-contrast passes, a manual resolve is
+also half the work of an `'auto'` one.
+
+### Clearing it, exporting it, base links
+
+- **`configure()` never clears a field by omission.** Pass `'auto'` explicitly
+  to leave manual mode — globally, or on one theme of a palette.
+- **`.export()` freezes only an *authored* level.** A level set on the instance
+  (or passed to `.export()`) is authored intent and is written to the snapshot;
+  a level merely inherited from the global config is a live user preference and
+  is left out, so a restored theme still follows the current slider. This
+  matches how `modes` and `states` are treated.
+- **Set the level globally, or on both sides of a base link.** A per-token level
+  on a dependent but not on its base anchors the two at different levels — the
+  same caveat as a per-instance `lightTone` override.
+
+`resolveContrastForLevel(spec, level, polarity?)` is exported for advanced use;
+see [Contrast solver](#contrast-solver).
+
+---
+
 ## Color definitions
 
 `ColorDef` is a discriminated union:
@@ -490,7 +629,7 @@ type ContrastSpec =
   | number // bare WCAG ratio
   | ContrastPreset // named WCAG preset
   | { wcag: HCPair<number | ContrastPreset> }
-  | { apca: HCPair<number> }; // APCA Lc target
+  | { apca: HCPair<number | ApcaPreset> }; // APCA Lc target
 ```
 
 | Preset        | WCAG ratio |
@@ -1553,6 +1692,7 @@ glaze.configure({
     alphaMax: 0.6,
     bgHueBlend: 0.2,
   },
+  contrastLevel: 'auto', // or 0–100 for a manual contrast slider
 });
 ```
 
@@ -1565,16 +1705,17 @@ boundaries, not the tone transfer.
 
 | Field                 | Default                                | Description                                                                                                                                                                                                                                                                                                                                                                                                               |
 | --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lightTone`           | `[10, 100]`                            | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC.                                                                                                                                                                                                                                                                                                                  |
-| `darkTone`            | `[15, 95]`                             | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC.                                                                                                                                                                                                                                                                                                                   |
+| `lightTone`           | `[10, 100]`                            | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC; widened continuously by [`contrastLevel`](#manual-contrast-level).                                                                                                                                                                                                                                                |
+| `darkTone`            | `[15, 95]`                             | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC; widened continuously by [`contrastLevel`](#manual-contrast-level).                                                                                                                                                                                                                                                 |
 | `darkDesaturation`    | `0.1`                                  | Saturation reduction in dark scheme (0–1).                                                                                                                                                                                                                                                                                                                                                                                |
 | `states.dark`         | `'@media(prefers-color-scheme: dark)'` | State alias for dark mode tokens ([Tasty](https://tasty.style) export). Defaults to a media query so tokens react to the OS preference without registering custom states.                                                                                                                                                                                                                                                                        |
 | `states.highContrast` | `'@media(prefers-contrast: more)'`     | State alias for HC tokens ([Tasty](https://tasty.style) export).                                                                                                                                                                                                                                                                                                                                                                                 |
 | `modes.dark`          | `true`                                 | Include dark variants in exports.                                                                                                                                                                                                                                                                                                                                                                                         |
-| `modes.highContrast`  | `false`                                | Include HC variants.                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `modes.highContrast`  | `false`                                | Include HC variants. Inert while a global [`contrastLevel`](#manual-contrast-level) is set — a manual level has no separate HC tier, so this reads as "emit HC variants when contrast is automatic".                                                                                                                                                                                                                                                                                   |
 | `shadowTuning`        | `undefined`                            | Default tuning for all shadow colors. Per-color tuning merges field-by-field.                                                                                                                                                                                                                                                                                                                                             |
 | `autoFlip`            | `true`                                 | Default for each color's `autoFlip`. When solving `contrast` (or applying a relative `tone` that overshoots `[0, 100]`), allow crossing to the opposite side instead of clamping. With `false`, only the requested direction is considered; unmet contrasts pin the tone to that direction's extreme (and emit a warning) and overshooting offsets clamp to the boundary. Override per color via [`autoFlip`](#autoflip). |
 | `inferRole`           | `true`                                 | Infer each color's [`role`](#roles) from its name when no explicit `role` is set. Set to `false` to opt out of name-based inference (the base-opposite and foreground-default fallbacks still apply).                                                                                                                                                                                                                     |
+| `contrastLevel`       | `'auto'`                               | Manual contrast level, `0`–`100`, replacing the two-tier high-contrast model with a slider. `0` reproduces the normal output and `100` the high-contrast output, bit for bit. See [Manual contrast level](#manual-contrast-level).                                                                                                                                                                                          |
 
 | Method                    | Description                                                                         |
 | ------------------------- | ----------------------------------------------------------------------------------- |
@@ -1582,7 +1723,7 @@ boundaries, not the tone transfer.
 | `glaze.getConfig()`       | Snapshot the current resolved config (shallow copy).                                |
 | `glaze.resetConfig()`     | Reset to defaults (also bumps the version counter).                                 |
 
-Themes and standalone color tokens keep a sparse local `GlazeConfigOverride` and merge the live global at resolve time for omitted fields. Authoring `.export(override?)` freezes the effective merge at call time; restored instances pin that freeze. `pastel` is instance-only (theme/token override or per-color) — not set via `configure()`.
+Themes and standalone color tokens keep a sparse local `GlazeConfigOverride` and merge the live global at resolve time for omitted fields. Authoring `.export(override?)` freezes the effective merge at call time; restored instances pin that freeze. `pastel` is instance-only (theme/token override or per-color) — not set via `configure()`. `contrastLevel` is the one field the freeze treats as a live preference: only an instance-authored level is written to the snapshot ([why](#two-rules-worth-knowing)).
 
 ---
 
@@ -1604,9 +1745,12 @@ palette.tokens({ modes: { dark: true, highContrast: true } });
 
 Resolution priority (highest first):
 
-1. Per-call `modes` option on `tokens` / `tasty` / `json`.
-2. `glaze.configure({ modes })` — global config.
-3. Built-in default: `{ dark: true, highContrast: false }`.
+1. A global [`contrastLevel`](#manual-contrast-level) — pins
+   `highContrast: false`, since a manual level leaves no separate high-contrast
+   tier to emit. `highContrast` is inert while it is set.
+2. Per-call `modes` option on `tokens` / `tasty` / `json`.
+3. `glaze.configure({ modes })` — global config.
+4. Built-in default: `{ dark: true, highContrast: false }`.
 
 ---
 
@@ -1621,6 +1765,7 @@ available result.
 | Condition                                           | Behavior                                                                                                 |
 | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
 | `contrast` without `base` in a **theme** color      | Validation error                                                                                         |
+| `contrast` pair switching metric (`[4.5, { apca: 75 }]`) | Validation error — a WCAG ratio and an APCA Lc are different scales                                  |
 | Relative `tone` without `base` in a **theme** color | Validation error                                                                                         |
 | `contrast` without `base` in `glaze.color()`        | Anchors against the literal seed (no error)                                                              |
 | Relative `tone` without `base` in `glaze.color()`   | Anchors against the literal seed (no error)                                                              |
@@ -1732,6 +1877,7 @@ import {
   findToneForContrast,
   findValueForMixContrast,
   resolveContrastForMode,
+  resolveContrastForLevel,
   resolveMinContrast,
   apcaContrast,
 } from '@tenphi/glaze';
@@ -1742,6 +1888,7 @@ import {
 | `findToneForContrast(opts)`                                       | Binary-search for the tone (0–1) that meets a contrast floor (WCAG or APCA) against a base color. Returns `{ tone, contrast, met, branch, flipped? }`.                                                                                                                                                                                                                                 |
 | `findValueForMixContrast(opts)`                                   | Same, but searches for a mix `value` (0–1) that meets a contrast floor between a base and a target.                                                                                                                                                                                                                                                                                    |
 | `resolveContrastForMode(spec, isHC, polarity?, outerExplicitHC?)` | Resolves a `ContrastSpec` to `{ metric: 'wcag' \| 'apca', target }` for the requested mode (picks the normal or HC entry of any pair). In HC, applies the metric's auto-enhancement unless `outerExplicitHC` is set or the inner metric pair carries an explicit HC value: APCA +15 Lc (clamped to 106); WCAG AA → AAA / AA-large → AAA-large (AAA-family and bare numbers unchanged). |
+| `resolveContrastForLevel(spec, level, polarity?)`                  | Resolves a `ContrastSpec` — including its outer `[normal, highContrast]` pair — at a [manual contrast level](#manual-contrast-level) (0–100), interpolating the two numeric targets. Levels 0 / 100 delegate verbatim to `resolveContrastForMode`; a WCAG-vs-APCA metric switch across the pair has no midpoint and switches at 50.                                                        |
 | `resolveMinContrast(value)`                                       | Resolves a `MinContrast` (WCAG preset or number) to a numeric ratio.                                                                                                                                                                                                                                                                                                                   |
 | `apcaContrast(yText, yBg)`                                        | APCA Lc magnitude (0–106) for two relative luminances.                                                                                                                                                                                                                                                                                                                                 |
 
@@ -1761,5 +1908,6 @@ Exported constants: `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (`15`, the Enhanced Le
 | `maxIterations`    | `18`                 | Max binary-search iterations per branch.                                                                                                                                                               |
 | `initialDirection` | higher-contrast side | Direction to search first (`'lighter'` or `'darker'`).                                                                                                                                                 |
 | `flip`             | `false`              | When `true`, try the opposite direction if the initial one doesn't meet the target. When `false`, only the initial direction is searched — unmet contrasts pin the result to that direction's extreme. |
+| `preferInitial`    | `false`              | With `flip` on and **both** directions meeting the target, keep `initialDirection` instead of taking whichever result lands nearer `preferredTone`. Makes the chosen side independent of the target — what [`contrastLevel`](#manual-contrast-level) uses to keep a color on one side of its base across the ramp. The flip fallback is unaffected. |
 
 Result: `{ tone, contrast, met, branch: 'lighter' | 'darker' | 'preferred', flipped? }`. `flipped: true` indicates the initial direction failed and the opposite direction satisfied the target.

package/docs/glaze/methodology.md

@@ -642,6 +642,25 @@ In HC variants, Glaze bypasses the normal tone window and uses the full
 `[0, 100]` range. Edge tones can reach the edge; contrast floors have more room
 to solve.
 
+### A slider instead of a tier
+
+The two-tier model assumes contrast is a binary OS preference. When contrast is
+instead a setting *your users* control, set
+[`contrastLevel`](api.md#manual-contrast-level) to a number and the HC tier
+becomes a `0–100` ramp: level `0` is your normal palette, `100` is the HC
+palette you already authored, and everything between is resolved at that level.
+
+The authoring work is the same — the HC pairs above are what the slider ramps
+toward, so a palette tuned for high contrast needs no new fields. Two
+consequences worth planning for:
+
+- The separate HC tier stops being emitted, so wire the level itself into your
+  build or runtime rather than a `prefers-contrast: more` block. Existing
+  media-query wiring keeps working; it just receives the same values as the base
+  block.
+- `contrastLevel: 0` is a useful state in its own right: normal contrast with no
+  HC tier at all, for products that ship the slider but default it off.
+
 ## Checklist
 
 Before shipping a palette, verify:
@@ -654,7 +673,8 @@ Before shipping a palette, verify:
 - Low-stakes visual relationships use tone deltas instead of fake contrast
   floors.
 - `inherit: false` is set on default-only tokens so status themes stay focused.
-- HC pairs exist where high contrast should visibly tighten.
+- HC pairs exist where high contrast should visibly tighten (they double as the
+  ramp for a manual `contrastLevel`).
 - `glaze.configure({ states, modes })` matches the states registered in the app.
 - Every emitted scheme (`light`, `dark`, `lightContrast`, `darkContrast`) has
   been reviewed on complete screens, not only in a token grid.

package/docs/glaze/okhst.md

@@ -85,6 +85,19 @@ lightTone: { lo: 10, hi: 100, eps: 0.05 }
 Pass `false` to use the full range. High-contrast variants always bypass the
 ordinary boundaries and use the full range.
 
+A [manual contrast level](api.md#manual-contrast-level) generalizes that bypass
+continuously: with `contrastLevel: L` (`f = L / 100`), each boundary moves toward
+the full range instead of jumping to it —
+
+```text
+lo(f) = lo + (0   - lo) * f
+hi(f) = hi + (100 - hi) * f
+```
+
+— so the light default walks `[10, 100] → [0, 100]` and the dark default
+`[15, 95] → [0, 100]`. The render `eps` is not interpolated, and a `false` window
+is already the full range and therefore level-invariant.
+
 ## Scheme adaptation
 
 Each regular color has an adaptation `mode`:

package/docs/tasty/README.md

@@ -24,6 +24,7 @@ Tasty is a styling engine for design systems that turns component state into det
 ## By Task
 
 - **Learn the style language**: [Style DSL](dsl.md)
+- **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, or properties globally**: [Configuration](configuration.md)
 - **Debug generated CSS or cache behavior**: [Debug Utilities](debug.md)

package/docs/tasty/ai-agents.md

@@ -0,0 +1,206 @@
+# Tasty Style Rules for AI Agents
+
+A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — every rule here is machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it means clean lint output. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
+
+Notation: ❌ wrong → ✅ correct.
+
+---
+
+## 0. Read the project config first
+
+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.
+
+## 1. Where styles go
+
+```jsx
+const Card = tasty({ as: 'div', styles: { … }, styleProps: ['padding'] }); // new component
+const Hero = tasty(Card, { styles: { … } });                              // extend a component
+const cls = useStyles({ … });                                             // ad-hoc class name
+tastyStatic('.card', { … });                                              // build-time, zero runtime
+```
+
+- Wrap, don't pass styles per instance: ❌ `<Box styles={{ padding: '2x' }} />` → ✅ `const Box = tasty({ styles: { padding: '2x' } })`.
+- Style values are **static**. Route anything conditional through a state map plus `mods` (or `tokens` / `styleProps`):
+  ❌ `fill: isOpen ? '#primary' : '#surface'` → ✅ `fill: { '': '#surface', open: '#primary' }` with `mods={{ open: isOpen }}`.
+
+## 2. Property names
+
+Keys are camelCase — a Tasty property or a real CSS property. No kebab-case, no invented names.
+
+Prefer the Tasty shorthand over its CSS equivalents:
+
+| Use | Instead of |
+|-----|------------|
+| `fill` | `backgroundColor`, `background` |
+| `image` | `backgroundImage` |
+| `border` | `borderColor`, `borderWidth`, `borderStyle`, `borderTop`/`Right`/`Bottom`/`Left` |
+| `radius` | `borderRadius` |
+| `outline` | `outlineColor`, `outlineWidth`, `outlineStyle`, `outlineOffset` |
+| `shadow` | `boxShadow` |
+| `padding` | `paddingTop`/`Right`/`Bottom`/`Left` |
+| `margin` | `marginTop`/`Right`/`Bottom`/`Left` |
+| `inset` | `top`, `right`, `bottom`, `left` |
+| `width` / `height` | `minWidth`/`maxWidth`, `minHeight`/`maxHeight` |
+| `flow` | `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow` |
+| `preset` | `fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform` |
+| `font` | `fontFamily` |
+| `scrollbar` | `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter` |
+| `gridColumns` / `gridRows` / `gridAreas` | `gridTemplateColumns` / `Rows` / `Areas` |
+| `textOverflow: 'ellipsis / 3'` | `lineClamp` |
+| `hide: true` | `display: 'none'` |
+| `flexGrow` / `flexShrink` / `flexBasis` | `flex` |
+
+The last row goes the other way — longhands over the shorthand — because `flex` is lossy: it resets the components you omit to non-initial values (`flex: '0'` silently sets `flex-basis: 0%`) and cannot express `flexShrink: 0` at all. The longhands also carry separate state maps.
+
+## 3. Values
+
+### 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 property *name* — only inside `transition` |
+
+- ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
+- ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
+- A `$name` must be declared as a `'$name': value` key in the same styles object, or in the config.
+
+### 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.
+
+Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'` → `'1r'`; `border: '1px …'` → `'1bw …'`.
+
+### Math
+
+❌ `calc(100% - 2x)` → ✅ `(100% - 2x)`. Parentheses are wrapped in `calc()` automatically — and must be balanced.
+
+### `true`
+
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+
+### `!important`
+
+Never use it. Tasty owns specificity through doubled selectors and state ordering; `!important` breaks that. Express the exception as a state instead.
+
+### Modifiers
+
+A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). 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` |
+| `outline` | the style keywords above |
+| `radius` | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf` |
+| `width`, `height` | `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 |
+
+Directional modifiers beat placeholder zeros:
+
+- ❌ `padding: '0 0 2x 0'` → ✅ `padding: '2x bottom'`
+- ❌ `padding: '1x 1x 2x 1x'` → ✅ `padding: '1x, 2x bottom'`
+- ❌ `border: '0 0 1bw 0'` — four tokens parse as *one* border value, so this renders no border at all → ✅ `border: '1bw bottom'`
+
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, `tabSize`, `paddingInline`, `paddingBlock`. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
+
+### `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`.
+
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+
+## 4. State maps
+
+A property value can be an object of `state: value`. Key order is priority — later keys win.
+
+| Key | Generated selector |
+|-----|--------------------|
+| `hovered` | `[data-hovered]` (boolean modifier from `mods`) |
+| `theme=danger` | `[data-theme="danger"]` (value modifier) |
+| `:hover` | pseudo-class |
+| `.active` | class selector |
+| `[aria-expanded="true"]` | attribute selector |
+| `hovered & .active` | AND |
+| `hovered \| focused` | OR (`,` also means OR) |
+| `!disabled` | NOT |
+| `hovered ^ focused` | XOR — exactly one (keep chains ≤ 4 operands) |
+
+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.
+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.
+
+```jsx
+color: { '': '#text', hovered: '#accent', disabled: '#text.40' }
+```
+
+Advanced states:
+
+| Prefix | Use | Example |
+|--------|-----|---------|
+| `@media(…)` | media query; dimensions `w` `h`; types `@media:print` `:screen` `:all` `:speech` | `@media(w < 768px)`, `@media(600px <= w < 1200px)` |
+| `@(…)` | container query; dimensions `w` `h` `is` `bs` | `@(layout, w >= 600px)`, `@($variant=primary)` |
+| `@supports(…)` | feature query; `$` first argument tests a selector | `@supports(display: grid)`, `@supports($, :has(*))` |
+| `@root(…)` | condition on `:root` | `@root(schema=dark)` |
+| `@parent(…)` | condition on an ancestor; `, >` for the direct parent | `@parent(hovered, >)` |
+| `@own(…)` | a sub-element's own state — **only inside sub-element styles** | `@own(:hover)` |
+| `@starting` | `@starting-style` entry animation | `@starting` |
+| `@name` | project state alias | `@mobile` |
+
+- At root level write the selector directly: ❌ `'@own(:hover)'` → ✅ `':hover'`.
+- `@name` aliases must exist in `states` in the config or be declared locally as an `'@name': '<state expression>'` key; alias keys start with `@` and their value must be a valid state expression.
+- `:is()` / `:has()` / `:not()` / `:where()` work in state keys but support at most 2 levels of nested parentheses, and `:has()` is expensive — prefer `@parent()`, `@own()` and modifiers.
+
+When extending a parent's state map: `'@inherit'` reuses the parent's value for that state, `null` removes a state (or resets a property, letting recipes fill in), `false` is a tombstone that blocks it entirely.
+
+## 5. Sub-elements
+
+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' } }
+```
+
+❌ 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).
+
+## 6. Special top-level keys
+
+| Key | Shape |
+|-----|-------|
+| `@keyframes` | `{ name: { '0%': styles, … } }` |
+| `@properties` | `{ '$name': { syntax, inherits, initialValue } }` |
+| `@fontFace` | `{ 'Family Name': descriptors \| descriptors[] }` |
+| `@counterStyle` | `{ name: descriptors }` |
+| `recipe` | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
+
+## 7. `tastyStatic()`
+
+The selector must be a string literal and valid CSS. Values must be static — strings, numbers, booleans, `null`, or objects/arrays of those. No variables, template literals, function calls, or spreads.
+
+## 8. Checklist
+
+- Token, preset, recipe, unit and `@alias` names exist in the project config.
+- Tasty shorthand chosen over CSS longhands; `flexGrow`/`flexShrink`/`flexBasis` over `flex`; `hide: true` over `display: 'none'`.
+- Colors are `#tokens`, not hex/rgb/oklch/named; `$prop` not `var(--prop)`.
+- Spacing uses `x`/`r`/`bw`/`ow` units; math uses `(…)`, not `calc(…)`.
+- `true` only on the properties that accept it; no `!important`.
+- Modifiers valid for the property; directional shorthand instead of placeholder zeros.
+- Every state map starts with `''` (or `_`), is flat, and lives inside a property value.
+- `@own()` only inside sub-elements; sub-element keys are capitalized and hold objects.
+- Values are static; dynamic behavior comes from `mods` / `tokens` / `styleProps`.

package/docs/tasty/injector.md

@@ -226,6 +226,21 @@ configure({
 - `devMode`: Automatically enabled in development environments (detected via `isDevEnv()`)
 - `forceTextInjection`: Automatically enabled in test environments (Jest, Vitest, Mocha, happy-dom, jsdom)
 
+**Injection Modes:**
+
+Each sheet picks its write mode once, when it is created, and keeps it for its
+lifetime:
+
+| Mode | How rules are written | How rules are removed |
+|---|---|---|
+| CSSOM (default) | `styleSheet.insertRule(rule, index)` | `styleSheet.deleteRule(index)` |
+| Text (`forceTextInjection`, or when `styleElement.sheet` is unavailable) | appended to `<style>.textContent` | rule texts are tracked per sheet and the element's text is rebuilt without them |
+| Adopted (ShadowRoot with constructable sheets) | `insertRule` on the constructable sheet | `deleteRule` on the constructable sheet |
+
+Text mode cannot edit a single rule in place the way CSSOM can, so the sheet
+keeps the inserted rule texts in index order and rewrites the element on delete.
+Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
+
 **Configuration Notes:**
 - Most options have sensible defaults and auto-detection
 - `configure()` is optional - the injector works with defaults

package/docs/tasty/react-api.md

@@ -419,6 +419,15 @@ function ThemeStyles() {
 }
 ```
 
+A slot — the `id`, or the selector when no `id` is given — holds exactly one
+injection **per `root`**. So:
+
+- Changing the styles replaces the previous CSS rather than adding to it.
+- Passing styles that produce no CSS (for example `{}`) clears the slot.
+- The same selector used in two shadow roots keeps a separate injection in each.
+- Two independent call sites that share a selector share a slot, and the last
+  render wins. Give them distinct `id`s if they should coexist.
+
 ### useRawCSS
 
 Inject raw CSS strings. Accepts an optional `id` in the options for update tracking — when the CSS changes for the same id, the previous injection is replaced:
@@ -435,6 +444,9 @@ function GlobalReset() {
 }
 ```
 
+An `id` slot holds one injection per `root`. Without an `id` the CSS is deduped
+by content and permanent — there is nothing to replace it with later.
+
 ### useKeyframes
 
 Inject `@keyframes` rules and return the generated animation name:
@@ -455,7 +467,7 @@ function Spinner() {
 }
 ```
 
-`useKeyframes()` also supports a factory function. The deps array is accepted for backward compatibility but the factory is called on every invocation — deduplication is handled internally by content hash:
+`useKeyframes()` also supports a factory function. Without a `name` the factory runs on every invocation and deduplication is handled internally by content hash; with a `name`, matching deps skip the factory entirely:
 
 ```tsx
 function Pulse({ scale }: { scale: number }) {
@@ -464,13 +476,20 @@ function Pulse({ scale }: { scale: number }) {
       '0%': { transform: 'scale(1)' },
       '100%': { transform: `scale(${scale})` },
     }),
-    [scale]
+    [scale],
+    { name: 'pulse' }
   );
 
   return <div style={{ animation: `${pulse} 500ms ease-in-out alternate infinite` }} />;
 }
 ```
 
+Passing `name` claims a slot owned by that one call site, per `root` — much like
+`id` in `useGlobalStyles()` and `useRawCSS()`. When the steps change the previous
+`@keyframes` rule is disposed and the name is reused, so the rules don't
+accumulate and the returned name stays stable. Anonymous keyframes are permanent
+and shared by content.
+
 ### useProperty
 
 Register a CSS `@property` rule so a custom property can animate smoothly: