@viraui/react 2026.6.1 → 2026.6.3

package/dist/components/radio/radio-group.d.ts

@@ -8,4 +8,4 @@ import { RadioGroup as RadioGroupPrimitive } from '@base-ui/react';
  * @default Base UI pass-through props keep upstream defaults.
  */
 export type RadioGroupProps<Value = string> = RadioGroupPrimitive.Props<Value>;
-export declare const RadioGroup: <Value>({ children, className, ...otherProps }: RadioGroupProps<Value>) => import("react").JSX.Element;
+export declare const RadioGroup: <Value>({ children, className, ...otherProps }: RadioGroupProps<Value>) => import('react').JSX.Element;

package/dist/specs/PROTOCOL.md

@@ -39,6 +39,17 @@ Prefer opening via package export / that `dist/specs/` tree. The `version` attri
 3. Examples / stories — examples only; never API authority.
 4. Skills prose — routers and playbooks only; never a second encyclopedia of component API facts.
 
+## Compose with the system (mandatory)
+
+Consumer agents build screens **with** ViraUI — public parts, compounds, and props from the units — not **around** it with immediate CSS overrides.
+
+1. Index → activity load → open `meta` / `props` / `usage` for every Vira surface you touch **before** JSX that invents classNames or a CSS module targeting those roots.
+2. Prefer another Vira part or public prop over custom CSS (layout → `Stack`/`Grid`/`Masonry`/`Bleed`/`Surface`; fill → `fullWidth` / `expandChildren`; type → `Text`/`Title` props; chrome → `Surface` / `Elevator`).
+3. Custom CSS defaults to **app chrome the system does not own** (page backdrop image, document scrollport, one-off marketing layout). It is **not** a license to reshape Vira control geometry, reinvent owned props, or “fix” controls that already look correct under theme + preflight — **unless the consumer expressly requests** that override / personalization. A future override layer will own formal customization hooks; until then, still open `props`/`usage` first and apply only the asked CSS.
+4. If `usage.xml` lists a **dont** against the CSS you are about to write and the consumer did **not** expressly override that guidance — stop. Do not ship it.
+
+Opening a CSS module on a Vira root without having opened that surface’s `props.xml` + `usage.xml` is a protocol defect. Unsolicited reshape CSS (no consumer ask) is the same defect.
+
 ## Forbidden discovery
 
 Do **not** `ls` / `rg` / `grep` `dist/components/**` or `*.d.ts` to discover Vira API **before** opening the index and target units. Types are for verification after units — open the specific `.d.ts` with Read if needed; do not shell-parse the tree.

package/dist/specs/activity-hints.xml

@@ -9,7 +9,7 @@
     <forbid>Opening all props.xml files</forbid>
   </activity>
   <activity id="implement">
-    <description>Implement UI with a chosen component.</description>
+    <description>Implement UI by composing with ViraUI parts and public props — not by restyling controls with custom CSS first.</description>
     <load>
       <step open="index.xml" />
       <step unit="meta" />
@@ -18,6 +18,8 @@
       <step unit="a11y" when="interactive or forms" />
     </load>
     <forbid>Opening every component props.xml in the package</forbid>
+    <forbid>Writing unsolicited className / CSS module / utility styles on a Vira root before opening that surface props.xml and usage.xml</forbid>
+    <forbid>Treating Vira controls as raw HTML to reshape without an express consumer request for override / personalization — compose with public parts and props first</forbid>
   </activity>
   <activity id="foundation-attrs">
     <description>Mode, vibrancy, elevation, grow/shrink hooks.</description>
@@ -30,6 +32,15 @@
     </load>
     <forbid>Inventing data-* attributes not listed in foundation units</forbid>
   </activity>
+  <activity id="foundation-motion">
+    <description>Duration/easing tokens, functional vs evocative motion, reduced-motion, longer-than-slowest calc.</description>
+    <load>
+      <step open="index.xml" />
+      <step open="foundation/motion.xml" />
+      <step open="foundation/theme-topics.xml" when="retuning --duration-* / --easing-* on a theme" />
+    </load>
+    <forbid>Hardcoding ms/s/ease or inventing spring curves instead of --duration-* / --easing-*</forbid>
+  </activity>
   <activity id="bootstrap">
     <description>Install peers, theme/fonts/preflight import order, root providers.</description>
     <load>

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

