@cube-dev/ui-kit 0.123.1 → 0.124.1

package/dist/tokens/base.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | 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.123.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.124.1 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.123.1";
+const VERSION = "0.124.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	window.CubeUIKit = window.CubeUIKit || { version };

package/docs/components/actions/Menu.md

@@ -66,8 +66,6 @@ Customizes individual menu items.
 - `Icon` - Icon element within menu items
 - `Text` - Main text content of menu items
 - `Description` - Secondary text content for items with descriptions
-- `Postfix` - Right-aligned content (shortcuts, badges, etc.)
-
 #### sectionStyles
 
 Customizes section container elements.

package/docs/tasty/README.md

@@ -1,12 +1,13 @@
 # Tasty Docs
 
-Use this page when you know what you want to do, but not which document to open next.
+Tasty is a styling engine for design systems that turns component state into deterministic CSS by compiling state maps into mutually exclusive selectors. Use this hub to choose the right guide once you know whether you are evaluating the model, adopting it in a design system, or implementing reusable, stateful components day to day.
 
 ## Start Here
 
 - **New to Tasty**: [Getting Started](getting-started.md) for installation, the first component, optional shared `configure()`, ESLint, editor tooling, and rendering mode selection.
 - **Learning the component model**: [Methodology](methodology.md) for root + sub-elements, `styleProps`, tokens, extension, and recommended boundaries between `styles`, `style`, and wrappers.
-- **Evaluating fit**: [Comparison](comparison.md) for tool-selection context, then [Adoption Guide](adoption.md) for rollout strategy inside a design system.
+- **Evaluating the selector model**: [Style rendering pipeline](PIPELINE.md) for how mutually exclusive selectors make stateful styling deterministic.
+- **Evaluating fit**: [Comparison](comparison.md) for tool-selection context, then [Adoption Guide](adoption.md) for audience fit and rollout strategy inside a design system.
 
 ## By Role
 
@@ -14,11 +15,11 @@ Use this page when you know what you want to do, but not which document to open
 - **Design-system author**: [Methodology](methodology.md), [Building a Design System](design-system.md), [Configuration](configuration.md), and [Adoption Guide](adoption.md).
 - **Platform or tooling engineer**: [Configuration](configuration.md), [Zero Runtime (tastyStatic)](tasty-static.md), [Server-Side Rendering](ssr.md), and [Debug Utilities](debug.md).
 
-## By Rendering Mode
+## By Styling Approach
 
 - **Runtime React components**: [Runtime API](runtime.md)
 - **Zero-runtime / build-time extraction**: [Zero Runtime (tastyStatic)](tasty-static.md)
-- **SSR with runtime `tasty()`**: [Server-Side Rendering](ssr.md)
+- **Runtime `tasty()` with server collection and hydration**: [Server-Side Rendering](ssr.md)
 
 ## By Task
 

package/docs/tasty/adoption.md

@@ -1,6 +1,6 @@
 # Adoption Guide
 
-Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**. That means the adoption path is not "rewrite your classes" but "reshape your styling architecture."
+Tasty is not a drop-in replacement for another styling library. It is a **substrate for building a design-system-defined styling language**: what the comparison guide calls a house styling language. That means adoption usually starts where styling for reusable, stateful components has already become a composition problem, not with an all-at-once rewrite.
 
 This guide is for design-system maintainers and platform engineers evaluating Tasty or introducing it into an existing codebase. Use this document for rollout strategy and adoption sequencing; use the [Comparison guide](comparison.md) when the open question is whether Tasty is the right tool in the first place.
 
@@ -116,6 +116,8 @@ See [Configuration](configuration.md) for the full `configure()` API.
 
 You do not need to adopt everything at once. Tasty is designed to be introduced layer by layer.
 
+A practical way to start is with the components that already suffer from intersecting state and variant logic: buttons, inputs, menus, disclosures, dialogs, list items, interactive cards, and compound components. Those are the places where deterministic resolution pays off fastest.
+
 ### Phase 1 -- Tokens and units
 
 Start by defining your design tokens and custom units. This is the lowest-risk step: it only configures the parser and does not require rewriting any components.
