@cube-dev/ui-kit 0.125.1 → 0.127.0

package/docs/components/fields/ListBox.md

@@ -313,6 +313,31 @@ Groups related items together with an optional heading.
 </ListBox>
 ```
 
+### With Sections (Dynamic)
+
+Sections and items can be defined dynamically using the `items` prop with a render function. Pass hierarchical data where each section contains a `children` array.
+
+```jsx
+const categories = [
+  { name: 'Fruits', children: [
+    { key: 'apple', label: 'Apple' },
+    { key: 'banana', label: 'Banana' },
+  ]},
+  { name: 'Vegetables', children: [
+    { key: 'carrot', label: 'Carrot' },
+    { key: 'broccoli', label: 'Broccoli' },
+  ]},
+];
+
+<ListBox label="Select food items" selectionMode="single" items={categories}>
+  {(category) => (
+    <ListBox.Section key={category.name} title={category.name} items={category.children}>
+      {(item) => <ListBox.Item key={item.key}>{item.label}</ListBox.Item>}
+    </ListBox.Section>
+  )}
+</ListBox>
+```
+
 ### Multiple Selection
 
 ```jsx
@@ -694,15 +719,20 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 
 ### Virtualization
 
-ListBox automatically enables virtualization when:
-- No sections are present (sections disable virtualization)
-- Provides smooth scrolling even with large datasets
-- Only visible items are rendered in the DOM
-- Uses `@tanstack/react-virtual` for efficient rendering
-- Automatically measures item heights for consistent scrolling
-- Supports items with varying heights (descriptions, complex content)
+For large datasets, use the `items` prop with a render function. This enables automatic virtualization — only visible items are rendered in the DOM, providing smooth scrolling even with thousands of items.
+
+```jsx
+const items = Array.from({ length: 1000 }, (_, i) => ({
+  key: `item-${i}`,
+  label: `Item ${i + 1}`,
+}));
+
+<ListBox label="Large Dataset" selectionMode="single" items={items}>
+  {(item) => <ListBox.Item key={item.key}>{item.label}</ListBox.Item>}
+</ListBox>
+```
 
-**Note**: Virtualization is transparent to the user - no configuration needed. It works automatically when you have a flat list without sections.
+**Note**: Virtualization is disabled when sections are present. For very large datasets, prefer a flat list structure.
 
 ### Optimization Tips
 

package/docs/components/fields/Picker.md