@@ -10,7 +10,7 @@
   <do>Navigation that should look like Button — use ButtonLink (framework Link via `render`)</do>
   <dont>Using Button without children as icon-only — prefer IconButton</dont>
   <dont>Using Button with `render={&lt;a /&gt;}` for links — Base UI enforces button semantics; use ButtonLink</dont>
-  <dont>Inventing `width: 100%` / `w-full` / `.fullWidth` / `flex: 1` CSS on Button when a parent Stack can own the fill</dont>
+  <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / `.fullWidth` / size-fill `className` (e.g. `.Submit`) on Button when a parent Stack can own the fill</dont>
   <dont>Duplicating icon size on every addon slot — Button CSS sizes SVG descendants</dont>
   <dont>Mixing `pill` with custom border-radius overrides that fight `data-pill` styling</dont>
   <dont>Primary Chip addon inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>

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

@@ -12,5 +12,5 @@
   <dont>Using IconButton for persistent or temporal pressed state — use ToggleButton</dont>
   <dont>Using IconButton with `render={&lt;a /&gt;}` for links — use IconButtonLink</dont>
   <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
-  <dont>Inventing `width: 100%` / `w-full` CSS on IconButton when a parent Stack `fullWidth` / `expandChildren` can own the fill</dont>
+  <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / size-fill `className` (e.g. `.Social`) on IconButton — it is intentionally square; Stack owns gap/align only</dont>
 </usage>

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

@@ -12,7 +12,7 @@
     <item>Cases where a single component already owns required flex chrome</item>
     <item>Expecting direct children to grow on the main axis without setting `expandChildren`</item>
     <item>Expecting this stack to fill parent inline size under non-stretch alignment without `fullWidth` (or an explicit `inlineSize`)</item>
-    <item>Inventing `width: 100%` / `w-full` on content-sized children (Button, Chip, …) when this Stack can own fill via `fullWidth` / `expandChildren`</item>
+    <item>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / size-fill className on content-sized children (Button, Chip, …) when this Stack can own fill via `fullWidth` / `expandChildren` — or on fixed-size children (IconButton) where width CSS is useless</item>
     <item>Using `enableContainer` inside complex masonry-like layouts when you don&apos;t need container queries (inline-size containment can change nested layout)</item>
   </when_not_to_use>
   <prop name="columnGap" kind="react">

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

@@ -11,7 +11,7 @@
   <dont>Reaching for a plain wrapper `div` when Stack (optionally with `render` for a semantic tag) can own the box</dont>
   <dont>Assuming Stack expands direct children by default — pass `expandChildren` when children should grow on the flex main axis</dont>
   <dont>Using `expandChildren` to fill parent width under `hAlign=&quot;center&quot;` — that is `fullWidth` on the child Stack (self `inline-size`), not child flex-grow</dont>
-  <dont>Inventing `width: 100%` / `w-full` / `.fullWidth` CSS on content-sized children when this Stack can own the fill</dont>
+  <dont>Inventing `width: 100%` / `inline-size: 100%` / `w-full` / `.fullWidth` / size-fill `className` on content-sized children when this Stack can own the fill — or when children are intentionally fixed-size (e.g. IconButton)</dont>
   <dont>Inventing CSS `gap` / `padding` on this root when public spacing props cover it</dont>
   <dont>Putting `data-grow=&quot;false&quot;` on an ancestor to control nested `expandChildren` — set it on the child that should not grow</dont>
   <dont>Combining `fullWidth` with `inline` — prefer block flex when the root must fill parent inline size</dont>

package/dist/specs/foundation/meta.xml

@@ -1,6 +1,6 @@
 <?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>
+  <summary>Preflight CSS, consumer bootstrap, data-* hooks, core CSS toggles (polarity + effects), elevation helpers, motion timing contract, and theme token topic map shipping with @viraui/react.</summary>
   <exports>
     <export name="getElevationProps" />
   </exports>
