@tenphi/tasty 0.0.0-snapshot.1d29633 → 0.0.0-snapshot.1f1c00a

package/docs/ai-agents.md

@@ -16,12 +16,18 @@ Color tokens (`#name`), custom properties (`$name`), `preset` names, `recipe` na
 const Card = tasty({ as: 'div', styles: { … }, styleProps: ['padding'] }); // new component
 const Hero = tasty(Card, { styles: { … } });                              // extend a component
 const cls = useStyles({ … });                                             // ad-hoc class name
-tastyStatic('.card', { … });                                              // build-time, zero runtime
+tastyStatic('.card', { … });                                              // build-time extraction
 ```
 
 - Wrap, don't pass styles per instance: ❌ `<Box styles={{ padding: '2x' }} />` → ✅ `const Box = tasty({ styles: { padding: '2x' } })`.
 - Style values are **static**. Route anything conditional through a state map plus `mods` (or `tokens` / `styleProps`):
   ❌ `fill: isOpen ? '#primary' : '#surface'` → ✅ `fill: { '': '#surface', open: '#primary' }` with `mods={{ open: isOpen }}`.
+- Keep JavaScript identifiers, calls, computed keys, and interpolated templates
+  out of style values. Use token references inside strings for values supplied
+  at runtime. Spell out style properties rather than spreading objects; if a
+  runtime spread is unavoidable, add a
+  `// eslint-disable-next-line tasty/no-style-spread -- reason` comment directly
+  above it. `tastyStatic()` cannot use spreads.
 
 ## 2. Property names
 
@@ -29,26 +35,28 @@ Keys are camelCase — a Tasty property or a real CSS property. No kebab-case, n
 
 Prefer the Tasty shorthand over its CSS equivalents:
 
-| Use | Instead of |
-|-----|------------|
-| `fill` | `backgroundColor`, `background` |
-| `image` | `backgroundImage` |
-| `border` | `borderColor`, `borderWidth`, `borderStyle`, `borderTop`/`Right`/`Bottom`/`Left` |
-| `radius` | `borderRadius` |
-| `outline` | `outlineColor`, `outlineWidth`, `outlineStyle`, `outlineOffset` |
-| `shadow` | `boxShadow` |
-| `padding` | `paddingTop`/`Right`/`Bottom`/`Left` |
-| `margin` | `marginTop`/`Right`/`Bottom`/`Left` |
-| `inset` | `top`, `right`, `bottom`, `left` |
-| `width` / `height` | `minWidth`/`maxWidth`, `minHeight`/`maxHeight` |
-| `flow` | `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow` |
-| `preset` | `fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform` |
-| `font` | `fontFamily` |
-| `scrollbar` | `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter` |
-| `gridColumns` / `gridRows` / `gridAreas` | `gridTemplateColumns` / `Rows` / `Areas` |
-| `textOverflow: 'ellipsis / 3'` | `lineClamp` |
-| `hide: true` | `display: 'none'` |
-| `flexGrow` / `flexShrink` / `flexBasis` | `flex` |
+| Use                                      | Instead of                                                                            |
+| ---------------------------------------- | ------------------------------------------------------------------------------------- |
+| `fill`                                   | `backgroundColor`, `background`                                                       |
+| `image`                                  | `backgroundImage`                                                                     |
+| `border`                                 | `borderColor`, `borderWidth`, `borderStyle`, `borderTop`/`Right`/`Bottom`/`Left`      |
+| `radius`                                 | `borderRadius`                                                                        |
+| `outline`                                | `outlineColor`, `outlineWidth`, `outlineStyle`, `outlineOffset`                       |
+| `shadow`                                 | `boxShadow`                                                                           |
+| `padding`                                | `paddingTop`/`Right`/`Bottom`/`Left`                                                  |
+| `margin`                                 | `marginTop`/`Right`/`Bottom`/`Left`                                                   |
+| `inset`                                  | `top`, `right`, `bottom`, `left`                                                      |
+| `width` / `height`                       | `minWidth`/`maxWidth`, `minHeight`/`maxHeight`                                        |
+| `flow`                                   | `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow`                               |
+| `preset`                                 | `fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform` |
+| `font`                                   | `fontFamily`                                                                          |
+| `scrollbar`                              | `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter`                                 |
+| `gridColumns` / `gridRows` / `gridAreas` | `gridTemplateColumns` / `Rows` / `Areas`                                              |
+| `textOverflow: 'ellipsis / 3'`           | `lineClamp`                                                                           |
+| `hide: true`                             | `display: 'none'`                                                                     |
+| `flexGrow` / `flexShrink` / `flexBasis`  | `flex`                                                                                |
+
+Use logical category styles when layout must follow writing mode or direction: `blockSize`/`inlineSize`, `blockPadding`/`inlinePadding`, `blockMargin`/`inlineMargin`, `blockInset`/`inlineInset`, `blockScrollMargin`/`inlineScrollMargin`, `blockScrollPadding`/`inlineScrollPadding`, and `blockBorder`/`inlineBorder`. Use `start`/`end` value modifiers; do not replace them with physical sides. Native logical CSS properties remain valid as ordinary keys when an individual declaration is needed.
 
 The last row goes the other way — longhands over the shorthand — because `flex` is lossy: it resets the components you omit to non-initial values (`flex: '0'` silently sets `flex-basis: 0%`) and cannot express `flexShrink: 0` at all. The longhands also carry separate state maps.
 
