@tenphi/tasty 0.0.0-snapshot.bbd10c7 → 0.0.0-snapshot.bbfcd75

package/docs/dsl.md

@@ -1,8 +1,10 @@
 # Style DSL Reference
 
-This is the Tasty style language reference — the value syntax, state mappings, tokens, units, extending semantics, and special declarations that apply to both runtime `tasty()` and build-time `tastyStatic()`.
+This is the language behind Tasty’s predictable state resolution. Every property can use a state map; later branches declare higher priority, and Tasty compiles them so only one generated selector can match.
 
-For the runtime React API (`tasty()`, hooks, component props), see [Runtime API](runtime.md). For all enhanced style properties, see [Style Properties](styles.md). For global configuration, see [Configuration](configuration.md).
+The same value syntax, state maps, tokens, units, extension semantics, and special declarations apply to React `tasty()`—whether rendered on the client or server—and build-time `tastyStatic()`.
+
+For the React API (`tasty()`, style functions, component props), see [React API](react-api.md). For all enhanced style properties, see [Style Properties](styles.md). For global configuration, see [Configuration](configuration.md).
 
 ---
 
@@ -18,41 +20,86 @@ fill: { '': '#white', hovered: '#gray.05', 'theme=danger': '#red' }
 
 #### State Key Types
 