@@ -15,6 +15,7 @@
     <unit kind="toggles" href="toggles.xml" />
     <unit kind="theme-topics" href="theme-topics.xml" />
     <unit kind="elevation" href="elevation.xml" />
+    <unit kind="motion" href="motion.xml" />
     <unit kind="modules" href="modules.xml" />
   </units>
 </meta>

package/dist/specs/foundation/modules.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <modules>
-  <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>
+  <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; motion timing: motion.xml; effect gates: toggles.xml; theme token groups: theme-topics.xml.</summary>
 
   <distributed>
     <import>@viraui/react/preflight.css</import>

package/dist/specs/foundation/motion.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<motion>
+  <summary>Motion is animation with intent: shared --duration-* and --easing-* on the theme so @viraui/react and custom CSS share one timing contract. Components already follow the roles below; retune token values when the brand needs a different pace — screens keep the same motion roles without hand-tuning each transition.</summary>
+  <concept>
+    Everyday UI feedback is functional motion (short, assistive, familiar). Attention moments are evocative motion (toast, badge-in, celebration, hero). Both roles use the same principles and theme tokens. Motion never carries meaning alone — pair with copy, structure, chips, or live regions.
+  </concept>
+
+  <principles>
+    <principle id="discreet">Every animation earns its place without pulling attention from the task. Keep transitions fast and agile so nobody waits on motion to finish. Draw attention with animation only when that is the goal — alert, hero entrance, celebration.</principle>
+    <principle id="assistive">Motion supports the message; it never carries information alone. Use it to hint interactivity or give immediate feedback — copy and structure still communicate if the animation never runs.</principle>
+    <principle id="intuitive">Movement should recall how objects behave in the real world — acceleration, gravity, volume — so the result feels natural. Familiar open/close and settle patterns make the app easier to learn, especially on touch.</principle>
+    <principle id="playful">Animation can carry brand personality, but playful motion only fits when the tone allows it. Skip bounce and wiggle for serious or important news so the meaning stays clear.</principle>
+  </principles>
+
+  <roles>
+    <role id="functional">
+      Everyday UI feedback — hover and focus, expand and collapse, menus, dialogs, tabs. Discreet (short), assistive (confirms the action), intuitive (familiar settle). Prefer --duration-instant or --duration-fast with --easing-standard or --easing-entrance. In serious or dense contexts — errors, destructive actions, legal copy, data-heavy tables — stay in this lane. If someone asks for &quot;delight&quot; on a dense surface, prefer a quieter cue (chip + live region) instead of bounce.
+    </role>
+    <role id="evocative">
+      Attention is the goal: toast arriving, badge popping in, celebration, hero entrance. Same principles with a louder dial — earn the spotlight only for that rare moment; copy still carries the message; personality easings still read like spring and settle. Use longer timing (--duration-slow or --duration-slowest) and personality easings (--easing-elastic, --easing-wiggle) on purpose. A flourish on every card stops feeling special — reserve energy for moments people should notice.
+    </role>
+  </roles>
+
+  <tokens>
+    <duration name="--duration-instant">Press, menu/select popup, small nudges.</duration>
+    <duration name="--duration-fast">Default functional: hover, disclosure, tabs, most overlays.</duration>
+    <duration name="--duration-normal">Larger overlay travel (dialog sheet).</duration>
+    <duration name="--duration-slow">Evocative enter (toast) and other intentional attention timing.</duration>
+    <duration name="--duration-slowest">Decorative loops (shimmer) and rare long flourishes.</duration>
+    <easing name="--easing-standard">Default state change: hover, indicator, accordion, position.</easing>
+    <easing name="--easing-entrance">Incoming: modal, popover, menu, toast-in, user-triggered reveal.</easing>
+    <easing name="--easing-exit">Leaving: dismiss, collapse, close — pair with a shorter duration than enter.</easing>
+    <easing name="--easing-elastic">Playful overshoot: press, toast. Not errors or data tables.</easing>
+    <easing name="--easing-wiggle">Attention wiggle. Rare. Never looping on content.</easing>
+  </tokens>
+
+  <extend>
+    Prefer named --duration-* tokens first (--duration-slowest is the widest step). When the task needs a duration longer than --duration-slowest, do not invent raw ms/s. Multiply the slowest token so timing stays theme-linked: calc(var(--duration-slowest) * n) with n a positive number (e.g. 2, 3). Retuning --duration-slowest on the theme still scales those custom lengths. Same rule for JS/WAAPI: derive from the token (or getComputedStyle), never hardcode 180/200/480.
+  </extend>
+
+  <accessibility>
+    Avoid large sudden movements and multiple objects moving at once in different directions — people with epilepsy or vestibular disorders can be especially sensitive. Respect Reduce motion: every transition you add in custom CSS should include a prefers-reduced-motion: reduce fallback (or equivalent). Preflight already kills transition/animation on * under reduce; add extra reduced-motion rules only when final state must change (instant opacity/transform, hide decorative effects). Motion never carries meaning alone.
+  </accessibility>
+
+  <do>Use --duration-* and --easing-* for @viraui/react and custom consumer CSS alike.</do>
+  <do>Keep functional UI on instant/fast (+ standard/entrance/exit); reserve slow/slowest and elastic/wiggle for evocative moments.</do>
+  <do>Make exits shorter than enters for the same surface.</do>
+  <do>Include a prefers-reduced-motion path for every authored animation (or rely on preflight kill when final state needs no change).</do>
+  <do>When longer than --duration-slowest is required, use calc(var(--duration-slowest) * n) instead of inventing ms.</do>
+  <dont>Do not hardcode ms, s, ease, ease-in-out, or homemade cubic-bezier / --spring.</dont>
+  <dont>Do not use elastic/wiggle on errors, destructive actions, legal copy, or dense data tables.</dont>
+  <dont>Do not put showy evocative motion on every card or routine hover.</dont>
+  <dont>Do not let motion be the only signal for saved / new / error.</dont>
+  <dont>Do not skip custom CSS — &quot;Vira already animates&quot; is not an exemption for consumer chrome.</dont>
+
+  <css title="Functional overlay"><![CDATA[
+.popup {
+  transition:
+    opacity var(--duration-instant) var(--easing-entrance),
+    transform var(--duration-instant) var(--easing-entrance);
+}
+.popup[data-ending-style] {
+  transition-duration: var(--duration-instant);
+  transition-timing-function: var(--easing-exit);
+}
+]]></css>
+  <css title="Evocative enter"><![CDATA[
+.banner {
+  transition:
+    transform var(--duration-slowest) var(--easing-elastic),
+    opacity var(--duration-slowest) var(--easing-elastic);
+}
+]]></css>
+  <css title="Longer than slowest (theme-linked)"><![CDATA[
+.hero-enter {
+  transition:
+    opacity calc(var(--duration-slowest) * 2) var(--easing-entrance),
+    transform calc(var(--duration-slowest) * 2) var(--easing-entrance);
+}
+@media (prefers-reduced-motion: reduce) {
+  .hero-enter {
+    transition: none;
+  }
+}
+]]></css>
+
+  <prompt title="Speed up">Make everyday UI motion feel a bit snappier — hovers, menus, dialogs. Keep celebration and hero moments at their current pace.</prompt>
+  <prompt title="Hover + a11y">Add subtle hover motion with theme duration/easing tokens and a prefers-reduced-motion fallback.</prompt>
+  <prompt title="Celebration">Add a one-shot evocative entrance for this toast/badge — slow + elastic, not on every card.</prompt>
+  <prompt title="Long hero">Hero entrance needs longer than --duration-slowest — use calc(var(--duration-slowest) * n), not raw ms.</prompt>
+
+  <tune>
+    Retune pace by overriding --duration-* and --easing-* on a compatible theme sheet (or App Studio export). Built-in components and token-based custom CSS keep the same motion roles; only the timing changes. Theme group map: foundation/theme-topics.xml topic motion. Compose playbook: viraui-motion skill (hub + one ref).
+  </tune>
+  <related>
+    <ref id="foundation-theme-topics" />
+    <ref id="foundation-modules" />
+  </related>
+</motion>

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

