@viraui/react 2026.7.1 → 2026.9.0

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

@@ -49,6 +49,8 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
     color?: string;
     /**
      * Controls line height through foundation leading tokens.
+     * Default `m`; prefer `s` on large wrapping titles and always inside Prose.
+     * Prefer this prop over CSS `line-height`.
      *
      * @defaultValue 'm'
      */
@@ -62,6 +64,9 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
     align?: React.CSSProperties['textAlign'];
     /**
      * Constrains the maximum inline size of the rendered text block.
+     * Prefer for readable wrapping titles (~10–12 words/line) over CSS `max-width`.
+     * Prefer `ch` (not `rem`) in patterns/examples. Width tracks `size` — smaller presets → narrower cap;
+     * never one fixed measure for every size. Shared columns may use parent Stack `maxWidth` instead.
      *
      * @defaultValue No max width constraint.
      */
@@ -90,6 +95,8 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
     transform?: React.CSSProperties['textTransform'];
     /**
      * Enables balanced wrapping for block-like titles.
+     * Prefer on short wrapping heads (hero, empty state, section);
+     * omit for single-line / `whiteSpace="nowrap"` metrics.
      *
      * @defaultValue false
      */

package/dist/index.js

@@ -24,6 +24,7 @@ import { DialogIndentBackground } from "./components/dialog/dialog-indent-backgr
 import { DialogSheet } from "./components/dialog/dialog-sheet.js";
 import { DialogTrigger } from "./components/dialog/dialog-trigger.js";
 import { Dialog } from "./components/dialog/dialog.js";
+import { DirectionProvider, useDirection } from "./components/direction-provider/index.js";
 import { Disclosure } from "./components/disclosure/disclosure.js";
 import { ELEVATION_DEFAULTS } from "./core/elevation/elevation-types.js";
 import { getElevationProps } from "./core/elevation/get-elevation-props.js";
@@ -72,4 +73,4 @@ import { ToggleGroup } from "./components/toggle-group/toggle-group.js";
 import { Typewriter } from "./components/typewriter/typewriter.js";
 import { TooltipContent } from "./components/tooltip/tooltip-content.js";
 import { Tooltip, TooltipProvider, TooltipTrigger } from "./components/tooltip/tooltip.js";
-export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, Disclosure, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, NumberField, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints };
+export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, DirectionProvider, Disclosure, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, NumberField, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints, useDirection };

package/dist/preflight.css

@@ -1,4 +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-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}}::-webkit-scrollbar-track{background-color:var(--scrollbar-track)}: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;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%)}}}}
+    );--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}}::-webkit-scrollbar-track{background-color:var(--scrollbar-track)}: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;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=true]{backdrop-filter:blur(calc(var(--vibrancy-blur) * 1px)) saturate(150%)}}}

package/dist/specs/PROTOCOL.md

@@ -44,7 +44,7 @@ Prefer opening via package export / that `dist/specs/` tree. The `version` attri
 Consumer agents build screens **with** ViraUI — public parts, compounds, and props from the units — not **around** it with immediate CSS overrides.
 
 1. Index → activity load → open `meta` / `props` / `usage` for every Vira surface you touch **before** JSX that invents classNames or a CSS module targeting those roots.
-2. Prefer another Vira part or public prop over custom CSS (layout → `Stack`/`Grid`/`Masonry`/`Bleed`/`Surface`; fill → `fullWidth` / `expandChildren`; one-sided inset → `hPadding`/`vPadding` `[start, end]` tuples — not `paddingBlock*`/`paddingInline*` style; type → `Text`/`Title` props; chrome → `Surface` / `Elevator`).
+2. Prefer another Vira part or public prop over custom CSS (layout → `Stack`/`Grid`/`Masonry`/`Bleed`/`Surface`; fill → `fullWidth` / `fullHeight` / `expandChildren` + stretch align — open Stack `patterns.xml` / `usage` when children must fill both axes; never invent `width`/`height: 100%` CSS; one-sided inset → `hPadding`/`vPadding` `[start, end]` tuples — not `paddingBlock*`/`paddingInline*` style; type → `Text`/`Title` props; chrome → `Surface` / `Elevator` or Stack `render={<Surface />}`).
 3. **Omit `render` when it restates the component’s default root.** Confirm the default in that surface’s `props`/`usage` (e.g. Stack → `div`). Do **not** write `render={<div />}` on Stack, or any other `render={<SameDefault />}` noop. Use `render` only to change the host (semantic tag, `Surface`, another component).
 4. Custom CSS defaults to **app chrome the system does not own** (page backdrop image, document scrollport, one-off marketing layout). It is **not** a license to reshape Vira control geometry, reinvent owned props, or “fix” controls that already look correct under theme + preflight — **unless the consumer expressly requests** that override / personalization. A future override layer will own formal customization hooks; until then, still open `props`/`usage` first and apply only the asked CSS.
 5. If `usage.xml` lists a **dont** against the CSS you are about to write and the consumer did **not** expressly override that guidance — stop. Do not ship it.

package/dist/specs/activity-hints.xml

@@ -56,15 +56,15 @@
     <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 open="patterns/settings-row.xml" when="label + control settings rows" />
+      <step open="components/stack/patterns.xml" when="Stack-owned: Surface render, page chrome, equal-width actions, both-axes fill / height 100% temptation" />
       <step unit="usage" note="confirm stack/surface/grid (etc.) do/dont after pattern" />
-      <step unit="props" note="verify spacing / render / fullWidth names" />
+      <step unit="props" note="verify spacing / render / fullWidth / fullHeight / expandChildren names" />
     </load>
     <forbid>Inventing display:flex / display:grid / CSS gap/padding/paddingBlock*/paddingInline*/border chrome when Stack, Grid, Masonry, Bleed, or Surface cover it — one-sided inset → hPadding/vPadding [start, end] tuples</forbid>
+    <forbid>Inventing width/height / inline-size/block-size:100% / w-full on Stack or children when fullWidth / fullHeight / expandChildren + hAlign/vAlign=&quot;stretch&quot; cover both-axis fill (open stack patterns + usage)</forbid>
     <forbid>Passing render={&lt;div /&gt;} (or any render that matches the component default root) — omit render; use it only for a different host</forbid>
   </activity>
 </activity_hints>

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

@@ -22,10 +22,10 @@
     <description>Resting background for the item card, forwarded to the wrapping `Surface` when `useSurface` is `true`. Omit for no background.</description>
   </prop>
   <prop name="Item.iconClosed" kind="react">
-    <description>Decorative icon shown when the item is closed.</description>
+    <description>Decorative icon shown when the item is closed. Omit glyph `size` / width / height unless expressly overriding — prefer host/chrome default.</description>
   </prop>
   <prop name="Item.iconOpen" kind="react">
-    <description>Decorative icon shown when the item is open.</description>
+    <description>Decorative icon shown when the item is open. Omit glyph `size` / width / height unless expressly overriding — prefer host/chrome default.</description>
   </prop>
   <prop name="Item.iconPosition" kind="react">
     <description>Side of the trigger label where the expand/collapse icon is rendered.</description>

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

@@ -6,7 +6,9 @@
   <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>
+  <do>Omit `size` / width / height on Item `iconClosed` / `iconOpen` glyphs unless expressly overriding — prefer chrome/host default</do>
   <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports — those stay inside `Accordion.Item`</dont>
+  <dont>Passing `size=&quot;1rem&quot;` on every Accordion icon by habit — omit unless expressly overriding</dont>
   <dont>Rendering an item without trigger text and without an external aria-label strategy</dont>
   <dont>Using Accordion for a single expandable section — use Disclosure</dont>
   <dont>Using Accordion for primary navigation that should be links, Tabs, or routes</dont>

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

@@ -11,7 +11,7 @@
   placeholder="Search by name…"
   items={reviewers}
   itemToStringValue={(person) => person.label}
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
 >
   {(person) => (
     <Autocomplete.Item
@@ -36,7 +36,7 @@
   placeholder="SaaS, travel, contractors…"
   items={expenseCategories}
   itemToStringValue={(category) => category.label}
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
 >
   {(category) => (
     <Autocomplete.Item key={category.id} value={category}>
@@ -57,7 +57,7 @@
   placeholder="Paris, Austin, Singapore…"
   items={transferDesks}
   itemToStringValue={(desk) => desk.label}
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
 >
   {(group) => (
     <Autocomplete.Group key={group.value} items={group.items} label={group.value}>
@@ -85,7 +85,7 @@
   items={results}
   itemToStringValue={(article) => article.title}
   placeholder="Wire limits, SEPA, tax forms…"
-  startAddon={<Magnifier aria-hidden size={16} />}
+  startAddon={<Magnifier aria-hidden />}
   status={
     <Stack columnGap="s" direction="row" vAlign="center">
       <Spinner aria-hidden size="s" />

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

@@ -25,7 +25,7 @@
     <description>Content rendered inside baked `Autocomplete.Empty` when the filtered list has no items.</description>
   </prop>
   <prop name="endAddon" kind="react">
-    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`.</description>
+    <description>Trailing decoration (icon, button). Buttons must use `type=&quot;button&quot;`. Omit glyph `size` / width / height on icons unless expressly overriding; IconButton/Button hosts own SVG size via CSS.</description>
   </prop>
   <prop name="error" kind="react">
     <description>Error copy rendered with `Field.Error` and `Text` in the same slot as `description`. Replaces description while the field is invalid and dirty.</description>
@@ -52,7 +52,7 @@
     <description>Ref forwarded to the autocomplete input.</description>
   </prop>
   <prop name="startAddon" kind="react">
-    <description>Leading decoration (prefix text, icon). Not a second field control.</description>
+    <description>Leading decoration (prefix text, icon). Not a second field control. Omit glyph `size` / width / height on icons unless expressly overriding the icon-library default.</description>
   </prop>
   <prop name="status" kind="react">
     <description>Content rendered inside baked `Autocomplete.Status` (async / limit messaging). Keep the slot mounted; update children when status changes.</description>

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

@@ -4,7 +4,7 @@
   <do>Prefer Autocomplete over Select when users may type a value not in the list (tags, categories, search)</do>
   <do>Form section: Fieldset legend + Autocomplete with sibling Textfield/Select when they share one section — Stack owns gap</do>
   <do>Fill a form column via a parent Stack `fullWidth` / `expandChildren` (Autocomplete has no `fullWidth` prop) — not CSS `width: 100%`</do>
-  <do>`startAddon` / `endAddon` for leading/trailing chrome (same control-group pattern as Textfield) — IconButton/Button addons use `size=&quot;s&quot;` and `type=&quot;button&quot;`</do>
+  <do>`startAddon` / `endAddon` for leading/trailing chrome (same control-group pattern as Textfield) — IconButton/Button addons use control `size=&quot;s&quot;` and `type=&quot;button&quot;`; omit glyph `size` / width / height on icons</do>
   <do>Grouped suggestion lists via `Autocomplete.Group` + `Autocomplete.Collection`; item rows via `Autocomplete.Item` `addon` (e.g. Avatar)</do>
   <do>Async or limited result lists: pass `empty` for no-match copy; keep root `status` mounted and update its children — Spinner + Text inside `status` is fine</do>
   <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>

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

@@ -81,10 +81,10 @@
   <example title="Flat addon links (clone)">
     <tsx><![CDATA[
 <Stack hAlign="start" rowGap="2xs">
-  <Button addon={<CircleImage size={18} />} variant="flat" size="s">
+  <Button addon={<CircleImage />} variant="flat" size="s">
     Open with GitHub Desktop
   </Button>
-  <Button addon={<ArrowDown size={18} />} variant="flat" size="s">
+  <Button addon={<ArrowDown />} variant="flat" size="s">
     Download ZIP
   </Button>
 </Stack>

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

@@ -13,7 +13,7 @@
     <item>Forcing full panel width with CSS `width: 100%` / `w-full` — wrap in Stack with `fullWidth` and/or `expandChildren` (see stack units)</item>
   </when_not_to_use>
   <prop name="addon" kind="react">
-    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips.</description>
+    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips. Omit glyph `size` / width / height — Button CSS sizes SVG via `--vui-button-icon-size`.</description>
   </prop>
   <prop name="addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label.</description>
@@ -31,7 +31,7 @@
     <description>Selects the visual treatment for the button.</description>
   </prop>
   <prop name="addon" kind="react">
-    <description>Decorative addon rendered alongside the link label. (button-link)</description>
+    <description>Decorative addon rendered alongside the link label. Omit glyph `size` / width / height — host CSS sizes SVG. (button-link)</description>
   </prop>
   <prop name="addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label. (button-link)</description>
@@ -61,7 +61,7 @@
     <description>Button block size; size prop presets via data attributes.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button.</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
@@ -85,7 +85,7 @@
     <description>Button block size; size prop presets via data attributes. (button-link)</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button. (button-link)</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode. (button-link)</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (button-link)</description>

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

@@ -8,10 +8,11 @@
   <do>Dialog / sheet action strips: Stack row of Button + ButtonLink; Cancel via `Dialog.Close render={&lt;Button variant=&quot;secondary&quot; /&gt;}`</do>
   <do>Primary Chip addons inside a primary Button — set `data-mode=&quot;inverted&quot;` on the Chip so its fill contrasts</do>
   <do>Navigation that should look like Button — use ButtonLink (framework Link via `render`; sets `data-no-link-style` so preflight underline does not fight button paint)</do>
+  <do>Omit `size` / width / height on `addon` icons — host CSS sets `--vui-button-icon-size` from control `size`; set glyph size only to expressly override</do>
   <dont>Using Button without children as icon-only — prefer IconButton</dont>
   <dont>Using Button with `render={&lt;a /&gt;}` for links — Base UI enforces button semantics; use ButtonLink</dont>
   <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / `.fullWidth` / size-fill `className` (e.g. `.Submit`) on Button when a parent Stack can own the fill</dont>
-  <dont>Duplicating icon size on every addon slot — Button CSS sizes SVG descendants</dont>
+  <dont>Passing `size={16}` / `size=&quot;1rem&quot;` (or width/height) on every `addon` icon — Button CSS sizes SVG descendants via `--vui-button-icon-size`</dont>
   <dont>Mixing `pill` with custom border-radius overrides that fight `data-pill` styling</dont>
   <dont>Primary Chip addon inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>
   <dont>Forcing `role=&quot;button&quot;` on a link</dont>

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

@@ -10,7 +10,7 @@
     Deploying
   </Chip>
   <Chip variant="yellow">Queued</Chip>
-  <Chip variant="red" addon={<Xmark size={14} />}>
+  <Chip variant="red" addon={<Xmark />}>
     Failed
   </Chip>
   <Chip variant="salmon">Rolled back</Chip>
@@ -30,7 +30,7 @@
       $0.00
     </Title>
   </Stack>
-  <Chip variant="outline" addon={<CircleCross size={8} color="var(--highlight-yellow)" />}>
+  <Chip variant="outline" addon={<CircleCross color="var(--highlight-yellow)" />}>
     Pending Setup
   </Chip>
 </Stack>

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

@@ -11,7 +11,7 @@
     <item>Long-form text content that should wrap like body copy — use Text</item>
   </when_not_to_use>
   <prop name="addon" kind="react">
-    <description>Decorative addon rendered alongside the chip label.</description>
+    <description>Decorative addon rendered alongside the chip label. Omit glyph `size` / width / height — Chip CSS sizes SVG via `--vui-chip-icon-size`.</description>
   </prop>
   <prop name="addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label.</description>
@@ -44,6 +44,6 @@
     <description>Fixed chip block size.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Decorative addon icon size.</description>
+    <description>Decorative addon icon size (`--vui-chip-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
 </props>

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

@@ -4,10 +4,12 @@
   <do>Metadata, category, status, or inline tag-like presentation in Stack rows with Text / Title</do>
   <do>Color-coded status via highlight `variant` values (`green`, `red`, `yellow`, …) or `primary` / `secondary` / `outline`</do>
   <do>Primary Chip as Button `addon` — set `data-mode=&quot;inverted&quot;` on the Chip when the Button is primary so fills contrast</do>
+  <do>Omit `size` / width / height on `addon` icons — Chip CSS sets `--vui-chip-icon-size`; set glyph size only to expressly override</do>
   <do>Equal-width Chip clusters: wrap in Stack with `fullWidth` and/or `expandChildren` — never per-Chip width CSS</do>
   <do>Polymorphic label root via `render` (default `div`; Chip sets `data-no-link-style` so Chip-as-`&lt;a&gt;` keeps chip chrome)</do>
   <dont>Using Chip as a button replacement for clickable actions — use Button or IconButton</dont>
   <dont>Expecting `addonPosition` to have any effect when `addon` is omitted</dont>
+  <dont>Passing `size={16}` / width / height on every Chip `addon` icon — Chip CSS sizes SVG descendants</dont>
   <dont>Introducing custom size variants instead of the fixed compact height</dont>
   <dont>Re-adding a one-off destructive variant instead of `variant=&quot;red&quot;`</dont>
   <dont>Primary Chip inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>

package/dist/specs/components/direction-provider/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="direction-provider">
+  <rule>Not an APG widget — direction context only; keep accessible names and semantics when flipping LTR/RTL</rule>
+  <rule>Pair provider `direction=&quot;rtl&quot;` with document `dir=&quot;rtl&quot;` so CSS logical properties and portaled overlays stay consistent for assistive tech and visual layout</rule>
+  <rule>Do not rely on mirrored chrome alone to communicate meaning that must stay in the accessible name</rule>
+</a11y>

package/dist/specs/components/direction-provider/meta.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="direction-provider" title="DirectionProvider" category="layout" shared_contract="direction-provider">
+  <summary>Transparent re-export of Base UI DirectionProvider and useDirection. Enables RTL behavior for Base UI–backed components; does not set HTML dir or CSS direction — pair with document dir=rtl on a portal ancestor (usually html).</summary>
+  <exports>
+    <export name="DirectionProvider" />
+    <export name="useDirection" />
+  </exports>
+  <related>
+    <ref id="menu" />
+    <ref id="slider" />
+    <ref id="select" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/utils/direction-provider#api-reference" />
+</meta>

package/dist/specs/components/direction-provider/patterns.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="direction-provider">
+  <example title="RTL subtree with Slider">
+    <tsx><![CDATA[
+<div dir="rtl">
+  <DirectionProvider direction="rtl">
+    <Slider defaultValue={25} label="Volume" />
+  </DirectionProvider>
+</div>
+]]></tsx>
+    <notes>Transparent Base UI re-export. Provider feeds Base UI context; `dir` on an ancestor owns HTML/CSS direction. For app-wide RTL set `dir` on `html`. Upstream: https://base-ui.com/react/utils/direction-provider</notes>
+  </example>
+
+  <example title="Read direction in a portal-safe hook">
+    <tsx><![CDATA[
+function DirectionLabel() {
+  const direction = useDirection();
+  return <Text size="s">Direction: {direction}</Text>;
+}
+
+<DirectionProvider direction="rtl">
+  <DirectionLabel />
+</DirectionProvider>
+]]></tsx>
+    <notes>`useDirection` reads the provider context — useful when portaled trees are outside a local `dir` wrapper.</notes>
+  </example>
+</patterns>

package/dist/specs/components/direction-provider/props.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="direction-provider">
+  <when_to_use>
+    <item>RTL apps that need Base UI–backed Vira menus, sliders, selects, and other direction-aware primitives to flip behavior</item>
+    <item>Reading the active text direction in portaled trees via `useDirection` when `dir` on html is not enough</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Expecting this provider alone to flip HTML/CSS layout — also set `dir=&quot;rtl&quot;` (or `direction: rtl`) on a portal ancestor, usually `&lt;html&gt;`</item>
+    <item>Mandatory root chrome — opt-in like BreakpointsProvider; not part of Dialog/Tooltip/Toast overlay shell</item>
+    <item>Inventing a Vira wrapper API — this surface is a transparent Base UI re-export</item>
+  </when_not_to_use>
+  <prop name="children" kind="react">
+    <description>Tree that should receive Base UI direction context. Pass-through from Base UI.</description>
+  </prop>
+  <prop name="direction" kind="react">
+    <description>Reading direction: `ltr` (default) or `rtl`. Pass-through from Base UI — see upstream API.</description>
+  </prop>
+</props>

package/dist/specs/components/direction-provider/usage.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="direction-provider">
+  <do>Import `DirectionProvider` / `useDirection` from `@viraui/react` — transparent Base UI re-export; full API → https://base-ui.com/react/utils/direction-provider</do>
+  <do>Wrap the app (or RTL subtree) in `DirectionProvider direction=&quot;rtl&quot;` and set `dir=&quot;rtl&quot;` on a portal ancestor (usually `&lt;html&gt;`) so body-mounted popups inherit CSS direction</do>
+  <do>Use `useDirection` when a portaled component needs the context direction without reading the DOM `dir` attribute</do>
+  <dont>Assuming `DirectionProvider` sets HTML `dir` or CSS `direction` — it only feeds Base UI context</dont>
+  <dont>Setting `dir=&quot;rtl&quot;` only on a local wrapper when popups portal to `document.body` — use `html` / document root</dont>
+  <dont>Importing `@base-ui/react/direction-provider` directly in Vira apps when `@viraui/react` already re-exports it</dont>
+  <dont>Treating this as required overlay bootstrap — Dialog/Tooltip/Toast providers stay separate; DirectionProvider is opt-in for RTL</dont>
+</usage>

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

@@ -22,9 +22,9 @@
   <Disclosure.Trigger
     hPadding="m"
     interpolateIcons
-    openIcon={<Xmark size="1rem" />}
+    openIcon={<Xmark />}
     radius="m"
-    restingIcon={<Plus size="1rem" />}
+    restingIcon={<Plus />}
     vPadding="m"
   >
     Advanced

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

@@ -10,10 +10,10 @@
     <item>Primary navigation that should use links, Tabs, or routes</item>
   </when_not_to_use>
   <prop name="Trigger.restingIcon" kind="react">
-    <description>Decorative icon while the panel is closed. Defaults to ChromeChevronEnd when both icon slots are omitted.</description>
+    <description>Decorative icon while the panel is closed. Defaults to ChromeChevronEnd when both icon slots are omitted. Omit glyph `size` / width / height — Disclosure CSS sizes SVG in the icon box.</description>
   </prop>
   <prop name="Trigger.openIcon" kind="react">
-    <description>Decorative icon while the panel is open. Defaults to ChromeChevronDown when both icon slots are omitted. When only restingIcon is set, that icon shows in both states.</description>
+    <description>Decorative icon while the panel is open. Defaults to ChromeChevronDown when both icon slots are omitted. When only restingIcon is set, that icon shows in both states. Omit glyph `size` / width / height — host CSS sizes SVG.</description>
   </prop>
   <prop name="Trigger.interpolateIcons" kind="react">
     <description>When dual icons are present, crossfade and light-rotate between them (`data-interpolate=&quot;true&quot;`). When false, swap instantly with no transition.</description>

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

@@ -4,8 +4,10 @@
   <do>Spread Surface chrome on Trigger (`color`, `hoverColor`, `border`, `radius`, padding) when using the default host</do>
   <do>Supply Panel children layout (Stack/padding) yourself — Panel has no default content padding</do>
   <do>Use `restingIcon` / `openIcon` / `interpolateIcons` for ToggleButton-style icon pairs; omit both for chrome chevron End/Down</do>
+  <do>Omit `size` / width / height on Trigger icon glyphs — Disclosure CSS sizes SVG in the icon box; set glyph size only to expressly override</do>
   <do>Pass Trigger `render` when replacing the Surface compose entirely</do>
   <dont>Using Accordion for a single section — Accordion is multi-item</dont>
   <dont>Expecting Accordion-like default Panel padding from Disclosure.Panel</dont>
+  <dont>Passing `size=&quot;1rem&quot;` / width / height on every Trigger icon glyph — host CSS sizes SVG descendants</dont>
   <dont>Relying on icon animation alone for open/closed meaning under reduced motion</dont>
 </usage>

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

@@ -19,7 +19,7 @@
           render={
             <IconButton
               aria-label="More actions for Q2 payout report"
-              icon={<DotsVertical size={16} />}
+              icon={<DotsVertical />}
               pill
               size="s"
               variant="flat"

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

@@ -38,13 +38,13 @@
 <Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
   <Grid columns={7} rows={6} columnGap="m" rowGap="m">
     <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
-      <IconButton aria-label="Home" icon={<House size={22} aria-hidden />} variant="flat" />
+      <IconButton aria-label="Home" icon={<House aria-hidden />} variant="flat" />
     </Grid.Item>
     <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
-      <IconButton aria-label="Search" icon={<Magnifier size={22} aria-hidden />} variant="flat" />
+      <IconButton aria-label="Search" icon={<Magnifier aria-hidden />} variant="flat" />
     </Grid.Item>
     <Grid.Item render={<Stack hAlign="center" vAlign="center" />}>
-      <IconButton aria-label="Settings" icon={<Gear size={22} aria-hidden />} variant="flat" />
+      <IconButton aria-label="Settings" icon={<Gear aria-hidden />} variant="flat" />
     </Grid.Item>
     {/* more IconButtons… */}
   </Grid>

package/dist/specs/components/icon-button/props.xml

@@ -12,7 +12,7 @@
     <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback. Use ToggleButton instead</item>
   </when_not_to_use>
   <prop name="icon" kind="react">
-    <description>Icon rendered as the sole visible control content.</description>
+    <description>Icon rendered as the sole visible control content. Omit glyph `size` / width / height — host CSS sizes SVG via `--vui-button-icon-size`.</description>
   </prop>
   <prop name="loading" kind="react">
     <description>Shows a centered spinner overlay while preserving the original content width.</description>
@@ -27,7 +27,7 @@
     <description>Selects the visual treatment for the button.</description>
   </prop>
   <prop name="icon" kind="react">
-    <description>Icon rendered as the sole visible control content. (icon-button-link)</description>
+    <description>Icon rendered as the sole visible control content. Omit glyph `size` / width / height — host CSS sizes SVG. (icon-button-link)</description>
   </prop>
   <prop name="loading" kind="react">
     <description>Shows a centered spinner overlay while preserving the original content width. Sets `aria-disabled` / `aria-busy` for loading chrome; link stays activatable. (icon-button-link)</description>
@@ -54,7 +54,7 @@
     <description>Button block size; size prop presets via data attributes.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button.</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
@@ -78,7 +78,7 @@
     <description>Button block size; size prop presets via data attributes. (icon-button-link)</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button. (icon-button-link)</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode. (icon-button-link)</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (icon-button-link)</description>

package/dist/specs/components/icon-button/usage.xml

@@ -3,8 +3,9 @@
   <do>Compact toolbar or chrome actions identified only by icon</do>
   <do>Same size, variant, and loading model as Button without a visible label</do>
   <do>Decorative glyph with an explicit accessible name on the root (`aria-label` / `aria-labelledby`)</do>
+  <do>Omit `size` / width / height on the `icon` glyph — host CSS sizes SVG via `--vui-button-icon-size`; set glyph size only to expressly override</do>
   <do>Toolbar / zoom / chrome clusters: Stack row of IconButtons inside Surface — gap via Stack, not per-control CSS</do>
-  <do>Textfield `endAddon` / `startAddon` for compact field chrome (e.g. copy) — keep addon control `size=&quot;s&quot;`</do>
+  <do>Textfield `endAddon` / `startAddon` for compact field chrome (e.g. copy) — keep addon control `size=&quot;s&quot;` (control size, not glyph size)</do>
   <do>Menu / overlay triggers via `Menu.Trigger render={&lt;IconButton … /&gt;}` (and peers with the same pattern)</do>
   <do>Icon-only navigation — use IconButtonLink (framework Link via `render`)</do>
   <dont>Passing `children`, `addon`, or `addonPosition` — not part of the public API; use `icon`</dont>
@@ -12,5 +13,6 @@
   <dont>Using IconButton for persistent or temporal pressed state — use ToggleButton</dont>
   <dont>Using IconButton with `render={&lt;a /&gt;}` for links — use IconButtonLink</dont>
   <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
+  <dont>Passing `size={16}` / `size=&quot;1rem&quot;` (or width/height) on the `icon` glyph — IconButton CSS sizes SVG descendants</dont>
   <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / size-fill `className` (e.g. `.Social`) on IconButton — it is intentionally square; Stack owns gap/align only</dont>
 </usage>