@viraui/react 2026.5.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/avatar/avatar.js

@@ -9,7 +9,7 @@ var fallbackTextSizeByAvatarSize = {
 	xs: "xs",
 	s: "xs",
 	m: "s",
-	l: "l"
+	l: "2xl"
 };
 var Avatar$1 = ({ alt = "", className, fallback, ref, size = "s", src, ...otherProps }) => {
 	const hasImage = Boolean(src);

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=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=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

@@ -25,11 +25,12 @@ export type TextProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     ref?: React.Ref<HTMLElement>;
     /**
-     * Selects a semantic body typography size from the active theme scale.
+     * Selects a semantic body typography size from the active theme scale
+     * (`4xl` | `3xl` | `2xl` | `xl` | `l` | `m` | `s` | `xs`).
      *
      * @default 'm'
      */
-    size?: 'xl' | 'l' | 'm' | 's' | 'xs';
+    size?: '4xl' | '3xl' | '2xl' | 'xl' | 'l' | 'm' | 's' | 'xs';
     /**
      * Selects the semantic font family for body copy and inline code-like text.
      *
@@ -52,7 +53,7 @@ export type TextProps = React.ComponentPropsWithoutRef<'span'> & {
      */
     tone?: 'default' | 'primary' | 'muted' | 'interactive' | 'positive' | 'informative' | 'danger' | 'warning';
     /**
-     * Applies a literal color escape hatch when semantic `tone` is not used.
+     * Applies a custom color as an escape hatch when semantic `tone` is not used.
      *
      * @default No literal color override.
      */
@@ -82,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.
      */
@@ -142,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/preflight.css

@@ -1 +1,4 @@
-@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.preflight{@property --scrollbar-thumb{syntax:"<color>";initial-value:#0000;inherits:true}@property --scrollbar-track{syntax:"<color>";initial-value:#0000;inherits:true}@property --outline-offset{syntax:"<length>";initial-value:2px;inherits:true}@property --outline-color{syntax:"<color>";initial-value:currentcolor;inherits:true}@property --outline{syntax:"*";initial-value:2px solid currentcolor;inherits:true}@property --is-light-mode{syntax:"<color>";initial-value:#000;inherits:true}@property --vira-flex-grow{syntax:"<number>";initial-value:1;inherits:false}@property --vira-flex-shrink{syntax:"<number>";initial-value:1;inherits:false}@property --__corner-shape{syntax:"*";inherits:false}}@layer viraui.preflight{:root{--font-scale-body-xs:0.75rem;--font-scale-body-s:0.875rem;--font-scale-body-m:1rem;--font-scale-body-l:round(down, calc(1rem * pow(var(--font-body-typescale), 3)), 1px);--font-scale-body-xl:round(down, calc(1rem * pow(var(--font-body-typescale), 5)), 1px);--font-scale-h6:round(down, calc(1rem * pow(var(--font-heading-typescale), 1)), 1px);--font-scale-h5:round(down, calc(1rem * pow(var(--font-heading-typescale), 2)), 1px);--font-scale-h4:round(down, calc(1rem * pow(var(--font-heading-typescale), 3)), 1px);--font-scale-h3:round(down, calc(1rem * pow(var(--font-heading-typescale), 4)), 1px);--font-scale-h2:round(down, calc(1rem * pow(var(--font-heading-typescale), 5)), 1px);--font-scale-h1:round(down, calc(1rem * pow(var(--font-heading-typescale), 6)), 1px);--font-scale-display:round(down, calc(1rem * pow(var(--font-heading-typescale), 8)), 1px)}}@layer viraui.preflight{html{--scrollbar-thumb:oklab(from var(--global-contrast) l a b / 0.3);--scrollbar-track:#0000;--outline-offset:2px;--outline-color:var(--global-outline);--outline:2px solid var(--outline-color);--is-light-mode:contrast-color(var(--global-background));font-size:var(--font-root-size);box-sizing:border-box;line-height:1.5;background-color:var(--global-background);color:var(--global-foreground);container:root/normal;scroll-behavior:smooth;@media (prefers-reduced-motion:reduce){scroll-behavior:auto}}*,:after,:before{margin:0;box-sizing:inherit;scrollbar-width:thin;scrollbar-color:var(--scrollbar-thumb) var(--scrollbar-track);@container root not style(--effect-corner-shape: initial){corner-shape:var(--__corner-shape,var(--corner-shape))}@media (prefers-reduced-motion:reduce){animation:none!important;transition:none!important}}:focus-visible{outline:var(--outline);outline-offset:var(--outline-offset)}body{color:var(--global-foreground);margin:0;font-size:var(--font-scale-body-m);font-optical-sizing:auto;font-family:var(--font-family-body),system-ui,sans-serif;font-variation-settings:"wght" 400;font-variant-numeric:tabular-nums;@container root not style(--effect-holofoil: initial){&:after{content:"";position:fixed;inset:0;z-index:999;background-color:#99ffd8;pointer-events:none;mix-blend-mode:multiply;contain:strict;isolation:isolate;opacity:25%;background-image:radial-gradient(at 79% 56%,#70ade6 0,#0000 50%),radial-gradient(at 61% 80%,#ee909e 0,#0000 50%),radial-gradient(at 0 63%,#fdbc68 0,#0000 50%),radial-gradient(at 6% 50%,#e5cb8a 0,#0000 50%),radial-gradient(at 23% 10%,#e5db8f 0,#0000 50%),radial-gradient(at 36% 91%,#a0eea8 0,#0000 50%),radial-gradient(at 2% 80%,#e3a47d 0,#0000 50%);@container root style(--is-light-mode: white){mix-blend-mode:color;opacity:15%}}}}::selection{background-color:var(--global-primary);color:contrast-color(var(--global-primary));text-shadow:none}img{display:block;inline-size:100%;max-inline-size:100%}svg{display:inline-flex;vertical-align:middle;&:not([fill]){fill:currentcolor}}ol ul,ul ol{font-size:medium}table{border-spacing:0;inline-size:100%;border-collapse:collapse}table[data-layout-fixed]{table-layout:fixed}table thead{box-shadow:inset 0 -3px 0 var(--base-2)}table[data-table-separators] tr+tr{border-top:1px solid var(--base-2)}table th{white-space:nowrap;font-variation-settings:"wght" 800}table :is(td,th){border:none;text-align:left;font-size:medium;padding:calc(var(--space-xs) + var(--space-2xs)) var(--space-s)}button,fieldset{padding:0;margin:0;border:0}button{appearance:none;background:none;font-size:inherit;font-family:inherit;display:inline-flex;cursor:pointer;color:inherit}}@layer viraui.preflight{@container root not style(--effect-shadows: initial){[data-elevation]{--shadow-direction:1;--shadow-opacity-factor:0.16;--extra-shadow:0 0 0 1px #0000;--shadow-color:oklch(0% 0 0);transition-property:box-shadow;transition-duration:var(--elevation-transition-duration,.16s);transition-timing-function:var(--elevation-transition-easing,ease)}[data-elevation]:where([data-elevation-direction=bottom],[data-elevation-direction=right]){--shadow-direction:1}[data-elevation]:where([data-elevation-direction=top],[data-elevation-direction=left]){--shadow-direction:-1}[data-elevation-hover="0"]:hover,[data-elevation="0"]{--y1:0px;--x1:0px;box-shadow:calc(var(--x1) * var(--shadow-direction)) calc(var(--y1) * var(--shadow-direction)) 0 oklch(from var(--shadow-color) l c h/var(--shadow-opacity-factor)),0 0 0 color-mix(in oklch,var(--shadow-color),#0000 calc(94% - var(--shadow-opacity-factor))),0 0 0 oklch(from var(--shadow-color) l c h/var(--shadow-opacity-factor)),var(--extra-shadow)}[data-elevation-hover="1"]:hover,[data-elevation-hover="2"]:hover,[data-elevation-hover="3"]:hover,[data-elevation-hover="4"]:hover,[data-elevation="1"],[data-elevation="2"],[data-elevation="3"],[data-elevation="4"]{box-shadow:calc(var(--x1) * var(--shadow-direction)) calc(var(--y1) * var(--shadow-direction)) var(--shadow-blur-1) oklab(from var(--shadow-color) l a b/.1),calc(var(--x2) * var(--shadow-direction)) calc(var(--y2) * var(--shadow-direction)) var(--shadow-blur-2) oklab(from var(--shadow-color) l a b/.08),calc(var(--x3) * var(--shadow-direction)) calc(var(--y3) * var(--shadow-direction)) var(--shadow-blur-3) oklab(from var(--shadow-color) l a b/.06),calc(var(--x4) * var(--shadow-direction)) calc(var(--y4) * var(--shadow-direction)) var(--shadow-blur-4) oklab(from var(--shadow-color) l a b/.04),calc(var(--x5) * var(--shadow-direction)) calc(var(--y5) * var(--shadow-direction)) var(--shadow-blur-5) oklab(from var(--shadow-color) l a b/.02),var(--extra-shadow)}[data-elevation-hover="1"]:hover,[data-elevation="1"]{--y1:0px;--y2:1px;--y3:1px;--y4:3px;--y5:4px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:0px;--shadow-blur-2:1px;--shadow-blur-3:1px;--shadow-blur-4:3px;--shadow-blur-5:4px}[data-elevation-hover="1"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="1"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:0px;--x2:1px;--x3:1px;--x4:3px;--x5:4px}[data-elevation-hover="2"]:hover,[data-elevation="2"]{--y1:0px;--y2:1px;--y3:3px;--y4:5px;--y5:8px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:0px;--shadow-blur-2:1px;--shadow-blur-3:3px;--shadow-blur-4:5px;--shadow-blur-5:8px}[data-elevation-hover="2"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="2"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:0px;--x2:1px;--x3:3px;--x4:5px;--x5:8px}[data-elevation-hover="3"]:hover,[data-elevation="3"]{--y1:1px;--y2:3px;--y3:6px;--y4:10px;--y5:16px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:1px;--shadow-blur-2:3px;--shadow-blur-3:6px;--shadow-blur-4:10px;--shadow-blur-5:16px}[data-elevation-hover="3"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="3"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:1px;--x2:3px;--x3:6px;--x4:10px;--x5:16px}[data-elevation-hover="4"]:hover,[data-elevation="4"]{--y1:1px;--y2:5px;--y3:12px;--y4:20px;--y5:32px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:1px;--shadow-blur-2:5px;--shadow-blur-3:12px;--shadow-blur-4:20px;--shadow-blur-5:32px}[data-elevation-hover="4"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="4"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:1px;--x2:5px;--x3:12px;--x4:20px;--x5:32px}}}@layer viraui.preflight{[data-grow=true]{--vira-flex-grow:1;flex-grow:1}[data-grow=false]{--vira-flex-grow:0;flex-grow:0}[data-shrink=true]{--vira-flex-shrink:1;flex-shrink:1}[data-shrink=false]{--vira-flex-shrink:0;flex-shrink:0}}@layer viraui.preflight{:where(p){line-height:1.5;min-block-size:.01vh;font-size:var(--font-scale-body-m)}small{font-size:.7em}b,strong{font-variation-settings:"wght" 700}:where(a:any-link):not([data-no-link-style]){text-decoration:none;color:var(--global-interactive-text);word-break:break-word;&:not([class]){background:linear-gradient(currentcolor,currentcolor) no-repeat 0 100%;background-size:0 1px;transition:background-size var(--duration-fast) var(--easing-entrance);&:focus,&:hover{background-size:100% 1px}}}del{padding:0 .4em;margin:0 .2em;background-color:oklab(from var(--highlight-red) l a b/12%);color:var(--highlight-red);box-shadow:0 0 0 1px oklab(from var(--highlight-red) l a b/50%);border-radius:var(--radius-s)}ins{background-color:oklab(from var(--highlight-green) l a b/15%);color:var(--highlight-green);box-shadow:0 0 0 1px oklab(from var(--highlight-green) l a b/50%)}ins,mark{padding:0 .4em;margin:0 .2em;text-decoration:none;border-radius:var(--radius-s)}mark{background-color:oklab(from var(--highlight-yellow) l a b/15%);color:var(--highlight-yellow);box-shadow:0 0 0 1px oklab(from var(--highlight-yellow) l a b/50%)}address{font-style:normal;line-height:inherit}dt{font-variation-settings:"wght" 600}dd{margin:0;padding:0}ul{font-size:medium;padding-left:1rem;& li::marker{font-size:inherit;text-align:right;font-variation-settings:"wght" 400;min-inline-size:var(--space-xl);color:oklab(from currentColor l a b/80%)}}ol{font-size:medium;& li::marker{font-size:inherit;font-variation-settings:"wght" 400;min-inline-size:var(--space-xl);font-variant-numeric:tabular-nums;white-space:nowrap;color:oklab(from currentColor l a b/80%)}}kbd{padding:.2em .4em;border-radius:var(--radius-s);font-variation-settings:"wght" 600;box-shadow:var(--global-contrast);background:var(--global-contrast)}abbr{text-decoration:underline dashed var(--global-primary)}label,legend{font-size:inherit}code{font-size:1em;font-family:var(--font-family-mono);&:not(:where(pre &)){background-color:var(--global-contrast);border-radius:var(--radius-s);box-shadow:var(--global-contrast);padding:.2em .4em}}pre code{box-shadow:none}s{text-decoration:line-through;color:var(--global-disabled-foreground);text-decoration-color:oklab(from var(--global-foreground) l a b/50%)}:root{color-scheme:light dark}[data-mode=dark]{--is-light-mode:#fff;color:var(--global-foreground);color-scheme:dark}[data-mode=light]{--is-light-mode:#000;color:var(--global-foreground);color-scheme:light}}@layer viraui.preflight{[data-mode=inverted]{color:var(--global-foreground);@container root style(--is-light-mode: black){color-scheme:dark}@container root style(--is-light-mode: white){color-scheme:light}}}@layer viraui.preflight{@container root not style(--effect-vibrancy: initial){[data-vibrant]{backdrop-filter:brightness(var(--vibrancy-brightness)) blur(calc(var(--vibrancy-blur) * 1px)) saturate(150%);@container root style(--is-light-mode: black){backdrop-filter:brightness(100%) blur(calc(var(--vibrancy-blur) * 1px)) saturate(150%)}}}}
+@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.preflight{@property --scrollbar-thumb{syntax:"<color>";initial-value:#0000;inherits:true}@property --scrollbar-track{syntax:"<color>";initial-value:#0000;inherits:true}@property --outline-offset{syntax:"<length>";initial-value:2px;inherits:true}@property --outline-color{syntax:"<color>";initial-value:currentcolor;inherits:true}@property --outline{syntax:"*";initial-value:2px solid currentcolor;inherits:true}@property --is-light-mode{syntax:"<color>";initial-value:#000;inherits:true}@property --vira-flex-grow{syntax:"<number>";initial-value:1;inherits:false}@property --vira-flex-shrink{syntax:"<number>";initial-value:1;inherits:false}@property --__corner-shape{syntax:"*";inherits:false}}@layer viraui.preflight{:root{--font-scale-body-m:1rem;--font-scale-body-s:min(1rem, max(0.875rem, round(down, calc(1rem / pow(var(--font-body-typescale), 1)), 1px)));--font-scale-body-xs:min(
+      var(--font-scale-body-s),
+      max(0.75rem, round(down, calc(1rem / pow(var(--font-body-typescale), 2)), 1px))
+    );--font-scale-body-l:round(down, calc(1rem * pow(var(--font-body-typescale), 1)), 1px);--font-scale-body-xl:round(down, calc(1rem * pow(var(--font-body-typescale), 2)), 1px);--font-scale-body-2xl:round(down, calc(1rem * pow(var(--font-body-typescale), 3)), 1px);--font-scale-body-3xl:round(down, calc(1rem * pow(var(--font-body-typescale), 4)), 1px);--font-scale-body-4xl:round(down, calc(1rem * pow(var(--font-body-typescale), 5)), 1px);--font-scale-h6:round(down, calc(1rem * pow(var(--font-heading-typescale), 1)), 1px);--font-scale-h5:round(down, calc(1rem * pow(var(--font-heading-typescale), 2)), 1px);--font-scale-h4:round(down, calc(1rem * pow(var(--font-heading-typescale), 3)), 1px);--font-scale-h3:round(down, calc(1rem * pow(var(--font-heading-typescale), 4)), 1px);--font-scale-h2:round(down, calc(1rem * pow(var(--font-heading-typescale), 5)), 1px);--font-scale-h1:round(down, calc(1rem * pow(var(--font-heading-typescale), 6)), 1px);--font-scale-display:round(down, calc(1rem * pow(var(--font-heading-typescale), 8)), 1px)}}@layer viraui.preflight{html{--scrollbar-thumb:oklab(from var(--global-contrast) l a b / 0.3);--scrollbar-track:#0000;--outline-offset:2px;--outline-color:var(--global-outline);--outline:2px solid var(--outline-color);--is-light-mode:contrast-color(var(--global-background));font-size:var(--font-root-size);box-sizing:border-box;line-height:1.5;background-color:var(--global-background);color:var(--global-foreground);container:root/normal;scroll-behavior:smooth;@media (prefers-reduced-motion:reduce){scroll-behavior:auto}}*,:after,:before{margin:0;box-sizing:inherit;scrollbar-width:thin;scrollbar-color:var(--scrollbar-thumb) var(--scrollbar-track);@container root not style(--effect-corner-shape: initial){corner-shape:var(--__corner-shape,var(--corner-shape))}@media (prefers-reduced-motion:reduce){animation:none!important;transition:none!important}}:focus-visible{outline:var(--outline);outline-offset:var(--outline-offset)}body{color:var(--global-foreground);margin:0;font-size:var(--font-scale-body-m);font-optical-sizing:auto;font-family:var(--font-family-body),system-ui,sans-serif;font-variation-settings:"wght" 400;font-variant-numeric:tabular-nums;@container root not style(--effect-holofoil: initial){&:after{content:"";position:fixed;inset:0;z-index:999;background-color:#99ffd8;pointer-events:none;mix-blend-mode:multiply;contain:strict;isolation:isolate;opacity:25%;background-image:radial-gradient(at 79% 56%,#70ade6 0,#0000 50%),radial-gradient(at 61% 80%,#ee909e 0,#0000 50%),radial-gradient(at 0 63%,#fdbc68 0,#0000 50%),radial-gradient(at 6% 50%,#e5cb8a 0,#0000 50%),radial-gradient(at 23% 10%,#e5db8f 0,#0000 50%),radial-gradient(at 36% 91%,#a0eea8 0,#0000 50%),radial-gradient(at 2% 80%,#e3a47d 0,#0000 50%);@container root style(--is-light-mode: white){mix-blend-mode:color;opacity:15%}}}}::selection{background-color:var(--global-primary);color:contrast-color(var(--global-primary));text-shadow:none}img{display:block;inline-size:100%;max-inline-size:100%}svg{display:inline-flex;vertical-align:middle;&:not([fill]){fill:currentcolor}}ol ul,ul ol{font-size:medium}table{border-spacing:0;inline-size:100%;border-collapse:collapse}table[data-layout-fixed]{table-layout:fixed}table thead{box-shadow:inset 0 -3px 0 var(--base-2)}table[data-table-separators] tr+tr{border-top:1px solid var(--base-2)}table th{white-space:nowrap;font-variation-settings:"wght" 800}table :is(td,th){border:none;text-align:left;font-size:medium;padding:calc(var(--space-xs) + var(--space-2xs)) var(--space-s)}button,fieldset{padding:0;margin:0;border:0}button{appearance:none;background:none;font-size:inherit;font-family:inherit;display:inline-flex;cursor:pointer;color:inherit}}@layer viraui.preflight{@container root not style(--effect-shadows: initial){[data-elevation]{--shadow-direction:1;--shadow-opacity-factor:0.16;--extra-shadow:0 0 0 1px #0000;--shadow-color:oklch(0% 0 0);transition-property:box-shadow;transition-duration:var(--elevation-transition-duration,.16s);transition-timing-function:var(--elevation-transition-easing,ease)}[data-elevation]:where([data-elevation-direction=bottom],[data-elevation-direction=right]){--shadow-direction:1}[data-elevation]:where([data-elevation-direction=top],[data-elevation-direction=left]){--shadow-direction:-1}[data-elevation-hover="0"]:hover,[data-elevation="0"]{--y1:0px;--x1:0px;box-shadow:calc(var(--x1) * var(--shadow-direction)) calc(var(--y1) * var(--shadow-direction)) 0 oklch(from var(--shadow-color) l c h/var(--shadow-opacity-factor)),0 0 0 color-mix(in oklch,var(--shadow-color),#0000 calc(94% - var(--shadow-opacity-factor))),0 0 0 oklch(from var(--shadow-color) l c h/var(--shadow-opacity-factor)),var(--extra-shadow)}[data-elevation-hover="1"]:hover,[data-elevation-hover="2"]:hover,[data-elevation-hover="3"]:hover,[data-elevation-hover="4"]:hover,[data-elevation="1"],[data-elevation="2"],[data-elevation="3"],[data-elevation="4"]{box-shadow:calc(var(--x1) * var(--shadow-direction)) calc(var(--y1) * var(--shadow-direction)) var(--shadow-blur-1) oklab(from var(--shadow-color) l a b/.1),calc(var(--x2) * var(--shadow-direction)) calc(var(--y2) * var(--shadow-direction)) var(--shadow-blur-2) oklab(from var(--shadow-color) l a b/.08),calc(var(--x3) * var(--shadow-direction)) calc(var(--y3) * var(--shadow-direction)) var(--shadow-blur-3) oklab(from var(--shadow-color) l a b/.06),calc(var(--x4) * var(--shadow-direction)) calc(var(--y4) * var(--shadow-direction)) var(--shadow-blur-4) oklab(from var(--shadow-color) l a b/.04),calc(var(--x5) * var(--shadow-direction)) calc(var(--y5) * var(--shadow-direction)) var(--shadow-blur-5) oklab(from var(--shadow-color) l a b/.02),var(--extra-shadow)}[data-elevation-hover="1"]:hover,[data-elevation="1"]{--y1:0px;--y2:1px;--y3:1px;--y4:3px;--y5:4px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:0px;--shadow-blur-2:1px;--shadow-blur-3:1px;--shadow-blur-4:3px;--shadow-blur-5:4px}[data-elevation-hover="1"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="1"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:0px;--x2:1px;--x3:1px;--x4:3px;--x5:4px}[data-elevation-hover="2"]:hover,[data-elevation="2"]{--y1:0px;--y2:1px;--y3:3px;--y4:5px;--y5:8px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:0px;--shadow-blur-2:1px;--shadow-blur-3:3px;--shadow-blur-4:5px;--shadow-blur-5:8px}[data-elevation-hover="2"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="2"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:0px;--x2:1px;--x3:3px;--x4:5px;--x5:8px}[data-elevation-hover="3"]:hover,[data-elevation="3"]{--y1:1px;--y2:3px;--y3:6px;--y4:10px;--y5:16px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:1px;--shadow-blur-2:3px;--shadow-blur-3:6px;--shadow-blur-4:10px;--shadow-blur-5:16px}[data-elevation-hover="3"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="3"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:1px;--x2:3px;--x3:6px;--x4:10px;--x5:16px}[data-elevation-hover="4"]:hover,[data-elevation="4"]{--y1:1px;--y2:5px;--y3:12px;--y4:20px;--y5:32px;--x1:0px;--x2:0px;--x3:0px;--x4:0px;--x5:0px;--shadow-blur-1:1px;--shadow-blur-2:5px;--shadow-blur-3:12px;--shadow-blur-4:20px;--shadow-blur-5:32px}[data-elevation-hover="4"]:where([data-elevation-direction=left],[data-elevation-direction=right]):hover,[data-elevation="4"]:where([data-elevation-direction=left],[data-elevation-direction=right]){--y1:0px;--y2:0px;--y3:0px;--y4:0px;--y5:0px;--x1:1px;--x2:5px;--x3:12px;--x4:20px;--x5:32px}}}@layer viraui.preflight{[data-grow=true]{--vira-flex-grow:1;flex-grow:1}[data-grow=false]{--vira-flex-grow:0;flex-grow:0}[data-shrink=true]{--vira-flex-shrink:1;flex-shrink:1}[data-shrink=false]{--vira-flex-shrink:0;flex-shrink:0}}@layer viraui.preflight{:where(p){line-height:1.5;min-block-size:.01vh;font-size:var(--font-scale-body-m)}small{font-size:.7em}b,strong{font-variation-settings:"wght" 700}:where(a:any-link):not([data-no-link-style]){text-decoration:none;color:var(--global-interactive-text);word-break:break-word;&:not([class]){background:linear-gradient(currentcolor,currentcolor) no-repeat 0 100%;background-size:0 1px;transition:background-size var(--duration-fast) var(--easing-entrance);&:focus,&:hover{background-size:100% 1px}}}del{padding:0 .4em;margin:0 .2em;background-color:oklab(from var(--highlight-red) l a b/12%);color:var(--highlight-red);box-shadow:0 0 0 1px oklab(from var(--highlight-red) l a b/50%);border-radius:var(--radius-s)}ins{background-color:oklab(from var(--highlight-green) l a b/15%);color:var(--highlight-green);box-shadow:0 0 0 1px oklab(from var(--highlight-green) l a b/50%)}ins,mark{padding:0 .4em;margin:0 .2em;text-decoration:none;border-radius:var(--radius-s)}mark{background-color:oklab(from var(--highlight-yellow) l a b/15%);color:var(--highlight-yellow);box-shadow:0 0 0 1px oklab(from var(--highlight-yellow) l a b/50%)}address{font-style:normal;line-height:inherit}dt{font-variation-settings:"wght" 600}dd{margin:0;padding:0}ul{font-size:medium;padding-left:1rem;& li::marker{font-size:inherit;text-align:right;font-variation-settings:"wght" 400;min-inline-size:var(--space-xl);color:oklab(from currentColor l a b/80%)}}ol{font-size:medium;& li::marker{font-size:inherit;font-variation-settings:"wght" 400;min-inline-size:var(--space-xl);font-variant-numeric:tabular-nums;white-space:nowrap;color:oklab(from currentColor l a b/80%)}}kbd{padding:.2em .4em;border-radius:var(--radius-s);font-variation-settings:"wght" 600;box-shadow:var(--global-contrast);background:var(--global-contrast)}abbr{text-decoration:underline dashed var(--global-primary)}label,legend{font-size:inherit}code{font-size:1em;font-family:var(--font-family-mono);&:not(:where(pre &)){background-color:var(--global-contrast);border-radius:var(--radius-s);box-shadow:var(--global-contrast);padding:.2em .4em}}pre code{box-shadow:none}s{text-decoration:line-through;color:var(--global-disabled-foreground);text-decoration-color:oklab(from var(--global-foreground) l a b/50%)}:root{color-scheme:light dark}[data-mode=dark]{--is-light-mode:#fff;color:var(--global-foreground);color-scheme:dark}[data-mode=light]{--is-light-mode:#000;color:var(--global-foreground);color-scheme:light}}@layer viraui.preflight{[data-mode=inverted]{color:var(--global-foreground);@container root style(--is-light-mode: black){color-scheme:dark}@container root style(--is-light-mode: white){color-scheme:light}}}@layer viraui.preflight{@container root not style(--effect-vibrancy: initial){[data-vibrant]{backdrop-filter:brightness(var(--vibrancy-brightness)) blur(calc(var(--vibrancy-blur) * 1px)) saturate(150%);@container root style(--is-light-mode: black){backdrop-filter:brightness(100%) blur(calc(var(--vibrancy-blur) * 1px)) saturate(150%)}}}}

package/dist/specs/PROTOCOL.md

@@ -1,29 +1,21 @@
 # ViraUI package specs protocol
 
 **Package:** `@viraui/react` agent documentation  
-**Authority after cutover:** navigation index + scoped XML units only. `*.guide.json` is **not** agent API authority.
+**Authority:** navigation index + scoped XML units only. `*.guide.json` is **not** agent API authority.
 
-## Index-first (mandatory)
+## Resolve from the installed package (mandatory)
 
-1. Open `index.xml` before any component or foundation unit.
-2. Use `activity-hints.xml` for activity → load sequences (`choose-component`, `implement`, `foundation-attrs`).
-3. Open only the unit files named for that activity (and the chosen surface).
-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.
+Consumer agents **MUST** read specs from the **installed** `@viraui/react` version — Node package resolution / `node_modules` — co-versioned with the code in use.
 
-## Authority order
+Do **not** search the consumer app tree, monorepo checkouts, or skills corpora for `index.xml` / unit files. Do **not** open ViraUI source under another clone unless that clone **is** the package under edit.
 
-1. **Package specs units** for the installed version (`meta`, `props`, `usage`, `a11y`, `patterns`, foundation) — intent, Vira-added props, anti-patterns, public CSS hooks.
-2. Installed package **types / source** — verify accepted props, inherited pass-through, and defaults **after** reading units. Never use types as first discovery.
-3. Examples / stories — examples only; never API authority.
-4. Skills prose — routers and playbooks only; never a second encyclopedia of component API facts.
-
-## Co-versioned resolution
-
-Resolve docs from the **installed** `@viraui/react` package (Node resolution / `node_modules`), not from a newer skills corpus or another checkout. The `version` attribute on `index.xml` must match the installed package version.
+Package exports: `@viraui/react/specs/*`.
 
 ### Filesystem recipe (Read tool)
 
-Prefer package subpaths; on disk under the install they map to:
+Bare names below (`index.xml`, `activity-hints.xml`, `foundation/…`, `components/<id>/…`) are **paths under the published specs root**, not repo-root paths.
+
+On disk under a typical install:
 
 - `node_modules/@viraui/react/dist/specs/PROTOCOL.md`
 - `node_modules/@viraui/react/dist/specs/index.xml`
@@ -31,7 +23,21 @@ Prefer package subpaths; on disk under the install they map to:
 - `node_modules/@viraui/react/dist/specs/components/<id>/*.xml`
 - `node_modules/@viraui/react/dist/specs/foundation/*.xml`
 
-Package exports: `@viraui/react/specs/*`.
+Prefer opening via package export / that `dist/specs/` tree. The `version` attribute on `index.xml` must match the installed package version.
+
+## 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`, `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.
+
+## Authority order
+
+1. **Package specs units** for the installed version (`meta`, `props`, `usage`, `a11y`, `patterns`, foundation) — intent, Vira-added props, anti-patterns, public CSS hooks.
+2. Installed package **types / source** — verify accepted props, inherited pass-through, and defaults **after** reading units. Never use types as first discovery.
+3. Examples / stories — examples only; never API authority.
+4. Skills prose — routers and playbooks only; never a second encyclopedia of component API facts.
 
 ## Forbidden discovery
 
@@ -41,8 +47,6 @@ Do **not** `ls` / `rg` / `grep` `dist/components/**` or `*.d.ts` to discover Vir
 
 `catalog.json` is a small tooling index of public components. Narrative discovery uses the specs index + units—not skill encyclopedias or legacy surface JSON.
 
-**Core / preflight units** are hand-authored under `packages/react/src/core/specs/` and published as `specs/foundation/*` (bootstrap, attributes, toggles, theme-topics, elevation, modules).
-
 ## Defects
 
 Missing index entry, broken `href`, or empty high-traffic units → fix the package docs. Do not invent props or load every `props.xml`.

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>