@@ -82,7 +82,7 @@
   <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>
+    <agent>Theme motion primitives. Full roles/principles/a11y: foundation/motion.xml. Compose playbook: viraui-motion.</agent>
   </topic>
 
   <topic id="font-scale" surface="derived" set_by="preflight">

package/dist/specs/index.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<index package="@viraui/react" version="2026.6.1" generated="2026-09-25T10:16:02.350Z">
+<index package="@viraui/react" version="2026.6.3" generated="2026-09-25T13:06:12.744Z">
   <categories>
     <category id="layout" />
     <category id="action" />
@@ -482,7 +482,7 @@
     </units>
   </entry>
   <entry id="core" category="foundation" title="Core / preflight">
-    <summary>Preflight CSS, consumer bootstrap, data-* hooks, core CSS toggles (polarity + effects), elevation helpers, and theme token topic map shipping with @viraui/react.</summary>
+    <summary>Preflight CSS, consumer bootstrap, data-* hooks, core CSS toggles (polarity + effects), elevation helpers, motion timing contract, and theme token topic map shipping with @viraui/react.</summary>
     <units>
       <unit kind="meta" href="foundation/meta.xml" />
       <unit kind="bootstrap" href="foundation/bootstrap.xml" />
@@ -490,6 +490,7 @@
       <unit kind="toggles" href="foundation/toggles.xml" />
       <unit kind="theme-topics" href="foundation/theme-topics.xml" />
       <unit kind="elevation" href="foundation/elevation.xml" />