@@ -56,23 +64,23 @@ The last row goes the other way — longhands over the shorthand — because `fl
 
 ### Tokens
 
-| Syntax | Meaning |
-|--------|---------|
-| `#name` | color token → `var(--name-color)` |
-| `#name.50` | token at 50% opacity (`0`–`100`) |
-| `#name.$opacity` | opacity from a custom property |
-| `#clear` / `#current` | `transparent` / `currentcolor` |
-| `$name` | custom property → `var(--name)` |
-| `(#a, #b)` | fallback chain |
-| `$$name` / `##name` | the custom property *name* (not its value) — inside `transition` |
-| `$$name(…)` | call a CSS `@function` declared via `@function`, `useFunction`, or config |
+| Syntax                | Meaning                                                                   |
+| --------------------- | ------------------------------------------------------------------------- |
+| `#name`               | color token → `var(--name-color)`                                         |
+| `#name.50`            | token at 50% opacity (`0`–`100`)                                          |
+| `#name.$opacity`      | opacity from a custom property                                            |
+| `#clear` / `#current` | `transparent` / `currentcolor`                                            |
+| `$name`               | custom property → `var(--name)`                                           |
+| `(#a, #b)`            | fallback chain                                                            |
+| `$$name` / `##name`   | the custom property _name_ (not its value) — inside `transition`          |
+| `$$name(…)`           | call a CSS `@function` declared via `@function`, `useFunction`, or config |
 
 - ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
 - ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
 - A `$name` must be declared as a `'$name': value` key in the same styles object, or in the config.
 - Names are case-sensitive and start lowercase — `$myVar` → `--myVar`; a leading capital folds (`$Foo` → `--foo`). Prefer kebab-case.
 - A `$name` reference is untyped: it fills the first free slot in a shorthand (`border: '1bw $my-style'` → the line style). Write colors as `#name`; `$name-color` is a fallback for pointing at a raw CSS custom property that holds a color.
-- `preset` and `transition` take token *names*, not values, so a `$name` cannot stand in for one (it warns in dev and is ignored).
+- `preset` and `transition` take token _names_, not values, so a `$name` cannot stand in for one (it warns in dev and is ignored).
 
 ### Units
 
@@ -86,7 +94,7 @@ Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'
 
 ### `true`
 
