@viraui/react 2026.6.0 → 2026.6.2

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

@@ -1,12 +1,116 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="tooltip">
-  <example title="Tooltip structure">
-    <tsx><![CDATA[<Tooltip.Provider>
+  <!-- Sources: viraui-app/components + design-kitchen preview-grid — cleaned (no handlers, no portal/preview chrome). -->
+
+  <example title="Provider wrap">
+    <tsx><![CDATA[
+<Tooltip.Provider>
+  {/* app / toolbar tree */}
+</Tooltip.Provider>
+]]></tsx>
+    <notes>From `providers/providers` (+ preview providers). One Provider groups adjacent tooltips for shared open/close delay.</notes>
+  </example>
+
+  <example title="Canvas zoom chip">
+    <tsx><![CDATA[
+<Tooltip>
+  <Tooltip.Trigger
+    render={
+      <Surface color={1} border="all" radius="m" vPadding="2xs" hPadding="2xs" aria-label="100%">
+        <Stack direction="row" vAlign="center">
+          <IconButton aria-label="Zoom out" icon={<Minus aria-hidden size="1rem" />} variant="flat" />
+          <IconButton aria-label="Reset zoom" icon={<FocusCenter aria-hidden size="1rem" />} variant="flat" />
+          <IconButton aria-label="Zoom in" icon={<Plus aria-hidden size="1rem" />} variant="flat" />
+        </Stack>
+      </Surface>
+    }
+  />
+  <Tooltip.Content side="bottom">100%</Tooltip.Content>
+</Tooltip>
+]]></tsx>
+    <notes>From `editor/canvas/canvas-zoom`. Whole chip is the Trigger; Content shows current zoom. Absolute shell position stays outside this hint.</notes>
+  </example>
+
+  <example title="Shuffle lock toggle">
+    <tsx><![CDATA[
+<Tooltip>
+  <Tooltip.Trigger
+    render={
+      <ToggleButton
+        aria-label="Shuffle lock"
+        pressed={false}
+        variant="flat"
+        restingIcon={<LockOpen2 aria-hidden size="1rem" />}
+        pressedIcon={<Lock aria-hidden size="1rem" />}
+      />
+    }
+  />
+  <Tooltip.Content>Unlocked in shuffle</Tooltip.Content>
+</Tooltip>
+]]></tsx>
+    <notes>From `editor/controls/shuffle-lock-toggle`. Icon ToggleButton + short lock state copy. Same shape as primary-color sync Tooltip addon.</notes>
+  </example>
+
+  <example title="Compat hint glyph">
+    <tsx><![CDATA[
+<Tooltip>
+  <Tooltip.Trigger
+    delay={50}
+    render={
+      <span aria-label="Supported by: Chrome, Edge, Firefox">
+        <TriangleWarning aria-hidden size="1rem" color="var(--highlight-yellow)" />
+      </span>
+    }
+  />
+  <Tooltip.Content>
+    <Stack direction="row" columnGap="s" vAlign="center">
+      {/* browser logos */}
+    </Stack>
+  </Tooltip.Content>
+</Tooltip>
+]]></tsx>
+    <notes>From `editor/controls/compat-label`. Non-button Trigger + rich Content row. Drop module CSS classes.</notes>
+  </example>
+
+  <example title="Metric label hint">
+    <tsx><![CDATA[
+<Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
   <Tooltip>
-    <Tooltip.Trigger />
-    <Tooltip.Content />
+    <Tooltip.Trigger
+      render={
+        <Button size="s" variant="flat">
+          APY
+        </Button>
+      }
+    />
+    <Tooltip.Content>
+      <Text size="s">Annual percentage yield after daily compounding on cash sweep.</Text>
+    </Tooltip.Content>
   </Tooltip>
-</Tooltip.Provider>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <Text family="mono" size="s" weight="semibold">
+    4.82%
+  </Text>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `contextual-hints`. Flat Button label as Trigger; Content carries the definition.</notes>
+  </example>
+
+  <example title="Toolbar shared handle">
+    <tsx><![CDATA[
+const toolbarHandle = Tooltip.createHandle<string>();
+
+<Tooltip.Trigger
+  closeDelay={200}
+  handle={toolbarHandle}
+  payload="Duplicate"
+  render={<Duplicate size={22} aria-label="Duplicate" />}
+/>
+{/* more Icon triggers with the same handle… */}
+
+<Tooltip handle={toolbarHandle}>
+  {({ payload }) => <Tooltip.Content>{payload as string}</Tooltip.Content>}
+</Tooltip>
+]]></tsx>
+    <notes>From preview-grid `action-toolbar` (+ team-directory mute Badge). One `createHandle` morphs Content across many triggers.</notes>
   </example>
 </patterns>

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

@@ -14,7 +14,7 @@
   <prop name="Content.container" kind="react">
     <description>Portal mount node (iframe body, shadow root, or app overlay root). Omit for Base UI default (`document.body` from the module window — iframe hosts must pass the iframe document body explicitly).</description>
   </prop>
-  <css_var suffix="content-fade-duration">
+  <prop name="content-fade-duration" kind="css">
     <description>content fade duration custom property on the component root.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="tooltip">
-  <do>Short hints on hover or focus for toolbar controls and icon buttons</do>
-  <do>Per-trigger labels on shared tooltip roots using `payload` and Root render-function children</do>
-  <do>Adjacent controls that benefit from shared open/close delay via `Tooltip.Provider`</do>
-  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <do>Short hover/focus hints on IconButton, ToggleButton, flat Button, or glyph triggers</do>
+  <do>Wrap adjacent tooltips in `Tooltip.Provider` for shared open/close delay</do>
+  <do>Compose Trigger via `render` (Surface chip, IconButton, ToggleButton) — Content holds the short copy</do>
+  <do>Shared toolbar labels: `Tooltip.createHandle` + Trigger `payload` + Root render-function children</do>
+  <do>Custom portal host via `container` on `Tooltip.Content`</do>
+  <do>Use Tooltip for concise hints; use Popover for rich panels, links, forms, or content that must stay open under pointer</do>
+  <do>Use Toast for system-wide transient alerts — not Tooltip</do>
   <dont>Putting essential-only information in a tooltip with no accessible name on the trigger</dont>
   <dont>Expecting `Tooltip.Arrow` (it is intentionally not exported or rendered)</dont>
-  <dont>Using tooltip for modal or focus-trapped tasks</dont>
+  <dont>Using tooltip for modal or focus-trapped tasks — use Dialog or Popover</dont>
 </usage>

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

@@ -1,7 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="typewriter">
-  <example title="Typewriter structure">
-    <tsx><![CDATA[<Typewriter>…</Typewriter>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components/auth/login-view — cleaned (no i18n / mobile branching). -->
+
+  <example title="Auth hero cycle">
+    <tsx><![CDATA[
+<Title size="1" render={<h1 />} maxWidth="32rem" lineHeight="s">
+  <Typewriter
+    texts={[
+      'Ship real UI at the speed of thought.',
+      'Ship real UI at the speed of your LLM.',
+      'Ship real UI at the speed of your team.',
+    ]}
+    preserveSpace
+    caret="underscore"
+    caretColor="var(--base-5)"
+  />
+</Title>
+]]></tsx>
+    <notes>From `auth/login-view`. Typewriter nests inside Title for display preset + `h1`. `preserveSpace` holds layout through phrase cycle; caret themed via `caretColor`. Only app usage found.</notes>
   </example>
 </patterns>

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

@@ -37,7 +37,7 @@
   <prop name="texts" kind="react">
     <description>Cycles through multiple phrases instead of a single `children` string.</description>
   </prop>
-  <css_var suffix="caret-color">
+  <prop name="caret-color" kind="css">
     <description>Typewriter caret color.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,11 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="typewriter">
-  <do>Hero or marketing copy that cycles through short phrases</do>
-  <do>Loading or status labels that reveal text progressively</do>
-  <do>Muted intro copy inside Text or Title where motion adds emphasis</do>
-  <dont>Using Typewriter as the only source of critical status information</dont>
-  <dont>Embedding layout positioning rules inside the component stylesheet</dont>
-  <dont>Restarting animation on every parent render by passing unstable inline text arrays without stable content</dont>
-  <dont>Setting parent Text or Title trim={false} solely so preserveSpace can reserve wrapped height</dont>
-  <dont>Driving per-character typing through React state (use DOM writes on the typed layer instead)</dont>
+  <do>Nest inside Title or Text so size/tone/heading `render` live on the parent — Typewriter stays decorative typed copy</do>
+  <do>Hero / marketing phrase cycles via `texts` + `preserveSpace` so layout holds through type/delete (see auth Title compose)</do>
+  <do>Caret via `caret` / `caretColor`; timing via `speed` / `deleteSpeed` / `pause` / `delay` / `loop`</do>
+  <do>Loading shimmer on static copy is Shimmer inside Text/Title — Typewriter when progressive letter reveal is the intent</do>
+  <dont>Using Typewriter as the only source of critical status without a labeled surrounding region</dont>
+  <dont>Passing unstable inline `texts` arrays that restart the cycle on every parent render</dont>
+  <dont>Setting parent Text/Title `trim={false}` solely so `preserveSpace` can reserve wrapped height</dont>
+  <dont>Driving per-character typing through React state — typed layer uses DOM text writes</dont>
+  <dont>Expecting reduced-motion users to see every phrase in a multi-text cycle — final phrase shows immediately</dont>
 </usage>

package/dist/specs/foundation/attributes.xml

@@ -4,18 +4,18 @@
   <prerequisite>Import compatible theme CSS, then @viraui/react/preflight.css. See foundation/bootstrap.xml.</prerequisite>
   <attr name="data-mode">
     <presence>value required</presence>
-    <effect>Narrows color-scheme on the element subtree: light forces light, dark forces dark, inverted flips color-scheme relative to the active theme using --is-light-mode on the root container.</effect>
+    <effect>Narrows color-scheme on the element subtree: light forces light, dark forces dark, inverted flips color-scheme relative to the active theme using --is-light-mode on the root container. (autoamtic in preflight).</effect>
     <values>
       <value>light</value>
       <value>dark</value>
       <value>inverted</value>
     </values>
-      <when>Toggle runtime light or dark mode on html, body, or a layout wrapper</when>
-      <when>Scope a subtree to one mode while the rest of the page stays unchanged</when>
-      <when>Invert color-scheme on a nested surface that must contrast the active theme, for example a primary Chip addon inside a primary Button</when>
-      <when_not>As a substitute for loading compatible theme CSS</when_not>
-      <when_not>To swap brand stylesheets; use theme CSS imports instead</when_not>
-      <gotcha>data-mode is independent from brand stylesheet selection; see runtime-enhancements.md</gotcha>
+    <when>Toggle runtime light or dark mode on html, body, or a layout wrapper</when>
+    <when>Scope a subtree to one mode while the rest of the page stays unchanged</when>
+    <when>Invert color-scheme on a nested surface that must contrast the active theme, for example a dark content section inside a light theme</when>
+    <when_not>As a substitute for loading compatible theme CSS</when_not>
+    <when_not>To swap brand stylesheets; use theme CSS imports instead and use the attribute data-mode as flag only</when_not>
+    <gotcha>data-mode is independent from brand stylesheet selection that may expose or not light and dark modes;</gotcha>
   </attr>
   <attr name="data-no-link-style">
     <presence>boolean attribute on anchor elements</presence>
@@ -23,14 +23,17 @@
     <values>
       <value>(boolean presence)</value>
     </values>
-      <when>Links that must keep component-owned or custom link chrome</when>
-      <when>Anchors inside Button, IconButton, or other interactive surfaces</when>
+      <when>Links that must keep component-owned or custom link chrome like linked Surfaces or other components</when>
+      <when>Anchors with their own link styling</when>
       <when_not>Standard inline prose links that should inherit preflight link styling</when_not>
 
   </attr>
   <attr name="data-elevation">
     <presence>value required</presence>
-    <effect>When the active theme sets --effect-shadows, applies resting box-shadow stack for the chosen elevation level.</effect>
+    <reference>elevation.xml</reference>
+    <effect>
+      Shadow depth only — not z-index / paint order. When the active theme leaves --effect-shadows empty or unset, applies the preflight box-shadow stack for the chosen level (0–4). Same numbers usually align with stacking vocabulary, but this attr never changes stacking; set z-index separately when paint order must change.
+    </effect>
     <values>
       <value>0</value>
       <value>1</value>
@@ -38,18 +41,22 @@
       <value>3</value>
       <value>4</value>
     </values>
-      <when>Static surfaces such as cards, panels, and popovers</when>
-      <when>Direct DOM usage without the Elevator component</when>
-      <when_not>When Elevator or getElevationProps already sets elevation hooks on the target element</when_not>
-      <when_not>When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)</when_not>
-      <gotcha>Elevator</gotcha>
-      <gotcha>Surface</gotcha>
-      <gotcha>getElevationProps</gotcha>
-      <gotcha>--effect-shadows</gotcha>
+    <when>Raw DOM hosts that need resting shadow when Elevator / getElevationProps do not fit</when>
+    <when>Static surfaces such as cards, panels, and popovers that should read raised</when>
+    <when_not>When Elevator or getElevationProps already sets elevation hooks on the target element — prefer those for React nodes</when_not>
+    <when_not>As a substitute for z-index; raising shadow does not move a surface above sticky headers or modals</when_not>
+    <when_not>When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow; surface stays flat)</when_not>
+    <when_not>On Surface via an elevation prop — Surface has none; wrap with Elevator or use getElevationProps / these attrs</when_not>
+    <gotcha>Prefer Elevator or getElevationProps on React elements; raw data-elevation* only when those utilities do not fit. Full compose guidance: elevation.xml.</gotcha>
+    <gotcha>Empty/unset --effect-shadows = shadows on; initial = off. Attrs may remain while stacks stay flat.</gotcha>
+    <gotcha>Do not hand-roll box-shadow; elevation stacks need the theme gate and preflight.</gotcha>
   </attr>
   <attr name="data-elevation-hover">
     <presence>optional value</presence>
-    <effect>When the active theme sets --effect-shadows, applies a different elevation level on :hover than the resting data-elevation value.</effect>
+    <reference>elevation.xml</reference>
+    <effect>
+      When --effect-shadows is on, applies a different elevation level on :hover than the resting data-elevation value. Shadows only — does not change z-index. Pair with data-elevation for resting and hover depth (e.g. card that lifts on hover).
+    </effect>
     <values>
       <value>0</value>
       <value>1</value>
@@ -57,33 +64,48 @@
       <value>3</value>
       <value>4</value>
     </values>
-      <when>Interactive surfaces that should lift on hover</when>
-      <when>Pair with data-elevation for resting and hover shadow levels</when>
-      <when_not>When hover elevation is not desired; omit the attribute entirely</when_not>
-      <when_not>When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)</when_not>
-      <gotcha>Elevator</gotcha>
-      <gotcha>getElevationProps</gotcha>
-      <gotcha>--effect-shadows</gotcha>
+    <when>Interactive surfaces that should lift on hover</when>
+    <when>Pair with data-elevation for resting and hover shadow levels</when>
+    <when_not>When hover elevation is not desired; omit the attribute entirely</when_not>
+    <when_not>When Elevator hover={…} or getElevationProps already maps hover on the target</when_not>
+    <when_not>When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)</when_not>
+    <gotcha>Prefer Elevator resting/hover props or getElevationProps; raw attrs only when utilities do not fit.</gotcha>
+    <gotcha>Hover shadow does not change stacking order.</gotcha>
+    <tsx><![CDATA[
+<div data-elevation="1" data-elevation-hover="4">
+  {/* subtle rest; lifts more on hover */}
+</div>
+]]></tsx>
   </attr>
   <attr name="data-elevation-direction">
     <presence>optional; defaults to bottom when data-elevation is present</presence>
-    <effect>When the active theme sets --effect-shadows, casts the shadow downward, upward, to the left, or to the right.</effect>
+    <reference>elevation.xml</reference>
+    <effect>
+      When --effect-shadows is on, casts the shadow downward (bottom), upward (top), to the left, or to the right. Direction is appearance only — not stacking.
+    </effect>
     <values>
       <value>bottom</value>
       <value>top</value>
       <value>left</value>
       <value>right</value>
     </values>
-      <when>Side drawers, top bars, or lateral panels where shadow direction matters</when>
-      <when_not>When default bottom cast is sufficient</when_not>
-      <when_not>When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)</when_not>
-      <gotcha>Elevator</gotcha>
-      <gotcha>getElevationProps</gotcha>
-      <gotcha>--effect-shadows</gotcha>
+    <when>Side drawers, top bars, or lateral panels where shadow cast direction matters</when>
+    <when_not>When default bottom cast is sufficient</when_not>
+    <when_not>When Elevator direction={…} or getElevationProps already sets direction on the target</when_not>
+    <when_not>When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)</when_not>
+    <gotcha>Prefer Elevator direction or getElevationProps; raw attrs only when utilities do not fit.</gotcha>
+    <tsx><![CDATA[
+<aside data-elevation="2" data-elevation-direction="left">
+  {/* drawer — shadow casts left */}
+</aside>
+]]></tsx>
   </attr>
   <attr name="data-grow">
     <presence>optional; omit for default flex growth</presence>
