@tenphi/tasty 0.0.0-snapshot.2f99c73 → 0.0.0-snapshot.3006ae0

package/README.md

@@ -5,7 +5,8 @@
 <h1 align="center">Tasty</h1>
 
 <p align="center">
-  A design-system-integrated styling system and DSL for concise, state-aware UI styling
+  <strong>The styling engine built for design systems.</strong><br>
+  Deterministic CSS generation. State-aware DSL. Zero specificity conflicts. Ever.
 </p>
 
 <p align="center">
@@ -16,21 +17,23 @@
 
 ---
 
-Tasty is a powerful CSS-in-JS styling system for React that combines declarative state-aware styling with design system integration. It provides a concise DSL for creating maintainable, themeable components with built-in support for responsive design, dark mode, container queries, and more.
+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.
 
-## Features
+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.
 
-- **Declarative state-aware styling** — style objects with state keys (`hovered`, `disabled`, `@media`, `@root`, etc.)
-- **Design token integration** — color tokens (`#purple`), custom units (`2x`, `1r`), typography presets
-- **Sub-element styling** — style inner elements via capitalized keys with `data-element` attributes
-- **Advanced state mapping** — media queries, container queries, root states, supports queries with boolean logic
-- **Zero-runtime mode** — Babel plugin extracts CSS at build time for static sites
-- **Plugin system** — extensible with custom color functions (OKHSL, etc.)
-- **React hooks** — `useStyles`, `useGlobalStyles`, `useRawCSS` for programmatic style injection
-- **Style extension** — compose and extend styled components with proper merge semantics
-- **Recipes** — named style bundles for reusable patterns
-- **TypeScript-first** — full type definitions with module augmentation support
-- **Tree-shakeable ESM** — unbundled output with `sideEffects: false`
+## 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).
 
 ## Installation
 
@@ -38,17 +41,9 @@ Tasty is a powerful CSS-in-JS styling system for React that combines declarative
 pnpm add @tenphi/tasty
 ```
 
-```bash
-npm install @tenphi/tasty
-```
-
-```bash
-yarn add @tenphi/tasty
-```
-
 ## Quick Start
 
-### Creating Styled Components
+### Create a styled component
 
 ```tsx
 import { tasty } from '@tenphi/tasty';
@@ -56,50 +51,68 @@ import { tasty } from '@tenphi/tasty';
 const Card = tasty({
   as: 'div',
   styles: {
+    display: 'flex',
+    flow: 'column',
     padding: '4x',
-    fill: '#white',
-    border: true,
-    radius: true,
+    gap: '2x',
+    fill: '#surface',
+    border: '#border bottom',
+    radius: '1r',
   },
 });
 
+// Just a React component
 <Card>Hello World</Card>
 ```
 
-### State-Based Styling
+Every value maps to CSS you'd recognize — but with tokens and units that keep your design system consistent by default.
+
+### Add state-driven styles
 
 ```tsx
