@tenphi/tasty 0.14.0 → 0.14.1

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>Deterministic styling for stateful component systems.</strong><br>
+  A design-system styling engine that compiles component states into mutually exclusive selectors.
 </p>
 
 <p align="center">
@@ -17,23 +17,30 @@
 
 ---
 
-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.
+Tasty is a styling engine for design systems that generates deterministic CSS for stateful components. It compiles state maps into **mutually exclusive selectors**, so each property resolves from declared state logic instead of selector competition.
 
-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.
+It fits best when a team is defining a house styling language for reusable components: tokens, style props, state aliases, recipes, and sub-element rules that need to stay predictable as the system grows.
 
 ## 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).
+- **Deterministic composition, not cascade fights** — Tasty generates mutually exclusive selectors, so stateful styles resolve from the state map you declared rather than source order or specificity accidents. See [How It Actually Works](#how-it-actually-works).
+- **Built for design-system teams** — Best fit for teams building reusable components with intersecting states, variants, tokens, sub-elements, responsive rules, and extension semantics that must stay predictable over time.
+- **A governed styling model, not just syntax sugar** — Tasty is not just a syntax layer. It gives design-system teams a way to define the styling language product teams consume: tokens, units, recipes, style props, state aliases, and sub-element rules.
+- **DSL that still 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.
+
+### Supporting capabilities
+
+- **Typed style 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).
+- **Runtime, SSR, and zero-runtime options** — Use `tasty()` for runtime React components, add SSR integrations when your framework renders that runtime on the server, or use `tastyStatic()` when you specifically want build-time extraction instead of runtime styling.
+- **Broad modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, `@keyframes`, 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 reusable component styling stays deterministic as systems grow. For the full mechanism, jump to [How It Actually Works](#how-it-actually-works).
 
 ## Installation
 
@@ -56,20 +63,13 @@ yarn add @tenphi/tasty
 
 ## 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: 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
 
-## 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,12 +82,12 @@ 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: 'okhsl(88% 0.02 255)',
-    radius: '1r',
+    padding: '24px',
+    gap: '12px',
+    fill: 'white',
+    color: '#222',
+    border: '1px solid #ddd',
+    radius: '12px',
   },
 });
 
@@ -95,7 +95,7 @@ const Card = tasty({
 <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 plain and config-free. 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).
 
@@ -165,9 +165,9 @@ Use `configure()` once when your app or design system needs shared aliases, toke
 
 ### CSS properties as props
 
-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.
+Beyond state resolution, Tasty can also expose selected style controls as typed component props. That lets design systems keep layout and composition inside governed component APIs instead of pushing teams toward wrapper elements or ad hoc styling escapes.
 
-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.
+With `styleProps`, a component can expose the styles you choose as normal typed props. You can adjust layout, spacing, alignment, or positioning where the component is used while staying inside a typed, design-system-aware API.
 
 ```tsx
 import { tasty, FLOW_STYLES, POSITION_STYLES } from '@tenphi/tasty';
@@ -216,13 +216,24 @@ The same props also support state maps, so responsive values use the exact same
 
 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()`.
 
+## 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** | `@tenphi/tasty` | Interactive apps with reusable stateful components 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 |
+
+If your framework can execute runtime React code on the server, you can also add **SSR on top of runtime** with `@tenphi/tasty/ssr/*`. This uses the same `tasty()` pipeline, but collects CSS during server rendering and hydrates the cache on the client. That is the model for Next.js, generic React SSR, and Astro islands. 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)**.
 
-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.
 
@@ -235,7 +246,11 @@ A small example makes this tangible. Two rules for a button's background:
 
 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.
 
-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.
+### 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.
+
+### What Tasty generates instead
 
 Tasty solves both problems at once: **every state mapping compiles into mutually exclusive selectors.**
 
@@ -280,8 +295,6 @@ Better — but the bare `.t0` default still matches unconditionally. It matches
 
 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:
-
 ```css
 /* Branch 1: Explicit dark schema */
 :root[data-schema="dark"] .t0.t0 {
@@ -308,9 +321,11 @@ Tasty generates the correct version automatically:
 }
 ```
 
+### 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)
 