@@ -425,6 +425,31 @@ Organize items into logical groups with section headers.
 </Picker>
 ```
 
+### With Sections (Dynamic)
+
+Sections and items can be defined dynamically using the `items` prop with a render function. Pass hierarchical data where each section contains a `children` array.
+
+```jsx
+const categories = [
+  { name: 'Fruits', children: [
+    { key: 'apple', label: 'Apple' },
+    { key: 'banana', label: 'Banana' },
+  ]},
+  { name: 'Vegetables', children: [
+    { key: 'carrot', label: 'Carrot' },
+    { key: 'broccoli', label: 'Broccoli' },
+  ]},
+];
+
+<Picker label="Favorite Food" placeholder="Select a food" items={categories}>
+  {(category) => (
+    <Picker.Section key={category.name} title={category.name} items={category.children}>
+      {(item) => <Picker.Item key={item.key}>{item.label}</Picker.Item>}
+    </Picker.Section>
+  )}
+</Picker>
+```
+
 ### Different Sizes
 
 Picker supports three sizes: small, medium (default), and large.

package/docs/components/fields/Select.md

@@ -386,6 +386,8 @@ Groups related options together with an optional heading.
 
 ### With Sections (Dynamic)
 
+Sections and items can be defined dynamically using the `items` prop with a render function.
+
 ```jsx
 const groups = [
   {

package/docs/components/navigation/Tabs.md

@@ -112,12 +112,12 @@ For individual tabs:
 
 ### Sizes
 
-- `xsmall` - Extra small size with t4 typography (radio type only)
+- `xsmall` - Extra small size with t4 typography
 - `small` - Small size with t3m typography (default)
 - `medium` - Default size with t3m typography
 - `large` - Larger tabs with t3m typography
 
-**Note:** Radio type only supports `medium` and `large` sizes, which are mapped to smaller Item sizes internally.
+**Note:** Radio type supports `large` (default, 40px total) and `medium` (32px total) sizes, mapped to Item button sizes `medium` (32px) and `xsmall` (24px) respectively.
 
 ## Compound Components
 

package/docs/tasty/README.md

@@ -6,18 +6,18 @@ Tasty is a styling engine for design systems that turns component state into det
 
 - **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 the selector model**: [Style rendering pipeline](PIPELINE.md) for how mutually exclusive selectors make stateful styling deterministic.
+- **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
 
-- **Application developer using an existing design system**: [Getting Started](getting-started.md), then [Runtime API](runtime.md).
+- **Application developer using an existing design system**: [Getting Started](getting-started.md), then [React API](react-api.md).
 - **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 Styling Approach
 
-- **Runtime React components**: [Runtime API](runtime.md)
+- **React components**: [React API](react-api.md)
 - **Zero-runtime / build-time extraction**: [Zero Runtime (tastyStatic)](tasty-static.md)
 - **Runtime `tasty()` with server collection and hydration**: [Server-Side Rendering](ssr.md)
 
@@ -27,5 +27,5 @@ Tasty is a styling engine for design systems that turns component state into det
 - **Look up a property handler**: [Style Properties](styles.md)
 - **Define tokens, units, recipes, keyframes, or properties globally**: [Configuration](configuration.md)
 - **Debug generated CSS or cache behavior**: [Debug Utilities](debug.md)
-- **Understand how selector generation works internally**: [Style rendering pipeline](PIPELINE.md)
+- **Understand how selector generation works internally**: [Style rendering pipeline](pipeline.md)
 - **Understand runtime injection internals**: [Style Injector](injector.md)

package/docs/tasty/adoption.md

@@ -13,7 +13,7 @@ Tasty is not the surface your product engineers interact with directly. It sits
 ```
 Product code
   └─ DS components (Button, Card, Layout, ...)
-       └─ Tasty engine (tasty(), configure(), hooks)
+       └─ Tasty engine (tasty(), configure(), style functions)
             └─ CSS (mutually exclusive selectors, tokens, custom properties)
 ```
 
@@ -64,7 +64,7 @@ Tasty provides the engine. The DS team defines the language that runs on it. Her
 | **Units** | Custom multiplier units (`x`, `r`, `bw`, or your own) | `configure({ units })` |
 | **State aliases** | Responsive breakpoints, theme modes, feature flags | `configure({ states })` |
 | **Recipes** | Reusable style bundles (card, elevated, input-reset) | `configure({ recipes })` |
-| **Typography** | Preset definitions (h1-h6, t1-t4, etc.) | `configure({ tokens: generateTypographyTokens(...) })` |
+| **Typography** | Preset definitions (h1-h6, t1-t4, etc.) | `configure({ presets: { ... } })` |
 | **Style props** | Which CSS properties each component exposes as React props | `styleProps` in each component |
 | **Sub-elements** | Inner parts of compound components (Title, Icon, Content) | `elements` + capitalized keys in `styles` |
 | **Override rules** | How product engineers extend or constrain components | Styled wrappers via `tasty(Base, { ... })` |
@@ -270,6 +270,8 @@ const LoadingButton = tasty(Button, {
 </Space>
 ```
 
+**Components are server components by default.** All `tasty()` components and style functions are hook-free, so they work as React Server Components without `'use client'`. In server-only contexts (Next.js RSC, Astro without `client:*` directives), they produce zero client JavaScript. Product engineers only add `'use client'` when their component needs actual React interactivity (state, effects, event handlers), never because of styling.
+
 **No cascade/specificity concerns.** Tasty's mutually exclusive selectors mean extending a component cannot accidentally break another. Import order, class name collisions, and specificity arithmetic are non-issues.
 
 ---
@@ -289,7 +291,7 @@ const LoadingButton = tasty(Button, {
 - [Methodology](methodology.md) -- the recommended patterns for structuring Tasty components
 - [Building a Design System](design-system.md) -- practical guide to building a DS layer with Tasty
 - [Style DSL](dsl.md) -- state maps, tokens, units, extending semantics, keyframes, @property
-- [Runtime API](runtime.md) -- `tasty()` factory, component props, variants, sub-elements, hooks
+- [React API](react-api.md) -- `tasty()` factory, component props, variants, sub-elements, style functions
 - [Configuration](configuration.md) -- tokens, recipes, custom units, style handlers, and TypeScript extensions
 - [Style Properties](styles.md) -- complete reference for all enhanced style properties
 - [Comparison](comparison.md) -- positioning and trade-offs vs. other styling systems

package/docs/tasty/comparison.md

@@ -29,14 +29,14 @@ That is why syntax-level comparisons are often shallow. The more meaningful comp
 
 ## High-level positioning
 
-| System | Best described as | Main authoring model | Conflict model | Best fit |
-|---|---|---|---|---|
-| **Tasty** | Design-system styling engine | Custom DSL with tokens, state maps, recipes, style props, sub-elements, custom units | **Mutually exclusive selector resolution** for stateful styles | Teams building shared component APIs or a house styling language |
-| **Tailwind CSS** | Utility-first styling framework | Utility classes in markup | Utility composition, variants, and framework-controlled ordering | Product teams optimizing for speed and direct authoring |
-| **Panda CSS** | Typed styling engine with atomic output | Typed style objects, recipes, generated primitives, style props | Atomic CSS with static analysis | Teams wanting a DS-friendly engine with typed primitives |
-| **vanilla-extract** | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition | Standard CSS semantics | Teams wanting static CSS and low-level control |
-| **StyleX** | Compiler-based atomic styling system | JS authoring with compiler-generated atomic CSS | Compiler-controlled atomic composition | Large app teams wanting optimized, predictable atomic styling |
-| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS | Styled components, `css()` APIs, object/string styles | Composition within CSS-in-JS rules | Teams optimizing for component DX and flexible styling |
+| System | Best described as | Main authoring model | Conflict model | RSC / zero-JS SSG | Best fit |
+|---|---|---|---|---|---|
+| **Tasty** | Design-system styling engine | Custom DSL with tokens, state maps, recipes, style props, sub-elements, custom units | **Mutually exclusive selector resolution** for stateful styles | Yes — hook-free, server components by default | Teams building shared component APIs or a house styling language |
+| **Tailwind CSS** | Utility-first styling framework | Utility classes in markup | Utility composition, variants, and framework-controlled ordering | Yes — no JS runtime | Product teams optimizing for speed and direct authoring |
+| **Panda CSS** | Typed styling engine with atomic output | Typed style objects, recipes, generated primitives, style props | Atomic CSS with static analysis | Yes — build-time extraction | Teams wanting a DS-friendly engine with typed primitives |
+| **vanilla-extract** | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition | Standard CSS semantics | Yes — build-time extraction | Teams wanting static CSS and low-level control |
+| **StyleX** | Compiler-based atomic styling system | JS authoring with compiler-generated atomic CSS | Compiler-controlled atomic composition | Yes — compiler-extracted | Large app teams wanting optimized, predictable atomic styling |
+| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS | Styled components, `css()` APIs, object/string styles | Composition within CSS-in-JS rules | No — requires `'use client'` | Teams optimizing for component DX and flexible styling |
 
 ---
 
@@ -92,7 +92,7 @@ That makes Tasty less of a "better way to write CSS objects" and more of a **sta
 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. 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).
+- **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 [React API — Sub-element Styling](react-api.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.
 - **Companion ecosystem** — An [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) with 27 lint rules, a [VS Code extension](https://github.com/tenphi/tasty-vscode-extension) for syntax highlighting, and [Glaze](https://github.com/tenphi/glaze) for OKHSL color theme generation with automatic WCAG contrast solving.
@@ -235,13 +235,12 @@ Tasty is more opinionated.
 
 It behaves less like "TypeScript that outputs CSS" and more like a **state-aware style compiler**. It is designed to encode higher-level styling semantics rather than only expose CSS primitives in typed form.
 
-This also makes Tasty's static mode notable:
+This also makes Tasty's rendering model notable:
 
-- Runtime `tasty()` creates React components with dynamic injection
-- `tastyStatic()` with the Babel plugin produces static class name strings with zero runtime overhead
-- In static mode, the output is plain CSS + class names, so it can be used with any JavaScript framework — not only React
+- `tasty()` components are hook-free and work as React Server Components. In server-only contexts (Next.js RSC, Astro without islands), they produce static HTML + CSS with zero client JavaScript — the full feature set is available without sacrificing server rendering
+- `tastyStatic()` with the Babel plugin produces static class name strings via build-time extraction, with no React dependency at runtime — the output works with any JavaScript framework
 
-Runtime features like `styleProps`, sub-element components, and dynamic variants are React-specific. The static path is framework-agnostic.
+Runtime features like `styleProps`, sub-element components, and dynamic variants are available in the `tasty()` path. The `tastyStatic()` path is framework-agnostic but limited to the DSL, tokens, and state logic.
 
 So the tradeoff is roughly:
 
@@ -303,6 +302,8 @@ So while Stitches and Emotion are strong tools for building components, Tasty is
 
 That makes it narrower in audience, but deeper in architectural ambition.
 
+There is also a fundamental architectural difference: Emotion and styled-components rely on React context and hooks internally, which means they require `'use client'` in modern React and cannot run as React Server Components. Tasty's style functions and `tasty()` components are hook-free, so they work as server components by default and produce zero client JavaScript in server-only contexts. This is not a minor compatibility detail — it means Tasty-based components stay as server components until *your* code needs interactivity, while Emotion and styled-components force the client boundary at the styling layer.
+
 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.
 
 ---
@@ -311,20 +312,18 @@ For teams evaluating runtime styling at scale, Tasty also documents its runtime
 
 Tasty is not limited to one execution model.
 
-It can be used as a styling system with runtime behavior, but it can also be used as a **fully build-time style compiler** when that is the right fit.
-
-That distinction matters.
+The term "runtime" in `tasty()` refers to *when* style computation happens — during React rendering — not to where that rendering occurs. In server-only contexts (Next.js RSC without `'use client'`, Astro without `client:*` directives, SSG), `tasty()` components render on the server, produce static HTML + CSS, and ship **zero client JavaScript**. The full feature set — `styleProps`, sub-elements, variants, state maps — is available. The result is the same as what `tastyStatic()` produces, but without giving up any runtime capabilities.
 
-In runtime mode, `tasty()` creates React components with dynamic style injection, `styleProps`, sub-element components, and variants. This path is React-specific.
+Client JavaScript only enters the picture when a component needs React interactivity (state, effects, event handlers) — and that is the consuming component's decision, never Tasty's. Tasty never forces the `'use client'` boundary.
 
-In build-time mode, `tastyStatic()` with the Babel plugin generates plain static class names and CSS files. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
+`tastyStatic()` with the Babel plugin is for a different scenario: when you want build-time CSS extraction **without React at runtime**. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
 
-The tradeoff is that some capabilities — `styleProps`, sub-element components (`<Card.Title>`), dynamic variants — are tied to the runtime path. The static path is best understood as extraction and compilation of the DSL, tokens, and state logic.
+The tradeoff is that some capabilities — `styleProps`, sub-element components (`<Card.Title>`), dynamic variants — are tied to the `tasty()` path. The `tastyStatic()` path is best understood as extraction and compilation of the DSL, tokens, and state logic without a React dependency.
 
 This flexibility is one of Tasty's more unusual strengths:
 
-- it can be used as a full authoring/runtime system for React
-- or as a static compiler whose output works with any framework
+- `tasty()` as the default for all React setups — zero client JS in server-only contexts, full feature set, SSR integration available when client hydration is needed
+- `tastyStatic()` as a static compiler whose output works with any framework, including non-React ones
 
 ---
 
@@ -337,8 +336,8 @@ These are optimized for styling product code directly.
 
 Examples:
 - Tailwind CSS
-- Emotion
-- Stitches (deprecated)
+- Emotion (requires `'use client'` — not RSC-compatible)
+- Stitches (deprecated, requires `'use client'`)
 
 ### Typed styling engines
 These are optimized for generating CSS with stronger structure and tooling.
@@ -412,7 +411,7 @@ Tasty is most compelling when the problem is not just "how do we write styles,"
 
 - [README](../README.md) — overview, quick start, and feature highlights
 - [Style DSL](dsl.md) — state maps, tokens, units, extending semantics, keyframes, @property
-- [Runtime API](runtime.md) — `tasty()` factory, component props, variants, sub-elements, hooks
+- [React API](react-api.md) — `tasty()` factory, component props, variants, sub-elements, style functions
 - [Style Properties](styles.md) — complete reference for all enhanced style properties
 - [Configuration](configuration.md) — tokens, recipes, custom units, style handlers, and TypeScript extensions
 - [Zero Runtime (tastyStatic)](tasty-static.md) — build-time static styling with Babel plugin

package/docs/tasty/configuration.md

@@ -54,8 +54,12 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 | `replaceTokens` | `Record<string, string \| number>` | - | Parse-time token substitution (inline replacement) |
 | `keyframes` | `Record<string, KeyframesSteps>` | - | Global keyframes for animations |
 | `properties` | `Record<string, PropertyDefinition>` | - | Global CSS @property definitions |
+| `fontFace` | `Record<string, FontFaceInput>` | - | Global @font-face definitions |
+| `counterStyle` | `Record<string, CounterStyleDescriptors>` | - | Global @counter-style definitions |
 | `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
 | `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
+| `presets` | `Record<string, TypographyPreset>` | - | Typography presets — shorthand for `generateTypographyTokens()` |
+| `globalStyles` | `Record<string, Styles>` | - | Global Tasty styles keyed by CSS selector |
 | `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
 
 ---
@@ -133,6 +137,65 @@ See [Replace Tokens](dsl.md#replace-tokens) in the Style DSL reference.
 
 ---
 
+## Font Face
+
+Register custom fonts globally so every component can reference them by family name. Values are descriptor objects or arrays (for multiple weights/styles). Rules are injected eagerly when styles are first generated.
+
+```ts
+configure({
+  fontFace: {
+    'Brand Sans': [
+      {
+        src: 'url("/fonts/brand-regular.woff2") format("woff2")',
+        fontWeight: 400,
+        fontDisplay: 'swap',
+      },
+      {
+        src: 'url("/fonts/brand-bold.woff2") format("woff2")',
+        fontWeight: 700,
+        fontDisplay: 'swap',
+      },
+    ],
+    Icons: {
+      src: 'url("/fonts/icons.woff2") format("woff2")',
+      fontDisplay: 'block',
+    },
+  },
+});
+```
+
+Now any component can use `fontFamily: '"Brand Sans", sans-serif'` and the browser will already have the `@font-face` rules in the stylesheet.
+
+See [Font Face (`@fontFace`)](dsl.md#font-face-fontface) for inline usage inside component styles and the full list of supported descriptors.
+
+---
+
+## Counter Style
+
+Define custom list-marker algorithms globally. Rules are injected eagerly when styles are first generated.
+
+```ts
+configure({
+  counterStyle: {
+    thumbs: {
+      system: 'cyclic',
+      symbols: '"👍"',
+      suffix: '" "',
+    },
+    'lower-roman-parens': {
+      system: 'extends lower-roman',
+      suffix: '") "',
+    },
+  },
+});
+```
+
+Components can then reference `listStyleType: 'thumbs'` directly.
+
+See [Counter Style (`@counterStyle`)](dsl.md#counter-style-counterstyle) for inline usage inside component styles and the full list of supported descriptors.
+
+---
+
 ## Recipes
 
 Recipes are predefined, named style bundles. Define them globally via `configure()`:
@@ -159,6 +222,72 @@ For how to apply, compose, and override recipes in components, see [Recipes](dsl
 
 ---
 
+## Typography Presets
+
+Typography presets are a shorthand for `generateTypographyTokens()`. Instead of calling the function manually and spreading the result into `tokens`, pass the presets directly:
+
+```jsx
+configure({
+  presets: {
+    h1: { fontSize: '32px', lineHeight: '1.2', fontWeight: '700' },
+    t2: { fontSize: '16px', lineHeight: '1.5', fontWeight: '400' },
+    tag: {
+      fontSize: '10px',
+      lineHeight: '1.4',
+      letterSpacing: '0.04em',
+      fontWeight: '600',
+    },
+  },
+});
+```
+
+Each preset generates `$name-font-size`, `$name-line-height`, `$name-letter-spacing`, `$name-font-weight`, and optional `$name-bold-font-weight`, `$name-icon-size`, `$name-text-transform`, `$name-font-family`, `$name-font-style` tokens.
+
+Preset values support state maps for responsive or theme-aware typography:
+
+```jsx
+configure({
+  presets: {
+    t2: {
+      fontSize: '16px',
+      lineHeight: '1.5',
+      fontWeight: { '': '400', '@dark': '300' },
+    },
+  },
+});
+```
+
+The generated tokens are merged **under** explicit `tokens` — if both `presets` and `tokens` define `$t2-font-weight`, the `tokens` value wins. Plugins can also provide `presets`; plugin presets are merged first, then config presets, then explicit tokens on top.
+
+---
+
+## Global Styles
+
+Apply Tasty styles to any selector via configuration, without needing `useGlobalStyles(selector, ...)` at runtime:
+
+```jsx
+configure({
+  globalStyles: {
+    body: {
+      fill: '#surface',
+      color: '#text',
+      preset: 't2',
+      margin: 0,
+      fontFamily: 'system-ui, sans-serif',
+    },
+    html: {
+      overflow: 'hidden',
+    },
+  },
+});
+```
+
+Each key is a CSS selector, and each value is a Tasty `Styles` object supporting the full style syntax including style properties, tokens, state maps, and selector-based sub-styling (e.g. `$: '> .app'` for elements outside React scope). Global styles are injected alongside `:root` tokens when the first style is rendered.
+
+Global styles are automatically emitted in all rendering modes: runtime (client), SSR, and zero-runtime (Babel plugin). Plugins can also provide `globalStyles`; they are merged per selector with config global styles (config wins on conflict).
+
+---
+
 ## Auto Property Types
 
 CSS cannot transition or animate custom properties unless their type is declared via [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property). Tasty handles this automatically — when a custom property is assigned a concrete value (e.g. `'$scale': 1`, `'$gap': '10px'`, `'#accent': 'purple'`), the type is inferred and a `@property` rule is registered.
@@ -262,4 +391,4 @@ declare module '@tenphi/tasty' {
 }
 ```
 
-See [Style DSL](dsl.md) for state maps, tokens, units, and extending semantics, and [Runtime API](runtime.md) for `tasty()`, hooks, and component props.
+See [Style DSL](dsl.md) for state maps, tokens, units, and extending semantics, and [React API](react-api.md) for `tasty()`, style functions, and component props.

package/docs/tasty/debug.md

@@ -12,6 +12,8 @@ In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically
 
 All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
+> **Note (2.0.0+):** Class names use a content-addressed base36 hash format (e.g. `t3a5f`) instead of the previous sequential `t{number}` format. Cross-environment hydration reads the rendered class list from `window.__TASTY__` (the legacy `window.__TASTY_SSR_CACHE__` global was removed in 2.0.0).
+
 ---
 
 ## Quick Start
@@ -69,8 +71,8 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 | `'unused'` | CSS with refCount = 0 (cached but not used) |
 | `'global'` | Only global CSS (from `injectGlobal`) |
 | `'page'` | All CSS on the page (including non-tasty) |
-| `'t42'` | CSS for a specific tasty class |
-| `['t0', 't5']` | CSS for multiple tasty classes |
+| `'t3a5f'` | CSS for a specific tasty class (class names are `t` + base36 hash) |
+| `['t3a5f', 't9k2']` | CSS for multiple tasty classes |
 | `'.my-button'` | CSS affecting a DOM element (by selector) |
 | `element` | CSS affecting a DOM element (by reference) |
 
@@ -88,11 +90,11 @@ interface CssOptions extends DebugOptions {
 tastyDebug.css('active');
 
 // Specific class, silent
-const css = tastyDebug.css('t42', { raw: true });
+const css = tastyDebug.css('t3a5f', { raw: true });
 
 // Compare original vs browser-parsed CSS (dev mode only)
-tastyDebug.css('t42');                    // live CSSOM
-tastyDebug.css('t42', { source: true }); // original output
+tastyDebug.css('t3a5f');                    // live CSSOM
+tastyDebug.css('t3a5f', { source: true }); // original output
 
 // Shadow DOM
 tastyDebug.css('all', { root: shadowRoot });
@@ -125,11 +127,11 @@ interface ChunkInfo {
 ```typescript
 tastyDebug.inspect('.my-card');
 // Logs: inspect div — 3 classes, 5 rules, 1.2KB
-//       Chunks: t3→appearance, t7→font, t12→dimension
+//       Chunks: t3a5f→appearance, t9k2→font, tb71→dimension
 
 // Silent
 const result = tastyDebug.inspect('.my-card', { raw: true });
-console.log(result.classes);  // ['t3', 't7', 't12']
+console.log(result.classes);  // ['t3a5f', 't9k2', 'tb71']
 console.log(result.rules);    // 5
 ```
 
@@ -291,10 +293,10 @@ tastyDebug.summary({ root: shadowRoot });
 tastyDebug.inspect('.my-button');
 
 // 2. See CSS for a specific class
-tastyDebug.css('t3');
+tastyDebug.css('t3a5f');
 
 // 3. Compare original vs browser-parsed (dev mode)
-tastyDebug.css('t3', { source: true });
+tastyDebug.css('t3a5f', { source: true });
 ```
 
 ### Checking cache efficiency

package/docs/tasty/design-system.md

@@ -84,25 +84,54 @@ configure({
 
 ### Typography presets
 
-Use `generateTypographyTokens()` to create typography tokens from your own presets, then pass them to `configure({ tokens })`:
+Pass typography presets directly to `configure()` — they are converted to tokens automatically:
 
 ```tsx
-import { configure, generateTypographyTokens } from '@tenphi/tasty';
+import { configure } from '@tenphi/tasty';
 
-const typographyTokens = generateTypographyTokens({
-  h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
-  t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+configure({
+  presets: {
+    h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
+    t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+  },
 });
+```
+
+Preset values support state maps for responsive or theme-aware typography:
 
+```tsx
 configure({
-  tokens: {
-    ...typographyTokens,
+  presets: {
+    t2: {
+      fontSize: '0.875rem',
+      lineHeight: '1.5',
+      fontWeight: { '': 400, '@dark': 300 },
+    },
   },
 });
 ```
 
 Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
+> You can also call `generateTypographyTokens()` manually and spread the result into `tokens` for more control — `presets` is just a shorthand.
+
+### Registering brand fonts
+
+Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
+
+```ts
+configure({
+  fontFace: {
+    'Brand Sans': [
+      { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
+      { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+    ],
+  },
+});
+```
+
+See [Font Face](configuration.md#font-face) for the full configuration reference.
+
 ---
 
 ## Defining state aliases
@@ -317,7 +346,7 @@ Usage:
 
 Sub-elements share the root component's state context by default. A `disabled` modifier on `<Card>` affects `Title`, `Content`, and `Footer` styles automatically — no prop drilling. For the full mental model, see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
 
-For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
+For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [React API — Sub-element Styling](react-api.md#sub-element-styling).
 
 ---
 
@@ -387,7 +416,7 @@ ds/
     index.ts              # Recipe definitions (imported by config.ts)
   tokens/
     colors.ts             # Color token definitions
-    typography.ts         # Typography presets via generateTypographyTokens()
+    typography.ts         # Typography presets for configure({ presets })
     spacing.ts            # Spacing token definitions
   index.ts                # Public API: re-exports components + configure
 ```
@@ -401,7 +430,7 @@ The key principle: `config.ts` imports tokens and recipes, calls `configure()`,
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components
 - **[Getting Started](getting-started.md)** — Installation, first component, tooling setup
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers
 - **[Adoption Guide](adoption.md)** — Who should adopt Tasty, incremental phases, what changes for product engineers
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties