@tenphi/tasty 0.0.0-snapshot.5776c4c → 0.0.0-snapshot.57effc3

package/README.md

@@ -1,60 +1,54 @@
 <p align="center">
-  <img src="assets/tasty.svg" width="128" height="128" alt="Tasty logo">
+  <img src="assets/tasty.svg" width="128" height="128" alt="Tasty logo" />
 </p>
 
 <h1 align="center">Tasty</h1>
 
 <p align="center">
-  <strong>Deterministic styling for stateful component systems.</strong><br>
-  A design-system styling engine that compiles component states into mutually exclusive selectors, so complex components stay predictable as they evolve.
+  <strong>CSS-in-JS for React design systems.</strong><br />
+  Build components whose styles don’t fight.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@tenphi/tasty"><img src="https://img.shields.io/npm/v/@tenphi/tasty.svg" alt="npm version"></a>
-  <a href="https://github.com/tenphi/tasty/actions/workflows/ci.yml"><img src="https://github.com/tenphi/tasty/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
-  <a href="https://github.com/tenphi/tasty/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tenphi/tasty" alt="license"></a>
+  <a href="https://www.npmjs.com/package/@tenphi/tasty"><img src="https://img.shields.io/npm/v/@tenphi/tasty.svg" alt="npm version" /></a>
+  <a href="https://github.com/tenphi/tasty/actions/workflows/ci.yml"><img src="https://github.com/tenphi/tasty/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <a href="https://github.com/tenphi/tasty/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tenphi/tasty" alt="license" /></a>
 </p>
 
 ---
 
-Tasty is a styling engine for design systems that generates deterministic CSS for stateful components.
+Tasty is a styling engine for teams that build component libraries. You describe hover, disabled, variants, themes, and breakpoints as **state maps**, in a CSS-like language built from your design system's own tokens and conventions. Tasty compiles each map into selectors that never match at the same time, so the result never depends on specificity or source order.
 
-It compiles state maps into **mutually exclusive selectors**, so for a given property and component state, one branch wins by construction instead of competing through cascade and specificity.
-
-That is the core guarantee: component styling resolves from declared state logic, not from source-order accidents or specificity fights.
-
-The practical payoff shows up later: adding states, variants, and overrides stays inside the state map instead of reopening selector logic by hand.
+```tsx
+import { tasty } from '@tenphi/tasty';
 
-Tasty fits best when you are building a design system or component library with intersecting states, variants, tokens, sub-elements, responsive rules, and extension semantics that need to stay predictable over time.
+const Button = tasty({
+  as: 'button',
+  styles: {
+    fill: {
+      '': '#primary',
+      ':hover': '#primary-hover',
+      ':active': '#primary-pressed',
+      '[disabled]': '#surface',
+    },
+  },
+});
+```
 
-On top of that foundation, Tasty gives teams a governed styling model: a CSS-like DSL, tokens, recipes, typed style props, sub-elements, and multiple rendering modes.
+Later keys have higher priority. If this button is both hovered and disabled, `[disabled]` wins and the hover rule does not apply. That decision is compiled into the selectors themselves, so you can add states, variants, themes, and overrides without reopening selector logic by hand.
 
-- **New here?** Start with [Comparison](docs/comparison.md) if you are evaluating fit.
-- **Adopting Tasty?** Read the [Adoption Guide](docs/adoption.md).
-- **Want the mechanism first?** Jump to [How It Actually Works](#how-it-actually-works).
-- **Ready to build?** Go to [Getting Started](docs/getting-started.md).
+- **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).
+- **Building a component library?** See [Methodology](docs/methodology.md) and [Building a Design System](docs/design-system.md).
 
 ## Why Tasty
 
