@cube-dev/ui-kit 0.0.0-canary-2757f7b → 0.0.0-canary-8b6ee8a

package/docs/glaze/methodology.md

@@ -642,6 +642,25 @@ In HC variants, Glaze bypasses the normal tone window and uses the full
 `[0, 100]` range. Edge tones can reach the edge; contrast floors have more room
 to solve.
 
+### A slider instead of a tier
+
+The two-tier model assumes contrast is a binary OS preference. When contrast is
+instead a setting *your users* control, set
+[`contrastLevel`](api.md#manual-contrast-level) to a number and the HC tier
+becomes a `0–100` ramp: level `0` is your normal palette, `100` is the HC
+palette you already authored, and everything between is resolved at that level.
+
+The authoring work is the same — the HC pairs above are what the slider ramps
+toward, so a palette tuned for high contrast needs no new fields. Two
+consequences worth planning for:
+
+- The separate HC tier stops being emitted, so wire the level itself into your
+  build or runtime rather than a `prefers-contrast: more` block. Existing
+  media-query wiring keeps working; it just receives the same values as the base
+  block.
+- `contrastLevel: 0` is a useful state in its own right: normal contrast with no
+  HC tier at all, for products that ship the slider but default it off.
+
 ## Checklist
 
 Before shipping a palette, verify:
@@ -654,7 +673,8 @@ Before shipping a palette, verify:
 - Low-stakes visual relationships use tone deltas instead of fake contrast
   floors.
 - `inherit: false` is set on default-only tokens so status themes stay focused.
-- HC pairs exist where high contrast should visibly tighten.
+- HC pairs exist where high contrast should visibly tighten (they double as the
+  ramp for a manual `contrastLevel`).
 - `glaze.configure({ states, modes })` matches the states registered in the app.
 - Every emitted scheme (`light`, `dark`, `lightContrast`, `darkContrast`) has
   been reviewed on complete screens, not only in a token grid.

package/docs/glaze/okhst.md

@@ -85,6 +85,19 @@ lightTone: { lo: 10, hi: 100, eps: 0.05 }
 Pass `false` to use the full range. High-contrast variants always bypass the
 ordinary boundaries and use the full range.
 
+A [manual contrast level](api.md#manual-contrast-level) generalizes that bypass
+continuously: with `contrastLevel: L` (`f = L / 100`), each boundary moves toward
+the full range instead of jumping to it —
+
+```text
+lo(f) = lo + (0   - lo) * f
+hi(f) = hi + (100 - hi) * f
+```
+
+— so the light default walks `[10, 100] → [0, 100]` and the dark default
+`[15, 95] → [0, 100]`. The render `eps` is not interpolated, and a `false` window
+is already the full range and therefore level-invariant.
+
 ## Scheme adaptation
 
 Each regular color has an adaptation `mode`:

package/docs/tasty/README.md

@@ -20,15 +20,13 @@ Tasty is a styling engine for design systems that turns component state into det
 - **React components**: [React API](react-api.md)
 - **Zero-runtime / build-time extraction**: [Zero Runtime (tastyStatic)](tasty-static.md)
 - **Runtime `tasty()` with server collection and hydration**: [Server-Side Rendering](ssr.md)
-- **Upgrading from v2**: [Migration Guide (v2 → v3)](migration-v3.md)
 
 ## By Task
 
 - **Learn the style language**: [Style DSL](dsl.md)
 - **Brief an AI agent (or yourself) on writing correct styles**: [Style Rules for AI Agents](ai-agents.md)
 - **Look up a property handler**: [Style Properties](styles.md)
-- **Define tokens, units, recipes, keyframes, properties, functions, or polyfills globally**: [Configuration](configuration.md)
-- **Extend Tasty with a plugin, custom handler, or custom prop**: [Plugins & Extension Points](plugins.md)
+- **Define tokens, units, recipes, keyframes, or properties globally**: [Configuration](configuration.md)
 - **Debug generated CSS or cache behavior**: [Debug Utilities](debug.md)
 - **Understand how selector generation works internally**: [Style rendering pipeline](pipeline.md)
 - **Understand runtime injection internals**: [Style Injector](injector.md)

package/docs/tasty/ai-agents.md

@@ -1,6 +1,6 @@
 # Tasty Style Rules for AI Agents
 
-A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — most rules here are machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it generally means clean lint output. The plugin ships separately and can lag a new DSL rule, so treat this page as the source of truth and the plugin as the enforcement that catches most of it. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
+A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — every rule here is machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it means clean lint output. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
 
 Notation: ❌ wrong → ✅ correct.
 
@@ -64,8 +64,7 @@ The last row goes the other way — longhands over the shorthand — because `fl
 | `#clear` / `#current` | `transparent` / `currentcolor` |
 | `$name` | custom property → `var(--name)` |
 | `(#a, #b)` | fallback chain |
-| `$$name` / `##name` | the custom property *name* (not its value) — inside `transition` |
-| `$$name(…)` | call a CSS `@function` declared via `@function`, `useFunction`, or config |
+| `$$name` / `##name` | the property *name* — only inside `transition` |
 
 - ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
 - ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
@@ -83,7 +82,7 @@ Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'
 
 ### `true`
 
-`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
 
 ### `!important`
 
@@ -91,7 +90,7 @@ Never use it. Tasty owns specificity through doubled selectors and state orderin
 
 ### Modifiers
 
-A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). A group that names **direction** modifiers takes a **single** value, applied to every direction it names — per-side values come from comma groups. A group naming no direction keeps plain CSS shorthand order (1–4 values). (`inset` + `dock` is the one exception: a second value insets the spanned sides.) Only the modifiers a property knows are valid:
+A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). Only the modifiers a property knows are valid:
 
 | Property | Modifiers |
 |----------|-----------|
@@ -112,8 +111,6 @@ Directional modifiers beat placeholder zeros:
 - ❌ `padding: '0 0 2x 0'` → ✅ `padding: '2x bottom'`
 - ❌ `padding: '1x 1x 2x 1x'` → ✅ `padding: '1x, 2x bottom'`
 - ❌ `border: '0 0 1bw 0'` — four tokens parse as *one* border value, so this renders no border at all → ✅ `border: '1bw bottom'`
-- ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
-- ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
 
 Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, `tabSize`, `paddingInline`, `paddingBlock`. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
 
@@ -187,21 +184,11 @@ styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent'
 | Key | Shape |
 |-----|-------|
 | `@keyframes` | `{ name: { '0%': styles, … } }` |
-| `@property` | `{ '$name': { syntax, inherits, initialValue } }` |
-| `@font-face` | `{ 'Family Name': descriptors \| descriptors[] }` |
-| `@counter-style` | `{ name: descriptors }` |
-| `@function` | `{ '$$name': { args, returns?, result, '$local'? } }` |
+| `@properties` | `{ '$name': { syntax, inherits, initialValue } }` |
+| `@fontFace` | `{ 'Family Name': descriptors \| descriptors[] }` |
+| `@counterStyle` | `{ name: descriptors }` |
 | `recipe` | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
 
-At-rule keys match the real CSS at-rule names, so they are kebab-case, not camelCase. Inside `@function`, the callable is `$$name` but its parameters and local variables are `$name`:
-
-```jsx
-styles: {
-  '@function': { $$negative: { args: ['$value'], result: '(-1 * $value)' } },
-  marginTop: '$$negative(2x)',
-}
-```
-
 ## 7. `tastyStatic()`
 
 The selector must be a string literal and valid CSS. Values must be static — strings, numbers, booleans, `null`, or objects/arrays of those. No variables, template literals, function calls, or spreads.
@@ -216,5 +203,4 @@ The selector must be a string literal and valid CSS. Values must be static — s
 - Modifiers valid for the property; directional shorthand instead of placeholder zeros.
 - Every state map starts with `''` (or `_`), is flat, and lives inside a property value.
 - `@own()` only inside sub-elements; sub-element keys are capitalized and hold objects.
-- At-rule keys are kebab-case (`@property`, `@font-face`, `@counter-style`, `@function`); `@function` names use `$$`, their args and locals use `$`.
 - Values are static; dynamic behavior comes from `mods` / `tokens` / `styleProps`.

package/docs/tasty/configuration.md

@@ -26,15 +26,12 @@ configure({
     custom: (n) => `${n * 10}px`, // Function-based unit
   },
 
-  // Custom functions — a single map for both flavors, discriminated by value type:
-  functions: {
-    // Bare key + function value → parse-time function, called as `double(...)`
+  // Custom functions for the parser
+  funcs: {
     double: (groups) => {
       const value = parseFloat(groups[0]?.output || '0');
       return `${value * 2}px`;
     },
-    // `$$name` key + object value → declarative CSS @function, called as `$$negative(...)`
-    $$negative: { args: ['$value'], result: '(-1 * $value)' },
   },
 });
 ```
@@ -48,31 +45,23 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 | 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) |
+| `units` | `Record<string, string \| Function>` | Built-in | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units) |
+| `funcs` | `Record<string, Function>` | - | Custom parser functions (merged with existing) |
+| `handlers` | `Record<string, StyleHandlerDefinition>` | Built-in | Custom style handlers (replace built-in) |
 | `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 |
+| `replaceTokens` | `Record<string, string \| number>` | - | Parse-time token substitution (inline replacement) |
 | `keyframes` | `Record<string, KeyframesSteps>` | - | Global keyframes for animations |
 | `properties` | `Record<string, PropertyDefinition>` | - | Global CSS @property definitions |
-| `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 |
+| `fontFace` | `Record<string, FontFaceInput>` | - | Global @font-face definitions |
+| `counterStyle` | `Record<string, CounterStyleDescriptors>` | - | Global @counter-style definitions |
 | `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
 | `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
 | `presets` | `Record<string, TypographyPreset>` | - | Typography presets — shorthand for `generateTypographyTokens()` |
 | `globalStyles` | `Record<string, Styles>` | - | Global Tasty styles keyed by CSS selector |