@@ -533,7 +548,7 @@ module.exports = {
 | **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 |
+| **Best for** | Interactive apps with reusable stateful components, design systems | Static sites, SSG, landing pages |
 
 Both share the same DSL, tokens, units, state mappings, and recipes.
 
@@ -714,9 +729,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, runtime, zero-runtime, runtime SSR integration, debugging, and internals
 
 ### Start here
 

package/dist/styles/types.d.ts

@@ -40,6 +40,7 @@ type PresetNameKey = Extract<keyof TastyPresetNames, string>;
 type PresetName = [PresetNameKey] extends [never] ? string : PresetNameKey;
 type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 type OpaquePercentage = '' | `.${Digit}` | `.${Digit}${Digit}` | '.100';
+type ColorValue = `#${NamedColor}${OpaquePercentage}` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})` | (string & {});
 type NoType = false | null | undefined;
 interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' | 'font' | 'outline' | 'type' | 'gap' | 'padding' | 'margin' | 'width' | 'height' | 'border' | 'transition' | 'placeContent' | 'placeItems'> {
   /**
@@ -57,13 +58,20 @@ interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' | 'font'
   /**
    * Set the background color of the element. Shortcut for `background-color` with enhanced support for Tasty color tokens and syntaxes.
    *
+   * Supports double-color syntax: the second color is applied as a foreground overlay via a CSS custom property.
+   *
    * Examples:
    * - `fill="#purple.10"` // purple background with 10% opacity
    * - `fill="#danger"` // danger theme color
    * - `fill="rgb(255 128 0)"` // custom RGB color
+   * - `fill="rgb(255 128 0 / 0.5)"` // RGB with opacity
+   * - `fill="hsl(200 100% 50%)"` // HSL color
+   * - `fill="okhsl(200 100% 50%)"` // perceptually uniform OKHSL color
+   * - `fill="oklch(0.7 0.15 200)"` // OKLCH color
+   * - `fill="#primary #secondary"` // double color (second as foreground overlay)
    * - `fill={true}` // default fill color
    */
-  fill?: `#${NamedColor}${OpaquePercentage}` | `rgb(${string})` | `rgba(${string})` | boolean | (string & {});
+  fill?: ColorValue | boolean;
   /**
    * @deprecated Use `fill` instead.
    */
@@ -92,19 +100,26 @@ interface StylesInterface extends Omit<CSSProperties, 'color' | 'fill' | 'font'
    * - `svgFill="#purple.10"` // purple fill with 10% opacity
    * - `svgFill="#danger"` // danger theme color
    * - `svgFill="rgb(255 128 0)"` // custom RGB color
+   * - `svgFill="hsl(200 100% 50%)"` // HSL color
+   * - `svgFill="okhsl(200 100% 50%)"` // OKHSL color
+   * - `svgFill="oklch(0.7 0.15 200)"` // OKLCH color
    * - `svgFill="currentColor"` // inherit from parent color
    */
-  svgFill?: `#${NamedColor}${OpaquePercentage}` | `rgb(${string})` | `rgba(${string})` | (string & {});
+  svgFill?: ColorValue;
   /**
    * Set the text (current) color of the element. Shortcut for `color` with enhanced support for Tasty color tokens and syntaxes.
    *
    * Examples:
    * - `color="#purple"` // purple text color
    * - `color="#danger.6"` // danger color with 60% opacity
+   * - `color="rgb(255 128 0)"` // custom RGB color
+   * - `color="hsl(200 100% 50%)"` // HSL color
+   * - `color="okhsl(200 100% 50%)"` // OKHSL color
+   * - `color="oklch(0.7 0.15 200)"` // OKLCH color
    * - `color="red"` // CSS color name
    * - `color={true}` // currentColor
    */