+      <unit kind="motion" href="foundation/motion.xml" />
       <unit kind="modules" href="foundation/modules.xml" />
     </units>
   </entry>
@@ -523,6 +524,12 @@
       <unit kind="foundation" href="foundation/elevation.xml" />
     </units>
   </entry>
+  <entry id="foundation-motion" category="foundation" title="Motion timing">
+    <summary>Duration/easing roles, functional vs evocative, reduced-motion, calc beyond --duration-slowest.</summary>
+    <units>
+      <unit kind="foundation" href="foundation/motion.xml" />
+    </units>
+  </entry>
   <entry id="foundation-modules" category="foundation" title="Preflight modules">
     <summary>Preflight CSS modules and related custom properties that compose preflight.css.</summary>
     <units>

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

@@ -9,8 +9,8 @@
     <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>
+  <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 **with** these parts; default custom CSS = **app chrome** the system does not own. 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 not open a CSS module to reshape a Vira control unless the consumer **expressly asked** for that override (still read `props`/`usage` first; a future override layer will formalize hooks).</do>
+  <dont>Do not invent bare wrapper `div`s (or `display:flex` / `display:grid` / CSS `gap` / `padding` / `width` / `inline-size` / border/radius chrome on raw tags or Vira control roots) when `Stack` or another layout primitive / `Surface` / a public `fullWidth` prop covers it. Do not skip composition to reach for a one-off stylesheet — including size-fill classNames that would do nothing on fixed-size controls.</dont>
   <tsx><![CDATA[
 {/* Flex row + panel chrome: one DOM node via Stack render={<Surface />} */}
 <Stack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viraui/react",
-  "version": "2026.6.1",
+  "version": "2026.6.3",
   "private": false,
   "files": [
     "dist"
@@ -27,17 +27,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@base-ui/react": ">=1.7.0",
-    "@viraui/foundation": "2026.6.1",
+    "@base-ui/react": ">=1.8.0",
+    "@viraui/foundation": "2026.6.3",
     "@viraui/icons": "2026.1.0",
     "@viraui/postcss-config": "2026.0.0",
     "@viraui/tsconfig": "2026.0.0",
-    "postcss": "8.5.26",
-    "postcss-cli": "11.0.1",
-    "react": ">=19.2.8",
-    "react-dom": ">=19.2.8",
-    "unplugin-dts": "1.0.3",
-    "vite": "8.2.2"
+    "postcss": "8.5.28",
+    "postcss-cli": "12.0.0",
+    "react": ">=19.3.0",
+    "react-dom": ">=19.3.0",
+    "unplugin-dts": "1.1.1",
+    "vite": "8.3.1"
   },
   "peerDependencies": {
     "@base-ui/react": ">=1.6.0",