-const InteractiveCard = tasty({
+const Button = tasty({
+  as: 'button',
   styles: {
+    padding: '1.5x 3x',
     fill: {
-      '': '#white',
-      'hovered': '#gray.05',
-      'pressed': '#gray.10',
-      '@media(w < 768px)': '#surface',
+      '': '#primary',
+      ':hover': '#primary-hover',
+      ':active': '#primary-pressed',
+      '[disabled]': '#surface',
     },
-    padding: {
-      '': '4x',
-      '@media(w < 768px)': '2x',
+    color: {
+      '': '#on-primary',
+      '[disabled]': '#text.40',
+    },
+    cursor: {
+      '': 'pointer',
+      '[disabled]': 'not-allowed',
     },
+    transition: 'theme',
   },
 });
 ```
 
-### Extending Components
+State keys support pseudo-classes first (`:hover`, `:active`), then modifiers (`theme=danger`), attributes (`[disabled]`), media/container queries, root states, and more. Tasty compiles them into exclusive selectors automatically.
+
+### Extend any component
 
 ```tsx
 import { Button } from 'my-ui-lib';
 
-const PrimaryButton = tasty(Button, {
+const DangerButton = tasty(Button, {
   styles: {
-    fill: '#purple',
-    color: '#white',
-    padding: '2x 4x',
+    fill: {
+      '': '#danger',
+      ':hover': '#danger-hover',
+    },
   },
 });
 ```
 
-### Configuration
+Child styles merge with parent styles intelligently — state maps can extend or replace parent states per-property.
+
+### Configure once, use everywhere
 
 ```tsx
 import { configure } from '@tenphi/tasty';
@@ -107,154 +120,546 @@ import { configure } from '@tenphi/tasty';
 configure({
   states: {
     '@mobile': '@media(w < 768px)',
-    '@dark': '@root(theme=dark)',
+    '@tablet': '@media(w < 1024px)',
+    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
   },
   recipes: {
-    card: {
-      padding: '4x',
-      fill: '#surface',
-      radius: '1r',
-      border: true,
-    },
+    card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
   },
 });
 ```
 
-## Entry Points
+Predefined states turn complex selector logic into single tokens. Use `@mobile` instead of writing media query expressions in every component.
 
-| Import | Description | Platform |
-|--------|-------------|----------|
-| `@tenphi/tasty` | Runtime style engine | Browser |
-| `@tenphi/tasty/static` | Build-time static style generation | Browser |
-| `@tenphi/tasty/babel-plugin` | Babel plugin for zero-runtime | Node |
-| `@tenphi/tasty/zero` | Programmatic extraction API | Node |
-| `@tenphi/tasty/next` | Next.js integration wrapper | Node |
+### 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.
+
+This is especially good for prototyping and fast UI iteration: you can shape interfaces quickly, while still staying inside a typed, design-system-aware component API that scales to production.
+
+```tsx
+import { tasty, FLOW_STYLES, POSITION_STYLES } from '@tenphi/tasty';
+
+const Space = tasty({
+  styles: {
+    display: 'flex',
+    flow: 'column',
+    gap: '1x',
+  },
+  styleProps: FLOW_STYLES,
+});
+
+const Button = tasty({
+  as: 'button',
+  styles: {
+    padding: '1.5x 3x',
+    fill: '#primary',
+    color: '#primary-text',
+    radius: true,
+  },
+  styleProps: POSITION_STYLES,
+});
+```
+
+Now you can compose layout and tweak component positioning directly in JSX:
+
+```tsx
+<Space flow="row" gap="2x" placeItems="center">
+  <Title>Dashboard</Title>
+  <Button placeSelf="end">Add Item</Button>
+</Space>
+```
+
+The same props also support state maps, so responsive values use the exact same API:
+
+```tsx
+<Space
+  flow={{ '': 'column', '@tablet': 'row' }}
+  gap={{ '': '2x', '@tablet': '4x' }}
+>
+  <Sidebar />
+  <Content />
+</Space>
+```
+
+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()`.
+
+## How It Actually Works
+
+This is the core idea that makes everything else possible.
+
+Traditional CSS has two structural problems.
+
+First, the **cascade** resolves conflicts by specificity and source order: when multiple selectors match, the one with the highest specificity wins, or — if specificity is equal — the last one in source order wins. That makes styles inherently fragile. Reordering imports, adding a media query, or composing components from different libraries can silently break styling.
+
+A small example makes this tangible. Two rules for a button's background:
+
+```css
+.btn:hover     { background: dodgerblue; }
+.btn[disabled] { background: gray; }
+```
 
-## Core Concepts
+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.
 
-### Design Tokens
+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.
+
+Tasty solves both problems at once: **every state mapping compiles into mutually exclusive selectors.**
 
 ```tsx
-const TokenCard = tasty({
+const Text = tasty({
   styles: {
-    fill: '#surface',        // Color token → var(--surface-color)
-    color: '#text',          // Color token
-    padding: '2x',           // Gap multiplier → calc(var(--gap) * 2)
-    radius: '1r',            // Border radius → var(--radius)
-    border: '1bw solid #border',
+    color: {
+      '': '#text',
+      '@dark': '#text-on-dark',
+    },
+    padding: {
+      '': '4x',
+      '@mobile': '2x',
+    },
   },
 });
 ```
 
+If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))`, try writing the CSS by hand. A first attempt might look like this:
+
+```css
+/* First attempt — the @media branch is too broad */
+.t0 { color: var(--text-color); }
+:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+@media (prefers-color-scheme: dark) {
+  .t0 { color: var(--text-on-dark-color); }
+}
+```
+
+The `@media` branch fires even when `data-schema="light"` is explicitly set. Fix that:
+
+```css
+/* Second attempt — @media is scoped, but the default is still too broad */
+.t0 { color: var(--text-color); }
+:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-schema]) .t0 { color: var(--text-on-dark-color); }
+}
+```
+
+Better — but the bare `.t0` default still matches unconditionally. It matches in dark mode, it matches when `data-schema="dark"` is set, and it can beat the attribute selector by source order if another rule re-declares it later. There is no selector that says "apply this default only when none of the dark branches win."
+
+This is just *one* property with *one* state, and getting it right already takes multiple iterations. The correct selectors require negating every other branch — which is exactly what Tasty generates automatically:
+
+Tasty generates the correct version automatically:
+
+```css
+/* Branch 1: Explicit dark schema */
+:root[data-schema="dark"] .t0.t0 {
+  color: var(--text-on-dark-color);
+}
+
+/* Branch 2: No schema attribute + OS prefers dark */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-schema]) .t0.t0 {
+    color: var(--text-on-dark-color);
+  }
+}
+
+/* Default: no schema + OS does not prefer dark */
+@media (not (prefers-color-scheme: dark)) {
+  :root:not([data-schema="dark"]) .t0.t0 {
+    color: var(--text-color);
+  }
+}
+
+/* Default: schema is set but not dark (any OS preference) */
+:root:not([data-schema="dark"])[data-schema] .t0.t0 {
+  color: var(--text-color);
+}
+```
+
+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.
+
+[Try it in the Tasty Playground →](https://cube-ui-kit.vercel.app/?path=/story/getting-started-tasty-playground--playground)
+
+## Capabilities
+
+### 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:
+
+```tsx
+fill: '#surface',         // → var(--surface-color)
+color: '#text.80',        // → 80% opacity text token
+padding: '2x',            // → calc(var(--gap) * 2)
+radius: '1r',             // → var(--radius)
+border: '1bw solid #border',
+```
+
+| Unit | Maps to | Example |
+|------|---------|---------|
+| `x` | `--gap` multiplier | `2x` → `calc(var(--gap) * 2)` |
+| `r` | `--radius` multiplier | `1r` → `var(--radius)` |
+| `bw` | `--border-width` multiplier | `1bw` → `var(--border-width)` |
+| `ow` | `--outline-width` multiplier | `1ow` → `var(--outline-width)` |
+| `cr` | `--card-radius` multiplier | `1cr` → `var(--card-radius)` |
+
+Define your own units via `configure({ units: { ... } })`.
+
+### State System
+
+Every style property accepts a state mapping object. Keys can be combined with boolean logic:
+
+| State type | Syntax | CSS output |
+|------------|--------|------------|
+| Data attribute (boolean modifier) | `disabled` | `[data-disabled]` |
+| Data attribute (value modifier) | `theme=danger` | `[data-theme="danger"]` |
+| Pseudo-class | `:hover` | `:hover` |
+| Attribute selector | `[role="tab"]` | `[role="tab"]` |
+| Class selector (supported) | `.is-active` | `.is-active` |
+| Media query | `@media(w < 768px)` | `@media (width < 768px)` |
+| Container query | `@(panel, w >= 300px)` | `@container panel (width >= 300px)` |
+| Root state | `@root(theme=dark)` | `:root[data-theme="dark"]` |
+| Parent state | `@parent(theme=danger)` | `:is([data-theme="danger"] *)` |
+| Feature query | `@supports(display: grid)` | `@supports (display: grid)` |
+| Entry animation | `@starting` | `@starting-style` |
+
+Combine with `&` (AND), `|` (OR), `!` (NOT):
+
+```tsx
+fill: {
+  '': '#surface',
+  'theme=danger & :hover': '#danger-hover',
+  '[aria-selected="true"]': '#accent-subtle',
+}
+```
+
 ### Sub-Element Styling
 
+Style inner elements from the parent component definition. No extra components, no CSS leakage:
+
 ```tsx
 const Card = tasty({
   styles: {
     padding: '4x',
     Title: { preset: 'h3', color: '#primary' },
-    Content: { color: '#text' },
-  },
-  elements: {
-    Title: 'h2',
-    Content: 'div',
+    Content: { color: '#text', preset: 't2' },
   },
+  elements: { Title: 'h2', Content: 'div' },
 });
 
 <Card>
