@tenphi/tasty 0.13.1 → 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. See [Style Properties](docs/styles.md).
-- **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. See [Configuration](docs/configuration.md).
-- **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 (experimental). 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
 
@@ -41,6 +48,28 @@ That guarantee unlocks a concise, CSS-like DSL where design tokens, custom units
 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
+
+- **[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
+
 ## Quick Start
 
 ### Create a styled component
@@ -53,11 +82,12 @@ const Card = tasty({
   styles: {
     display: 'flex',
     flow: 'column',
-    padding: '4x',
-    gap: '2x',
-    fill: '#surface',
-    border: '#border bottom',
-    radius: '1r',
+    padding: '24px',
+    gap: '12px',
+    fill: 'white',
+    color: '#222',
+    border: '1px solid #ddd',
+    radius: '12px',
   },
 });
 
@@ -65,7 +95,9 @@ const Card = tasty({
 <Card>Hello World</Card>
 ```
 
-Every value maps to CSS you'd recognize — but with tokens and units that keep your design system consistent by default.
+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).
 
 ### Add state-driven styles
 
@@ -112,7 +144,7 @@ const DangerButton = tasty(Button, {
 
 Child styles merge with parent styles intelligently — state maps can extend or replace parent states per-property.
 
-### Configure once, use everywhere
+### Optional: configure shared conventions
 
 ```tsx
 import { configure } from '@tenphi/tasty';
@@ -129,13 +161,13 @@ configure({
 });
 ```
 
-Predefined states turn complex selector logic into single tokens. Use `@mobile` instead of writing media query expressions in every component.
+Use `configure()` once when your app or design system needs shared aliases, tokens, recipes, or parser extensions. Predefined states turn complex selector logic into single tokens, so teams can write `@mobile` instead of repeating media query expressions in every component.
 
 ### CSS properties as props
 
-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';
@@ -184,11 +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.
 
-Traditional CSS has two structural problems.
+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.
 
@@ -201,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.**
 
@@ -246,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 {
@@ -274,14 +321,18 @@ 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 Tasty Playground →](https://cube-ui-kit.vercel.app/?path=/story/getting-started-tasty-playground--playground)
+[Try it in the Cube UI Kit Storybook playground →](https://cube-ui-kit.vercel.app/?path=/story/getting-started-tasty-playground--playground)
 
 ## Capabilities
 
+This section is a quick product tour. For the canonical guides and references, start from the [Docs Hub](docs/README.md).
+
 ### Design Tokens and Custom Units
 
 Tokens are first-class. Colors use `#name` syntax. Spacing, radius, and border width use multiplier units tied to CSS custom properties:
@@ -317,7 +368,7 @@ Every style property accepts a state mapping object. Keys can be combined with b
 | 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(theme=dark)` | `:root[data-theme="dark"]` |
+| 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` |
@@ -478,7 +529,7 @@ module.exports = {
     ['@tenphi/tasty/babel-plugin', {
       output: 'public/tasty.css',
       config: {
-        states: { '@dark': '@root(theme=dark)' },
+        states: { '@dark': '@root(schema=dark)' },
       },
     }],
   ],
@@ -497,25 +548,13 @@ 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.
 
-### Runtime Performance
+### Server-Side Rendering
 
-If you choose the runtime approach, performance is usually a non-issue in practice:
-
-- 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.
-
-### Server-Side Rendering (Experimental)
-
-SSR with zero-cost client hydration. Existing `tasty()` components work unchanged — SSR is opt-in and requires no per-component modifications. Supports Next.js (App Router with streaming), Astro (middleware + islands), and any React-based framework via the core API. Requires React 19+.
+SSR with zero-cost client hydration. Existing `tasty()` components work unchanged — SSR is opt-in and requires no per-component modifications. Supports Next.js (App Router with streaming), Astro (middleware + islands), and any React-based framework via the core API. Requires React 18+.
 
 **Next.js setup:**
 
@@ -553,7 +592,7 @@ export default function RootLayout({
 }
 ```
 
-See the [full SSR guide](docs/ssr.md) for Astro integration, streaming SSR, generic framework usage, and the complete API reference.
+See the [full SSR guide](docs/ssr.md) for Astro integration, streaming SSR, generic framework usage, troubleshooting, and the current requirements.
 
 ## Entry Points
 
@@ -569,13 +608,73 @@ See the [full SSR guide](docs/ssr.md) for Astro integration, streaming SSR, gene
 | `@tenphi/tasty/ssr/next` | Next.js App Router SSR integration | Node |
 | `@tenphi/tasty/ssr/astro` | Astro middleware + auto-hydration | Node / Browser |
 
+## Browser Requirements
+
+Tasty's exclusive selector system relies on modern CSS pseudo-class syntax:
+
+- **`: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.
+
+## Performance
+
+### Bundle Size
+
+All sizes measured with [size-limit](https://github.com/ai/size-limit) — minified and brotli-compressed, including all dependencies.
+
+| Entry point | Size |
+|-------------|------|
+| `@tenphi/tasty` (runtime + SSR) | ~44 kB |
+| `@tenphi/tasty/core` (runtime, no SSR) | ~41 kB |
+| `@tenphi/tasty/static` (zero-runtime) | ~1.5 kB |
+
+Run `pnpm size` for exact up-to-date numbers.
+
+### Runtime Benchmarks
+
+If you choose the runtime approach, performance is usually a non-issue in practice. The numbers below show single-call throughput for the core pipeline stages, measured with `vitest bench` on an Apple M1 Max (Node 22).
+
+| Operation | ops/sec | Latency (mean) |
+|-----------|--------:|---------------:|
+| `renderStyles` — 5 flat properties (cold) | ~72,000 | ~14 us |
+| `renderStyles` — state map with media/hover/modifier (cold) | ~22,000 | ~46 us |
+| `renderStyles` — same styles (cached) | ~7,200,000 | ~0.14 us |
+| `parseStateKey` — simple key like `:hover` (cold) | ~1,200,000 | ~0.9 us |
+| `parseStateKey` — complex OR/AND/NOT key (cold) | ~190,000 | ~5 us |
+| `parseStateKey` — any key (cached) | ~3,300,000–8,900,000 | ~0.1–0.3 us |
+| `parseStyle` — value tokens like `2x 4x` (cold) | ~345,000 | ~3 us |
+| `parseStyle` — color tokens (cold) | ~525,000 | ~1.9 us |
+| `parseStyle` — any value (cached) | ~15,500,000 | ~0.06 us |
+
+"Cold" benchmarks use unique inputs to bypass all caches. Cached benchmarks reuse a single input and measure the LRU hot path.
+
+Run `pnpm bench` to reproduce.
+
+#### What This Means in Practice
+
+- **Cached path dominates production.** After a component's first render, subsequent renders with stable styles skip the pipeline entirely (React `useMemo` + LRU cache hits at every level). All cached operations are sub-microsecond — effectively free.
+- **Cold path is fast enough.** The heaviest cold operation — a complex state map with media queries, hover, and modifiers — takes ~46 us. Even a page with 100 unique styled components adds only ~5 ms of total style computation on first render, negligible next to React reconciliation and DOM work.
+- **Cache multipliers are 30x–100x.** This confirms the multi-level LRU architecture (parser, state-key, simplify, condition, pipeline) is delivering real value.
+- **Comparable to lighter systems.** Emotion's `css()` is typically 5–20 us for simple styles; Tasty's cold `renderStyles` at ~14 us for 5 properties is in the same range despite doing significantly more work (state maps, design tokens, sub-elements, chunking).
+- **On slower devices.** The benchmarks above are from an M1 Max (Geekbench 6 SC ~2,400). A mid-range consumer laptop (~1,800 SC) is roughly 1.3x slower; a mid-range phone (~1,200 SC) is roughly 2x slower; a budget phone (~700 SC) is roughly 3–4x slower. Even at 4x, the heaviest cold operation stays under 200 us and 100 unique components under 20 ms — still well within a single frame budget. The cached path remains sub-microsecond on all devices.
+
+### How It Stays Fast
+
+- 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.
+
 ## Ecosystem
 
 Tasty is the core of a production-ready styling platform. These companion tools complete the picture:
 
 ### [ESLint Plugin](https://github.com/tenphi/eslint-plugin-tasty)
 
-`@tenphi/eslint-plugin-tasty` — 27 lint rules that validate style property names, value syntax, token existence, state keys, and enforce best practices. Catch typos and invalid styles at lint time, not at runtime.
+`@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.
 
 ```bash
 pnpm add -D @tenphi/eslint-plugin-tasty
@@ -630,9 +729,13 @@ 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, configuration, ESLint plugin setup, editor tooling, and rendering mode decision tree
+- **[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
 
 ### Guides
@@ -654,6 +757,7 @@ Open-source React UI kit built on Tasty + React Aria. 100+ production components
 
 ### 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
 

package/dist/config.d.ts

@@ -3,6 +3,7 @@ import { StyleDetails, UnitHandler } from "./parser/types.js";
 import { StyleHandlerDefinition } from "./utils/styles.js";
 import { ConfigTokens, RecipeStyles } from "./styles/types.js";
 import { StyleInjector } from "./injector/injector.js";
+import { ColorSpace } from "./utils/color-space.js";
 import { TastyPlugin } from "./plugins/types.js";
 
 //#region src/config.d.ts
@@ -58,6 +59,17 @@ interface TastyConfig {
    * @example { myFunc: (groups) => groups.map(g => g.output).join(' ') }
    */
   funcs?: Record<string, (groups: StyleDetails[]) => string>;
+  /**
+   * Color space used for decomposed color token companion variables.
+   * Controls the CSS function and suffix for alpha composition.
+   *
+   * - `'rgb'`   — suffix `-rgb`, e.g. `rgb(var(--name-color-rgb) / .5)`
+   * - `'hsl'`   — suffix `-hsl`, e.g. `hsl(var(--name-color-hsl) / .5)`
+   * - `'oklch'` — suffix `-oklch`, e.g. `oklch(var(--name-color-oklch) / .5)`
+   *
+   * @default 'oklch'
+   */
+  colorSpace?: ColorSpace;
   /**
    * Automatically infer and register CSS @property declarations
    * from custom property values found in styles, keyframes, and global config.
@@ -157,7 +169,7 @@ interface TastyConfig {
    * for responsive/theme-aware tokens.
    *
    * - `$name` keys become `--name` CSS custom properties
-   * - `#name` keys become `--name-color` and `--name-color-rgb` properties
+   * - `#name` keys become `--name-color` and `--name-color-{colorSpace}` properties
    *
    * Tokens are injected once when the first style is rendered.
    *

package/dist/config.js

@@ -1,3 +1,4 @@
+import { resetColorSpace, setColorSpace } from "./utils/color-space.js";
 import { isDevEnv } from "./utils/is-dev-env.js";
 import { CUSTOM_UNITS, getGlobalFuncs, getGlobalParser, normalizeColorTokenValue, resetGlobalPredefinedTokens, setGlobalPredefinedTokens } from "./utils/styles.js";
 import { normalizeHandlerDefinition, registerHandler, resetHandlers } from "./styles/predefined.js";
@@ -375,6 +376,8 @@ function configure(config = {}) {
 		const tokenKeys = new Set(Object.keys(mergedConfigTokens));
 		for (const key of Object.keys(mergedReplaceTokens)) if (tokenKeys.has(key)) warnOnce(`token-conflict-${key}`, `[Tasty] Token "${key}" is defined in both \`tokens\` and \`replaceTokens\`. \`replaceTokens\` performs parse-time substitution, so the \`tokens\` CSS custom property will be injected but never used by Tasty styles. Remove it from one of the two.`);
 	}
+	setColorSpace(config.colorSpace ?? "oklch");
+	getGlobalParser().clearCache();
 	if (Object.keys(mergedStates).length > 0) setGlobalPredefinedStates(mergedStates);
 	const parser = getGlobalParser();
 	if (config.parserCacheSize !== void 0) parser.updateOptions({ cacheSize: config.parserCacheSize });
@@ -409,7 +412,7 @@ function configure(config = {}) {
 	}
 	if (Object.keys(mergedConfigTokens).length > 0) setGlobalConfigTokens(mergedConfigTokens);
 	if (Object.keys(mergedRecipes).length > 0) setGlobalRecipes(mergedRecipes);
-	const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, properties: _properties, handlers: _handlers, tokens: _tokens, replaceTokens: _replaceTokens, recipes: _recipes, ...injectorConfig } = config;
+	const { states: _states, parserCacheSize: _parserCacheSize, units: _units, funcs: _funcs, plugins: _plugins, keyframes: _keyframes, properties: _properties, handlers: _handlers, tokens: _tokens, replaceTokens: _replaceTokens, recipes: _recipes, colorSpace: _colorSpace, ...injectorConfig } = config;
 	const fullConfig = {
 		...createDefaultConfig(),
 		...currentConfig,
@@ -450,6 +453,7 @@ function resetConfig() {
 	globalConfigTokens = null;
 	resetGlobalPredefinedTokens();
 	resetHandlers();
+	resetColorSpace();
 	clearPipelineCache();
 	emittedWarnings.clear();
 	const storage = typeof window !== "undefined" ? window : globalThis;