@tenphi/tasty 0.0.0-snapshot.89ab060 → 0.0.0-snapshot.8be165d

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">Tasty</h1>
 
 <p align="center">
-  <strong>The styling engine built for design systems.</strong><br>
-  Deterministic CSS generation. State-aware DSL. Zero specificity conflicts. Ever.
+  <strong>CSS-in-JS for React design systems.</strong><br>
+  Build components whose styles don’t fight.
 </p>
 
 <p align="center">
@@ -17,23 +17,57 @@
 
 ---
 
-Most CSS-in-JS libraries emit rules that compete through cascade and specificity. Tasty emits **mutually exclusive CSS selectors** — for any component state combination, exactly one selector matches each property at a time. No cascade conflicts, no specificity wars, no `!important` escapes. Components compose and extend without breaking each other.
+Describe hover, disabled, variants, themes, and responsive behavior as state maps. Tasty makes one branch win by design—without specificity fights or source-order surprises.
 
-That guarantee unlocks a concise, CSS-like DSL where design tokens, custom units, responsive states, container queries, sub-element styling, and theming all compose without surprises — one coherent system that scales from a single component to an enterprise design system.
+```tsx
+import { tasty } from '@tenphi/tasty';
+
+const Button = tasty({
+  as: 'button',
+  styles: {
+    fill: {
+      '': '#primary',
+      ':hover': '#primary-hover',
+      ':active': '#primary-pressed',
+      '[disabled]': '#surface',
+    },
+  },
+});
+```
+
+Later branches have higher priority. If this button is both hovered and disabled, `[disabled]` wins and the hover rule is excluded. Tasty compiles that decision into mutually exclusive selectors, so the result does not depend on CSS source order.
+
+That is the core promise: add states, variants, themes, and overrides without reopening selector logic by hand.
+
+Tasty fits best when you are building a design system or component library whose components need to stay predictable as their state logic grows. Alongside state maps, it provides a CSS-like DSL, typed style props, tokens, recipes, sub-elements, and client-side, server-only, or build-time CSS delivery.
+
+- **Ready to try it?** Follow [Getting Started](docs/getting-started.md).
+- **Evaluating fit?** Read [Comparison](docs/comparison.md) and the [Adoption Guide](docs/adoption.md).
+- **Want the compiler model?** Jump to [How It Actually Works](#how-it-actually-works).
+- **Building a component library?** See [Methodology](docs/methodology.md) and [Building a Design System](docs/design-system.md).
 
 ## Why Tasty
 
-- **Deterministic at any scale** — Exclusive selector generation eliminates the entire class of cascade/specificity bugs. Every state combination resolves to exactly one CSS rule per property. Refactor freely. See [How It Actually Works](#how-it-actually-works).
-- **AI-friendly by design** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, understand, and refactor even advanced state bindings as confidently as a human — because there's no hidden cascade logic or implicit ordering to second-guess.
-- **DSL that feels like CSS** — Property names you already know (`padding`, `color`, `display`) with syntax sugar that removes boilerplate. Learn the DSL in minutes, not days. Start with the [Style DSL](docs/dsl.md), then use [Style Properties](docs/styles.md) as the handler reference.
-- **CSS properties as normal component props** — `styleProps` lets you expose selected styles as typed React props. Use `<Button placeSelf="end">` or `<Space flow="row" gap="2x">` without extra wrappers, utility classes, or `styles` overrides. The same props also accept state maps, so responsive values work with the same API. See [CSS properties as props](#css-properties-as-props).
-- **Design-system native** — Color tokens (`#primary`), spacing units (`2x`), typography presets (`h1`, `t2`), border radius (`1r`), and recipes are first-class primitives, not afterthoughts. Built-in units and standard color values work out of the box, and [Configuration](docs/configuration.md) lets teams define shared conventions on top.
-- **Near-complete modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, `@keyframes`, etc. Some features that don't fit Tasty's component model (such as `@layer` and `!important`) are intentionally omitted, but real-world use cases are covered almost completely.
-- **Runtime, zero-runtime, or SSR — your call** — Use `tasty()` for dynamic React components with runtime injection, `tastyStatic()` with the Babel plugin for zero-runtime CSS extraction, or enable SSR with zero-cost client hydration for Next.js, Astro, or any React framework. Same DSL, same tokens, same output.
-- **Only generate what is used** — In runtime mode, Tasty injects CSS on demand for mounted components/variants, so your app avoids shipping style rules for UI states that are never rendered.
-- **Runtime performance that holds at scale** — The runtime path is tested against enterprise-scale applications and tuned with multi-level caching, chunk-level style reuse, style garbage collection, and a dedicated injector.
-- **Composable and extensible by design** — Extend any component's styles with proper merge semantics, and evolve built-in behavior through configuration and plugins.
-- **TypeScript-first** — Full type definitions, module augmentation for custom properties, and autocomplete for tokens, presets, and themes. See [Configuration](docs/configuration.md).
+- **States that don’t fight** — Each property’s state map compiles into mutually exclusive selectors, so one branch wins by construction.
+- **Safe to extend** — Add variants, overrides, and new states without re-deriving selector interactions.
+- **Built for component systems** — Model roots and sub-elements together and expose governed, typed component APIs.
+- **Your design system’s language** — Define tokens, units, aliases, recipes, style props, and parser rules for your system.
+- **One model for every state** — Pseudo-classes, modifiers, root and parent states, media and container queries, `:has()`, and `@supports` all use state maps.
+- **Client, server, or build time** — Use `tasty()` in client React, React Server Components, SSR, and static server rendering, or use `tastyStatic()` for framework-agnostic build-time extraction.
+
+### Supporting capabilities
+
+- **Typed style props and mod props** — `styleProps` exposes selected CSS properties as typed React props (`<Space flow="row" gap="2x">`); `modProps` does the same for modifier keys (`<Button isLoading size="large">`). Both support state maps and full TypeScript autocomplete. See [Style Props](#style-props) and [Mod Props](#mod-props).
+- **Zero client styling runtime with the full React API** — All `tasty()` components and style functions are hook-free. In server-only rendering, they generate CSS on the server and ship no Tasty styling runtime to the browser. Astro without islands is the concrete integration; server-only Next.js RSC follows the same architecture. Use `tastyStatic()` when you specifically need build-time extraction without React.
+- **Broad modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, `@keyframes`, `@font-face`, `@counter-style`, `@function`, and more. Features that do not fit the component model (such as `@layer` and `!important`) are intentionally left out.
+- **Performance and caching** — When styles are generated in the browser, Tasty injects CSS on demand, reuses chunks aggressively, and relies on multi-level caching so large component systems stay practical.
+- **TypeScript-first and AI-friendly** — Style definitions are declarative, structurally consistent, and fully typed, which helps both humans and tooling understand advanced stateful styles without hidden cascade logic.
+
+## Why State Maps Matter
+
+Component styling becomes fragile when multiple selectors can win for the same property. Hover, disabled, theme, breakpoint, parent state, and root state rules start competing through specificity and source order.
+
+Tasty replaces that competition with explicit priority in the state map. Each property compiles into mutually exclusive branches, so only one generated selector can match. For the full mechanism, jump to [How It Actually Works](#how-it-actually-works).
 
 ## Installation
 
@@ -56,20 +90,15 @@ yarn add @tenphi/tasty
 
 ## Start Here
 
+For the fuller docs map beyond the quick routes above, start here:
+
+- **[Comparison](docs/comparison.md)** — read this first if you are evaluating whether Tasty fits your team's styling model
+- **[Adoption Guide](docs/adoption.md)** — understand who Tasty is for, where it fits, and how to introduce it incrementally
 - **[Getting Started](docs/getting-started.md)** — the canonical onboarding path: install, first component, optional shared `configure()`, ESLint, editor tooling, and rendering mode selection
-- **[Docs Hub](docs/README.md)** — choose docs by role and task: runtime, zero-runtime, SSR, design-system authoring, internals, and debugging
+- **[Style rendering pipeline](docs/pipeline.md)** — see the selector model behind deterministic style resolution
+- **[Docs Hub](docs/README.md)** — choose docs by role and task: React rendering, zero-client-runtime delivery, build-time extraction, design-system authoring, internals, and debugging
 - **[Methodology](docs/methodology.md)** — the recommended component model and public API conventions for design-system code
 
-## Choose a Rendering Mode
-
-| Mode | Entry point | Best for | Trade-off |
-|------|-------------|----------|-----------|
-| **Runtime** | `@tenphi/tasty` | Interactive apps and design systems | Full feature set; CSS is generated on demand at runtime |
-| **Zero-runtime** | `@tenphi/tasty/static` | Static sites, SSG, landing pages | Requires the Babel plugin; no component-level `styleProps` or runtime-only APIs |
-| **SSR** | `@tenphi/tasty/ssr/*` | Next.js, Astro, and other streaming React SSR setups | Uses runtime `tasty()` with server-collected CSS and hydration cache transfer |
-
-All three share the same DSL, tokens, units, and state mappings. See [Getting Started](docs/getting-started.md#choosing-a-rendering-mode), [Zero Runtime](docs/tasty-static.md), and [Server-Side Rendering](docs/ssr.md).
-
 ## Quick Start
 
 ### Create a styled component
@@ -82,20 +111,22 @@ const Card = tasty({
   styles: {
     display: 'flex',
     flow: 'column',
-    padding: '4x',
-    gap: '2x',
-    fill: 'okhsl(98% 0.02 255)',
-    color: 'okhsl(28% 0.03 255)',
-    border: '1bw solid okhsl(88% 0.02 255)',
-    radius: '1r',
+    padding: '24px',
+    gap: '12px',
+    fill: 'white',
+    color: '#222',
+    border: '1px solid #ddd',
+    radius: '12px',
   },
 });
 
 // Just a React component
-<Card>Hello World</Card>
+<Card>Hello World</Card>;
 ```
 
-Every value maps to CSS you'd recognize. This example is intentionally config-free: built-in units work immediately, and standard color values such as `rgb(...)`, `hsl(...)`, named colors, and `okhsl(...)` are all valid without setup. `okhsl(...)` is the recommended choice when you want a design-system-friendly color authoring path from day one.
+Every value maps to CSS you'd recognize. This example is intentionally a simple first contact, not a tour of the whole DSL.
+
+When you want a more design-system-shaped authoring model, Tasty also supports built-in units, tokens, recipes, state aliases, and color values such as `okhsl(...)` without extra runtime libraries.
 
 Use `configure()` when you want to define shared tokens, state aliases, recipes, or other conventions for your app or design system. For a fuller onboarding path, follow [Getting Started](docs/getting-started.md).
 
@@ -110,22 +141,22 @@ const Button = tasty({
       '': '#primary',
       ':hover': '#primary-hover',
       ':active': '#primary-pressed',
-      '[disabled]': '#surface',
+      disabled: '#surface',
     },
     color: {
       '': '#on-primary',
-      '[disabled]': '#text.40',
+      disabled: '#text.40',
     },
     cursor: {
       '': 'pointer',
-      '[disabled]': 'not-allowed',
+      disabled: 'not-allowed',
     },
     transition: 'theme',
   },
 });
 ```
 
-State keys support pseudo-classes first (`:hover`, `:active`), then modifiers (`theme=danger`), attributes (`[disabled]`), media/container queries, root states, and more. Tasty compiles them into exclusive selectors automatically.
+State keys support pseudo-classes (`:hover`, `:active`), modifiers (`theme=danger`), attributes, media/container queries, root states, and more. The built-in `disabled` and `checked` states automatically track their corresponding native props or attributes; `disabled` is the concise Tasty form of `[disabled]`. Tasty compiles state maps into exclusive selectors automatically.
 
 ### Extend any component
 
@@ -153,7 +184,8 @@ configure({
   states: {
     '@mobile': '@media(w < 768px)',
     '@tablet': '@media(w < 1024px)',
-    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
+    '@dark':
+      '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
   },
   recipes: {
     card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
@@ -163,79 +195,60 @@ configure({
 
 Use `configure()` once when your app or design system needs shared aliases, tokens, recipes, or parser extensions. Predefined states turn complex selector logic into single tokens, so teams can write `@mobile` instead of repeating media query expressions in every component.
 
-### CSS properties as props
+### Props as the public API
 
-With `styleProps`, a component can expose the styles you choose as normal typed props. That means you can adjust layout, spacing, alignment, or positioning right where the component is used, instead of introducing wrapper elements or reaching for a separate styling API.
-
-This is especially good for prototyping and fast UI iteration: you can shape interfaces quickly, while still staying inside a typed, design-system-aware component API that scales to production.
-
-```tsx
-import { tasty, FLOW_STYLES, POSITION_STYLES } from '@tenphi/tasty';
-
-const Space = tasty({
-  styles: {
-    display: 'flex',
-    flow: 'column',
-    gap: '1x',
-  },
-  styleProps: FLOW_STYLES,
-});
-
-const Button = tasty({
-  as: 'button',
-  styles: {
-    padding: '1.5x 3x',
-    fill: '#primary',
-    color: '#primary-text',
-    radius: true,
-  },
-  styleProps: POSITION_STYLES,
-});
-```
-
-Now you can compose layout and tweak component positioning directly in JSX:
+`styleProps` exposes selected CSS properties as typed React props, and `modProps` does the same for modifier keys. Together they let design systems define a governed, typed component API without wrapper elements or `styles` overrides:
 
 ```tsx
 <Space flow="row" gap="2x" placeItems="center">
-  <Title>Dashboard</Title>
-  <Button placeSelf="end">Add Item</Button>
+  <Button isLoading size="large" placeSelf="end">
+    Submit
+  </Button>
 </Space>
 ```
 
-The same props also support state maps, so responsive values use the exact same API:
+See [Style Props](#style-props) and [Mod Props](#mod-props) below, or the full reference in [React API](docs/react-api.md#style-props).
 
-```tsx
-<Space
-  flow={{ '': 'column', '@tablet': 'row' }}
-  gap={{ '': '2x', '@tablet': '4x' }}
->
-  <Sidebar />
-  <Content />
-</Space>
-```
+## Choose a Styling Approach
+
+Once you understand the component model, choose where Tasty should generate CSS. Zero-runtime delivery is an outcome, not a synonym for `tastyStatic()`.
 
-Layout components can expose flow props. Buttons can expose positioning props. Each component can offer only the style props that make sense for its role, while still keeping tokens, custom units, and state maps fully typed. This works in runtime `tasty()` components, not in `tastyStatic()`.
+| Approach                  | Authoring API                               | CSS is generated                    | Tasty runtime in the browser | Best for                                                            |
+| ------------------------- | ------------------------------------------- | ----------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| **Server-only React**     | `tasty()`; optional `@tenphi/tasty/ssr/*`   | During server or static rendering   | None                         | Astro without islands, server-only RSC, SSG                         |
+| **Hydrated React**        | `tasty()` plus `@tenphi/tasty/ssr/*`        | During SSR, then on demand in React | Only in hydrated components  | Interactive React apps, Next.js client components, Astro islands    |
+| **Build-time extraction** | `tastyStatic()` from `@tenphi/tasty/static` | During the build                    | None in file mode            | Non-React frameworks or CSS that must be extracted before rendering |
+
+The first approach and `tastyStatic()`'s default file mode both ship zero Tasty styling runtime to the browser. The difference is authoring and timing: server-only `tasty()` retains `styleProps`, sub-elements, variants, and the rest of the React API, while `tastyStatic()` extracts build-time-known styles without a React dependency. (`tastyStatic()` inject mode intentionally ships a tiny CSS injector.) Astro supports the server-only path directly with `tastyIntegration({ islands: false })`; the same server-only model applies to Next.js RSC, though you should verify the output for your deployment. See [Getting Started](docs/getting-started.md#choosing-a-rendering-mode), [Build-Time Extraction](docs/tasty-static.md), and [Server-Side Rendering](docs/ssr.md).
 
 ## How It Actually Works
 
 This is the core idea that makes everything else possible.
 
-For the end-to-end architecture — parsing state keys, building exclusive conditions, merging by output, and materializing selectors and at-rules — see **[Style rendering pipeline](docs/PIPELINE.md)**.
+For the end-to-end architecture — parsing state keys, building exclusive conditions, merging by output, and materializing selectors and at-rules — see **[Style rendering pipeline](docs/pipeline.md)**.
 
-Traditional CSS has two structural problems.
+### The structural problem with normal CSS
 
 First, the **cascade** resolves conflicts by specificity and source order: when multiple selectors match, the one with the highest specificity wins, or — if specificity is equal — the last one in source order wins. That makes styles inherently fragile. Reordering imports, adding a media query, or composing components from different libraries can silently break styling.
 
 A small example makes this tangible. Two rules for a button's background:
 
 ```css
-.btn:hover     { background: dodgerblue; }
-.btn[disabled] { background: gray; }
+.btn:hover {
+  background: dodgerblue;
+}
+.btn[disabled] {
+  background: gray;
+}
 ```
 
-Both selectors have specificity `(0, 1, 1)`. When the button is hovered **and** disabled, both match — and the last rule in source order wins. Swap the two lines and a hovered disabled button silently turns blue instead of gray. This class of bug is invisible in code review because the logic is correct; only the ordering is wrong.
+Both selectors have specificity `(0, 2, 0)`. When the button is hovered **and** disabled, both match — and the last rule in source order wins. Swap the two lines and a hovered disabled button silently turns blue instead of gray. This class of bug is invisible in code review because the logic is correct; only the ordering is wrong.
+
+### Why real state logic is hard to author by hand
+
+Authoring selectors that capture real-world state logic is fundamentally hard. A single state like "dark mode" may depend on a root attribute, an OS preference, or both — each branch needing its own selector, proper negation of competing branches, and correct `@media` nesting. The example below shows the CSS you'd write by hand for just _one_ property with _one_ state. Scale that across dozens of properties, then add breakpoints and container queries, and the selector logic quickly becomes unmanageable.
 
-Second, **authoring selectors that capture real-world state logic is fundamentally hard.** A single state like "dark mode" may depend on a root attribute, an OS preference, or both — each branch needing its own selector, proper negation of competing branches, and correct `@media` nesting. The example below shows the CSS you'd write by hand for just *one* property with *one* state. Scale that across dozens of properties, then add breakpoints and container queries, and the selector logic quickly becomes unmanageable.
+### What Tasty generates instead
 
 Tasty solves both problems at once: **every state mapping compiles into mutually exclusive selectors.**
 
@@ -258,10 +271,16 @@ If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-col
 
 ```css
 /* First attempt — the @media branch is too broad */
-.t0 { color: var(--text-color); }
-:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+.t0 {
+  color: var(--text-color);
+}
+:root[data-schema='dark'] .t0 {
+  color: var(--text-on-dark-color);
+}
 @media (prefers-color-scheme: dark) {
-  .t0 { color: var(--text-on-dark-color); }
+  .t0 {
+    color: var(--text-on-dark-color);
+  }
 }
 ```
 
@@ -269,22 +288,26 @@ The `@media` branch fires even when `data-schema="light"` is explicitly set. Fix
 
 ```css
 /* Second attempt — @media is scoped, but the default is still too broad */
-.t0 { color: var(--text-color); }
-:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+.t0 {
+  color: var(--text-color);
+}
+:root[data-schema='dark'] .t0 {
+  color: var(--text-on-dark-color);
+}
 @media (prefers-color-scheme: dark) {
-  :root:not([data-schema]) .t0 { color: var(--text-on-dark-color); }
+  :root:not([data-schema]) .t0 {
+    color: var(--text-on-dark-color);
+  }
 }
 ```
 
 Better — but the bare `.t0` default still matches unconditionally. It matches in dark mode, it matches when `data-schema="dark"` is set, and it can beat the attribute selector by source order if another rule re-declares it later. There is no selector that says "apply this default only when none of the dark branches win."
 
-This is just *one* property with *one* state, and getting it right already takes multiple iterations. The correct selectors require negating every other branch — which is exactly what Tasty generates automatically:
-
-Tasty generates the correct version automatically:
+This is just _one_ property with _one_ state, and getting it right already takes multiple iterations. The correct selectors require negating every other branch — which is exactly what Tasty generates automatically:
 
 ```css
 /* Branch 1: Explicit dark schema */
-:root[data-schema="dark"] .t0.t0 {
+:root[data-schema='dark'] .t0.t0 {
   color: var(--text-on-dark-color);
 }
 
@@ -297,22 +320,24 @@ Tasty generates the correct version automatically:
 
 /* Default: no schema + OS does not prefer dark */
 @media (not (prefers-color-scheme: dark)) {
-  :root:not([data-schema="dark"]) .t0.t0 {
+  :root:not([data-schema='dark']) .t0.t0 {
     color: var(--text-color);
   }
 }
 
 /* Default: schema is set but not dark (any OS preference) */
-:root:not([data-schema="dark"])[data-schema] .t0.t0 {
+:root:not([data-schema='dark'])[data-schema] .t0.t0 {
   color: var(--text-color);
 }
 ```
 
+### What guarantee that gives you
+
 Every rule is guarded by the negation of higher-priority rules. No two rules can match at the same time. No specificity arithmetic. No source-order dependence. Components compose and extend without collisions.
 
-By absorbing selector complexity, Tasty makes advanced CSS patterns practical again — nested container queries, multi-condition `@supports` gates, and combined root-state/media branches. You stay in pure CSS instead of relying on JavaScript workarounds, so the browser can optimize layout, painting, and transitions natively. Tasty doesn't limit CSS; it unlocks its full potential by removing the complexity that held teams back.
+By absorbing selector complexity, Tasty makes advanced CSS patterns practical again — nested container queries, multi-condition `@supports` gates, and combined root-state/media branches. You stay in pure CSS instead of relying on JavaScript workarounds, so the browser can optimize layout, painting, and transitions natively. Tasty keeps the solution in CSS while removing much of the selector bookkeeping that is hard to maintain by hand.
 
-[Try it in the Cube UI Kit Storybook playground →](https://cube-ui-kit.vercel.app/?path=/story/getting-started-tasty-playground--playground)
+[Try it in the playground →](https://tasty.style/playground)
 
 ## Capabilities
 
@@ -330,13 +355,13 @@ radius: '1r',             // → var(--radius)
 border: '1bw solid #border',
 ```
 
-| Unit | Maps to | Example |
-|------|---------|---------|
-| `x` | `--gap` multiplier | `2x` → `calc(var(--gap) * 2)` |
-| `r` | `--radius` multiplier | `1r` → `var(--radius)` |
-| `bw` | `--border-width` multiplier | `1bw` → `var(--border-width)` |
+| Unit | Maps to                      | Example                        |
+| ---- | ---------------------------- | ------------------------------ |
+| `x`  | `--gap` multiplier           | `2x` → `calc(var(--gap) * 2)`  |
+| `r`  | `--radius` multiplier        | `1r` → `var(--radius)`         |
+| `bw` | `--border-width` multiplier  | `1bw` → `var(--border-width)`  |
 | `ow` | `--outline-width` multiplier | `1ow` → `var(--outline-width)` |
-| `cr` | `--card-radius` multiplier | `1cr` → `var(--card-radius)` |
+| `cr` | `--card-radius` multiplier   | `1cr` → `var(--card-radius)`   |
 
 Define your own units via `configure({ units: { ... } })`.
 
@@ -344,21 +369,21 @@ Define your own units via `configure({ units: { ... } })`.
 
 Every style property accepts a state mapping object. Keys can be combined with boolean logic:
 
-| State type | Syntax | CSS output |
-|------------|--------|------------|
-| Data attribute (boolean modifier) | `disabled` | `[data-disabled]` |
-| Data attribute (value modifier) | `theme=danger` | `[data-theme="danger"]` |
-| Pseudo-class | `:hover` | `:hover` |
-| Attribute selector | `[role="tab"]` | `[role="tab"]` |
-| Class selector (supported) | `.is-active` | `.is-active` |
-| Media query | `@media(w < 768px)` | `@media (width < 768px)` |
-| Container query | `@(panel, w >= 300px)` | `@container panel (width >= 300px)` |
-| Root state | `@root(schema=dark)` | `:root[data-schema="dark"]` |
-| Parent state | `@parent(theme=danger)` | `:is([data-theme="danger"] *)` |
-| Feature query | `@supports(display: grid)` | `@supports (display: grid)` |
-| Entry animation | `@starting` | `@starting-style` |
-
-Combine with `&` (AND), `|` (OR), `!` (NOT):
+| State type                        | Syntax                     | CSS output                          |
+| --------------------------------- | -------------------------- | ----------------------------------- |
+| Data attribute (boolean modifier) | `disabled`                 | `[data-disabled]`                   |
+| Data attribute (value modifier)   | `theme=danger`             | `[data-theme="danger"]`             |
+| Pseudo-class                      | `:hover`                   | `:hover`                            |
+| Attribute selector                | `[role="tab"]`             | `[role="tab"]`                      |
+| Class selector (supported)        | `.is-active`               | `.is-active`                        |
+| Media query                       | `@media(w < 768px)`        | `@media (width < 768px)`            |
+| Container query                   | `@(panel, w >= 300px)`     | `@container panel (width >= 300px)` |
+| Root state                        | `@root(schema=dark)`       | `:root[data-schema="dark"]`         |
+| Parent state                      | `@parent(theme=danger)`    | `:is([data-theme="danger"] *)`      |
+| Feature query                     | `@supports(display: grid)` | `@supports (display: grid)`         |
+| Entry animation                   | `@starting`                | `@starting-style`                   |
+
+Combine with `&` (AND), `|` (OR), `!` (NOT), `^` (XOR):
 
 ```tsx
 fill: {
@@ -370,228 +395,143 @@ fill: {
 
 ### Sub-Element Styling
 
-Style inner elements from the parent component definition. No extra components, no CSS leakage:
+Compound components can style inner parts from the parent definition with capitalized keys in `styles` and optional `elements` declarations, producing typed sub-components like `<Card.Title />` instead of separate wrapper components or ad hoc class naming.
 
-```tsx
-const Card = tasty({
-  styles: {
-    padding: '4x',
-    Title: { preset: 'h3', color: '#primary' },
-    Content: { color: '#text', preset: 't2' },
-  },
-  elements: { Title: 'h2', Content: 'div' },
-});
+Sub-elements share the root state context by default, so keys like `:hover`, modifiers, root states, and media queries resolve as one coordinated styling block. Use `@own(...)` when a sub-element should react to its own state, and use the `$` selector affix when you need precise descendant targeting.
 
-<Card>
-  <Card.Title>Heading</Card.Title>
-  <Card.Content>Body text</Card.Content>
-</Card>
-```
+See [React API - Sub-element Styling](docs/react-api.md#sub-element-styling), [Style DSL - Advanced States](docs/dsl.md#advanced-states--prefix), and [Methodology](docs/methodology.md#component-architecture-root--sub-elements).
 
-Sub-elements use `data-element` attributes — no extra class names, no naming conventions.
+### Style Props
 
-By default, sub-elements participate in the same state context as the root component. That means mappings like `:hover`, `theme=danger`, `[role="button"]`, and other keys are evaluated as one unified block, which keeps styling logic predictable across the whole markup tree.
+`styleProps` exposes selected CSS properties as typed React props. Components control which properties to open up; consumers get layout and composition knobs without `styles` overrides. Supports state maps for responsive values.
 
-Use `@own(...)` when a sub-element should react to its own state instead of the root state context.
+```tsx
+const Space = tasty({
+  styles: { display: 'flex', flow: 'column', gap: '1x' },
+  styleProps: FLOW_STYLES,
+});
 
-Class selectors are also supported, but modifiers/pseudo-classes are usually the better default in design-system code.
+<Space flow="row" gap={{ '': '2x', '@tablet': '4x' }}>
+```
 
-Use the sub-element selector `$` when you need precise descendant targeting to avoid leakage in deeply nested component trees.
+See [React API - Style Props](docs/react-api.md#style-props) and [Methodology - styleProps](docs/methodology.md#styleprops-as-the-public-api).
 
-### Variants
+### Mod Props
 
-Variants are designed to keep single-component CSS lean. Instead of generating dozens of static button classes up front, define all versions once and let runtime usage decide what CSS is actually emitted.
+`modProps` exposes modifier keys as typed React props — the modifier equivalent of `styleProps`. Accepts an array of key names or an object with type descriptors (`Boolean`, `String`, `Number`, or enum arrays) for full TypeScript autocomplete.
 
 ```tsx
 const Button = tasty({
-  styles: { padding: '2x 4x', radius: '1r' },
-  variants: {
-    default: { fill: '#primary', color: '#on-primary' },
-    danger: { fill: '#danger', color: '#on-danger' },
-    outline: { fill: 'transparent', border: '1bw solid #primary' },
+  as: 'button',
+  modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const },
+  styles: {
+    fill: { '': '#primary', isLoading: '#primary.5' },
+    padding: { '': '2x 4x', 'size=sm': '1x 2x' },
   },
 });
 
-<Button variant="danger">Delete</Button>
+<Button isLoading size="lg">
+  Submit
+</Button>;
 ```
 
-### Recipes
-
-Recipes are predefined style sets that work like composable styling classes for Tasty. They can be pre-applied or post-applied to current styles, which lets you add reusable state logic while still allowing local style overrides.
+See [React API - Mod Props](docs/react-api.md#mod-props) and [Methodology - modProps](docs/methodology.md#modprops-and-mods).
 
-```tsx
-configure({
-  recipes: {
-    card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
-    elevated: { shadow: '0 2x 4x #shadow' },
-  },
-});
+### Variants
 
-const ProfileCard = tasty({
-  styles: {
-    recipe: 'card elevated',
-    color: '#text',
-  },
-});
-```
+Variants let one component expose named visual versions without pre-generating a separate class for every possible combination. With `tasty()`, Tasty emits only the variant CSS that is actually used, whether rendering happens on the server or in the browser.
 
-Use `/` to post-apply recipes after local styles when you need recipe states/styles to win the final merge order. Use `none` to skip base recipes: `recipe: 'none / disabled'`.
+See [React API - Variants](docs/react-api.md#variants).
 
-### Auto-Inferred `@property`
+### Recipes
 
-CSS custom properties do not animate smoothly by default because the browser does not know how to interpolate their values. The [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) at-rule fixes that by declaring a property's syntax, such as `<number>` or `<color>`.
+Recipes are reusable style bundles defined in `configure({ recipes })` and applied with the `recipe` style property. They are useful when your design system wants shared state logic or visual presets without forcing every component to repeat the same style map.
 
-In Tasty, you usually do not need to declare `@property` manually. When a custom property is assigned a concrete value, Tasty infers the syntax and registers the matching `@property` for you:
+Use `/` to post-apply recipes after local styles when recipe states should win the final merge order, and use `none` to skip base recipes entirely.
 
-```tsx
-const Pulse = tasty({
-  styles: {
-    animation: 'pulse 2s infinite',
-    transform: 'scale($pulse-scale)',
-    '@keyframes': {
-      pulse: {
-        '0%, 100%': { '$pulse-scale': 1 },
-        '50%': { '$pulse-scale': 1.05 },
-      },
-    },
-  },
-});
-```
+See [Style DSL - Recipes](docs/dsl.md#recipes) and [Configuration - recipes](docs/configuration.md#recipes).
 
-Here, `$pulse-scale: 1` is inferred as `<number>`, so Tasty injects `@property --pulse-scale` automatically before using it in the animation. Numeric types (`<number>`, `<length>`, `<percentage>`, `<angle>`, `<time>`) are inferred from values; `<color>` is inferred from the `#name` token convention.
+### Auto-Inferred `@property`
 
-If you prefer full manual control, disable auto-inference globally with `configure({ autoPropertyTypes: false })`.
+Tasty usually removes the need to hand-author CSS [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) rules. When a custom property receives a concrete value, Tasty infers its syntax and registers the matching `@property` automatically, which makes transitions and animations on custom properties work without extra boilerplate.
 
-### Explicit `@properties`
+If you prefer explicit control, disable inference with `configure({ autoPropertyTypes: false })` or declare the properties yourself.
 
-Declare `@properties` yourself only when you need to override the defaults, for example to set `inherits: false` or provide a custom `initialValue`:
+See [Style DSL - Properties (`@property`)](docs/dsl.md#properties-property).
 
-```tsx
-'@properties': {
-  '$pulse-scale': { syntax: '<number>', inherits: false, initialValue: 1 },
-},
-```
+### Explicit `@property`
 
-### React Hooks
+Use explicit `@property` only when you need to override defaults such as `inherits: false` or a custom `initialValue`.
 
-For cases where you don't need a full component:
+See [Style DSL - Properties (`@property`)](docs/dsl.md#properties-property).
 
-```tsx
-import { useStyles, useGlobalStyles, useRawCSS } from '@tenphi/tasty';
+### CSS Functions (`@function`)
 
-function App() {
-  const { className } = useStyles({ padding: '2x', fill: '#surface' });
-  useGlobalStyles('body', { margin: '0' });
-  useRawCSS('@font-face { font-family: "Custom"; src: url(...); }');
+Define reusable, parameterized CSS functions and call them anywhere a value is accepted. Declare with `$$name`, invoke with `$$name(...)`; parameters and local variables use `$name`.
 
-  return <main className={className}>...</main>;
-}
+```jsx
+const Card = tasty({
+  styles: {
+    '@function': {
+      $$negative: { args: ['$value'], result: '(-1 * $value)' },
+    },
+    margin: '$$negative(2x) top',
+  },
+});
 ```
 
-### Zero-Runtime Mode
+Definitions can also come from `configure({ functions })` or the `useFunction` style function, and work across client rendering, SSR/RSC, and build-time extraction. `@function` is an experimental CSS feature, so for browsers that do not ship it yet enable `configure({ polyfills: { functions: true } })` to inline every call into plain CSS at parse time.
 
-Extract all CSS at build time. Zero JavaScript overhead in production:
+See [Style DSL - Functions](docs/dsl.md#functions-function) and [Configuration - Polyfills](docs/configuration.md#polyfills).
 
-```tsx
-import { tastyStatic } from '@tenphi/tasty/static';
+### Style Functions
 
-const card = tastyStatic({
-  padding: '4x',
-  fill: '#surface',
-  radius: '1r',
-  color: { '': '#text', '@dark': '#text-on-dark' },
-});
+When you do not need a full component wrapper, use the style functions directly: `useStyles` for local class names, `useGlobalStyles` for selector-scoped global CSS, `useRawCSS` for raw rules, plus `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` for animation, custom-property, font, counter-style, and CSS-function primitives. All style functions are hook-free and work in React Server Components.
 
-// card is a CSS class name string
-<div className={card}>Static styles, zero runtime</div>
-```
+See [React API - Style Functions](docs/react-api.md#style-functions).
 
-Configure the Babel plugin:
+### Zero-Runtime Delivery
 
-```js
-module.exports = {
-  plugins: [
-    ['@tenphi/tasty/babel-plugin', {
-      output: 'public/tasty.css',
-      config: {
-        states: { '@dark': '@root(schema=dark)' },
-      },
-    }],
-  ],
-};
-```
+There are two ways to ship no Tasty styling runtime to the browser:
 
-### `tasty` vs `tastyStatic`
+- Render `tasty()` components only on the server, retaining the full React component API. Astro's `tastyIntegration({ islands: false })` is the clearest example.
+- Use `tastyStatic()` to extract build-time-known CSS without React.
 
-| | `tasty` (runtime) | `tastyStatic` (zero-runtime) |
-|---|---|---|
-| **Output** | React component | CSS class name |
-| **CSS injection** | Runtime `<style>` tags | Build-time extraction |
-| **Runtime cost** | Style generation on mount | None |
-| **Generated CSS scope** | Only styles/variants used at runtime | All extracted static styles at build time |
-| **Dynamic values** | Fully supported | Via CSS custom properties |
-| **Sub-elements** | Built-in (`<C.Title>`) | Manual (`data-element`) |
-| **Variants** | Built-in (`variants` option) | Separate static styles |
-| **Framework** | React | Any (requires Babel) |
-| **Best for** | Interactive apps, design systems | Static sites, SSG, landing pages |
+See [Server-Side Rendering](docs/ssr.md), [Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md), and [Getting Started - Choosing a rendering mode](docs/getting-started.md#choosing-a-rendering-mode).
 
-Both share the same DSL, tokens, units, state mappings, and recipes.
+### `tasty` vs `tastyStatic`
 
-### Server-Side Rendering
+`tasty()` returns React components that compute CSS during rendering. That render can happen in the browser or only on the server; the server-only path ships no Tasty styling runtime while retaining the full feature set. `tastyStatic()` returns class names and extracts CSS during the build via a Babel plugin, with no React dependency. Both share the same DSL, tokens, units, state mappings, and recipes. Use `tasty()` as the default for React; use `tastyStatic()` when extraction must happen before rendering or the consumer is not React.
 
-SSR with zero-cost client hydration. Existing `tasty()` components work unchanged — SSR is opt-in and requires no per-component modifications. Supports Next.js (App Router with streaming), Astro (middleware + islands), and any React-based framework via the core API. Requires React 18+.
+See [Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md), [React API](docs/react-api.md), and [Comparison - Where styles are computed](docs/comparison.md#where-styles-are-computed).
 
-**Next.js setup:**
+### Server-Side Rendering
 
-```tsx
-// app/tasty-registry.tsx
-'use client';
+`tasty()` components already work on the server without any SSR integration — they are hook-free and render as React Server Components by default. In server-only contexts, they ship no Tasty styling runtime while retaining the full feature set. Astro without islands is the explicit zero-client-JavaScript setup; server-only Next.js RSC follows the same architecture, with output depending on the application deployment.
 
-import { TastyRegistry } from '@tenphi/tasty/ssr/next';
+SSR integration (`TastyRegistry`, `tastyIntegration`) adds CSS batching, deduplication across component trees, FOUC prevention, and client cache hydration. Use it when your app also has client-side rendering:
 
-export default function TastyStyleRegistry({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return <TastyRegistry>{children}</TastyRegistry>;
-}
-```
+- `@tenphi/tasty/ssr/next` for Next.js App Router (mixed server + client components)
+- `@tenphi/tasty/ssr/astro` for Astro (with or without islands)
+- The core SSR API for other React SSR setups
 
-```tsx
-// app/layout.tsx
-import TastyStyleRegistry from './tasty-registry';
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html>
-      <body>
-        <TastyStyleRegistry>{children}</TastyStyleRegistry>
-      </body>
-    </html>
-  );
-}
-```
-
-See the [full SSR guide](docs/ssr.md) for Astro integration, streaming SSR, generic framework usage, troubleshooting, and the current requirements.
+See the [full SSR guide](docs/ssr.md).
 
 ## Entry Points
 
-| Import | Description | Platform |
-|--------|-------------|----------|
-| `@tenphi/tasty` | Runtime style engine (`tasty`, hooks, `configure`) | Browser |
-| `@tenphi/tasty/static` | Zero-runtime static styles (`tastyStatic`) | Browser |
-| `@tenphi/tasty/core` | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | Browser / Node |
-| `@tenphi/tasty/babel-plugin` | Babel plugin for zero-runtime CSS extraction | Node |
-| `@tenphi/tasty/zero` | Programmatic extraction API | Node |
-| `@tenphi/tasty/next` | Next.js integration wrapper | Node |
-| `@tenphi/tasty/ssr` | Core SSR API (collector, context, hydration) | Node |
-| `@tenphi/tasty/ssr/next` | Next.js App Router SSR integration | Node |
-| `@tenphi/tasty/ssr/astro` | Astro middleware + auto-hydration | Node / Browser |
+| Import                           | Description                                                                                             | Platform       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- |
+| `@tenphi/tasty`                  | React style engine (`tasty`, style functions, `configure`)                                              | Browser / Node |
+| `@tenphi/tasty/static`           | Build-time extraction authoring API (`tastyStatic`)                                                     | Build time     |
+| `@tenphi/tasty/static/inject`    | Runtime helper the Babel plugin rewrites `tastyStatic` imports to in inject mode                        | Browser        |
+| `@tenphi/tasty/core`             | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | Browser / Node |
+| `@tenphi/tasty/babel-plugin`     | Babel plugin for build-time CSS extraction                                                              | Node           |
+| `@tenphi/tasty/zero`             | Programmatic extraction API                                                                             | Node           |
+| `@tenphi/tasty/zero/next`        | Next.js integration wrapper                                                                             | Node           |
+| `@tenphi/tasty/ssr`              | Core SSR API (collector, context, hydration)                                                            | Node           |
+| `@tenphi/tasty/ssr/next`         | Next.js App Router SSR integration                                                                      | Node           |
+| `@tenphi/tasty/ssr/astro`        | Astro integration + middleware                                                                          | Node           |
+| `@tenphi/tasty/ssr/astro-client` | Astro client-side cache hydration                                                                       | Browser        |
 
 ## Browser Requirements
 
@@ -607,41 +547,24 @@ Tasty's exclusive selector system relies on modern CSS pseudo-class syntax:
 
 All sizes measured with [size-limit](https://github.com/ai/size-limit) — minified and brotli-compressed, including all dependencies.
 
-| Entry point | Size |
-|-------------|------|
-| `@tenphi/tasty` (runtime + SSR) | ~44 kB |
-| `@tenphi/tasty/core` (runtime, no SSR) | ~41 kB |
-| `@tenphi/tasty/static` (zero-runtime) | ~1.5 kB |
+| Entry point                                       | Size     |
+| ------------------------------------------------- | -------- |
+| `@tenphi/tasty` (client + server rendering)       | 50.19 kB |
+| `@tenphi/tasty/core` (runtime, no SSR)            | 47.76 kB |
+| `@tenphi/tasty/static` (build-time authoring API) | 16.43 kB |
+| `@tenphi/tasty/zero` (programmatic extraction)    | 29.6 kB  |
+| `@tenphi/tasty/babel-plugin` (Babel plugin entry) | 43.7 kB  |
 
-Run `pnpm size` for exact up-to-date numbers.
+Run `pnpm size` to reproduce (outputs may shift slightly with releases).
 
 ### Runtime Benchmarks
 
-If you choose the runtime approach, performance is usually a non-issue in practice. The numbers below show single-call throughput for the core pipeline stages, measured with `vitest bench` on an Apple M1 Max (Node 22).
-
-| Operation | ops/sec | Latency (mean) |
-|-----------|--------:|---------------:|
-| `renderStyles` — 5 flat properties (cold) | ~72,000 | ~14 us |
-| `renderStyles` — state map with media/hover/modifier (cold) | ~22,000 | ~46 us |
-| `renderStyles` — same styles (cached) | ~7,200,000 | ~0.14 us |
-| `parseStateKey` — simple key like `:hover` (cold) | ~1,200,000 | ~0.9 us |
-| `parseStateKey` — complex OR/AND/NOT key (cold) | ~190,000 | ~5 us |
-| `parseStateKey` — any key (cached) | ~3,300,000–8,900,000 | ~0.1–0.3 us |
-| `parseStyle` — value tokens like `2x 4x` (cold) | ~345,000 | ~3 us |
-| `parseStyle` — color tokens (cold) | ~525,000 | ~1.9 us |
-| `parseStyle` — any value (cached) | ~15,500,000 | ~0.06 us |
-
-"Cold" benchmarks use unique inputs to bypass all caches. Cached benchmarks reuse a single input and measure the LRU hot path.
-
-Run `pnpm bench` to reproduce.
-
-#### What This Means in Practice
-
-- **Cached path dominates production.** After a component's first render, subsequent renders with stable styles skip the pipeline entirely (React `useMemo` + LRU cache hits at every level). All cached operations are sub-microsecond — effectively free.
-- **Cold path is fast enough.** The heaviest cold operation — a complex state map with media queries, hover, and modifiers — takes ~46 us. Even a page with 100 unique styled components adds only ~5 ms of total style computation on first render, negligible next to React reconciliation and DOM work.
-- **Cache multipliers are 30x–100x.** This confirms the multi-level LRU architecture (parser, state-key, simplify, condition, pipeline) is delivering real value.
-- **Comparable to lighter systems.** Emotion's `css()` is typically 5–20 us for simple styles; Tasty's cold `renderStyles` at ~14 us for 5 properties is in the same range despite doing significantly more work (state maps, design tokens, sub-elements, chunking).
-- **On slower devices.** The benchmarks above are from an M1 Max (Geekbench 6 SC ~2,400). A mid-range consumer laptop (~1,800 SC) is roughly 1.3x slower; a mid-range phone (~1,200 SC) is roughly 2x slower; a budget phone (~700 SC) is roughly 3–4x slower. Even at 4x, the heaviest cold operation stays under 200 us and 100 unique components under 20 ms — still well within a single frame budget. The cached path remains sub-microsecond on all devices.
+Reproducible benchmarks cover the core style pipeline, the React overhead of an
+empty `tasty({})` wrapper, cold browser generation plus rule injection against
+equivalent CSS already present on the page, and a representative 1,000-element
+React update with shared styles. See
+[Runtime Benchmarks](docs/runtime-benchmarks.md) for the methodology, exact
+results, limitations, and commands.
 
 ### How It Stays Fast
 
@@ -651,6 +574,7 @@ Run `pnpm bench` to reproduce.
 - Style normalization guarantees equivalent style input resolves to the same chunks, improving deduplication hit rates.
 - A style garbage collector removes unused styles/chunks over time.
 - A dedicated style injector minimizes DOM/style-tag overhead.
+- Optional [batched injection](docs/configuration.md#batched-injection) keeps stylesheet writes together before layout reads, allowing the browser to resolve their effects together instead of between individual insertions.
 - This approach is validated in enterprise-scale apps where runtime styling overhead is not noticeable in normal UI flows.
 
 ## Ecosystem
@@ -698,7 +622,7 @@ Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Hi
 
 ### [tasty.style](https://tasty.style) ([source](https://github.com/tenphi/tasty.style))
 
-The official Tasty documentation and landing page — itself built entirely with Tasty. A showcase for zero-runtime styling via `tastyStatic`, SSR with Next.js, and OKHSL color theming with Glaze.
+The official Tasty documentation and landing page — itself built entirely with `tasty()`. A showcase for server-rendered Tasty with Next.js and OKHST color theming with Glaze.
 
 ### [Cube Cloud](https://cube.dev/)
 
@@ -714,9 +638,9 @@ Open-source React UI kit built on Tasty + React Aria. 100+ production components
 
 ## Documentation
 
-Start from the docs hub if you want the shortest path to the right guide for your role or rendering mode.
+Start from the docs hub if you want the shortest path to the right guide for your role or styling approach.
 
-- **[Docs Hub](docs/README.md)** — audience-based navigation across onboarding, design-system authoring, runtime, zero-runtime, SSR, debugging, and internals
+- **[Docs Hub](docs/README.md)** — audience-based navigation across onboarding, design-system authoring, client and server rendering, build-time extraction, debugging, and internals
 
 ### Start here
 
@@ -730,19 +654,25 @@ Start from the docs hub if you want the shortest path to the right guide for you
 
 ### Reference
 
-- **[Style DSL](docs/dsl.md)** — The Tasty style language: state maps, tokens, units, color syntax, extending semantics, recipes, keyframes, and @property
-- **[Runtime API](docs/runtime.md)** — React-specific API: `tasty()` factory, component props, variants, sub-elements, and hooks
-- **[Configuration](docs/configuration.md)** — Global configuration: tokens, recipes, custom units, style handlers, and TypeScript extensions
+- **[Style DSL](docs/dsl.md)** — The Tasty style language: state maps, tokens, units, color syntax, extending semantics, recipes, keyframes, `@property`, `@font-face`, `@counter-style`, and `@function`
+- **[React API](docs/react-api.md)** — React-specific API: `tasty()` factory, component props, variants, sub-elements, and style functions
+- **[Configuration](docs/configuration.md)** — Global configuration: tokens, recipes, custom units, functions, polyfills, style handlers, props middleware, and TypeScript extensions
+- **[Plugins & Extension Points](docs/plugins.md)** — Extending Tasty: choosing an extension point, authoring style handlers and props middleware, and packaging it as a plugin
 - **[Style Properties](docs/styles.md)** — Complete reference for all enhanced style properties: syntax, values, modifiers, and recommendations
+- **[Style Rules for AI Agents](docs/ai-agents.md)** — Condensed, rule-based brief for AI coding agents: correct value syntax, state maps, and property choices in one short page
+
+### Upgrading
+
+- **[Migration Guide (v2 → v3)](docs/migration-v3.md)** — Every breaking change in 3.0 with a search-and-replace cheat sheet: at-rule key renames, the directional-shorthand rule, config keys, renamed and removed exports, and what deliberately did not change
 
 ### Rendering modes
 
-- **[Zero Runtime (tastyStatic)](docs/tasty-static.md)** — Build-time static styling: Babel plugin setup, Next.js integration, and static style patterns
+- **[Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md)** — Babel plugin setup, Next.js integration, and static style patterns
 - **[Server-Side Rendering](docs/ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks: streaming support, cache hydration, and troubleshooting
 
 ### Internals
 
-- **[Style rendering pipeline](docs/PIPELINE.md)** — How `Styles` become mutually exclusive CSS rules: parse → exclusives → combinations → handlers → merge → materialize (`src/pipeline/`)
+- **[Style rendering pipeline](docs/pipeline.md)** — How `Styles` become mutually exclusive CSS rules: parse → exclusives → combinations → handlers → merge → materialize (`src/pipeline/`)
 - **[Style Injector](docs/injector.md)** — Internal CSS injection engine: `inject()`, `injectGlobal()`, `injectRawCSS()`, `keyframes()`, deduplication, reference counting, cleanup, SSR support, and Shadow DOM
 - **[Debug Utilities](docs/debug.md)** — Runtime CSS inspection via `tastyDebug`: CSS extraction, element inspection, cache metrics, chunk breakdown, and performance monitoring