-`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `scrollMargin`, `scrollPadding`, and the enhanced logical category styles listed above, plus `hide`. Anywhere else it is an error.
 
 ### `!important`
 
@@ -96,51 +104,65 @@ Never use it. Tasty owns specificity through doubled selectors and state orderin
 
 A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). A group that names **direction** modifiers takes a **single** value, applied to every direction it names — per-side values come from comma groups. A group naming no direction keeps plain CSS shorthand order (1–4 values). (`inset` + `dock` is the one exception: a second value insets the spanned sides.) Only the modifiers a property knows are valid:
 
-| Property | Modifiers |
-|----------|-----------|
-| `padding`, `margin`, `inset`, `fade` | `top` `right` `bottom` `left` |
-| `border` | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden` |
-| `outline` | the style keywords above |
-| `radius` | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf` |
-| `width`, `height` | `min` `max` `fixed` |
-| `flow` | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense` |
-| `overflow` | `visible` `hidden` `scroll` `clip` `auto` `overlay` |
-| `position` | `static` `relative` `absolute` `fixed` `sticky` |
-| `shadow` | `inset` |
-| `preset` | `name / strong` (or `bold`) `italic` `icon` `tight` |
-| box properties | `longhand` — emit CSS longhands instead of the shorthand |
+| Property                             | Modifiers                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `padding`, `margin`, `inset`, `fade` | `top` `right` `bottom` `left`                                                                              |
+| `border`                             | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden` |
+| logical axis spacing/inset styles    | `start` `end`                                                                                              |
+| `blockBorder`, `inlineBorder`         | `start` `end` + the border style keywords above                                                            |
+| `outline`                            | the style keywords above                                                                                   |
+| `radius`                             | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf`                                 |
+| `width`, `height`, `blockSize`, `inlineSize` | `min` `max` `fixed`                                                                                |
+| `flow`                               | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense`                                      |
+| `overflow`                           | `visible` `hidden` `scroll` `clip` `auto` `overlay`                                                        |
+| `position`                           | `static` `relative` `absolute` `fixed` `sticky`                                                            |
+| `shadow`                             | `inset`                                                                                                    |
+| `preset`                             | `name / strong` (or `bold`) `italic` `icon` `tight`                                                        |
+| box properties                       | `longhand` — emit CSS longhands instead of the shorthand                                                   |
 
 Directional modifiers beat placeholder zeros:
 
 - ❌ `padding: '0 0 2x 0'` → ✅ `padding: '2x bottom'`
 - ❌ `padding: '1x 1x 2x 1x'` → ✅ `padding: '1x, 2x bottom'`
-- ❌ `border: '0 0 1bw 0'` — four tokens parse as *one* border value, so this renders no border at all → ✅ `border: '1bw bottom'`
+- ❌ `border: '0 0 1bw 0'` — four tokens parse as _one_ border value, so this renders no border at all → ✅ `border: '1bw bottom'`
 - ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
 - ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
 
-Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, `tabSize`, `paddingInline`, `paddingBlock`. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
 
 ### `transition`
 
 Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
 
-❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill'`
+
+Omit the duration to use `$fill-transition` with `$transition` as fallback, or
+use a duration token explicitly (`transition: 'fill $transition'`). Avoid raw
+time values in duration slots. An explicit zero can be useful to disable motion.
+
+Use `transition` when defining a complete transition, and the native CSS
+`animation` shorthand when defining a complete animation. Tasty accepts
+`animation` directly and tracks local keyframes referenced by it; no special
+animation handler is needed. Use duration tokens in either form. Keep
+`transitionDuration`, `animationDuration`, and other motion longhands when a
+state or extension changes only one part of an existing effect. A shorthand
+resets omitted parts, including an animation's timeline and range.
 
 ## 4. State maps
 
 A property value can be an object of `state: value`. Key order is priority — later keys win.
 
-| Key | Generated selector |
-|-----|--------------------|
-| `hovered` | `[data-hovered]` (boolean modifier from `mods`) |
-| `theme=danger` | `[data-theme="danger"]` (value modifier) |
-| `:hover` | pseudo-class |
-| `.active` | class selector |
-| `[aria-expanded="true"]` | attribute selector |
-| `hovered & .active` | AND |
-| `hovered \| focused` | OR (`,` also means OR) |
-| `!disabled` | NOT |
-| `hovered ^ focused` | XOR — exactly one (keep chains ≤ 4 operands) |
+| Key                      | Generated selector                              |
+| ------------------------ | ----------------------------------------------- |
+| `hovered`                | `[data-hovered]` (boolean modifier from `mods`) |
+| `theme=danger`           | `[data-theme="danger"]` (value modifier)        |
+| `:hover`                 | pseudo-class                                    |
+| `.active`                | class selector                                  |
+| `[aria-expanded="true"]` | attribute selector                              |
+| `hovered & .active`      | AND                                             |
+| `hovered \| focused`     | OR (`,` also means OR)                          |
+| `!disabled`              | NOT                                             |
+| `hovered ^ focused`      | XOR — exactly one (keep chains ≤ 4 operands)    |
 
 Precedence `!` > `^` > `|` > `&`; use parentheses to override.
 
