@tenphi/tasty 3.3.1 → 3.5.0

package/docs/getting-started.md

@@ -1,6 +1,8 @@
 # Getting Started
 
-This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [React API](react-api.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
+Build one stateful component first. You will see how Tasty expresses priority as a state map, why overlapping states do not compete, and where shared design-system configuration fits afterward.
+
+This is the right starting point when you are ready to try Tasty in code. If you are still evaluating it, read the [Introduction](../README.md), [Comparison](comparison.md), and [Adoption Guide](adoption.md).
 
 ---
 
@@ -10,7 +12,7 @@ This guide walks you from zero to a working Tasty component, then through the op
 - **React** >= 18 (peer dependency)
 - **Package manager**: pnpm, npm, or yarn
 
-Tasty can be used immediately in a React app, but it is most compelling for teams building reusable components with intersecting states, variants, tokens, and design-system conventions.
+No Tasty configuration is required for the first component.
 
 ---
 
@@ -22,36 +24,57 @@ pnpm add @tenphi/tasty
 
 ---
 
-## Your first component
+## Build a button whose states don’t fight
 
 ```tsx
 import { tasty } from '@tenphi/tasty';
 
-const Card = tasty({
-  as: 'div',
+const Button = tasty({
+  as: 'button',
   styles: {
-    display: 'flex',
-    flow: 'column',
-    padding: '4x',
-    gap: '2x',
-    fill: '#white',
-    border: true,
-    radius: true,
+    padding: '12px 20px',
+    radius: '8px',
+    border: '0',
+    fill: {
+      '': 'royalblue',
+      ':hover': 'blue',
+      ':active': 'navy',
+      disabled: 'lightgray',
+    },
+    color: {
+      '': 'white',
+      disabled: 'dimgray',
+    },
+    cursor: {
+      '': 'pointer',
+      disabled: 'not-allowed',
+    },
   },
 });
 
 export default function App() {
-  return <Card>Hello, Tasty!</Card>;
+  return (
+    <>
+      <Button>Save changes</Button>
+      <Button disabled>Disabled</Button>
+    </>
+  );
 }
 ```
 
-`tasty()` returns a normal React component. Values like `4x`, `#white`, `true`, and `1r` are Tasty DSL — they map to CSS custom properties, shorthand expansions, and design tokens. See [Style Properties](styles.md) for the full reference.
+`tasty()` returns a normal React component. The keys in each state map define priority: later branches win over earlier ones. Because `disabled` is last, a disabled button keeps its disabled styles even while the pointer is over it.
+
+`disabled` and `checked` are built-in automatic states. Tasty activates them from the corresponding native prop or attribute, so `disabled` is the concise Tasty form of `[disabled]`, and `checked` is the concise form of `[checked]`.
+
+Tasty compiles that priority into selectors that exclude one another. The hover, active, and disabled background rules cannot all match and ask the CSS cascade to decide the winner.
+
+The example uses ordinary CSS values so it works without setup. A design system will usually replace them with shared tokens, units, and state aliases in the next step. See the [Style DSL](dsl.md) for the complete state-map syntax and [Style Properties](styles.md) for Tasty’s enhanced CSS properties.
 
 ---
 
-## Optional: add shared configuration
+## Add your design system’s language
 
-Use `configure()` once, before your app renders, when your app or design system needs shared state aliases, tokens, recipes, or parser extensions:
+The first component needs no configuration. Use `configure()` once, before your app renders, when your app or design system is ready to share tokens, state aliases, recipes, units, or parser extensions:
 
 ```tsx
 // src/tasty-config.ts
@@ -91,8 +114,8 @@ configure({
     '#primary': 'oklch(55% 0.25 265)',
     '#surface': '#fff',
     '#text': '#111',
-    '$gap': '8px',
-    '$radius': '4px',
+    $gap: '8px',
+    $radius: '4px',
     '$border-width': '1px',
     '$outline-width': '2px',
   },
@@ -148,23 +171,21 @@ export default [
 
 The `recommended` config enables 18 of the plugin's 27 total rules. It covers the most common issues without turning on the stricter governance rules:
 
-| Category | Rules | Examples |
-|----------|-------|---------|
-| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element` | Flags typos like `pading` or invalid boolean usage |
-| Value validation | `valid-value`, `valid-color-token`, `valid-custom-unit` | Catches `#nonexistent` tokens, bad unit syntax |
-| State validation | `valid-state-key`, `no-nested-state-map`, `require-default-state` | Validates state key syntax, ensures `''` default exists |
-| Structure | `valid-styles-structure`, `no-important`, `no-nested-selector` | Prevents `!important`, invalid nesting |
-| Static mode | `static-no-dynamic-values`, `static-valid-selector` | Enforces build-time constraints in `tastyStatic()` |
-| Style properties | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax |
+| Category            | Rules                                                                                                  | Examples                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
+| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage           |
+| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax               |
+| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists      |
+| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                       |
+| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`           |
+| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax |
 
 ### Strict config
 
 For stricter governance, use `tasty.configs.strict`. It adds rules that enforce best practices like preferring shorthand properties, consistent token usage, and flagging direct `styles` prop usage:
 
 ```js
-export default [
-  tasty.configs.strict,
-];
+export default [tasty.configs.strict];
 ```
 
 ---
@@ -179,19 +200,19 @@ export default [
 
 ## Choosing a rendering mode
 
-`tasty()` is the default for all React apps. All `tasty()` components and style functions are hook-free and work as React Server Components without `'use client'`. In server-only contexts, they produce zero client JavaScript with the full feature set.
+`tasty()` is the default for all React apps. All `tasty()` components and style functions are hook-free and work as React Server Components without `'use client'`. Zero-runtime delivery is not tied to one API: both server-only `tasty()` and build-time `tastyStatic()` can ship no Tasty styling runtime to the browser.
 
-| Approach | Entry point | Best for | Trade-off |
-|------|-------------|----------|-----------|
-| **Runtime (default)** | `tasty()` from `@tenphi/tasty` | All React apps — server-rendered by default, zero client JS until you need interactivity | Full feature set (styleProps, sub-elements, variants); CSS computed during rendering |
-| **Runtime + SSR integration** | Add `@tenphi/tasty/ssr/*` | Apps with client-side hydration (Next.js client components, Astro islands) | Adds CSS batching, deduplication, FOUC prevention, and client cache hydration |
-| **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Non-React frameworks or build-time extraction without React | Requires Babel plugin; no `styleProps` or runtime-only APIs |
+| Approach                  | Authoring API                               | CSS is generated                    | Tasty runtime in the browser | Best for                                                         |
+| ------------------------- | ------------------------------------------- | ----------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
+| **Server-only React**     | `tasty()`; optional `@tenphi/tasty/ssr/*`   | During server or static rendering   | None                         | Astro without islands, server-only RSC, SSG                      |
+| **Hydrated React**        | `tasty()` plus `@tenphi/tasty/ssr/*`        | During SSR, then on demand in React | Only in hydrated components  | Interactive React apps, Next.js client components, Astro islands |
+| **Build-time extraction** | `tastyStatic()` from `@tenphi/tasty/static` | During the build                    | None in file mode            | Non-React frameworks or extraction before rendering              |
 
 Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state mappings.
 
-- **Runtime** is the default and requires no extra setup beyond `@tenphi/tasty`. In server-only contexts (Next.js RSC, Astro without `client:*` directives, SSG), `tasty()` produces static HTML + CSS with zero client JavaScript — the same end result as `tastyStatic()` but with the full feature set. For example, `tasty()` + `tastyIntegration()` in Astro without islands gives you the complete API with zero JS shipped.
-- **SSR integration** is only needed when your app also has client-side rendering. Add `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API to get CSS deduplication and cache hydration. See [Server-Side Rendering](ssr.md).
-- **Zero-runtime** requires the Babel plugin and additional peer dependencies. Use it when you need build-time extraction without a React runtime. See [Zero Runtime (tastyStatic)](tasty-static.md).
+- **Server-only `tasty()`** keeps the full feature set (`styleProps`, sub-elements, variants) while generating CSS during server rendering. `tasty()` plus `tastyIntegration({ islands: false })` in Astro is the verified concrete setup and ships no client JavaScript. The same server-only architecture applies to Next.js RSC; verify the generated output for your deployment.
+- **Hydrated `tasty()`** uses the SSR integrations to batch and deduplicate server CSS, prevent FOUC, and hydrate the client cache. The browser styling pipeline is available only where React components hydrate. See [Server-Side Rendering](ssr.md).
+- **Build-time extraction** uses the Babel plugin and additional peer dependencies. Choose `tastyStatic()` when CSS must be generated before rendering or when the consumer is not React. File mode ships no styling runtime; inject mode intentionally includes a tiny CSS injector. See [Build-Time Extraction (`tastyStatic`)](tasty-static.md).
 
 ---
 
@@ -214,4 +235,4 @@ Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state
 
 - Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
 - Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](debug.md).
-- You need build-time extraction or server-rendered CSS delivery: use [Zero Runtime (tastyStatic)](tasty-static.md) for extraction, or add [Server-Side Rendering](ssr.md) on top of runtime `tasty()` when your framework renders on the server.
+- You need zero-runtime delivery: use server-only [`tasty()` with server rendering](ssr.md) to keep the full React API, or use [`tastyStatic()` build-time extraction](tasty-static.md) when styles must be compiled before rendering.

package/docs/injector.md

@@ -9,7 +9,7 @@ A high-performance CSS-in-JS solution that powers the Tasty design system with e
 The Style Injector is the core engine behind Tasty's styling system, providing:
 
 - **Hash-based deduplication** - Identical CSS gets the same className
-- **Reference counting** - Automatic cleanup when components unmount (refCount = 0)
+- **DOM-driven lifetime** - Styles are collected once nothing renders them
 - **CSS nesting flattening** - Handles `&`, `.Class`, `SubElement` patterns
 - **At-rule injection** - First-class `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` support
 - **Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
@@ -63,10 +63,16 @@ const result = inject([{
 
 console.log(result.className); // 't-abc123'
 
-// Cleanup when component unmounts (refCount decremented)
+// Release the pin; the class becomes collectible once nothing renders it
 result.dispose();
 ```
 
+`inject()` **pins** the class it returns, and `gc()` never evicts a pinned class
+— that is what `dispose()` releases. Pass `{ pin: false }` when the caller keeps
+no handle and the DOM is the only record that the class is in use; `dispose()`
+is then a no-op. The render path (`tasty()` / `computeStyles()`) injects this
+way, because a hook-free render has no unmount signal to dispose on.
+
 ### `injectGlobal(rules, options?): { dispose: () => void }`
 
 Injects global styles that don't reserve tasty class names.
@@ -245,8 +251,27 @@ Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 - Most options have sensible defaults and auto-detection
 - `configure()` is optional - the injector works with defaults
 - **Configuration is locked after styles are generated** - calling `configure()` after first render will emit a warning and be ignored
-- `gc.touchInterval`: Number of touch events between GC cycles. Each style render counts as a touch. When the counter reaches this value, GC is scheduled via `requestIdleCallback`.
-- `gc.capacity`: Maximum number of unused styles (refCount = 0, not in DOM) to retain. When exceeded, the oldest are evicted first. Actively referenced styles don't count against this limit.
+- `gc.touchInterval`: Number of renders between sweeps. When the counter reaches this value, a sweep is scheduled via `requestIdleCallback`; without idle callbacks nothing is collected automatically.
+- `gc.grace`: How long a class is left alone after collection first notices nothing is carrying it, in milliseconds (default `10000`).
+
+**What a sweep does.** Everything the injector holds falls into one of five bands, and only the last is ever deleted:
+
+| Band | | Deleted |
+|---|---|---|
+| 1 | **Rendered** — some element carries the class right now | never |
+| 2 | **Not ours** — queued for a batched write, pre-allocated, or server-rendered | never |
+| 3 | **Hot** — nothing carries it, but that was noticed less than `grace` ago | never |
+| 4 | **Cached** — cold, but within `capacity` when ordered by when it went cold | never |
+| 5 | Everything else | on every sweep |
+
+`gc({ force: true })` and `cleanup()` take bands 4 and 5 together, ignoring capacity. Band 3 is spared even then: an explicit cleanup is still no reason to take rules from a render that has not committed yet.
+
+> **Why band 3 exists.** Rendering is not commit-aware: a render can resolve a class and commit it a little later, and in between nothing on the page carries it. From outside React that is indistinguishable from a class that is finished, so collection does not try to tell them apart — it leaves alone anything only just noticed to be cold. A render would have to stay pending for the whole window to lose its rules, and it gets them back on its next render.
+>
+> The clock starts when a sweep *notices*, not when the element actually left — nothing observes that moment, so starting it at the sighting is what gives every class the same full window however long ago it went.
+>
+> This is also why collection costs nothing to run: the timestamps are written by the sweep's own DOM scan, so rendering tracks nothing per class.
+- `gc.capacity`: Maximum number of unused styles (not in the DOM, not pinned) to retain. When exceeded, the least recently used are evicted first. Rendered and pinned styles don't count against this limit.
 
 ---
 
@@ -329,23 +354,28 @@ const button2 = inject([{
 console.log(button1.className === button2.className); // true
 ```
 
-### Reference Counting
+### Pinning
 
 ```typescript
-// Multiple components using the same styles
+// Multiple callers using the same styles
 const comp1 = inject([commonStyle]);
 const comp2 = inject([commonStyle]);
 const comp3 = inject([commonStyle]);
 
-// Style is kept alive while any component uses it
-comp1.dispose(); // refCount: 3 → 2
-comp2.dispose(); // refCount: 2 → 1
-comp3.dispose(); // refCount: 1 → 0, eligible for bulk cleanup
+// Style is pinned while any caller holds a handle
+comp1.dispose(); // pins: 3 → 2
+comp2.dispose(); // pins: 2 → 1
+comp3.dispose(); // pins: 1 → 0, now up to the DOM and gc()
 
-// Rule exists but refCount = 0 means unused
-// Next inject() with same styles will increment refCount and reuse immediately
+// Unpinned does not mean deleted: the rule stays cached and is reused instantly
+// by the next inject(). gc() decides when it actually goes.
 ```
 
+Pinning covers callers that hold a handle. Styles that come from rendering are
+never pinned — see `{ pin: false }` under
+[`inject()`](#injectrules-options-injectresult) — so what keeps them alive is
+being in the DOM, and nothing else.
+
 ### Garbage Collection
 
 ```typescript
@@ -353,6 +383,9 @@ import { configure, gc } from '@tenphi/tasty';
 
 // Keyframes: Disposed immediately when refCount = 0 (safer for global scope)
 // CSS rules: Tracked by touch count and cleaned up via gc()
+//
+// A CSS rule is collectible when no element carries its class AND nobody
+// pinned it with inject().
 
 configure({
   gc: {
@@ -367,15 +400,19 @@ gc();
 // Force-remove ALL unused styles (e.g. on route change or test teardown):
 gc({ force: true });
 
-// GC is also triggered automatically by touch count during rendering.
-// Every `touchInterval` touches, GC is scheduled via requestIdleCallback.
+// cleanup() is the same thing:
+cleanup();
+
+// Every `touchInterval` renders, a sweep is scheduled in idle time. It scans
+// the DOM for the classes actually on the page and sorts everything the
+// injector holds into five bands — only the last one is deleted. See below.
 
 // Benefits:
 // - Activity-proportional: busy apps trigger GC more often
 // - DOM-safe: styles currently in the DOM are never evicted
 // - Oldest-first: least recently used styles are evicted first
 // - Keyframes: Immediate cleanup prevents global namespace pollution
-// - Unused styles can be instantly reactivated (just increment refCount)
+// - Unused styles stay cached until evicted, so re-rendering them is a cache hit
 ```
 
 ### Shadow DOM Support
@@ -470,11 +507,11 @@ const metrics = injector.instance.getMetrics();
 console.log({
   cacheHits: metrics.hits,           // Successful cache hits  
   cacheMisses: metrics.misses,       // New styles injected
-  unusedHits: metrics.unusedHits,    // Current unused styles (calculated on demand)
+  unusedHits: metrics.unusedHits,    // Styles currently eligible for eviction (scans the DOM)
   bulkCleanups: metrics.bulkCleanups, // Number of bulk cleanup operations
   stylesCleanedUp: metrics.stylesCleanedUp, // Total styles removed in bulk cleanups
   totalInsertions: metrics.totalInsertions, // Lifetime insertions
-  totalUnused: metrics.totalUnused,  // Total styles marked as unused (refCount = 0)
+  totalUnused: metrics.totalUnused,  // Times a pinned style lost its last pin
   startTime: metrics.startTime,      // Metrics collection start timestamp
   cleanupHistory: metrics.cleanupHistory, // Detailed cleanup operation history
 });
@@ -518,10 +555,10 @@ metrics.cleanupHistory.forEach(cleanup => {
 
 ```typescript
 // ✅ Reuse styles - identical CSS gets deduplicated
-const buttonBase = { padding: '8px 16px', borderRadius: '4px' };
+const buttonBase = 'padding: 8px 16px; border-radius: 4px;';
 
 // ✅ Avoid frequent disposal and re-injection
-// Let the reference counting system handle cleanup
+// Let the injector handle cleanup
 
 // ✅ Use bulk operations for global styles
 injectGlobal([
@@ -547,13 +584,13 @@ configure({
 // The injector automatically manages memory through:
 
 // 1. Hash-based deduplication - same CSS = same className
-// 2. Reference counting - styles stay alive while in use (refCount > 0)
-// 3. Immediate keyframes cleanup - disposed instantly when refCount = 0
-// 4. Touch-count GC - unused CSS rules are evicted oldest-first when over capacity
-// 5. DOM safety guard - styles visible in the DOM are never evicted
+// 2. DOM-driven lifetime - a rendered class is never evicted
+// 3. Pinning - inject() callers hold their classes until they dispose
+// 4. Immediate keyframes cleanup - disposed instantly when refCount = 0
+// 5. Touch-count GC - unused CSS rules are evicted oldest-first when over capacity
 
 // Manual cleanup is rarely needed but available:
-cleanup(); // Force immediate cleanup of all unused CSS rules (refCount = 0)
+cleanup(); // Remove every rule that is neither rendered nor pinned
 destroy(); // Nuclear option: remove all stylesheets and reset
 ```
 
@@ -575,9 +612,9 @@ const StyledButton = tasty({
 
 // Internally uses the injector:
 // 1. Styles are parsed into StyleResult objects
-// 2. inject() is called with the parsed results
+// 2. inject() is called with the parsed results, unpinned
 // 3. Component gets the returned className
-// 4. dispose() is called when component unmounts
+// 4. gc() reclaims the class once no element carries it
 ```
 
 For most development, you'll use the [React API](./react-api.md) rather than the injector directly. The injector provides the high-performance foundation that makes Tasty's declarative styling possible.

package/docs/methodology.md

@@ -1,6 +1,8 @@
 # Methodology
 
-Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: deterministic state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
+State maps keep a property’s branches from fighting. This guide applies the same goal to component architecture: keep state ownership explicit, expose intentional public APIs, and make extension predictable as a component system grows.
+
+The patterns are recommended rather than required. Tasty works without them, but they help design-system teams carry its state-resolution guarantees across roots, sub-elements, typed props, tokens, and styled wrappers.
 
 ---
 
@@ -75,7 +77,7 @@ const Nav = tasty({
         '': '#text',
         '@own(:hover)': '#primary',
         '@own(:focus-visible)': '#primary',
-        'selected': '#primary',
+        selected: '#primary',
       },
     },
   },
@@ -117,16 +119,16 @@ Style props accept state maps, so responsive values work through the same API:
 
 Tasty exports predefined style prop lists that group properties by role. Use them instead of hand-picking arrays:
 
-| Preset | Properties | Typical use |
-|--------|-----------|-------------|
-| `FLOW_STYLES` | flow, gap, columnGap, rowGap, align, justify, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`) |
-| `POSITION_STYLES` | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, margin, inset, position | Positioned elements (`Button`, `Badge`) |
-| `DIMENSION_STYLES` | width, height, flexBasis, flexGrow, flexShrink, flex | Sized elements |
-| `COLOR_STYLES` | color, fill, fade, image | Color-customizable elements |
-| `BLOCK_STYLES` | padding, paddingInline, paddingBlock, overflow, scrollbar, textAlign, border, radius, shadow, outline | Block-level containers |
-| `CONTAINER_STYLES` | All of the above combined (+ BASE_STYLES) | Fully flexible containers |
-| `OUTER_STYLES` | POSITION_STYLES + DIMENSION_STYLES + block outer (border, radius, shadow, outline) | Components whose outer shell is customizable |
-| `INNER_STYLES` | BASE_STYLES + COLOR_STYLES + block inner (padding, overflow, scrollbar) + FLOW_STYLES | Components whose inner layout is customizable |
+| Preset             | Properties                                                                                                                                                                     | Typical use                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
+| `FLOW_STYLES`      | flow, gap, columnGap, rowGap, align, justify, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`)           |
+| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, margin, inset, position                                                                       | Positioned elements (`Button`, `Badge`)       |
+| `DIMENSION_STYLES` | width, height, flexBasis, flexGrow, flexShrink, flex                                                                                                                           | Sized elements                                |
+| `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                       | Color-customizable elements                   |
+| `BLOCK_STYLES`     | padding, paddingInline, paddingBlock, overflow, scrollbar, textAlign, border, radius, shadow, outline                                                                          | Block-level containers                        |
+| `CONTAINER_STYLES` | All of the above combined (+ BASE_STYLES)                                                                                                                                      | Fully flexible containers                     |
+| `OUTER_STYLES`     | POSITION_STYLES + DIMENSION_STYLES + block outer (border, radius, shadow, outline)                                                                                             | Components whose outer shell is customizable  |
+| `INNER_STYLES`     | BASE_STYLES + COLOR_STYLES + block inner (padding, overflow, scrollbar) + FLOW_STYLES                                                                                          | Components whose inner layout is customizable |
 
 ```tsx
 import { tasty, FLOW_STYLES, POSITION_STYLES } from '@tenphi/tasty';
@@ -159,7 +161,7 @@ Match the preset to the component's role:
 
 ### The governance trade-off
 
-Exposing every CSS property as a prop defeats the purpose of a design system. The more props a component exposes, the more ways product engineers can deviate from the intended design. A good rule of thumb: expose props that product engineers *need* to adjust for layout and composition, and keep visual identity (colors, borders, typography) controlled through the component definition, variants, or styled wrappers.
+Exposing every CSS property as a prop defeats the purpose of a design system. The more props a component exposes, the more ways product engineers can deviate from the intended design. A good rule of thumb: expose props that product engineers _need_ to adjust for layout and composition, and keep visual identity (colors, borders, typography) controlled through the component definition, variants, or styled wrappers.
 
 ---
 
@@ -180,17 +182,19 @@ const Card = tasty({
 });
 
 // Clean prop API — no mods object needed
-<Card isLoading isSelected>Content</Card>
+<Card isLoading isSelected>
+  Content
+</Card>;
 ```
 
 ### When to use which
 
-| Pattern | Use when |
-|---|---|
-| `modProps` | The component has a fixed set of known boolean/string states that drive styles. Provides TypeScript autocomplete and a cleaner JSX API. |
-| `mods` prop | The component needs arbitrary or dynamic modifiers that aren't known at definition time. |
-| Both | Combine `modProps` for the known states and `mods` for ad-hoc overrides. Mod props take precedence. |
-| `styleProps` | Exposing CSS properties (layout, sizing) for customization — different from modifiers. |
+| Pattern      | Use when                                                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `modProps`   | The component has a fixed set of known boolean/string states that drive styles. Provides TypeScript autocomplete and a cleaner JSX API. |
+| `mods` prop  | The component needs arbitrary or dynamic modifiers that aren't known at definition time.                                                |
+| Both         | Combine `modProps` for the known states and `mods` for ad-hoc overrides. Mod props take precedence.                                     |
+| `styleProps` | Exposing CSS properties (layout, sizing) for customization — different from modifiers.                                                  |
 
 ### Typed modProps vs array form
 
@@ -239,20 +243,20 @@ const ProgressBar = tasty({
 });
 
 // Usage: the progress value comes from a prop, not from styles
-<ProgressBar tokens={{ '$progress': `${percent}%` }} />
+<ProgressBar tokens={{ $progress: `${percent}%` }} />;
 ```
 
 The `tokens` prop sets `style="--progress: 75%"` on the DOM element. The `$progress` reference in styles maps to `var(--progress)`, so the bar width updates without regenerating any CSS.
 
 ### When to use tokens vs other mechanisms
 
-| Need | Use |
-|------|-----|
-| Value changes per instance at render time (progress, user color, avatar size) | `tokens` prop (on component) |
-| Value is constant across all instances (card padding, border radius) | `configure({ tokens })` for `:root` CSS custom properties |
-| Value should be inlined at parse time (alias for another token) | `configure({ replaceTokens })` |
-| Value changes based on component state (hover, disabled, breakpoint) | State map in `styles` |
-| Value changes based on a variant (primary, danger, outline) | `variants` option |
+| Need                                                                          | Use                                                       |
+| ----------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Value changes per instance at render time (progress, user color, avatar size) | `tokens` prop (on component)                              |
+| Value is constant across all instances (card padding, border radius)          | `configure({ tokens })` for `:root` CSS custom properties |
+| Value should be inlined at parse time (alias for another token)               | `configure({ replaceTokens })`                            |
+| Value changes based on component state (hover, disabled, breakpoint)          | State map in `styles`                                     |
+| Value changes based on a variant (primary, danger, outline)                   | `variants` option                                         |
 
 Design tokens (via `configure({ tokens })`) are injected as CSS custom properties on `:root`. Replace tokens (via `configure({ replaceTokens })`) are resolved at parse time and baked into the generated CSS. The `tokens` prop on components is resolved at render time via inline CSS custom properties. Use design tokens for design-system constants, replace tokens for value aliases, and the `tokens` prop for truly dynamic per-instance values.
 
@@ -271,7 +275,7 @@ const ProgressBar = tasty({
 });
 
 // Clean prop API — no tokens object needed
-<ProgressBar progress="75%" accentColor="#purple" />
+<ProgressBar progress="75%" accentColor="#purple" />;
 
 // Conversion:
 //   'progress'    → $progress    → --progress
@@ -291,7 +295,7 @@ const Card = tasty({
   styles: { padding: '$card-size', fill: '#card-accent' },
 });
 
-<Card size="4x" color="#purple" />
+<Card size="4x" color="#purple" />;
 ```
 
 #### Merge order
@@ -326,7 +330,7 @@ const LargeCard = tasty(Card, {
   styles: { padding: '6x', Title: { color: '#danger' } },
 });
 
-<LargeCard />
+<LargeCard />;
 ```
 
 Why? Styled wrappers are:
@@ -417,10 +421,12 @@ const Link = tasty({
 
 const Span = tasty({
   as: 'span',
-  styles: { fontWeight: 'bold' },
+  styles: { preset: 'strong' },
 });
 
-<Link href="/blog" padding="1x">Blog</Link>;
+<Link href="/blog" padding="1x">
+  Blog
+</Link>;
 ```
 
 The wrapped component only needs to forward `className` (and ideally `style` and `ref`) to its underlying DOM node. Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `isDisabled`, `isHidden`, `isChecked`, and any `styleProps`/`modProps`/`tokenProps` you declared) are consumed by the wrapper and converted to `data-*` attributes or CSS custom properties — they never leak to the DOM.
@@ -593,7 +599,7 @@ Modifiers are compiled into exclusive selectors once. Changing `styles` at runti
 
 ```tsx
 // Bad: bypassing Tasty for custom styling
-<Button style={{ backgroundColor: 'red', padding: '12px 24px' }} />
+<Button style={{ backgroundColor: 'red', padding: '12px 24px' }} />;
 
 // Good: create a styled wrapper
 const DangerButton = tasty(Button, {
@@ -610,7 +616,7 @@ The `style` prop bypasses tokens, units, and state maps. It should only be used
 <Card>
   <div data-element="Title">Card Title</div>
   <div data-element="Content">Card content</div>
-</Card>
+</Card>;
 
 // Better: declare elements for typed sub-components
 const Card = tasty({
@@ -624,7 +630,7 @@ const Card = tasty({
 <Card>
   <Card.Title>Card Title</Card.Title>
   <Card.Content>Card content</Card.Content>
-</Card>
+</Card>;
 ```
 
 The `elements` prop gives you typed sub-components with automatic `data-element` attributes, `mods` support, and better discoverability.