@cube-dev/ui-kit 0.199.2 → 0.200.0

package/dist/tokens/shadows.js.map

@@ -1 +1 @@
-{"version":3,"file":"shadows.js","names":["Styles","SHADOW_TOKENS","$shadow"],"sources":["../../src/tokens/shadows.ts"],"sourcesContent":["import type { Styles } from '@tenphi/tasty';\n\n/**\n * Shadow tokens using tasty shorthand syntax.\n *\n * Format: `<offset-y> <blur> <spread?> <color>`\n * - `1bw` = 1 × border-width\n * - `.5x` = 0.5 × gap\n *\n * The shadow colors (`#shadow-sm` / `#shadow-md` / `#shadow-lg`) are\n * generated by Glaze and adapt automatically to dark / high-contrast\n * schemes — see `src/tokens/palette.ts`.\n *\n * Keys use $ prefix for CSS custom properties.\n */\nexport const SHADOW_TOKENS: Styles = {\n  /** Subtle shadow for list items */\n  '$item-shadow': '0 1bw .375x #shadow-sm',\n  /** Standard card shadow */\n  '$card-shadow': '0 .5x 2x #shadow-md',\n  /** Standard elevation */\n  $shadow: '0 .5x 2x #shadow-md',\n  /** Elevated dialog shadow */\n  '$dialog-shadow': '0 1x 4x #shadow-lg',\n};\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAaC,gBAAwB;;CAEnC,gBAAgB;;CAEhB,gBAAgB;;CAEhBC,SAAS;;CAET,kBAAkB;AACpB"}
+{"version":3,"file":"shadows.js","names":["Styles","SHADOW_TOKENS","$shadow"],"sources":["../../src/tokens/shadows.ts"],"sourcesContent":["import type { Styles } from '@tenphi/tasty';\n\n/**\n * Shadow tokens using tasty shorthand syntax.\n *\n * Format: `<offset-y> <blur> <spread?> <color>`\n * - `.5x` = 0.5 × gap\n *\n * The shadow colors (`#shadow-sm` / `#shadow-md` / `#shadow-lg`) are\n * generated by Glaze and adapt automatically to dark / high-contrast\n * schemes — see `src/tokens/palette.ts`.\n *\n * Keys use $ prefix for CSS custom properties.\n */\nexport const SHADOW_TOKENS: Styles = {\n  /** Subtle shadow for list items */\n  '$item-shadow': '0 1px .375x #shadow-sm',\n  /** Standard card shadow */\n  '$card-shadow': '0 .5x 2x #shadow-md',\n  /** Standard elevation */\n  $shadow: '0 .5x 2x #shadow-md',\n  /** Elevated dialog shadow */\n  '$dialog-shadow': '0 1x 4x #shadow-lg',\n};\n"],"mappings":";;;;;;;;;;;;;;AAcA,MAAaC,gBAAwB;;CAEnC,gBAAgB;;CAEhB,gBAAgB;;CAEhBC,SAAS;;CAET,kBAAkB;AACpB"}

package/dist/tokens/sizes.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/tokens/sizes.ts
 /**
 * Component size values in pixels.

package/dist/tokens/spacing.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/tokens/spacing.ts
 /**
 * Spacing tokens using tasty multiplier syntax.

package/dist/tokens/typography.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/tokens/typography.ts
 /**
 * Typography presets for headings, text, and special styles.

package/dist/utils/ResizeSensor.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/ResizeSensor.ts
 /**
 * Iterate over each of the provided element(s).

package/dist/utils/colors.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { hslToSrgb, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, parseHexAlpha } from "@tenphi/glaze";
 //#region src/utils/colors.ts
 /**

package/dist/utils/dotize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/dotize.ts
 /**
 * Flattens a nested object into dot paths: `{ a: { b: 1 } }` becomes

package/dist/utils/is-dev-env.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/is-dev-env.ts
 /**
 * `NODE_ENV` as the environment that is actually running reports it, or

package/dist/utils/modules.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/modules.ts
 function extractModule(promise) {
 	return promise.then((module) => module.default || module);

package/dist/utils/promise.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/promise.ts
 function timeout(ms = 30) {
 	return new Promise((resolve) => {

package/dist/utils/raf.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/raf.ts
 /**
 * Chains N requestAnimationFrame calls and returns a cancel function.

package/dist/utils/random.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/random.ts
 function random(min, max) {
 	const realMin = min < max ? min : max;

package/dist/utils/range.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/range.ts
 function range(count) {
 	return Array.from({ length: count }, (_, i) => i);

package/dist/utils/react/RenderCache.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useRef } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/utils/react/RenderCache.tsx

package/dist/utils/react/Slots.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { mergeProps } from "./mergeProps.js";
 import { c } from "react/compiler-runtime";
 import { Children, cloneElement, createContext, useContext } from "react";

package/dist/utils/react/chain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/chain.ts
 /**
 * Calls all functions in the order they were chained with the same arguments.

package/dist/utils/react/disabledProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/disabledProps.ts
 /**
 * Tags where `disabled` is a real HTML attribute. Browsers refuse to dispatch

package/dist/utils/react/forwardRefWithGenerics.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/forwardRefWithGenerics.tsx
 /**
 * @deprecated Declare a ref prop on a generic component, or preserve an

package/dist/utils/react/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { useLayoutEffect } from "./useLayoutEffect.js";
 import { mergeProps } from "./mergeProps.js";

package/dist/utils/react/interactions.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { c } from "react/compiler-runtime";
 import { useRef, useState } from "react";

package/dist/utils/react/isTextOnly.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { Children, isValidElement } from "react";
 //#region src/utils/react/isTextOnly.ts
 function isTextOnly(children) {

package/dist/utils/react/mapProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/mapProps.ts
 /** Converts AriaButtonProps to CubeButtonProps */
 function ariaToCubeButtonProps(props) {

package/dist/utils/react/mergeProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { mergeIds } from "./useId.js";
 import { mergeStyles } from "@tenphi/tasty";

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/nullableValue.ts
 function castNullableStringValue(props, emptyValue = "") {
 	return castNullableField(props, ["value", "defaultValue"], "string", (v) => String(v), emptyValue);

package/dist/utils/react/overlayKeyPropagation.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/overlayKeyPropagation.ts
 /**
 * Keys whose final handling belongs to the overlay around a control, not to

package/dist/utils/react/programmaticFocus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/programmaticFocus.ts
 /**
 * Telling focus the user moved from focus a component moved for them.

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/utils/react/resolveIcon.ts
 /**
 * Resolves a dynamic icon prop to its content and slot state.

package/dist/utils/react/sharedStore.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { isDevEnv } from "../is-dev-env.js";
 import { c } from "react/compiler-runtime";

package/dist/utils/react/useBufferedValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useCallback, useRef, useState } from "react";
 //#region src/utils/react/useBufferedValue.ts

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useRef } from "react";
 //#region src/utils/react/useCombinedRefs.ts

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { c } from "react/compiler-runtime";
 import { useEffect } from "react";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 //#region src/utils/react/useEventBus.ts

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import "react/compiler-runtime";
 import { useEffect, useRef, useState } from "react";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { c } from "react/compiler-runtime";
 //#region src/utils/react/useKeySymbols.ts

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import * as React$1 from "react";
 //#region src/utils/react/useLayoutEffect.tsx
 const useLayoutEffect$1 = typeof window !== "undefined" ? React$1.useLayoutEffect : React$1.useEffect;

package/dist/utils/react/useLocalStorage.js

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

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 //#region src/utils/react/useMergeStyles.ts

package/dist/utils/react/useOverlayEscapeGuard.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react/compiler-runtime";
 import { getEventTarget, nodeContains } from "@react-aria/utils";

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { c } from "react/compiler-runtime";
 import { useContext, useEffect, useEffectEvent, useRef } from "react";

package/dist/utils/react/useQaProps.js

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

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 //#region src/utils/react/useScheme.ts
 /**

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 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.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { Fragment, isValidElement } from "react";
 //#region src/utils/react/wrapNodeIfPlain.ts
 function wrapNodeIfPlain(children, render) {

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | 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.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { isSelector, mergeStyles } from "@tenphi/tasty";
 //#region src/utils/styles.ts
 function isRecord(value) {

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | 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.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {

package/dist/version.js

@@ -1,7 +1,7 @@
-/** @license MIT | @cube-dev/ui-kit v0.199.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.200.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.199.2";
-const TASTY_VERSION = "3.13.0";
+const VERSION = "0.200.0";
+const TASTY_VERSION = "3.14.0";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	const tastyVersion = TASTY_VERSION;

package/docs/BaseProperties.md

@@ -10,6 +10,8 @@ All UI Kit components support a common set of base properties from the `tasty` s
 - **`styles`** `Styles` — Tasty styles object
 - **`css`** `string` — Raw CSS string
 - **`mods`** `Mods` — State modifiers for conditional styling
+- **`tokens`** `Tokens` — Custom-property values, applied as inline custom properties on the element
+- **`theme`** `string` — Renders `data-theme`. Components with their own `theme` prop, such as `Button`, `Alert` and `ItemAction`, give it their own meaning
 - **`breakpoints`** — Responsive breakpoint configuration
 - **`hidden`** `boolean` — Hide the element
 - **`isHidden`** `boolean` — Hide the element

package/docs/ComplexLayout.md

@@ -49,7 +49,7 @@ Use `Layout.Panel` for side navigation. Panels are absolutely positioned and aut
 <Layout height="400px">              {/* block, Inner: flex column ↓ */}
   <Layout.Panel side="left" size={200} isOpen={isOpen}> {/* absolute left, pushes content via insets */}
     <Layout.PanelHeader isClosable title="Menu" onClose={() => setIsOpen(false)} />
-    <Layout.Content padding=".5x" gap="1bw"> {/* flex column ↓, scrollable */}
+    <Layout.Content padding=".5x" gap="$item-gap"> {/* flex column ↓, scrollable */}
       <ItemButton type="clear">Dashboard</ItemButton>
       <ItemButton type="clear">Settings</ItemButton>
     </Layout.Content>

package/docs/Usage.md

@@ -46,7 +46,10 @@ These CSS custom properties are defined in `src/tokens/base.ts` and applied glob
 | `$gap` | `8px` | Base spacing unit (used with `x` multiplier) |
 | `$radius` | `6px` | Base border radius (used with `r` multiplier) |
 | `$border-width` | `1px` | Base border width (used with `bw` multiplier) |
-| `$outline-width` | `3px` | Focus outline width (used with `ow` multiplier) |
+| `$outline-width` | `3px` | Width of a field's thick focus ring (used with `ow` multiplier) |
+| `$outline-offset` | `1px` | Gap between a focus outline and its element |
+| `$ring-width` | `1px` | Width of a hairline focus or selection ring |
+| `$item-gap` | `1px` | Hairline gap between adjacent items in a list, menu or action group |
 | `$stroke-width` | `1.5` | Icon stroke width |
 | `$disabled-opacity` | `0.4` | Opacity for disabled elements |
 | `$transition` | `80ms` | Default transition duration |
@@ -90,7 +93,7 @@ Defined in `src/tokens/shadows.ts`. Shadow colors (`#shadow-sm`, `#shadow-md`, `
 
 | Token            | Value                     |
 | ---------------- | ------------------------- |
-| `$item-shadow`   | `0 1bw 0.375x #shadow-sm` |
+| `$item-shadow`   | `0 1px 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`      |
@@ -402,6 +405,46 @@ Component themes are set via the `theme` prop or `theme=name` modifier:
 | `note` | Informational / note states |
 | `current` | No palette of its own — every color is mixed from the inherited text color (`#current`), so the component adopts whatever its container paints with. Supported by `Button`, `Item` (and `ItemButton`, `Item.Action`, `ItemBadge`) |
 
+## Customizing components
+
+Most components are a design contract: customize them through their own props (`type`, `theme`, `size`, …), `tokens` and `mods` rather than by restyling them. The layout and typography primitives (`Element`, `Block`, `Flex`, `Flow`, `Grid`, `Space`, `Prefix`, `Suffix`, `Text`, `TextItem`, `Title`, `Paragraph`, `Typography`, `ButtonGroup` and `Button.Group`), the `Action` base and the icons (including `IconSwitch`) are the exception: their `styles` are their API.
+
+The package's `tasty.config.ts` lists the other components as `protectedComponents`, and `tasty/no-protected-restyle` from `@tenphi/eslint-plugin-tasty` 1.12.0 or newer reports a restyle of one in your code:
+
+- instance `styles`, and every `*Styles` prop such as `inputStyles`;
+- style props other than the ones that place or size the component (`width`, `height`, `gridArea`, `margin`, `inset`, …). Containers (`Card`, `Panel`, `ResizablePanel`, `Content`, `Header`, `Footer`, and `Layout` and `GridLayout` with their sub-components) also keep the ones that lay out their content: `padding`, `gap`, `flow`, `place*`, `align*`, `justify*`, `grid*`, `overflow` and `scrollbar`. Root `styles` that sets only allowed props passes too;
+- `tasty()` wrappers that restyle a protected component, and wrappers of those wrappers.
+
+A component's own prop that shares a name with a style passes, such as a field's `direction` and `filter`, a text field's `resize`, `ColorSwatch`'s `color` or `AlertDialog`'s `content`.
+
+A sub-component counts as the component it hangs off, so `Button.Split` is protected like `Button`, and `Layout.Content` is a container like `Layout`. The list names the exceptions, such as `Button.Group`.
+
+To turn it on, extend the package's config and enable the rule:
+
+```ts
+// tasty.config.ts
+export default { extends: '@cube-dev/ui-kit' };
+```
+
+```jsonc
+// .oxlintrc.json
+{
+  "jsPlugins": [{ "name": "tasty", "specifier": "@tenphi/eslint-plugin-tasty" }],
+  "rules": { "tasty/no-protected-restyle": "warn" },
+}
+```
+
+An intended override takes a disable comment with its reason on the line before it. Among JSX children, only the `{/* … */}` form works:
+
+```tsx
+<Space>
+  {/* oxlint-disable-next-line tasty/no-protected-restyle -- the empty state's call to action takes the brand fill */}
+  <Button fill="#purple">Get started</Button>
+</Space>
+```
+
+With this rule on, `tasty/no-styles-prop` can stay off, so the primitives keep their `styles`.
+
 ## Recipes
 
 Reusable style presets applied via the `recipe` style property. Defined in `src/components/Root.tsx`.

package/docs/Utilities.md

@@ -146,13 +146,16 @@ function filterBaseProps(
 | Category | Examples |
 | --- | --- |
 | DOM ids | `id` |
-| Base props | `role`, `as`, `children`, `style`, `className`, `href`, `target`, `tabIndex`, `hidden`, `disabled` |
+| Base props | `role`, `title`, `as`, `children`, `style`, `className`, `href`, `target`, `tabIndex`, `hidden`, `disabled` |
+| Tasty props | `qa`, `qaVal`, `mods`, `tokens`, `theme` (rendered as `data-theme`), `isHidden`, `isDisabled`, `isChecked` |
 | ARIA attributes | `aria-label`, `aria-describedby`, etc. |
 | Data attributes | `data-qa`, `data-testid`, etc. |
 | Event handlers (opt-in) | `onClick`, `onFocus`, `onKeyDown`, etc. (when `eventProps: true`) |
 | Custom (opt-in) | Any prop name added to `opts.propNames` |
 
-Style props (`width`, `fill`, `padding`, `border`, etc.), tasty-specific props (`mods`, `qa`, `styles`), and React Aria interaction props (`onPress`, `onHoverStart`, `onHoverEnd`, `onPressStart`, `onPressEnd`) are filtered out.
+Style props (`width`, `fill`, `padding`, `border`, etc.), `styles`, and React Aria interaction props (`onPress`, `onHoverStart`, `onHoverEnd`, `onPressStart`, `onPressEnd`) are filtered out.
+
+An explicit prop written after the spread wins, so set a wrapper's own `tokens` or `theme` after `{...filterBaseProps(props)}`, or merge the `tokens` objects. A component whose own `theme` prop means something else (such as `Alert`'s status theme) takes it out before filtering.
 
 ### Usage
 

package/docs/components/GridProvider.md

@@ -11,9 +11,9 @@ Provides CSS custom properties for responsive grid column calculations. Children
 ## Properties
 
 - **`columns`** `number` (default: `2`) — Number of grid columns
-- **`gap`** `Styles['gap']` (default: `'0'`) — Gap between columns
-- **`width`** `Styles['width']` — Forced container width (bypasses auto-detection)
-- **`initialWidth`** `Styles['width']` — Initial width before resize observer kicks in
+- **`gap`** `string | number` (default: `0`) — Gap between columns, as a single Tasty value such as `'1x'`, or a number of pixels. A string needs a unit: `'0'` makes `--column-width` invalid
+- **`width`** `string | number` — Forced container width (bypasses auto-detection), as a single Tasty value or a number of pixels
+- **`initialWidth`** `string | number` — Initial width before resize observer kicks in, as a single Tasty value or a number of pixels
 
 ### CSS Custom Properties Provided
 

package/docs/components/content/Layout.md

@@ -818,7 +818,7 @@ function ApplicationShell() {
           title="Navigation"
           onClose={() => setSidebarOpen(false)}
         />
-        <Layout.Content padding=".5x" scrollbar="tiny" gap="1bw">
+        <Layout.Content padding=".5x" scrollbar="tiny" gap="$item-gap">
           {['Dashboard', 'Analytics', 'Reports'].map((item) => (
             <ItemButton key={item} type="clear" width="100%">
               {item}

package/docs/components/fields/ComboBox.md

@@ -35,7 +35,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or false to disable filtering. If not provided, uses default contains filter
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the trigger button
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size, which the options in the list share
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`necessityIndicator`** `'label' | 'icon'` — How the required state should be indicated
 - **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes
 - **`onInputChange`** `(value: string) => void` — Callback fired when the input text changes

package/docs/components/fields/CommandTextArea.md

@@ -61,7 +61,7 @@ Supports all [Field properties](../../FieldProperties.md) (`label`, `name`, `isR
 - **`optionStyles`** — Styles for individual options.
 - **`sectionStyles`** — Styles for section containers.
 - **`headingStyles`** — Styles for section headings.
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 
 ### Style Properties
 

package/docs/components/fields/FilterListBox.md

@@ -26,7 +26,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — FilterListBox size
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`searchPlaceholder`** `string` (default: `Search...`) — Placeholder text in the search input
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or `false` to disable filtering
 - **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state

package/docs/components/fields/FilterPicker.md

@@ -41,7 +41,7 @@ Choose a different component when the interaction has another shape:
 - **`type`** `'outline' | 'outline-2' | 'clear' | 'primary'` (default: `outline`) — Button styling type
 - **`theme`** `'default' | 'special'` (default: `default`) — Button theme
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`searchPlaceholder`** `string` — Placeholder text in the search input
 - **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for determining if an option should be included in search results

package/docs/components/fields/ListBox.md

@@ -29,7 +29,7 @@ A versatile list selection component that allows users to select one or more ite
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ListBox size
 - **`shape`** `'card' | 'plain' | 'popover'` (default: `card`) — Visual shape of the ListBox
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`filter`** `(nodes: Iterable<Node>) => Iterable<Node>` — Filter function for the list items
 - **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available. The empty listbox stays in the document, described by this label
 - **`header`** `ReactNode` — Custom header content
@@ -185,7 +185,7 @@ The `mods` property accepts the following modifiers you can override:
 - Use `plain` when embedding ListBox directly into another component
 - Use `popover` when using ListBox inside overlays (Dialog, ComboBox, Picker)
 
-**listGap** (`number`, default: a hairline, `1bw`)
+**listGap** (`number`, default: a hairline, `$item-gap`)
 
 - The space between options, in pixels
 - Use it rather than a margin in `optionStyles`: a virtualized list positions its options itself, so it ignores their margins

package/docs/components/fields/Picker.md

@@ -34,7 +34,7 @@ Choose a different component when the interaction has another shape:
 - **`defaultSelectedKeys`** `string[] | 'all'` — The default selected keys in uncontrolled multiple mode
 - **`items`** `Iterable<T>` — Array of items for dynamic content with render function pattern
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`type`** `'outline' | 'outline-2' | 'clear' | 'primary'` (default: `outline`) — Trigger button styling type
 - **`theme`** `'default' | 'danger'` (default: `default`) — Trigger button color theme
 - **`icon`** `ReactNode` — Icon displayed in the trigger button

package/docs/components/fields/SearchComboBox.md

@@ -37,7 +37,7 @@ Choose a different component when the interaction has another outcome:
 - **`isLoading`** `boolean` (default: `false`) — Whether items are being loaded (e.g. from a server)
 - **`loadingDelay`** `number` (default: `1000`) — Delay in ms before the loading indicator appears
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the component
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`disabledKeys`** `Iterable<Key>` — Keys of suggestions that cannot be selected
 - **`onSelect`** `(key: string, textValue: string) => void` — Fired when a suggestion is picked; the input clears afterwards
 - **`onSubmit`** `(value: string) => void` — Opt-in. Fired when Enter is pressed with no focused/available option; the input clears afterwards

package/docs/components/fields/Select.md

@@ -56,7 +56,7 @@ Choose a different component when the interaction has another shape:
 - **`inputStyles`** `Styles` — Styles for the input trigger element
 - **`listBoxStyles`** `Styles` — Styles for the dropdown list container
 - **`optionStyles`** `Styles` — Styles for individual option items
-- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
+- **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`$item-gap`, `1px`)
 - **`overlayStyles`** `Styles` — Styles for the dropdown overlay wrapper
 - **`triggerStyles`** `Styles` — Styles for the trigger button element
 - **`inputProps`** `Props` — Additional props for the trigger button element