-    <effect>Affects only the element: true sets --vira-flex-grow: 1 and flex-grow: 1; false sets --vira-flex-grow: 0 and flex-grow: 0. Custom props are registered inherits: false so ancestors do not poison nested Stack expandChildren.</effect>
+    <effect>
+      Affects only the element: true sets --vira-flex-grow: 1 and flex-grow: 1; false sets --vira-flex-grow: 0 and flex-grow: 0. Custom props are registered inherits: false so ancestors do not poison nested Stack expandChildren.
+      Generally this attribute is used on children of a Stack to force/prevent grow on specific children while keeping the default flex growth for the rest of the children.
+    </effect>
     <values>
       <value>true</value>
       <value>false</value>
@@ -92,12 +114,16 @@
       <when>Fixed-width icons, indicators, or trailing slots (false)</when>
       <when_not>When default flex growth is already correct</when_not>
       <when_not>Expecting ancestor data-grow to change nested expandChildren children</when_not>
+      <when_not>Inventing width: 100% CSS on Button/Chip instead of Stack fullWidth / expandChildren</when_not>
       <gotcha>Stack</gotcha>
       <gotcha>--vira-flex-grow</gotcha>
   </attr>
   <attr name="data-shrink">
     <presence>optional; omit for default flex shrink</presence>