-  <Card.Title>Title</Card.Title>
-  <Card.Content>Content</Card.Content>
+  <Card.Title>Heading</Card.Title>
+  <Card.Content>Body text</Card.Content>
 </Card>
 ```
 
-### Hooks
+Sub-elements use `data-element` attributes — no extra class names, no naming conventions.
+
+By default, sub-elements participate in the same state context as the root component. That means mappings like `:hover`, `theme=danger`, `[role="button"]`, and other keys are evaluated as one unified block, which keeps styling logic predictable across the whole markup tree.
+
+Use `@own(...)` when a sub-element should react to its own state instead of the root state context.
+
+Class selectors are also supported, but modifiers/pseudo-classes are usually the better default in design-system code.
+
+Use the sub-element selector `$` when you need precise descendant targeting to avoid leakage in deeply nested component trees.
+
+### Variants
+
+Variants are designed to keep single-component CSS lean. Instead of generating dozens of static button classes up front, define all versions once and let runtime usage decide what CSS is actually emitted.
+
+```tsx
+const Button = tasty({
+  styles: { padding: '2x 4x', radius: '1r' },
+  variants: {
+    default: { fill: '#primary', color: '#on-primary' },
+    danger: { fill: '#danger', color: '#on-danger' },
+    outline: { fill: 'transparent', border: '1bw solid #primary' },
+  },
+});
+
+<Button variant="danger">Delete</Button>
+```
+
+### Recipes
+
+Recipes are predefined style sets that work like composable styling classes for Tasty. They can be pre-applied or post-applied to current styles, which lets you add reusable state logic while still allowing local style overrides.
 
 ```tsx
