@tenphi/tasty 3.10.0 → 3.11.1

package/docs/dsl.md

@@ -6,6 +6,8 @@ The same value syntax, state maps, tokens, units, extension semantics, and speci
 
 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).
 
+To autocomplete your own token and preset names, see [TypeScript autocomplete](getting-started.md#typescript-autocomplete); to check state keys, tokens, units, and values at lint time, see [ESLint plugin](getting-started.md#eslint-plugin).
+
 ---
 
 ## Dictionary
@@ -18,6 +20,15 @@ Object where keys represent states and values are the styles to apply:
 fill: { '': '#white', hovered: '#gray.05', 'theme=danger': '#red' }
 ```
 
+Define an alias for one component by adding an `'@name': '<state expression>'` key to its styles. It works like a global alias from [`configure({ states })`](configuration.md#options), scoped to that component:
+
+```jsx
+styles: {
+  '@narrow': '@media(w < 600px)',
+  fill: { '': '#surface', '@narrow': '#surface-mobile' },
+}
+```
+
 #### State Key Types
 
 | Syntax             | Example                  | Generated CSS                                                            |
@@ -34,17 +45,20 @@ fill: { '': '#white', hovered: '#gray.05', 'theme=danger': '#red' }
 
 #### 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:
+`disabled`, `checked`, and `hidden` are built-in automatic states. A Tasty component sets `data-disabled`, `data-checked`, and `data-hidden` from the native `disabled`, `checked`, and `hidden` props (or `isDisabled`, `isChecked`, `isHidden`), so each pair below expresses the same component state:
 
-| Concise Tasty state | Explicit attribute selector |
-| ------------------- | --------------------------- |
-| `disabled`          | `[disabled]`                |
-| `checked`           | `[checked]`                 |
+| Concise Tasty state | Compiles to       | Explicit attribute selector |
+| ------------------- | ----------------- | --------------------------- |
+| `disabled`          | `[data-disabled]` | `[disabled]`                |
+| `checked`           | `[data-checked]`  | `[checked]`                 |
+| `hidden`            | `[data-hidden]`   | `[hidden]`                  |
 
 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)`.
 
+A top-level comma is the same as `|`: `'hovered, focused'` is `'hovered | 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
@@ -76,9 +90,7 @@ Element styled using a capitalized key. Identified by `data-element` attribute:
 
 ```jsx
 styles: {
-  Title: {
-    preset: 'h3';
-  }
+  Title: { preset: 'h3' },
 }
 // Targets: <div data-element="Title">
 ```
@@ -117,14 +129,16 @@ The `@` placeholder marks exactly where `[data-element="..."]` is injected, allo
 const List = tasty({
   styles: {
     Item: {
-      $: '>@:last-child',
-      border: 'none',
+      $: '>@::after',
+      content: '""',
     },
   },
 });
-// → .t0 > [data-element="Item"]:last-child { border: none }
+// → .t1x29r0l.t1x29r0l > [data-element="Item"]::after { content: ""; }
 ```
 
+Keep conditions such as `:last-child` out of `$` and write them as `@own(:last-child)` in a state map; `tasty/no-state-in-selector` warns otherwise.
+
 ### Color Token
 
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:
@@ -157,6 +171,10 @@ fill: '#current',           // → currentcolor
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
+`#white`, `#black`, `#border`, and `#outline` are registered by default (see [Default properties](#default-properties)), and `#clear` is a built-in alias for `transparent` (see [below](#clear-is-transparent)), so they work before you define any tokens.
+
+A name that is also a hex color is read as a token with the literal as its fallback, in every color style: `color: '#ddd'` emits `var(--ddd-color, #ddd)`, and `#ddd.5` emits `oklch(from var(--ddd-color, #ddd) l c h / .5)`. A `#ddd` token, if you define one, wins over the literal.
+
 The suffix sets the alpha on the token's color with CSS relative color syntax:
 
 ```jsx
@@ -182,6 +200,17 @@ Two properties follow from writing the alpha slot rather than compositing:
   `/ var(--fade)` unchanged, so it works whether `$fade` holds `.5` or `50%` —
   which is what `--*-opacity` properties are registered to accept.
 
+### `#clear` is transparent
+
+`#clear` is a built-in [replace token](#replace-tokens) for `transparent`.
+Opacity suffixes are ignored: `#clear.5` and `#clear.$fade` both emit
+`transparent`. The same rule applies to user-defined replace tokens resolving
+to `transparent`, including aliases of `#clear`.
+
+It does not read `--clear-color` or require an `@property` registration.
+An explicit `configure({ replaceTokens: { '#clear': ... } })` overrides the
+default alias and uses the replacement's usual opacity behavior.
+
 ### `#current` is the keyword
 
 `#current` emits the `currentcolor` keyword, so it resolves against the element
@@ -219,7 +248,7 @@ through `color-mix()`, which works from Safari 16.2 and composes like every othe
 
 ### `#current` composes instead
 
-`#current` is the one exception, and the difference is deliberate. A token _names_
+`#current` composes alpha, 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":
@@ -236,9 +265,10 @@ 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).
+Token fades always use `oklch(from …)`: it is unbounded, so a wide-gamut color
+survives a round trip that a gamut-limited space would clamp. `#current` fades
+mix `in oklab`. Nothing configures either — see
+[Color space](configuration.md#color-space).
 
 ---
 
@@ -256,6 +286,9 @@ border: '1bw solid oklch(from #primary l c h / 50%)',  // relative color syntax
 shadow: '0 0 1x color-mix(in oklab, #dark 20%, transparent)',
 ```
 
+Tasty also ships `okhsl()` and `okhst()`, which compile to `rgb()` at parse
+time: `fill: 'okhsl(280 80% 50%)'` → `rgb(40% 38.5% 88.2%)`.
+
 `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.
@@ -293,16 +326,16 @@ 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        | Default          | Example | CSS output       |
+| ---- | ------------------ | ---------------- | ------- | ---------------- |
+| `x`  | Spacing step       | `8px`            | `2x`    | `16px`           |
+| `r`  | Border radius      | `6px`            | `1r`    | `6px`            |
+| `cr` | Card border radius | `10px`           | `1cr`   | `10px`           |
+| `bw` | Border width       | `1px`            | `2bw`   | `2px`            |
+| `ow` | Outline width      | `3px`            | `1ow`   | `3px`            |
+| `sf` | Stable fraction    | `minmax(0, Nfr)` | `1sf`   | `minmax(0, 1fr)` |
 
-You can register additional custom units via [`configure()`](configuration.md#options).
+Units compile to plain values. Change the scale with `configure({ units: { x: '4px' } })`, or point a unit at a custom property when it must change at runtime: with `units: { x: 'var(--gap)' }`, `2x` compiles to `calc(2 * var(--gap))`. Setting a `$gap` or `$radius` token does not change the units. Register additional units the same way via [`configure()`](configuration.md#options).
 
 ---
 
@@ -359,7 +392,7 @@ const CardWithPanel = tasty({
 });
 ```
 
-At each level, base recipes are collected in name order (later recipes replace earlier values for the same property), then local styles are merged, then post recipes are merged. The merges with local styles and post recipes follow the [state-map extension and replacement rules](#extending-vs-replacing-state-maps).
+At each level, base recipes are collected in the order listed (later recipes replace earlier values for the same property), then local styles are merged, then post recipes are merged. The merges with local styles and post recipes follow the [state-map extension and replacement rules](#extending-vs-replacing-state-maps).
 
 Recipe definitions themselves cannot contain a `recipe` reference to another recipe: there is no recursive expansion or recipe inheritance. Compose names in the root or sub-element `recipe` property instead. See [Configuration — Recipes](configuration.md#recipes) for an unsupported nesting example.
 
@@ -439,12 +472,14 @@ 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
+const MyButton = tasty(Button, {
+  styles: {
+    fill: {
+      hovered: null, // removes the parent's hovered state
+      disabled: false, // tombstone — no CSS for disabled, blocks recipe too
+    },
+  },
+});
 ```
 
 ### Resetting Properties with `null` and `false`
@@ -494,7 +529,7 @@ const SimpleButton = tasty(Button, {
 
 ### `@media(...)` — Media Queries
 
-Media queries support dimension shorthands and custom unit expansion:
+Media queries support dimension shorthands:
 
 | Shorthand | Expands to |
 | --------- | ---------- |
@@ -516,10 +551,17 @@ fill: {
 | `@media(600px <= w < 1200px)`        | `@media (600px <= width < 1200px)`    |
 | `@media:print`                       | `@media print`                        |
 | `@media:screen`                      | `@media screen`                       |
+| `@media:all`                         | `@media all`                          |
+| `@media:speech`                      | `@media speech`                       |
 | `@media(prefers-color-scheme: dark)` | `@media (prefers-color-scheme: dark)` |
 | `@media(prefers-reduced-motion)`     | `@media (prefers-reduced-motion)`     |
+| `@media(aspect-ratio > 16/9)`        | `@media (aspect-ratio > 16/9)`        |
 
-Custom units work inside media queries: `@media(w < 40x)` → `@media (width < calc(var(--gap) * 40))`.
+Tasty units resolve to their literal length inside query conditions, built-in and configured units alike: `@media(w < 40x)` emits `@media (width < 320px)`. A query condition cannot read a custom property, so a unit configured as one (`units: { x: 'var(--gap)' }`) cannot be used there; write that length in `px`, `em`, or `rem`.
+
+Units are only converted in features that take a length: `width`, `height`, `inline-size`, and `block-size`, with or without `min-`/`max-` (`@media(min-width: 40x)` converts too). Every other feature keeps its value as written, so `@media(min-resolution: 2x)` and `@media(resolution >= 2x)` reach the browser unchanged: there `x` is CSS's own resolution unit, an alias of `dppx`.
+
+When it combines or orders conditions, Tasty compares bounds only within one unit. `@media(w >= 600px) & @media(w < 40em)` keeps both bounds, because a query `em` follows the user's font size, so `600px` and `40em` cannot be ordered at build time.
 
 In practice, define state aliases via `configure({ states })` and use `@mobile` instead of writing the full query in every component.
 
@@ -545,28 +587,30 @@ 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")`.
+Container style queries use `$prop` (boolean) or `$prop=value` syntax, which maps to CSS `style(--prop)` or `style(--prop: value)`. The value is emitted unquoted, so it matches a custom property set to the identifier `danger`, not the string `"danger"`.
+
+Other size features pass through as written: `@(aspect-ratio > 1)` → `@container (aspect-ratio > 1)`, `@(orientation: portrait)` → `@container (orientation: portrait)`. They need a container with `containerType: 'size'`, since an `inline-size` container has no block size to compare against.
 
 ### `@supports(...)` — Feature Queries
 
 Feature queries test CSS property support and accept CSS support functions such
 as `at-rule()`. Use `$` as the first argument to test selector support:
 
-| Tasty syntax                 | CSS output                         |
-| ---------------------------- | ---------------------------------- |
-| `@supports(display: grid)`   | `@supports (display: grid)`        |
-| `@supports($, :has(*))`       | `@supports selector(:has(*))`      |
-| `@supports(at-rule(@scope))`  | `@supports (at-rule(@scope))`      |
-| `!@supports(display: grid)`  | `@supports (not (display: grid))`  |
+| Tasty syntax                  | CSS output                          |
+| ----------------------------- | ----------------------------------- |
+| `@supports(display: grid)`    | `@supports (display: grid)`         |
+| `@supports($, :has(*))`       | `@supports selector(:has(*))`       |
+| `@supports(at-rule(@scope))`  | `@supports (at-rule(@scope))`       |
+| `!@supports(display: grid)`   | `@supports (not (display: grid))`   |
 | `!@supports(at-rule(@scope))` | `@supports (not (at-rule(@scope)))` |
 
 ```jsx
@@ -620,12 +664,12 @@ inset: {
 
 ```css
 .t0.t0 {
-  inset: 0...;
+  inset: 0 auto auto auto;
 }
-@container scroll-state(scrolled: block-end) {
-  @supports (container-type: scroll-state) {
+@supports (container-type: scroll-state) {
+  @container scroll-state(scrolled: block-end) {
     .t0.t0 {
-      inset: -80px...;
+      inset: -640px auto auto auto;
     }
   }
 }
@@ -634,7 +678,7 @@ inset: {
 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).
+`:where()` above).
 
 Notes:
 
@@ -706,7 +750,7 @@ color: {
 | `@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 { ... }`.
+Root conditions are prepended to the component selector inside `:where()`: `:where(:root[data-schema="dark"]) .t0.t0 { ... }`.
 
 ### `@own(...)` — Sub-element's Own State
 
@@ -752,11 +796,11 @@ const FadeIn = tasty({
 
 | Tasty syntax | CSS output                           |
 | ------------ | ------------------------------------ |
-| `@starting`  | `@starting-style { .t0.t0 { ... } }` |
+| `@starting`  | `.t0.t0 { @starting-style { ... } }` |
 
 ### `@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 `:where([selector] *)` / `:where(:not([selector] *))` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`, `^`) is supported inside `@parent()`.
 
 ```jsx
 const Highlight = tasty({
@@ -770,15 +814,15 @@ const Highlight = tasty({
 });
 ```
 
-| 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) |
+| Syntax                                | CSS Output                                                                 |
+| ------------------------------------- | -------------------------------------------------------------------------- |
+| `@parent(hovered)`                    | `:where([data-hovered] *)`                                                 |
+| `!@parent(hovered)`                   | `:where(:not([data-hovered] *))`                                           |
+| `@parent(hovered, >)`                 | `:where([data-hovered] > *)` (direct parent)                               |
+| `@parent(.active)`                    | `:where(.active *)`                                                        |
+| `@parent(hovered & focused)`          | `:where([data-hovered][data-focused] *)` (same ancestor)                   |
+| `@parent(hovered) & @parent(focused)` | `:where([data-hovered] *):where([data-focused] *)` (independent ancestors) |
+| `@parent(hovered \| focused)`         | `:where([data-hovered] *, [data-focused] *)` (OR inside single wrapper)    |
 
 For sub-elements, the parent check applies to the root element's ancestors:
 
@@ -793,12 +837,12 @@ const Card = tasty({
     },
   },
 });
-// → .t0.t0:is([data-hovered] *) [data-element="Label"]
+// → .t0.t0:where([data-hovered] *) [data-element="Label"]
 ```
 
 ### `:is()`, `:has()` — CSS Structural Pseudo-classes
 
-Use CSS structural pseudo-classes directly in state keys. Capitalized words become `[data-element="..."]` selectors; lowercase words are HTML tags. A trailing combinator (`>`, `+`, `~`) is auto-completed with `*`.
+Use CSS structural pseudo-classes directly in state keys. Capitalized words become `[data-element="..."]` selectors; lowercase words are HTML tags. A trailing combinator (`>`, `+`, `~`) is auto-completed with `*`. Leading combinators (`> Icon`, `+ Icon`) are relative selectors and are valid only inside `:has()`.
 
 `:where()` and `:not()` are also supported but rarely needed — use `:is()` and `!` negation instead.
 
@@ -821,18 +865,18 @@ const Card = tasty({
 });
 ```
 
-| 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`)                   |
+| 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)` | Is an input right after a Field sibling |
+| `: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 (`&`, `|`, `!`, `^`):
 
@@ -894,6 +938,26 @@ Use explicit `@property` when you need non-default settings like `inherits: fals
 },
 ```
 
+### Default properties
+
+Tasty registers these properties itself. Style handlers read their defaults from them rather than repeating the values inline, so styles work before you define any tokens, and defining a token replaces the initial value.
+
+| Token                                                | Initial value                            | Read by                                                        |
+| ---------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------- |
+| `#current`                                           | `currentcolor`                           | anything reading `$current-color`, which `color` sets          |
+| `#white`, `#black`                                   | `rgb(255 255 255)`, `rgb(0 0 0)`         | your styles                                                    |
+| `#border`                                            | `currentcolor`                           | `border` with no color                                         |
+| `#outline`                                           | `currentcolor`                           | `outline` with no color                                        |
+| `$gap`, `$radius`, `$border-width`, `$outline-width` | `8px`, `6px`, `1px`, `3px`               | units you point at them, as in `units: { x: 'var(--gap)' }`    |
+| `$transition`                                        | `80ms`                                   | `transition` with no duration                                  |
+| `$sharp-radius`                                      | `0px`                                    | the sharp corners of `radius: 'leaf'` and `radius: 'backleaf'` |
+| `$bold-font-weight`                                  | `700`                                    | `preset: 'name / strong'`                                      |
+| `$font-sans-fallback`, `$font-mono-fallback`         | a `system-ui` and a `ui-monospace` stack | `font` and presets, after `$font-sans` / `$font-mono`          |
+
+Every rendering path emits them: the client injector, the SSR collector (`TastyRegistry`, `tastyIntegration()`, `runWithCollector()`), the `withTastyNext()` shared stylesheet, and the Babel plugin. CSS written with the programmatic API needs [`extractConfigProperties()`](tasty-static.md#programmatic-api), once per stylesheet. Server rendering without a collector, such as Astro without `tastyIntegration()`, emits none of them.
+
+The initial values need `@property` support: Chrome and Edge 85+, Firefox 128+, Safari 16.4+. In older engines a handler that reads one of these tokens resolves to nothing unless your tokens define it: a `border` with no color draws no border, and a `transition` with no duration does not animate. To support those engines, define the tokens your styles rely on in `configure({ tokens })`.
+
 ---
 
 ## Font Face (`@font-face`)
@@ -954,7 +1018,7 @@ Define custom list markers via the CSS `@counter-style` at-rule. Keys are counte
 
 ```ts
 const EmojiList = tasty({
-  tag: 'ol',
+  as: 'ol',
   styles: {
     '@counter-style': {
       thumbs: {
@@ -1046,7 +1110,7 @@ Generated CSS:
 
 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).
+Functions can also be registered with the [`useFunction`](react-api.md#usefunction) style function 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.
 

package/docs/getting-started.md

@@ -64,7 +64,7 @@ export default function App() {
 
 `tasty()` returns a normal React component. The keys in each state map define priority: later branches win over earlier ones. Because `disabled` is last, a disabled button keeps its disabled styles even while the pointer is over it.
 
-`disabled` and `checked` are built-in automatic states. Tasty activates them from the corresponding native prop or attribute, so `disabled` is the concise Tasty form of `[disabled]`, and `checked` is the concise form of `[checked]`.
+`disabled`, `checked`, and `hidden` are built-in automatic states. Tasty sets `data-disabled`, `data-checked`, and `data-hidden` from the matching native prop, so `disabled` in a state map is the concise form of `[disabled]` (it compiles to `[data-disabled]`).
 
 Tasty compiles that priority into selectors that exclude one another. The hover, active, and disabled background rules cannot all match and ask the CSS cascade to decide the winner.
 
@@ -101,9 +101,9 @@ import App from './App';
 createRoot(document.getElementById('root')!).render(<App />);
 ```
 
-### Define shared tokens and override default unit values
+### Define shared tokens and units
 
-Color tokens like `#primary` resolve to CSS custom properties at runtime (e.g. `var(--primary-color)`). Built-in units like `x`, `r`, and `bw` already work without setup and multiply CSS custom properties by default. Use `configure({ tokens })` when you want to define shared token values or override the defaults your app uses:
+Color tokens like `#primary` and value tokens like `$sidebar-width` resolve to CSS custom properties (`var(--primary-color)`, `var(--sidebar-width)`). Define their values with `configure({ tokens })`:
 
 ```tsx
 // src/tasty-config.ts
@@ -114,10 +114,7 @@ configure({
     '#primary': 'oklch(55% 0.25 265)',
     '#surface': '#fff',
     '#text': '#111',
-    $gap: '8px',
-    $radius: '4px',
-    '$border-width': '1px',
-    '$outline-width': '2px',
+    '$sidebar-width': '280px',
   },
 });
 ```
@@ -135,7 +132,20 @@ configure({
 });
 ```
 
-Every component using `#primary`, `2x`, or `1r` adjusts automatically. Tokens are injected as `:root` CSS custom properties when the first style is rendered. You can also use standard CSS color values such as `rgb(...)`, `hsl(...)`, and named colors directly; `okhsl(...)` is the recommended choice when you want authored colors that stay aligned with Tasty's design-system-oriented workflow.
+Tokens are injected as `:root` CSS custom properties when the first style is rendered, and every component using `#primary` follows them. You can also use standard CSS color values such as `rgb(...)`, `hsl(...)`, and named colors directly; the built-in `okhsl(...)` and `okhst(...)` functions are the recommended choice when you want authored colors that stay aligned with Tasty's design-system-oriented workflow.
+
+Units work differently: `x`, `r`, `cr`, `bw`, and `ow` compile to plain values when styles are generated (`2x` → `16px` with the default `8px` step), so setting a `$gap` token does not change them. Change the scale with `configure({ units })`:
+
+```tsx
+configure({
+  units: {
+    x: '4px', // spacing step: 2x → 8px
+    r: '8px', // radius: 1r → 8px
+  },
+});
+```
+
+When the scale has to change at runtime, for example per theme or density, point the unit at a custom property and define that property as a token. With `units: { x: 'var(--gap)' }` and `tokens: { $gap: '8px' }`, `2x` compiles to `calc(2 * var(--gap))`. See [Built-in Units](dsl.md#built-in-units) for the defaults.
 
 > **Note:** `configure({ replaceTokens })` is a separate mechanism — it replaces tokens with literal values at parse time (baked into CSS). Use it for value aliases like `$card-padding: '4x'` that should be resolved during style generation, not for defining color or unit values. See [Configuration — Replace Tokens](configuration.md#replace-tokens-parse-time-substitution) for details.
 
@@ -145,7 +155,7 @@ See [Configuration](configuration.md) for the full `configure()` API — tokens,
 
 ## ESLint plugin
 
-The ESLint plugin catches invalid style properties, bad token references, malformed state keys, and other mistakes at lint time — before they reach the browser.
+The ESLint plugin catches invalid style properties, bad token references, malformed state keys, and other mistakes at lint time — before they reach the browser. It checks style objects and JSX style props alike, and runs under both ESLint 9+ and oxlint.
 
 ### Install
 
@@ -167,36 +177,80 @@ export default [
 ];
 ```
 
-### What `recommended` catches
+### Tell it about your design system
+
+Without project configuration the plugin checks syntax and property names, but it cannot know which tokens, presets, or recipes exist. Add a `tasty.config.ts` at the project root to enable those checks for the names your `configure()` call defines:
+
+```ts
+// tasty.config.ts
+export default {
+  tokens: ['#primary', '#surface', '#text', '$sidebar-width'],
+  states: ['@mobile', '@dark'],
+  presets: ['h1', 'h2', 't1', 't2'],
+  recipes: ['card'],
+  importSources: ['@my-org/ui'], // modules that re-export tasty()
+};
+```
 
-The `recommended` config covers common correctness and style issues:
+Every list is optional; leaving one out skips that check. `importSources` matters when your design system re-exports `tasty()` from its own module: the plugin only lints calls whose import it can trace.
 
-| Category            | Rules                                                                                                  | Examples                                                              |
-| ------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
-| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage                    |
-| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax                        |
-| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists               |
-| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                                |
-| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`                    |
-| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax          |
-| Motion guidance     | `no-raw-transition-duration`                                                                           | Suggests timing tokens or the default timing for transition durations |
-| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                         | Warns on JavaScript values and spreads inside runtime style objects   |
+### What `recommended` catches
+
+| Category            | Rules                                                                                                  | Examples                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage                       |
+| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax                           |
+| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists                  |
+| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                                   |
+| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`                       |
+| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax             |
+| Token usage         | `no-raw-color-values`, `consistent-token-usage`, `no-raw-transition-duration`                          | Suggests `#color` tokens over raw colors, units over raw pixel lengths   |
+| Preferred syntax    | `prefer-shorthand-property`, `prefer-auto-calc`, `prefer-hide`, `prefer-state-negation`, and others    | Suggests `fill` over `backgroundColor`, `(...)` over `calc(...)`         |
+| Component props     | `no-style-prop`, `no-classname-prop`, `no-styles-prop`                                                 | Points escape hatches toward `tokens`, `mods`, and the component's props |
+| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                        | Warns on JavaScript values and spreads inside runtime style objects      |
 
 ### Strict config
 
-For stricter governance, use `tasty.configs.strict`. It adds rules that flag direct `styles` prop usage and other patterns:
+For stricter governance, use `tasty.configs.strict`. It adds existence checks for `$` custom properties and `@` state aliases, and validates state definitions in `configure()` and `tasty.config.ts`:
 
 ```js
 export default [tasty.configs.strict];
 ```
 
+See the [plugin README](https://github.com/tenphi/eslint-plugin-tasty) for every rule, the oxlint setup, and the experimental type-aware mode for JSX props.
+
+---
+
+## TypeScript autocomplete
+
+Component props are typed from their definitions without extra setup: `modProps` value lists become unions, `variant` is typed from the variant keys, and sub-elements are typed components. To get autocomplete for your own token, preset, and theme names inside style values, register them with module augmentation:
+
+```ts
+// tasty.d.ts
+import '@tenphi/tasty';
+
+declare module '@tenphi/tasty' {
+  interface TastyNamedColors {
+    primary: true;
+    surface: true;
+    text: true;
+  }
+  interface TastyPresetNames {
+    h1: true;
+    t2: true;
+  }
+}
+```
+
+See [Configuration → TypeScript](configuration.md#typescript) for every augmentation interface and how component props are typed.
+
 ---
 
 ## Editor support
 
-**[VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)** — Syntax highlighting for Tasty styles in TypeScript/TSX/JavaScript/JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()` and `tastyStatic()` calls. Install from the VS Code marketplace or from a `.vsix` file.
+**[VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)** — Syntax highlighting for Tasty styles in TypeScript/TSX/JavaScript/JSX: color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, `styles` objects, and style functions. It also adds snippets for components, state maps, and `configure()`. Install the `.vsix` from the [latest GitHub release](https://github.com/tenphi/tasty-vscode-extension/releases/latest); the extension is not published to the marketplace.
 
-**[Glaze](https://github.com/tenphi/glaze)** — OKHSL-based color theme generator with automatic WCAG contrast solving. Generate light, dark, and high-contrast color palettes from a single hue and export them directly as Tasty color tokens. See the [Ecosystem section](../README.md#ecosystem) in the README.
+**[Glaze](https://github.com/tenphi/glaze)** — Not an editor tool, but the fastest way to fill `configure({ tokens })`: it generates light, dark, and high-contrast palettes from one hue in the OKHST color space, solves WCAG and APCA contrast, and exports them as Tasty tokens with `configure({ tokens: theme.tasty() })`. See [Glaze in the README](../README.md#glaze).
 
 ---
 
@@ -228,6 +282,7 @@ Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state
 - **[Adoption Guide](adoption.md)** — Roll out Tasty inside an existing design system or platform team
 - **[Comparison](comparison.md)** — Evaluate Tasty against other styling systems
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Plugins & Extension Points](plugins.md)** — Add your own style properties, units, functions, and component props
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[Debug Utilities](debug.md)** — Inspect generated CSS and debug runtime behavior when styles do not look right
 
@@ -237,4 +292,6 @@ Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state
 
 - Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
 - Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](debug.md).
+- Changing a `$gap` or `$radius` token does not change `2x` or `1r`: units compile to plain values from `configure({ units })`. Point a unit at the custom property (`units: { x: 'var(--gap)' }`) if it should follow the token.
+- The linter accepts unknown tokens or presets: list them in `tasty.config.ts` so the plugin knows what your design system defines.
 - You need zero-runtime delivery: use server-only [`tasty()` with server rendering](ssr.md) to keep the full React API, or use [`tastyStatic()` build-time extraction](tasty-static.md) when styles must be compiled before rendering.