-    <effect>Affects only the element: true sets --vira-flex-shrink: 1 and flex-shrink: 1; false sets --vira-flex-shrink: 0 and flex-shrink: 0. Custom props are registered inherits: false.</effect>
+    <effect>
+      Affects only the element: true sets --vira-flex-shrink: 1 and flex-shrink: 1; false sets --vira-flex-shrink: 0 and flex-shrink: 0. Custom props are registered inherits: false.
+      Generally this attribute is used on children of a Stack to force/prevent shrink on specific children while keeping the default flex shrink for the rest of the children.
+    </effect>
     <values>
       <value>true</value>
       <value>false</value>
@@ -111,12 +137,16 @@
   </attr>
   <attr name="data-vibrant">
     <presence>boolean attribute; value ignored</presence>
-    <effect>When the active theme sets --effect-vibrancy, applies vibrancy backdrop-filter (brightness/blur/saturate). Surface with data-vibrant translucifies its fill via component CSS: without color, frosted shell from --global-background; with color, 80% tint from --vui-surface-background.</effect>
+    <effect>
+      When the active theme sets --effect-vibrancy, applies vibrancy backdrop-filter (brightness/blur/saturate). Surface with data-vibrant translucifies its fill via component CSS: it doesn't apply a background color to the element, that still need to be set by the consumer.
+      Only the  urface component applies the correct `color` prop based on the presence of the attribute. For custom styles you need to set the background color explicitly if you need one.
+      In built-in themes, the applied backdrop-filter is different based on the active theme mode: light or dark.
+    </effect>
     <values>
       <value>(boolean presence)</value>
     </values>
       <when>Glass / frosted panels on Surface or other hosts over busy backgrounds</when>
