@tenphi/tasty 0.0.0-snapshot.d2dcdeb → 0.0.0-snapshot.d4ccea8

package/docs/ai-agents.md

@@ -0,0 +1,224 @@
+# Tasty Style Rules for AI Agents
+
+A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — most rules here are machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it generally means clean lint output. The plugin ships separately and can lag a new DSL rule, so treat this page as the source of truth and the plugin as the enforcement that catches most of it. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
+
+Notation: ❌ wrong → ✅ correct.
+
+---
+
+## 0. Read the project config first
+
+Color tokens (`#name`), custom properties (`$name`), `preset` names, `recipe` names, state aliases (`@mobile`) and extra units are **project-defined** in `tasty.config.ts` or a `configure({ … })` call. Look them up before writing styles. Never invent a name — reuse an existing one, or add it to the config.
+
+## 1. Where styles go
+
+```jsx
+const Card = tasty({ as: 'div', styles: { … }, styleProps: ['padding'] }); // new component
+const Hero = tasty(Card, { styles: { … } });                              // extend a component
+const cls = useStyles({ … });                                             // ad-hoc class name
+tastyStatic('.card', { … });                                              // build-time 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 }}`.
+
+## 2. Property names
+
+Keys are camelCase — a Tasty property or a real CSS property. No kebab-case, no invented names.
+
+Prefer the Tasty shorthand over its CSS equivalents:
+
+| Use                                      | Instead of                                                                            |
+| ---------------------------------------- | ------------------------------------------------------------------------------------- |
+| `fill`                                   | `backgroundColor`, `background`                                                       |
+| `image`                                  | `backgroundImage`                                                                     |
+| `border`                                 | `borderColor`, `borderWidth`, `borderStyle`, `borderTop`/`Right`/`Bottom`/`Left`      |
+| `radius`                                 | `borderRadius`                                                                        |
+| `outline`                                | `outlineColor`, `outlineWidth`, `outlineStyle`, `outlineOffset`                       |
+| `shadow`                                 | `boxShadow`                                                                           |
+| `padding`                                | `paddingTop`/`Right`/`Bottom`/`Left`                                                  |
+| `margin`                                 | `marginTop`/`Right`/`Bottom`/`Left`                                                   |
+| `inset`                                  | `top`, `right`, `bottom`, `left`                                                      |
+| `width` / `height`                       | `minWidth`/`maxWidth`, `minHeight`/`maxHeight`                                        |
+| `flow`                                   | `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow`                               |
+| `preset`                                 | `fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform` |
+| `font`                                   | `fontFamily`                                                                          |
+| `scrollbar`                              | `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter`                                 |
+| `gridColumns` / `gridRows` / `gridAreas` | `gridTemplateColumns` / `Rows` / `Areas`                                              |
+| `textOverflow: 'ellipsis / 3'`           | `lineClamp`                                                                           |
+| `hide: true`                             | `display: 'none'`                                                                     |
+| `flexGrow` / `flexShrink` / `flexBasis`  | `flex`                                                                                |
+
+The last row goes the other way — longhands over the shorthand — because `flex` is lossy: it resets the components you omit to non-initial values (`flex: '0'` silently sets `flex-basis: 0%`) and cannot express `flexShrink: 0` at all. The longhands also carry separate state maps.
+
+## 3. Values
+
+### Tokens
+
+| Syntax                | Meaning                                                                   |
+| --------------------- | ------------------------------------------------------------------------- |
+| `#name`               | color token → `var(--name-color)`                                         |
+| `#name.50`            | token at 50% opacity (`0`–`100`)                                          |
+| `#name.$opacity`      | opacity from a custom property                                            |
+| `#clear` / `#current` | `transparent` / `currentcolor`                                            |
+| `$name`               | custom property → `var(--name)`                                           |
+| `(#a, #b)`            | fallback chain                                                            |
+| `$$name` / `##name`   | the 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).
+
+### Units
+
+Tasty units: `x` (gap multiple), `r` (radius), `cr` (card radius), `bw` (border width), `ow` (outline width), `sf` (`minmax(0, Nfr)`). All CSS units work too, plus anything in `units` in the config. Any other unit is an error.
+
+Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'` → `'1r'`; `border: '1px …'` → `'1bw …'`.
+
+### Math
+
+❌ `calc(100% - 2x)` → ✅ `(100% - 2x)`. Parentheses are wrapped in `calc()` automatically — and must be balanced.
+
+### `true`
+
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+
+### `!important`
+
+Never use it. Tasty owns specificity through doubled selectors and state ordering; `!important` breaks that. Express the exception as a state instead.
+
+### Modifiers
+
+A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). 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                                                   |
+
+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'`
+- ❌ `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.
+
+### `transition`
+
+Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
+
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+
+## 4. State maps
+
+A property value can be an object of `state: value`. Key order is priority — later keys win.
+
+| Key                      | Generated selector                              |
+| ------------------------ | ----------------------------------------------- |
+| `hovered`                | `[data-hovered]` (boolean modifier from `mods`) |
+| `theme=danger`           | `[data-theme="danger"]` (value modifier)        |
+| `:hover`                 | pseudo-class                                    |
+| `.active`                | class selector                                  |
+| `[aria-expanded="true"]` | attribute selector                              |
+| `hovered & .active`      | AND                                             |
+| `hovered \| focused`     | OR (`,` also means OR)                          |
+| `!disabled`              | NOT                                             |
+| `hovered ^ focused`      | XOR — exactly one (keep chains ≤ 4 operands)    |
+
+Precedence `!` > `^` > `|` > `&`; use parentheses to override.
+
+Rules:
+
+1. **`''` comes first.** The bare default is the lowest-priority state; placing it later would override everything above it.
+2. **Every state map needs `''` or `_`** — except when extending (`tasty(Parent, …)`), where omitting `''` merges into the parent's states and including `''` replaces them wholesale.
+3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be _unknown_ (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
+4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
+5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
+6. **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' }
+```
+
+Advanced states:
+
+| Prefix         | Use                                                                              | Example                                             |
+| -------------- | -------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `@media(…)`    | media query; dimensions `w` `h`; types `@media:print` `:screen` `:all` `:speech` | `@media(w < 768px)`, `@media(600px <= w < 1200px)`  |
+| `@(…)`         | container query; dimensions `w` `h` `is` `bs`                                    | `@(layout, w >= 600px)`, `@($variant=primary)`      |
+| `@supports(…)` | feature query; `$` first argument tests a selector                               | `@supports(display: grid)`, `@supports($, :has(*))` |
+| `@root(…)`     | condition on `:root`                                                             | `@root(schema=dark)`                                |
+| `@parent(…)`   | condition on an ancestor; `, >` for the direct parent                            | `@parent(hovered, >)`                               |
+| `@own(…)`      | a sub-element's own state — **only inside sub-element styles**                   | `@own(:hover)`                                      |
+| `@starting`    | `@starting-style` entry animation                                                | `@starting`                                         |
+| `@name`        | project state alias                                                              | `@mobile`                                           |
+
+- At root level write the selector directly: ❌ `'@own(:hover)'` → ✅ `':hover'`.
+- `@name` aliases must exist in `states` in the config or be declared locally as an `'@name': '<state expression>'` key; alias keys start with `@` and their value must be a valid state expression.
+- `:is()` / `:has()` / `:not()` / `:where()` work in state keys but support at most 2 levels of nested parentheses, and `:has()` is expensive — prefer `@parent()`, `@own()` and modifiers.
+
+When extending a parent's state map: `'@inherit'` reuses the parent's value for that state, `null` removes a state (or resets a property, letting recipes fill in), `false` is a tombstone that blocks it entirely.
+
+## 5. Sub-elements
+
+A **capitalized** key targets `[data-element="Name"]`, and its value must be a style object.
+
+```jsx
+styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent' } }
+```
+
+❌ nested-selector keys (`'& .title'`, `'&:hover'`) → ✅ sub-elements and state maps. Use the `$` affix property inside a sub-element to control how its selector attaches (`>` direct child, `@` placeholder for the element itself, `&::before` for a root pseudo-element).
+
+## 6. Special top-level keys
+
+| Key              | Shape                                                                                                       |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `@keyframes`     | `{ name: { '0%': styles, … } }`                                                                             |
+| `@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'` |
+
+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)' } },
+  margin: '$$negative(2x) top',
+}
+```
+
+## 7. `tastyStatic()`
+
+The selector must be a string literal and valid CSS. Values must be static — strings, numbers, booleans, `null`, or objects/arrays of those. No variables, template literals, function calls, or spreads.
+
+## 8. Checklist
+
+- Token, preset, recipe, unit and `@alias` names exist in the project config.
+- Tasty shorthand chosen over CSS longhands; `flexGrow`/`flexShrink`/`flexBasis` over `flex`; `hide: true` over `display: 'none'`.
+- Colors are `#tokens`, not hex/rgb/oklch/named; `$prop` not `var(--prop)`.
+- Spacing uses `x`/`r`/`bw`/`ow` units; math uses `(…)`, not `calc(…)`.
+- `true` only on the properties that accept it; no `!important`.
+- Modifiers valid for the property; directional shorthand instead of placeholder zeros.
+- Every state map starts with `''` (or `_`), is flat, and lives inside a property value.
+- `@own()` only inside sub-elements; sub-element keys are capitalized and hold objects.
+- At-rule keys are kebab-case (`@property`, `@font-face`, `@counter-style`, `@function`); `@function` names use `$$`, their args and locals use `$`.
+- Values are static; dynamic behavior comes from `mods` / `tokens` / `styleProps`.

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