@tenphi/tasty 3.9.11 → 3.11.0

package/docs/configuration.md

@@ -23,9 +23,8 @@ configure({
 
   // Custom units (merged with built-in units)
   units: {
-    vh: 'vh',
-    vw: 'vw',
-    custom: (n) => `${n * 10}px`, // Function-based unit
+    gu: '4px', // `2gu` → `8px`
+    cols: (n) => `calc(${n} * var(--col-width))`, // function-based unit
   },
 
   // Custom functions — a single map for both flavors, discriminated by value type:
@@ -47,35 +46,35 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 
 ## Options
 
-| Option               | Type                                             | Default                               | Description                                                                                                                                                          |
-| -------------------- | ------------------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nonce`              | `string`                                         | -                                     | CSP nonce for style elements                                                                                                                                         |
-| `maxRulesPerSheet`   | `number`                                         | `8192`                                | Maximum rules per injected stylesheet                                                                                                                                |
-| `forceTextInjection` | `boolean`                                        | auto (`true` in test envs)            | Force text-node CSS injection instead of constructable stylesheets                                                                                                   |
-| `devMode`            | `boolean`                                        | auto                                  | Enable development-mode features: performance metrics and debug info                                                                                                 |
-| `states`             | `Record<string, string>`                         | -                                     | Global state aliases for advanced state mapping                                                                                                                      |
-| `parserCacheSize`    | `number`                                         | `1000`                                | Parser LRU cache size                                                                                                                                                |
-| `units`              | `Record<string, string \| UnitHandler>`          | Built-in                              | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units)                                                                                     |
-| `functions`          | `Record<string, FunctionDefinition \| Function>` | -                                     | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                      |
-| `handlers`           | `Record<string, StyleHandlerDefinition>`         | Built-in                              | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers)                                                                        |
-| `propHandlers`       | `Record<string, PropHandlerDefinition>`          | -                                     | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware)                                                                |
-| `baseStyleProps`     | `readonly string[]`                              | -                                     | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props)                                                                       |
-| `tokens`             | `Record<string, value \| stateMap>`              | -                                     | Design tokens injected as `:root` CSS custom properties                                                                                                              |
-| `replaceTokens`      | `Record<string, string \| number \| boolean>`    | -                                     | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens                                                                        |
-| `keyframes`          | `Record<string, KeyframesSteps>`                 | -                                     | Global keyframes for animations                                                                                                                                      |
-| `properties`         | `Record<string, PropertyDefinition>`             | -                                     | Global CSS @property definitions                                                                                                                                     |
-| `fontFaces`          | `Record<string, FontFaceInput>`                  | -                                     | Global @font-face definitions                                                                                                                                        |
-| `counterStyles`      | `Record<string, CounterStyleDescriptors>`        | -                                     | Global @counter-style definitions                                                                                                                                    |
-| `polyfills`          | `{ functions?: boolean }`                        | `{}`                                  | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time                                             |
-| `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                                                                                                                            |
-| `plugins`            | `TastyPlugin[]`                                  | -                                     | Plugins that bundle any of the above (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md)                        |
-| `gc`                 | `GCConfig`                                       | -                                     | Garbage-collection tuning for unused styles (`{ touchInterval, capacity }`)                                                                                          |
-| `batchInjection`     | `boolean \| 'always'`                            | `false`                               | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection)                                                                     |
-| `colorSpace`         | `'rgb' \| 'hsl' \| 'oklch'`                      | -                                     | **Deprecated** — no longer has any effect. See [Color space](#color-space)                                                                                           |
-| `namePrefix`         | `string`                                         | `'t'` (`tasty`) / `'ts'` (build-time) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix). |
+| Option               | Type                                             | Default                                                                              | Description                                                                                                                                                                                                                                                                                                                             |
+| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nonce`              | `string`                                         | -                                                                                    | CSP nonce for style elements                                                                                                                                                                                                                                                                                                            |
+| `maxRulesPerSheet`   | `number`                                         | `8192`                                                                               | Maximum rules per injected stylesheet                                                                                                                                                                                                                                                                                                   |
+| `forceTextInjection` | `boolean`                                        | `false` (`true` in test environments only while `configure()` has never been called) | Force text-node CSS injection instead of constructable stylesheets. Set it explicitly in test setup                                                                                                                                                                                                                                     |
+| `devMode`            | `boolean`                                        | auto                                                                                 | Enable development-mode features: performance metrics and debug info. Does not turn on dev warnings; those follow `NODE_ENV` (or `localStorage.TASTY_DEBUG = 'true'` in a browser)                                                                                                                                                      |
+| `states`             | `Record<string, string>`                         | -                                                                                    | Global state aliases for advanced state mapping                                                                                                                                                                                                                                                                                         |
+| `parserCacheSize`    | `number`                                         | `1000`                                                                               | Parser LRU cache size                                                                                                                                                                                                                                                                                                                   |
+| `units`              | `Record<string, string \| UnitHandler>`          | Built-in                                                                             | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units)                                                                                                                                                                                                                                                        |
+| `functions`          | `Record<string, FunctionDefinition \| Function>` | -                                                                                    | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                                                                                                                                                                                         |
+| `handlers`           | `Record<string, StyleHandlerDefinition>`         | Built-in                                                                             | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers)                                                                                                                                                                                                                                           |
+| `propHandlers`       | `Record<string, PropHandlerDefinition>`          | -                                                                                    | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware)                                                                                                                                                                                                                                   |
+| `baseStyleProps`     | `readonly string[]`                              | -                                                                                    | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props)                                                                                                                                                                                                                                          |
+| `tokens`             | `Record<string, value \| stateMap>`              | -                                                                                    | Design tokens injected as `:root` CSS custom properties                                                                                                                                                                                                                                                                                 |
+| `replaceTokens`      | `Record<string, string \| number \| boolean>`    | `{ '#clear': 'transparent' }`                                                        | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens                                                                                                                                                                                                                                           |
+| `keyframes`          | `Record<string, KeyframesSteps>`                 | -                                                                                    | Global keyframes for animations                                                                                                                                                                                                                                                                                                         |
+| `properties`         | `Record<string, PropertyDefinition>`             | -                                                                                    | Global CSS @property definitions                                                                                                                                                                                                                                                                                                        |
+| `fontFaces`          | `Record<string, FontFaceInput>`                  | -                                                                                    | Global @font-face definitions                                                                                                                                                                                                                                                                                                           |
+| `counterStyles`      | `Record<string, CounterStyleDescriptors>`        | -                                                                                    | Global @counter-style definitions                                                                                                                                                                                                                                                                                                       |
+| `polyfills`          | `{ functions?: boolean }`                        | `{}`                                                                                 | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time                                                                                                                                                                                                                |
+| `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                                                                                                                                                                                                                                                                                               |
+| `plugins`            | `TastyPlugin[]`                                  | -                                                                                    | Plugins that bundle `functions`, `units`, `states`, `handlers`, `propHandlers`, `baseStyleProps`, `tokens`, `replaceTokens`, `recipes`, `presets`, `globalStyles`, `properties`, `keyframes`, `fontFaces`, and `counterStyles` (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md) |
+| `gc`                 | `GCConfig`                                       | -                                                                                    | Turns on automatic collection of unused styles: `{ touchInterval?, capacity?, grace? }` (defaults `1000`, `1000`, `10000` ms). Without it nothing is collected automatically; call `gc()` yourself                                                                                                                                      |
+| `batchInjection`     | `boolean \| 'always'`                            | `false`                                                                              | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection)                                                                                                                                                                                                                                        |
+| `colorSpace`         | `'rgb' \| 'hsl' \| 'oklch'`                      | -                                                                                    | **Deprecated** — no longer has any effect. See [Color space](#color-space)                                                                                                                                                                                                                                                              |
+| `namePrefix`         | `string`                                         | `'t'` (`tasty`) / `'ts'` (build-time)                                                | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix).                                                                                                                                                                    |
 
 ---
 