-      <when>Match overlay chrome (Dialog/Popover/Menu/Toast) that ships with data-vibrant</when>
+      <when>Match overlay chrome (Dialog/Popover/Menu/Toast) that ships with data-vibrant internally</when>
       <when_not>When the theme does not expose --effect-vibrancy (attr is a no-op for filters)</when_not>
       <when_not>Hand-rolling backdrop-filter CSS instead of the documented attr</when_not>
       <gotcha>Surface</gotcha>

package/dist/specs/foundation/bootstrap.xml

@@ -5,16 +5,16 @@
     <package name="@viraui/react">Public components, preflight CSS, and package specs.</package>
     <package name="react">Peer dependency.</package>
     <package name="react-dom">Peer dependency.</package>
-    <package name="@base-ui/react">Peer dependency for wrapped primitives.</package>
+    <package name="@base-ui/react">Peer dependency for wrapped primitives. Always install the version that matches the @viraui/react major/minor peer dependency version, patches are free to change.</package>
   </required_packages>
   <optional_packages>
-    <package name="@viraui/foundation">Preset Vira brand theme CSS, ThemeTypes, and JSON only.</package>
-    <package name="@viraui/icons">Optional Vira content glyphs (@viraui/icons/react). Icon slots accept any ReactNode.</package>
+    <package name="@viraui/foundation">Preset Vira brand theme CSS, ThemeTypes, and design tokens only.</package>
+    <package name="@viraui/icons">Optional ViraUI iconography (@viraui/icons/react). Icon slots accept any ReactNode.</package>
   </optional_packages>
   <import_order>