-import { useStyles, useGlobalStyles } from '@tenphi/tasty';
+configure({
+  recipes: {
+    card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
+    elevated: { shadow: '0 2x 4x #shadow' },
+  },
+});
 
-function MyComponent() {
-  const { className } = useStyles({
-    padding: '2x',
-    fill: '#surface',
-  });
+const ProfileCard = tasty({
+  styles: {
+    recipe: 'card elevated',
+    color: '#text',
+  },
+});
+```
 
-  useGlobalStyles('.card', {
-    border: '1bw solid #border',
-    radius: '1r',
-  });
+Use `/` to post-apply recipes after local styles when you need recipe states/styles to win the final merge order. Use `none` to skip base recipes: `recipe: 'none / disabled'`.
+
+### Auto-Inferred `@property`
+
+CSS custom properties do not animate smoothly by default because the browser does not know how to interpolate their values. The [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property) at-rule fixes that by declaring a property's syntax, such as `<number>` or `<color>`.
+
+In Tasty, you usually do not need to declare `@property` manually. When a custom property is assigned a concrete value, Tasty infers the syntax and registers the matching `@property` for you:
+
+```tsx
+const Pulse = tasty({
+  styles: {
+    animation: 'pulse 2s infinite',
+    transform: 'scale($pulse-scale)',
+    '@keyframes': {
+      pulse: {
+        '0%, 100%': { '$pulse-scale': 1 },
+        '50%': { '$pulse-scale': 1.05 },
+      },
+    },
+  },
+});
+```
+
+Here, `$pulse-scale: 1` is inferred as `<number>`, so Tasty injects `@property --pulse-scale` automatically before using it in the animation. Numeric types (`<number>`, `<length>`, `<percentage>`, `<angle>`, `<time>`) are inferred from values; `<color>` is inferred from the `#name` token convention.
 
-  return <div className={className}>Styled</div>;
+If you prefer full manual control, disable auto-inference globally with `configure({ autoPropertyTypes: false })`.
+
+### Explicit `@properties`
+
+Declare `@properties` yourself only when you need to override the defaults, for example to set `inherits: false` or provide a custom `initialValue`:
+
+```tsx
+'@properties': {
+  '$pulse-scale': { syntax: '<number>', inherits: false, initialValue: 1 },
+},
+```
+
+### React Hooks
+
+For cases where you don't need a full component:
+
+```tsx
+import { useStyles, useGlobalStyles, useRawCSS } from '@tenphi/tasty';
+
+function App() {
+  const { className } = useStyles({ padding: '2x', fill: '#surface' });
+  useGlobalStyles('body', { margin: '0' });
+  useRawCSS('@font-face { font-family: "Custom"; src: url(...); }');
+
+  return <main className={className}>...</main>;
 }
 ```
 
 ### Zero-Runtime Mode
 
+Extract all CSS at build time. Zero JavaScript overhead in production:
+
 ```tsx
 import { tastyStatic } from '@tenphi/tasty/static';
 
-const button = tastyStatic({
-  display: 'inline-flex',
-  padding: '2x 4x',
-  fill: '#purple',
-  color: '#white',
+const card = tastyStatic({
+  padding: '4x',
+  fill: '#surface',
+  radius: '1r',
+  color: { '': '#text', '@dark': '#text-on-dark' },
 });
 
-<button className={button}>Click me</button>
+// card is a CSS class name string
+<div className={card}>Static styles, zero runtime</div>
 ```
 
 Configure the Babel plugin:
 
 ```js
-// babel.config.js
 module.exports = {
   plugins: [
-    ['@tenphi/tasty/babel-plugin', { output: 'public/tasty.css' }],
+    ['@tenphi/tasty/babel-plugin', {
+      output: 'public/tasty.css',
+      config: {
+        states: { '@dark': '@root(theme=dark)' },
+      },
+    }],
   ],
 };
 ```
 
-## Built-in Units
+### `tasty` vs `tastyStatic`
 
-| Unit | Description | Example | CSS Output |
-|------|-------------|---------|------------|
-| `x` | Gap multiplier | `2x` | `calc(var(--gap) * 2)` |
-| `r` | Border radius | `1r` | `var(--radius)` |
-| `cr` | Card border radius | `1cr` | `var(--card-radius)` |
-| `bw` | Border width | `2bw` | `calc(var(--border-width) * 2)` |
-| `ow` | Outline width | `1ow` | `var(--outline-width)` |
-| `fs` | Font size | `1fs` | `var(--font-size)` |
-| `lh` | Line height | `1lh` | `var(--line-height)` |
-| `sf` | Stable fraction | `1sf` | `minmax(0, 1fr)` |
+| | `tasty` (runtime) | `tastyStatic` (zero-runtime) |
+|---|---|---|
+| **Output** | React component | CSS class name |
+| **CSS injection** | Runtime `<style>` tags | Build-time extraction |
+| **Runtime cost** | Style generation on mount | None |
+| **Generated CSS scope** | Only styles/variants used at runtime | All extracted static styles at build time |
+| **Dynamic values** | Fully supported | Via CSS custom properties |
+| **Sub-elements** | Built-in (`<C.Title>`) | Manual (`data-element`) |
+| **Variants** | Built-in (`variants` option) | Separate static styles |
+| **Framework** | React | Any (requires Babel) |
+| **Best for** | Interactive apps, design systems | Static sites, SSG, landing pages |
 
-## `tasty` vs `tastyStatic`
+Both share the same DSL, tokens, units, state mappings, and recipes.
 
-Tasty ships two styling APIs with different trade-offs. Pick the one that fits your project:
+### Runtime Performance
 
-| | `tasty` (runtime) | `tastyStatic` (zero-runtime) |
-|---|---|---|
-| **Framework** | React only | Framework-agnostic (requires Babel) |
-| **Import** | `@tenphi/tasty` | `@tenphi/tasty/static` |
-| **Output** | React component | CSS class name (string) |
-| **CSS injection** | At runtime via `<style>` tags | At build time via Babel plugin |
-| **Runtime overhead** | Style generation + injection on mount | None — CSS is pre-extracted |
-| **Requires Babel plugin** | No | Yes (`@tenphi/tasty/babel-plugin`) |
-| **Component creation** | `tasty({ as, styles, ... })` | `tastyStatic({ ... })` returns a class |
-| **Extending components** | `tasty(BaseComponent, { styles })` | `tastyStatic(baseStyle, { ... })` |
-| **Global / selector styles** | `useGlobalStyles(selector, styles)` | `tastyStatic(selector, styles)` |
-| **Style props at runtime** | Yes — `styleProps`, `styles`, `mods` | No — all values must be static |
-| **Dynamic values** | Fully supported | Only via CSS custom properties |
-| **Sub-elements** | Built-in (`elements` + `<C.Title>`) | Manual (use `data-element` + CSS) |
-| **Variants** | Built-in (`variants` option) | Manual (create separate static styles) |
-| **Tokens** | `tokens` prop → inline CSS vars | `processTokens()` helper |
-| **Design tokens & units** | Full support (`#color`, `2x`, `1r`) | Full support (`#color`, `2x`, `1r`) |
-| **State mappings** | Full support (modifiers, media, etc.) | Full support (modifiers, media, etc.) |
-| **Recipes** | Supported via `configure()` | Supported via Babel plugin config |
-| **Best for** | Interactive React apps, design systems | Static sites, landing pages, SSG |
+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+.
+
+**Next.js setup:**
+
+```tsx
+// app/tasty-registry.tsx
+'use client';
+
+import { TastyRegistry } from '@tenphi/tasty/ssr/next';
+
+export default function TastyStyleRegistry({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <TastyRegistry>{children}</TastyRegistry>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import TastyStyleRegistry from './tasty-registry';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        <TastyStyleRegistry>{children}</TastyStyleRegistry>
+      </body>
+    </html>
+  );
+}
+```
+
+See the [full SSR guide](docs/ssr.md) for Astro integration, streaming SSR, generic framework usage, and the complete API reference.
+
+## Entry Points
+
+| Import | Description | Platform |
+|--------|-------------|----------|
+| `@tenphi/tasty` | Runtime style engine (`tasty`, hooks, `configure`) | Browser |
+| `@tenphi/tasty/static` | Zero-runtime static styles (`tastyStatic`) | Browser |
+| `@tenphi/tasty/core` | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | Browser / Node |
+| `@tenphi/tasty/babel-plugin` | Babel plugin for zero-runtime CSS extraction | Node |
+| `@tenphi/tasty/zero` | Programmatic extraction API | Node |
+| `@tenphi/tasty/next` | Next.js integration wrapper | Node |
+| `@tenphi/tasty/ssr` | Core SSR API (collector, context, hydration) | Node |
+| `@tenphi/tasty/ssr/next` | Next.js App Router SSR integration | Node |
+| `@tenphi/tasty/ssr/astro` | Astro middleware + auto-hydration | Node / Browser |
+
+## 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.
+
+```bash
+pnpm add -D @tenphi/eslint-plugin-tasty
+```
+
+```js
+import tasty from '@tenphi/eslint-plugin-tasty';
+export default [tasty.configs.recommended];
+```
+
+### [Glaze](https://github.com/tenphi/glaze)
+
+`@tenphi/glaze` — OKHSL-based color theme generator with automatic WCAG contrast solving. Generate light, dark, and high-contrast palettes from a single hue, and export them directly as Tasty color tokens.
+
+```tsx
+import { glaze } from '@tenphi/glaze';
+
+const theme = glaze(280, 80);
+theme.colors({
+  surface: { lightness: 97 },
+  text: { base: 'surface', lightness: '-52', contrast: 'AAA' },
+});
+
+const tokens = theme.tasty(); // Ready-to-use Tasty tokens
+```
+
+### [VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)
+
+Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, and related APIs.
+
+<p align="center">
+  <img src="assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example">
+</p>
+
+## Built with Tasty
+
+### [tasty.style](https://tasty.style) ([source](https://github.com/tenphi/tasty.style))
+
+The official Tasty documentation and landing page — itself built entirely with Tasty. A showcase for zero-runtime styling via `tastyStatic`, SSR with Next.js, and OKHSL color theming with Glaze.
+
+### [Cube Cloud](https://cube.dev/)
+
+Enterprise universal semantic layer platform by Cube Dev, Inc. Cube Cloud unifies data modeling, caching, access control, and APIs (REST, GraphQL, SQL, AI) for analytics at scale. Tasty has powered its frontend for over 5 years in production.
+
+### [Cube Cloud for Excel and Google Sheets](https://cube.dev/)
+
+A single spreadsheet add-in deployed to both [Microsoft Excel](https://marketplace.microsoft.com/en-us/product/office/WA200008486) and [Google Sheets](https://workspace.google.com/u/0/marketplace/app/cube_cloud_for_sheets/641460343379). Connects spreadsheets to any cloud data platform (BigQuery, Databricks, Snowflake, Redshift, and more) via Cube Cloud's universal semantic layer.
+
+### [Cube UI Kit](https://github.com/cube-js/cube-ui-kit) ([storybook](https://cube-ui-kit.vercel.app/))
+
+Open-source React UI kit built on Tasty + React Aria. 100+ production components proving Tasty works at design-system scale. A reference implementation and a ready-to-use component library.
 
 ## Documentation
 
-- [Runtime API (tasty)](docs/tasty.md) — Full runtime styling documentation
-- [Zero Runtime (tastyStatic)](docs/tasty-static.md) — Build-time static styling documentation
+### Start here
+
+- **[Getting Started](docs/getting-started.md)** — Installation, first component, 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
+
+- **[Building a Design System](docs/design-system.md)** — Practical guide to building a DS layer: token vocabulary, state aliases, recipes, primitives, compound components, override contracts
+- **[Adoption Guide](docs/adoption.md)** — Where Tasty sits in the stack, who should adopt it, what you define yourself, and how to introduce it incrementally into an existing design system
+
+### Reference
+
+- **[Style DSL](docs/dsl.md)** — The Tasty style language: state maps, tokens, units, color syntax, extending semantics, recipes, keyframes, and @property
+- **[Runtime API](docs/runtime.md)** — React-specific API: `tasty()` factory, component props, variants, sub-elements, and hooks
+- **[Configuration](docs/configuration.md)** — Global configuration: tokens, recipes, custom units, style handlers, and TypeScript extensions
+- **[Style Properties](docs/styles.md)** — Complete reference for all enhanced style properties: syntax, values, modifiers, and recommendations
+
+### Rendering modes
+
+- **[Zero Runtime (tastyStatic)](docs/tasty-static.md)** — Build-time static styling: Babel plugin setup, Next.js integration, and static style patterns
+- **[Server-Side Rendering](docs/ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks: streaming support, cache hydration, and troubleshooting
+
+### Internals
+
+- **[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
+
+### Context
+
+- **[Comparison](docs/comparison.md)** — How Tasty compares to Tailwind, Panda CSS, vanilla-extract, StyleX, Stitches, and Emotion: positioning, trade-offs, and when each tool fits best
 
 ## License