-| Syntax | Example | Generated CSS |
-|--------|---------|---------------|
-| Boolean modifier | `hovered` | `[data-hovered]` |
-| Value modifier | `theme=danger` | `[data-theme="danger"]` |
-| Pseudo-class | `:hover` | `:hover` |
-| Class selector | `.active` | `.active` |
-| Attribute selector | `[aria-expanded="true"]` | `[aria-expanded="true"]` |
-| Combined | `hovered & .active` | `[data-hovered].active` |
+| Syntax             | Example                  | Generated CSS                                                            |
+| ------------------ | ------------------------ | ------------------------------------------------------------------------ |
+| Boolean modifier   | `hovered`                | `[data-hovered]`                                                         |
+| Value modifier     | `theme=danger`           | `[data-theme="danger"]`                                                  |
+| Pseudo-class       | `:hover`                 | `:hover`                                                                 |
+| Class selector     | `.active`                | `.active`                                                                |
+| Attribute selector | `[aria-expanded="true"]` | `[aria-expanded="true"]`                                                 |
+| Combined (AND)     | `hovered & .active`      | `[data-hovered].active`                                                  |
+| Combined (OR)      | `hovered \| focused`     | `[data-hovered], [data-focused]`                                         |
+| Negated (NOT)      | `!disabled`              | `:not([data-disabled])`                                                  |
+| Exclusive (XOR)    | `hovered ^ focused`      | `[data-hovered]:not([data-focused]), :not([data-hovered])[data-focused]` |
+
+#### Automatic Native States
+
+`disabled` and `checked` are built-in automatic states. On a Tasty component, they track the corresponding native prop or attribute, so these pairs express the same component state:
+
+| Concise Tasty state | Explicit attribute selector |
+| ------------------- | --------------------------- |
+| `disabled`          | `[disabled]`                |
+| `checked`           | `[checked]`                 |
+
+Prefer the concise form when authoring Tasty component styles. Explicit attribute selectors remain valid and can be useful when targeting arbitrary attributes or when CSS-shaped syntax makes an introductory example easier to recognize.
+
+Operator precedence (highest to lowest): `!` (NOT) > `^` (XOR) > `|` (OR) > `&` (AND). Use parentheses to override: `hovered & (pressed ^ focused)`.
+
+`^` (XOR) means "exactly one of" — `A ^ B` expands to `(A & !B) | (!A & B)`. This is useful for mutually exclusive states where exactly one should be active:
+
+```jsx
+fill: {
+  '': '#surface',
+  'hovered ^ focused': '#accent',  // active when hovered OR focused, but not both
+}
+```
+
+#### Default State Ordering
+
+Key order sets priority — later keys win and turn off earlier ones via negation. The bare default (`''`) is the lowest-priority state, so it **must be the first key**. If it appears after other states, Tasty moves it to the front and emits a dev warning (`MISPLACED_DEFAULT_STATE`); otherwise it would override every state above it.
+
+```jsx
+// Correct — default first
+color: { '': '#text', hovered: '#accent' }
+
+// Auto-corrected with a warning — '' moved to the front
+color: { hovered: '#accent', '': '#text' }
+```
+
+The bare `''` default still **receives negation** (it is turned off when a higher-priority state matches). For a value that must always apply as a guaranteed floor — even where a query is _unknown_ — use the [`_` fallback floor](#_--fallback-floor) instead. The two can coexist: `''` is the negated default, `_` is the always-on floor. If a map contains only `_` and `''` (no other states), the `''` default is redundant — Tasty keeps the `_` value and drops `''` with a `REDUNDANT_DEFAULT_STATE` warning.
 
 ### Sub-element
 
 Element styled using a capitalized key. Identified by `data-element` attribute:
 
 ```jsx
-styles: { Title: { preset: 'h3' } }
+styles: {
+  Title: {
+    preset: 'h3';
+  }
+}
 // Targets: <div data-element="Title">
 ```
 
 #### Selector Affix (`$`)
 
-Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
-
-| Pattern | Result | Description |
-|---------|--------|-------------|
-| *(none)* | ` [el]` | Descendant (default) |
-| `>` | `> [el]` | Direct child |
-| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
-| `h1` | ` h1` | Tag selector (no key injection) |
-| `h1 >` | ` h1 > [el]` | Key is direct child of tag |
-| `h1 *` | ` h1 *` | Any descendant of tag |
-| `*` | ` *` | All descendants |
-| `::before` | `::before` | Root pseudo (no key) |
-| `@::before` | `[el]::before` | Pseudo on the sub-element |
-| `>@:hover` | `> [el]:hover` | Pseudo-class on the sub-element |
-| `>@.active` | `> [el].active` | Class on the sub-element |
+Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles.
+
+Examples below assume the sub-element key is **Cell** (i.e. `[data-element="Cell"]` in CSS):
+
+| Pattern     | Result                                            | Description                                                                                                                                      |
+| ----------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| _(none)_    | `[data-element="Cell"]`                           | Descendant (default)                                                                                                                             |
+| `>`         | `> [data-element="Cell"]`                         | Direct child                                                                                                                                     |
+| `>Body>`    | `> [data-element="Body"] > [data-element="Cell"]` | Chained elements                                                                                                                                 |
+| `> Cell`    | `> [data-element="Cell"]`                         | Self-name shorthand — when the trailing element name matches the sub-element's own key, it acts as the placeholder (same as `@`); no duplication |
+| `h1`        | `h1`                                              | Tag selector (no key injection)                                                                                                                  |
+| `h1 >`      | `h1 > [data-element="Cell"]`                      | Key is direct child of tag                                                                                                                       |
+| `h1 *`      | `h1 *`                                            | Any descendant of tag                                                                                                                            |
+| `*`         | `*`                                               | All descendants                                                                                                                                  |
+| `&::before` | `::before`                                        | Root pseudo (no key); `&` is required                                                                                                            |
+| `@::before` | `[data-element="Cell"]::before`                   | Pseudo on the sub-element                                                                                                                        |
+| `>@.active` | `> [data-element="Cell"].active`                  | Class on the sub-element                                                                                                                         |
 
 Rules for key injection (`[data-element="..."]`):
 
@@ -81,7 +128,7 @@ const List = tasty({
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:
 
 ```jsx
-fill: '#purple.5'  // → var(--purple-color) with 50% opacity
+fill: '#purple.5'; // → oklch(from var(--purple-color) l c h / .5)
 ```
 
 ### Modifier
@@ -93,7 +140,7 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
-Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](runtime.md#mod-props).
+Modifiers can also be exposed as top-level component props via `modProps` — see [React API — Mod Props](react-api.md#mod-props).
 
 ---
 
@@ -103,23 +150,155 @@ Modifiers can also be exposed as top-level component props via `modProps` — se
 color: '#purple',           // Full opacity
 color: '#purple.5',         // 50% opacity
 color: '#purple.05',        // 5% opacity
+color: '#purple.$fade',     // Opacity from a custom property
 fill: '#current',           // → currentcolor
-fill: '#current.5',         // → color-mix(in oklab, currentcolor 50%, transparent)
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
+The suffix sets the alpha on the token's color with CSS relative color syntax:
+
+```jsx
+fill: '#purple.5';
+// → oklch(from var(--purple-color) l c h / .5)
+```
+
+The channels are copied over and the alpha slot is written, which asks nothing of
+the color beyond _being_ a color. That means the suffix works on every one of
+these:
+
+- a token holding a `color-mix()`, a `light-dark()`, or a `color()` in a space
+  Tasty cannot convert — none of which have channels to decompose
+- `#current`, which resolves to the color the element inherits
+- a `--name-color` variable declared in your own CSS, with no Tasty token
+  definition behind it
+
+Two properties follow from writing the alpha slot rather than compositing:
+
+- **Alpha is replaced, not multiplied.** A token holding `rgb(255 0 0 / .8)`
+  faded to `.5` is alpha `.5`, not `.4`.
+- **The alpha may be a number or a percentage.** `#purple.$fade` emits
+  `/ var(--fade)` unchanged, so it works whether `$fade` holds `.5` or `50%` —
+  which is what `--*-opacity` properties are registered to accept.
+
+### `#current` is the keyword
+
+`#current` emits the `currentcolor` keyword, so it resolves against the element
+that reads it. That is what lets it follow a color an ancestor faded — a ramp
+that expresses its disabled state once, in `color`, fades everything painted from
+`#current` below it with no further declarations.
+
+The `color` style also publishes `--current-color` beside every color it sets,
+for anything that needs the inherited color _as a color_ rather than as the
+keyword — hand-authored CSS, or a place the keyword will not do. Read it as
+`$current-color`. It is registered with `initial-value: currentcolor`, so where
+nothing published it, it still resolves against each element's own color:
+
+```jsx
+fill: '$current-color'; // → var(--current-color)
+```
+
+A color that already reads the color it inherits — `#current`, a `#current` fade
+— is not published into it: resolving such a value a second time at a descendant
+would fade it twice.
+
+One case needs the wider floor to be considered. A token _defined_ as `#current`
+and then faded gives relative color syntax a `currentcolor` origin, which Safari
+supports only from 18:
+
+```jsx
+{ '#ink': '#current', fill: '#ink.5' }
+// --ink-color: currentcolor
+// fill: oklch(from currentcolor l c h / .5)  → Chrome, Firefox, Safari 18+
+```
+
+Put the fade in the token instead — `{ '#ink': '#current.5' }` — and it goes
+through `color-mix()`, which works from Safari 16.2 and composes like every other
+`#current` fade.
+
+### `#current` composes instead
+
+`#current` is the one exception, and the difference is deliberate. A token _names_
+a color, so fading it sets its alpha. `currentcolor` is the color an element
+**inherits**, which an ancestor may already have faded — `#current.4` means "40%
+of what reaches me":
+
+```jsx
+fill: '#current.4';
+// → color-mix(in oklab, currentcolor 40%, transparent)
+```
+
+So a `#current` fade nested inside another one composes: a label at `#current.4`
+with a fill of `#current.18` under it lands at `.072`. Color ramps built on
+`#current` depend on that — replacing would double the opacity of every nested
+step. Because a `color-mix()` percentage cannot be a `<number>`, an opacity
+custom property used as `#current.$fade` must hold a unitless number; a token
+accepts either form.
+
+The space is always `oklch`: it is unbounded, so a wide-gamut color survives a
+round trip that a gamut-limited space would clamp. Nothing configures this —
+see [Color space](configuration.md#color-space).
+
+---
+
+## CSS Color Functions
+
+Every CSS color function is recognized as a color, so it lands in the color slot
+of whichever style property you use it in — and tokens inside it are expanded:
+
+```jsx
+fill: 'color-mix(in oklab, #primary 50%, #surface)',
+color: 'light-dark(#dark, #light)',
+color: 'contrast-color(#primary)',
+fill: 'color(display-p3 1 .5 0)',
+border: '1bw solid oklch(from #primary l c h / 50%)',  // relative color syntax
+shadow: '0 0 1x color-mix(in oklab, #dark 20%, transparent)',
+```
+
+`light-dark()` is the one exception to "always a color": CSS lets it pick between
+values of any type, so it is treated as a color only when its arguments are
+colors. `padding: 'light-dark(1x, 2x)'` still reaches the padding slot.
+
+A color token defined as one of these functions takes the
+[opacity suffix](#color-tokens--opacity) like any other:
+
+```jsx
+const Card = tasty({
+  styles: {
+    '#brand': 'color-mix(in oklab, #primary 50%, #surface)',
+    fill: '#brand.5',
+  },
+});
+```
+
+A [replace token](configuration.md#replace-tokens-parse-time-substitution) is
+substituted while parsing, so its color is right there to fade in place. A
+channel function takes the alpha after a slash; a derived function has no alpha
+channel, so it gets wrapped:
+
+```jsx
+configure({
+  replaceTokens: {
+    '#solid': 'hsl(220 90% 50%)',
+    '#adaptive': 'light-dark(#dark, #light)',
+  },
+});
+
+fill: '#solid.5'; // → hsl(220 90% 50% / .5)
+fill: '#adaptive.5'; // → oklch(from light-dark(…) l c h / .5)
+```
+
 ---
 
 ## Built-in Units
 
-| Unit | Description | Example | CSS Output |
-|------|-------------|---------|------------|
-| `x` | Gap multiplier | `2x` | `calc(var(--gap) * 2)` |
-| `r` | Border radius | `1r` | `var(--radius)` |
-| `cr` | Card border radius | `1cr` | `var(--card-radius)` |
-| `bw` | Border width | `2bw` | `calc(var(--border-width) * 2)` |
-| `ow` | Outline width | `1ow` | `var(--outline-width)` |
-| `sf` | Stable fraction | `1sf` | `minmax(0, 1fr)` |
+| Unit | Description        | Example | CSS Output                      |
+| ---- | ------------------ | ------- | ------------------------------- |
+| `x`  | Gap multiplier     | `2x`    | `calc(var(--gap) * 2)`          |
+| `r`  | Border radius      | `1r`    | `var(--radius)`                 |
+| `cr` | Card border radius | `1cr`   | `var(--card-radius)`            |
+| `bw` | Border width       | `2bw`   | `calc(var(--border-width) * 2)` |
+| `ow` | Outline width      | `1ow`   | `var(--outline-width)`          |
+| `sf` | Stable fraction    | `1sf`   | `minmax(0, 1fr)`                |
 
 You can register additional custom units via [`configure()`](configuration.md#options).
 
@@ -164,7 +343,7 @@ const ElevatedCard = tasty({
 
 **Post-merge recipes (`/` separator):**
 
-Recipes listed after `/` are applied *after* component styles using `mergeStyles`:
+Recipes listed after `/` are applied _after_ component styles using `mergeStyles`:
 
 ```jsx
 const Input = tasty({
@@ -202,8 +381,8 @@ When a style property uses a state map, the merge behavior depends on whether th
 const MyButton = tasty(Button, {
   styles: {
     fill: {
-      'loading': '#yellow',      // append new state
-      'disabled': '#gray.20',    // override existing state in place
+      loading: '#yellow', // append new state
+      disabled: '#gray.20', // override existing state in place
     },
   },
 });
@@ -213,7 +392,7 @@ const MyButton = tasty(Button, {
   styles: {
     fill: {
       '': '#red',
-      'hovered': '#blue',
+      hovered: '#blue',
     },
   },
 });
@@ -238,8 +417,12 @@ fill: {
 Use `null` inside a state map to remove a state, or `false` to block it entirely (tombstone):
 
 ```jsx
-fill: { pressed: null }   // removes pressed from the result
-fill: { disabled: false } // tombstone — no CSS for disabled, blocks recipe too
+fill: {
+  pressed: null;
+} // removes pressed from the result
+fill: {
+  disabled: false;
+} // tombstone — no CSS for disabled, blocks recipe too
 ```
 
 ### Resetting Properties with `null` and `false`
@@ -247,44 +430,54 @@ fill: { disabled: false } // tombstone — no CSS for disabled, blocks recipe to
 ```jsx
 const SimpleButton = tasty(Button, {
   styles: {
-    fill: null,    // discard parent's fill, let recipe fill in
+    fill: null, // discard parent's fill, let recipe fill in
     border: false, // no border at all (tombstone — blocks recipe too)
   },
 });
 ```
 
-| Value | Meaning | Recipe fills in? |
-|-------|---------|-----------------|
-| `undefined` | Not provided — parent preserved | N/A |
-| `null` | Intentional unset — parent discarded | Yes |
-| `false` | Tombstone — blocks everything | No |
+| Value       | Meaning                              | Recipe fills in? |
+| ----------- | ------------------------------------ | ---------------- |
+| `undefined` | Not provided — parent preserved      | N/A              |
+| `null`      | Intentional unset — parent discarded | Yes              |
+| `false`     | Tombstone — blocks everything        | No               |
 
 ---
 
 ## Advanced States (`@` prefix)
 
-| Prefix | Purpose | Example |
-|--------|---------|---------|
-| `@media` | Media queries | `@media(w < 768px)` |
-| `@(...)` | Container queries | `@(panel, w >= 300px)` |
-| `@supports` | Feature/selector support | `@supports(display: grid)` |
-| `@root` | Root element states | `@root(schema=dark)` |
-| `@parent` | Parent/ancestor element states | `@parent(hovered)` |
-| `@own` | Sub-element's own state | `@own(hovered)` |
-| `@starting` | Entry animation | `@starting` |
-| `:is()` | CSS `:is()` structural pseudo-class | `:is(fieldset > label)` |
-| `:has()` | CSS `:has()` relational pseudo-class | `:has(> Icon)` |
-| `:not()` | CSS `:not()` negation (prefer `!:is()`) | `:not(:first-child)` |
-| `:where()` | CSS `:where()` (zero specificity) | `:where(Section)` |
+| Prefix      | Purpose                                   | Example                    |
+| ----------- | ----------------------------------------- | -------------------------- |
+| `@media`    | Media queries                             | `@media(w < 768px)`        |
+| `@(...)`    | Container queries                         | `@(panel, w >= 300px)`     |
+| `@supports` | Feature/selector support                  | `@supports(display: grid)` |
+| `@root`     | Root element states                       | `@root(schema=dark)`       |
+| `@parent`   | Parent/ancestor element states            | `@parent(hovered)`         |
+| `@own`      | Sub-element's own state                   | `@own(hovered)`            |
+| `@starting` | Entry animation                           | `@starting`                |
+| `_`         | Fallback floor (always-on, never negated) | `_`                        |
+| `:is()`     | CSS `:is()` structural pseudo-class       | `:is(fieldset > label)`    |
+| `:has()`    | CSS `:has()` relational pseudo-class      | `:has(> Icon)`             |
+| `:not()`    | CSS `:not()` negation (prefer `!:is()`)   | `:not(:first-child)`       |
+| `:where()`  | CSS `:where()` (zero specificity)         | `:where(Section)`          |
+
+> **Specificity.** All state selectors Tasty generates (modifiers, pseudo-classes,
+> `:is()`/`:not()` groups, and `@root` / `@parent` context) are wrapped in
+> `:where(...)` so they carry **zero specificity**. The only specificity anchors
+> are the doubled component class (`.t0.t0`) and sub-element `[data-element]`
+> attributes. This means overlapping rules (e.g. a `_` fallback floor and the
+> states layered over it) resolve purely by **source order** — Tasty emits
+> lower-priority states first and higher-priority states last so the cascade
+> produces the intended winner.
 
 ### `@media(...)` — Media Queries
 
 Media queries support dimension shorthands and custom unit expansion:
 
 | Shorthand | Expands to |
-|-----------|------------|
-| `w` | `width` |
-| `h` | `height` |
+| --------- | ---------- |
+| `w`       | `width`    |
+| `h`       | `height`   |
 
 ```jsx
 fill: {
@@ -295,14 +488,14 @@ fill: {
 }
 ```
 
-| Tasty syntax | CSS output |
-|--------------|------------|
-| `@media(w < 768px)` | `@media (width < 768px)` |
-| `@media(600px <= w < 1200px)` | `@media (600px <= width < 1200px)` |
-| `@media:print` | `@media print` |
-| `@media:screen` | `@media screen` |
+| Tasty syntax                         | CSS output                            |
+| ------------------------------------ | ------------------------------------- |
+| `@media(w < 768px)`                  | `@media (width < 768px)`              |
+| `@media(600px <= w < 1200px)`        | `@media (600px <= width < 1200px)`    |
+| `@media:print`                       | `@media print`                        |
+| `@media:screen`                      | `@media screen`                       |
 | `@media(prefers-color-scheme: dark)` | `@media (prefers-color-scheme: dark)` |
-| `@media(prefers-reduced-motion)` | `@media (prefers-reduced-motion)` |
+| `@media(prefers-reduced-motion)`     | `@media (prefers-reduced-motion)`     |
 
 Custom units work inside media queries: `@media(w < 40x)` → `@media (width < calc(var(--gap) * 40))`.
 
@@ -312,12 +505,12 @@ In practice, define state aliases via `configure({ states })` and use `@mobile`
 
 Container queries use the syntax `@(name, condition)` for named containers or `@(condition)` for the nearest ancestor container. Dimension shorthands (`w`, `h`, `is`, `bs`) are expanded the same way as `@media`.
 
-| Shorthand | Expands to |
-|-----------|------------|
-| `w` | `width` |
-| `h` | `height` |
-| `is` | `inline-size` |
-| `bs` | `block-size` |
+| Shorthand | Expands to    |
+| --------- | ------------- |
+| `w`       | `width`       |
+| `h`       | `height`      |
+| `is`      | `inline-size` |
+| `bs`      | `block-size`  |
 
 ```jsx
 const Panel = tasty({
@@ -330,14 +523,14 @@ const Panel = tasty({
 });
 ```
 
-| Tasty syntax | CSS output |
-|--------------|------------|
-| `@(layout, w < 600px)` | `@container layout (width < 600px)` |
-| `@(w < 600px)` | `@container (width < 600px)` |
-| `@(layout, $variant=danger)` | `@container layout style(--variant: "danger")` |
-| `@(layout, $compact)` | `@container layout style(--compact)` |
-| `@(scroll-state(stuck: top))` | `@container scroll-state(stuck: top)` |
-| `@(nav, scroll-state(stuck: top))` | `@container nav scroll-state(stuck: top)` |
+| Tasty syntax                       | CSS output                                     |
+| ---------------------------------- | ---------------------------------------------- |
+| `@(layout, w < 600px)`             | `@container layout (width < 600px)`            |
+| `@(w < 600px)`                     | `@container (width < 600px)`                   |
+| `@(layout, $variant=danger)`       | `@container layout style(--variant: "danger")` |
+| `@(layout, $compact)`              | `@container layout style(--compact)`           |
+| `@(scroll-state(stuck: top))`      | `@container scroll-state(stuck: top)`          |
+| `@(nav, scroll-state(stuck: top))` | `@container nav scroll-state(stuck: top)`      |
 
 Container style queries use `$prop` (boolean) or `$prop=value` syntax, which maps to CSS `style(--prop)` or `style(--prop: "value")`.
 
@@ -345,10 +538,10 @@ Container style queries use `$prop` (boolean) or `$prop=value` syntax, which map
 
 Feature queries test CSS property support. Use `$` as the first argument to test selector support:
 
-| Tasty syntax | CSS output |
-|--------------|------------|
-| `@supports(display: grid)` | `@supports (display: grid)` |
-| `@supports($, :has(*))` | `@supports selector(:has(*))` |
+| Tasty syntax                | CSS output                        |
+| --------------------------- | --------------------------------- |
+| `@supports(display: grid)`  | `@supports (display: grid)`       |
+| `@supports($, :has(*))`     | `@supports selector(:has(*))`     |
 | `!@supports(display: grid)` | `@supports (not (display: grid))` |
 
 ```jsx
@@ -358,6 +551,95 @@ display: {
 }
 ```
 
+### `_` — Fallback Floor
+
+By default Tasty makes states **mutually exclusive**: a higher-priority state
+turns the lower-priority ones off via negation, so exactly one branch applies.
+This relies on `A | !A` always being true. CSS feature/container queries break
+that assumption: `@supports(...)` and `@(...)` queries can be **unknown** (not
+just true/false), and `not(unknown)` is also unknown — so a negated default
+branch silently never applies. The classic case is `scroll-state`: a browser can
+support `container-type: scroll-state` while a specific `scroll-state(...)` query
+is unknown, leaving _no_ branch active.
+
+The `_` fallback floor solves this. Use `_` as a **standalone key** and its value
+**always applies** as a guaranteed floor: it never receives negation, and
+higher-priority states simply layer over it via the cascade.
+
+```jsx
+inset: {
+  _: '0 top',
+  '@supports(container-type: scroll-state) & @(scroll-state(scrolled: block-end))':
+    '-80x top',
+}
+```
+
+```css
+.t0.t0 {
+  inset: 0...;
+}
+@container scroll-state(scrolled: block-end) {
+  @supports (container-type: scroll-state) {
+    .t0.t0 {
+      inset: -80px...;
+    }
+  }
+}
+```
+
+The floor is emitted as a bare rule (no negated `@supports` / container branches),
+so it always applies. When the override matches it wins because it is emitted
+later and all state selectors share the same specificity (see the note on
+`:where()` below).
+
+Notes:
+
+- `_` is a **standalone key only** — it defines a single map-wide floor and
+  cannot be combined with state logic. Keys like `_ & hovered` or `_ | focused`
+  are ignored with an `INVALID_FALLBACK_KEY` dev warning.
+- `_` can coexist with the bare `''` default when other states exist: `''` is the
+  negated default, `_` is the always-on floor. With only `_` and `''` (no other
+  states) the `''` default is redundant — Tasty keeps the `_` value and drops
+  `''` with a `REDUNDANT_DEFAULT_STATE` warning.
+- `_` is position-independent: it is always placed at the lowest priority
+  regardless of where it appears in the map.
+
+#### `_` vs the `''` default
+
+In simple maps where every other state is a plain modifier (always cleanly
+on/off), `_` and `''` produce the **same visible result** — the base value shows
+whenever no other state wins. They diverge in three situations, and the root
+cause is always the same: **`''` is mutually exclusive (turned off by negation),
+while `_` is always on (layered underneath).**
+
+- **Unknown / invalid branches.** If a higher-priority branch sits behind a query
+  that can be _unknown_ (`@supports`, container, `scroll-state`) or uses a
+  selector the browser drops, the negated `''` default disappears along with it
+  (`not(unknown) = unknown`), leaving the property with no rule. The `_` floor
+  survives because it is an unconditional bare rule. This is the case `_` exists
+  for.
+
+- **Empty / "unset" states.** A state can intentionally produce _no_ output (an
+  empty value) to leave a property unset while that state is active. With `''`
+  this works — the default is negated away and nothing replaces it, so the
+  property unsets. With `_` the floor can never be turned off, so its value keeps
+  applying and the "unset on this state" intent is lost.
+
+  ```jsx
+  // '' : color unsets while loading.  '_' : color stays #text while loading.
+  color: { '': '#text', loading: '' }
+  ```
+
+- **States with different output shapes.** Because `_` layers additively, when
+  different states emit _different sets_ of declarations, the floor's
+  declarations bleed through wherever the winning state does not override the
+  same property — which can produce inconsistent combinations. A `''` default is
+  swapped out cleanly by its mutually-exclusive condition.
+
+Rule of thumb: **use `''` for the normal default** (clean mutual exclusivity,
+supports unsetting), and reach for `_` only when a value must survive an
+_unknown_ higher-priority branch.
+
 ### `@root(...)` — Root Element States
 
 Root states generate selectors on the `:root` element. They are useful for theme modes, feature flags, and other page-level conditions:
@@ -372,13 +654,13 @@ color: {
 }
 ```
 
-| Tasty syntax | CSS selector |
-|--------------|-------------|
-| `@root(schema=dark)` | `:root[data-schema="dark"]` |
-| `@root(hovered)` | `:root[data-hovered]` |
-| `@root(.premium-user)` | `:root.premium-user` |
-| `@root([lang="en"])` | `:root[lang="en"]` |
-| `!@root(schema=dark)` | `:root:not([data-schema="dark"])` |
+| Tasty syntax           | CSS selector                      |
+| ---------------------- | --------------------------------- |
+| `@root(schema=dark)`   | `:root[data-schema="dark"]`       |
+| `@root(hovered)`       | `:root[data-hovered]`             |
+| `@root(.premium-user)` | `:root.premium-user`              |
+| `@root([lang="en"])`   | `:root[lang="en"]`                |
+| `!@root(schema=dark)`  | `:root:not([data-schema="dark"])` |
 
 Root conditions are prepended to the component selector: `:root[data-schema="dark"] .t0.t0 { ... }`.
 
@@ -394,7 +676,7 @@ const Nav = tasty({
         '': '#text',
         '@own(:hover)': '#primary',
         '@own(:focus-visible)': '#primary',
-        'selected': '#primary',       // root-level modifier
+        selected: '#primary', // root-level modifier
       },
     },
   },
@@ -402,11 +684,11 @@ const Nav = tasty({
 });
 ```
 
-| Tasty syntax (inside sub-element) | CSS output |
-|-----------------------------------|------------|
-| `@own(:hover)` | `:hover` on the sub-element selector |
-| `@own(hovered)` | `[data-hovered]` on the sub-element selector |
-| `@own(theme=dark)` | `[data-theme="dark"]` on the sub-element selector |
+| Tasty syntax (inside sub-element) | CSS output                                        |
+| --------------------------------- | ------------------------------------------------- |
+| `@own(:hover)`                    | `:hover` on the sub-element selector              |
+| `@own(hovered)`                   | `[data-hovered]` on the sub-element selector      |
+| `@own(theme=dark)`                | `[data-theme="dark"]` on the sub-element selector |
 
 `@own()` is only valid inside sub-element styles. Using it on root styles emits a warning and is treated as a regular modifier.
 
@@ -424,35 +706,35 @@ const FadeIn = tasty({
 });
 ```
 
-| Tasty syntax | CSS output |
-|--------------|------------|
-| `@starting` | `@starting-style { .t0.t0 { ... } }` |
+| Tasty syntax | CSS output                           |
+| ------------ | ------------------------------------ |
+| `@starting`  | `@starting-style { .t0.t0 { ... } }` |
 
 ### `@parent(...)` — Parent Element States
 
-Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`) is supported inside `@parent()`.
+Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`, `^`) is supported inside `@parent()`.
 
 ```jsx
 const Highlight = tasty({
   styles: {
     fill: {
       '': '#white',
-      '@parent(hovered)': '#gray.05',         // Any ancestor has [data-hovered]
-      '@parent(theme=dark, >)': '#dark-02',   // Direct parent has [data-theme="dark"]
+      '@parent(hovered)': '#gray.05', // Any ancestor has [data-hovered]
+      '@parent(theme=dark, >)': '#dark-02', // Direct parent has [data-theme="dark"]
     },
   },
 });
 ```
 
-| Syntax | CSS Output |
-|--------|------------|
-| `@parent(hovered)` | `:is([data-hovered] *)` |
-| `!@parent(hovered)` | `:not([data-hovered] *)` |
-| `@parent(hovered, >)` | `:is([data-hovered] > *)` (direct parent) |
-| `@parent(.active)` | `:is(.active *)` |
-| `@parent(hovered & focused)` | `:is([data-hovered][data-focused] *)` (same ancestor) |
+| Syntax                                | CSS Output                                                           |
+| ------------------------------------- | -------------------------------------------------------------------- |
+| `@parent(hovered)`                    | `:is([data-hovered] *)`                                              |
+| `!@parent(hovered)`                   | `:not([data-hovered] *)`                                             |
+| `@parent(hovered, >)`                 | `:is([data-hovered] > *)` (direct parent)                            |
+| `@parent(.active)`                    | `:is(.active *)`                                                     |
+| `@parent(hovered & focused)`          | `:is([data-hovered][data-focused] *)` (same ancestor)                |
 | `@parent(hovered) & @parent(focused)` | `:is([data-hovered] *):is([data-focused] *)` (independent ancestors) |
-| `@parent(hovered \| focused)` | `:is([data-hovered] *, [data-focused] *)` (OR inside single wrapper) |
+| `@parent(hovered \| focused)`         | `:is([data-hovered] *, [data-focused] *)` (OR inside single wrapper) |
 
 For sub-elements, the parent check applies to the root element's ancestors:
 
@@ -483,37 +765,38 @@ const Card = tasty({
   styles: {
     display: {
       '': 'block',
-      ':has(> Icon)': 'grid',              // has Icon as direct child
-      ':has(+ Icon)': 'grid',              // immediately followed by an Icon sibling
-      ':has(~ Icon)': 'grid',              // has an Icon sibling somewhere after
-      ':has(Icon +)': 'grid',              // immediately preceded by an Icon sibling (auto-completes to `Icon + *`)
-      ':has(Icon ~)': 'grid',              // has an Icon sibling somewhere before (auto-completes to `Icon ~ *`)
-      ':is(fieldset > label)': 'inline',   // is a label inside a fieldset (HTML tags)
-      '!:has(> Icon)': 'flex',             // negation: no Icon child
+      ':has(> Icon)': 'grid', // has Icon as direct child
+      ':has(+ Icon)': 'grid', // immediately followed by an Icon sibling
+      ':has(~ Icon)': 'grid', // has an Icon sibling somewhere after
+      ':has(Icon +)': 'grid', // immediately preceded by an Icon sibling (auto-completes to `Icon + *`)
+      ':has(Icon ~)': 'grid', // has an Icon sibling somewhere before (auto-completes to `Icon ~ *`)
+      ':is(fieldset > label)': 'inline', // is a label inside a fieldset (HTML tags)
+      '!:has(> Icon)': 'flex', // negation: no Icon child
     },
   },
 });
 ```
 
-| Syntax | CSS Output | Meaning |
-|--------|------------|---------|
-| `:has(> Icon)` | `:has(> [data-element="Icon"])` | Has Icon as direct child |
-| `:has(+ Icon)` | `:has(+ [data-element="Icon"])` | Immediately followed by an Icon sibling |
-| `:has(~ Icon)` | `:has(~ [data-element="Icon"])` | Has an Icon sibling somewhere after |
-| `:has(Icon +)` | `:has([data-element="Icon"] + *)` | Immediately preceded by an Icon sibling |
-| `:has(Icon ~)` | `:has([data-element="Icon"] ~ *)` | Has an Icon sibling somewhere before |
-| `:has(>)` | `:has(> *)` | Has any direct child |
-| `:is(> Field + input)` | `:is(> [data-element="Field"] + input)` | Structural match |
-| `:has(button)` | `:has(button)` | HTML tag (lowercase, unchanged) |
-| `!:has(> Icon)` | `:not(:has(> [data-element="Icon"]))` | Negation (use `!`) |
-| `!:is(Panel)` | `:not([data-element="Panel"])` | Negation (use `!:is`) |
-
-Combine with other states using boolean logic:
+| Syntax                 | CSS Output                              | Meaning                                 |
+| ---------------------- | --------------------------------------- | --------------------------------------- |
+| `:has(> Icon)`         | `:has(> [data-element="Icon"])`         | Has Icon as direct child                |
+| `:has(+ Icon)`         | `:has(+ [data-element="Icon"])`         | Immediately followed by an Icon sibling |
+| `:has(~ Icon)`         | `:has(~ [data-element="Icon"])`         | Has an Icon sibling somewhere after     |
+| `:has(Icon +)`         | `:has([data-element="Icon"] + *)`       | Immediately preceded by an Icon sibling |
+| `:has(Icon ~)`         | `:has([data-element="Icon"] ~ *)`       | Has an Icon sibling somewhere before    |
+| `:has(>)`              | `:has(> *)`                             | Has any direct child                    |
+| `:is(> Field + input)` | `:is(> [data-element="Field"] + input)` | Structural match                        |
+| `:has(button)`         | `:has(button)`                          | HTML tag (lowercase, unchanged)         |
+| `!:has(> Icon)`        | `:not(:has(> [data-element="Icon"]))`   | Negation (use `!`)                      |
+| `!:is(Panel)`          | `:not([data-element="Panel"])`          | Negation (use `!:is`)                   |
+
+Combine with other states using boolean logic (`&`, `|`, `!`, `^`):
 
 ```jsx
-':has(> Icon) & hovered'                // structural + data attribute
-'@parent(hovered) & :has(> Icon)'       // parent check + structural
-':has(> Icon) | :has(> Button)'         // OR: either sub-element present
+':has(> Icon) & hovered'; // AND: structural + data attribute
+'@parent(hovered) & :has(> Icon)'; // AND: parent check + structural
+':has(> Icon) | :has(> Button)'; // OR: either sub-element present
+':has(> Icon) ^ :has(> Button)'; // XOR: exactly one present
 ```
 
 > **Nesting limit:** The state key parser supports up to 2 levels of nested parentheses inside `:is()`, `:has()`, `:not()`, and `:where()` — e.g. `:has(Input:not(:disabled))` works, but 3+ levels like `:has(:is(:not(:hover)))` will not be tokenized correctly. This covers virtually all practical use cases.
@@ -548,8 +831,8 @@ CSS cannot transition or animate custom properties unless the browser knows thei
 const AnimatedGradient = tasty({
   styles: {
     '$gradient-angle': '0deg',
-    '#theme': 'okhsl(280 80% 50%)',
-    background: 'linear-gradient($gradient-angle, #theme, transparent)',
+    '#theme': 'okhst(280 80% 50%)',
+    image: 'linear-gradient($gradient-angle, #theme, #clear)',
     transition: '$$gradient-angle 0.3s, ##theme 0.3s',
   },
 });
@@ -557,30 +840,30 @@ const AnimatedGradient = tasty({
 
 Here `$gradient-angle: '0deg'` is detected as `<angle>` and `#theme` as `<color>` (via the `#name` naming convention), so both transitions work without any manual `@property` declarations. Numeric types (`<number>`, `<length>`, `<percentage>`, `<angle>`, `<time>`) are inferred from values; `<color>` is inferred from `#name` tokens.
 
-Use explicit `@properties` when you need non-default settings like `inherits: false`:
+Use explicit `@property` when you need non-default settings like `inherits: false`:
 
 ```jsx
-'@properties': {
+'@property': {
   '$gradient-angle': { syntax: '<angle>', inherits: false, initialValue: '0deg' },
 },
 ```
 
 ---
 
-## Font Face (`@fontFace`)
+## Font Face (`@font-face`)
 
 Register custom fonts directly inside a `styles` object. Keys are font-family names, values are descriptor objects (or arrays of them for multiple weights/styles).
 
 ```ts
 const Heading = tasty({
   styles: {
-    '@fontFace': {
+    '@font-face': {
       'Brand Sans': {
         src: 'url("/fonts/brand-sans.woff2") format("woff2")',
         fontDisplay: 'swap',
       },
     },
-    fontFamily: '"Brand Sans", sans-serif',
+    font: '"Brand Sans", sans-serif',
   },
 });
 ```
@@ -590,7 +873,7 @@ const Heading = tasty({
 Supply an array to register several variants of the same family:
 
 ```ts
-'@fontFace': {
+'@font-face': {
   'Brand Sans': [
     { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
     { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
@@ -600,26 +883,26 @@ Supply an array to register several variants of the same family:
 
 ### Supported descriptors
 
-| Descriptor | CSS property | Type |
-|---|---|---|
-| `src` (required) | `src` | `string` |
-| `fontWeight` | `font-weight` | `string \| number` |
-| `fontStyle` | `font-style` | `string` |
-| `fontStretch` | `font-stretch` | `string` |
-| `fontDisplay` | `font-display` | `'auto' \| 'block' \| 'swap' \| 'fallback' \| 'optional'` |
-| `unicodeRange` | `unicode-range` | `string` |
-| `ascentOverride` | `ascent-override` | `string` |
-| `descentOverride` | `descent-override` | `string` |
-| `lineGapOverride` | `line-gap-override` | `string` |
-| `sizeAdjust` | `size-adjust` | `string` |
-| `fontFeatureSettings` | `font-feature-settings` | `string` |
-| `fontVariationSettings` | `font-variation-settings` | `string` |
+| Descriptor              | CSS property              | Type                                                      |
+| ----------------------- | ------------------------- | --------------------------------------------------------- |
+| `src` (required)        | `src`                     | `string`                                                  |
+| `fontWeight`            | `font-weight`             | `string \| number`                                        |
+| `fontStyle`             | `font-style`              | `string`                                                  |
+| `fontStretch`           | `font-stretch`            | `string`                                                  |
+| `fontDisplay`           | `font-display`            | `'auto' \| 'block' \| 'swap' \| 'fallback' \| 'optional'` |
+| `unicodeRange`          | `unicode-range`           | `string`                                                  |
+| `ascentOverride`        | `ascent-override`         | `string`                                                  |
+| `descentOverride`       | `descent-override`        | `string`                                                  |
+| `lineGapOverride`       | `line-gap-override`       | `string`                                                  |
+| `sizeAdjust`            | `size-adjust`             | `string`                                                  |
+| `fontFeatureSettings`   | `font-feature-settings`   | `string`                                                  |
+| `fontVariationSettings` | `font-variation-settings` | `string`                                                  |
 
 > Font-face rules are permanent — they are injected once and never cleaned up, matching how browsers handle `@font-face`.
 
 ---
 
-## Counter Style (`@counterStyle`)
+## Counter Style (`@counter-style`)
 
 Define custom list markers via the CSS `@counter-style` at-rule. Keys are counter-style names, values are descriptor objects.
 
@@ -627,7 +910,7 @@ Define custom list markers via the CSS `@counter-style` at-rule. Keys are counte
 const EmojiList = tasty({
   tag: 'ol',
   styles: {
-    '@counterStyle': {
+    '@counter-style': {
       thumbs: {
         system: 'cyclic',
         symbols: '"👍"',
@@ -641,23 +924,88 @@ const EmojiList = tasty({
 
 ### Supported descriptors
 
-| Descriptor | CSS property | Type |
-|---|---|---|
-| `system` (required) | `system` | `'cyclic' \| 'numeric' \| 'alphabetic' \| 'symbolic' \| 'additive' \| 'fixed' \| string` |
-| `symbols` | `symbols` | `string` |
-| `additiveSymbols` | `additive-symbols` | `string` |
-| `prefix` | `prefix` | `string` |
-| `suffix` | `suffix` | `string` |
-| `negative` | `negative` | `string` |
-| `range` | `range` | `string` |
-| `pad` | `pad` | `string` |
-| `fallback` | `fallback` | `string` |
-| `speakAs` | `speak-as` | `string` |
+| Descriptor          | CSS property       | Type                                                                                     |
+| ------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
+| `system` (required) | `system`           | `'cyclic' \| 'numeric' \| 'alphabetic' \| 'symbolic' \| 'additive' \| 'fixed' \| string` |
+| `symbols`           | `symbols`          | `string`                                                                                 |
+| `additiveSymbols`   | `additive-symbols` | `string`                                                                                 |
+| `prefix`            | `prefix`           | `string`                                                                                 |
+| `suffix`            | `suffix`           | `string`                                                                                 |
+| `negative`          | `negative`         | `string`                                                                                 |
+| `range`             | `range`            | `string`                                                                                 |
+| `pad`               | `pad`              | `string`                                                                                 |
+| `fallback`          | `fallback`         | `string`                                                                                 |
+| `speakAs`           | `speak-as`         | `string`                                                                                 |
 
 > Counter-style rules are permanent — they are injected once and never cleaned up, matching how browsers handle `@counter-style`.
 
 ---
 
+## Functions (`@function`)
+
+Define reusable, parameterized CSS [custom functions](https://developer.mozilla.org/en-US/docs/Web/CSS/@function) via the CSS `@function` at-rule. A custom function takes parameters and returns a single value — like a dynamic custom property.
+
+The token convention follows Tasty's `$` vs `$$` distinction:
+
+- **`$$name`** — the literal callable name (`--name`). Used for the **definition key** and for **invocation** `$$name(...)`, mirroring the existing `$$gradient-angle` → `--gradient-angle` sugar. The definition key matches the call site.
+- **`$name`** — a custom-property declaration/reference (`var(--name)`). Used for **parameters** and **local variables**, exactly like declaring custom props in a styles object.
+- **Local variables** are declared directly as `$name` keys on the descriptor — the body reads like a mini styles object.
+- `result`, local-variable values, and parameter `default` values flow through the full Tasty DSL, so units (`2x`), color tokens (`#theme`), auto-calc (`(-1 * $value)` → `calc(-1 * var(--value))`), and fallbacks (`($shadow-color, black)` → `var(--shadow-color, black)`) all work.
+
+```ts
+const Box = tasty({
+  styles: {
+    '@function': {
+      // simplest: one bare param + result (auto-calc, no explicit calc())
+      $$negative: { args: ['$value'], result: '(-1 * $value)' },
+
+      // typed param + default + return type + local variable
+      $$shadow: {
+        args: { '$shadow-color': { syntax: '<color>', default: 'inherit' } },
+        returns: '<color>',
+        $offset: '2px', // local variable
+        result: '$offset $offset ($shadow-color, black)',
+      },
+    },
+    margin: '$$negative(10px) top', // → margin: --negative(10px) 0 0 0
+    shadow: '$$shadow(#accent)', // → box-shadow: --shadow(var(--accent-color))
+  },
+});
+```
+
+Generated CSS:
+
+```css
+@function --negative(--value) {
+  result: calc(-1 * var(--value));
+}
+@function --shadow(--shadow-color <color>: inherit) returns <color> {
+  --offset: 2px;
+  result: var(--offset) var(--offset) var(--shadow-color, black);
+}
+.t0 {
+  margin: --negative(10px) 0 0 0;
+  box-shadow: --shadow(var(--accent-color));
+}
+```
+
+### Descriptor shape
+
+| Field               | Type                                              | Notes                                                                                    |
+| ------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `result` (required) | `string`                                          | The `result:` value, parsed through the Tasty DSL.                                       |
+| `args`              | `string[]` \| `Record<string, FunctionParameter>` | Ordered parameters. Array form lists bare names; object form maps names to type/default. |
+| `returns`           | `string`                                          | Optional return type, e.g. `'<color>'`.                                                  |
+| `$name` keys        | `string \| number`                                | Any `$name` key declares a local variable `--name` (value parsed).                       |
+
+A `FunctionParameter` is one of: `true` (bare param), a string CSS type shorthand (`'<length>'`), or `{ syntax?: string; default?: string | number }`.
+
+Functions can also be registered with the [`useFunction`](react-api.md#usefunction) hook or globally via [`configure({ functions })`](configuration.md#functions) (the same map also accepts bare-key parse functions).
+
+> `@function` is permanent — injected once and never cleaned up, like `@counter-style`. It is an experimental CSS feature ([Chrome 139+](https://developer.mozilla.org/en-US/docs/Web/CSS/@function)); unsupported browsers safely ignore the native rule, so use it as progressive enhancement — or enable the [`configure({ polyfills: { functions: true } })`](configuration.md#polyfills) inline polyfill to expand `$$name(...)` calls into plain CSS for full cross-browser support.
+
+---
+
 ## Style Properties
 
 For a complete reference of all enhanced style properties — syntax, values, modifiers, and recommendations — see **[Style Properties Reference](styles.md)**.
@@ -666,8 +1014,8 @@ For a complete reference of all enhanced style properties — syntax, values, mo
 
 ## Learn more
 
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
 - **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
-- **[Zero Runtime (tastyStatic)](tasty-static.md)** — Build-time static styling with Babel plugin
+- **[Build-Time Extraction (`tastyStatic`)](tasty-static.md)** — Static styling with the Babel plugin