-    <step>Compatible theme CSS (preset @viraui/foundation/vira.css, custom theme CSS, or future theme-builder export)</step>
     <step>Consumer font CSS or @font-face rules matching theme font-family strings</step>
     <step>@viraui/react/preflight.css</step>
+    <step>Compatible theme CSS (preset @viraui/foundation/vira.css, custom theme CSS, or future theme-builder export)</step>
   </import_order>
   <component_css>
     <rule>Import public components from the @viraui/react root barrel. Component CSS follows the JS module graph through side-effect CSS imports.</rule>
@@ -26,7 +26,7 @@
   </cascade_layers>
   <import_mechanism>
     <rule>Load theme CSS, font CSS, and preflight through JavaScript side-effect imports in the app root entry module.</rule>
-    <forbidden>Do not bootstrap Vira theme, font, or preflight CSS with CSS @import in a global stylesheet. Do not require per-component CSS imports in app bootstrap.</forbidden>
+    <forbidden>Bootstrap Vira theme, font, or preflight CSS with CSS @import in a global stylesheet only if the consumer project requires it. Do not require per-component CSS imports in app bootstrap.</forbidden>
   </import_mechanism>
   <root_providers>
     <rule>After CSS bootstrap, wrap the app tree once in Dialog.Provider, Dialog.IndentBackground, Dialog.Indent, Tooltip.Provider, and Toast.Provider. Toast.createToastManager() stays at module scope. Map Toast.useToastManager().toasts to Toast.Banner inside Toast.Portal and Toast.Viewport.</rule>