@@ -334,8 +333,7 @@ Tokens support state maps for responsive or theme-aware values:
 ```jsx
 configure({
   tokens: {
-    $gap: '4px',
-    $radius: '6px',
+    '$sidebar-width': '280px',
     '#primary': {
       '': '#purple',
       '@dark': '#light-purple',
@@ -350,9 +348,10 @@ configure({
 
 - `$name` keys become `--name` CSS custom properties
 - `#name` keys become `--name-color` custom properties
+- Tokens do not change units: `2x` stays `16px` whatever `$gap` is. To drive a unit from a token, point the unit at it: `units: { x: 'var(--gap)' }` makes `2x` compile to `calc(2 * var(--gap))`
 - Names keep their case, since CSS custom properties are case-sensitive: `$myVar` is `--myVar` and is referenced as `$myVar`. A leading capital is not supported and folds — `$Foo` and `#Purple` become `--foo` and `--purple-color` — so start names lowercase. Kebab-case (`$my-var`) remains the convention.
 
-Tokens are automatically emitted in all delivery modes: client rendering, server rendering, and build-time extraction with the Babel plugin.
+Tokens are emitted by the client injector, by the SSR collector (`TastyRegistry`, `tastyIntegration()`, `runWithCollector()`), by the `withTastyNext()` shared stylesheet, and by the Babel plugin. The inline React Server Component path without a collector does not emit them — see [Server-Side Rendering](ssr.md).
 
 ---
 