-  color?: `#${NamedColor}${OpaquePercentage}` | `rgb(${string})` | `rgba(${string})` | boolean | string;
+  color?: ColorValue | boolean;
   /**
    * The fade style applies gradient-based fading masks to the edges of an element. Replaces complex CSS mask gradients with a simple, declarative API.
    *

package/dist/tasty.d.ts

@@ -104,8 +104,8 @@ declare const Element: ForwardRefExoticComponent<AllBaseProps<keyof HTMLElementT
   image?: StyleValue<csstype.Property.BackgroundImage | undefined> | StyleValueStateMap<csstype.Property.BackgroundImage | undefined>;
   marker?: StyleValue<csstype.Property.Marker | undefined> | StyleValueStateMap<csstype.Property.Marker | undefined>;
   mask?: StyleValue<csstype.Property.Mask<string | number> | undefined> | StyleValueStateMap<csstype.Property.Mask<string | number> | undefined>;
-  fill?: StyleValue<boolean | (string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `rgba(${string})` | undefined> | StyleValueStateMap<boolean | (string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `rgba(${string})` | undefined>;
-  color?: StyleValue<string | boolean | undefined> | StyleValueStateMap<string | boolean | undefined>;
+  fill?: StyleValue<boolean | ((string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})`) | undefined> | StyleValueStateMap<boolean | ((string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})`) | undefined>;
+  color?: StyleValue<boolean | ((string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})`) | undefined> | StyleValueStateMap<boolean | ((string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})`) | undefined>;
   font?: StyleValue<boolean | csstype.Property.FontFamily | undefined> | StyleValueStateMap<boolean | csstype.Property.FontFamily | undefined>;
   outline?: StyleValue<string | boolean | undefined> | StyleValueStateMap<string | boolean | undefined>;
   gap?: StyleValue<boolean | csstype.Property.Gap<string | number> | undefined> | StyleValueStateMap<boolean | csstype.Property.Gap<string | number> | undefined>;
@@ -957,7 +957,7 @@ declare const Element: ForwardRefExoticComponent<AllBaseProps<keyof HTMLElementT
   colorInterpolation?: StyleValue<csstype.Property.ColorInterpolation | undefined> | StyleValueStateMap<csstype.Property.ColorInterpolation | undefined>;
   colorRendering?: StyleValue<csstype.Property.ColorRendering | undefined> | StyleValueStateMap<csstype.Property.ColorRendering | undefined>;
   glyphOrientationVertical?: StyleValue<csstype.Property.GlyphOrientationVertical | undefined> | StyleValueStateMap<csstype.Property.GlyphOrientationVertical | undefined>;
-  svgFill?: StyleValue<(string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `rgba(${string})` | undefined> | StyleValueStateMap<(string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `rgba(${string})` | undefined>;
+  svgFill?: StyleValue<((string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})`) | undefined> | StyleValueStateMap<((string & {}) | `#${string}` | `#${string}.0` | `#${string}.1` | `#${string}.2` | `#${string}.7` | `#${string}.3` | `#${string}.4` | `#${string}.5` | `#${string}.6` | `#${string}.8` | `#${string}.9` | `#${string}.00` | `#${string}.01` | `#${string}.02` | `#${string}.07` | `#${string}.03` | `#${string}.04` | `#${string}.05` | `#${string}.06` | `#${string}.08` | `#${string}.09` | `#${string}.10` | `#${string}.11` | `#${string}.12` | `#${string}.17` | `#${string}.13` | `#${string}.14` | `#${string}.15` | `#${string}.16` | `#${string}.18` | `#${string}.19` | `#${string}.20` | `#${string}.21` | `#${string}.22` | `#${string}.27` | `#${string}.23` | `#${string}.24` | `#${string}.25` | `#${string}.26` | `#${string}.28` | `#${string}.29` | `#${string}.70` | `#${string}.71` | `#${string}.72` | `#${string}.77` | `#${string}.73` | `#${string}.74` | `#${string}.75` | `#${string}.76` | `#${string}.78` | `#${string}.79` | `#${string}.30` | `#${string}.31` | `#${string}.32` | `#${string}.37` | `#${string}.33` | `#${string}.34` | `#${string}.35` | `#${string}.36` | `#${string}.38` | `#${string}.39` | `#${string}.40` | `#${string}.41` | `#${string}.42` | `#${string}.47` | `#${string}.43` | `#${string}.44` | `#${string}.45` | `#${string}.46` | `#${string}.48` | `#${string}.49` | `#${string}.50` | `#${string}.51` | `#${string}.52` | `#${string}.57` | `#${string}.53` | `#${string}.54` | `#${string}.55` | `#${string}.56` | `#${string}.58` | `#${string}.59` | `#${string}.60` | `#${string}.61` | `#${string}.62` | `#${string}.67` | `#${string}.63` | `#${string}.64` | `#${string}.65` | `#${string}.66` | `#${string}.68` | `#${string}.69` | `#${string}.80` | `#${string}.81` | `#${string}.82` | `#${string}.87` | `#${string}.83` | `#${string}.84` | `#${string}.85` | `#${string}.86` | `#${string}.88` | `#${string}.89` | `#${string}.90` | `#${string}.91` | `#${string}.92` | `#${string}.97` | `#${string}.93` | `#${string}.94` | `#${string}.95` | `#${string}.96` | `#${string}.98` | `#${string}.99` | `#${string}.100` | `rgb(${string})` | `hsl(${string})` | `okhsl(${string})` | `oklch(${string})`) | undefined>;
   fade?: StyleValue<string | undefined> | StyleValueStateMap<string | undefined>;
   scrollbar?: StyleValue<string | boolean | undefined> | StyleValueStateMap<string | boolean | undefined>;
   boldFontWeight?: StyleValue<number | undefined> | StyleValueStateMap<number | undefined>;

package/docs/README.md

@@ -1,12 +1,13 @@
 # Tasty Docs
 
-Use this page when you know what you want to do, but not which document to open next.
+Tasty is a styling engine for design systems that turns component state into deterministic CSS by compiling state maps into mutually exclusive selectors. Use this hub to choose the right guide once you know whether you are evaluating the model, adopting it in a design system, or implementing with it day to day.
 
 ## Start Here
 
 - **New to Tasty**: [Getting Started](getting-started.md) for installation, the first component, optional shared `configure()`, ESLint, editor tooling, and rendering mode selection.
 - **Learning the component model**: [Methodology](methodology.md) for root + sub-elements, `styleProps`, tokens, extension, and recommended boundaries between `styles`, `style`, and wrappers.
-- **Evaluating fit**: [Comparison](comparison.md) for tool-selection context, then [Adoption Guide](adoption.md) for rollout strategy inside a design system.
+- **Evaluating the selector model**: [Style rendering pipeline](PIPELINE.md) for how mutually exclusive selectors make stateful styling deterministic.
+- **Evaluating fit**: [Comparison](comparison.md) for tool-selection context, then [Adoption Guide](adoption.md) for audience fit and rollout strategy inside a design system.
 
 ## By Role
 
@@ -14,11 +15,11 @@ Use this page when you know what you want to do, but not which document to open
 - **Design-system author**: [Methodology](methodology.md), [Building a Design System](design-system.md), [Configuration](configuration.md), and [Adoption Guide](adoption.md).
 - **Platform or tooling engineer**: [Configuration](configuration.md), [Zero Runtime (tastyStatic)](tasty-static.md), [Server-Side Rendering](ssr.md), and [Debug Utilities](debug.md).
 
-## By Rendering Mode
+## By Styling Approach
 
 - **Runtime React components**: [Runtime API](runtime.md)
 - **Zero-runtime / build-time extraction**: [Zero Runtime (tastyStatic)](tasty-static.md)
-- **SSR with runtime `tasty()`**: [Server-Side Rendering](ssr.md)
+- **Runtime `tasty()` with server collection and hydration**: [Server-Side Rendering](ssr.md)
 
 ## By Task
 

package/docs/adoption.md

@@ -1,6 +1,6 @@
 # Adoption Guide
 
-Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**. That means the adoption path is not "rewrite your classes" but "reshape your styling architecture."
+Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**: what the comparison guide calls a house styling language. That means adoption usually starts where styling has already become a composition problem, not with an all-at-once rewrite.
 
 This guide is for design-system maintainers and platform engineers evaluating Tasty or introducing it into an existing codebase. Use this document for rollout strategy and adoption sequencing; use the [Comparison guide](comparison.md) when the open question is whether Tasty is the right tool in the first place.
 
@@ -116,6 +116,8 @@ See [Configuration](configuration.md) for the full `configure()` API.
 
 You do not need to adopt everything at once. Tasty is designed to be introduced layer by layer.
 
+A practical way to start is with the components that already suffer from intersecting state and variant logic: buttons, inputs, menus, disclosures, dialogs, list items, interactive cards, and compound components. Those are the places where deterministic resolution pays off fastest.
+
 ### Phase 1 -- Tokens and units
 
 Start by defining your design tokens and custom units. This is the lowest-risk step: it only configures the parser and does not require rewriting any components.
@@ -161,7 +163,7 @@ configure({
 
 ### Phase 3 -- Migrate a few primitives
 
-Pick 2-3 simple, widely used components (Box, Text, Button) and rewrite them with `tasty()`. Keep the public API identical so product code does not need to change.
+Pick 2-3 widely used primitives (Box, Text, Button) and rewrite them with `tasty()`. Keep the public API identical so product code does not need to change.
 
 ```tsx
 const Box = tasty({
@@ -175,11 +177,11 @@ const Box = tasty({
 });
 ```
 
-At this point you can validate the DSL, token workflow, and component authoring experience before committing further.
+At this point you can validate the DSL, token workflow, and component authoring experience before expanding the rollout.
 
 ### Phase 4 -- Encode complex states
 
-Move components with intersecting states (buttons with hover + disabled + theme variants, inputs with focus + error + readonly) to Tasty's state map syntax. This is where mutually exclusive selectors start paying off.
+Move the components with the most painful intersecting states (buttons with hover + disabled + theme variants, inputs with focus + error + readonly) to Tasty's state map syntax. This is where mutually exclusive selectors start paying off.
 
 ```tsx
 const Button = tasty({

package/docs/comparison.md

@@ -4,6 +4,10 @@ Use this guide when you are deciding whether Tasty is the right tool. If you hav
 
 Tasty is best understood not as a general-purpose CSS framework, but as a **styling engine for design systems and shared component APIs**.
 
+It targets a different layer: helping design-system teams define a **house styling language** on top of CSS.
+
+That does not require a big upfront configuration step. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
+
 Most styling tools focus on one of these layers:
 
 - direct app styling
@@ -12,9 +16,7 @@ Most styling tools focus on one of these layers:
 - utility composition
 - atomic CSS generation
 
-Tasty targets a different layer: it helps teams define a **house styling language** on top of CSS, including tokens, state semantics, style props, recipes, custom units, and sub-element rules.
-
-That does not mean a big upfront configuration step is required. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
+Tasty's house styling language can include tokens, state semantics, style props, recipes, custom units, and sub-element rules.
 
 That is why syntax-level comparisons are often shallow. The more meaningful comparison is about:
 
@@ -87,9 +89,9 @@ Tasty compiles this into selectors where `disabled` is guarded by `:not(:hover)`
 
 That makes Tasty less of a "better way to write CSS objects" and more of a **state-aware style compiler for design systems**.
 
-Beyond state resolution, Tasty includes several structural capabilities that most other tools do not offer:
+Beyond state resolution, Tasty also provides several structural capabilities that reinforce the design-system layer:
 
-- **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. No other tool provides this as a first-class, typed, design-system-aware feature.
+- **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. This keeps layout and composition controls inside a governed component API instead of pushing teams back to ad hoc styling escapes.
 - **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and `data-element` attributes. States, tokens, and recipes apply across the entire element tree from a single definition. See [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
 - **Auto-inferred `@property`** — When a custom property is assigned a concrete value, Tasty infers the CSS `@property` syntax and registers it automatically, enabling smooth transitions on custom properties without manual declarations.
 - **AI-friendly style definitions** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, refactor, and generate Tasty styles as confidently as a human — no hidden cascade logic or implicit ordering to second-guess.
@@ -122,7 +124,7 @@ So this is not mainly a comparison of syntax. It is a comparison of **governance
 - Tailwind: developers author directly with framework vocabulary
 - Tasty: design-system authors define the vocabulary product teams consume
 
-Tailwind is usually a stronger fit for fast product styling with framework-owned vocabulary. Tasty is usually a stronger fit when teams want direct usability now, but also a path toward governed design-system architecture.
+Tailwind is a stronger fit for fast product styling with framework-owned vocabulary. Tasty is a stronger fit when styling should be exposed through a design-system-owned API and state resolution needs to stay deterministic as the component model grows.
 
 To make this concrete, consider a button with `hover`, `disabled`, and `theme=danger` states.
 
@@ -301,7 +303,7 @@ So while Stitches and Emotion are strong tools for building components, Tasty is
 
 That makes it narrower in audience, but deeper in architectural ambition.
 
-Tasty's runtime performance is also validated in enterprise-scale applications where styling overhead is not noticeable in normal UI flows — an important consideration for teams evaluating runtime CSS-in-JS at scale.
+For teams evaluating runtime styling at scale, Tasty also documents its runtime benchmarks and caching model in the main [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
 
 ---
 

package/docs/design-system.md

@@ -2,7 +2,7 @@
 
 This guide walks through building a design-system styling layer on top of Tasty — defining tokens, state aliases, recipes, primitive components, and compound components with sub-elements.
 
-It assumes you have already decided to adopt Tasty. For evaluation criteria, audience fit, and incremental adoption phases, see the [Adoption Guide](adoption.md). For the recommended component patterns and mental model, see [Methodology](methodology.md).
+It assumes you have already decided to adopt Tasty. The goal is not just to centralize tokens, but to define a styling language whose component states resolve deterministically across variants, responsive rules, and sub-elements. For evaluation criteria, audience fit, and incremental adoption phases, see the [Adoption Guide](adoption.md). For the recommended component patterns and mental model, see [Methodology](methodology.md).
 
 ---
 

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
+This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
 
 ---
 
@@ -10,6 +10,8 @@ This guide walks you from zero to a working Tasty component, then through the op
 - **React** >= 18 (peer dependency)
 - **Package manager**: pnpm, npm, or yarn
 
+Tasty can be used immediately in a React app, but it is most compelling for teams building reusable components with intersecting states, variants, tokens, and design-system conventions.
+
 ---
 
 ## Install
@@ -177,25 +179,25 @@ export default [
 
 ## Choosing a rendering mode
 
-Tasty supports three rendering modes. Pick the one that fits your use case:
+Tasty has two styling approaches. Pick the one that fits your use case, then decide whether your runtime setup also needs server rendering support:
 
-| Mode | Entry point | Best for | Trade-off |
+| Approach | Entry point | Best for | Trade-off |
 |------|-------------|----------|-----------|
-| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
+| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps with reusable stateful components, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
 | **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Static sites, landing pages, SSG | Zero JS overhead; requires Babel plugin; no dynamic props |
-| **SSR** | `@tenphi/tasty/ssr/next` or `@tenphi/tasty/ssr/astro` | Next.js, Astro, streaming SSR | Runtime `tasty()` with server-rendered CSS and zero-cost hydration |
 
-All three share the same DSL, tokens, units, and state mappings.
+Both share the same DSL, tokens, units, and state mappings.
 
 - Runtime is the default and requires no extra setup beyond `@tenphi/tasty`.
+- If your framework can execute runtime code during server rendering, add SSR support on top of runtime with `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API. This still uses `tasty()`; it just collects CSS on the server and hydrates the cache on the client.
 - Zero-runtime requires the Babel plugin and additional peer dependencies. See [Zero Runtime (tastyStatic)](tasty-static.md).
-- SSR works with existing `tasty()` components — wrap your app with a registry or middleware. See [Server-Side Rendering](ssr.md).
+- SSR works with existing `tasty()` components — wrap your app with a registry, middleware, or collector. See [Server-Side Rendering](ssr.md).
 
 ---
 
 ## Next steps
 
-- **[Docs Hub](README.md)** — Pick the next guide by role, rendering mode, or task
+- **[Docs Hub](README.md)** — Pick the next guide by role, styling approach, or task
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
 - **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
@@ -212,4 +214,4 @@ All three share the same DSL, tokens, units, and state mappings.
 
 - Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
 - Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](debug.md).
-- You need zero-runtime or SSR instead of the default runtime path: use [Zero Runtime (tastyStatic)](tasty-static.md) or [Server-Side Rendering](ssr.md) rather than trying to retrofit the runtime setup later.
+- You need build-time extraction or server-rendered CSS delivery: use [Zero Runtime (tastyStatic)](tasty-static.md) for extraction, or add [Server-Side Rendering](ssr.md) on top of runtime `tasty()` when your framework renders on the server.

package/docs/methodology.md

@@ -1,11 +1,13 @@
 # Methodology
 
-Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: better state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
+Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: deterministic state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
 
 ---
 
 ## Component architecture: root + sub-elements
 
+This model matters most for design-system authors and platform teams building reusable, stateful components. It turns Tasty's selector guarantees into a component architecture that stays predictable as states, variants, and compound parts accumulate.
+
 ### The model
 
 Every Tasty component has a **root element** and zero or more **sub-elements**. The root owns the state context. Sub-elements participate in the same context by default.

package/docs/ssr.md

@@ -1,6 +1,6 @@
 # Server-Side Rendering (SSR)
 
-Tasty supports server-side rendering with zero-cost client hydration. Your existing `tasty()` components work unchanged -- SSR is opt-in and requires no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
+Tasty supports server-side rendering with zero-cost client hydration. This does **not** introduce a separate styling engine: SSR uses the same runtime `tasty()` pipeline you already use on the client, then adds server-side CSS collection and client-side cache hydration. Your existing `tasty()` components work unchanged, and SSR remains opt-in with no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
 
 ---
 
@@ -18,7 +18,7 @@ The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies
 
 ## How It Works
 
-During server rendering, `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `useStyles()` skips the rendering pipeline entirely during hydration.
+When the environment can execute runtime React code during server rendering, the same `tasty()` and `useStyles()` calls can run there too. In Next.js, generic React SSR, and Astro islands, Tasty simply changes where that runtime-generated CSS goes: `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `useStyles()` skips the rendering pipeline entirely during hydration.
 
 ```
 Server                         Client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",