-| `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 }`) |
 | `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
-| `namePrefix` | `string` | `'t'` (runtime) / `'ts'` (zero-runtime) | 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). |
+| `namePrefix` | `string` | `'t'` (runtime) / `'ts'` (zero-runtime) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). See [Name prefix](#name-prefix). |
 
 ---
 
@@ -198,7 +187,7 @@ Register custom fonts globally so every component can reference them by family n
 
 ```ts
 configure({
-  fontFaces: {
+  fontFace: {
     'Brand Sans': [
       {
         src: 'url("/fonts/brand-regular.woff2") format("woff2")',
@@ -221,7 +210,7 @@ configure({
 
 Now any component can use `fontFamily: '"Brand Sans", sans-serif'` and the browser will already have the `@font-face` rules in the stylesheet.
 
-See [Font Face (`@font-face`)](dsl.md#font-face-font-face) for inline usage inside component styles and the full list of supported descriptors.
+See [Font Face (`@fontFace`)](dsl.md#font-face-fontface) for inline usage inside component styles and the full list of supported descriptors.
 
 ---
 
@@ -231,7 +220,7 @@ Define custom list-marker algorithms globally. Rules are injected eagerly when s
 
 ```ts
 configure({
-  counterStyles: {
+  counterStyle: {
     thumbs: {
       system: 'cyclic',
       symbols: '"👍"',
@@ -247,98 +236,7 @@ configure({
 
 Components can then reference `listStyleType: 'thumbs'` directly.
 
-See [Counter Style (`@counter-style`)](dsl.md#counter-style-counter-style) for inline usage inside component styles and the full list of supported descriptors.
-
----
-
-## Functions
-
-The single `functions` map holds both kinds of custom functions, discriminated by the value type:
-
-- **Parse functions** — a **bare key** with a **function value** `(groups) => string`. Runs at parse time and is called as `name(...)`. Use these for computed/derived CSS that JavaScript produces (e.g. color-space conversions).
-- **CSS `@function` definitions** — a **`$$name` key** with an **object value** (a [`FunctionDefinition`](https://developer.mozilla.org/en-US/docs/Web/CSS/@function)). Injected eagerly as a native `@function` rule and called as `$$name(...)` (→ `--name(...)`).
-
-```ts
-configure({
-  functions: {
-    // Parse function — bare key, function value
-    double: (groups) => `calc(2 * ${groups[0]?.output ?? '0'})`,
-
-    // CSS @function — `$$` key, object value
-    $$negative: { args: ['$value'], result: '(-1 * $value)' },
-    $$shadow: {
-      args: { '$shadow-color': { syntax: '<color>', default: 'inherit' } },
-      returns: '<color>',
-      $offset: '2px',
-      result: '$offset $offset ($shadow-color, black)',
-    },
-  },
-});
-```
-
-Components then invoke parse functions as `double(...)` and CSS functions with the `$$name(...)` sugar, e.g. `marginTop: '$$negative(10px)'`.
-
-> A key whose prefix doesn't match its value type (an object under a bare key, or a function under a `$$` key) is **ignored with a dev-mode warning**.
-
-See [Functions (`@function`)](dsl.md#functions-function) for inline usage inside component styles, the full descriptor shape, and token conventions. `@function` is an experimental CSS feature — unsupported browsers safely ignore the native rule (see the polyfill below).
-
-### 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, token decomposition into the configured color space, 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.
-
-```ts
-import { configure, createColorFunc } from '@tenphi/tasty';
-
-// A custom color space is just a `functions` entry.
-const myColorPlugin = () => ({
-  name: 'mycolor',
-  functions: {
-    // Hand-written parse function:
-    mycolor: (groups) => {
-      const [r, g, b] = groups[0].all;
-      return `rgb(${r} ${g} ${b})`;
-    },
-  },
-});
-
-configure({ plugins: [myColorPlugin()] });
-
-// Now `mycolor(...)` is a color in every context:
-//   fill: 'mycolor(255 0 0)'
-//   fill: '#brand.5'   (with replaceTokens: { '#brand': 'mycolor(255 0 0)' })
-```
-
-For HSL-style color spaces (a hue angle plus two percentages), the exported `createColorFunc(name, convert, label?)` helper handles angle/percentage parsing, clamping, alpha, and caching. `convert` returns sRGB `[r, g, b]` in 0-1; `label` is an optional string used only in dev warnings (e.g. `'H S L'`) and has no effect on output. This is exactly how `okhslPlugin`/`okhstPlugin` are implemented.
-
----
-
-## Polyfills
-
-`@function` only ships natively in Chromium 139+. To use CSS functions in browsers that don't support the at-rule yet (Firefox, Safari), enable the **functions polyfill**, which expands every `$$name(...)` call into plain CSS (`calc()`/`var()`/`color-mix()`) at parse time instead of emitting the native `@function` rule:
-
-```ts
-configure({
-  polyfills: {
-    functions: true, // default: false
-  },
-  functions: {
-    $$negative: { args: ['$value'], result: '(-1 * $value)' },
-  },
-});
-
-// Now `marginTop: '$$negative(10px)'` renders `margin-top: calc(-1 * 10px)`
-// — no native @function rule is emitted.
-```
-
-This works across all rendering modes (client, SSR/RSC, and `tastyStatic`) because expansion happens in the parser. Note `polyfills.functions` (the feature toggle) is distinct from the top-level `functions` (the definitions map).
-
-**Decided limitations when the polyfill is on:**
-
-- **No native fallback** — functions are always inlined; we do exactly what is configured.
-- **Conditional results** (`@media`/`@supports`/`if()` inside `result`) are inlined verbatim; the conditional nuance is not resolved per-element.
-- **Typed params / `returns`** are dropped (inlining is purely lexical substitution).
-- **Param name collisions** are avoided by fully inlining argument values (no function-internal custom properties are emitted) and by namespacing the function's own variables.
-- **Recursion** — self/mutually-recursive functions are not expanded; the cycle guard bails and leaves the call untouched.
+See [Counter Style (`@counterStyle`)](dsl.md#counter-style-counterstyle) for inline usage inside component styles and the full list of supported descriptors.
 
 ---
 
@@ -362,7 +260,7 @@ configure({
 });
 ```
 
-Recipe values are flat tasty styles (no sub-element keys). They may contain base styles, tokens, local states, `@keyframes`, and `@property`. Recipes cannot reference other recipes.
+Recipe values are flat tasty styles (no sub-element keys). They may contain base styles, tokens, local states, `@keyframes`, and `@properties`. Recipes cannot reference other recipes.
 
 For how to apply, compose, and override recipes in components, see [Recipes](dsl.md#recipes) in the Style DSL reference.
 
@@ -451,12 +349,12 @@ Supported types:
 | `300ms`, `1s` (time units) | `<time>` |
 | `#name` tokens (by naming convention) | `<color>` |
 
-Auto-inferred properties use `inherits: true` (the CSS default). Use explicit `@property` when you need different settings:
+Auto-inferred properties use `inherits: true` (the CSS default). Use explicit `@properties` when you need different settings:
 
 ```jsx
 // In component styles
 styles: {
-  '@property': {
+  '@properties': {
     '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
   },
 }
@@ -469,7 +367,7 @@ configure({
 });
 ```
 
-To disable auto-inference entirely (only explicit `@property` will be used):
+To disable auto-inference entirely (only explicit `@properties` will be used):
 
 ```jsx
 configure({ autoPropertyTypes: false });
@@ -487,13 +385,21 @@ 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).
 
 ```jsx
-import { configure, defineHandler, styleHandlers } from '@tenphi/tasty';
+import { configure, styleHandlers } from '@tenphi/tasty';
 
 configure({
   handlers: {
+    // Function only — overrides built-in fill handler
+    fill: ({ fill }) => {
+      if (fill?.startsWith('gradient:')) {
+        return { background: fill.slice(9) };
+      }
+      return styleHandlers.fill({ fill });
+    },
+
     // Function only — new single-prop handler
     elevation: ({ elevation }) => {
       const level = parseInt(elevation) || 1;
@@ -503,112 +409,16 @@ configure({
       };
     },
 
-    // Overriding a built-in: declare every style the built-in handled and pass
-    // them all through, or the ones you leave out stop working (see below).
-    fill: defineHandler(
-      [
-        'fill', 'backgroundColor', 'image', 'backgroundImage',
-        'backgroundPosition', 'backgroundSize', 'backgroundRepeat',
-      ],
-      (props) => {
-        if (typeof props.fill === 'string' && props.fill.startsWith('gradient:')) {
-          return { background: props.fill.slice(9) };
-        }
-        return styleHandlers.fill(props);
-      },
-    ),
-
     // Multi dep — handler reads multiple style properties
-    gap: defineHandler(['display', 'flow', 'gap'], ({ display, flow, gap }) => {
+    gap: [['display', 'flow', 'gap'], ({ display, flow, gap }) => {
       if (!gap) return;
-      const isGrid = String(display ?? '').includes('grid');
+      const isGrid = display?.includes('grid');
       return { gap: isGrid ? gap : `/* custom logic for ${flow} */` };
-    }),
+    }],
   },
 });
 ```
 
-### Return shape
-
-A handler returns a `CSSMap`, an array of them, or nothing:
-
-- Keys are **kebab-case** CSS property names (`'background-color'`, not `backgroundColor`) or `--custom-property` names. A camelCase key warns in development and is emitted verbatim, which the browser ignores.
-- Values are stringified, so numbers are fine (`{ '-webkit-line-clamp': 3 }`).
-- The reserved `$` key is a **selector suffix**: `{ $: '& > *:not(:last-child)', 'margin-right': gap }` applies the declarations to a nested selector. It accepts an array to fan out over several.
-- Return an array of maps to emit several declaration sets, each with its own `$`.
-
-Values arrive **state-resolved but unparsed** — the raw authored DSL string (`'2x'`, `'#purple.5'`, `true`, `4`). Call the exported `parseStyle()` / `parseColor()` yourself; nothing parses them for you.
-
-### Replacing a built-in handler
-
-Built-in handlers are shared across several style names. Registering a handler for one of those names unregisters the built-in from **all** of them, and the displaced names then fall back to auto-generated CSS aliases — so `hide: true` starts emitting a literal `hide: true` declaration. A development-mode warning lists exactly what was displaced.
-
-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 |
-
-Either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a name that isn't shared.
-
-### Chunk membership
-
-Tasty renders and caches CSS in independent chunks, and a chunk's cache key covers only its own style values. All of a handler's dependencies must therefore live in one chunk. Custom style names are pulled into their handler's chunk automatically at registration; a handler whose dependencies span two *built-in* chunks (say `fill` and `padding`) warns, because it would be invoked once per chunk with a subset of its inputs.
-
-`configure({ handlers })` must run before the first render, like every other config option.
-
----
-
-## Props Middleware
-
-`propHandlers` are middleware over a component's props — props in, props out. Where a style *handler* turns a style property into CSS declarations, a prop handler turns a **component prop** into other props, including `styles`. It is the extension point for props whose value isn't a style value.
-
-```jsx
-import { configure, mergeStyles } from '@tenphi/tasty';
-
-configure({
-  propHandlers: {
-    glaze: (props) => {
-      const { glaze, ...rest } = props;
-      if (!glaze) return rest;
-
-      return { ...rest, styles: mergeStyles(glazeStyles(glaze), rest.styles) };
-    },
-  },
-});
-
-<Element glaze="purple" />
-```
-
-The map key is the handler's name and, by default, the prop that triggers it, so an absent prop costs one property check rather than a call. A tuple overrides that: `['glaze', fn]`, `[['glaze', 'tint'], fn]`, or `['*', fn]` for unconditional.
-
-Handlers run at the very top of every component's render, before any prop is destructured, so one can rewrite `styles`, `mods`, `tokens`, `variant`, `as`, `element`, and `qa`. They run in registration order — plugins first, then direct config — each receiving the previous one's output.
-
-Handlers must be **pure** and must not mutate their input, and should memoize the styles they build per input value: style values are cached by object identity, so mutating one in place yields stale CSS, and a reference-stable object avoids re-serializing on every render.
-
-Injected styles occupy the `styles` slot, so they beat a component's own default styles and lose to a style prop at the call site. Prop handlers do not apply to sub-elements or to zero-runtime `tastyStatic()`, which has no props.
-
-See [Plugins → Props middleware](plugins.md#props-middleware) for the full contract and a worked example.
-
----
-
-## Base Style Props
-
-`baseStyleProps` exposes style properties as props on **every** `tasty()` component, on top of the built-in base styles (`display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`):
-
-```jsx
-configure({ baseStyleProps: ['radius', 'shadow'] });
-
-<Card radius="1r" shadow />
-```
-
-`configure()` may run after your components are defined — each factory resolves its prop list lazily.
-
-Each name costs one property check per render of every component, and the effect is app-global, so keep the list short and use a factory's own `styleProps` for anything narrower. Avoid names that collide with real DOM or component props (`width`, `size`, `color`), since every component will then swallow them as styles.
-
 ---
 
 ## Extending Style Types (TypeScript)

package/docs/tasty/debug.md

@@ -79,7 +79,7 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 **Extra options:**
 
 ```typescript
-interface CSSOptions extends DebugOptions {
+interface CssOptions extends DebugOptions {
   prettify?: boolean; // Format output (default: true)
   source?: boolean;   // Read original CSS instead of live CSSOM (default: false, dev-mode only)
 }
@@ -111,14 +111,14 @@ Inspects a DOM element and returns detailed information about its tasty styles,
 ```typescript
 interface InspectResult {
   element?: Element | null;
-  classes: string[];          // Tasty classes on the element
-  chunks: DebugChunkInfo[];   // Chunk assignment per class
-  css: string;                // Prettified CSS
-  size: number;               // CSS size in characters
-  rules: number;              // Number of CSS rule blocks
+  classes: string[];    // Tasty classes on the element
+  chunks: ChunkInfo[];  // Chunk assignment per class
+  css: string;          // Prettified CSS
+  size: number;         // CSS size in characters
+  rules: number;        // Number of CSS rule blocks
 }
 
-interface DebugChunkInfo {
+interface ChunkInfo {
   className: string;
   chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
 }

package/docs/tasty/design-system.md

@@ -117,11 +117,11 @@ Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
 ### Registering brand fonts
 
-Register your design system's custom fonts via `configure({ fontFaces })` so every component can reference them:
+Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
 
 ```ts
 configure({
-  fontFaces: {
+  fontFace: {
     'Brand Sans': [
       { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
       { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },