@viraui/react 2026.6.0 → 2026.6.2

package/dist/specs/foundation/modules.xml

@@ -1,65 +1,142 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <modules>
-  <summary>Preflight CSS modules under packages/react/src/core/preflight/ that compose @viraui/react/preflight.css.</summary>
-  <module id="themes" file="modes.css">
-    <purpose>Runtime color-scheme hints for light, dark, and inverted mode.</purpose>
+  <summary>What @viraui/react/preflight.css provides at runtime. Capability map for consumers and agents — not a source-tree inventory. Full attr contracts: attributes.xml; elevation compose: elevation.xml; effect gates: toggles.xml; theme token groups: theme-topics.xml.</summary>
+
+  <distributed>
+    <import>@viraui/react/preflight.css</import>
+    <layer>viraui.preflight (declared by the published entry; components use viraui.components; app overrides prefer viraui.overrides or unlayered CSS)</layer>
+    <prerequisite>Compatible theme CSS and consumer fonts must load before preflight. Order and providers: bootstrap.xml.</prerequisite>
+  </distributed>
+
+  <agent_rules>
+    <use>Import the single published preflight entry. Drive UI via documented data-* hooks, Elevator / getElevationProps, and theme tokens.</use>
+    <use>Open this unit to learn which preflight capability owns a behavior, then follow the linked foundation unit for values and when/when_not.</use>
+    <use>Consume surface=&quot;derived&quot; tokens (e.g. --font-scale-*) with var(…); change them by overriding theme inputs (typescale), not by redefining the derived vars.</use>
+    <do_not>Patch, fork, or import individual files from inside the preflight bundle.</do_not>
+    <do_not>Invent data-* names or --__* vars. Public hooks live in attributes.xml / this map; internals are not app API.</do_not>
+    <do_not>Hand-roll box-shadow, backdrop-filter, or corner-shape when preflight + theme gates already cover the need.</do_not>
+    <do_not>Set surface=&quot;internal&quot; custom properties from app markup or style.</do_not>
+  </agent_rules>
+
+  <module id="baseline">
+    <purpose>Root document baseline after theme load: rem root from --font-root-size, color/background from --global-*, polarity --is-light-mode, scrollbar and focus-visible ring, reduced-motion, corner-shape gate.</purpose>
+    <provides>--is-light-mode; focus ring via --outline*; scrollbar via --scrollbar-*; corner-shape application</provides>
+    <use>Theme tokens + data-mode. Query polarity with @container root style(--is-light-mode: black|white). Details: toggles.xml.</use>
+    <do_not>Replace preflight reset with a second framework reboot. Prefer omitting third-party preflight/reset (setup skill coexistence).</do_not>
   </module>
-  <module id="core" file="core.css">
-    <purpose>Root baseline including html font-size from --font-root-size, --is-light-mode registration, global element defaults, and corner-shape gate via var(--__corner-shape, var(--corner-shape)).</purpose>
+  <module id="font-scale">
+    <purpose>Derives --font-scale-* from theme --font-heading-typescale / --font-body-typescale (pow + round). body-m = 1rem; smaller body steps floored; larger body and display from continuous powers.</purpose>
+    <provides>--font-scale-body-*, --font-scale-h*, --font-scale-display</provides>
+    <use>Read var(--font-scale-*) in components/app CSS. To change sizes, override typescale theme tokens (theme-topics.xml font-typescale).</use>
+    <do_not>Author --font-scale-* in theme CSS. Preflight owns derivation; theme ships ratios only.</do_not>
   </module>
-  <module id="font-scale" file="font-scale.css">
-    <purpose>Derive --font-scale-* from --font-heading-typescale / --font-body-typescale with pow + round(down, …, 1px). body-m = 1rem; body-s/body-xs = modular 1/pow floored at 0.875rem/0.75rem (max) and capped so xs ≤ s ≤ m (min); body-l…body-4xl = continuous n=1…5; display = heading n=8.</purpose>
+  <module id="modes">
+    <purpose>Runtime light / dark / inverted color-scheme via data-mode.</purpose>
+    <provides>data-mode</provides>
+    <use>Set on html, body, or a layout wrapper. Values and when/when_not: attributes.xml. Mode flag ≠ swapping brand theme sheets.</use>
+    <do_not>Use data-mode as a substitute for loading compatible theme CSS.</do_not>
   </module>
-  <module id="typography" file="typography.css">
-    <purpose>Semantic HTML element typography and link styling opt-out.</purpose>
+  <module id="elevations">
+    <purpose>Theme-gated box-shadow depth stacks for raised surfaces (not z-index).</purpose>
+    <provides>data-elevation, data-elevation-hover, data-elevation-direction; --shadow-color, --extra-shadow, --elevation-transition-*</provides>
+    <use>Prefer Elevator or getElevationProps on React hosts; raw data-elevation* only when those do not fit. Full compose: elevation.xml. Gate: --effect-shadows (toggles.xml).</use>
+    <do_not>Hand-roll box-shadow. Do not expect elevation attrs to change stacking / z-index.</do_not>
   </module>
