@cube-dev/ui-kit 0.137.1 → 0.138.1

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import { useEventBus } from "./useEventBus.js";
 import { useEffect, useRef } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.d.ts

@@ -4,9 +4,12 @@ declare global {
   interface Window {
     CubeUIKit: {
       version: string;
+      tastyVersion: string;
     };
   }
   /** Replaced at build time by tsdown `define` */
   const __UIKIT_VERSION__: string;
+  /** Replaced at build time by tsdown `define` */
+  const __TASTY_VERSION__: string;
 }
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,13 +1,21 @@
-/** @license MIT | @cube-dev/ui-kit v0.137.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.138.1 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.137.1";
+const VERSION = "0.138.1";
+const TASTY_VERSION = "2.6.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;
-	window.CubeUIKit = window.CubeUIKit || { version };
+	const tastyVersion = TASTY_VERSION;
+	window.CubeUIKit = window.CubeUIKit || {
+		version,
+		tastyVersion
+	};
 	if (window.CubeUIKit.version && window.CubeUIKit.version !== version) console.error("More than one version of CubeUIKit is loaded", { loadedVersions: [window.CubeUIKit.version, version] });
-	else window.CubeUIKit.version = version;
+	else {
+		window.CubeUIKit.version = version;
+		window.CubeUIKit.tastyVersion = tastyVersion;
+	}
 }
 
 //#endregion
-export { VERSION };
+export { TASTY_VERSION, VERSION };
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":[],"sources":["../src/version.ts"],"sourcesContent":["declare global {\n  interface Window {\n    CubeUIKit: {\n      version: string;\n    };\n  }\n\n  /** Replaced at build time by tsdown `define` */\n  const __UIKIT_VERSION__: string;\n}\n\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const VERSION: string = __UIKIT_VERSION__;\n\nif (typeof window !== 'undefined') {\n  const version = VERSION;\n\n  // Ensure CubeUIKit is defined on window in a way bundlers recognize\n  window.CubeUIKit = window.CubeUIKit || { version };\n\n  // Check for multiple versions\n  if (window.CubeUIKit.version && window.CubeUIKit.version !== version) {\n    console.error('More than one version of CubeUIKit is loaded', {\n      loadedVersions: [window.CubeUIKit.version, version],\n    });\n  } else {\n    // Set version if not already set\n    window.CubeUIKit.version = version;\n  }\n}\n"],"mappings":";;AAYA,MAAa;AAEb,IAAI,OAAO,WAAW,aAAa;CACjC,MAAM,UAAU;AAGhB,QAAO,YAAY,OAAO,aAAa,EAAE,SAAS;AAGlD,KAAI,OAAO,UAAU,WAAW,OAAO,UAAU,YAAY,QAC3D,SAAQ,MAAM,gDAAgD,EAC5D,gBAAgB,CAAC,OAAO,UAAU,SAAS,QAAQ,EACpD,CAAC;KAGF,QAAO,UAAU,UAAU"}
+{"version":3,"file":"version.js","names":[],"sources":["../src/version.ts"],"sourcesContent":["declare global {\n  interface Window {\n    CubeUIKit: {\n      version: string;\n      tastyVersion: string;\n    };\n  }\n\n  /** Replaced at build time by tsdown `define` */\n  const __UIKIT_VERSION__: string;\n  /** Replaced at build time by tsdown `define` */\n  const __TASTY_VERSION__: string;\n}\n\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const VERSION: string = __UIKIT_VERSION__;\n// eslint-disable-next-line no-undef -- replaced at build time by tsdown `define`\nexport const TASTY_VERSION: string = __TASTY_VERSION__;\n\nif (typeof window !== 'undefined') {\n  const version = VERSION;\n  const tastyVersion = TASTY_VERSION;\n\n  // Ensure CubeUIKit is defined on window in a way bundlers recognize\n  window.CubeUIKit = window.CubeUIKit || { version, tastyVersion };\n\n  // Check for multiple versions\n  if (window.CubeUIKit.version && window.CubeUIKit.version !== version) {\n    console.error('More than one version of CubeUIKit is loaded', {\n      loadedVersions: [window.CubeUIKit.version, version],\n    });\n  } else {\n    window.CubeUIKit.version = version;\n    window.CubeUIKit.tastyVersion = tastyVersion;\n  }\n}\n"],"mappings":";;AAeA,MAAa;AAEb,MAAa;AAEb,IAAI,OAAO,WAAW,aAAa;CACjC,MAAM,UAAU;CAChB,MAAM,eAAe;AAGrB,QAAO,YAAY,OAAO,aAAa;EAAE;EAAS;EAAc;AAGhE,KAAI,OAAO,UAAU,WAAW,OAAO,UAAU,YAAY,QAC3D,SAAQ,MAAM,gDAAgD,EAC5D,gBAAgB,CAAC,OAAO,UAAU,SAAS,QAAQ,EACpD,CAAC;MACG;AACL,SAAO,UAAU,UAAU;AAC3B,SAAO,UAAU,eAAe"}

package/docs/Usage.md

@@ -69,13 +69,14 @@ Defined in `src/tokens/sizes.ts`. Used for component heights and icon sizes.
 
 ## Shadow Tokens
 
-Defined in `src/tokens/shadows.ts`.
+Defined in `src/tokens/shadows.ts`. Shadow colors (`#shadow-sm`, `#shadow-md`, `#shadow-lg`) are generated by Glaze and adapt automatically to dark / high-contrast schemes.
 
 | Token | Value |
 |-------|-------|
-| `$item-shadow` | `0 1bw 0.375x #dark.15` |
-| `$card-shadow` | `0 0.5x 2x #shadow` |
-| `$dialog-shadow` | `0 1x 4x #dark.15` |
+| `$item-shadow` | `0 1bw 0.375x #shadow-sm` |
+| `$card-shadow` | `0 0.5x 2x #shadow-md` |
+| `$shadow` | `0 0.5x 2x #shadow-md` |
+| `$dialog-shadow` | `0 1x 4x #shadow-lg` |
 
 ## Layout Tokens
 
@@ -89,43 +90,110 @@ Defined in `src/tokens/layout.ts`.
 
 ## Color Tokens
 
-All color tokens use `#name` syntax in styles. Opacity variants use `#name.NN` (e.g. `#dark.06` for 6% opacity). Defined in `src/tokens/colors.ts`.
+All color tokens use `#name` syntax in styles. Opacity variants use `#name.NN` (e.g. `#surface-text.06` for 6% opacity).
 
-### Base Colors
+The palette is generated by [`@tenphi/glaze`](https://github.com/tenphi/glaze) (see `src/tokens/palette.ts`). Every color token is emitted as a state map with `light`, `@dark`, and `@hc` (high-contrast) variants, so the entire UI Kit adapts to dark / high-contrast schemes automatically.
 
-| Token | Description |
-|-------|-------------|
-| `#white`, `#black`, `#clear` | Absolute white, black, and transparent |
-| `#text` | Default text color |
+### Color Schemes
+
+The `@dark` and `@hc` predefined states are wired up in `src/components/Root.tsx` to support both an attribute opt-in and the user's system preference:
+
+```html
+<!-- Force dark scheme -->
+<html data-schema="dark">
+
+<!-- Force high-contrast scheme -->
+<html data-contrast="high">
+
+<!-- Both can be combined -->
+<html data-schema="dark" data-contrast="high">
+```
+
+When the attribute is absent, the scheme falls back to `@media (prefers-color-scheme: dark)` and `@media (prefers-contrast: more)`.
+
+### Surface & Text Vocabulary
+
+The neutral palette uses a `surface` / `surface-text` model. Each surface depth has its own AAA text color, plus a soft (AA) variant for secondary copy:
+
+| Token | Role |
+|-------|------|
+| `#surface` | Primary background |
+| `#surface-2` | Slightly recessed background (cards, inputs) |
+| `#surface-3` | Deepest background (panels, code blocks) |
+| `#surface-text` | AAA text on `#surface` |
+| `#surface-text-soft` | AA text on `#surface` (secondary copy, body text) |
+| `#surface-text-soft-2` | AA-large text on `#surface` (placeholders, captions) |
+| `#surface-2-text`, `#surface-2-text-soft` | Same scale, anchored to `#surface-2` |
+| `#surface-3-text`, `#surface-3-text-soft` | Same scale, anchored to `#surface-3` |
+
+### Other Neutral Tokens
+
+| Token | Role |
+|-------|------|
 | `#border` | Default border color |
 | `#placeholder` | Input placeholder text |
-| `#shadow` | Shadow color |
-| `#minor` | Secondary/muted text |
 | `#focus` | Focus ring color |
-| `#pink` | Accent pink |
-| `#light` | Light background |
-
-### Semantic Color Groups
+| `#disabled` | Disabled state fill / text |
+| `#pink` | Accent pink (independent hue) |
+| `#shadow-sm` / `#shadow-md` / `#shadow-lg` | Tinted shadow colors (used by `$*-shadow` tokens) |
+| `#overlay` | Dim backdrop (50% transparent) |
+| `#clear` | `transparent` |
 
-Each semantic group provides a base color and variants following the pattern: `#name`, `#name-text`, `#name-bg`, `#name-icon`, `#name-desaturated`, `#name-disabled`.
+### Accent System
 
-| Group | Hue | Purpose |
-|-------|-----|---------|
-| `#primary` / `#purple` | 280.3° | Primary actions, brand color |
-| `#danger` | 23.1° | Errors, destructive actions |
-| `#success` | 156.9° | Success states, confirmations |
-| `#warning` | 84.3° | Warning states, caution |
-| `#note` | 302.3° | Informational notes |
+Each themed color (default, primary, success, danger, warning, note) provides an `accent-*` family anchored to a fixed white "accent surface text". These tokens stay recognizable across schemes (used for branded buttons, CTAs, etc.):
 
-### Neutral Scales
+| Token (default theme; prefixed in others) | Role |
+|-------|------|
+| `#accent-surface` | Saturated brand fill (button bg) |
+| `#accent-surface-2`, `#accent-surface-3` | Darker / more saturated variants |
+| `#accent-surface-text` | Near-white text on accent fill |
+| `#accent-text` | Saturated colored text (used on neutral surface) |
+| `#accent-icon` | Saturated colored icon |
 
-**Dark scale:** `#dark`, `#dark-01` through `#dark-05` — neutral scale from near-black to light gray. **Surfaces:** `#surface`, `#surface-2`, `#surface-3` — layered UI backgrounds.
+In the `default` theme these tokens are unprefixed (`#accent-surface`). In colored themes they are prefixed (`#success-accent-surface`, `#danger-accent-text`, …).
 
-**Purple scale:** `#purple-01` through `#purple-04` — additional purple shades for gradients and accents.
+### Themed Surfaces
 
-### Disabled Colors
+Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`) also provides its own tinted `<theme>-surface` (banner / chip background) and `<theme>-surface-text` (banner text):
 
-`#disabled`, `#disabled-text`, `#disabled-bg` — dedicated colors for disabled UI elements.
+| Group | Hue | Purpose |
+|-------|-----|---------|
+| `#primary-*` / `#purple-*` | 280.3° | Primary actions, brand color |
+| `#success-*` | 156.9° | Success states, confirmations |
+| `#danger-*` | 23.1° | Errors, destructive actions |
+| `#warning-*` | 84.3° | Warning states, caution |
+| `#note-*` | 302.3° | Informational notes |
+
+For example, a success banner uses `fill: '#success-surface'` + `color: '#success-surface-text'`, while a primary button uses `fill: '#primary-accent-surface'` + `color: '#primary-accent-surface-text'`.
+
+### Legacy Aliases
+
+The previous token names continue to work as aliases (defined at the bottom of `src/tokens/colors.ts`). New code should prefer the Glaze tokens, but existing components do not need to be migrated:
+
+| Legacy | Resolves to |
+|-------|------------|
+| `#text` | `#surface-text-soft` |
+| `#dark` / `#dark-01` | `#surface-text` |
+| `#dark-02` | `#surface-text-soft` |
+| `#dark-03` | `#surface-text-soft-2` |
+| `#dark-04` | `#placeholder` |
+| `#dark-05` | `#border` |
+| `#minor` | `#surface-text-soft.65` |
+| `#shadow` | `#shadow-md` |
+| `#light` | `#surface-3` |
+| `#dark-bg` | `#surface-2` |
+| `#primary` / `#purple` | `#primary-accent-surface` |
+| `#primary-text` / `#purple-text` | `#primary-accent-text` |
+| `#primary-bg` / `#purple-bg` | `#primary-surface` |
+| `#primary-icon` / `#purple-icon` | `#primary-accent-icon` |
+| `#<status>` | `#<status>-accent-surface` |
+| `#<status>-text` | `#<status>-accent-text` |
+| `#<status>-bg` | `#<status>-surface` |
+| `#<status>-icon` | `#<status>-accent-icon` |
+| `#<status>-disabled` | `#disabled` |
+
+`#white`, `#black`, and `#clear` are not defined in the palette — `#white` and `#black` are tasty's built-in named colors, and `#clear` is an alias for `transparent`.
 
 ## Typography Presets
 
@@ -242,7 +310,7 @@ In style value maps, keys define when styles apply. States can be combined with
 fill: {
   '': '#surface',              // default
   ':hover': '#surface-hover',  // pseudo-class
-  disabled: '#disabled-bg',    // data-attribute modifier
+  disabled: '#disabled-surface', // data-attribute modifier
   'type=danger': '#danger',    // data-attribute with value
   '@media(w < 768px)': '...',  // media query
   '@(panel, w >= 300px)': '...', // container query

package/docs/components/content/Card.md

@@ -17,7 +17,7 @@ No component-specific props. Use style props directly.
 - `display` — `block`
 - `flow` — `column`
 - `radius` — `(1cr + 1bw)`
-- `fill` — `#white`
+- `fill` — `#surface`
 - `border` — `#border`
 - `padding` — `1.5x`
 - `preset` — `t3`

package/docs/components/content/PrismCode.md

@@ -24,6 +24,27 @@ Syntax-highlighted code block using Prism. Supports multiple languages.
 
 Supports [Base properties](../../BaseProperties.md).
 
+## Theme
+
+Syntax colors are driven by a dedicated, scheme-aware palette of `code-*`
+tokens. Each token uses a different hue so token classes stay visually
+separable, and every token meets at least **WCAG AA (4.5:1)** contrast
+against `#surface` in light, dark, and high-contrast schemes (AAA in HC).
+
+| Token                | Hue            | Used for                                                       |
+| -------------------- | -------------- | -------------------------------------------------------------- |
+| `#code-comment`      | gray           | comments, prolog, doctype, cdata                               |
+| `#code-punctuation`  | muted pink     | operators, punctuation                                         |
+| `#code-keyword`      | pink           | keywords, booleans, constants, atrules (`font-weight: 500`)    |
+| `#code-string`       | primary purple | strings, characters, attribute values, URLs                    |
+| `#code-number`       | green          | numbers, numeric entities                                      |
+| `#code-function`     | pink           | functions, class names, regex, variables                       |
+| `#code-attribute`    | cyan           | tags, attribute names, properties, selectors, built-ins, keys  |
+
+Diff insertion (`+`) and deletion (`-`) intentionally re-use the existing
+`#success-*` / `#danger-*` ramps — both the line background tint and the
+foreground color adapt to the active scheme.
+
 ## Examples
 
 ```jsx

package/docs/components/form/Field.md

@@ -197,7 +197,7 @@ const InputElement = tasty({
     padding: '1x 1.5x',
     border: true,
     radius: '1r',
-    fill: '#white',
+    fill: '#surface',
     color: '#dark-02',
     transition: 'theme',
 

package/docs/components/layout/ResizablePanel.md

@@ -50,7 +50,7 @@ These properties allow direct style application without using the `styles` prop:
 ### Resizable sidebar
 
 ```jsx
-<Panel isFlex isStretched height="min 30x" fill="#white">
+<Panel isFlex isStretched height="min 30x" fill="#surface">
   <ResizablePanel direction="right">
     <Block padding="1x">Sidebar content</Block>
   </ResizablePanel>

package/docs/components/organisms/FileTabs.md

@@ -21,7 +21,7 @@ A tab bar for file-like items with close buttons and dirty state indicators. Des
 
 - Tab `radius` — `1r 1r 0 0`
 - Tab `padding` — `1x 1.5x`
-- Tab `fill` — `#dark.04` (active tabs use `#white`)
+- Tab `fill` — `#dark.04` (active tabs use `#surface`)
 - Tab gap — `.5x`
 
 ### Base Properties

package/docs/components/organisms/StatsCard.md

@@ -22,7 +22,7 @@ Extends Card with:
 - `placeContent` — `space-between`
 - `gap` — `1x`
 - `border` — none
-- `shadow` — `0 2px 6px #dark.10`
+- `shadow` — `$shadow` (design-system elevation token, scheme-aware via `#shadow-md`)
 - `padding` — `2.5x`
 
 ### Base Properties

package/docs/tasty/configuration.md

@@ -61,6 +61,7 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 | `presets` | `Record<string, TypographyPreset>` | - | Typography presets — shorthand for `generateTypographyTokens()` |
 | `globalStyles` | `Record<string, Styles>` | - | Global Tasty styles keyed by CSS selector |
 | `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
+| `namePrefix` | `string` | `'t'` (runtime) / `'ts'` (zero-runtime) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). See [Name prefix](#name-prefix). |
 
 ---
 
@@ -84,6 +85,49 @@ The `oklch` color space is the default because it provides perceptually uniform
 
 ---
 
+## Name Prefix
+
+Every identifier Tasty generates — class names, keyframe names, counter-style names — starts with a configurable prefix. The runtime, SSR, and RSC paths default to `'t'`; the zero-runtime build path (`tastyStatic` via the Babel plugin) defaults to `'ts'` so static-extracted classes can never collide with runtime classes when both are loaded on the same page.
+
+```jsx
+configure({
+  namePrefix: 'mb',
+});
+```
+
+The prefix is prepended verbatim to the hash, so include any separator inside the prefix string itself:
+
+| Setting | Class | Keyframe | Counter-style |
+|---|---|---|---|
+| `'t'` (runtime default) | `t1a2b3` | `tk1a2b3` | `tc1a2b3` |
+| `'ts'` (zero-runtime default) | `ts1a2b3` | `tsk1a2b3` | `tsc1a2b3` |
+| `'mb'` | `mb1a2b3` | `mbk1a2b3` | `mbc1a2b3` |
+| `'myapp-'` | `myapp-1a2b3` | `myapp-k1a2b3` | `myapp-c1a2b3` |
+
+The single-letter discriminators (`k` for keyframes, `c` for counter-styles) keep the three kinds visually distinct in devtools — they are not required for correctness because CSS keeps these in separate namespaces.
+
+### Rules
+
+- Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. Examples that pass: `'t'`, `'ts'`, `'app'`, `'myapp-'`, `'_foo'`. Examples that fail: `''`, `'1foo'`, `'my app'`.
+- Validated at `configure()` time; an invalid prefix throws synchronously rather than silently producing broken hydration.
+- Locked once styles have been generated, like all other config.
+
+### Coexistence with the zero-runtime build
+
+The runtime and zero-runtime builds **must use different prefixes** when both are loaded on the same page. Defaults already guarantee this; if you customize one, customize the other accordingly:
+
+```jsx
+// app config (runtime / SSR / RSC)
+configure({ namePrefix: 'mb' });
+
+// tasty-zero.config.ts (Babel plugin)
+export default { namePrefix: 'mbs' };
+```
+
+If you only use one of the two builds, you only need to set `namePrefix` on that path.
+
+---
+
 ## Design Tokens
 
 Design tokens define CSS custom properties on `:root`. They are injected automatically when the first style is rendered. Values are parsed through the Tasty DSL, so you can use units, color syntax, and other DSL features.

package/docs/tasty/dsl.md

@@ -52,22 +52,23 @@ styles: { Title: { preset: 'h3' } }
 
 #### Selector Affix (`$`)
 
-Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
+Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles.
+
+Examples below assume the sub-element key is **Cell** (i.e. `[data-element="Cell"]` in CSS):
 
 | Pattern | Result | Description |
 |---------|--------|-------------|
-| *(none)* | ` [el]` | Descendant (default) |
-| `>` | `> [el]` | Direct child |
-| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
-| `> SubElementName` | `> [SubElementName]` | Self-name shorthand — when the trailing element name matches the sub-element's own key, it acts as the placeholder (same as `@`); no duplication |
-| `h1` | ` h1` | Tag selector (no key injection) |
-| `h1 >` | ` h1 > [el]` | Key is direct child of tag |
-| `h1 *` | ` h1 *` | Any descendant of tag |
-| `*` | ` *` | All descendants |
-| `::before` | `::before` | Root pseudo (no key) |
-| `@::before` | `[el]::before` | Pseudo on the sub-element |
-| `>@:hover` | `> [el]:hover` | Pseudo-class on the sub-element |
-| `>@.active` | `> [el].active` | Class on the sub-element |
+| *(none)* | `[data-element="Cell"]` | Descendant (default) |
+| `>` | `> [data-element="Cell"]` | Direct child |
+| `>Body>` | `> [data-element="Body"] > [data-element="Cell"]` | Chained elements |
+| `> Cell` | `> [data-element="Cell"]` | Self-name shorthand — when the trailing element name matches the sub-element's own key, it acts as the placeholder (same as `@`); no duplication |
+| `h1` | `h1` | Tag selector (no key injection) |
+| `h1 >` | `h1 > [data-element="Cell"]` | Key is direct child of tag |
+| `h1 *` | `h1 *` | Any descendant of tag |
+| `*` | `*` | All descendants |
+| `&::before` | `::before` | Root pseudo (no key); `&` is required |
+| `@::before` | `[data-element="Cell"]::before` | Pseudo on the sub-element |
+| `>@.active` | `> [data-element="Cell"].active` | Class on the sub-element |
 
 Rules for key injection (`[data-element="..."]`):
 

package/docs/tasty/methodology.md

@@ -399,6 +399,32 @@ tasty(Button, {
 
 For full details on merge semantics, `@inherit`, `null`, and `false` tombstones, see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps).
 
+### Styling non-Tasty components or string tags
+
+`tasty(Component, { ... })` always forwards every prop to `Component`, which means `Component` must be Tasty-aware (i.e. it knows how to consume `styles`, `mods`, `qa`, etc.). To apply styles to a third-party component (Next.js `Link`, `react-router`'s `Link`, Radix primitives, MUI, etc.) or to a plain DOM tag, use the options-only form with `as`:
+
+```tsx
+import NextLink from 'next/link';
+
+const Link = tasty({
+  as: NextLink,
+  styles: {
+    color: { '': '#accent-text', ':hover': '#text' },
+    textDecoration: 'underline',
+  },
+  styleProps: ['padding'],
+});
+
+const Span = tasty({
+  as: 'span',
+  styles: { fontWeight: 'bold' },
+});
+
+<Link href="/blog" padding="1x">Blog</Link>;
+```
+
+The wrapped component only needs to forward `className` (and ideally `style` and `ref`) to its underlying DOM node. Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `isDisabled`, `isHidden`, `isChecked`, and any `styleProps`/`modProps`/`tokenProps` you declared) are consumed by the wrapper and converted to `data-*` attributes or CSS custom properties — they never leak to the DOM.
+
 ### When to use styleProps vs wrapping
 
 If the component exposes the properties you need as `styleProps`, use them directly — that is what they are for:

package/docs/tasty/react-api.md

@@ -42,6 +42,30 @@ const PrimaryButton = tasty(Button, {
 
 Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
 
+`tasty(Component, ...)` always wraps `Component` and forwards every prop to it, so `Component` must be Tasty-aware (i.e. it accepts `styles`, `mods`, `qa`, etc. and renders them through its own Tasty pipeline). To apply styles to a third-party component or a string DOM tag via `className`, use the options-only form with `as`:
+
+```jsx
+import NextLink from 'next/link';
+
+const Link = tasty({
+  as: NextLink,
+  styles: {
+    color: { '': '#accent-text', ':hover': '#text' },
+    textDecoration: 'underline',
+  },
+  styleProps: ['padding'],
+});
+
+const Span = tasty({
+  as: 'span',
+  styles: { fontWeight: 'bold' },
+});
+
+<Link href="/blog" padding="1x">Blog</Link>;
+```
+
+The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `styleProps`, `modProps`, `tokenProps`) are consumed by Tasty and never leak to the DOM.
+
 ---
 
 ## Style Props

package/docs/tasty/ssr.md

@@ -358,16 +358,18 @@ const stream = await runWithCollector(collector, () =>
 
 Server-safe style collector. One instance per request.
 
+Constructor: `new ServerStyleCollector(namePrefix?)`. The optional `namePrefix` overrides the value from `configure({ namePrefix })`; in normal usage you pass nothing and let the global config drive it. See [Configuration: Name prefix](configuration.md#name-prefix).
+
 | Method | Description |
 |---|---|
-| `allocateClassName(cacheKey)` | Allocate a sequential class name (`t0`, `t1`, ...) for a cache key. Returns `{ className, isNewAllocation }`. |
+| `allocateClassName(cacheKey)` | Allocate a deterministic, content-hashed class name for a cache key (e.g. `t1a2b3` with the default prefix). The same `cacheKey` always produces the same class name on server and client when both share the same `namePrefix`. Returns `{ className, isNewAllocation }`. |
 | `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`. |
 | `collectKeyframes(name, css)` | Record a `@keyframes` rule. Deduplicated by name. |
-| `allocateKeyframeName(providedName?)` | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one (`k0`, `k1`, ...). |
+| `allocateKeyframeName(providedName?)` | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one using `${namePrefix}k${counter}` (e.g. `tk0`, `tk1`, ...). |
 | `collectProperty(name, css)` | Record a `@property` rule. Deduplicated by name. |
 | `collectFontFace(key, css)` | Record a `@font-face` rule. Deduplicated by content hash. |
 | `collectCounterStyle(name, css)` | Record a `@counter-style` rule. Deduplicated by name. |
-| `allocateCounterStyleName(providedName?)` | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one (`cs0`, `cs1`, ...). |
+| `allocateCounterStyleName(providedName?)` | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one using `${namePrefix}c${counter}` (e.g. `tc0`, `tc1`, ...). |
 | `collectGlobalStyles(key, css)` | Record global styles (from `useGlobalStyles`). Deduplicated by key. |
 | `collectRawCSS(key, css)` | Record raw CSS text (from `useRawCSS`). Deduplicated by key. |
 | `collectInternals()` | Collect internal `@property` rules, `:root` token defaults, `@font-face`, and `@counter-style` rules from the global config. Called automatically on first chunk collection; idempotent. |

package/docs/tasty/styles.md

@@ -378,11 +378,11 @@ Multiple shadows: `shadow="1x 1x 2x #dark.20, inset 0 0 4x #dark.10"`
 
 Typography preset that sets font-size, line-height, letter-spacing, font-weight, font-style, and text-transform from named design tokens.
 
-**Syntax:** `name`, `name / modifier`, or `modifier` (shorthand)
+**Syntax:** `name`, `name / modifier...`, or `modifier...` (shorthand)
 
 Preset names are project-specific (e.g. `h1`–`h6`, `t1`–`t4`, `p1`–`p4`). Register them for autocomplete by augmenting `TastyPresetNames`.
 
-Use `/` to separate the preset name from a modifier. When a modifier is used alone (without a name), the preset name defaults to `inherit`.
+Use `/` to separate the preset name from one or more space-separated modifiers. When modifiers are used alone (without a name), the preset name defaults to `inherit`. Modifiers can be combined freely because they target different properties.
 
 **Modifiers:**
 
@@ -394,11 +394,13 @@ Use `/` to separate the preset name from a modifier. When a modifier is used alo
 | `tight` | Sets line-height equal to font-size |
 
 ```jsx
-preset="h1"              // heading 1
-preset="h2 / strong"     // bold heading 2
-preset="t3 / italic"     // italic text 3
-preset="t2 / tight"      // text 2 with tight line-height
-preset="bold"             // inherit preset with bold (shorthand for "inherit / bold")
+preset="h1"                    // heading 1
+preset="h2 / strong"           // bold heading 2
+preset="h2 / strong italic"    // bold + italic heading 2
+preset="t3 / italic"           // italic text 3
+preset="t2 / strong tight"     // bold text 2 with tight line-height
+preset="bold"                  // inherit preset with bold (shorthand)
+preset="bold italic"           // inherit preset with bold + italic (shorthand)
 ```
 
 Individual typography props (`fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform`) can be used alongside `preset` to override specific values, but using `preset` alone is recommended.

package/docs/tasty/tasty-static.md

@@ -178,6 +178,21 @@ module.exports = {
 | `config.globalStyles` | `Record<string, Styles>` | — | Global Tasty styles keyed by CSS selector. Supports the full style syntax. |
 | `config.autoPropertyTypes` | `boolean` | `true` | Automatically infer and register CSS `@property` declarations from values |
 | `config.parserCacheSize` | `number` | `1000` | Parser LRU cache size. Larger values improve performance for builds with many unique style values |
+| `config.namePrefix` | `string` | `'ts'` | Prefix prepended to every generated identifier. Defaults to `'ts'` so static classes never collide with runtime (`'t'`) classes. See [Configuration: Name prefix](configuration.md#name-prefix). |
+
+### Coexisting with runtime tasty
+
+When a page mixes `tastyStatic` with runtime `tasty`, both must use **different** `namePrefix` values. The defaults handle this automatically (`'t'` for runtime, `'ts'` for zero-runtime). If you customize one, customize the other:
+
+```ts
+// tasty-zero.config.ts (Babel plugin)
+export default { namePrefix: 'mbs' };
+```
+
+```ts
+// app entry (runtime configure)
+configure({ namePrefix: 'mb' });
+```
 
 ---