@cube-dev/ui-kit 0.124.1 → 0.124.2

package/dist/provider.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { EventBusProvider } from "./utils/react/useEventBus.js";
 import { defaultNavigationAdapter } from "./providers/navigationAdapter.default.js";
 import { createContext, useContext, useMemo } from "react";

package/dist/providers/TrackingProvider.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { createContext, useContext, useMemo } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 

package/dist/providers/navigationAdapter.default.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/providers/navigationAdapter.default.ts
 /**
 * Converts a Path object to a string URL

package/dist/tokens/base.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/tokens/base.ts
 /**
 * Base design system tokens.

package/dist/tokens/colors.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/tokens/colors.ts
 const PINK_HUE = 5;
 const PURPLE_HUE = 280.3;

package/dist/tokens/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { BASE_TOKENS } from "./base.js";
 import { COLOR_TOKENS } from "./colors.js";
 import { LAYOUT_TOKENS } from "./layout.js";

package/dist/tokens/layout.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/tokens/layout.ts
 /**
 * Layout-related tokens for common UI dimensions.

package/dist/tokens/shadows.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/tokens/shadows.ts
 /**
 * Shadow tokens using tasty shorthand syntax.

package/dist/tokens/sizes.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/utils/ResizeSensor.ts
 /**
 * Iterate over each of the provided element(s).

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

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/utils/is-dev-env.ts
 function isDevEnv() {
 	if (typeof window !== "undefined" && window.localStorage) try {

package/dist/utils/modules.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { useRef } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 

package/dist/utils/react/Slots.js

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

package/dist/utils/react/chain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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/forwardRefWithGenerics.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/utils/react/forwardRefWithGenerics.tsx
 /**
 * A helper for creating forwardRef components with generic types.

package/dist/utils/react/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { forwardRefWithGenerics } from "./forwardRefWithGenerics.js";
 import { isTextOnly } from "./isTextOnly.js";

package/dist/utils/react/interactions.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { useState } from "react";
 import { useFocus, useFocusVisible } from "react-aria";
 

package/dist/utils/react/isTextOnly.js

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

package/dist/utils/react/mapProps.js

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

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useSyncExternalStore } from "react";
 

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { useEffect } from "react";
 import { useFocusVisible } from "react-aria";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import React, { createContext, useCallback, useContext, useEffect, 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useEffect, useRef, useState } from "react";
 import { useSSRSafeId } from "@react-aria/ssr";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | 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.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.2 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.124.1";
+const VERSION = "0.124.2";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	window.CubeUIKit = window.CubeUIKit || { version };

package/docs/tasty/design-system.md

@@ -333,13 +333,19 @@ A design system works best when the rules for customization are explicit. Tasty
 <Space flow="row" gap="3x" padding="2x">
 ```
 
-2. **Pass tokens** — inject runtime values through the `tokens` prop for per-instance customization:
+2. **Use modProps** — control component states through typed props instead of `mods`:
+
+```tsx
+<Button isLoading size="large">Submit</Button>
+```
+
+3. **Pass tokens** — inject runtime values through the `tokens` prop for per-instance customization:
 
 ```tsx
 <ProgressBar tokens={{ '$progress': `${percent}%` }} />
 ```
 
-3. **Create styled wrappers** — extend a component's styles with `tasty(Base, { styles })`:
+4. **Create styled wrappers** — extend a component's styles with `tasty(Base, { styles })`:
 
 ```tsx
 const DangerButton = tasty(Button, {

package/docs/tasty/dsl.md

@@ -93,6 +93,8 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
+Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](runtime.md#mod-props).
+
 ---
 
 ## Color Tokens & Opacity

package/docs/tasty/methodology.md

@@ -163,6 +163,61 @@ Exposing every CSS property as a prop defeats the purpose of a design system. Th
 
 ---
 
+## modProps and mods
+
+`modProps` expose modifier keys as top-level component props — the modifier equivalent of `styleProps`. Use them when a component has a fixed set of known state modifiers.
+
+```tsx
+const Card = tasty({
+  modProps: {
+    isLoading: Boolean,
+    isSelected: Boolean,
+  },
+  styles: {
+    fill: { '': '#surface', isLoading: '#surface.5' },
+    border: { '': '1bw solid #outline', isSelected: '2bw solid #primary' },
+  },
+});
+
+// Clean prop API — no mods object needed
+<Card isLoading isSelected>Content</Card>
+```
+
+### When to use which
+
+| Pattern | Use when |
+|---|---|
+| `modProps` | The component has a fixed set of known boolean/string states that drive styles. Provides TypeScript autocomplete and a cleaner JSX API. |
+| `mods` prop | The component needs arbitrary or dynamic modifiers that aren't known at definition time. |
+| Both | Combine `modProps` for the known states and `mods` for ad-hoc overrides. Mod props take precedence. |
+| `styleProps` | Exposing CSS properties (layout, sizing) for customization — different from modifiers. |
+
+### Typed modProps vs array form
+
+The object form gives precise TypeScript types using JS constructors (`Boolean`, `String`, `Number`) or enum arrays:
+
+```tsx
+const Button = tasty({
+  modProps: {
+    isLoading: Boolean,
+    size: ['small', 'medium', 'large'] as const,
+  },
+  // ...
+});
+
+// TypeScript knows: isLoading?: boolean, size?: 'small' | 'medium' | 'large'
+```
+
+The array form is simpler but types all values as `ModValue`:
+
+```tsx
+modProps: ['isLoading', 'isSelected'] as const,
+```
+
+For the full API reference, see [Runtime — Mod Props](runtime.md#mod-props).
+
+---
+
 ## tokens prop for dynamic values
 
 Every Tasty component accepts a `tokens` prop that renders as inline CSS custom properties on the element. This is the mechanism for per-instance dynamic values.
@@ -402,8 +457,9 @@ See [Configuration](configuration.md) for the full `configure()` API.
 - **Use semantic transition names** (`transition: 'theme 0.3s'`) instead of listing CSS properties
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
+- **Use `modProps`** to expose known modifier states as clean component props
 - **Use `tokens` prop** for per-instance dynamic values (progress, user color)
-- **Use modifiers** (`mods`) for state-driven style changes instead of runtime `styles` prop changes
+- **Use modifiers** (`mods` or `modProps`) for state-driven style changes instead of runtime `styles` prop changes
 
 ### Avoid
 
@@ -441,11 +497,19 @@ Tasty's enhanced properties provide concise syntax, better composability, and si
 // Bad: styles object changes every render
 <Card styles={{ padding: isCompact ? '2x' : '4x' }} />
 
-// Good: use modifiers
-<Card mods={{ compact: isCompact }} />
+// Good: use modifiers via modProps
+<Card isCompact={isCompact} />
+
+// Or via mods object
+<Card mods={{ isCompact }} />
 
 // In the component definition:
-padding: { '': '4x', compact: '2x' },
+const Card = tasty({
+  modProps: ['isCompact'] as const,
+  styles: {
+    padding: { '': '4x', isCompact: '2x' },
+  },
+});
 ```
 
 Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS.

package/docs/tasty/runtime.md

@@ -74,6 +74,86 @@ For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_ST
 
 ---
 
+## Mod Props
+
+Use `modProps` to expose modifier keys as direct component props instead of requiring the `mods` object:
+
+```jsx
+// Before: mods object
+<Button mods={{ isLoading: true, size: 'large' }}>Submit</Button>
+
+// After: mod props
+<Button isLoading size="large">Submit</Button>
+```
+
+### Array form
+
+List modifier key names. Types default to `ModValue` (`boolean | string | number | undefined | null`):
+
+```jsx
+const Button = tasty({
+  modProps: ['isLoading', 'isSelected'] as const,
+  styles: {
+    fill: { '': '#surface', isLoading: '#surface.5' },
+    border: { '': '1bw solid #outline', isSelected: '2bw solid #primary' },
+  },
+});
+
+<Button isLoading isSelected>Submit</Button>
+// Renders: <button data-is-loading="" data-is-selected="">Submit</button>
+```
+
+### Object form (typed)
+
+Map modifier names to type descriptors for precise TypeScript types:
+
+```tsx
+const Button = tasty({
+  modProps: {
+    isLoading: Boolean,   // isLoading?: boolean
+    isSelected: Boolean,  // isSelected?: boolean
+    size: ['small', 'medium', 'large'] as const,  // size?: 'small' | 'medium' | 'large'
+  },
+  styles: {
+    padding: { '': '2x 4x', 'size=small': '1x 2x', 'size=large': '3x 6x' },
+    fill: { '': '#surface', isLoading: '#surface.5' },
+  },
+});
+
+<Button isLoading size="large">Submit</Button>
+// Renders: <button data-is-loading="" data-size="large">Submit</button>
+```
+
+Available type descriptors:
+
+| Descriptor | TypeScript type | Example |
+|---|---|---|
+| `Boolean` | `boolean` | `isLoading: Boolean` |
+| `String` | `string` | `label: String` |
+| `Number` | `number` | `count: Number` |
+| `['a', 'b'] as const` | `'a' \| 'b'` | `size: ['sm', 'md', 'lg'] as const` |
+
+### Merge with `mods`
+
+Mod props and the `mods` object can be used together. Mod props take precedence:
+
+```jsx
+<Button mods={{ isLoading: false, extra: true }} isLoading>
+// isLoading=true wins (from mod prop), extra=true preserved from mods
+```
+
+### When to use `modProps` vs `mods`
+
+| Use case | Recommendation |
+|---|---|
+| Component has a fixed set of known modifiers | `modProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic modifiers | `mods` — open-ended `Record<string, ModValue>` |
+| Both fixed and dynamic | Combine: `modProps` for known keys, `mods` for ad-hoc |
+
+For architecture guidance on when to use modifiers vs `styleProps`, see [Methodology — modProps and mods](methodology.md#modprops-and-mods).
+
+---
+
 ## Variants
 
 Define named style variations. Only CSS for variants actually used at runtime is injected:

package/docs/tasty/styles.md

@@ -146,37 +146,39 @@ Individual props `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marg
 
 ### `width`
 
-Element width with min/max control.
+Element width with min/max control. One, two, or three values set `min-width`, `width`, and `max-width` together.
 
-**Syntax:** `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
+**Positional syntax:**
 
-**Modifiers:** `min`, `max`, `fixed`
+| Value | min-width | width | max-width |
+|-------|-----------|-------|-----------|
+| `"10x"` | initial | `10x` | initial |
+| `"1x 10x"` | `1x` | auto | `10x` |
+| `"1x 5x 10x"` | `1x` | `5x` | `10x` |
+| `"0 100% 800px"` | `0` | `100%` | `800px` |
+| `"initial 100% 1400px"` | initial | `100%` | `1400px` |
+
+**Modifier syntax:**
+
+| Value | min-width | width | max-width |
+|-------|-----------|-------|-----------|
+| `"min 2x"` | `2x` | auto | initial |
+| `"max 100%"` | initial | auto | `100%` |
+| `"fixed 200px"` | `200px` | `200px` | `200px` |
 
 **Keywords:** `stretch`, `max-content`, `min-content`, `fit-content`
 
 | Value | Effect |
 |-------|--------|
-| `"10x"` | Width `10x`, min `initial`, max `initial` |
-| `"1x 10x"` | Width `auto`, min `1x`, max `10x` |
-| `"1x 5x 10x"` | Min `1x`, width `5x`, max `10x` |
-| `"min 2x"` | Min-width `2x`, width `auto`, max `initial` |
-| `"max 100%"` | Max-width `100%`, width `auto`, min `initial` |
-| `"fixed 200px"` | Min, width, and max all set to `200px` |
 | `"stretch"` | Fill available space (cross-browser) |
-| `true` | Width `auto`, min `initial`, max `initial` |
+| `true` | Reset to `auto` / `initial` / `initial` |
 | Number | Converted to `px` |
 
 Separate `minWidth` and `maxWidth` props are supported and override values from the `width` syntax.
 
 ### `height`
 
-Element height. Same syntax and modifiers as `width`.
-
-**Syntax:** `[value]` | `[min max]` | `[min value max]` | `[modifier value]`
-
-**Modifiers:** `min`, `max`, `fixed`
-
-**Keywords:** `max-content`, `min-content`, `fit-content`
+Element height. Same syntax, modifiers, and positional patterns as `width`.
 
 Separate `minHeight` and `maxHeight` props are supported and override values from the `height` syntax.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.124.1",
+  "version": "0.124.2",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -45,7 +45,7 @@
     "@react-types/shared": "^3.32.1",
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
-    "@tenphi/tasty": "0.14.2",
+    "@tenphi/tasty": "0.15.2",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",