-  <module id="elevations" file="elevations.css">
-    <purpose>Theme-gated resting and hover box-shadow elevation stacks plus unlayered box-shadow transitions.</purpose>
+  <module id="layout">
+    <purpose>Local flex grow/shrink signals for Stack and flex children.</purpose>
+    <provides>data-grow, data-shrink (drive --vira-flex-grow / --vira-flex-shrink; non-inheriting)</provides>
+    <use>Set data-grow / data-shrink on the flex child (attributes.xml). Stack expandChildren reads the grow signal.</use>
+    <do_not>Assign --vira-flex-grow / --vira-flex-shrink directly in app CSS — use the data-* attrs.</do_not>
   </module>
-  <module id="layout" file="layout.css">
-    <purpose>Flex growth and shrink utilities via data-grow / data-shrink for Stack and component children.</purpose>
+  <module id="typography">
+    <purpose>Semantic HTML element typography defaults and link chrome opt-out.</purpose>
+    <provides>element type defaults; data-no-link-style</provides>
+    <use>Leave default prose links alone. Add data-no-link-style when component or custom link chrome must win (attributes.xml).</use>
+    <do_not>Fight preflight link styles without the opt-out attr.</do_not>
   </module>
-  <module id="vibrancy" file="vibrancy.css">
-    <purpose>Theme-gated backdrop-filter vibrancy on elements that opt in with data-vibrant.</purpose>
+  <module id="vibrancy">
+    <purpose>Theme-gated backdrop-filter glass on opt-in hosts.</purpose>
+    <provides>data-vibrant</provides>
+    <use>Set data-vibrant when --effect-vibrancy is on; still set a background fill as needed (Surface translucifies fill when present). Params: --vibrancy-* (theme-topics). Attr contract: attributes.xml.</use>
+    <do_not>Hand-roll backdrop-filter for the same effect.</do_not>
   </module>
-  <custom_property name="--is-light-mode">
-    <purpose>Registers the active theme polarity for @container root queries; data-mode=&quot;inverted&quot; flips color-scheme against this value.</purpose>
+
+  <custom_property name="--is-light-mode" surface="public">
+    <purpose>Theme polarity for @container root queries; data-mode=&quot;inverted&quot; flips color-scheme against this value (black = light theme, white = dark theme).</purpose>
     <default>black</default>
-    <set_by>html root in core.css from contrast-color(var(--global-background))</set_by>
+    <set_by>Preflight on html from contrast-color(var(--global-background)); data-mode light/dark may force black/white</set_by>
+    <use>Branch with @container root style(--is-light-mode: black|white). Do not invent alternate light/dark hooks.</use>
   </custom_property>
-  <custom_property name="--shadow-color">
-    <purpose>Shadow tint for data-elevation stacks.</purpose>
+  <custom_property name="--shadow-color" surface="public">
+    <purpose>Shadow tint for elevation stacks.</purpose>
     <default>oklch(0% 0 0)</default>
-    <set_by>inline style or component elevation mapping</set_by>
+    <set_by>Elevator / getElevationProps (shadowColor) or equivalent style on the elevated host</set_by>
+    <use>Prefer getElevationProps({ shadowColor }). Pair with data-elevation*.</use>
   </custom_property>
-  <custom_property name="--extra-shadow">
-    <purpose>Additional box-shadow layer appended to elevation stacks, for example hairline borders.</purpose>
+  <custom_property name="--extra-shadow" surface="public">
+    <purpose>Extra box-shadow layer appended to elevation stacks (e.g. hairline border).</purpose>
     <default>0 0 0 1px transparent</default>
-    <set_by>inline style or component elevation mapping</set_by>
+    <set_by>Elevator / getElevationProps (extraShadow) or equivalent style on the elevated host</set_by>
+    <use>Prefer getElevationProps({ extraShadow }).</use>
   </custom_property>
-  <custom_property name="--elevation-transition-duration">
+  <custom_property name="--elevation-transition-duration" surface="public">
     <purpose>Duration for data-elevation box-shadow transitions.</purpose>
     <default>160ms</default>
-    <set_by>inline style or theme override</set_by>
+    <set_by>Optional style on the elevated host or theme override</set_by>
+    <use>Override only when product motion needs differ; default is fine for most UI.</use>
   </custom_property>
-  <custom_property name="--elevation-transition-easing">
+  <custom_property name="--elevation-transition-easing" surface="public">
     <purpose>Timing function for data-elevation box-shadow transitions.</purpose>
     <default>ease</default>
-    <set_by>inline style or theme override</set_by>
+    <set_by>Optional style on the elevated host or theme override</set_by>
+    <use>Optional; default is fine for most UI.</use>
   </custom_property>
-  <custom_property name="--vira-flex-grow">
-    <purpose>Local grow signal for Stack expandChildren / child flex defaults; does not inherit so ancestor data-grow cannot poison nested stacks.</purpose>
-    <default>1 (initial-value); inherits: false; Stack expandChildren uses var(--vira-flex-grow, 1)</default>
-    <set_by>data-grow=&quot;true&quot; or data-grow=&quot;false&quot;; registered in global-properties.css</set_by>
+  <custom_property name="--vira-flex-grow" surface="public">
+    <purpose>Local grow signal for Stack expandChildren / child flex defaults; does not inherit.</purpose>
+    <default>1; inherits: false</default>
+    <set_by>data-grow=&quot;true&quot; | data-grow=&quot;false&quot;</set_by>
+    <use>Set via data-grow only.</use>
   </custom_property>
-  <custom_property name="--vira-flex-shrink">
-    <purpose>Local shrink signal for flex defaults; does not inherit so ancestor data-shrink cannot poison descendants.</purpose>
-    <default>1 (initial-value); inherits: false</default>
-    <set_by>data-shrink=&quot;true&quot; or data-shrink=&quot;false&quot;; registered in global-properties.css</set_by>
+  <custom_property name="--vira-flex-shrink" surface="public">
+    <purpose>Local shrink signal for flex defaults; does not inherit.</purpose>
+    <default>1; inherits: false</default>
+    <set_by>data-shrink=&quot;true&quot; | data-shrink=&quot;false&quot;</set_by>
+    <use>Set via data-shrink only.</use>
   </custom_property>
-  <custom_property name="--__corner-shape">
-    <purpose>Internal override for the preflight corner-shape gate so full radius keeps round pill arcs when --effect-corner-shape is on. Not a consumer data-* or public theme recipe. Consumers must disable corner-shape when using full radius.</purpose>
-    <default>guaranteed-invalid (no initial-value); inherits: false; preflight uses var(--__corner-shape, var(--corner-shape))</default>
-    <set_by>ViraUI components on the same element as full / pill radius (CSS modules or React style); registered in global-properties.css</set_by>
+  <custom_property name="--scrollbar-thumb" surface="public">
+    <purpose>Scrollbar thumb color for preflight scrollbar-color.</purpose>
+    <default>Derived on html from --global-contrast (semi-transparent)</default>
+    <set_by>Preflight on html; optional root override</set_by>
+    <use>Override on html/root when product needs a custom scrollbar tint.</use>
+  </custom_property>
+  <custom_property name="--scrollbar-track" surface="public">
+    <purpose>Scrollbar track color for preflight scrollbar-color.</purpose>
+    <default>transparent</default>
+    <set_by>Preflight on html; optional root override</set_by>
+    <use>Optional root override.</use>
+  </custom_property>
+  <custom_property name="--outline" surface="public">
+    <purpose>Focus-visible outline shorthand.</purpose>
+    <default>2px solid var(--outline-color) on html</default>
+    <set_by>Preflight on html; optional root override</set_by>
+    <use>Override at root for brand focus ring. Do not remove *:focus-visible affordance.</use>
+  </custom_property>
+  <custom_property name="--outline-color" surface="public">
+    <purpose>Focus ring color wired into --outline.</purpose>
+    <default>var(--global-outline) on html</default>
+    <set_by>Preflight from theme --global-outline; optional root override</set_by>
+    <use>Prefer overriding theme --global-outline first.</use>
+  </custom_property>
+  <custom_property name="--outline-offset" surface="public">
+    <purpose>Focus-visible outline-offset.</purpose>
+    <default>2px</default>
+    <set_by>Preflight on html; optional root override</set_by>
+    <use>Optional root override.</use>
+  </custom_property>
+  <custom_property name="--__corner-shape" surface="internal">
+    <purpose>Preflight-owned override so full/pill radius keeps round arcs when --effect-corner-shape is on. Not a consumer data-* or theme recipe.</purpose>
+    <default>guaranteed-invalid (falls through to --corner-shape)</default>
+    <set_by>ViraUI components on the same element as full / pill radius</set_by>
+    <use>Do not set from app markup. Need true pills on raw CSS: unset local corner-shape or turn --effect-corner-shape off. Theme token remains --corner-shape (theme-topics / toggles).</use>
   </custom_property>
 </modules>

package/dist/specs/foundation/theme-topics.xml

@@ -1,64 +1,99 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <theme_topics>
-  <summary>Public semantic CSS custom properties required by @viraui/react components.</summary>
-  <compatibility>Custom and builder-generated themes must keep documented semantic variable names stable while values may change.</compatibility>
-  <topic id="bootstrap-order">
+  <summary>Public semantic CSS custom-property groups required by @viraui/react. Short routing map — not a Style Dictionary dump. Names stay stable; values may change.</summary>
+  <compatibility>Custom and builder-generated themes must keep documented semantic variable names. Override surface=&quot;theme&quot; groups after a complete theme sheet. Do not author surface=&quot;derived&quot; vars in theme CSS.</compatibility>
+
+  <audience>
+    <consumer>Ship or override surface=&quot;theme&quot; topics. Prefer semantic aliases over surface=&quot;raw&quot; primitives. Never bake surface=&quot;derived&quot; tokens (e.g. --font-scale-*) into theme sheets — preflight owns those.</consumer>
+    <maintainer>When adding or renaming a public theme group: update this map, docs/theme-contract.md, foundation brand sources, and viraui-setup theme.md in the same change. Derived outputs are preflight-owned (modules.xml), not brand JSON.</maintainer>
+  </audience>
+
+  <agent_rules>
+    <use>Override --global-*, --base-*, --highlight-*, --space-*, --radius-*, --corner-shape, --effect-*, --vibrancy-*, --font-root-size, --font-*-typescale, --font-leading-*, --font-family-*, --duration-*, --easing-* after a complete compatible theme sheet.</use>
+    <use>Change live typography scale via --font-heading-typescale / --font-body-typescale; preflight re-derives --font-scale-*.</use>
+    <use>Read surface=&quot;derived&quot; tokens (var(--font-scale-*)) in component/app CSS — consume, do not redefine in theme.</use>
+    <do_not>Author --font-scale-* in theme CSS or brand typography.json. Theme ships typescale ratios only.</do_not>
+    <do_not>Ship theme CSS without @viraui/react/preflight.css — --font-scale-* come from preflight only.</do_not>
+    <do_not>Use raw --color-{palette}-{step} as the primary consumer override API; prefer --global-* / --base-* / --highlight-*. Use --color-* when the same color value must be the same across modes (and has enought contrast).</do_not>
+    <do_not>Rename documented semantic vars between preset and custom paths.</do_not>
+    <do_not>Treat --__corner-shape as a public theme recipe (component/preflight-owned; see modules.xml).</do_not>
+  </agent_rules>
+
+  <topic id="bootstrap-order" surface="bootstrap">
     <summary>Load compatible theme CSS, then consumer fonts, then @viraui/react/preflight.css via JS side-effect imports.</summary>
+    <agent>Theme before preflight so typescale inputs exist when font-scale.css derives sizes. Full rules: bootstrap.xml.</agent>
   </topic>
-  <topic id="base">
+
+  <topic id="base" surface="theme">
     <pattern>--base-*</pattern>
     <summary>Semantic neutral ramp for surfaces and text on themed backgrounds.</summary>
+    <agent>Safe override target. Keep step count and lightness progression unless the user asks to rebuild the ramp.</agent>
   </topic>
-  <topic id="global">
+  <topic id="global" surface="theme">
     <pattern>--global-*</pattern>
     <summary>App-facing foreground, background, primary, muted, interactive, disabled, and contrast colors.</summary>
+    <agent>Primary brand/accent override surface.</agent>
   </topic>
-  <topic id="effects">
+  <topic id="highlight" surface="theme">
+    <pattern>--highlight-*</pattern>
+    <summary>Status and decorative highlight palette.</summary>
+    <agent>Override for status/decorative semantics; leave untouched groups at theme defaults.</agent>
+  </topic>
+  <topic id="effects" surface="theme">
     <pattern>--effect-vibrancy | --effect-corner-shape | --effect-holofoil | --effect-shadows | --effect-fluid-typography</pattern>
-    <summary>Optional effect toggles; empty/unset = on, initial = off. Brand holofoil defaults to initial (off); vibrancy, corner-shape, shadows, and fluid-typography default empty (on). Holofoil on paints a fixed body::after foil overlay; shadows off disables preflight data-elevation box-shadow stacks; fluid-typography off locks Text/Title to each size’s theme scale token.</summary>
+    <summary>Optional effect toggles; empty/unset = on, initial = off. Brand holofoil defaults to initial (off); vibrancy, corner-shape, shadows, and fluid-typography default empty (on). Holofoil on paints a fixed body::after foil overlay; shadows off disables preflight data-elevation box-shadow stacks; fluid-typography off locks Text/Title to each size’s theme scale token (Text defaults `fluid` false; Title defaults true; both expose per-instance `fluid`).</summary>
+    <agent>Theme-level gates. Runtime polarity/details: toggles.xml. Do not invent alternate effect hooks.</agent>
   </topic>
-  <topic id="vibrancy">
+  <topic id="vibrancy" surface="theme">
     <pattern>--vibrancy-blur | --vibrancy-brightness</pattern>
     <summary>Vibrancy glass params; blur is a numeric amount consumed as pixels, brightness is a percent string.</summary>
+    <agent>Theme params for data-vibrant hosts when --effect-vibrancy is on. Do not hand-roll backdrop-filter.</agent>
   </topic>
-  <topic id="highlight">
-    <pattern>--highlight-*</pattern>
-    <summary>Status and decorative highlight palette.</summary>
-  </topic>
-  <topic id="radius">
+  <topic id="radius" surface="theme">
     <pattern>--radius-* | --corner-shape</pattern>
     <summary>Semantic radius scale plus corner-shape value for component chrome. Full/pill radius with --effect-corner-shape on can cap true pills; ViraUI sets internal --__corner-shape (preflight-owned, not a consumer data-*) beside full radius.</summary>
+    <agent>Override --radius-* / --corner-shape. Never set --__corner-shape from app markup. Raw CSS pills: local corner-shape: unset when effect is on.</agent>
   </topic>
