@viraui/react 2026.6.0 → 2026.6.1

package/dist/catalog.json

@@ -41,7 +41,7 @@
     {
       "id": "beam",
       "name": "Beam",
-      "summary": "Decorative animated border, line, or pulse glow on a transparent Surface shell (radius only). Put the visual card as children. CSS-module geometry plus shared ~30fps pulse rAF for pulse variants. Memory/CPU cost — use sparingly.",
+      "summary": "Decorative animated border, line, or pulse glow on a transparent Surface shell (radius only). Put the visual card as children. CSS-module geometry plus shared ~30fps pulse rAF for pulse variants. Memory/CPU-heavy — use sparingly; prefer one focal instance per view.",
       "agentDocs": "./specs/components/beam/meta.xml"
     },
     {
@@ -53,7 +53,7 @@
     {
       "id": "breakpoints",
       "name": "BreakpointsProvider",
-      "summary": "Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens.",
+      "summary": "Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens. Style-only CSS should reuse the same map lengths.",
       "agentDocs": "./specs/components/breakpoints/meta.xml"
     },
     {
@@ -107,7 +107,7 @@
     {
       "id": "glow",
       "name": "Glow",
-      "summary": "Decorative pointer-driven border highlight on a transparent Surface shell (radius only). Put the visual card as children; a shared rAF tracker paints CSS variables without React re-renders. Memory-heavy — use sparingly (rarely).",
+      "summary": "Decorative pointer-driven border highlight on a transparent Surface shell (radius only). Put the visual card as children; a shared rAF tracker paints CSS variables without React re-renders. Memory/CPU-heavy — use sparingly; prefer one focal instance per view.",
       "agentDocs": "./specs/components/glow/meta.xml"
     },
     {
@@ -155,7 +155,7 @@
     {
       "id": "progressive-blur",
       "name": "ProgressiveBlur",
-      "summary": "Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge.",
+      "summary": "Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge. GPU/memory-heavy — use sparingly; prefer one focal instance per view.",
       "agentDocs": "./specs/components/progressive-blur/meta.xml"
     },
     {
@@ -209,7 +209,7 @@
     {
       "id": "static-noise",
       "name": "StaticNoise",
-      "summary": "Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly (rarely).",
+      "summary": "Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly; prefer one focal instance per view.",
       "agentDocs": "./specs/components/static-noise/meta.xml"
     },
     {

package/dist/components/stack/stack.d.ts

@@ -46,8 +46,9 @@ export type StackProps = React.ComponentPropsWithoutRef<'div'> & {
     /**
      * Makes direct children grow along the flex main axis (`flex-grow`).
      *
+     * Prefer for equal-width row actions instead of inventing width/flex CSS on each child.
      * Does not set the stack root's own inline size — use `fullWidth` when this stack must
-     * fill its parent width (e.g. centered shell with `maxWidth`).
+     * fill its parent width (e.g. centered shell with `maxWidth`, or a full-bleed Button column).
      *
      * @default false
      */
@@ -55,6 +56,8 @@ export type StackProps = React.ComponentPropsWithoutRef<'div'> & {
     /**
      * Sets `inline-size: 100%` on the stack root so it fills the parent's inline size.
      *
+     * Prefer this (with cross-axis stretch) so content-sized children like Button span a panel —
+     * do not add `width: 100%` CSS on those children.
      * Use with `maxWidth` under a parent `hAlign="center"` for a fluid, capped, centered shell.
      * Orthogonal to `expandChildren` (self size vs children grow).
      *

package/dist/components/tabs/tabs.css

@@ -1 +1 @@
-@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-tabs-translate-amount{syntax:"<length>";inherits:true;initial-value:10px}.viraui__tabs-module__Tabs_AwbZZ{min-block-size:10rem}.viraui__tabs-module__Viewport_15X1I{display:grid;grid-template-columns:minmax(0,1fr);inline-size:100%}.viraui__tabs-module__Panel_vkCFI{grid-area:1/1;inline-size:100%;opacity:1;translate:0 0;transition:opacity var(--duration-fast) var(--easing-entrance),translate var(--duration-fast) var(--easing-entrance);&[data-ending-style]{pointer-events:none}&[data-ending-style],&[data-starting-style]{opacity:0}&[data-activation-direction=right][data-starting-style]{translate:var(--vui-tabs-translate-amount) 0}&[data-activation-direction=left][data-starting-style],&[data-activation-direction=right][data-ending-style]{translate:calc(var(--vui-tabs-translate-amount) * -1) 0}&[data-activation-direction=left][data-ending-style]{translate:var(--vui-tabs-translate-amount) 0}&[data-activation-direction=none][data-ending-style],&[data-activation-direction=none][data-starting-style]{translate:0 var(--vui-tabs-translate-amount)}&[hidden]{display:none}@media (prefers-reduced-motion:reduce){&[data-ending-style],&[data-starting-style]{opacity:1;translate:0 0}}}}@layer viraui.overrides{.viraui__tabs-module__List_XJorr{position:relative;max-inline-size:100%;overflow-x:auto;overflow-y:clip}.viraui__tabs-module__Track_Fet4f{display:inline-flex;min-inline-size:100%;box-sizing:border-box;padding-inline:var(--space-2xs)}.viraui__tabs-module__Indicator_UyNUn{position:absolute;pointer-events:none;inset-block-start:0;inset-inline-start:0;inline-size:var(--active-tab-width);block-size:round(nearest,var(--active-tab-height),2px);translate:var(--active-tab-left) calc(var(--active-tab-top) + (var(--active-tab-height) - round(nearest, var(--active-tab-height), 2px)) / 2);transition:translate var(--duration-fast) var(--easing-standard),inline-size var(--duration-fast) var(--easing-standard),block-size var(--duration-fast) var(--easing-standard)}.viraui__tabs-module__Item_XZ86Z{position:relative;flex-shrink:0;cursor:pointer;flex-basis:0;transition:none;will-change:auto;&[data-variant]:not(:disabled):active{translate:0 0}&:hover{background:#0000}&[data-disabled]{opacity:.5;background:#0000}&[data-active] .viraui__tabs-module__Label_5-8-Y{color:var(--global-foreground)}&:focus-visible{border-radius:var(--radius-s);outline-offset:-2px}}}
+@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-tabs-translate-amount{syntax:"<length>";inherits:true;initial-value:10px}.viraui__tabs-module__Tabs_AwbZZ{min-block-size:10rem}.viraui__tabs-module__Viewport_15X1I{display:grid;grid-template-columns:minmax(0,1fr);inline-size:100%}.viraui__tabs-module__Panel_vkCFI{grid-area:1/1;inline-size:100%;opacity:1;translate:0 0;transition:opacity var(--duration-fast) var(--easing-entrance),translate var(--duration-fast) var(--easing-entrance);&[data-ending-style]{pointer-events:none}&[data-ending-style],&[data-starting-style]{opacity:0}&[data-activation-direction=right][data-starting-style]{translate:var(--vui-tabs-translate-amount) 0}&[data-activation-direction=left][data-starting-style],&[data-activation-direction=right][data-ending-style]{translate:calc(var(--vui-tabs-translate-amount) * -1) 0}&[data-activation-direction=left][data-ending-style]{translate:var(--vui-tabs-translate-amount) 0}&[data-activation-direction=none][data-ending-style],&[data-activation-direction=none][data-starting-style]{translate:0 var(--vui-tabs-translate-amount)}&[hidden]{display:none}@media (prefers-reduced-motion:reduce){&[data-ending-style],&[data-starting-style]{opacity:1;translate:0 0}}}}@layer viraui.overrides{.viraui__tabs-module__List_XJorr{position:relative;max-inline-size:100%;overflow-x:auto;overflow-y:clip}.viraui__tabs-module__Track_Fet4f{display:inline-flex;min-inline-size:100%;box-sizing:border-box;padding-inline:var(--space-2xs)}.viraui__tabs-module__Indicator_UyNUn{position:absolute;pointer-events:none;inset-block-start:0;left:0;inline-size:var(--active-tab-width);block-size:round(nearest,var(--active-tab-height),2px);translate:var(--active-tab-left) calc(var(--active-tab-top) + (var(--active-tab-height) - round(nearest, var(--active-tab-height), 2px)) / 2);transition:translate var(--duration-fast) var(--easing-standard),inline-size var(--duration-fast) var(--easing-standard),block-size var(--duration-fast) var(--easing-standard)}.viraui__tabs-module__Item_XZ86Z{position:relative;flex-shrink:0;cursor:pointer;flex-basis:0;transition:none;will-change:auto;&[data-variant]:not(:disabled):active{translate:0 0}&:hover{background:#0000}&[data-disabled]{opacity:.5;background:#0000}&[data-active] .viraui__tabs-module__Label_5-8-Y{color:var(--global-foreground)}&:focus-visible{border-radius:var(--radius-s);outline-offset:-2px}}}

package/dist/components/text/text.css

@@ -2,4 +2,4 @@
     var(--__text-size-min),
     calc(var(--__text-size-min) + (var(--__text-size-max) - var(--__text-size-min)) * var(--__text-fluid)),
     var(--__text-size-max)
-  );--vui-text-font-family:var(--font-family-body);--vui-text-line-height:var(--font-leading-m);margin:0;max-inline-size:var(--vui-text-max-width);font-family:var(--vui-text-font-family);font-size:var(--vui-text-font-size);line-height:var(--vui-text-line-height);text-align:var(--vui-text-align);letter-spacing:var(--vui-text-letter-spacing);text-transform:var(--vui-text-text-transform);white-space:var(--vui-text-white-space);word-break:break-word;font-weight:var(--vui-text-font-weight);font-stretch:calc(var(--vui-text-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-text-font-weight),"wdth" var(--vui-text-font-width),"opsz" var(--vui-text-font-opsz);text-box:var(--vui-text-trim) var(--vui-text-trim-type);&[data-text-balanced=true]{text-wrap:balance}&[data-text-selection=false]{-webkit-user-select:none;user-select:none}&[data-text-has-padding=true]{padding:var(--vui-text-padding-block-start) var(--vui-text-padding-inline-end) var(--vui-text-padding-block-end) var(--vui-text-padding-inline-start)}&[data-text-family=mono]{--vui-text-font-family:var(--font-family-mono)}&[data-text-size="4xl"]{--__text-size-min:var(--font-scale-body-3xl);--__text-size-max:var(--font-scale-body-4xl)}&[data-text-size="3xl"]{--__text-size-min:var(--font-scale-body-2xl);--__text-size-max:var(--font-scale-body-3xl)}&[data-text-size="2xl"]{--__text-size-min:var(--font-scale-body-xl);--__text-size-max:var(--font-scale-body-2xl)}&[data-text-size=xl]{--__text-size-min:var(--font-scale-body-l);--__text-size-max:var(--font-scale-body-xl)}&[data-text-size=l]{--__text-size-min:var(--font-scale-body-m);--__text-size-max:var(--font-scale-body-l)}&[data-text-size=s]{--__text-size-min:var(--font-scale-body-xs);--__text-size-max:var(--font-scale-body-s)}&[data-text-size=xs]{--vui-text-font-size:var(--font-scale-body-xs)}@container root style(--effect-fluid-typography: initial){--vui-text-font-size:var(--font-scale-body-m);&[data-text-size="4xl"]{--vui-text-font-size:var(--font-scale-body-4xl)}&[data-text-size="3xl"]{--vui-text-font-size:var(--font-scale-body-3xl)}&[data-text-size="2xl"]{--vui-text-font-size:var(--font-scale-body-2xl)}&[data-text-size=xl]{--vui-text-font-size:var(--font-scale-body-xl)}&[data-text-size=l]{--vui-text-font-size:var(--font-scale-body-l)}&[data-text-size=m]{--vui-text-font-size:var(--font-scale-body-m)}&[data-text-size=s]{--vui-text-font-size:var(--font-scale-body-s)}&[data-text-size=xs]{--vui-text-font-size:var(--font-scale-body-xs)}}&[data-text-weight=light]{--vui-text-font-weight:200}&[data-text-weight=semibold]{--vui-text-font-weight:600}&[data-text-weight=bold]{--vui-text-font-weight:800}&[data-text-tone=primary]{color:var(--global-primary)}&[data-text-tone=muted]{color:var(--global-muted)}&[data-text-tone=interactive]{color:var(--global-interactive-text)}&[data-text-tone=positive]{color:var(--highlight-green)}&[data-text-tone=informative]{color:var(--highlight-blue)}&[data-text-tone=danger]{color:var(--highlight-red)}&[data-text-tone=warning]{color:var(--highlight-yellow)}&[data-text-has-literal-color=true]{color:var(--vui-text-literal-color)}&[data-text-line-height=none]{--vui-text-line-height:0}&[data-text-line-height=xs]{--vui-text-line-height:var(--font-leading-xs)}&[data-text-line-height=s]{--vui-text-line-height:var(--font-leading-s)}&[data-text-line-height=m]{--vui-text-line-height:var(--font-leading-m)}&[data-text-line-height=l]{--vui-text-line-height:var(--font-leading-l)}}}
+  );--vui-text-font-family:var(--font-family-body);--vui-text-line-height:var(--font-leading-m);margin:0;max-inline-size:var(--vui-text-max-width);font-family:var(--vui-text-font-family);font-size:var(--vui-text-font-size);line-height:var(--vui-text-line-height);text-align:var(--vui-text-align);letter-spacing:var(--vui-text-letter-spacing);text-transform:var(--vui-text-text-transform);white-space:var(--vui-text-white-space);word-break:break-word;font-weight:var(--vui-text-font-weight);font-stretch:calc(var(--vui-text-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-text-font-weight),"wdth" var(--vui-text-font-width),"opsz" var(--vui-text-font-opsz);text-box:var(--vui-text-trim) var(--vui-text-trim-type);&[data-text-balanced=true]{text-wrap:balance}&[data-text-selection=false]{-webkit-user-select:none;user-select:none}&[data-text-has-padding=true]{padding:var(--vui-text-padding-block-start) var(--vui-text-padding-inline-end) var(--vui-text-padding-block-end) var(--vui-text-padding-inline-start)}&[data-text-family=mono]{--vui-text-font-family:var(--font-family-mono)}&[data-text-size="4xl"]{--__text-size-min:var(--font-scale-body-3xl);--__text-size-max:var(--font-scale-body-4xl)}&[data-text-size="3xl"]{--__text-size-min:var(--font-scale-body-2xl);--__text-size-max:var(--font-scale-body-3xl)}&[data-text-size="2xl"]{--__text-size-min:var(--font-scale-body-xl);--__text-size-max:var(--font-scale-body-2xl)}&[data-text-size=xl]{--__text-size-min:var(--font-scale-body-l);--__text-size-max:var(--font-scale-body-xl)}&[data-text-size=l]{--__text-size-min:var(--font-scale-body-m);--__text-size-max:var(--font-scale-body-l)}&[data-text-size=s]{--__text-size-max:var(--font-scale-body-s)}&[data-text-size=s],&[data-text-size=xs]{--__text-size-min:var(--font-scale-body-xs)}&[data-text-size=xs]{--__text-size-max:var(--font-scale-body-xs)}&[data-text-fluid=false]{--vui-text-font-size:var(--__text-size-max)}@container root style(--effect-fluid-typography: initial){--vui-text-font-size:var(--__text-size-max)}&[data-text-weight=light]{--vui-text-font-weight:200}&[data-text-weight=semibold]{--vui-text-font-weight:600}&[data-text-weight=bold]{--vui-text-font-weight:800}&[data-text-tone=primary]{color:var(--global-primary)}&[data-text-tone=muted]{color:var(--global-muted)}&[data-text-tone=interactive]{color:var(--global-interactive-text)}&[data-text-tone=positive]{color:var(--highlight-green)}&[data-text-tone=informative]{color:var(--highlight-blue)}&[data-text-tone=danger]{color:var(--highlight-red)}&[data-text-tone=warning]{color:var(--highlight-yellow)}&[data-text-has-literal-color=true]{color:var(--vui-text-literal-color)}&[data-text-line-height=none]{--vui-text-line-height:0}&[data-text-line-height=xs]{--vui-text-line-height:var(--font-leading-xs)}&[data-text-line-height=s]{--vui-text-line-height:var(--font-leading-s)}&[data-text-line-height=m]{--vui-text-line-height:var(--font-leading-m)}&[data-text-line-height=l]{--vui-text-line-height:var(--font-leading-l)}}}

package/dist/components/text/text.d.ts

@@ -83,13 +83,15 @@ export type TextProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     whiteSpace?: React.CSSProperties['whiteSpace'];
     /**
-     * Sets letter spacing on the rendered copy.
+     * Sets letter-spacing on the rendered copy. Prefer this prop over CSS
+     * `letter-spacing` on the same Text root.
      *
      * @default No letter-spacing override.
      */
     tracking?: React.CSSProperties['letterSpacing'];
     /**
-     * Applies a text-transform on the rendered copy.
+     * Applies `text-transform` on the rendered copy. Prefer this prop over CSS
+     * `text-transform` on the same Text root.
      *
      * @default No text-transform override.
      */
@@ -143,6 +145,14 @@ export type TextProps = React.ComponentPropsWithoutRef<'span'> & {
      * @default No optical size override.
      */
     opticalSize?: number;
+    /**
+     * Enables viewport fluid clamp sizing for this instance.
+     * Default locks at this size’s `--font-scale-body-*` token (UI chrome stays stable).
+     * Pass `true` for fluid page/body copy. Theme `--effect-fluid-typography: initial` still locks all Text globally.
+     *
+     * @default false
+     */
+    fluid?: boolean;
 };
 export declare const Text: React.FC<TextProps>;
 export {};

package/dist/components/text/text.js

@@ -4,7 +4,7 @@ import { resolveAxisPadding } from "../../core/styles/resolve-axis-padding.js";
 import text_module_default from "./text.module.js";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/text/text.tsx
-var Text = ({ align = "start", balanced = false, selection = true, className, color, family = "body", fontWidth, hPadding, lineHeight = "m", maxWidth, opticalSize, ref, render, size = "m", style, tone, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight = "regular", whiteSpace = "normal", ...otherProps }) => {
+var Text = ({ align = "start", balanced = false, selection = true, className, color, family = "body", fluid = false, fontWidth, hPadding, lineHeight = "m", maxWidth, opticalSize, ref, render, size = "m", style, tone, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight = "regular", whiteSpace = "normal", ...otherProps }) => {
 	const hasPadding = Boolean(hPadding || vPadding);
 	const dynamicStyle = {
 		"--vui-text-align": align,
@@ -35,6 +35,7 @@ var Text = ({ align = "start", balanced = false, selection = true, className, co
 			"data-text-line-height": lineHeight,
 			"data-text-balanced": balanced ? "true" : "false",
 			"data-text-selection": selection ? "true" : "false",
+			"data-text-fluid": fluid ? "true" : "false",
 			"data-text-has-padding": hasPadding ? "true" : "false",
 			"data-text-has-literal-color": color ? "true" : "false",
 			className: clsx(text_module_default.Text, className),

package/dist/components/textfield/textfield.d.ts

@@ -53,6 +53,7 @@ export type TextfieldProps = PrimitiveInput.Props & FieldRoot.Props & {
     fitContent?: BasicInputProps['fitContent'];
     /**
      * When `true`, root and control group take `inline-size: 100%`.
+     * Prefer this prop over CSS `width: 100%` / `w-full` on the Textfield root.
      *
      * @default false
      */

package/dist/components/title/title.css

@@ -2,4 +2,4 @@
     var(--__title-size-min),
     calc(var(--__title-size-min) + (var(--__title-size-max) - var(--__title-size-min)) * var(--__title-fluid)),
     var(--__title-size-max)
-  );--vui-title-font-family:var(--font-family-heading);--vui-title-line-height:var(--font-leading-m);--__title-letter-spacing:-0.03em;margin:0;max-inline-size:var(--vui-title-max-width);font-family:var(--vui-title-font-family);font-size:var(--vui-title-font-size);line-height:var(--vui-title-line-height);letter-spacing:var(--__title-letter-spacing);text-transform:var(--vui-title-text-transform);text-align:var(--vui-title-align);white-space:var(--vui-title-white-space);word-break:break-word;font-weight:var(--vui-title-font-weight);font-stretch:calc(var(--vui-title-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-title-font-weight),"wdth" var(--vui-title-font-width),"opsz" var(--vui-title-font-opsz);text-box:var(--vui-title-trim) var(--vui-title-trim-type);display:inline-flex;&[data-title-has-tracking=true]{letter-spacing:var(--vui-title-letter-spacing)}&[data-title-balanced=true]{text-wrap:balance}&[data-title-selection=false]{-webkit-user-select:none;user-select:none}&[data-title-has-padding=true]{padding:var(--vui-title-padding-block-start) var(--vui-title-padding-inline-end) var(--vui-title-padding-block-end) var(--vui-title-padding-inline-start)}&[data-title-size=display]{--__title-size-min:var(--font-scale-h1);--__title-size-max:var(--font-scale-display)}&[data-title-size="2"]{--__title-size-min:var(--font-scale-h3);--__title-size-max:var(--font-scale-h2)}&[data-title-size="3"]{--__title-size-min:var(--font-scale-h4);--__title-size-max:var(--font-scale-h3)}&[data-title-size="4"]{--__title-size-min:var(--font-scale-h5);--__title-size-max:var(--font-scale-h4)}&[data-title-size="5"]{--__title-size-min:var(--font-scale-h6);--__title-size-max:var(--font-scale-h5);--__title-letter-spacing:-0.02em}&[data-title-size="6"]{--__title-size-min:var(--font-scale-body-m);--__title-size-max:var(--font-scale-h6);--__title-letter-spacing:-0.02em}@container root style(--effect-fluid-typography: initial){--vui-title-font-size:var(--font-scale-h1);&[data-title-size=display]{--vui-title-font-size:var(--font-scale-display)}&[data-title-size="1"]{--vui-title-font-size:var(--font-scale-h1)}&[data-title-size="2"]{--vui-title-font-size:var(--font-scale-h2)}&[data-title-size="3"]{--vui-title-font-size:var(--font-scale-h3)}&[data-title-size="4"]{--vui-title-font-size:var(--font-scale-h4)}&[data-title-size="5"]{--vui-title-font-size:var(--font-scale-h5)}&[data-title-size="6"]{--vui-title-font-size:var(--font-scale-h6)}}&[data-title-has-literal-color=true]{color:var(--vui-title-literal-color)}&[data-title-line-height=none]{--vui-title-line-height:0}&[data-title-line-height=xs]{--vui-title-line-height:var(--font-leading-xs)}&[data-title-line-height=s]{--vui-title-line-height:var(--font-leading-s)}&[data-title-line-height=m]{--vui-title-line-height:var(--font-leading-m)}&[data-title-line-height=l]{--vui-title-line-height:var(--font-leading-l)}}}
+  );--vui-title-font-family:var(--font-family-heading);--vui-title-line-height:var(--font-leading-m);--__title-letter-spacing:-0.03em;margin:0;max-inline-size:var(--vui-title-max-width);font-family:var(--vui-title-font-family);font-size:var(--vui-title-font-size);line-height:var(--vui-title-line-height);letter-spacing:var(--__title-letter-spacing);text-transform:var(--vui-title-text-transform);text-align:var(--vui-title-align);white-space:var(--vui-title-white-space);word-break:break-word;font-weight:var(--vui-title-font-weight);font-stretch:calc(var(--vui-title-font-width) * 1%);font-optical-sizing:auto;font-variation-settings:"wght" var(--vui-title-font-weight),"wdth" var(--vui-title-font-width),"opsz" var(--vui-title-font-opsz);text-box:var(--vui-title-trim) var(--vui-title-trim-type);display:inline-flex;&[data-title-has-tracking=true]{letter-spacing:var(--vui-title-letter-spacing)}&[data-title-balanced=true]{text-wrap:balance}&[data-title-selection=false]{-webkit-user-select:none;user-select:none}&[data-title-has-padding=true]{padding:var(--vui-title-padding-block-start) var(--vui-title-padding-inline-end) var(--vui-title-padding-block-end) var(--vui-title-padding-inline-start)}&[data-title-size=display]{--__title-size-min:var(--font-scale-h1);--__title-size-max:var(--font-scale-display)}&[data-title-size="2"]{--__title-size-min:var(--font-scale-h3);--__title-size-max:var(--font-scale-h2)}&[data-title-size="3"]{--__title-size-min:var(--font-scale-h4);--__title-size-max:var(--font-scale-h3)}&[data-title-size="4"]{--__title-size-min:var(--font-scale-h5);--__title-size-max:var(--font-scale-h4)}&[data-title-size="5"]{--__title-size-min:var(--font-scale-h6);--__title-size-max:var(--font-scale-h5);--__title-letter-spacing:-0.02em}&[data-title-size="6"]{--__title-size-min:var(--font-scale-body-m);--__title-size-max:var(--font-scale-h6);--__title-letter-spacing:-0.02em}&[data-title-fluid=false]{--vui-title-font-size:var(--__title-size-max)}@container root style(--effect-fluid-typography: initial){--vui-title-font-size:var(--__title-size-max)}&[data-title-has-literal-color=true]{color:var(--vui-title-literal-color)}&[data-title-line-height=none]{--vui-title-line-height:0}&[data-title-line-height=xs]{--vui-title-line-height:var(--font-leading-xs)}&[data-title-line-height=s]{--vui-title-line-height:var(--font-leading-s)}&[data-title-line-height=m]{--vui-title-line-height:var(--font-leading-m)}&[data-title-line-height=l]{--vui-title-line-height:var(--font-leading-l)}}}

package/dist/components/title/title.d.ts

@@ -72,7 +72,8 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     whiteSpace?: React.CSSProperties['whiteSpace'];
     /**
-     * Sets letter spacing on the rendered copy.
+     * Sets letter-spacing on the rendered copy. Prefer this prop over CSS
+     * `letter-spacing` on the same Title root.
      *
      * Overrides size preset letter-spacing when set.
      *
@@ -80,7 +81,8 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     tracking?: React.CSSProperties['letterSpacing'];
     /**
-     * Applies a text-transform on the rendered copy.
+     * Applies `text-transform` on the rendered copy. Prefer this prop over CSS
+     * `text-transform` on the same Title root.
      *
      * @default No text-transform override.
      */
@@ -134,6 +136,14 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      * @default No optical size override.
      */
     opticalSize?: number;
+    /**
+     * Enables viewport fluid clamp sizing for this instance.
+     * Pass `false` to lock at this size’s `--font-scale-display` / `--font-scale-h*` token.
+     * Theme `--effect-fluid-typography: initial` still locks all Title globally.
+     *
+     * @default true
+     */
+    fluid?: boolean;
 };
 export declare const Title: React.FC<TitleProps>;
 export {};

package/dist/components/title/title.js

@@ -4,7 +4,7 @@ import { resolveAxisPadding } from "../../core/styles/resolve-axis-padding.js";
 import title_module_default from "./title.module.js";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/title/title.tsx
-var Title = ({ align = "start", balanced = false, selection = true, className, color, fontWidth, hPadding, size = "1", lineHeight = "m", maxWidth, opticalSize, ref, render, style, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight, whiteSpace = "normal", ...otherProps }) => {
+var Title = ({ align = "start", balanced = false, selection = true, className, color, fluid = true, fontWidth, hPadding, size = "1", lineHeight = "m", maxWidth, opticalSize, ref, render, style, tracking, transform, trim = "both", trimType = "cap alphabetic", vPadding, weight, whiteSpace = "normal", ...otherProps }) => {
 	const hasPadding = Boolean(hPadding || vPadding);
 	const hasTracking = tracking !== void 0;
 	const dynamicStyle = {
@@ -33,6 +33,7 @@ var Title = ({ align = "start", balanced = false, selection = true, className, c
 			"data-title-line-height": lineHeight,
 			"data-title-balanced": balanced ? "true" : "false",
 			"data-title-selection": selection ? "true" : "false",
+			"data-title-fluid": fluid ? "true" : "false",
 			"data-title-has-padding": hasPadding ? "true" : "false",
 			"data-title-has-literal-color": color ? "true" : "false",
 			"data-title-has-tracking": hasTracking ? "true" : "false",

package/dist/specs/PROTOCOL.md

@@ -28,7 +28,7 @@ Prefer opening via package export / that `dist/specs/` tree. The `version` attri
 ## Index-first (mandatory)
 
 1. Open `index.xml` (specs root) before any component or foundation unit.
-2. Use `activity-hints.xml` for activity → load sequences (`choose-component`, `implement`, `foundation-attrs`, `bootstrap`).
+2. Use `activity-hints.xml` for activity → load sequences (`choose-component`, `implement`, `compose-layout`, `foundation-attrs`, `bootstrap`).
 3. Open only the unit files named for that activity (and the chosen surface), using `href` values from the index (still under the same specs root).
 4. Do **not** parse the full tree of XML unit files. Failure to route is an index or content defect—not a reason to tree-walk or `rg` the package.
 

package/dist/specs/activity-hints.xml

@@ -23,10 +23,10 @@
     <description>Mode, vibrancy, elevation, grow/shrink hooks.</description>
     <load>
       <step open="index.xml" />
-      <step open="foundation/attributes.xml" />
-      <step open="foundation/elevation.xml" when="elevation on React or raw DOM" />
+      <step open="foundation/attributes.xml" when="always" />
+      <step open="foundation/elevation.xml" when="elevation/shadows on React or raw DOM" />
       <step open="foundation/toggles.xml" when="effects involved" />
-      <step open="foundation/modules.xml" when="debugging which preflight CSS module owns a hook" />
+      <step open="foundation/modules.xml" when="which preflight capability owns a behavior or CSS var" />
     </load>
     <forbid>Inventing data-* attributes not listed in foundation units</forbid>
   </activity>
@@ -39,4 +39,19 @@
     </load>
     <forbid>Guessing import paths or inventing provider trees</forbid>
   </activity>
+  <activity id="compose-layout">
+    <description>Page/section flex, grid, panels — prefer layout primitives and composition over custom CSS.</description>
+    <load>
+      <step open="index.xml" note="category=pattern + stack/surface/grid/masonry/bleed" />
+      <step open="patterns/compose-layout-first.xml" />
+      <step open="patterns/stack-as-surface.xml" when="border/fill/radius on a flex cluster" />
+      <step open="patterns/page-chrome.xml" when="page shell / semantic tags" />
+      <step open="patterns/equal-width-actions.xml" when="full-bleed or equal action rows" />
+      <step open="patterns/card-grid.xml" when="CSS grid tracks / card walls" />
+      <step open="patterns/settings-panel.xml" when="settings / form panels" />
+      <step unit="usage" note="confirm stack/surface/grid (etc.) do/dont after pattern" />
+      <step unit="props" note="verify spacing / render / fullWidth names" />
+    </load>
+    <forbid>Inventing display:flex / display:grid / CSS gap/padding/border chrome when Stack, Grid, Masonry, Bleed, or Surface cover it</forbid>
+  </activity>
 </activity_hints>

package/dist/specs/components/accordion/patterns.xml

@@ -1,9 +1,73 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="accordion">
-  <example title="Accordion structure">
-    <tsx><![CDATA[<Accordion>
-  <Accordion.Item trigger="…">…</Accordion.Item>
-</Accordion>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no i18n, no scroll-box style). Public parts: Accordion + Accordion.Item only. -->
+
+  <example title="Help FAQ (multiple open)">
+    <tsx><![CDATA[
+<Surface overflow="hidden" color={1} border="all" radius="l">
+  <Stack rowGap="l">
+    <Stack rowGap="l" hPadding="m" vPadding="m">
+      <Stack rowGap="xs">
+        <Title size="6" render={<h2 />}>
+          Payout Help
+        </Title>
+        <Text size="s" tone="muted">
+          Royalty deposits and tax reporting
+        </Text>
+      </Stack>
+
+      <Accordion defaultValue={['tax-docs']} multiple>
+        <Accordion.Item color={2} border="all" trigger="When do payouts arrive?" value="arrival-timing">
+          <Text tone="muted">
+            Payouts trigger when your balance crosses the minimum threshold. ACH transfers land in 2–3 business days;
+            instant payouts post within minutes for eligible accounts.
+          </Text>
+        </Accordion.Item>
+        <Accordion.Item color={2} border="all" trigger="What fees apply?" value="fees">
+          <Text tone="muted">
+            Standard ACH deposits are free. Instant payouts carry a 1.5% fee capped at $25 per transfer.
+          </Text>
+        </Accordion.Item>
+        <Accordion.Item color={2} border="all" trigger="Tax documents" value="tax-docs">
+          <Text tone="muted">
+            Annual 1099 forms publish by January 31. Download prior-year statements from Account Settings.
+          </Text>
+        </Accordion.Item>
+      </Accordion>
+    </Stack>
+
+    <Surface
+      render={<Stack direction="row" hAlign="space-between" vAlign="center" />}
+      color={2}
+      hPadding="l"
+      vPadding="m"
+    >
+      <Button variant="secondary">View all statements</Button>
+      <Button>Contact support</Button>
+    </Surface>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/payout-help`. Compose via `Accordion.Item` only — no public Header/Trigger/Panel. `multiple` + `defaultValue` from Base UI root. Item `color`/`border` forward to Surface when `useSurface` (default).</notes>
+  </example>
+
+  <example title="Sidebar advanced section">
+    <tsx><![CDATA[
+<Accordion>
+  <Accordion.Item
+    value="advanced"
+    trigger="Advanced"
+    iconClosed={<CircleWarning />}
+    iconOpen={<RouteAlert />}
+    color={1}
+    radius="m"
+  >
+    <Stack rowGap="m" vPadding="xs">
+      {/* advanced controls */}
+    </Stack>
+  </Accordion.Item>
+</Accordion>
+]]></tsx>
+    <notes>From `editor/sidebar/sidebar` advancedAccordion. Single Item with custom open/closed icons + Surface `color`/`radius`. Drop studio store / section registry chrome.</notes>
   </example>
 </patterns>

package/dist/specs/components/accordion/props.xml

@@ -39,10 +39,10 @@
   <prop name="Item.useSurface" kind="react">
     <description>When `true`, wraps the item in `Surface` (optional open-block background via `color`). When `false`, renders without `Surface` so consumers can insert `Separator` between items; island styling is skipped for that item.</description>
   </prop>
-  <css_var suffix="island-gap">
+  <prop name="island-gap" kind="css">
     <description>Gap between separated Surface islands when islands={true}.</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Corner radius for Surface island block edges when useSurface is true.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/accordion/usage.xml

@@ -1,8 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="accordion">
-  <do>Progressive disclosure for related content sections in one surface</do>
-  <do>FAQ or settings groups where only one section may be open by default</do>
-  <do>Multiple open sections when `multiple` is enabled</do>
-  <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports</dont>
+  <do>Progressive disclosure for FAQ or settings groups in one surface</do>
+  <do>Compose only via `Accordion` + `Accordion.Item` — put panel body (Text, Stack of controls, …) as Item children; pass visible label via Item `trigger`</do>
+  <do>FAQ chrome: outer Surface + Stack header (Title/Text) + Accordion; Item `color` / `border` / `radius` forward to Surface when `useSurface` (default)</do>
+  <do>Separated islands with root `islands`; attached block corners when `islands={false}`</do>
+  <do>Insert `Separator` between items when `Item` `useSurface={false}`</do>
+  <do>Multiple open sections with root `multiple` (+ `defaultValue` / `value` as needed)</do>
+  <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports — those stay inside `Accordion.Item`</dont>
   <dont>Rendering an item without trigger text and without an external aria-label strategy</dont>
+  <dont>Using Accordion for primary navigation that should be links, Tabs, or routes</dont>
 </usage>

package/dist/specs/components/annotate/patterns.xml

@@ -1,7 +1,54 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="annotate">
-  <example title="Annotate structure">
-    <tsx><![CDATA[<Annotate note="…">…</Annotate>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no giant SVG payloads, no swatch layout CSS). -->
+
+  <example title="QR callout (device pairing)">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
+  <Stack rowGap="m" expandChildren>
+    <Stack rowGap="m" vAlign="start" hPadding="l" vPadding={['2xl', 'l']} hAlign="center">
+      <Annotate color="blue" note="Scan me!" side="top-end" arrowOffsetY="25px">
+        <Surface color="var(--global-foreground)" radius="l" hPadding="m" vPadding="m">
+          {/* QR / code graphic */}
+        </Surface>
+      </Annotate>
+
+      <Stack vPadding="m" rowGap="xs" hAlign="center">
+        <Title align="center" size="6" render={<h6 />}>
+          Scan to connect your mobile device
+        </Title>
+        <Text size="s" align="center" maxWidth="20rem" tone="muted">
+          Open the Ledger mobile app and scan this code to link your device.
+        </Text>
+      </Stack>
+    </Stack>
+
+    <Button variant="secondary">Got it</Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/device-pairing`. Annotate wraps the QR Surface; `note` is decorative only. Collapse the inline SVG to a comment slot.</notes>
+  </example>
+
+  <example title="CTA nudge (empty team)">
+    <tsx><![CDATA[
+<Annotate color="green" note="start here" side="bottom-end" arrowOffsetY="-25px">
+  <Button>Invite Members</Button>
+</Annotate>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/empty-team`. Point at a primary CTA. Drop Badge toggle / onClick kitchen chrome — keep Annotate + Button.</notes>
+  </example>
+
+  <example title="Inline mark in copy">
+    <tsx><![CDATA[
+<Text size="s" tone="muted">
+  Designers love packing{' '}
+  <Annotate color="yellow" mark note="look here" side="top-end">
+    quirky glyphs
+  </Annotate>{' '}
+  into test phrases. This is a preview of the theme voice, contrast, and color rhythm.
+</Text>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/theme-preview`. `mark` highlighter behind inline phrase; note stays decorative. Drop swatch grid shell from this hint.</notes>
   </example>
 </patterns>

package/dist/specs/components/annotate/props.xml

@@ -52,37 +52,37 @@
   <prop name="zIndex" kind="react">
     <description>Stacking order for arrow and note via `--vui-annotate-z-index`. Same value on both parts.</description>
   </prop>
-  <css_var suffix="arrow-x">
+  <prop name="arrow-x" kind="css">
     <description>Horizontal arrow offset.</description>
-  </css_var>
-  <css_var suffix="arrow-y">
+  </prop>
+  <prop name="arrow-y" kind="css">
     <description>Vertical arrow offset.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Arrow, note, and mark accent color. Defaults to var(--global-foreground).</description>
-  </css_var>
-  <css_var suffix="label-gap">
+  </prop>
+  <prop name="label-gap" kind="css">
     <description>Gap between arrow and note on all sides.</description>
-  </css_var>
-  <css_var suffix="label-max-width">
+  </prop>
+  <prop name="label-max-width" kind="css">
     <description>Max width for the note part.</description>
-  </css_var>
-  <css_var suffix="rotate">
+  </prop>
+  <prop name="rotate" kind="css">
     <description>Note rotation angle.</description>
-  </css_var>
-  <css_var suffix="target-gap">
+  </prop>
+  <prop name="target-gap" kind="css">
     <description>Gap between the target and the arrow.</description>
-  </css_var>
-  <css_var suffix="text-align">
+  </prop>
+  <prop name="text-align" kind="css">
     <description>Text alignment for the note. Defaults to start.</description>
-  </css_var>
-  <css_var suffix="text-x">
+  </prop>
+  <prop name="text-x" kind="css">
     <description>Legacy horizontal note offset custom property. Prefer textOffsetX from React.</description>
-  </css_var>
-  <css_var suffix="text-y">
+  </prop>
+  <prop name="text-y" kind="css">
     <description>Legacy vertical note offset custom property. Prefer textOffsetY from React.</description>
-  </css_var>
-  <css_var suffix="z-index">
+  </prop>
+  <prop name="z-index" kind="css">
     <description>Stacking order for arrow and note. Defaults to auto.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/annotate/usage.xml

@@ -1,10 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="annotate">
-  <do>Call out a word or phrase in marketing, docs, or onboarding copy</do>
-  <do>Add a playful visual annotation without interactive chrome</do>
-  <do>Highlight a target with an optional mark while keeping children as the real content</do>
-  <dont>Using note as the only source of instructions or status</dont>
-  <dont>Nesting Annotate inside overflow-hidden parents without padding for the arrow</dont>
+  <do>Wrap a Button CTA, a Surface graphic (QR / icon tile), or an inline phrase inside Text/Title — children stay the real content</do>
+  <do>Compose onboarding / empty-state callouts inside Stack + Surface shells with Title/Text/Button for the labeled instructions</do>
+  <do>Add optional `mark` highlighter behind the wrapped phrase while keeping `note` decorative</do>
+  <dont>Putting critical instructions or status only in `note` — assistive tech does not announce it; put that copy in Text/Title/Button</dont>
+  <dont>Using Annotate instead of Tooltip/Popover when focus, hover, or keyboard behavior is required</dont>
+  <dont>Nesting Annotate inside `overflow: hidden` parents without room for the arrow and label</dont>
+  <dont>Adding `position: relative` on Annotate — it breaks CSS anchor `position-area` placement</dont>
   <dont>Expecting the label to participate in hit-testing or selection</dont>
-  <dont>Adding position:relative on Annotate — it breaks CSS anchor position-area placement</dont>
 </usage>