-- **Deterministic composition, not cascade fights** — Stateful styles resolve from the state map you declared, not from selector competition. See [How It Actually Works](#how-it-actually-works).
-- **Easier to extend over time** — When components gain new states, variants, or overrides, you update declared branches instead of re-deriving selector interactions by hand.
-- **Built for design-system teams** — Best fit for reusable component systems with complex state interactions.
-- **A governed styling model, not just syntax sugar** — Design-system authors define the styling language product teams consume.
-- **DSL that still feels like CSS** — Familiar property names, less selector boilerplate. Start with the [Style DSL](docs/dsl.md), then use [Style Properties](docs/styles.md) as the handler reference.
-
-### 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).
-- **Server-compatible by default, zero client JS in server-only contexts** — All `tasty()` components and style functions are hook-free. In server-only rendering (Next.js RSC, Astro without islands, SSG), they produce zero client JavaScript with the full feature set. Add SSR integration only when your app also has client-side hydration. Use `tastyStatic()` only when you 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** — Runtime mode 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 It Exists
-
-Modern component styling becomes fragile when multiple selectors can still 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 state-map resolution. Each property compiles into mutually exclusive branches, so component styling stays deterministic as systems grow. For the full mechanism, jump to [How It Actually Works](#how-it-actually-works).
+- **States that can't conflict** — Every state map compiles into mutually exclusive selectors, and the last matching key wins by construction. Adding a state, variant, or override never means re-deriving selector interactions. [How it works →](#how-it-works)
+- **Your design system's language** — Define color tokens, units, state aliases like `@mobile` and `@dark`, typography presets, and recipes once with `configure()`. Components then read like the spec: `padding: '2x'`, `fill: '#surface'`, `preset: 'h3'`. [Design-system integration →](#design-system-integration)
+- **Typed component APIs** — Decide exactly what consumers can change. `styleProps`, `modProps`, `tokenProps`, `variants`, and sub-elements become typed React props and components with full autocomplete. [Component API →](#component-api)
+- **Guardrails in the editor and CI** — An ESLint and oxlint plugin with 40+ rules checks property names, values, tokens, state keys, presets, and recipes against your project's config. TypeScript augmentation autocompletes your own token, preset, and theme names. [Types and linting →](#types-and-linting)
+- **Modern CSS, one model** — Media and container queries, `@supports`, `:has()`, root and parent states, and `@starting-style` are all state keys. `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` are built in. [CSS coverage →](#css-coverage)
+- **Render anywhere** — The same styles work in client React, React Server Components, and streaming SSR (Next.js, Astro). Render only on the server to ship no styling runtime at all, or extract CSS at build time with `tastyStatic()`. [Rendering modes →](#rendering-modes)
 
 ## Installation
 
@@ -62,33 +56,13 @@ Tasty replaces that competition with explicit state-map resolution. Each propert
 pnpm add @tenphi/tasty
 ```
 
-Requirements:
-
-- Node.js 20+
-- React 18+ (peer dependency for the React entry points)
-- `pnpm`, `npm`, or `yarn`
-
-Other package managers:
-
-```bash
-npm add @tenphi/tasty
-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
-- **[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: runtime, zero-runtime, runtime SSR integration, design-system authoring, internals, and debugging
-- **[Methodology](docs/methodology.md)** — the recommended component model and public API conventions for design-system code
+Requires Node.js 20+ and React 18+ (a peer dependency of the React entry points). `npm add @tenphi/tasty` and `yarn add @tenphi/tasty` work the same way.
 
 ## Quick Start
 
-### Create a styled component
+### 1. Write a component
+
+Plain CSS values work as-is, so a first component looks like CSS you already know:
 
 ```tsx
 import { tasty } from '@tenphi/tasty';
@@ -97,140 +71,154 @@ const Card = tasty({
   as: 'div',
   styles: {
     display: 'flex',
-    flow: 'column',
+    flow: 'column', // flex-flow
     padding: '24px',
     gap: '12px',
-    fill: 'white',
+    fill: 'white', // background-color
     color: '#222',
     border: '1px solid #ddd',
-    radius: '12px',
+    radius: '12px', // border-radius
   },
 });
 
-// Just a React component
-<Card>Hello World</Card>
+<Card>Hello World</Card>;
 ```
 
-Every value maps to CSS you'd recognize. This example is intentionally a simple first contact, not a tour of the whole DSL.
+### 2. Bring in your design system
 
-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.
+Call `configure()` once, before your app renders, to define the vocabulary every component shares:
 
-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).
+```tsx
+// tasty.setup.ts — import it at the top of your entry point
+import { configure } from '@tenphi/tasty';
+
+configure({
+  tokens: {
+    '#surface': { '': '#fff', '@dark': '#1c1c1e' },
+    '#text': { '': '#222', '@dark': '#f2f2f7' },
+    '#border': '#ddd',
+  },
+  units: { x: '8px', r: '12px' }, // spacing step and radius
+  states: {
+    '@mobile': '@media(w < 768px)',
+    '@dark':
+      '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
+  },
+});
+```
 
-### Add state-driven styles
+The same card, written in that vocabulary:
+
+```tsx
+const Card = tasty({
+  styles: {
+    display: 'flex',
+    flow: 'column',
+    padding: { '': '3x', '@mobile': '2x' }, // 24px, 16px on mobile
+    gap: '1.5x', // 12px
+    fill: '#surface', // var(--surface-color)
+    color: '#text',
+    border: true, // 1bw solid #border
+    radius: '1r', // 12px
+  },
+});
+```
+
+The component never mentions dark mode, yet it follows the `@dark` tokens. Change a token or a unit once and every component follows.
+
+### 3. Add states and a typed API
 
 ```tsx
 const Button = tasty({
   as: 'button',
+  modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const },
   styles: {
-    padding: '1.5x 3x',
+    padding: { '': '1.5x 3x', 'size=sm': '1x 2x', 'size=lg': '2x 4x' },
+    radius: '1r',
     fill: {
       '': '#primary',
       ':hover': '#primary-hover',
       ':active': '#primary-pressed',
-      '[disabled]': '#surface',
-    },
-    color: {
-      '': '#on-primary',
-      '[disabled]': '#text.40',
-    },
-    cursor: {
-      '': 'pointer',
-      '[disabled]': 'not-allowed',
+      disabled: '#surface',
     },
+    color: { '': '#on-primary', disabled: '#text.40' },
+    cursor: { '': 'pointer', isLoading: 'wait', disabled: 'not-allowed' },
     transition: 'theme',
   },
 });
+
+<Button size="lg" isLoading>
+  Save
+</Button>;
+// renders <button data-is-loading data-size="lg" class="…">
 ```
 
-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.
+`size` is typed as `'sm' | 'md' | 'lg'`. Mod props become `data-*` attributes, which state keys like `size=lg` and `isLoading` select. `disabled` tracks the native `disabled` prop, `#text.40` is the text color at 40% opacity, and `transition: 'theme'` is a named group that transitions color, background, border, shadow, outline, and opacity together.
 
-### Extend any component
+### 4. Extend a component
 
 ```tsx
-import { Button } from 'my-ui-lib';
-
 const DangerButton = tasty(Button, {
   styles: {
     fill: {
       '': '#danger',
       ':hover': '#danger-hover',
+      ':active': '#danger-pressed',
+      disabled: '@inherit', // keep the parent's disabled branch
     },
   },
 });
 ```
 
-Child styles merge with parent styles intelligently — state maps can extend or replace parent states per-property.
+A state map with a `''` key replaces the parent's map; a map without one extends it. `@inherit` pulls a single branch from the parent, `null` removes one, and `false` blocks it entirely. See [Extending vs. replacing state maps](docs/dsl.md#extending-vs-replacing-state-maps).
 
-### Optional: configure shared conventions
+[Getting Started](docs/getting-started.md) continues from here with setup, linting, editor tooling, and choosing a rendering mode.
 
-```tsx
-import { configure } from '@tenphi/tasty';
+## How It Works
 
-configure({
-  states: {
-    '@mobile': '@media(w < 768px)',
-    '@tablet': '@media(w < 1024px)',
-    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
-  },
-  recipes: {
-    card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
-  },
-});
-```
+The cascade resolves conflicts by specificity, then by source order. Take two rules for a button's background:
 
-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
+.btn:hover {
+  background: dodgerblue;
+}
+.btn[disabled] {
+  background: gray;
+}
+```
 
-### Props as the public API
+Both selectors have specificity `(0, 2, 0)`. When the button is hovered **and** disabled, both match and the later rule wins. Swap the two rules and a hovered disabled button silently turns blue. The logic is correct; only the order is wrong, which is why this class of bug survives code review.
 
-`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:
+Tasty removes the competition. For the same intent:
 
 ```tsx
-<Space flow="row" gap="2x" placeItems="center">
-  <Button isLoading size="large" placeSelf="end">Submit</Button>
-</Space>
+fill: {
+  '': '#primary',
+  ':hover': '#primary-hover',
+  '[disabled]': '#surface',
+}
 ```
 
-See [Style Props](#style-props) and [Mod Props](#mod-props) below, or the full reference in [React API](docs/react-api.md#style-props).
-
-## Choose a Styling Approach
-
-Once you understand the component model, pick the rendering mode that matches your app.
-
-| Approach | Entry point | Best for | Trade-off |
-|----------|-------------|----------|-----------|
-| **Runtime (default)** | `tasty()` from `@tenphi/tasty` | All React apps — server-rendered by default, zero client JS until you need interactivity | Full feature set; CSS computed during React rendering (server or client) |
-| **Runtime + SSR integration** | Add `@tenphi/tasty/ssr/*` | Apps with client-side hydration (Next.js client components, Astro islands) | Adds CSS deduplication, FOUC prevention, and client cache hydration |
-| **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Non-React frameworks or when you need build-time extraction without React | Requires the Babel plugin; no component-level `styleProps` or runtime-only APIs |
-
-All `tasty()` components are hook-free and work as React Server Components. In server-only contexts — Next.js RSC without `'use client'`, Astro without `client:*` directives, and other SSG setups — they produce the same end result as `tastyStatic()` (static HTML + CSS, zero client JavaScript) but with the full feature set including `styleProps`, sub-elements, and variants. SSR integration is only needed when your app also has client-side rendering. See [Getting Started](docs/getting-started.md#choosing-a-rendering-mode), [Zero Runtime](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)**.
-
-### 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:
+it generates:
 
 ```css
-.btn:hover     { background: dodgerblue; }
-.btn[disabled] { background: gray; }
+.t0.t0:where(:not([disabled]):not(:hover)) {
+  background-color: var(--primary-color);
+}
+.t0.t0:where(:not([disabled]):hover) {
+  background-color: var(--primary-hover-color);
+}
+.t0.t0:where([disabled]) {
+  background-color: var(--surface-color);
+}
 ```
 
-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.
-
-### 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.
+Each branch is guarded by the negation of every higher-priority branch, so exactly one rule matches any element. Reorder the rules, split them across stylesheets, or extend the component: the outcome stays the same. Because the logic stays in CSS rather than JavaScript, the browser handles layout, painting, and transitions natively.
 
-### What Tasty generates instead
+<details>
+<summary><strong>A harder case: dark mode from a root attribute or the OS preference</strong></summary>
 
-Tasty solves both problems at once: **every state mapping compiles into mutually exclusive selectors.**
+Say `@dark` means "the root has `data-schema="dark"`, or no schema is set and the OS prefers dark":
 
 ```tsx
 const Text = tasty({
@@ -239,371 +227,425 @@ const Text = tasty({
       '': '#text',
       '@dark': '#text-on-dark',
     },
-    padding: {
-      '': '4x',
-      '@mobile': '2x',
-    },
   },
 });
 ```
 
-If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))`, try writing the CSS by hand. A first attempt might look like this:
+A first attempt by hand:
 
 ```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); }
-@media (prefers-color-scheme: dark) {
-  .t0 { color: var(--text-on-dark-color); }
+.t0 {
+  color: var(--text-color);
+}
+:root[data-schema='dark'] .t0 {
+  color: var(--text-on-dark-color);
 }
-```
-
-The `@media` branch fires even when `data-schema="light"` is explicitly set. Fix that:
-
-```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); }
 @media (prefers-color-scheme: dark) {
-  :root:not([data-schema]) .t0 { color: var(--text-on-dark-color); }
+  .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:
+The `@media` branch fires even when `data-schema="light"` is set explicitly. Scoping it to `:root:not([data-schema])` fixes that, but the bare `.t0` default still matches unconditionally, and it can beat the attribute selector by source order if another rule re-declares it later. No single selector says "apply the default only when none of the dark branches win". The correct version negates every other branch, which is what Tasty generates:
 
 ```css
-/* Branch 1: Explicit dark schema */
-:root[data-schema="dark"] .t0.t0 {
+/* Explicit dark schema */
+:where(:root[data-schema='dark']) .t0.t0 {
   color: var(--text-on-dark-color);
 }
 
-/* Branch 2: No schema attribute + OS prefers dark */
+/* No schema attribute, OS prefers dark */
 @media (prefers-color-scheme: dark) {
-  :root:not([data-schema]) .t0.t0 {
+  :where(:root:not([data-schema])) .t0.t0 {
     color: var(--text-on-dark-color);
   }
 }
 
-/* Default: no schema + OS does not prefer dark */
+/* Default: OS prefers light, schema is not dark */
 @media (not (prefers-color-scheme: dark)) {
-  :root:not([data-schema="dark"]) .t0.t0 {
+  :where(: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 {
-  color: var(--text-color);
+/* Default: OS prefers dark, but a non-dark schema is set */
+@media (prefers-color-scheme: dark) {
+  :where(:root:not([data-schema='dark'])[data-schema]) .t0.t0 {
+    color: var(--text-color);
+  }
 }
 ```
 
-### What guarantee that gives you
+That is one property with one state. Multiply it by dozens of properties, breakpoints, and container queries, and hand-written selectors stop being maintainable.
 
-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.
+</details>
 
-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.
+For the full compiler model (parsing state keys, building exclusive conditions, merging by value, materializing selectors and at-rules), see the [Style rendering pipeline](docs/pipeline.md). [Try it in the playground →](https://tasty.style/playground)
 
-[Try it in the playground →](https://tasty.style/playground)
+## Design-System Integration
 
-## Capabilities
+`configure()` is where a design system's vocabulary lives. Everything defined there is available to every component, and the same names feed the linter and TypeScript.
 
-This section is a quick product tour. For the canonical guides and references, start from the [Docs Hub](docs/README.md).
+| Define                       | With `configure({ … })`                                 | Use in styles                                            |
+| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
+| Color tokens                 | `tokens: { '#surface': '#fff' }`                        | `fill: '#surface'`, `color: '#text.60'`                  |
+| Value tokens                 | `tokens: { '$sidebar-width': '280px' }`                 | `width: '$sidebar-width'`                                |
+| Units                        | `units: { x: '8px', r: '6px' }`                         | `padding: '2x'`, `radius: '1r'`                          |
+| State aliases                | `states: { '@mobile': '@media(w < 768px)' }`            | `gap: { '': '2x', '@mobile': '1x' }`                     |
+| Typography presets           | `presets: { h1: { fontSize: '2rem', … } }`              | `preset: 'h1'`                                           |
+| Recipes                      | `recipes: { card: { padding: '4x', … } }`               | `recipe: 'card'`                                         |
+| Global at-rules              | `keyframes`, `properties`, `fontFaces`, `counterStyles` | `animation: 'fade-in 200ms'`                             |
+| Functions, handlers, plugins | `functions`, `handlers`, `propHandlers`, `plugins`      | `$$name(...)`, new style properties, new component props |
 
-### Design Tokens and Custom Units
+Tokens accept state maps, so a theme is just more branches: `'#surface': { '': '#fff', '@dark': '#1c1c1e' }`. To generate whole light, dark, and high-contrast palettes with contrast solving, use [Glaze](#glaze).
 
-Tokens are first-class. Colors use `#name` syntax. Spacing, radius, and border width use multiplier units tied to CSS custom properties:
-
-```tsx
-fill: '#surface',         // → var(--surface-color)
-color: '#text.80',        // → 80% opacity text token
-padding: '2x',            // → calc(var(--gap) * 2)
-radius: '1r',             // → var(--radius)
-border: '1bw solid #border',
-```
+### Built-in units
 
-| 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)` |
+| Unit | Default             | Example                  |
+| ---- | ------------------- | ------------------------ |
+| `x`  | `8px` spacing step  | `2x` → `16px`            |
+| `r`  | `6px` radius        | `1r` → `6px`             |
+| `cr` | `10px` card radius  | `1cr` → `10px`           |
+| `bw` | `1px` border width  | `2bw` → `2px`            |
+| `ow` | `3px` outline width | `1ow` → `3px`            |
+| `sf` | stable fraction     | `1sf` → `minmax(0, 1fr)` |
 
-Define your own units via `configure({ units: { ... } })`.
+Units compile to plain values. Override them with `configure({ units })`. When the scale has to change at runtime, point a unit at a custom property and define it as a token: `units: { x: 'var(--gap)' }` with `tokens: { $gap: '8px' }` makes `2x` compile to `calc(2 * var(--gap))`. Parentheses become `calc()`: `width: '(100% - 4x)'`.
 
-### State System
-
-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` |
+### Recipes
 
-Combine with `&` (AND), `|` (OR), `!` (NOT), `^` (XOR):
+Recipes are reusable style bundles, state maps included:
 
 ```tsx
-fill: {
-  '': '#surface',
-  'theme=danger & :hover': '#danger-hover',
-  '[aria-selected="true"]': '#accent-subtle',
-}
+configure({
+  recipes: {
+    card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
+    elevated: { shadow: '0 1x 3x #shadow' },
+  },
+});
+
+const Panel = tasty({ styles: { recipe: 'card elevated', gap: '2x' } });
 ```
 
-### Sub-Element Styling
+Local styles merge over recipes with the same extend/replace rules as component extension. Recipes listed after `/` apply after local styles, and `none` skips base recipes. See [Style DSL — Recipes](docs/dsl.md#recipes).
 
-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.
+For token vocabularies, state aliases, layout primitives, and override contracts, see [Building a Design System](docs/design-system.md). To add your own style properties, units, functions, or component props, see [Plugins & Extension Points](docs/plugins.md).
 
-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.
+## Component API
 
-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).
+A Tasty component's public API is something you design. Instead of handing consumers an open `styles` escape hatch, expose the knobs they need as typed props.
 
-### Style Props
+### Style props
 
-`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.
+`styleProps` turns selected style properties into props. They accept state maps, so responsive values use the same syntax:
 
 ```tsx
+import { tasty, FLOW_STYLES } from '@tenphi/tasty';
+
 const Space = tasty({
   styles: { display: 'flex', flow: 'column', gap: '1x' },
   styleProps: FLOW_STYLES,
 });
 
-<Space flow="row" gap={{ '': '2x', '@tablet': '4x' }}>
+<Space flow="row" gap={{ '': '2x', '@mobile': '1x' }} />;
 ```
 
-See [React API - Style Props](docs/react-api.md#style-props) and [Methodology - styleProps](docs/methodology.md#styleprops-as-the-public-api).
+### Mod props
 
-### Mod Props
+`modProps` exposes modifiers as typed props (`<Button isLoading size="lg">`, as in the [Quick Start](#3-add-states-and-a-typed-api)). Use `Boolean`, `String`, `Number`, or a `const` array of allowed values.
 
-`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.
+### Token props
+
+`tokenProps` handles values that change often, such as progress, user-picked colors, or measured sizes. They set custom properties inline, so the class name and the CSS stay the same while the value changes:
 
 ```tsx
-const Button = tasty({
-  as: 'button',
-  modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const },
-  styles: {
-    fill: { '': '#primary', isLoading: '#primary.5' },
-    padding: { '': '2x 4x', 'size=sm': '1x 2x' },
+const Progress = tasty({
+  tokenProps: ['progress', 'accentColor'] as const,
+  styles: { width: '$progress', fill: '#accent' },
+});
+
+<Progress progress="75%" accentColor="#purple" />;
+// style="--progress:75%;--accent-color:var(--purple-color)"
+```
+
+### Variants
+
+Variants are named style sets. `variant` is typed from their keys, `default` applies when no `variant` is passed, and only the variants actually rendered emit CSS:
+
+```tsx
+const Badge = tasty({
+  styles: { padding: '.5x 1x', radius: '1r' },
+  variants: {
+    default: { fill: '#surface', color: '#text' },
+    danger: { fill: '#danger', color: '#on-danger' },
   },
 });
 
-<Button isLoading size="lg">Submit</Button>
+<Badge variant="danger">Failed</Badge>;
 ```
 
-See [React API - Mod Props](docs/react-api.md#mod-props) and [Methodology - modProps](docs/methodology.md#modprops-and-mods).
+### Sub-elements
 
-### Variants
+Compound components style their inner parts from one definition. `elements` produces typed sub-components:
 
-Variants let one component expose named visual versions without pre-generating a separate class for every possible combination. In runtime mode, Tasty emits only the variant CSS that is actually used.
+```tsx
+const Card = tasty({
+  styles: {
+    padding: '4x',
+    Title: { preset: 'h3', color: { '': '#text', ':hover': '#primary' } },
+    Content: { color: '#text' },
+  },
+  elements: { Title: 'h3', Content: 'div' },
+});
 
-See [React API - Variants](docs/react-api.md#variants).
+<Card>
+  <Card.Title>Revenue</Card.Title>
+  <Card.Content>Up 12% this week</Card.Content>
+</Card>;
+```
 
-### Recipes
+Sub-elements share the root's state context: `:hover` inside `Title` means "when the card is hovered". Use `@own(...)` when a part should react to its own state, and the `$` selector affix for precise descendant targeting.
 
-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.
+All of these are covered in [React API](docs/react-api.md). For guidance on what to expose and when, see [Methodology](docs/methodology.md).
 
-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.
+## Types and Linting
 
-See [Style DSL - Recipes](docs/dsl.md#recipes) and [Configuration - recipes](docs/configuration.md#recipes).
+### TypeScript
 
-### Auto-Inferred `@property`
+Component props are typed from their definitions: `modProps` value lists become unions, `variant` is typed from the variant keys, style props are typed like the styles they expose, and sub-elements are typed components. Register your design system's names to get autocomplete inside style values too:
 
-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.
+```ts
+// tasty.d.ts
+import '@tenphi/tasty';
 
-If you prefer explicit control, disable inference with `configure({ autoPropertyTypes: false })` or declare the properties yourself.
+declare module '@tenphi/tasty' {
+  // '#surface', '#primary.50' in fill, color, and other color props
+  interface TastyNamedColors {
+    surface: true;
+    primary: true;
+  }
+  // preset: 'h1'
+  interface TastyPresetNames {
+    h1: true;
+    t2: true;
+  }
+  // <Button theme="danger" />
+  interface TastyThemeNames {
+    danger: true;
+  }
+}
+```
 
-See [Style DSL - Properties (`@property`)](docs/dsl.md#properties-property).
+`StylesInterface`, `TastyCustomProps`, and `TastyBaseStylePropNames` type the style properties, component props, and base style props your plugins add. See [Configuration → TypeScript](docs/configuration.md#typescript).
 
-### Explicit `@property`
+### ESLint and oxlint
 
-Use explicit `@property` only when you need to override defaults such as `inherits: false` or a custom `initialValue`.
+[`@tenphi/eslint-plugin-tasty`](https://github.com/tenphi/eslint-plugin-tasty) validates style objects and JSX style props at lint time:
 
-See [Style DSL - Properties (`@property`)](docs/dsl.md#properties-property).
+```bash
+pnpm add -D @tenphi/eslint-plugin-tasty
+```
 
-### CSS Functions (`@function`)
+```js
+// eslint.config.js
+import tasty from '@tenphi/eslint-plugin-tasty';
 
-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`.
+export default [tasty.configs.recommended]; // or tasty.configs.strict
+```
 
-```jsx
-const Card = tasty({
-  styles: {
-    '@function': {
-      $$negative: { args: ['$value'], result: '(-1 * $value)' },
-    },
-    marginTop: '$$negative(2x)',
-  },
-});
+A `tasty.config.ts` at the project root tells the plugin what your design system defines:
+
+```ts
+// tasty.config.ts
+export default {
+  tokens: ['#surface', '#text', '#primary', '$sidebar-width'],
+  states: ['@mobile', '@dark'],
+  presets: ['h1', 'h2', 't1', 't2'],
+  recipes: ['card', 'elevated'],
+  importSources: ['@my-org/ui'], // modules that re-export tasty()
+};
 ```
 
-Definitions can also come from `configure({ functions })` or the `useFunction` style function, and work across client, SSR/RSC, and zero-runtime modes. `@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.
+With that in place, `recommended` catches:
 
-See [Style DSL - Functions](docs/dsl.md#functions-function) and [Configuration - Polyfills](docs/configuration.md#polyfills).
+- Typos in property names (checked against the full CSS property set) and malformed values
+- Unknown color tokens, units, presets, and recipes (plus `$` tokens and state aliases in `strict`)
+- Invalid state keys, missing `''` defaults, nested state maps, and `!important`
+- Raw colors and pixel lengths where tokens belong, and non-idiomatic syntax such as `calc(...)` or `display: 'none'`, some with autofixes
+- `style`, `className`, and instance `styles` on Tasty components, in favor of their typed API
+- Bad values in JSX style props, such as `<Box fill="red" gap="17px" />`
 
-### Style Functions
+The same rule sets run under oxlint. See the [plugin README](https://github.com/tenphi/eslint-plugin-tasty) for every rule and option.
 
-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.
+## CSS Coverage
 
-See [React API - Style Functions](docs/react-api.md#style-functions).
+Every style property accepts a state map, and every kind of condition is a state key:
 
-### Zero-Runtime Mode
+| State type       | Syntax                     | CSS output                          |
+| ---------------- | -------------------------- | ----------------------------------- |
+| Boolean modifier | `loading`                  | `[data-loading]`                    |
+| Value modifier   | `theme=danger`             | `[data-theme="danger"]`             |
+| Pseudo-class     | `:hover`                   | `:hover`                            |
+| Attribute        | `[aria-selected="true"]`   | `[aria-selected="true"]`            |
+| Class            | `.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"] *)`      |
+| Structural       | `:has(> Icon)`             | `:has(> [data-element="Icon"])`     |
+| Feature query    | `@supports(display: grid)` | `@supports (display: grid)`         |
+| Entry animation  | `@starting`                | `@starting-style`                   |
 
-Use `tastyStatic` when you want the same DSL and state model, but with CSS extracted at build time and no styling runtime in the client bundle. It is a strong fit for static sites, landing pages, and other build-time-first setups.
+Combine them with `&` (and), `|` (or), `!` (not), and `^` (xor): `'theme=danger & :hover'`. The `_` key sets a fallback floor for queries a browser may evaluate as unknown. See [Style DSL](docs/dsl.md).
 
-See [Zero Runtime (tastyStatic)](docs/tasty-static.md) and [Getting Started - Choosing a rendering mode](docs/getting-started.md#choosing-a-rendering-mode).
+At-rules live next to the styles that use them:
 
-### `tasty` vs `tastyStatic`
+```tsx
+const Spinner = tasty({
+  styles: {
+    '@keyframes': { spin: { to: { transform: 'rotate(360deg)' } } },
+    animation: 'spin 1s linear infinite',
+  },
+});
+```
 
-`tasty()` returns React components that compute CSS during rendering. In server-only contexts, this produces static HTML + CSS with zero client JavaScript — the same end result as `tastyStatic()` but with the full feature set. `tastyStatic()` returns class names and extracts CSS during the build via a Babel plugin, with no React dependency at runtime. Both share the same DSL, tokens, units, state mappings, and recipes. Use `tasty()` as the default for any React-based setup; use `tastyStatic()` when you need build-time extraction without React.
+- **`@keyframes`**: inline, as above, or global via `configure({ keyframes })`.
+- **`@property`**: inferred automatically when a custom property gets a concrete value, so custom properties can transition and animate with no boilerplate. Declare one explicitly to change `inherits` or the initial value.
+- **`@font-face`** and **`@counter-style`**: in styles, in `configure()`, or with the matching style function.
+- **`@function`**: define parameterized CSS functions as `$$name` and call them anywhere a value is accepted. An opt-in polyfill inlines the calls for browsers that do not support it yet.
 
-See [Zero Runtime (tastyStatic)](docs/tasty-static.md), [React API](docs/react-api.md), and [Comparison - Build-time vs runtime](docs/comparison.md#build-time-vs-runtime).
+Tasty also ships its own style properties (`fill`, `flow`, `radius`, `preset`, `fade`, `scrollbar`, `hide`, and more), documented in [Style Properties](docs/styles.md). `@layer` and `!important` are intentionally left out: they would bring back the priority fights that state maps remove.
 
-### Server-Side Rendering
+### Style functions
 
-`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 (Next.js RSC, Astro without islands), they produce zero client JavaScript with the full feature set.
+When you don't need a component, call the style functions directly: `useStyles` for a class name, `useGlobalStyles` for selector-scoped global CSS, `useRawCSS` for raw rules, plus `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction`. Apart from `useStyles`, which reads React context, they are plain functions despite the `use` prefix, so they work in React Server Components and outside React; `computeStyles` is the hook-free equivalent of `useStyles`. See [React API — Style Functions](docs/react-api.md#style-functions).
 
-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:
+## Rendering Modes
 
-- `@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
+The DSL, tokens, units, state maps, and recipes are the same everywhere. What changes is where CSS is generated:
 
-See the [full SSR guide](docs/ssr.md).
+| Approach                  | Authoring API                               | CSS is generated                    | Tasty runtime in the browser | Best for                                                         |
+| ------------------------- | ------------------------------------------- | ----------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
+| **Server-only React**     | `tasty()` plus `@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, CSS needed before rendering                |
 
-## Entry Points
+- **`tasty()` renders on the server.** Components are hook-free and render as React Server Components by default. Rendered only on the server, they keep the full React API (`styleProps`, sub-elements, variants) and ship no styling runtime. Astro's `tastyIntegration({ islands: false })` is the verified zero-JavaScript setup; server-only Next.js RSC follows the same architecture. Without an integration, each element inlines its own CSS and configured tokens and global styles are not emitted, so use one for anything that relies on `configure()`.
+- **SSR integrations** add CSS batching, cross-tree deduplication, FOUC prevention, and client cache hydration for apps that also render on the client: `TastyRegistry` from `@tenphi/tasty/ssr/next` (plus `withTastyNext()` from `@tenphi/tasty/ssr/next-config` for a shared global stylesheet), `tastyIntegration()` from `@tenphi/tasty/ssr/astro`, and a core API for other React SSR setups. Streaming is supported.
+- **`tastyStatic()`** returns class names and extracts CSS during the build through a Babel plugin, with no React dependency. File mode ships no runtime; inject mode ships a tiny CSS injector.
 
-| Import | Description | Platform |
-|--------|-------------|----------|
-| `@tenphi/tasty` | Runtime style engine (`tasty`, style functions, `configure`) | Browser |
-| `@tenphi/tasty/static` | Zero-runtime static styles (`tastyStatic`) | Browser |
-| `@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 zero-runtime 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 |
+See [Server-Side Rendering](docs/ssr.md), [Build-Time Extraction](docs/tasty-static.md), and [Choosing a rendering mode](docs/getting-started.md#choosing-a-rendering-mode).
 
-## Browser Requirements
+## Tooling
 
-Tasty's exclusive selector system relies on modern CSS pseudo-class syntax:
+### ESLint plugin
 
-- **`:is()`** — available across all major browsers since January 2021 ([MDN Baseline](https://developer.mozilla.org/en-US/docs/Web/CSS/:is)).
-- **Level-4 `:not()` with selector lists** — Chrome/Edge 88+, Firefox 84+, Safari 9+, Opera 75+.
-- **Not supported:** IE 11.
+Covered in [Types and Linting](#eslint-and-oxlint): 40+ rules for ESLint 9+ and oxlint, configured from `tasty.config.ts`.
 
-## Performance
+### VS Code extension
 
-### Bundle Size
+[Tasty for VS Code](https://github.com/tenphi/tasty-vscode-extension) highlights color tokens, units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, `styles` objects, and style functions, and adds snippets for components, state maps, and `configure()`. Install the `.vsix` from the [latest release](https://github.com/tenphi/tasty-vscode-extension/releases/latest).
 
-All sizes measured with [size-limit](https://github.com/ai/size-limit) — minified and brotli-compressed, including all dependencies.
+<p align="center">
+  <img src="assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example" />
+</p>
 
-| Entry point | Size |
-|-------------|------|
-| `@tenphi/tasty` (runtime + SSR) | 50.19 kB |
-| `@tenphi/tasty/core` (runtime, no SSR) | 47.76 kB |
-| `@tenphi/tasty/static` (zero-runtime) | 16.43 kB |
-| `@tenphi/tasty/zero` (programmatic extraction) | 29.6 kB |
-| `@tenphi/tasty/babel-plugin` (Babel plugin entry) | 43.7 kB |
+### Glaze
 
-Run `pnpm size` to reproduce (outputs may shift slightly with releases).
+[`@tenphi/glaze`](https://github.com/tenphi/glaze) generates light, dark, and high-contrast themes from one hue in the OKHST color space, solves WCAG and APCA contrast, and exports Tasty tokens directly (as well as CSS, DTCG, and Tailwind):
 
-### Runtime Benchmarks
+```ts
+import { glaze } from '@tenphi/glaze';
+import { configure } from '@tenphi/tasty';
 
-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 `pnpm bench` on an Apple M1 Max (Node 22).
+const theme = glaze(280, 80); // hue, saturation
+theme.colors({
+  surface: { tone: 97, saturation: 0.15 },
+  text: { base: 'surface', tone: '-1', contrast: 'AA' },
+});
 
-| Operation | ops/sec | Latency (mean) |
-|-----------|--------:|---------------:|
-| `renderStyles` — 5 flat properties (cold) | ~60,000 | ~17 us |
-| `renderStyles` — state map with media/hover/modifier (cold) | ~18,500 | ~54 us |
-| `renderStyles` — same styles (cached) | ~5,800,000 | ~0.17 us |
-| `parseStateKey` — simple key like `:hover` (cold) | ~790,000 | ~1.3 us |
-| `parseStateKey` — complex OR/AND/NOT key (cold) | ~140,000 | ~7 us |
-| `parseStateKey` — any key (cached) | ~3,400,000–8,300,000 | ~0.1–0.3 us |
-| `parseStyle` — value tokens like `2x 4x` (cold) | ~344,000 | ~2.9 us |
-| `parseStyle` — color tokens (cold) | ~567,000 | ~1.8 us |
-| `parseStyle` — any value (cached) | ~15,250,000 | ~0.07 us |
+configure({ tokens: theme.tasty() }); // #surface and #text, light and dark
+```
 
-"Cold" benchmarks use unique inputs to bypass all caches. Cached benchmarks reuse a single input and measure the LRU hot path. Expect roughly ±10% between runs on an otherwise idle machine.
+### Debugging
 
-Run `pnpm bench` to reproduce. `pnpm bench:browser` runs the component-render benchmarks separately, in headless Chromium — those are useful for comparing variants against each other (a plain element vs. one with sub-elements), but the browser's 0.1 ms timer resolution makes their absolute values too coarse to quote. The two suites are deliberately separate commands: running them together lets the browser compete with Node for CPU and depresses both.
+`tastyDebug` inspects what Tasty injected, straight from the browser console:
 
-#### What This Means in Practice
+```ts
+import { tastyDebug } from '@tenphi/tasty';
 
-- **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 ~54 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 10x–300x.** The parser sees ~30x, state-key parsing ~10x–25x, and the full pipeline ~100x on flat styles and ~300x on complex state maps — the deeper the work, the more the cache saves. 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 ~17 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 250 us and 100 unique components under 25 ms — still well within a single frame budget. The cached path remains sub-microsecond on all devices.
+tastyDebug.install(); // exposes window.tastyDebug
+tastyDebug.inspect('.my-button'); // classes, chunks, and the CSS that applies
+```
 
-### How It Stays Fast
+See [Debug Utilities](docs/debug.md).
 
-- CSS is generated and injected only when styles are actually used.
-- Multi-level caching avoids repeated parsing and style recomputation.
-- Styles are split into reusable chunks and applied as multiple class names, so matching chunks can be reused across components instead of re-injected.
-- 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.
-- This approach is validated in enterprise-scale apps where runtime styling overhead is not noticeable in normal UI flows.
+### AI coding agents
 
-## Ecosystem
+Style definitions are declarative and fully typed, so agents can read and write them reliably. [Style Rules for AI Agents](docs/ai-agents.md) is a one-page brief to add to an agent's context.
 
-Tasty is the core of a production-ready styling platform. These companion tools complete the picture:
+## Performance
 
-### [ESLint Plugin](https://github.com/tenphi/eslint-plugin-tasty)
+### Bundle size
 
-`@tenphi/eslint-plugin-tasty` — 27 total lint rules for style property names, value syntax, token existence, state keys, and best practices. The `recommended` preset enables 18 of them as a practical default. Catch typos and invalid styles at lint time, not at runtime.
+Measured with [size-limit](https://github.com/ai/size-limit): minified and brotli-compressed, including all dependencies.
 
-```bash
-pnpm add -D @tenphi/eslint-plugin-tasty
-```
+| Entry point                                       | Size     |
+| ------------------------------------------------- | -------- |
+| `@tenphi/tasty`, importing `tasty`                | 50.79 kB |
+| `@tenphi/tasty`, everything                       | 57.54 kB |
+| `@tenphi/tasty/core`, everything (no SSR)         | 54.45 kB |
+| `@tenphi/tasty/static` (build-time authoring API) | 920 B    |
+| `@tenphi/tasty/ssr/astro-client`                  | 283 B    |
+| `@tenphi/tasty/zero` (Node, build time)           | 37.57 kB |
+| `@tenphi/tasty/babel-plugin` (Node, build time)   | 41.65 kB |
 
-```js
-import tasty from '@tenphi/eslint-plugin-tasty';
-export default [tasty.configs.recommended];
-```
+Run `pnpm size` to reproduce; numbers shift slightly between releases.
 
-### [Glaze](https://github.com/tenphi/glaze)
+### Runtime
 
-`@tenphi/glaze` — OKHSL-based color theme generator with automatic WCAG contrast solving. Generate light, dark, and high-contrast palettes from a single hue, and export them directly as Tasty color tokens.
+When styles are generated in the browser:
 
-```tsx
-import { glaze } from '@tenphi/glaze';
+- CSS is generated and injected only for styles that are actually rendered.
+- Styles are split into chunks and normalized, so equivalent styles resolve to the same classes and are reused across components instead of re-injected.
+- Multi-level caching avoids re-parsing and recomputation.
+- Unused styles can be garbage-collected over time with `configure({ gc })`, or on demand with `gc()` and `cleanup()`.
+- Optional [batched injection](docs/configuration.md#batched-injection) groups stylesheet writes before layout reads.
+- The approach runs in enterprise-scale apps where runtime styling overhead is not noticeable in normal UI flows.
 
-const theme = glaze(280, 80);
-theme.colors({
-  surface: { lightness: 97 },
-  text: { base: 'surface', lightness: '-52', contrast: 'AAA' },
-});
+Reproducible benchmarks cover the core pipeline, the React overhead of an empty `tasty({})` wrapper, cold generation and injection against equivalent precompiled CSS, steady-state interactions, and page-load cold start. See [Runtime Benchmarks](docs/runtime-benchmarks.md) for methodology and results.
 
-const tokens = theme.tasty(); // Ready-to-use Tasty tokens
-```
+## Browser Support
 
-### [VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)
+Exclusive selectors rely on `:is()`, `:where()`, and level-4 `:not()` with selector lists: Chrome and Edge 88+, Firefox 84+, Safari 14+. Internet Explorer is not supported.
 
-Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, and related APIs.
+## Entry Points
 
-<p align="center">
-  <img src="assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example">
-</p>
+| Import                           | Description                                                                                             | Platform       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- |
+| `@tenphi/tasty`                  | React style engine (`tasty`, style functions, `configure`)                                              | Browser / Node |
+| `@tenphi/tasty/core`             | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | 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/babel-plugin`     | Babel plugin for build-time CSS extraction                                                              | Node           |
+| `@tenphi/tasty/zero`             | Programmatic extraction API                                                                             | Node           |
+| `@tenphi/tasty/zero/next`        | Next.js wrapper for build-time extraction                                                               | Node           |
+| `@tenphi/tasty/ssr`              | Core SSR API (collector, context, hydration)                                                            | Node           |
+| `@tenphi/tasty/ssr/next`         | Next.js App Router SSR integration (`TastyRegistry`)                                                    | Node           |
+| `@tenphi/tasty/ssr/next-config`  | Next.js config wrapper for a shared global stylesheet (`withTastyNext`)                                 | Node           |
+| `@tenphi/tasty/ssr/astro`        | Astro integration and middleware                                                                        | Node           |
+| `@tenphi/tasty/ssr/astro-client` | Astro client-side cache hydration                                                                       | Browser        |
 
 ## Built with Tasty
 
 ### [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.
+
+### [Cookbook](https://cookbook.tenphi.me) ([source](https://github.com/tenphi/cookbook))
+
+`@tenphi/cookbook` builds a static Astro documentation site from your repository or a published npm package. Brand colors, semantic palettes, fonts, typography, and individual component parts are configured through Tasty and Glaze, so the docs match your product.
 
 ### [Cube Cloud](https://cube.dev/)
 
@@ -619,47 +661,43 @@ 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 styling approach.
-
-- **[Docs Hub](docs/README.md)** — audience-based navigation across onboarding, design-system authoring, runtime, zero-runtime, runtime SSR integration, debugging, and internals
-
-### Start here
-
-- **[Getting Started](docs/getting-started.md)** — Installation, first component, optional shared configuration, ESLint plugin setup, editor tooling, and rendering mode decision tree
-- **[Methodology](docs/methodology.md)** — The recommended patterns for structuring Tasty components: root + sub-elements, styleProps, tokens, styles vs style, wrapping and extension
+The [Docs Hub](docs/README.md) routes you by role, rendering mode, and task.
 
-### Guides
+**Start here**
 
-- **[Building a Design System](docs/design-system.md)** — Practical guide to building a DS layer: token vocabulary, state aliases, recipes, primitives, compound components, override contracts
-- **[Adoption Guide](docs/adoption.md)** — Where Tasty sits in the stack, who should adopt it, what you define yourself, and how to introduce it incrementally into an existing design system
+- [Getting Started](docs/getting-started.md) — Install, first component, shared configuration, ESLint, editor tooling, and choosing a rendering mode
+- [Methodology](docs/methodology.md) — The recommended component model: root + sub-elements, `styleProps`, tokens, `styles` vs `style`, wrapping and extension
 
-### Reference
+**Guides**
 
-- **[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
+- [Building a Design System](docs/design-system.md) — Token vocabulary, state aliases, recipes, primitives, compound components, and override contracts
+- [Adoption Guide](docs/adoption.md) — Where Tasty fits, who should adopt it, and how to introduce it incrementally
+- [Comparison](docs/comparison.md) — Tasty next to Tailwind, Panda CSS, vanilla-extract, StyleX, Stitches, and Emotion
 
-### Upgrading
+**Reference**
 
-- **[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
+- [Style DSL](docs/dsl.md) — State maps, tokens, units, colors, extending semantics, recipes, and at-rules
+- [Style Properties](docs/styles.md) — Every enhanced style property: syntax, values, and modifiers
+- [React API](docs/react-api.md) — `tasty()`, component props, variants, sub-elements, and style functions
+- [Configuration](docs/configuration.md) — Everything `configure()` accepts
+- [Plugins & Extension Points](docs/plugins.md) — Custom style handlers, props middleware, and typing your extension
+- [Style Rules for AI Agents](docs/ai-agents.md) — A condensed brief for writing correct styles
 
-### Rendering modes
+**Rendering modes**
 
-- **[Zero Runtime (tastyStatic)](docs/tasty-static.md)** — Build-time static styling: 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
+- [Server-Side Rendering](docs/ssr.md) — Next.js, Astro, and generic React SSR: streaming, cache hydration, and troubleshooting
+- [Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md) — Babel plugin setup, Next.js integration, and static style patterns
 
-### Internals
+**Internals**
 
-- **[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
+- [Style rendering pipeline](docs/pipeline.md) — How state maps become mutually exclusive CSS rules
+- [Style Injector](docs/injector.md) — Deduplication, reference counting, cleanup, SSR, and Shadow DOM
+- [Debug Utilities](docs/debug.md) — Inspecting CSS, elements, caches, and chunks at runtime
+- [Runtime Benchmarks](docs/runtime-benchmarks.md) — Methodology and results
 
-### Context
+**Upgrading**
 
-- **[Comparison](docs/comparison.md)** — How Tasty compares to Tailwind, Panda CSS, vanilla-extract, StyleX, Stitches, and Emotion: positioning, trade-offs, and when each tool fits best
+- [Migration Guide (v2 → v3)](docs/migration-v3.md) — Every breaking change in 3.0, with a search-and-replace cheat sheet
 
 ## License