-  <topic id="space">
+  <topic id="space" surface="theme">
     <pattern>--space-*</pattern>
     <summary>Semantic spacing scale for layout and component padding.</summary>
+    <agent>Safe override target. Keep relative ratios unless the user asks to rebuild the scale.</agent>
   </topic>
-  <topic id="font-root-size">
+  <topic id="font-root-size" surface="theme">
     <pattern>--font-root-size</pattern>
     <summary>Root html font-size as a percentage of the user-agent default; preflight applies it on html so rem-based scales inherit the brand baseline.</summary>
+    <agent>Theme lever for rem baseline. Preflight applies it on html (modules.xml baseline).</agent>
   </topic>
-  <topic id="font-typescale">
+  <topic id="font-typescale" surface="theme">
     <pattern>--font-heading-typescale | --font-body-typescale</pattern>
     <summary>Editable modular ratios from theme CSS. Preflight derives --font-scale-* from these with pow + round(down). Override these (not baked sizes) for live typography scale changes.</summary>
+    <agent>Only editable typography-scale levers. Changing these updates derived --font-scale-* live once preflight is loaded.</agent>
   </topic>
-  <topic id="font-scale">
-    <pattern>--font-scale-*</pattern>
-    <summary>Semantic typography sizes (display, headings, body steps) derived by preflight from typescale ratios — not theme source tokens. body-m is always 1rem; body-s/body-xs use modular 1/pow with max() floors (0.875rem/0.75rem) and min() caps so they never shrink under chrome mins but can rise toward body-m; body-l…body-4xl are continuous powers n=1…5; display uses heading ratio at n=8. Text/Title fluid clamp between scale tokens is gated by --effect-fluid-typography (off → fixed at that size’s scale token).</summary>
-  </topic>
-  <topic id="font-family">
+  <topic id="font-family" surface="theme">
     <pattern>--font-family-heading | --font-family-body | --font-family-mono</pattern>
     <summary>Semantic font-family touchpoints; consumers must provide matching @font-face rules.</summary>
+    <agent>Theme publishes family strings only. Load matching fonts separately — theme never loads remote fonts.</agent>
   </topic>
-  <topic id="font-leading">
+  <topic id="font-leading" surface="theme">
     <pattern>--font-leading-*</pattern>
     <summary>Semantic line-height scale for text and title components.</summary>
+    <agent>Safe theme override for leading tokens.</agent>
   </topic>
-  <topic id="color-primitives">
-    <pattern>--color-{palette}-{step}</pattern>
-    <summary>Raw palette steps 0–70 by tens referenced by semantic aliases; not the primary consumer override API.</summary>
-  </topic>
-  <topic id="motion">
+  <topic id="motion" surface="theme">
     <pattern>--duration-* | --easing-*</pattern>
     <summary>Duration and easing tokens for component motion.</summary>
+    <agent>Theme motion primitives. Compose guidance: viraui-motion.</agent>
+  </topic>
+
+  <topic id="font-scale" surface="derived" set_by="preflight">
+    <pattern>--font-scale-*</pattern>
+    <summary>Semantic typography sizes (display, headings, body steps) derived by preflight from typescale ratios — not theme source tokens. body-m is always 1rem; body-s/body-xs use modular 1/pow with max() floors (0.875rem/0.75rem) and min() caps so they never shrink under chrome mins but can rise toward body-m; body-l…body-4xl are continuous powers n=1…5; display uses heading ratio at n=8. Text/Title fluid clamp between scale tokens is gated by --effect-fluid-typography and per-instance `fluid` (Text defaults false / locked; Title defaults true; off → fixed at that size’s scale token).</summary>
+    <agent>INTERNAL derivation — do not modify. Consume via var(--font-scale-*). To change sizes, override font-typescale. Capability map: modules.xml id=font-scale.</agent>
+  </topic>
+
+  <topic id="color-primitives" surface="raw">
+    <pattern>--color-{palette}-{step}</pattern>
+    <summary>Raw palette steps 0–70 by tens referenced by semantic aliases; not the primary consumer override API.</summary>
+    <agent>Preset build input. Prefer overriding --global-* / --base-* / --highlight-*. Do not theme an app by editing only --color-*.</agent>
   </topic>
 </theme_topics>