@@ -161,7 +163,7 @@ configure({
 
 ### Phase 3 -- Migrate a few primitives
 
-Pick 2-3 simple, widely used components (Box, Text, Button) and rewrite them with `tasty()`. Keep the public API identical so product code does not need to change.
+Pick 2-3 widely used primitives (Box, Text, Button) and rewrite them with `tasty()`. Keep the public API identical so product code does not need to change.
 
 ```tsx
 const Box = tasty({
@@ -175,11 +177,11 @@ const Box = tasty({
 });
 ```
 
-At this point you can validate the DSL, token workflow, and component authoring experience before committing further.
+At this point you can validate the DSL, token workflow, and component authoring experience before expanding the rollout.
 
 ### Phase 4 -- Encode complex states
 
-Move components with intersecting states (buttons with hover + disabled + theme variants, inputs with focus + error + readonly) to Tasty's state map syntax. This is where mutually exclusive selectors start paying off.
+Move the components with the most painful intersecting states (buttons with hover + disabled + theme variants, inputs with focus + error + readonly) to Tasty's state map syntax. This is where mutually exclusive selectors start paying off.
 
 ```tsx
 const Button = tasty({

package/docs/tasty/comparison.md

@@ -4,6 +4,10 @@ Use this guide when you are deciding whether Tasty is the right tool. If you hav
 
 Tasty is best understood not as a general-purpose CSS framework, but as a **styling engine for design systems and shared component APIs**.
 
+It targets a different layer: helping design-system teams define a **house styling language** on top of CSS.
+
+That does not require a big upfront configuration step. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
+
 Most styling tools focus on one of these layers:
 
 - direct app styling
@@ -12,9 +16,7 @@ Most styling tools focus on one of these layers:
 - utility composition
 - atomic CSS generation
 
-Tasty targets a different layer: it helps teams define a **house styling language** on top of CSS, including tokens, state semantics, style props, recipes, custom units, and sub-element rules.
-
-That does not mean a big upfront configuration step is required. Tasty's built-in units and normal CSS color values work out of the box, and `okhsl(...)` is available immediately as the recommended path for color authoring. The extra setup comes later if a team wants shared tokens, aliases, recipes, or stricter conventions.
+Tasty's house styling language can include tokens, state semantics, style props, recipes, custom units, and sub-element rules. In other words, it is a governed styling model, not just another syntax for writing CSS.
 
 That is why syntax-level comparisons are often shallow. The more meaningful comparison is about:
 
@@ -87,9 +89,9 @@ Tasty compiles this into selectors where `disabled` is guarded by `:not(:hover)`
 
 That makes Tasty less of a "better way to write CSS objects" and more of a **state-aware style compiler for design systems**.
 
-Beyond state resolution, Tasty includes several structural capabilities that most other tools do not offer:
+Beyond state resolution, Tasty also provides several structural capabilities that reinforce the design-system layer:
 
-- **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. No other tool provides this as a first-class, typed, design-system-aware feature.
+- **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. This keeps layout and composition controls inside a governed component API instead of pushing teams back to ad hoc styling escapes.
 - **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and `data-element` attributes. States, tokens, and recipes apply across the entire element tree from a single definition. See [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
 - **Auto-inferred `@property`** — When a custom property is assigned a concrete value, Tasty infers the CSS `@property` syntax and registers it automatically, enabling smooth transitions on custom properties without manual declarations.
 - **AI-friendly style definitions** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, refactor, and generate Tasty styles as confidently as a human — no hidden cascade logic or implicit ordering to second-guess.
@@ -122,7 +124,7 @@ So this is not mainly a comparison of syntax. It is a comparison of **governance
 - Tailwind: developers author directly with framework vocabulary
 - Tasty: design-system authors define the vocabulary product teams consume
 
-Tailwind is usually a stronger fit for fast product styling with framework-owned vocabulary. Tasty is usually a stronger fit when teams want direct usability now, but also a path toward governed design-system architecture.
+Tailwind is a stronger fit for fast product styling with framework-owned vocabulary. Tasty is a stronger fit when styling should be exposed through a design-system-owned API and state resolution needs to stay deterministic as the component model grows.
 
 To make this concrete, consider a button with `hover`, `disabled`, and `theme=danger` states.
 
@@ -301,7 +303,7 @@ So while Stitches and Emotion are strong tools for building components, Tasty is
 
 That makes it narrower in audience, but deeper in architectural ambition.
 
-Tasty's runtime performance is also validated in enterprise-scale applications where styling overhead is not noticeable in normal UI flows — an important consideration for teams evaluating runtime CSS-in-JS at scale.
+For teams evaluating runtime styling at scale, Tasty also documents its runtime benchmarks and caching model in the main [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
 
 ---
 

package/docs/tasty/design-system.md

@@ -2,7 +2,7 @@
 
 This guide walks through building a design-system styling layer on top of Tasty — defining tokens, state aliases, recipes, primitive components, and compound components with sub-elements.
 
-It assumes you have already decided to adopt Tasty. For evaluation criteria, audience fit, and incremental adoption phases, see the [Adoption Guide](adoption.md). For the recommended component patterns and mental model, see [Methodology](methodology.md).
+It assumes you have already decided to adopt Tasty. The goal is not just to centralize tokens, but to define a styling language whose component states resolve deterministically across variants, responsive rules, and sub-elements. For evaluation criteria, audience fit, and incremental adoption phases, see the [Adoption Guide](adoption.md). For the recommended component patterns and mental model, see [Methodology](methodology.md).
 
 ---
 

package/docs/tasty/dsl.md

@@ -36,6 +36,46 @@ styles: { Title: { preset: 'h3' } }
 // Targets: <div data-element="Title">
 ```
 
+#### Selector Affix (`$`)
+
+Control how a sub-element selector attaches to the root selector using the `$` property inside the sub-element's styles:
+
+| Pattern | Result | Description |
+|---------|--------|-------------|
+| *(none)* | ` [el]` | Descendant (default) |
+| `>` | `> [el]` | Direct child |
+| `>Body>Row>` | `> [Body] > [Row] > [el]` | Chained elements |
+| `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 |
+
+Rules for key injection (`[data-element="..."]`):
+
+- **Trailing combinator** (`>`, `+`, `~`) — key is injected after it
+- **Uppercase element name** (`Body`, `Row`) — key is injected as descendant
+- **HTML tag** (`h1`, `a`, `span`) — no key injection; the tag IS the selector
+- **Universal selector** (`*`) — no key injection
+- **Pseudo / class / attribute** — no key injection
+
+The `@` placeholder marks exactly where `[data-element="..."]` is injected, allowing you to attach pseudo-classes, pseudo-elements, or class selectors directly to the sub-element instead of the root:
+
+```jsx
+const List = tasty({
+  styles: {
+    Item: {
+      $: '>@:last-child',
+      border: 'none',
+    },
+  },
+});
+// → .t0 > [data-element="Item"]:last-child { border: none }
+```
+
 ### Color Token
 
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:

package/docs/tasty/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
+This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
 
 ---
 
@@ -10,6 +10,8 @@ This guide walks you from zero to a working Tasty component, then through the op
 - **React** >= 18 (peer dependency)
 - **Package manager**: pnpm, npm, or yarn
 
+Tasty can be used immediately in a React app, but it is most compelling for teams building reusable components with intersecting states, variants, tokens, and design-system conventions.
+
 ---
 
 ## Install
@@ -177,25 +179,25 @@ export default [
 
 ## Choosing a rendering mode
 
-Tasty supports three rendering modes. Pick the one that fits your use case:
+Tasty has two styling approaches. Pick the one that fits your use case, then decide whether your runtime setup also needs server rendering support:
 
-| Mode | Entry point | Best for | Trade-off |
+| Approach | Entry point | Best for | Trade-off |
 |------|-------------|----------|-----------|
-| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
+| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps with reusable stateful components, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
 | **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Static sites, landing pages, SSG | Zero JS overhead; requires Babel plugin; no dynamic props |
-| **SSR** | `@tenphi/tasty/ssr/next` or `@tenphi/tasty/ssr/astro` | Next.js, Astro, streaming SSR | Runtime `tasty()` with server-rendered CSS and zero-cost hydration |
 
-All three share the same DSL, tokens, units, and state mappings.
+Both share the same DSL, tokens, units, and state mappings.
 
 - Runtime is the default and requires no extra setup beyond `@tenphi/tasty`.
+- If your framework can execute runtime code during server rendering, add SSR support on top of runtime with `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API. This still uses `tasty()`; it just collects CSS on the server and hydrates the cache on the client.
 - Zero-runtime requires the Babel plugin and additional peer dependencies. See [Zero Runtime (tastyStatic)](tasty-static.md).
-- SSR works with existing `tasty()` components — wrap your app with a registry or middleware. See [Server-Side Rendering](ssr.md).
+- SSR works with existing `tasty()` components — wrap your app with a registry, middleware, or collector. See [Server-Side Rendering](ssr.md).
 
 ---
 
 ## Next steps
 
-- **[Docs Hub](README.md)** — Pick the next guide by role, rendering mode, or task
+- **[Docs Hub](README.md)** — Pick the next guide by role, styling approach, or task
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
 - **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
@@ -212,4 +214,4 @@ All three share the same DSL, tokens, units, and state mappings.
 
 - Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
 - Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](debug.md).
-- You need zero-runtime or SSR instead of the default runtime path: use [Zero Runtime (tastyStatic)](tasty-static.md) or [Server-Side Rendering](ssr.md) rather than trying to retrofit the runtime setup later.
+- You need build-time extraction or server-rendered CSS delivery: use [Zero Runtime (tastyStatic)](tasty-static.md) for extraction, or add [Server-Side Rendering](ssr.md) on top of runtime `tasty()` when your framework renders on the server.

package/docs/tasty/methodology.md

@@ -1,11 +1,13 @@
 # Methodology
 
-Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: better state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
+Tasty has opinions about how components should be structured. The patterns described here are not mandatory — Tasty works without them — but following them gets the most out of the engine: deterministic state resolution, cleaner component APIs, simpler overrides, and fewer surprises as the system grows.
 
 ---
 
 ## Component architecture: root + sub-elements
 
+This model matters most for design-system authors and platform teams building reusable, stateful components. It turns Tasty's selector guarantees into a component architecture that stays predictable as states, variants, and compound parts accumulate.
+
 ### The model
 
 Every Tasty component has a **root element** and zero or more **sub-elements**. The root owns the state context. Sub-elements participate in the same context by default.