@tenphi/tasty 3.10.0 → 3.11.0

package/docs/getting-started.md

@@ -64,7 +64,7 @@ export default function App() {
 
 `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]`.
+`disabled`, `checked`, and `hidden` are built-in automatic states. Tasty sets `data-disabled`, `data-checked`, and `data-hidden` from the matching native prop, so `disabled` in a state map is the concise form of `[disabled]` (it compiles to `[data-disabled]`).
 
 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.
 
@@ -101,9 +101,9 @@ import App from './App';
 createRoot(document.getElementById('root')!).render(<App />);
 ```
 
-### Define shared tokens and override default unit values
+### Define shared tokens and units
 
-Color tokens like `#primary` resolve to CSS custom properties at runtime (e.g. `var(--primary-color)`). Built-in units like `x`, `r`, and `bw` already work without setup and multiply CSS custom properties by default. Use `configure({ tokens })` when you want to define shared token values or override the defaults your app uses:
+Color tokens like `#primary` and value tokens like `$sidebar-width` resolve to CSS custom properties (`var(--primary-color)`, `var(--sidebar-width)`). Define their values with `configure({ tokens })`:
 
 ```tsx
 // src/tasty-config.ts
@@ -114,10 +114,7 @@ configure({
     '#primary': 'oklch(55% 0.25 265)',
     '#surface': '#fff',
     '#text': '#111',
-    $gap: '8px',
-    $radius: '4px',
-    '$border-width': '1px',
-    '$outline-width': '2px',
+    '$sidebar-width': '280px',
   },
 });
 ```
@@ -135,7 +132,20 @@ configure({
 });
 ```
 
-Every component using `#primary`, `2x`, or `1r` adjusts automatically. Tokens are injected as `:root` CSS custom properties when the first style is rendered. You can also use standard CSS color values such as `rgb(...)`, `hsl(...)`, and named colors directly; `okhsl(...)` is the recommended choice when you want authored colors that stay aligned with Tasty's design-system-oriented workflow.
+Tokens are injected as `:root` CSS custom properties when the first style is rendered, and every component using `#primary` follows them. You can also use standard CSS color values such as `rgb(...)`, `hsl(...)`, and named colors directly; the built-in `okhsl(...)` and `okhst(...)` functions are the recommended choice when you want authored colors that stay aligned with Tasty's design-system-oriented workflow.
+
+Units work differently: `x`, `r`, `cr`, `bw`, and `ow` compile to plain values when styles are generated (`2x` → `16px` with the default `8px` step), so setting a `$gap` token does not change them. Change the scale with `configure({ units })`:
+
+```tsx
+configure({
+  units: {
+    x: '4px', // spacing step: 2x → 8px
+    r: '8px', // radius: 1r → 8px
+  },
+});
+```
+
+When the scale has to change at runtime, for example per theme or density, point the unit at a custom property and define that property as a token. With `units: { x: 'var(--gap)' }` and `tokens: { $gap: '8px' }`, `2x` compiles to `calc(2 * var(--gap))`. See [Built-in Units](dsl.md#built-in-units) for the defaults.
 
 > **Note:** `configure({ replaceTokens })` is a separate mechanism — it replaces tokens with literal values at parse time (baked into CSS). Use it for value aliases like `$card-padding: '4x'` that should be resolved during style generation, not for defining color or unit values. See [Configuration — Replace Tokens](configuration.md#replace-tokens-parse-time-substitution) for details.
 
@@ -145,7 +155,7 @@ See [Configuration](configuration.md) for the full `configure()` API — tokens,
 
 ## ESLint plugin
 
-The ESLint plugin catches invalid style properties, bad token references, malformed state keys, and other mistakes at lint time — before they reach the browser.
+The ESLint plugin catches invalid style properties, bad token references, malformed state keys, and other mistakes at lint time — before they reach the browser. It checks style objects and JSX style props alike, and runs under both ESLint 9+ and oxlint.
 
 ### Install
 
@@ -167,36 +177,80 @@ export default [
 ];
 ```
 
-### What `recommended` catches
+### Tell it about your design system
+
+Without project configuration the plugin checks syntax and property names, but it cannot know which tokens, presets, or recipes exist. Add a `tasty.config.ts` at the project root to enable those checks for the names your `configure()` call defines:
+
+```ts
+// tasty.config.ts
+export default {
+  tokens: ['#primary', '#surface', '#text', '$sidebar-width'],
+  states: ['@mobile', '@dark'],
+  presets: ['h1', 'h2', 't1', 't2'],
+  recipes: ['card'],
+  importSources: ['@my-org/ui'], // modules that re-export tasty()
+};
+```
 
-The `recommended` config covers common correctness and style issues:
+Every list is optional; leaving one out skips that check. `importSources` matters when your design system re-exports `tasty()` from its own module: the plugin only lints calls whose import it can trace.
 
-| 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          |
-| Motion guidance     | `no-raw-transition-duration`                                                                           | Suggests timing tokens or the default timing for transition durations |
-| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                         | Warns on JavaScript values and spreads inside runtime style objects   |
+### What `recommended` catches
+
+| 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             |
+| Token usage         | `no-raw-color-values`, `consistent-token-usage`, `no-raw-transition-duration`                          | Suggests `#color` tokens over raw colors, units over raw pixel lengths   |
+| Preferred syntax    | `prefer-shorthand-property`, `prefer-auto-calc`, `prefer-hide`, `prefer-state-negation`, and others    | Suggests `fill` over `backgroundColor`, `(...)` over `calc(...)`         |
+| Component props     | `no-style-prop`, `no-classname-prop`, `no-styles-prop`                                                 | Points escape hatches toward `tokens`, `mods`, and the component's props |
+| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                        | Warns on JavaScript values and spreads inside runtime style objects      |
 
 ### Strict config
 
-For stricter governance, use `tasty.configs.strict`. It adds rules that flag direct `styles` prop usage and other patterns:
+For stricter governance, use `tasty.configs.strict`. It adds existence checks for `$` custom properties and `@` state aliases, and validates state definitions in `configure()` and `tasty.config.ts`:
 
 ```js
 export default [tasty.configs.strict];
 ```
 
+See the [plugin README](https://github.com/tenphi/eslint-plugin-tasty) for every rule, the oxlint setup, and the experimental type-aware mode for JSX props.
+
+---
+
+## TypeScript autocomplete
+
+Component props are typed from their definitions without extra setup: `modProps` value lists become unions, `variant` is typed from the variant keys, and sub-elements are typed components. To get autocomplete for your own token, preset, and theme names inside style values, register them with module augmentation:
+
+```ts
+// tasty.d.ts
+import '@tenphi/tasty';
+
+declare module '@tenphi/tasty' {
+  interface TastyNamedColors {
+    primary: true;
+    surface: true;
+    text: true;
+  }
+  interface TastyPresetNames {
+    h1: true;
+    t2: true;
+  }
+}
+```
+
+See [Configuration → TypeScript](configuration.md#typescript) for every augmentation interface and how component props are typed.
+
 ---
 
 ## Editor support
 
-**[VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)** — Syntax highlighting for Tasty styles in TypeScript/TSX/JavaScript/JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()` and `tastyStatic()` calls. Install from the VS Code marketplace or from a `.vsix` file.
+**[VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)** — Syntax highlighting for Tasty styles in TypeScript/TSX/JavaScript/JSX: color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, `styles` objects, and style functions. It also adds snippets for components, state maps, and `configure()`. Install the `.vsix` from the [latest GitHub release](https://github.com/tenphi/tasty-vscode-extension/releases/latest); the extension is not published to the marketplace.
 
-**[Glaze](https://github.com/tenphi/glaze)** — OKHSL-based color theme generator with automatic WCAG contrast solving. Generate light, dark, and high-contrast color palettes from a single hue and export them directly as Tasty color tokens. See the [Ecosystem section](../README.md#ecosystem) in the README.
+**[Glaze](https://github.com/tenphi/glaze)** — Not an editor tool, but the fastest way to fill `configure({ tokens })`: it generates light, dark, and high-contrast palettes from one hue in the OKHST color space, solves WCAG and APCA contrast, and exports them as Tasty tokens with `configure({ tokens: theme.tasty() })`. See [Glaze in the README](../README.md#glaze).
 
 ---
 
@@ -228,6 +282,7 @@ Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state
 - **[Adoption Guide](adoption.md)** — Roll out Tasty inside an existing design system or platform team
 - **[Comparison](comparison.md)** — Evaluate Tasty against other styling systems
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Plugins & Extension Points](plugins.md)** — Add your own style properties, units, functions, and component props
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[Debug Utilities](debug.md)** — Inspect generated CSS and debug runtime behavior when styles do not look right
 
@@ -237,4 +292,6 @@ 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).
+- Changing a `$gap` or `$radius` token does not change `2x` or `1r`: units compile to plain values from `configure({ units })`. Point a unit at the custom property (`units: { x: 'var(--gap)' }`) if it should follow the token.
+- The linter accepts unknown tokens or presets: list them in `tasty.config.ts` so the plugin knows what your design system defines.
 - 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

@@ -10,10 +10,10 @@ The Style Injector is the core engine behind Tasty's styling system, providing:
 
 - **Hash-based deduplication** - Identical CSS gets the same className
 - **DOM-driven lifetime** - Styles are collected once nothing renders them
-- **CSS nesting flattening** - Handles `&`, `.Class`, `SubElement` patterns
+- **Selector assembly** - Prepends the doubled `.tX.tX` class and root prefix to the pipeline's selector fragments (sub-element and `&` nesting is flattened earlier, by the pipeline)
 - **At-rule injection** - First-class `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` support
 - **Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
-- **SSR support** - Deterministic class names and CSS extraction
+- **SSR support** - Deterministic class names shared with `ServerStyleCollector`, and hydration of server-rendered classes
 - **Multiple roots** - Works with Document and ShadowRoot
 - **Non-stacking cleanups** - Prevents timeout accumulation for better performance
 
@@ -55,13 +55,15 @@ Injects CSS rules and returns a className with dispose function.
 ```typescript
 import { inject } from '@tenphi/tasty';
 
-// Component styling - generates tasty class names
+// Rules flagged needsClassName get the generated class prepended (doubled)
 const result = inject([{
-  selector: '.t-abc123',
+  selector: '',
   declarations: 'color: red; padding: 10px;',
+  needsClassName: true,
 }]);
 
-console.log(result.className); // 't-abc123'
+console.log(result.className); // 'th8n0uh' — `t` + base36 hash of the rules
+// Injected: .th8n0uh.th8n0uh { color: red; padding: 10px; }
 
 // Release the pin; the class becomes collectible once nothing renders it
 result.dispose();
@@ -175,7 +177,7 @@ const result = testInjector.inject(rules);
 Injects CSS keyframes with automatic deduplication.
 
 ```typescript
-// Generated name (k0, k1, k2...)
+// Generated name (tk0, tk1, … — namePrefix + 'k' + counter)
 const fadeIn = keyframes({
   from: { opacity: 0 },
   to: { opacity: 1 },
@@ -253,6 +255,7 @@ Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 - **Configuration is locked after styles are generated** - calling `configure()` after first render will emit a warning and be ignored
 - `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`).
+- Automatic sweeps are opt-in: they run only when `configure({ gc })` is set (`gc: {}` enables them with these defaults). Without it nothing is collected until you call `gc()` or `cleanup()`.
 
 **What a sweep does.** Everything the injector holds falls into one of five bands, and only the last is ever deleted:
 
@@ -289,7 +292,7 @@ Beyond ordinary rules, the injector has a dedicated entry point per at-rule. All
 
 Every one of these takes an optional `root` (a `Document` or `ShadowRoot`).
 
-`func()` also accepts `weak: true`, which registers the rule **without** overriding an existing one of the same name. `configure()` uses it for global `@function` definitions so a component-local definition always wins over the global default, regardless of which is injected first.
+`counterStyle()` and `func()` also accept `weak: true`, which registers the rule **without** overriding an existing one of the same name. `configure()` uses it for global `@counter-style` and `@function` definitions so a component-local definition always wins over the global default, regardless of which is injected first.
 
 ```ts
 import { counterStyle, fontFace, func, property } from '@tenphi/tasty';
@@ -306,22 +309,24 @@ func('$$negative', { args: ['$value'], result: '(-1 * $value)' });
 
 ### Style Result Format
 
-The injector works with `StyleResult` objects from the tasty parser:
+The injector works with `StyleResult` objects from the pipeline (`renderStyles`):
 
 ```typescript
 interface StyleResult {
-  selector: string;              // CSS selector
-  declarations: string;          // CSS declarations
-  atRules?: string[];           // @media, @supports, etc.
-  nestingLevel?: number;        // Nesting depth for specificity
+  selector: string;          // full selector, or a fragment when needsClassName
+  declarations: string;      // CSS declarations
+  atRules?: string[];        // @media, @container, @supports, …
+  needsClassName?: boolean;  // prepend the generated `.tX.tX` (OR'd fragments joined with '|||')
+  rootPrefix?: string;       // root-state prefix placed before the class
+  startingStyle?: boolean;   // wrap declarations in @starting-style
 }
 
 // Example StyleResult
 const styleRule: StyleResult = {
-  selector: '.t-button',
+  selector: ':where([data-hovered])',
   declarations: 'padding: 8px 16px; background: blue; color: white;',
   atRules: ['@media (min-width: 768px)'],
-  nestingLevel: 0,
+  needsClassName: true,
 };
 ```
 
@@ -339,28 +344,24 @@ API here calls it for you.
 ### Deduplication & Performance
 
 ```typescript
-// Identical CSS rules get the same className
-const button1 = inject([{
-  selector: '.t-btn1',
-  declarations: 'padding: 8px; color: red;'
-}]);
+const rule = { selector: '', declarations: 'padding: 8px; color: red;', needsClassName: true };
 
-const button2 = inject([{
-  selector: '.t-btn2', 
-  declarations: 'padding: 8px; color: red;' // Same declarations
-}]);
+const button1 = inject([rule], { cacheKey: 'button' });
+const button2 = inject([rule], { cacheKey: 'button' });
 
-// Both get the same className due to deduplication
+// One class, one copy of the CSS
 console.log(button1.className === button2.className); // true
 ```
 
+Without `cacheKey` the class name still matches (it hashes the rules), but the rule is inserted again and the pin count restarts at 1.
+
 ### Pinning
 
 ```typescript
 // Multiple callers using the same styles
-const comp1 = inject([commonStyle]);
-const comp2 = inject([commonStyle]);
-const comp3 = inject([commonStyle]);
+const comp1 = inject([commonStyle], { cacheKey: 'common' });
+const comp2 = inject([commonStyle], { cacheKey: 'common' });
+const comp3 = inject([commonStyle], { cacheKey: 'common' });
 
 // Style is pinned while any caller holds a handle
 comp1.dispose(); // pins: 3 → 2
@@ -439,15 +440,16 @@ const shadowAnimation = keyframes({
 
 ### Server-Side Rendering
 
+`getCSSText()` reads the injector's stylesheets, so it needs a DOM; on a server it throws. Collect server CSS with `ServerStyleCollector` from `@tenphi/tasty/ssr` (`collector.getCSS()`) — see [SSR](./ssr.md).
+
 ```typescript
 import { getCSSText, getCSSTextForNode } from '@tenphi/tasty';
+import { render } from '@testing-library/react';
 
-// Extract all CSS for SSR
-const cssText = getCSSText();
+const cssText = getCSSText(); // everything the injector holds (browser / test DOM)
 
-// Extract CSS for specific DOM subtree (like jest-styled-components)
-const container = render(<MyComponent />);
-const componentCSS = getCSSTextForNode(container);
+const { container } = render(<MyComponent />);
+const componentCSS = getCSSTextForNode(container); // only the CSS this subtree uses
 ```
 
 ### Test Environment Detection
@@ -520,17 +522,14 @@ console.log({
 ### Debug Information
 
 ```typescript
-// Get detailed information about injected styles
-const debugInfo = injector.instance.getDebugInfo();
+import { tastyDebug } from '@tenphi/tasty';
 
-console.log({
-  activeStyles: debugInfo.activeStyles,     // Currently active styles
-  unusedStyles: debugInfo.unusedStyles,     // Styles marked for cleanup
-  totalSheets: debugInfo.totalSheets,       // Number of stylesheets
-  totalRules: debugInfo.totalRules,         // Total CSS rules
-});
+const { activeClasses, unusedClasses, hotClasses, totalRuleCount } =
+  tastyDebug.summary({ raw: true });
 ```
 
+See [Debug Utilities](./debug.md).
+
 ### Cleanup History
 
 ```typescript

package/docs/methodology.md

@@ -119,16 +119,17 @@ 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, physical/logical margin, inset, scroll margin/padding, position                                 | Positioned elements (`Button`, `Badge`)       |
-| `DIMENSION_STYLES` | width, height, blockSize, inlineSize, flexBasis, flexGrow, flexShrink, flex                                                                                                    | Sized elements                                |
-| `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                       | Color-customizable elements                   |
-| `BLOCK_STYLES`     | padding, blockPadding, inlinePadding, overflow, scrollbar, textAlign, border, blockBorder, inlineBorder, 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, place, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`)           |
+| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, physical/logical margin, inset, scroll margin/padding, position                                      | Positioned elements (`Button`, `Badge`)       |
+| `DIMENSION_STYLES` | width, height, blockSize, inlineSize, flexBasis, flexGrow, flexShrink, flex                                                                                                           | Sized elements                                |
+| `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                              | Color-customizable elements                   |
+| `BLOCK_STYLES`     | padding, blockPadding, inlinePadding, overflow, scrollbar, textAlign, border, blockBorder, inlineBorder, radius, shadow, outline                                                      | Block-level containers                        |
+| `TEXT_STYLES`      | textTransform, fontWeight, fontStyle                                                                                                                                                  | Text elements                                 |
+| `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';
@@ -156,7 +157,10 @@ Match the preset to the component's role:
 
 - **Layout containers** (`Space`, `Box`, `Grid`) — `FLOW_STYLES`, optionally with `DIMENSION_STYLES`
 - **Positioned elements** (`Button`, `Badge`) — `POSITION_STYLES`
-- **Text elements** — custom: `['preset', 'color']`
+- **Text elements** — `['color', ...TEXT_STYLES]`
+
+`BASE_STYLES` (`display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`) are accepted as props on every component without being listed; extend that set app-wide with [`configure({ baseStyleProps })`](configuration.md#base-style-props).
+
 - **Compound components** — typically none; styling happens via sub-elements and extension
 
 ### The governance trade-off
@@ -220,6 +224,26 @@ modProps: ['isLoading', 'isSelected'] as const,
 
 For the full API reference, see [React API — Mod Props](react-api.md#mod-props).
 
+### variants vs modProps
+
+Use `variants` for looks that replace each other (primary, danger, ghost) and `modProps` for states that combine (`isLoading`, `size`):
+
+```tsx
+const Button = tasty({
+  as: 'button',
+  modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const },
+  styles: { padding: { '': '1.5x 3x', 'size=sm': '1x 2x' }, radius: '1r' },
+  variants: {
+    default: { fill: '#primary', color: '#on-primary' },
+    danger: { fill: '#danger', color: '#on-danger' },
+  },
+});
+
+<Button variant="danger" size="sm" isLoading />;
+```
+
+`variant` is typed from the variant keys, the `default` variant applies when no `variant` prop is passed, and only variants that render emit CSS. See [React API — Variants](react-api.md#variants).
+
 ---
 
 ## tokens prop for dynamic values
@@ -335,10 +359,9 @@ const LargeCard = tasty(Card, {
 
 Why? Styled wrappers are:
 
-- **Faster** — styles are parsed and injected once at definition time, not on every render
-- **Stable** — the style object is defined once, not recreated on every render
+- **Stable** — the style object is defined once at module level, not recreated on every render
 - **Composable** — another engineer can extend `LargeCard` further
-- **Inspectable** — the component has a name in React DevTools
+- **Inspectable** — give it a `qa` (`tasty(Card, { qa: 'LargeCard', styles })`) and it appears as `TastyWrappedComponent(LargeCard)` in React DevTools and as `data-qa="LargeCard"` in the DOM
 - **Lint-friendly** — the ESLint plugin's `no-styles-prop` rule flags direct usage
 
 The `styles` prop exists as an escape hatch — for prototyping, one-off overrides during development, or cases where wrapping is impractical. It should not be the default way product engineers customize components.
@@ -453,11 +476,13 @@ const DangerCard = tasty(Card, {
 
 This is preferred over `<Card styles={{ border: '1bw solid #danger' }}>` because:
 
-1. Styles are parsed and injected once, not on every render
+1. The styles live in one module-level definition instead of being rebuilt inside render
 2. `DangerCard` can be extended further by others
-3. It has a meaningful name in DevTools and code search
+3. It is searchable in code, and named in DevTools once you give it a `qa`
 4. The ESLint `no-styles-prop` rule encourages this pattern
 
+A wrapper does not re-expose the base's sub-element components: `DangerCard.Title` is `undefined` and not part of its type. Keep using the base's parts inside it — `<DangerCard><Card.Title>…</Card.Title></DangerCard>`. The wrapper's `Title` styles still apply, because they target `[data-element="Title"]`.
+
 ---
 
 ## How configuration simplifies components
@@ -554,7 +579,7 @@ fill: 'oklch(55% 0.25 265)',
 fill: '#primary',
 ```
 
-Tokens ensure consistency across components and make theme changes a one-line update.
+Tokens ensure consistency across components and make theme changes a one-line update. The recommended lint config flags this with `tasty/no-raw-color-values` and `tasty/consistent-token-usage`.
 
 ### Using CSS property names when Tasty alternatives exist
 
@@ -570,7 +595,7 @@ radius: '1r',
 flow: 'column',
 ```
 
-Tasty's enhanced properties provide concise syntax, better composability, and simpler overrides. See [recommended props](styles.md#recommended-props) for the full mapping.
+Tasty's enhanced properties provide concise syntax, better composability, and simpler overrides. See [recommended props](styles.md#recommended-props) for the full mapping. `tasty/prefer-shorthand-property` flags the native spellings.
 
 ### Changing styles prop at runtime
 
@@ -593,7 +618,7 @@ const Card = tasty({
 });
 ```
 
-Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS.
+Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS. `tasty/no-styles-prop` and `tasty/no-runtime-styles-mutation` flag these patterns.
 
 ### Overusing style prop
 
@@ -607,7 +632,7 @@ const DangerButton = tasty(Button, {
 });
 ```
 
-The `style` prop bypasses tokens, units, and state maps. It should only be used for third-party library integration.
+The `style` prop bypasses tokens, units, and state maps. It should only be used for third-party library integration. `tasty/no-style-prop` flags it on Tasty components.
 
 ### Skipping elements for compound components
 

package/docs/migration-v3.md

@@ -188,8 +188,8 @@ A key whose prefix doesn't match its value type is ignored with a development wa
 ## 7. Moved subpath
 
 ```diff
-- import { withTasty } from '@tenphi/tasty/next';
-+ import { withTasty } from '@tenphi/tasty/zero/next';
+- import { withTastyZero } from '@tenphi/tasty/next';
++ import { withTastyZero } from '@tenphi/tasty/zero/next';
 ```
 
 The build-time extraction Next.js wrapper already lived under the `zero` namespace internally; the top-level `/next` path collided confusingly with `@tenphi/tasty/ssr/next`, which is a different integration.

package/docs/pipeline.md

@@ -76,7 +76,7 @@ Output: CSSRule[]
 
 **Simplification** (`simplifyCondition` in `simplify.ts`) is not a separate numbered stage. It runs inside OR expansion, exclusive building, `expandExclusiveOrs` branch cleanup, combination ANDs, merge-by-value ORs, and materialization. Every call is cached by condition unique-id, so the repetition is cheap.
 
-**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` (`index.ts`) filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle`, then **stable-sorts rules by their cascade `order` hint (ascending source priority)** so lower-priority rules come first and higher-priority rules win, and finally emits every `@starting-style` rule **after** all normal rules. The `order` hint is the highest source priority among the entries that produced each rule (threaded `ComputedRule → CSSRule`). This ordering is cascade-critical because Stage 7 equalizes specificity with `:where()`: once every state selector carries zero specificity, source order alone decides which of two overlapping rules wins — most importantly the `_` fallback floor (low order, emitted first) versus the states layered over it, and `@starting-style` versus its normal counterpart. Mutually-exclusive rules are unaffected by ordering (they never both match), so reordering them is safe.
+**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` (`index.ts`) filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle`, then **stable-sorts rules by their cascade `order` hint (ascending source priority)** so lower-priority rules come first and higher-priority rules win, and finally emits every `@starting-style` rule **after** all normal rules. Each Stage 4 snapshot takes the highest source priority among its entries as its `order` hint; when Stage 6 merges same-output rules, the merged rule keeps the lowest `order` of its group, so a rule carrying the `_` floor's value keeps the floor's early position (threaded `ComputedRule → CSSRule`). This ordering is cascade-critical because Stage 7 equalizes specificity with `:where()`: once every state selector carries zero specificity, source order alone decides which of two overlapping rules wins — most importantly the `_` fallback floor (low order, emitted first) versus the states layered over it, and `@starting-style` versus its normal counterpart. Mutually-exclusive rules are unaffected by ordering (they never both match), so reordering them is safe.
 
 ---
 
@@ -197,7 +197,9 @@ Merging two same-value entries with conditions `C_h` (higher priority) and `C_l`
 
 The merge is safe iff for every entry `e_m` strictly between them in priority with a different value,
 
-    simplify(C_m & C_l & !C_h) = FALSE
+```
+simplify(C_m & C_l & !C_h) = FALSE
+```
 
 i.e. there is no scenario where the intermediate state could have matched, the lower same-value entry would also have matched, and the higher one would not. This is the only way the merge could leak through and shadow the intermediate state.
 
@@ -362,7 +364,7 @@ This is the companion to **Stage 2a** (user-OR expansion). The split exists beca
 
 | Stage | Runs on | Sees ORs from | Sorts branches? |
 |---|---|---|---|
-| 2a `expandOrConditions` | `ParsedStyleEntry.condition` | User-authored `|` in state keys | No — user order is stable |
+| 2a `expandOrConditions` | `ParsedStyleEntry.condition` | User-authored `\|` in state keys | No — user order is stable |
 | 3 `expandExclusiveOrs` | `ExclusiveStyleEntry.exclusiveCondition` | De Morgan negation inside `buildExclusiveConditions` | Yes — at-rule branches first |
 
 ### How It Works
@@ -545,12 +547,13 @@ interface CSSRule {
   declarations: string; // CSS declarations (e.g. 'color: red;')
   atRules?: string[]; // Wrapping at-rules
   rootPrefix?: string; // Root state prefix
+  rootState?: string; // Root-state segment without its :root anchor; lets a root selector take states directly
   startingStyle?: boolean; // Wrap declarations in @starting-style
   order?: number; // Internal cascade order hint (ascending source priority); stripped before injection
 }
 ```
 
-When `renderStyles` runs **without** a selector, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` inside `materialize.ts`.
+When `renderStyles` runs **without** a selector, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` (defined in `materialize-types.ts`).
 
 ---
 
@@ -618,7 +621,7 @@ Applies boolean algebra rules to reduce condition complexity and detect impossib
    - `A & (A | B) = A`
    - `A | (A & B) = A`
 
-7. **Range intersection**: For **media and container** dimension queries, impossible ranges simplify to `FALSE` (e.g. `@media(w > 400px) & @media(w < 300px)`). Ranges with compatible bounds are also merged in place (`w >= 400 & w <= 800` → a single bounded range).
+7. **Range intersection**: For **media and container** dimension queries, impossible ranges simplify to `FALSE` (e.g. `@media(w > 400px) & @media(w < 300px)`). Ranges with compatible bounds are also merged in place (`w >= 400 & w <= 800` → a single bounded range). Only bounds in the same unit are compared: `600px` and `40em` are never merged or found contradictory, because a query `em` follows the user's default font size. A bound with no numeric value (`calc(…)`) and a range whose two bounds use different units are left as they are.
 
 8. **Container style queries**: Conflicting or redundant `@container` style conditions on the same property can be reduced (see `simplify.ts` around the container-style conflict pass).
 
@@ -642,7 +645,7 @@ LRU and small auxiliary caches:
 | Cache | Size | Key | Purpose |
 |-------|------|-----|---------|
 | `pipelineCache` | 5000 | `pipelineCacheKey \|\| stringifyStyles(styles)` | Skip full pipeline for identical styles |
-| `parseCache` | 5000 | `trimmedStateKey + '\\0' + isSubElement + '\\0' + JSON.stringify(localPredefinedStates)` | Skip re-parsing identical state keys in context |
+| `parseCache` | 5000 | `trimmedStateKey + '\0' + (isSubElement ? '1' : '0') + '\0' + (localPredefinedStates non-empty ? JSON.stringify(localPredefinedStates) : '')` | Skip re-parsing identical state keys in context |
 | `simplifyCache` | 5000 | `getConditionUniqueId(node)` | Skip re-simplifying identical conditions |
 | `conditionCache` | 3000 | `getConditionUniqueId(node)` in `conditionToCSS` | Skip re-materializing identical conditions |
 | `variantKeyCache` | — | `WeakMap<SelectorVariant, string>` | Stable string keys for variants during materialization |
@@ -702,24 +705,24 @@ Each snapshot yields distinct declarations; no merge.
 
 ### Stage 7: Materialize CSS
 
-Using `renderStyles(styles, '.t1')` (the class is doubled — `.t1.t1` — so Tasty owns specificity without `!important`):
+Using `renderStyles(styles, '.t1', { doubleSelector: true })`. The injector doubles the class the same way (`.t1.t1`) so Tasty owns specificity without `!important`, and every state is wrapped in `:where()` so it adds none. Rules come out in ascending priority:
 
 ```css
-.t1[data-hovered] {
-  color: var(--highlight-color);
-  --current-color: var(--highlight-color);
+@media (not (prefers-color-scheme: dark)) {
+  .t1.t1:where(:not([data-hovered])) {
+    color: var(--white-color);
+    --current-color: var(--white-color);
+  }
 }
 @media (prefers-color-scheme: dark) {
-  .t1:not([data-hovered]) {
+  .t1.t1:where(:not([data-hovered])) {
     color: var(--dark-color);
     --current-color: var(--dark-color);
   }
 }
-@media (not (prefers-color-scheme: dark)) {
-  .t1:not([data-hovered]) {
-    color: var(--white-color);
-    --current-color: var(--white-color);
-  }
+.t1.t1:where([data-hovered]) {
+  color: var(--highlight-color);
+  --current-color: var(--highlight-color);
 }
 ```