@@ -45,10 +45,10 @@
     <rule>In Next.js App Router apps, import theme CSS, font CSS, and @viraui/react/preflight.css as JavaScript side-effect imports in root app/layout.tsx; never bootstrap them with CSS @import in globals.css.</rule>
     <entry_module>app/layout.tsx</entry_module>
     <tsx><![CDATA[
-import '@viraui/foundation/vira.css';
 import '@fontsource-variable/geist/wght.css';
 import '@fontsource-variable/geist-mono/wght.css';
 import '@viraui/react/preflight.css';
+import '@viraui/foundation/vira.css';
 import './globals.css';
 ]]></tsx>
   </next_js_app_router>

package/dist/specs/foundation/elevation.xml

@@ -1,12 +1,41 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <elevation>
-  <summary>Elevation on React nodes prefers Elevator or getElevationProps; raw data-elevation* only when those do not fit. Surface has no elevation prop.</summary>
-  <do>Use Elevator or getElevationProps for React elements that need resting/hover shadow stacks.</do>
+  <summary>Elevation is shadow depth, not paint order. Apply shadows with Elevator or getElevationProps; raw data-elevation* only when those do not fit. Surface has no elevation prop. Elevator never sets z-index — stacking is a separate control that usually shares the same 0–4 vocabulary.</summary>
+  <concept>
+    A raised surface casts a larger, softer shadow. ViraUI maps that to a stepped scale (0–4). z-index is who paints on top of whom. Same layer numbers usually line up so something that looks elevated also stacks where expected, but raising a card's shadow does not move it above a sticky header. A popover that looks elevated but paints under its trigger is a stack problem, not an Elevator problem.
+  </concept>
+  <gate>
+    Shadows respect the --effect-shadows theme gate: empty or unset means on, initial means off. When the gate is off, elevated surfaces stay flat even if data-elevation* attrs remain. Full gate polarity lives in foundation/toggles.xml and Effects theme topics.
+  </gate>
+  <layers>
+    <layer value="0">Plane content — page backgrounds, body, non-lifted surfaces.</layer>
+    <layer value="1">Cards, fields, buttons, and other lightly raised page chrome.</layer>
+    <layer value="2">Anchored overlays above nearby page content — Popover, Tooltip, non-modal sheets.</layer>
+    <layer value="3">Fixed chrome above the page but below blocking modals — sticky header/nav, floating actions.</layer>
+    <layer value="4">Modals, drawers, and global toasts at the top of app UI. Vira overlays already own this layer.</layer>
+  </layers>
+  <do>Use the same stepped numbers for shadow and stacking so depth stays consistent; elevate for appearance, stack for paint order.</do>
+  <do>Prefer Elevator or getElevationProps for React elements that need resting/hover shadow stacks.</do>
   <do>Pass data-elevation / data-elevation-hover values 0–4 and data-elevation-direction bottom|top|left|right on raw DOM when utilities do not fit.</do>
