@viraui/react 2026.3.11 → 2026.4.1

package/dist/specs/foundation/attributes.xml

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<attributes>
+  <summary>Data attributes and related CSS custom properties exposed by @viraui/react/preflight.css.</summary>
+  <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>
+    <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>
+  </attr>
+  <attr name="data-no-link-style">
+    <presence>boolean attribute on anchor elements</presence>
+    <effect>Excludes the anchor from preflight default link styling (interactive color, no underline, animated underline on unclassed links).</effect>
+    <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_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>
+    <values>
+      <value>0</value>
+      <value>1</value>
+      <value>2</value>
+      <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>
+  </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>
+    <values>
+      <value>0</value>
+      <value>1</value>
+      <value>2</value>
+      <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>
+  </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>
+    <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>
+  </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>
+    <values>
+      <value>true</value>
+      <value>false</value>
+    </values>
+      <when>Force grow or opt out on an expandChildren direct child</when>
+      <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>
+      <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>
+    <values>
+      <value>true</value>
+      <value>false</value>
+    </values>
+      <when>Force shrink or resist shrink on that flex item</when>
+      <when>Labels, icons, or controls that must keep intrinsic width (false)</when>
+      <when_not>When default flex shrink is already correct</when_not>
+      <when_not>Expecting ancestor data-shrink to change nested flex consumers</when_not>
+      <gotcha>Stack</gotcha>
+      <gotcha>--vira-flex-shrink</gotcha>
+  </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>
+    <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_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>
+      <gotcha>--effect-vibrancy</gotcha>
+      <gotcha>--vibrancy-blur</gotcha>
+      <gotcha>--vibrancy-brightness</gotcha>
+  </attr>
+</attributes>