package/dist/specs/foundation/toggles.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <toggles>
-  <summary>Core polarity and theme effect gates shipped with preflight. Polarity: --is-light-mode is a &lt;color&gt; on the root container (black = light theme, white = dark theme); query it with @container root style(--is-light-mode: black|white). Effect toggles: empty/unset = on, initial = off; brand holofoil defaults to initial (off); vibrancy, corner-shape, shadows, and fluid-typography default empty (on). Gate effects with @container root not style(--effect-*: initial). Holofoil on paints a fixed body::after foil overlay; shadows off disables preflight data-elevation box-shadow stacks; fluid-typography off locks Text/Title font-size to each size’s theme scale token.</summary>
+  <summary>Core polarity and theme effect gates shipped with preflight. Polarity: --is-light-mode is a &lt;color&gt; on the root container (black = light theme, white = dark theme); query it with @container root style(--is-light-mode: black|white). Effect toggles: empty/unset = on, initial = off; brand holofoil defaults to initial (off); vibrancy, corner-shape, shadows, and fluid-typography default empty (on). Gate effects with @container root not style(--effect-*: initial). Holofoil on paints a fixed body::after foil overlay; shadows off disables preflight data-elevation box-shadow stacks; fluid-typography off locks Text/Title font-size to each size’s theme scale token (Text defaults `fluid` false; Title defaults true; both expose per-instance `fluid`).</summary>
   <toggle name="--is-light-mode">
     <when>html registers polarity via contrast-color(var(--global-background)) so light backgrounds resolve to black and dark backgrounds to white; container name is root (see core.css).</when>
     <when>data-mode=&quot;light&quot; forces --is-light-mode: black and color-scheme: light; data-mode=&quot;dark&quot; forces white and color-scheme: dark.</when>
@@ -20,7 +20,7 @@
     <when>Brand default is initial (off). When on, paints a fixed body::after foil overlay gated by @container root not style(--effect-holofoil: initial); foil blend adjusts under @container root style(--is-light-mode: white). Do not invent alternate foil hooks.</when>
   </toggle>
   <toggle name="--effect-fluid-typography">
-    <when>Empty/unset enables Text/Title fluid clamp sizing (prev scale step→step via container progress); set to initial to lock each size at its theme scale token (--font-scale-body-* / --font-scale-display / --font-scale-h*). Text and Title module CSS gate with @container root not style(--effect-fluid-typography: initial). No React prop or data-* — theme root only. Text size xs stays fixed regardless. At full fluid progress, on and off resolve to the same token.</when>
+    <when>Empty/unset enables Text/Title fluid clamp sizing (prev scale step→step via viewport progress) when the instance `fluid` prop is true. Text defaults `fluid` false (locked at --font-scale-body-*); Title defaults true. Set theme to initial to lock each size at its theme scale token (--font-scale-body-* / --font-scale-display / --font-scale-h*). Per-instance: Text/Title `fluid={false}` → data-*-fluid=false locks that node to its size max token; Text `fluid` opts in. Module CSS also gates with @container root style(--effect-fluid-typography: initial). Text size xs stays fixed (min=max). At full fluid progress, on and off resolve to the same token.</when>
   </toggle>
   <toggle name="--corner-shape">
     <when>Theme corner shape token; preflight may set internal --__corner-shape beside full radius. Not a consumer data-*.</when>

package/dist/specs/index.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<index package="@viraui/react" version="2026.6.0" generated="2026-09-24T08:32:32.436Z">
+<index package="@viraui/react" version="2026.6.2" generated="2026-09-25T10:54:01.336Z">
   <categories>
     <category id="layout" />
     <category id="action" />
@@ -92,7 +92,7 @@
     </units>
   </entry>
   <entry id="breakpoints" category="layout" title="BreakpointsProvider">
-    <summary>Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens.</summary>
+    <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.</summary>
     <units>
       <unit kind="meta" href="components/breakpoints/meta.xml" />
       <unit kind="a11y" href="components/breakpoints/a11y.xml" />
@@ -182,7 +182,7 @@
     </units>
   </entry>
   <entry id="glow" category="effect" title="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-he…</summary>
+    <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/CP…</summary>
     <units>
       <unit kind="meta" href="components/glow/meta.xml" />
       <unit kind="a11y" href="components/glow/a11y.xml" />
@@ -262,7 +262,7 @@
     </units>
   </entry>
   <entry id="progressive-blur" category="effect" title="ProgressiveBlur">
-    <summary>Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge.</summary>
+    <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.</summary>
     <units>
       <unit kind="meta" href="components/progressive-blur/meta.xml" />
       <unit kind="a11y" href="components/progressive-blur/a11y.xml" />
@@ -352,7 +352,7 @@
     </units>
   </entry>
   <entry id="static-noise" category="effect" title="StaticNoise">
-    <summary>Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly (rarely).</summary>
+    <summary>Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly; prefer one focal instance per view.</summary>
     <units>
       <unit kind="meta" href="components/static-noise/meta.xml" />
       <unit kind="a11y" href="components/static-noise/a11y.xml" />
@@ -529,10 +529,46 @@
       <unit kind="foundation" href="foundation/modules.xml" />
     </units>
   </entry>