@@ -148,9 +170,11 @@ Rules:
 
 1. **`''` comes first.** The bare default is the lowest-priority state; placing it later would override everything above it.
 2. **Every state map needs `''` or `_`** — except when extending (`tasty(Parent, …)`), where omitting `''` merges into the parent's states and including `''` replaces them wholesale.
-3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be *unknown* (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
+3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be _unknown_ (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
 4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
 5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
+6. **Write keys Tasty can fully read.** Names start with a letter (a single letter is fine: `x` → `[data-x]`); join states with an operator (`hovered & focused`, not `hovered focused`); no space between `@media` and `(`. Tasty warns (`INVALID_STATE_KEY`) and skips what it cannot read.
+7. **Prefer automatic native states:** use `disabled` and `checked` in Tasty component styles instead of `[disabled]` and `[checked]`. The concise states track the corresponding native prop or attribute automatically.
 
 ```jsx
 color: { '': '#text', hovered: '#accent', disabled: '#text.40' }
@@ -158,16 +182,16 @@ color: { '': '#text', hovered: '#accent', disabled: '#text.40' }
 
 Advanced states:
 
-| Prefix | Use | Example |
-|--------|-----|---------|
-| `@media(…)` | media query; dimensions `w` `h`; types `@media:print` `:screen` `:all` `:speech` | `@media(w < 768px)`, `@media(600px <= w < 1200px)` |
-| `@(…)` | container query; dimensions `w` `h` `is` `bs` | `@(layout, w >= 600px)`, `@($variant=primary)` |
-| `@supports(…)` | feature query; `$` first argument tests a selector | `@supports(display: grid)`, `@supports($, :has(*))` |
-| `@root(…)` | condition on `:root` | `@root(schema=dark)` |
-| `@parent(…)` | condition on an ancestor; `, >` for the direct parent | `@parent(hovered, >)` |
-| `@own(…)` | a sub-element's own state — **only inside sub-element styles** | `@own(:hover)` |
-| `@starting` | `@starting-style` entry animation | `@starting` |
-| `@name` | project state alias | `@mobile` |
+| Prefix         | Use                                                                              | Example                                             |
+| -------------- | -------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `@media(…)`    | media query; dimensions `w` `h`; types `@media:print` `:screen` `:all` `:speech` | `@media(w < 768px)`, `@media(600px <= w < 1200px)`  |
+| `@(…)`         | container query; dimensions `w` `h` `is` `bs`                                    | `@(layout, w >= 600px)`, `@($variant=primary)`      |
+| `@supports(…)` | feature query; `$` first argument tests a selector                               | `@supports(display: grid)`, `@supports($, :has(*))` |
+| `@root(…)`     | condition on `:root`                                                             | `@root(schema=dark)`                                |
+| `@parent(…)`   | condition on an ancestor; `, >` for the direct parent                            | `@parent(hovered, >)`                               |
+| `@own(…)`      | a sub-element's own state — **only inside sub-element styles**                   | `@own(:hover)`                                      |
+| `@starting`    | `@starting-style` entry animation                                                | `@starting`                                         |
+| `@name`        | project state alias                                                              | `@mobile`                                           |
 
 - At root level write the selector directly: ❌ `'@own(:hover)'` → ✅ `':hover'`.
 - `@name` aliases must exist in `states` in the config or be declared locally as an `'@name': '<state expression>'` key; alias keys start with `@` and their value must be a valid state expression.
@@ -187,21 +211,23 @@ styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent'
 
 ## 6. Special top-level keys
 
-| Key | Shape |
-|-----|-------|
-| `@keyframes` | `{ name: { '0%': styles, … } }` |
-| `@property` | `{ '$name': { syntax, inherits, initialValue } }` |
-| `@font-face` | `{ 'Family Name': descriptors \| descriptors[] }` |
-| `@counter-style` | `{ name: descriptors }` |
-| `@function` | `{ '$$name': { args, returns?, result, '$local'? } }` |
-| `recipe` | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
+| Key              | Shape                                                                                                       |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `@keyframes`     | `{ name: { '0%': styles, … } }`                                                                             |
+| `@property`      | `{ '$name': { syntax, inherits, initialValue } }`                                                           |
+| `@font-face`     | `{ 'Family Name': descriptors \| descriptors[] }`                                                           |
+| `@counter-style` | `{ name: descriptors }`                                                                                     |
+| `@function`      | `{ '$$name': { args, returns?, result, '$local'? } }`                                                       |
+| `recipe`         | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
+
+`recipe` resolves on the component root and independently in each sub-element's styles: `styles: { Panel: { recipe: 'card elevated' } }` is supported. Configured recipe definitions must be flat and cannot contain their own `recipe` key; references inside recipe values are not recursively expanded. Compose names where the recipe is applied, not inside `configure({ recipes })`. See [Recipes](dsl.md#recipes).
 
 At-rule keys match the real CSS at-rule names, so they are kebab-case, not camelCase. Inside `@function`, the callable is `$$name` but its parameters and local variables are `$name`:
 
 ```jsx
 styles: {
   '@function': { $$negative: { args: ['$value'], result: '(-1 * $value)' } },
-  marginTop: '$$negative(2x)',
+  margin: '$$negative(2x) top',
 }
 ```
 
@@ -213,6 +239,7 @@ The selector must be a string literal and valid CSS. Values must be static — s
 
 - Token, preset, recipe, unit and `@alias` names exist in the project config.
 - Tasty shorthand chosen over CSS longhands; `flexGrow`/`flexShrink`/`flexBasis` over `flex`; `hide: true` over `display: 'none'`.
+- Logical category styles keep native `block`/`inline` declarations and accept `start`/`end`, never physical direction modifiers.
 - Colors are `#tokens`, not hex/rgb/oklch/named; `$prop` not `var(--prop)`.
 - Spacing uses `x`/`r`/`bw`/`ow` units; math uses `(…)`, not `calc(…)`.
 - `true` only on the properties that accept it; no `!important`.

package/docs/comparison.md

@@ -2,9 +2,9 @@
 
 Use this guide when you are deciding whether Tasty is the right tool. If you have already decided to adopt it and need rollout guidance, use the [Adoption Guide](adoption.md) instead.
 
-Tasty is best understood not as a general-purpose CSS framework, but as a **styling engine for design systems and shared component APIs**.
+Tasty is CSS-in-JS for React design systems. It is built for the point where reusable components have enough intersecting states, variants, themes, and extension rules that ordinary selector competition becomes hard to reason about.
 
-It targets a different layer: helping design-system teams define a **house styling language** on top of CSS.
+Its distinctive guarantee is narrow and concrete: each property’s state map compiles into selectors that cannot compete, so one declared branch wins regardless of CSS source order.
 
 That does not require a big upfront configuration step. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
 
@@ -16,7 +16,7 @@ Most styling tools focus on one of these layers:
 - utility composition
 - atomic CSS generation
 
-Tasty's house styling language can include tokens, state semantics, style props, recipes, custom units, and sub-element rules. In other words, it is a governed styling model, not just another syntax for writing CSS.
+For design-system teams, that state model can sit alongside tokens, typed style props, recipes, custom units, and sub-element rules. Tasty can therefore define the styling language exposed by shared components, not just another syntax for writing CSS.
 
 That is why syntax-level comparisons are often shallow. The more meaningful comparison is about:
 
@@ -29,14 +29,14 @@ That is why syntax-level comparisons are often shallow. The more meaningful comp
 
 ## High-level positioning
 
-| System | Best described as | Main authoring model | Conflict model | RSC / zero-JS SSG | Best fit |
-|---|---|---|---|---|---|
-| **Tasty** | Design-system styling engine | Custom DSL with tokens, state maps, recipes, style props, sub-elements, custom units | **Mutually exclusive selector resolution** for stateful styles | Yes — hook-free, server components by default | Teams building shared component APIs or a house styling language |
-| **Tailwind CSS** | Utility-first styling framework | Utility classes in markup | Utility composition, variants, and framework-controlled ordering | Yes — no JS runtime | Product teams optimizing for speed and direct authoring |
-| **Panda CSS** | Typed styling engine with atomic output | Typed style objects, recipes, generated primitives, style props | Atomic CSS with static analysis | Yes — build-time extraction | Teams wanting a DS-friendly engine with typed primitives |
-| **vanilla-extract** | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition | Standard CSS semantics | Yes — build-time extraction | Teams wanting static CSS and low-level control |
-| **StyleX** | Compiler-based atomic styling system | JS authoring with compiler-generated atomic CSS | Compiler-controlled atomic composition | Yes — compiler-extracted | Large app teams wanting optimized, predictable atomic styling |
-| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS | Styled components, `css()` APIs, object/string styles | Composition within CSS-in-JS rules | No — requires `'use client'` | Teams optimizing for component DX and flexible styling |
+| System                                  | Best described as                        | Main authoring model                                                             | Conflict model                                                   | RSC / zero-JS SSG                             | Best fit                                                      |
+| --------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| **Tasty**                               | CSS-in-JS for React design systems       | CSS-like objects with state maps, tokens, recipes, style props, and sub-elements | **Mutually exclusive selector resolution** for stateful styles   | Yes — hook-free, server components by default | Teams building long-lived shared component APIs               |
+| **Tailwind CSS**                        | Utility-first styling framework          | Utility classes in markup                                                        | Utility composition, variants, and framework-controlled ordering | Yes — no JS runtime                           | Product teams optimizing for speed and direct authoring       |
+| **Panda CSS**                           | Typed styling engine with atomic output  | Typed style objects, recipes, generated primitives, style props                  | Atomic CSS with static analysis                                  | Yes — build-time extraction                   | Teams wanting a DS-friendly engine with typed primitives      |
+| **vanilla-extract**                     | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition                              | Standard CSS semantics                                           | Yes — build-time extraction                   | Teams wanting static CSS and low-level control                |
+| **StyleX**                              | Compiler-based atomic styling system     | JS authoring with compiler-generated atomic CSS                                  | Compiler-controlled atomic composition                           | Yes — compiler-extracted                      | Large app teams wanting optimized, predictable atomic styling |
+| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS                | Styled components, `css()` APIs, object/string styles                            | Composition within CSS-in-JS rules                               | No — requires `'use client'`                  | Teams optimizing for component DX and flexible styling        |
 
 ---
 
@@ -69,8 +69,12 @@ This is especially relevant for components with intersecting states such as:
 Here is a minimal example. Two CSS rules for a button's background — one for `:hover`, one for `[disabled]`:
 
 ```css
-.btn:hover    { background: dodgerblue; }
-.btn[disabled] { background: gray; }
+.btn:hover {
+  background: dodgerblue;
+}
+.btn[disabled] {
+  background: gray;
+}
 ```
 
 When the button is both hovered **and** disabled, both selectors match with equal specificity. The last rule in source order wins. Swap the two lines and the visual behavior silently reverses — a hovered disabled button turns blue instead of gray.
@@ -81,11 +85,11 @@ In Tasty, the same intent is declared as a state map:
 fill: {
   '': '#primary',
   ':hover': '#primary-hover',
-  'disabled': '#surface',
+  '[disabled]': '#surface',
 }
 ```
 
-Tasty compiles this into selectors where `disabled` is guarded by `:not(:hover)` negations (and vice versa), so exactly one rule matches regardless of source order. The outcome is defined by the state map, not by which line comes last.
+Because `[disabled]` is declared later, it has higher priority. Tasty excludes disabled buttons from the hover selector, so exactly one background rule matches. The outcome is defined by the state map, not by which CSS rule comes last.
 
 That makes Tasty less of a "better way to write CSS objects" and more of a **state-aware style compiler for design systems**.
 
@@ -131,16 +135,36 @@ To make this concrete, consider a button with `hover`, `disabled`, and `theme=da
 **Plain CSS** — you need a selector for every intersection, and equal-specificity rules depend on source order:
 
 ```css
-.btn { background: var(--primary); color: white; cursor: pointer; }
-.btn:hover { background: var(--primary-hover); }
-.btn:active { background: var(--primary-pressed); }
-.btn[disabled] { background: var(--surface); color: var(--text-40); cursor: not-allowed; }
+.btn {
+  background: var(--primary);
+  color: white;
+  cursor: pointer;
+}
+.btn:hover {
+  background: var(--primary-hover);
+}
+.btn:active {
+  background: var(--primary-pressed);
+}
+.btn[disabled] {
+  background: var(--surface);
+  color: var(--text-40);
+  cursor: not-allowed;
+}
 
 /* theme=danger overrides — must repeat disabled/hover/active */
-.btn[data-theme="danger"] { background: var(--danger); }
-.btn[data-theme="danger"]:hover { background: var(--danger-hover); }
-.btn[data-theme="danger"]:active { background: var(--danger-pressed); }
-.btn[data-theme="danger"][disabled] { background: var(--surface); }
+.btn[data-theme='danger'] {
+  background: var(--danger);
+}
+.btn[data-theme='danger']:hover {
+  background: var(--danger-hover);
+}
+.btn[data-theme='danger']:active {
+  background: var(--danger-pressed);
+}
+.btn[data-theme='danger'][disabled] {
+  background: var(--surface);
+}
 
 /* Bug: .btn:hover and .btn[disabled] have the same specificity.
    A hovered disabled button gets :hover styles — unless source order saves you. */
@@ -172,18 +196,18 @@ const Button = tasty({
       '': '#primary',
       ':hover': '#primary-hover',
       ':active': '#primary-pressed',
-      'disabled': '#surface',
+      disabled: '#surface',
       'theme=danger': '#danger',
       'theme=danger & :hover': '#danger-hover',
       'theme=danger & :active': '#danger-pressed',
     },
     color: {
       '': '#on-primary',
-      'disabled': '#text.40',
+      disabled: '#text.40',
     },
     cursor: {
       '': 'pointer',
-      'disabled': 'not-allowed',
+      disabled: 'not-allowed',
     },
   },
 });
@@ -235,12 +259,12 @@ Tasty is more opinionated.
 
 It behaves less like "TypeScript that outputs CSS" and more like a **state-aware style compiler**. It is designed to encode higher-level styling semantics rather than only expose CSS primitives in typed form.
 
-This also makes Tasty's rendering model notable:
+This also makes Tasty's delivery model notable:
 
-- `tasty()` components are hook-free and work as React Server Components. In server-only contexts (Next.js RSC, Astro without islands), they produce static HTML + CSS with zero client JavaScript — the full feature set is available without sacrificing server rendering
-- `tastyStatic()` with the Babel plugin produces static class name strings via build-time extraction, with no React dependency at runtime — the output works with any JavaScript framework
+- `tasty()` components are hook-free and work as React Server Components. In server-only contexts, they produce HTML + CSS with zero Tasty styling runtime in the browser while retaining the full React feature set. Astro without islands is the concrete integration; server-only Next.js RSC uses the same architecture.
+- `tastyStatic()` with the Babel plugin produces static class-name objects via build-time extraction, with no React dependency — the output works with any JavaScript framework.
 
-Runtime features like `styleProps`, sub-element components, and dynamic variants are available in the `tasty()` path. The `tastyStatic()` path is framework-agnostic but limited to the DSL, tokens, and state logic.
+React component features like `styleProps`, sub-element components, and dynamic variants are available in the `tasty()` path whether it renders on the server or in the browser. The `tastyStatic()` path is framework-agnostic but limited to the DSL, tokens, and state logic.
 
 So the tradeoff is roughly:
 
@@ -298,32 +322,32 @@ It is less focused on "how do I style this component ergonomically right now?" a
 - what should be allowed or constrained?
 - how do we keep style behavior deterministic as the system grows?
 
-So while Stitches and Emotion are strong tools for building components, Tasty is more naturally positioned as a **styling substrate for the design system itself**.
+So while Stitches and Emotion are strong tools for building components, Tasty is more naturally positioned as the **styling engine underneath a design system’s component API**.
 
 That makes it narrower in audience, but deeper in architectural ambition.
 
-There is also a fundamental architectural difference: Emotion and styled-components rely on React context and hooks internally, which means they require `'use client'` in modern React and cannot run as React Server Components. Tasty's style functions and `tasty()` components are hook-free, so they work as server components by default and produce zero client JavaScript in server-only contexts. This is not a minor compatibility detail — it means Tasty-based components stay as server components until *your* code needs interactivity, while Emotion and styled-components force the client boundary at the styling layer.
+There is also a fundamental architectural difference: Emotion and styled-components rely on React context and hooks internally, which means they require `'use client'` in modern React and cannot run as React Server Components. Tasty's style functions and `tasty()` components are hook-free, so they work as server components by default and ship no Tasty styling runtime in server-only contexts. This is not a minor compatibility detail — it means Tasty-based components stay as server components until _your_ code needs interactivity, while Emotion and styled-components force the client boundary at the styling layer.
 
 For teams evaluating runtime styling at scale, Tasty also documents its runtime benchmarks and caching model in the main [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
 
 ---
 
-## Build-time vs runtime
+## Where styles are computed
 
 Tasty is not limited to one execution model.
 
-The term "runtime" in `tasty()` refers to *when* style computation happens — during React rendering — not to where that rendering occurs. In server-only contexts (Next.js RSC without `'use client'`, Astro without `client:*` directives, SSG), `tasty()` components render on the server, produce static HTML + CSS, and ship **zero client JavaScript**. The full feature set — `styleProps`, sub-elements, variants, state maps — is available. The result is the same as what `tastyStatic()` produces, but without giving up any runtime capabilities.
+Zero-runtime delivery is an outcome, not a synonym for `tastyStatic()`. `tasty()` computes styles during React rendering, but that rendering can happen only on the server. In that case it produces HTML + CSS and ships **zero Tasty styling runtime** to the browser. The full feature set — `styleProps`, sub-elements, variants, state maps — remains available. Astro's `tastyIntegration({ islands: false })` is the explicit setup for this path. Server-only Next.js RSC follows the same architecture; verify the generated output for the target deployment.
 
 Client JavaScript only enters the picture when a component needs React interactivity (state, effects, event handlers) — and that is the consuming component's decision, never Tasty's. Tasty never forces the `'use client'` boundary.
 
-`tastyStatic()` with the Babel plugin is for a different scenario: when you want build-time CSS extraction **without React at runtime**. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
+`tastyStatic()` with the Babel plugin reaches zero-runtime delivery differently: CSS is extracted **during the build**, without React. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
 
 The tradeoff is that some capabilities — `styleProps`, sub-element components (`<Card.Title>`), dynamic variants — are tied to the `tasty()` path. The `tastyStatic()` path is best understood as extraction and compilation of the DSL, tokens, and state logic without a React dependency.
 
-This flexibility is one of Tasty's more unusual strengths:
+This gives Tasty two zero-runtime paths:
 
-- `tasty()` as the default for all React setups — zero client JS in server-only contexts, full feature set, SSR integration available when client hydration is needed
-- `tastyStatic()` as a static compiler whose output works with any framework, including non-React ones
+- server-only `tasty()` for the full React component API, with CSS generated during server or static rendering
+- `tastyStatic()` as a build-time compiler whose output works with any framework, including non-React ones
 
 ---
 
@@ -332,22 +356,27 @@ This flexibility is one of Tasty's more unusual strengths:
 Another useful way to think about the ecosystem is by abstraction level.
 
 ### Direct styling tools
+
 These are optimized for styling product code directly.
 
 Examples:
+
 - Tailwind CSS
 - Emotion (requires `'use client'` — not RSC-compatible)
 - Stitches (deprecated, requires `'use client'`)
 
 ### Typed styling engines
+
 These are optimized for generating CSS with stronger structure and tooling.
 
 Examples:
+
 - Panda CSS
 - vanilla-extract
 - StyleX
 
 ### Design-system language engines
+
 These are optimized for helping a team define its own styling grammar and semantics.
 
 Tasty belongs most naturally here.
@@ -364,7 +393,7 @@ Tasty makes the most sense when:
 - a shared component API is emerging even if the design system is still lightweight
 - styling should be governed through a central platform team
 - component state logic is complex
-- the team wants a house styling language instead of raw CSS-shaped authoring
+- the team wants a design-system-owned styling language instead of raw CSS-shaped authoring
 - tokens, recipes, and sub-elements should be first-class
 - deterministic state resolution matters more than minimum abstraction overhead
 - the styling engine may need to work as either a runtime tool or a build-time compiler
@@ -414,6 +443,6 @@ Tasty is most compelling when the problem is not just "how do we write styles,"
 - [React API](react-api.md) — `tasty()` factory, component props, variants, sub-elements, style functions
 - [Style Properties](styles.md) — complete reference for all enhanced style properties
 - [Configuration](configuration.md) — tokens, recipes, custom units, style handlers, and TypeScript extensions
-- [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
 - [Adoption Guide](adoption.md) — where Tasty sits in the stack, incremental adoption, and what changes for product engineers
 - [Server-Side Rendering](ssr.md) — SSR setup for Next.js, Astro, and generic frameworks