package/dist/specs/foundation/bootstrap.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bootstrap>
+  <summary>Minimal bootstrap for external apps consuming @viraui/react.</summary>
+  <required_packages>
+    <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>
+  </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>
+  </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>
+  </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>
+    <optional_explicit_import>@viraui/react/&lt;component&gt;.css for tree-shaking or debugging only; not part of default bootstrap.</optional_explicit_import>
+  </component_css>
+  <cascade_layers>
+    <order>viraui.preflight, viraui.components, viraui.overrides</order>
+    <rule>Preflight owns the canonical @layer order; component CSS re-declares the same order. Unlayered app CSS beats all Vira layers.</rule>
+  </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>
+  </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>
+    <tree>Dialog.Provider</tree>
+    <tree>Dialog.IndentBackground (sibling of Indent)</tree>
+    <tree>Dialog.Indent (wraps app + toast viewport)</tree>
+    <tree>Tooltip.Provider</tree>
+    <tree>Toast.Provider toastManager={toastManager}</tree>
+    <tree>children</tree>
+    <tree>Toast.Portal &gt; Toast.Viewport &gt; Toast.Banner per toast</tree>
+    <next_js>Keep CSS side-effect imports in the Server Component root layout. Put the provider tree in a Client Component that wraps children.</next_js>
+    <astro>React context does not cross Astro islands. Providers must live in the same island as the Vira overlays that consume them.</astro>
+    <rtl>For RTL menus and popups, wrap with Base UI DirectionProvider direction="rtl" and set dir="rtl" on a portal ancestor (usually html).</rtl>
+  </root_providers>
+  <next_js_app_router>
+    <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 './globals.css';
+]]></tsx>
+  </next_js_app_router>
+  <discovery>
+    <path>@viraui/react/catalog.json</path>
+    <path>@viraui/react/specs/PROTOCOL.md</path>
+    <path>@viraui/react/specs/index.xml</path>
+    <path>@viraui/react/specs/foundation/*.xml</path>
+    <path>@viraui/react/specs/components/&lt;id&gt;/*.xml</path>
+  </discovery>
+</bootstrap>

package/dist/specs/foundation/elevation.xml

@@ -0,0 +1,21 @@
+<?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>
+  <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>
+  <dont>Do not pass elevation={…} on Surface — use Elevator / getElevationProps / data-elevation*.</dont>
+  <dont>Do not hand-roll box-shadow; elevation needs --effect-shadows on the active theme.</dont>
+  <api name="getElevationProps">
+    <description>Returns data-elevation* attributes plus --shadow-color / --extra-shadow style hooks from resting, hover, direction, shadowColor, and extraShadow.</description>
+    <tsx><![CDATA[
+import { getElevationProps } from '@viraui/react';
+
+const { attributes, style } = getElevationProps({ resting: 2, hover: 3 });
+<div {...attributes} style={style} />
+]]></tsx>
+  </api>
+  <related>
+    <ref id="elevator" />
+    <ref id="foundation-attributes" />
+  </related>
+</elevation>

package/dist/specs/foundation/meta.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="core" title="Core / preflight" category="foundation" shared_contract="core">
+  <summary>Preflight CSS, consumer bootstrap, data-* hooks, core CSS toggles (polarity + effects), elevation helpers, and theme token topic map shipping with @viraui/react.</summary>
+  <exports>
+    <export name="getElevationProps" />
+  </exports>
+  <related>
+    <ref id="elevator" />
+    <ref id="surface" />
+    <ref id="stack" />
+  </related>
+  <units>
+    <unit kind="bootstrap" href="bootstrap.xml" />
+    <unit kind="attributes" href="attributes.xml" />
+    <unit kind="toggles" href="toggles.xml" />
+    <unit kind="theme-topics" href="theme-topics.xml" />
+    <unit kind="elevation" href="elevation.xml" />
+    <unit kind="modules" href="modules.xml" />
+  </units>
+</meta>

package/dist/specs/foundation/modules.xml

@@ -0,0 +1,62 @@
+<?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>
+  </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>
+  <module id="typography" file="typography.css">
+    <purpose>Semantic HTML element typography and link styling opt-out.</purpose>
+  </module>
+  <module id="elevations" file="elevations.css">
+    <purpose>Theme-gated resting and hover box-shadow elevation stacks plus unlayered box-shadow transitions.</purpose>
+  </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>
+  <module id="vibrancy" file="vibrancy.css">
+    <purpose>Theme-gated backdrop-filter vibrancy on elements that opt in with data-vibrant.</purpose>
+  </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>
+    <default>black</default>
+    <set_by>html root in core.css from contrast-color(var(--global-background))</set_by>
+  </custom_property>
+  <custom_property name="--shadow-color">
+    <purpose>Shadow tint for data-elevation stacks.</purpose>
+    <default>oklch(0% 0 0)</default>
+    <set_by>inline style or component elevation mapping</set_by>
+  </custom_property>
+  <custom_property name="--extra-shadow">
+    <purpose>Additional box-shadow layer appended to elevation stacks, for example hairline borders.</purpose>
+    <default>0 0 0 1px transparent</default>
+    <set_by>inline style or component elevation mapping</set_by>
+  </custom_property>
+  <custom_property name="--elevation-transition-duration">
+    <purpose>Duration for data-elevation box-shadow transitions.</purpose>
+    <default>160ms</default>
+    <set_by>inline style or theme override</set_by>
+  </custom_property>
+  <custom_property name="--elevation-transition-easing">
+    <purpose>Timing function for data-elevation box-shadow transitions.</purpose>
+    <default>ease</default>
+    <set_by>inline style or theme override</set_by>
+  </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>
+  <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>
+  <custom_property name="--__corner-shape">
+    <purpose>Internal override for the preflight corner-shape gate so infinite 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 infinite 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 infinite / pill radius (CSS modules or React style); registered in global-properties.css</set_by>
+  </custom_property>
+</modules>

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

@@ -0,0 +1,60 @@
+<?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>Load compatible theme CSS, then consumer fonts, then @viraui/react/preflight.css via JS side-effect imports.</summary>
+  </topic>
+  <topic id="base">
+    <pattern>--base-*</pattern>
+    <summary>Semantic neutral ramp for surfaces and text on themed backgrounds.</summary>
+  </topic>
+  <topic id="global">
+    <pattern>--global-*</pattern>
+    <summary>App-facing foreground, background, primary, muted, interactive, disabled, and contrast colors.</summary>
+  </topic>
+  <topic id="effects">
+    <pattern>--effect-vibrancy | --effect-corner-shape | --effect-holofoil | --effect-shadows</pattern>
+    <summary>Optional effect toggles; empty/unset = on, initial = off. Brand holofoil defaults to initial (off); vibrancy, corner-shape, and shadows default empty (on). Holofoil on paints a fixed body::after foil overlay; shadows off disables preflight data-elevation box-shadow stacks.</summary>
+  </topic>
+  <topic id="vibrancy">
+    <pattern>--vibrancy-blur | --vibrancy-brightness</pattern>
+    <summary>Vibrancy glass params; blur is a numeric amount consumed as pixels, brightness is a percent string.</summary>
+  </topic>
+  <topic id="highlight">
+    <pattern>--highlight-*</pattern>
+    <summary>Status and decorative highlight palette.</summary>
+  </topic>
+  <topic id="radius">
+    <pattern>--radius-* | --corner-shape</pattern>
+    <summary>Semantic radius scale plus corner-shape value for component chrome. Infinite/pill radius with --effect-corner-shape on can cap true pills; ViraUI sets internal --__corner-shape (preflight-owned, not a consumer data-*) beside infinite radius.</summary>
+  </topic>
+  <topic id="space">
+    <pattern>--space-*</pattern>
+    <summary>Semantic spacing scale for layout and component padding.</summary>
+  </topic>
+  <topic id="font-root-size">
+    <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>
+  </topic>
+  <topic id="font-scale">
+    <pattern>--font-scale-*</pattern>
+    <summary>Semantic typography sizes including display, headings, and body steps.</summary>
+  </topic>
+  <topic id="font-family">
+    <pattern>--font-family-heading | --font-family-body | --font-family-mono</pattern>
+    <summary>Semantic font-family touchpoints; consumers must provide matching @font-face rules.</summary>
+  </topic>
+  <topic id="font-leading">
+    <pattern>--font-leading-*</pattern>
+    <summary>Semantic line-height scale for text and title components.</summary>
+  </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">
+    <pattern>--duration-* | --easing-*</pattern>
+    <summary>Duration and easing tokens for component motion.</summary>
+  </topic>
+</theme_topics>

package/dist/specs/foundation/toggles.xml

@@ -0,0 +1,25 @@
+<?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, and shadows 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.</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>
+    <when>data-mode=&quot;inverted&quot; flips color-scheme against the root value: @container root style(--is-light-mode: black) → dark; style(--is-light-mode: white) → light.</when>
+    <when>Component/preflight CSS branches on polarity with @container root style(--is-light-mode: black) or white — e.g. vibrancy brightness, holofoil mix-blend, Button/Chip secondary fills. Do not invent alternate light/dark hooks.</when>
+  </toggle>
+  <toggle name="--effect-shadows">
+    <when>Empty/unset enables data-elevation box-shadow stacks; set to initial to disable. Preflight gates with @container root not style(--effect-shadows: initial). Do not hand-roll box-shadow.</when>
+  </toggle>
+  <toggle name="--effect-vibrancy">
+    <when>Empty/unset enables data-vibrant backdrop filters; set to initial to disable. Preflight gates with @container root not style(--effect-vibrancy: initial); vibrancy may further branch on --is-light-mode. Do not hand-roll backdrop-filter.</when>
+  </toggle>
+  <toggle name="--effect-corner-shape">
+    <when>Empty/unset enables theme corner-shape on *; set to initial to disable. Preflight gates with @container root not style(--effect-corner-shape: initial) and applies var(--__corner-shape, var(--corner-shape)). Pair with --corner-shape token.</when>
+  </toggle>
+  <toggle name="--effect-holofoil">
+    <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="--corner-shape">
+    <when>Theme corner shape token; preflight may set internal --__corner-shape beside infinite radius. Not a consumer data-*.</when>
+  </toggle>
+</toggles>