@@ -375,6 +374,17 @@ configure({
 
 When a component uses `padding: '$card-padding'`, the parser replaces it with `'4x'` before generating CSS. When a component uses `fill: '#accent'`, it is replaced with `'#purple'`, which in turn resolves to `var(--purple-color)`.
 
+Tasty includes `'#clear': 'transparent'` as a default replace token, available
+without calling `configure()`. It survives `resetConfig()`, and explicit
+`replaceTokens` entries can override it. A replace token resolving to the literal
+`transparent` ignores numeric and custom-property opacity suffixes:
+`#clear`, `#clear.5`, and `#clear.$opacity` all emit `transparent`.
+
+`#clear` no longer reads `--clear-color`, and Tasty no longer registers that
+property by default. If you previously customized `#clear` through `tokens`,
+local token definitions, or CSS, use a different color token or explicitly
+override `replaceTokens['#clear']` instead.
+
 See [Replace Tokens](dsl.md#replace-tokens) in the Style DSL reference.
 
 ---
@@ -471,7 +481,7 @@ See [Functions (`@function`)](dsl.md#functions-function) for inline usage inside
 
 ### Custom color functions
 
-A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `#token.alpha` opacity injection, and `parseColor` — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
+A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `parseColor`, and the `#token.alpha` opacity suffix, which calls the function with a `/ alpha` part appended (read `groups[0].parts[1]`, as below) — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
 
 ```ts
 import { configure, createColorFunc } from '@tenphi/tasty';
@@ -482,8 +492,12 @@ const myColorPlugin = () => ({
   functions: {
     // Hand-written parse function:
     mycolor: (groups) => {
-      const [r, g, b] = groups[0].all;
-      return `rgb(${r} ${g} ${b})`;
+      // `mycolor(255 0 0 / .5)` and `#brand.5` both arrive as two parts
+      const [main, alpha] = groups[0].parts;
+      const [r, g, b] = main.all;
+      return alpha?.all.length
+        ? `rgb(${r} ${g} ${b} / ${alpha.output})`
+        : `rgb(${r} ${g} ${b})`;
     },
   },
 });
@@ -631,7 +645,7 @@ configure({
 });
 ```
 
-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.
+Each key is a CSS selector (a list such as `'.uni-checkbox, uni-checkbox'` styles every item), and each value is a Tasty `Styles` object supporting the full style syntax including style properties, tokens, state maps, `@keyframes`, 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 delivery modes: client rendering, server rendering, and build-time extraction with the Babel plugin. Plugins can also provide `globalStyles`; they are merged per selector with config global styles (config wins on conflict).
 
@@ -690,10 +704,16 @@ Override or extend the built-in style property handlers. A handler definition ca
 | Single dep    | `['styleName', handler]`           | Triggered by the specified style property                       |
 | Multi dep     | `[['dep1', 'dep2', ...], handler]` | Triggered by any of the listed properties; receives all of them |
 
-The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy). Use `defineHandler` for it and the dependency types are inferred from the dependency list, so a typo in the destructure is a type error instead of a silent `undefined`.
+The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy). A handler whose dependencies include a built-in style takes over that style's whole group — see [Replacing a built-in handler](#replacing-a-built-in-handler). Use `defineHandler` for it and the dependency types are inferred from the dependency list, so a typo in the destructure is a type error instead of a silent `undefined`.
 
 ```jsx