+  <entry id="card-grid" category="pattern" title="Card grid">
+    <summary>Use Grid for CSS grid tracks (auto-fill/fit or fixed columns). Put token `rowGap` / `columnGap` on Grid; put card chrome on Surface; nest Stack inside each card for content gaps.</summary>
+    <units>
+      <unit kind="pattern" href="patterns/card-grid.xml" />
+    </units>
+  </entry>
+  <entry id="compose-layout-first" category="pattern" title="Compose layout primitives first">
+    <summary>Prefer Vira layout roots (`Stack`, `Grid`, `Masonry`, `Bleed`, `Surface`) and their public props for every consumer layout. Treat `Stack` as the default box: an enriched `div` (flex + gap/padding/ali…</summary>
+    <units>
+      <unit kind="pattern" href="patterns/compose-layout-first.xml" />
+    </units>
+  </entry>
+  <entry id="equal-width-actions" category="pattern" title="Equal-width action row">
+    <summary>Span or share space with Stack `fullWidth` and/or `expandChildren` (and control `fullWidth` when the surface owns it). Orthogonal: `fullWidth` sizes the Stack; `expandChildren` grows direct children …</summary>
+    <units>
+      <unit kind="pattern" href="patterns/equal-width-actions.xml" />
+    </units>
+  </entry>
+  <entry id="page-chrome" category="pattern" title="Page chrome with Stack render">
+    <summary>Own page/section flex with Stack. Pick semantic tags (`header`, `main`, `nav`, `section`, …) via `render={&amp;lt;tag /&amp;gt;}` — keep Stack as the layout engine. CSS modules may set min-block-size / scrol…</summary>
+    <units>
+      <unit kind="pattern" href="patterns/page-chrome.xml" />
+    </units>
+  </entry>
+  <entry id="settings-panel" category="pattern" title="Settings panel (Surface + Stack)">
+    <summary>Wrap a settings block in Surface for fill/border/radius/padding; nest Stack for child gaps and rows. Compose the settings-row pattern inside for label+control rows. Prefer props over CSS for spacing …</summary>
+    <units>
+      <unit kind="pattern" href="patterns/settings-panel.xml" />
+    </units>
+  </entry>
   <entry id="settings-row" category="pattern" title="Settings row">
-    <summary>Use Stack for the row flex layout and token gap; put the control at the trailing edge.</summary>
+    <summary>Use Stack for the row flex layout and token `columnGap`; put label copy in a nested column Stack with `expandChildren`; put the control at the trailing edge.</summary>
     <units>
       <unit kind="pattern" href="patterns/settings-row.xml" />
     </units>
   </entry>
+  <entry id="stack-as-surface" category="pattern" title="Stack as Surface (avoid extra DOM)">
+    <summary>When a flex cluster also needs Surface chrome (border, color, radius, padding), prefer `Stack render={&amp;lt;Surface … /&amp;gt;}` so layout + chrome share one root. Put gap/align/`fullWidth`/`expandChildre…</summary>
+    <units>
+      <unit kind="pattern" href="patterns/stack-as-surface.xml" />
+    </units>
+  </entry>
 </index>

package/dist/specs/patterns/card-grid.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pattern id="card-grid" title="Card grid">
+  <uses>
+    <ref id="grid" units="meta,usage,props" />
+    <ref id="surface" units="meta,usage" />
+    <ref id="stack" units="meta,usage" />
+    <ref id="text" units="meta" />
+  </uses>
+  <do>Use Grid for CSS grid tracks (auto-fill/fit or fixed columns). Put token `rowGap` / `columnGap` on Grid; put card chrome on Surface; nest Stack inside each card for content gaps.</do>
+  <dont>Do not invent `display:grid` / `grid-template-*` / CSS `gap` on plain HTML when Grid can own the layout. Do not use Masonry when you need explicit tracks or full-width spans.</dont>
+  <tsx><![CDATA[
+<Grid filling="fill" colMinWidth="16rem" rowGap="m" columnGap="m">
+  <Grid.Item>
+    <Surface color={1} border="all" radius="m" hPadding="m" vPadding="m">
+      <Stack rowGap="s">
+        <Text weight="m">Inbox</Text>
+        <Text size="sm" color="muted">
+          Unread threads
+        </Text>
+      </Stack>
+    </Surface>
+  </Grid.Item>
+  <Grid.Item>
+    <Surface color={1} border="all" radius="m" hPadding="m" vPadding="m">
+      <Stack rowGap="s">
+        <Text weight="m">Archive</Text>
+        <Text size="sm" color="muted">
+          Stored mail
+        </Text>
+      </Stack>
+    </Surface>
+  </Grid.Item>
+</Grid>
+]]></tsx>
+</pattern>

package/dist/specs/patterns/compose-layout-first.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pattern id="compose-layout-first" title="Compose layout primitives first">
+  <uses>
+    <ref id="stack" units="meta,usage,props" />
+    <ref id="surface" units="meta,usage,props" />
+    <ref id="text" units="meta" />
+    <ref id="button" units="meta" />
+    <ref id="grid" units="meta,usage" />
+    <ref id="masonry" units="meta,usage" />
+    <ref id="bleed" units="meta,usage" />
+  </uses>
+  <do>Prefer Vira layout roots (`Stack`, `Grid`, `Masonry`, `Bleed`, `Surface`) and their public props for every consumer layout. Treat `Stack` as the default box: an enriched `div` (flex + gap/padding/align/`fullWidth`/`render`/…) — prefer it over bare wrapper `div`s even for simple nesting. Compose and nest components; add custom CSS only when props cannot express size/scroll/basis. Prefer another Vira component (e.g. `Surface` for border/fill/radius) or `render` merge over a CSS class for chrome the library already owns.</do>
+  <dont>Do not invent bare wrapper `div`s (or `display:flex` / `display:grid` / CSS `gap` / `padding` / border/radius chrome on raw tags) when `Stack` or another layout primitive / `Surface` covers it. Do not skip composition to reach for a one-off stylesheet.</dont>
+  <tsx><![CDATA[
+{/* Flex row + panel chrome: one DOM node via Stack render={<Surface />} */}
+<Stack
+  direction="row"
+  columnGap="m"
+  vAlign="center"
+  fullWidth
+  expandChildren
+  render={
+    <Surface border="all" color={1} radius="m" hPadding="m" vPadding="m" />
+  }
+>
+  <Text weight="m">Profile</Text>
+  <Button variant="secondary" data-grow="false">
+    Edit
+  </Button>
+</Stack>
+]]></tsx>
+</pattern>

package/dist/specs/patterns/equal-width-actions.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pattern id="equal-width-actions" title="Equal-width action row">
+  <uses>
+    <ref id="stack" units="meta,usage,props" />
+    <ref id="button" units="meta,props" />
+  </uses>
+  <do>Span or share space with Stack `fullWidth` and/or `expandChildren` (and control `fullWidth` when the surface owns it). Orthogonal: `fullWidth` sizes the Stack; `expandChildren` grows direct children on the main axis.</do>
+  <dont>Do not invent `width: 100%` / `w-full` / per-child `flex: 1` CSS on Button (or other content-sized controls) when Stack can own the fill.</dont>
+  <tsx><![CDATA[
+{/* Full-bleed column CTAs */}
+<Stack fullWidth rowGap="s">
+  <Button>Continue</Button>
+  <Button variant="secondary">Cancel</Button>
+</Stack>
+
+{/* Equal-width row actions — children grow on the main axis. Add fullWidth when the Stack itself should fill its parent width */}
+<Stack expandChildren direction="row" columnGap="s">
+  <Button>Continue</Button>
+  <Button variant="secondary">Cancel</Button>
+</Stack>
+]]></tsx>
+</pattern>

package/dist/specs/patterns/page-chrome.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pattern id="page-chrome" title="Page chrome with Stack render">
+  <uses>
+    <ref id="stack" units="meta,usage,props" />
+    <ref id="title" units="meta" />
+    <ref id="button" units="meta" />
+  </uses>
+  <do>Own page/section flex with Stack. Pick semantic tags (`header`, `main`, `nav`, `section`, …) via `render={&lt;tag /&gt;}` — keep Stack as the layout engine. CSS modules may set min-block-size / scroll; never `display:flex`.</do>
+  <dont>Do not use raw `header`/`main`/`nav` + `display:flex` / CSS gap for jobs Stack owns. Tag choice ≠ layout engine.</dont>
+  <tsx><![CDATA[
+<Stack rowGap="m" expandChildren>
+  <Stack
+    direction="row"
+    hAlign="space-between"
+    vAlign="center"
+    columnGap="m"
+    hPadding="m"
+    vPadding="m"
+    render={<header />}
+  >
+    <Title render={<h1 />}>Settings</Title>
+    <Button>Save</Button>
+  </Stack>
+  <Stack direction="row" columnGap="m" expandChildren render={<main />}>
+    <Stack rowGap="xs" hPadding="s" vPadding="s" render={<nav aria-label="Settings" />}>
+      {/* nav links */}
+    </Stack>
+    <Stack rowGap="l" expandChildren>
+      {/* content */}
+    </Stack>
+  </Stack>
+</Stack>
+]]></tsx>
+</pattern>

package/dist/specs/patterns/settings-panel.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pattern id="settings-panel" title="Settings panel (Surface + Stack)">
+  <uses>
+    <ref id="stack" units="meta,usage" />
+    <ref id="surface" units="meta,usage,props" />
+    <ref id="textfield" units="meta" />
+    <ref id="switch" units="meta" />
+    <ref id="text" units="meta" />
+  </uses>
+  <do>Wrap a settings block in Surface for fill/border/radius/padding; nest Stack for child gaps and rows. Compose the settings-row pattern inside for label+control rows. Prefer props over CSS for spacing and chrome.</do>
+  <dont>Do not reimplement card chrome or row flex in app CSS when Surface + Stack cover it.</dont>
+  <tsx><![CDATA[
+<Stack rowGap="m" hPadding="m" vPadding="m">
+  <Surface color={1} border="all" radius="m" hPadding="m" vPadding="m">
+    <Stack rowGap="m">
+      <Textfield label="Display name" fullWidth />
+      <Stack direction="row" vAlign="center" columnGap="m" fullWidth>
+        <Stack rowGap="2xs" expandChildren>
+          <Text weight="m">Notifications</Text>
+          <Text size="sm" color="muted">
+            Email digests for account activity
+          </Text>
+        </Stack>
+        <Switch aria-label="Notifications" />
+      </Stack>
+    </Stack>
+  </Surface>
+</Stack>
+]]></tsx>
+</pattern>