+  <do>Set z-index separately when paint order must change; stay within the built-in 0–4 scale for app UI.</do>
   <dont>Do not pass elevation={…} on Surface — use Elevator / getElevationProps / data-elevation*.</dont>
+  <dont>Do not expect Elevator to change stacking; it never sets z-index.</dont>
   <dont>Do not hand-roll box-shadow; elevation needs --effect-shadows on the active theme.</dont>
+  <dont>Do not copy theme chrome z-index patterns (e.g. body::after holofoil at very high values) to beat modals in app UI.</dont>
+  <api name="Elevator">
+    <description>No-DOM helper: merges data-elevation* and elevation CSS vars onto each valid element child. Shadows only — wrap Surface or other hosts; invalid/non-element children pass through.</description>
+    <tsx><![CDATA[
+import { Elevator, Surface } from '@viraui/react';
+
+<Elevator resting={1} hover={4}>
+  <Surface color={1} radius="m" hPadding="m" vPadding="m">
+    {/* card — shadows change; z-index does not */}
+  </Surface>
+</Elevator>
+]]></tsx>
+  </api>
   <api name="getElevationProps">
-    <description>Returns data-elevation* attributes plus --shadow-color / --extra-shadow style hooks from resting, hover, direction, shadowColor, and extraShadow.</description>
+    <description>Returns data-elevation* attributes plus --shadow-color / --extra-shadow style hooks from resting, hover, direction, shadowColor, and extraShadow. Use on a host you already own.</description>
     <tsx><![CDATA[
 import { getElevationProps } from '@viraui/react';
 
@@ -14,8 +43,27 @@ const { attributes, style } = getElevationProps({ resting: 2, hover: 3 });
 <div {...attributes} style={style} />
 ]]></tsx>
   </api>
+  <api name="data-elevation*">
+    <description>Raw preflight attrs for resting shadow (data-elevation), hover shadow (data-elevation-hover), and cast direction (data-elevation-direction). Prefer Elevator / getElevationProps; reach for raw attrs only when those utilities do not fit. See foundation/attributes.xml.</description>
+    <tsx><![CDATA[
+<div
+  data-elevation="1"
+  data-elevation-hover="2"
+  data-elevation-direction="bottom"
+>
+  {/* raw DOM host — shadows only */}
+</div>
+]]></tsx>
+  </api>
+  <prompt title="Hover-lift card">Give this card a subtle shadow that lifts a bit more on hover. Shadows only — don't change stacking order.</prompt>
+  <prompt title="Popover depth">This popover should look elevated above the page but sit below modals and drawers. The sticky header should stay under modal overlays.</prompt>
+  <prompt title="Flat brand">Turn off drop shadows everywhere so elevated surfaces stay flat. Keep stacking order as it is — this is appearance only.</prompt>
+  <tune>
+    Compose elevation on Elevator and stack with z-index. Retune on the theme whether shadows can run at all via --effect-shadows (and related shadow tokens when the brand softens or hardens depth). Flat brand = set --effect-shadows: initial; attrs may remain but stacks stay flat.
+  </tune>
   <related>
     <ref id="elevator" />
     <ref id="foundation-attributes" />
+    <ref id="foundation-toggles" />
   </related>
 </elevation>