-import { configure, defineHandler, styleHandlers } from '@tenphi/tasty';
+import {
+  configure,
+  defineHandler,
+  parseColor,
+  parseStyle,
+  styleHandlers,
+} from '@tenphi/tasty';
 
 configure({
   handlers: {
@@ -717,6 +737,10 @@ configure({
         'backgroundPosition',
         'backgroundSize',
         'backgroundRepeat',
+        'backgroundAttachment',
+        'backgroundOrigin',
+        'backgroundClip',
+        'background',
       ],
       (props) => {
         if (
@@ -729,12 +753,18 @@ configure({
       },
     ),
 
-    // Multi dep — handler reads multiple style properties
-    gap: defineHandler(['display', 'flow', 'gap'], ({ display, flow, gap }) => {
-      if (!gap) return;
-      const isGrid = String(display ?? '').includes('grid');
-      return { gap: isGrid ? gap : `/* custom logic for ${flow} */` };
-    }),
+    // Multi dep — triggered by either name, receives both
+    stripe: defineHandler(
+      ['stripe', 'stripeColor'],
+      ({ stripe, stripeColor }) => {
+        if (!stripe) return;
+        const width = parseStyle(String(stripe)).output;
+        const color = stripeColor
+          ? parseColor(String(stripeColor)).color
+          : 'currentcolor';
+        return { 'border-left': `${width} solid ${color}` };
+      },
+    ),
   },
 });
 ```
@@ -756,12 +786,17 @@ Built-in handlers are shared across several style names. Registering a handler f
 
 The shared groups worth knowing:
 
-| Registering a handler for      | Also takes over                                                                                           |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `fill`                         | `backgroundColor`, `image`, `backgroundImage`, `backgroundPosition`, `backgroundSize`, `backgroundRepeat` |
-| `display`                      | `hide`, `overflow`, `whiteSpace`, `textOverflow`, `flow`, `gap`                                           |
-| `preset`                       | `font`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textTransform`             |
-| `padding` / `margin` / `inset` | their `*Top`/`*Right`/`*Bottom`/`*Left`/`*Block`/`*Inline` longhands                                      |
+| Registering a handler for | Also takes over                                                                                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fill`                    | `backgroundColor`, `image`, `backgroundImage`, `backgroundPosition`, `backgroundSize`, `backgroundRepeat`, `backgroundAttachment`, `backgroundOrigin`, `backgroundClip`, `background` |
+| `display`                 | `hide`, `whiteSpace`, `textOverflow`, `flow`, `gap`                                                                                                                                   |
+| `flow`                    | `gap`                                                                                                                                                                                 |
+| `preset`                  | `font`, `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textTransform`                                                                           |
+| `padding` / `margin`      | their `Top`/`Right`/`Bottom`/`Left` longhands (`paddingTop`, `marginLeft`, …)                                                                                                         |
+| `inset`                   | `top`, `right`, `bottom`, `left`                                                                                                                                                      |
+| `width` / `height`        | `minWidth`/`maxWidth`, `minHeight`/`maxHeight`                                                                                                                                        |
+
+A multi-dep handler takes over every group its dependencies touch: `defineHandler(['display', 'flow', 'gap'], …)` takes over `display`, `flow`, and `gap` together, so it must emit `display` and `flex-flow` itself.
 
 Either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a name that isn't shared.
 
@@ -822,18 +857,98 @@ Each name costs one property check per render of every component, and the effect
 
 ---
 
-## Extending Style Types (TypeScript)
+## TypeScript
 
-Use module augmentation to extend the `StylesInterface`:
+Component props are typed from the `tasty()` definition with no setup. Module augmentation adds the names your design system defines and the extensions your plugins add.
+
+### Component props
+
+| In `tasty({ … })`                                                     | Adds the props                                                                                                                                                        |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `styleProps: ['gap', 'padding'] as const`                             | `gap`, `padding`, each typed like the style: a value or a state map                                                                                                   |
+| `modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const }` | `isLoading?: boolean`, `size?: 'sm' \| 'md' \| 'lg'` (`String` gives `string`, `Number` gives `number`)                                                               |
+| `modProps: ['isLoading'] as const`                                    | `isLoading?: ModValue`                                                                                                                                                |
+| `tokenProps: ['progress', 'accentColor'] as const`                    | `progress?: TokenValue`, `accentColor?: TokenValue`                                                                                                                   |
+| `variants: { default: {…}, danger: {…} }`                             | `variant?: 'default' \| 'danger'`                                                                                                                                     |
+| `elements: { Title: 'h3' }`                                           | `Card.Title`, with the `h3` props plus `qa`, `qaVal`, `mods`, `tokens`, `isDisabled`, `isHidden`, `isChecked`, and a `ref` typed as `HTMLHeadingElement`; no `styles` |
+| `as: SomeComponent`                                                   | `SomeComponent`'s own props, required ones still required                                                                                                             |
+
+Write the array forms with `as const`. Without it, `modProps: ['isLoading']` widens to `string[]` and every prop on the component is typed `ModValue`, so an `onClick` handler no longer type-checks. A `modProps` value list without `as const` widens to `string`.
+
+`tasty(Base, { … })` keeps `Base`'s prop types and adds none for the options above, which that form ignores — see [Extend an existing component](react-api.md#extend-an-existing-component).
+
+### Registering your names and extensions
+
+```ts
+// tasty.d.ts — keep the import: it makes this file a module, so the block
+// below extends '@tenphi/tasty' instead of replacing it.
+import '@tenphi/tasty';
 
-```tsx
-// tasty.d.ts
 declare module '@tenphi/tasty' {
+  interface TastyNamedColors {
+    surface: true;
+    text: true;
+    primary: true;
+  }
+  interface TastyPresetNames {
+    h1: true;
+    t2: true;
+  }
+  interface TastyThemeNames {
+    danger: true;
+    success: true;
+  }
   interface StylesInterface {
-    elevation?: string;
-    gradient?: string;
+    stripe?: string;
+  }
+  interface TastyCustomProps {
+    glaze: 'soft' | 'strong' | { tone: string; intensity?: number };
+  }
+  interface TastyBaseStylePropNames {
+    radius: true;
+    stripe: true;
   }
 }
 ```
 
+| Interface                 | Register                                                             | What it types                                                            |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `TastyNamedColors`        | Color token names from `tokens` and `replaceTokens`, without the `#` | Suggestions for `#name` and `#name.50` in `fill`, `color`, and `svgFill` |
+| `TastyPresetNames`        | `presets` names                                                      | The `preset` style and prop                                              |
+| `TastyThemeNames`         | Theme names                                                          | The `theme` prop (rendered as `data-theme`)                              |
+| `StylesInterface`         | Style properties added with `handlers`                               | Their value type in `styles`, `styleProps`, and base style props         |
+| `TastyCustomProps`        | Props added with `propHandlers`                                      | An optional prop on every `tasty()` component (not on sub-elements)      |
+| `TastyBaseStylePropNames` | Names passed to `baseStyleProps`                                     | A prop on every component, typed like the style it names                 |
+
+- The first three add autocomplete, not checking: any other string still type-checks (`preset: 'h9'` compiles). The ESLint plugin is what reports unknown names.
+- In `StylesInterface`, declare the plain value type (`stripe?: string`). Tasty adds state-map support itself, as it does for built-in styles.
+- A custom style name in `styles` type-checks without augmentation, but `styleProps` and `TastyBaseStylePropNames` accept only names in `StylesInterface`. A base style prop name missing from it adds no prop.
+- `TastyCustomProps` types the component prop, not the handler. A prop handler receives `Record<string, unknown>`, so cast inside it (`rest.styles as Styles`).
+- State keys, `$` value tokens, units, and recipe names have no TypeScript types. The ESLint plugin checks them against `tasty.config.ts`.
+
+### `tasty.config.ts`
+
+TypeScript augmentation does not reach the linter or the editor. [`@tenphi/eslint-plugin-tasty`](https://github.com/tenphi/eslint-plugin-tasty) and the Tasty VS Code extension read a `tasty.config.ts` (or `.js`, `.json`) at the project root instead. It only lists names: it is not passed to `configure()`, and it is unrelated to the Babel plugin's `configFile` (such as `tasty-zero.config.ts`).
+
+```ts
+// tasty.config.ts
+import type { TastyExtensionConfig } from '@tenphi/tasty';
+import type { TastyValidationConfig } from '@tenphi/eslint-plugin-tasty';
+
+export default {
+  tokens: ['#surface', '#text', '#primary', '$sidebar-width'],
+  units: ['cols'],
+  states: ['@mobile', '@dark'],
+  presets: ['h1', 't2'],
+  recipes: ['card', 'elevated'],
+  styles: ['stripe'],
+  importSources: ['@my-org/ui'],
+  presetDescriptions: { h1: 'Heading 1 (32px, bold)' },
+} satisfies TastyExtensionConfig & TastyValidationConfig;
+```
+
+`TastyExtensionConfig` from `@tenphi/tasty` types the fields the VS Code extension reads: `extends`, `tokens`, `units`, `functions`, `states`, `presets`, `styles`, `presetDescriptions`, and `stateDescriptions`. It has no `recipes`, `importSources`, `ownedSources`, or `styleFunctions`, so annotating the file with it alone rejects those ESLint fields; intersect it with the plugin's `TastyValidationConfig`, as above. An omitted list is not checked; `tokens: false`, `units: false`, or `functions: false` turns a check off even when an `extends` parent sets it.
+
+Keep it in step with `configure()`: token names with their `#` or `$`, custom units, parse-function names, state aliases, presets, recipes, and custom style names.
+
 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/debug.md

@@ -78,7 +78,7 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 |---|---|
 | `'all'` | All tasty CSS (component + global + raw) |
 | `'active'` | CSS for classes currently in the DOM |
-| `'unused'` | CSS for injected classes no element carries (cached but not rendered) |
+| `'unused'` | CSS for classes `gc({ force: true })` would delete now — not rendered, not pinned, past the `gc.grace` window |
 | `'global'` | Only global CSS (from `injectGlobal`) |
 | `'page'` | All CSS on the page (including non-tasty) |
 | `'t3a5f'` | CSS for a specific tasty class (class names are `t` + base36 hash) |
@@ -154,7 +154,8 @@ One-shot overview of the entire Tasty CSS state. Logs a compact report.
 ```typescript
 interface Summary {
   activeClasses: string[];
-  unusedClasses: string[];
+  unusedClasses: string[]; // classes gc({ force: true }) would delete now
+  hotClasses: string[]; // not rendered, but pinned or inside gc.grace — not yet collectable
   totalStyledClasses: string[];
 
   activeCSSSize: number;

package/docs/design-system.md

@@ -42,15 +42,25 @@ configure({
     // Borders
     '#border': '#e0e0e0',
 
-    // Unit values
+    // Spacing and shape scale
     $gap: '8px',
     $radius: '4px',
     '$border-width': '1px',
     '$outline-width': '2px',
   },
+  // Built-in units compile to fixed values by default. Pointing them at the
+  // tokens above lets a theme or density mode change the scale at runtime.
+  units: {
+    x: 'var(--gap)', // 2x → calc(2 * var(--gap))
+    r: 'var(--radius)',
+    bw: 'var(--border-width)',
+    ow: 'var(--outline-width)',
+  },
 });
 ```
 
+Leave out the `units` block to keep the built-in fixed scale (`x` = `8px`, `r` = `6px`, `bw` = `1px`, `ow` = `3px`), or set fixed values there instead (`units: { x: '8px', r: '4px' }`). Define the token a unit points at; until you do, `--gap`, `--radius`, `--border-width`, and `--outline-width` start at the built-in unit values. Boolean shorthands follow the same scale: `radius: true` is `1r`, `border: true` is `1bw`, and `outline: true` is `1ow`. See [Built-in Units](dsl.md#built-in-units).
+
 Tokens are injected as CSS custom properties on `:root` when the first style is rendered. They support state maps for theme-aware values:
 
 ```tsx
@@ -66,7 +76,7 @@ configure({
 
 The `#on-*` convention names the text color that sits on top of a fill — `#on-primary` is the text color on a `#primary` background. This makes state maps self-documenting: `fill: '#primary'` and `color: '#on-primary'` clearly belong together.
 
-For OKHSL-based palette generation with automatic WCAG contrast solving, see [Glaze](https://github.com/tenphi/glaze).
+To generate the whole palette instead of hand-picking values, use [Glaze](https://github.com/tenphi/glaze): it builds light, dark, and high-contrast variants from one hue in the OKHST color space, solves WCAG and APCA contrast, and exports Tasty tokens you can pass straight to `configure({ tokens: theme.tasty() })`.
 
 ### Replace tokens for value aliases
 
@@ -176,11 +186,13 @@ const Card = tasty({
   styles: {
     padding: { '': '4x', '@mobile': '2x' },
     flow: { '': 'row', '@mobile': 'column' },
-    fill: { '': '#surface', '@dark': '#surface-dark' },
+    radius: { '': '1r', '@mobile': '0' },
   },
 });
 ```
 
+Theme switching belongs in tokens (`'#surface': { '': '#fff', '@dark': '#1c1c1e' }`) rather than in component state maps, so components stay theme-agnostic.
+
 Without aliases, the same component would need the full media query expression inlined in every state map — across every property, in every component. Aliases eliminate that duplication.
 
 ---
@@ -279,7 +291,7 @@ const Grid = tasty({
     display: 'grid',
     gap: '1x',
   },
-  styleProps: [...FLOW_STYLES, 'gridColumns', 'gridRows', 'gridAreas'],
+  styleProps: FLOW_STYLES, // includes gridColumns, gridRows, gridAreas
 });
 ```
 
@@ -298,18 +310,54 @@ Product engineers use these to compose layouts without writing CSS:
 </Grid>
 ```
 
+### Interactive components with variants
+
+Variants are named looks that replace each other. Combine them with `modProps` for states that stack, such as size or loading:
+
+```tsx
+const Button = tasty({
+  as: 'button',
+  modProps: { size: ['sm', 'md', 'lg'] as const },
+  styles: {
+    recipe: 'interactive',
+    padding: { '': '1.5x 3x', 'size=sm': '1x 2x', 'size=lg': '2x 4x' },
+    radius: '1r',
+  },
+  variants: {
+    default: {
+      fill: {
+        '': '#primary',
+        ':hover': '#primary-hover',
+        disabled: '#surface',
+      },
+      color: '#on-primary',
+    },
+    danger: {
+      fill: { '': '#danger', ':hover': '#danger-hover', disabled: '#surface' },
+      color: '#on-danger',
+    },
+  },
+});
+
+<Button variant="danger" size="lg">
+  Delete
+</Button>;
+```
+
+`variant` is typed from the keys, the `default` variant applies when no `variant` prop is passed, and only the variants that actually render emit CSS. See [React API — Variants](react-api.md#variants).
+
 ### Which styleProps to expose
 
 Match the prop set to the component's role:
 
-| Component category                         | Recommended styleProps                                         |
-| ------------------------------------------ | -------------------------------------------------------------- |
-| Layout containers (`Space`, `Box`, `Grid`) | `FLOW_STYLES` — flow, gap, align, justify, padding, fill       |
-| Positioned elements (`Button`, `Badge`)    | `POSITION_STYLES` — placeSelf, gridArea, order                 |
-| Text elements                              | `['preset', 'color']` or a custom subset                       |
-| Compound components                        | Typically none — styling happens via sub-elements and wrapping |
+| Component category                         | Recommended styleProps                                                                              |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Layout containers (`Space`, `Box`, `Grid`) | `FLOW_STYLES` — flow, gap, align/justify/place, grid templates (add `padding` or `fill` explicitly) |
+| Positioned elements (`Button`, `Badge`)    | `POSITION_STYLES` — placeSelf, gridArea, order                                                      |
+| Text elements                              | `['color', ...TEXT_STYLES]` (`preset` is always available)                                          |
+| Compound components                        | Typically none — styling happens via sub-elements and wrapping                                      |
 
-Exposing too many props weakens the design system's constraints. See [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api) for the rationale.
+`BASE_STYLES` (`display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`) are accepted as props on every component without being listed. Exposing too many props weakens the design system's constraints. See [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api) for the rationale.
 
 ---
 
@@ -369,14 +417,14 @@ For sub-element syntax details (selector affix `$`, `@own()`, `elements` config)
 
 ## Defining the override contract
 
-A design system works best when the rules for customization are explicit. Tasty provides three levels of control:
+A design system works best when the rules for customization are explicit. Tasty gives product engineers four sanctioned ways to customize a component, and a few to discourage:
 
 ### What product engineers can do
 
 1. **Use styleProps** — adjust layout, spacing, positioning through the props the component exposes:
 
 ```tsx
-<Space flow="row" gap="3x" padding="2x">
+<Space flow="row" gap="3x" placeItems="center">
 ```
 
 2. **Use modProps** — control component states through typed props instead of `mods`:
@@ -398,7 +446,12 @@ A design system works best when the rules for customization are explicit. Tasty
 ```tsx
 const DangerButton = tasty(Button, {
   styles: {
-    fill: { '': '#danger', ':hover': '#danger-hover' },
+    fill: {
+      '': '#danger',
+      ':hover': '#danger-hover',
+      ':active': '#danger-pressed',
+      disabled: '@inherit', // a map with '' replaces the parent's; keep its disabled branch
+    },
     color: '#on-danger',
   },
 });
@@ -414,6 +467,53 @@ See [Methodology — styles prop vs style prop](methodology.md#styles-prop-vs-st
 
 ---
 
+## Guardrails: linting and types
+
+A vocabulary only holds if mistakes surface early. Register the same names you pass to `configure()` with the ESLint plugin and with TypeScript:
+
+```ts
+// tasty.config.ts — read by @tenphi/eslint-plugin-tasty
+export default {
+  tokens: ['#surface', '#text', '#primary', '#danger', '$gap', '$radius'],
+  states: ['@mobile', '@tablet', '@desktop', '@dark', '@reduced-motion'],
+  presets: ['h1', 'h2', 'h3', 't2', 't3'],
+  recipes: ['card', 'elevated', 'input-reset', 'interactive'],
+  importSources: ['@my-org/ds'], // where product code imports tasty() from
+};
+```
+
+```js
+// eslint.config.js
+import tasty from '@tenphi/eslint-plugin-tasty';
+
+export default [tasty.configs.recommended]; // or tasty.configs.strict
+```
+
+```ts
+// tasty.d.ts
+import '@tenphi/tasty';
+
+declare module '@tenphi/tasty' {
+  interface TastyNamedColors {
+    surface: true;
+    text: true;
+    primary: true;
+    danger: true;
+  }
+  interface TastyPresetNames {
+    h1: true;
+    h2: true;
+    h3: true;
+    t2: true;
+    t3: true;
+  }
+}
+```
+
+Unknown colors, presets, and recipes then fail lint (`valid-color-token`, `valid-preset`, `valid-recipe`), and `strict` adds checks for unknown `$` tokens and state aliases (`valid-custom-property`, `no-unknown-state-alias`). The same names autocomplete in editors. Deriving both lists from the same token and recipe modules that `config.ts` imports keeps all three in sync.
+
+---
+
 ## Project structure
 
 A recommended structure for a design system built on Tasty:
@@ -421,6 +521,8 @@ A recommended structure for a design system built on Tasty:
 ```
 ds/
   config.ts              # configure() — tokens, units, states, recipes
+  tasty.config.ts        # Names the ESLint plugin validates against
+  tasty.d.ts             # TypeScript augmentation for autocomplete
   primitives/
     Space.tsx             # Layout: flex container with FLOW_STYLES
     Box.tsx               # Generic container
@@ -436,7 +538,7 @@ ds/
   tokens/
     colors.ts             # Color token definitions
     typography.ts         # Typography presets for configure({ presets })
-    spacing.ts            # Spacing token definitions
+    units.ts              # Spacing and shape scale for configure({ units })
   index.ts                # Public API: re-exports components + configure
 ```