@viraui/react 2026.3.11 → 2026.4.1

package/dist/catalog.json

@@ -6,285 +6,285 @@
       "id": "accordion",
       "name": "Accordion",
       "summary": "Collapsible sections grouped into open/closed blocks with optional Surface wrapping, shared corner radius, and optional Item color for open-block background.",
-      "guidePath": "./components/accordion/accordion.guide.json"
+      "agentDocs": "./specs/components/accordion/meta.xml"
     },
     {
       "id": "annotate",
       "name": "Annotate",
       "summary": "Decorative arrow and handwritten label that wraps inline content with optional highlighter mark, positioned via CSS anchor positioning.",
-      "guidePath": "./components/annotate/annotate.guide.json"
+      "agentDocs": "./specs/components/annotate/meta.xml"
     },
     {
       "id": "autocomplete",
       "name": "Autocomplete",
       "summary": "Field-wrapped free-form suggest input with Textfield chrome and Select-like popup list.",
-      "guidePath": "./components/autocomplete/autocomplete.guide.json"
+      "agentDocs": "./specs/components/autocomplete/meta.xml"
     },
     {
       "id": "avatar",
       "name": "Avatar",
       "summary": "Circular identity image or fallback for users, entities, or profile chips.",
-      "guidePath": "./components/avatar/avatar.guide.json"
+      "agentDocs": "./specs/components/avatar/meta.xml"
     },
     {
       "id": "avatar-group",
       "name": "AvatarGroup",
       "summary": "Overlapping avatar stack with shared sizing, directional layout, and an optional overflow pill.",
-      "guidePath": "./components/avatar-group/avatar-group.guide.json"
+      "agentDocs": "./specs/components/avatar-group/meta.xml"
     },
     {
       "id": "badge",
       "name": "Badge",
       "summary": "Decorative status-dot overlay that wraps a child, with optional radial mask cutout on the child around the corner dot.",
-      "guidePath": "./components/badge/badge.guide.json"
+      "agentDocs": "./specs/components/badge/meta.xml"
     },
     {
       "id": "beam",
       "name": "Beam",
       "summary": "Decorative animated border, line, or pulse glow on a transparent Surface shell (radius only). Put the visual card as children. CSS-module geometry plus shared ~30fps pulse rAF for pulse variants. Memory/CPU cost — use sparingly.",
-      "guidePath": "./components/beam/beam.guide.json"
+      "agentDocs": "./specs/components/beam/meta.xml"
     },
     {
       "id": "bleed",
       "name": "Bleed",
       "summary": "Layout utility that pulls content past inline padding using negative margins or full viewport bleed.",
-      "guidePath": "./components/bleed/bleed.guide.json"
+      "agentDocs": "./specs/components/bleed/meta.xml"
     },
     {
       "id": "breakpoints",
       "name": "BreakpointsProvider",
       "summary": "Client provider plus `useBreakpoints` for mobile-first viewport min-width matches. Defaults are hardcoded em thresholds, not theme tokens.",
-      "guidePath": "./components/breakpoints/breakpoints.guide.json"
+      "agentDocs": "./specs/components/breakpoints/meta.xml"
     },
     {
       "id": "button",
       "name": "Button",
       "summary": "Primary action control with size, variant, optional addon, optional pill shape, and loading state.",
-      "guidePath": "./components/button/button.guide.json"
+      "agentDocs": "./specs/components/button/meta.xml"
     },
     {
       "id": "checkbox",
       "name": "Checkbox",
       "summary": "Field.Item checkbox option for standalone fields or CheckboxGroup children.",
-      "guidePath": "./components/checkbox/checkbox.guide.json"
+      "agentDocs": "./specs/components/checkbox/meta.xml"
     },
     {
       "id": "chip",
       "name": "Chip",
       "summary": "Compact visual label primitive for short status, category, or metadata treatments.",
-      "guidePath": "./components/chip/chip.guide.json"
+      "agentDocs": "./specs/components/chip/meta.xml"
     },
     {
       "id": "clamp-text",
       "name": "ClampText",
       "summary": "Presentational utility that truncates overflowing copy to a fixed line count.",
-      "guidePath": "./components/clamp-text/clamp-text.guide.json"
+      "agentDocs": "./specs/components/clamp-text/meta.xml"
     },
     {
       "id": "dialog",
       "name": "Dialog",
       "summary": "Compound drawer sheet with `Dialog.Trigger`, `Dialog.Sheet`, `Dialog.Close`, and Base UI pass-through `Dialog.Provider`, `Dialog.Indent`, and `Dialog.IndentBackground` for app-shell indent effects.",
-      "guidePath": "./components/dialog/dialog.guide.json"
+      "agentDocs": "./specs/components/dialog/meta.xml"
     },
     {
       "id": "elevator",
       "name": "Elevator",
       "summary": "No-DOM elevation utility that merges shadow hooks onto valid element children.",
-      "guidePath": "./components/elevator/elevator.guide.json"
+      "agentDocs": "./specs/components/elevator/meta.xml"
     },
     {
       "id": "fieldset",
       "name": "Fieldset",
       "summary": "Semantic field grouping with shared legend and optional group helper copy.",
-      "guidePath": "./components/fieldset/fieldset.guide.json"
+      "agentDocs": "./specs/components/fieldset/meta.xml"
     },
     {
       "id": "fit-text",
       "name": "FitText",
       "summary": "CSS-only fit-to-width wrapper that scales children to fill available inline space.",
-      "guidePath": "./components/fit-text/fit-text.guide.json"
+      "agentDocs": "./specs/components/fit-text/meta.xml"
     },
     {
       "id": "glow",
       "name": "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-heavy — use sparingly (rarely).",
-      "guidePath": "./components/glow/glow.guide.json"
+      "agentDocs": "./specs/components/glow/meta.xml"
     },
     {
       "id": "grid",
       "name": "Grid",
       "summary": "CSS Grid layout primitive for auto-fill/fit or fixed track layouts with token gaps, Stack-aligned padding, and item placement (`fullWidth` / `fullHeight` / column / row).",
-      "guidePath": "./components/grid/grid.guide.json"
+      "agentDocs": "./specs/components/grid/meta.xml"
     },
     {
       "id": "icon-button",
       "name": "IconButton",
       "summary": "Icon-only button that shares Button visual chrome (--vui-button-* CSS) and requires an accessible name through aria-label or aria-labelledby.",
-      "guidePath": "./components/icon-button/icon-button.guide.json"
+      "agentDocs": "./specs/components/icon-button/meta.xml"
     },
     {
       "id": "linear-progress",
       "name": "LinearProgress",
       "summary": "Shows determinate or indeterminate progress for a task in a compact horizontal track.",
-      "guidePath": "./components/linear-progress/linear-progress.guide.json"
+      "agentDocs": "./specs/components/linear-progress/meta.xml"
     },
     {
       "id": "masonry",
       "name": "Masonry",
       "summary": "Responsive React-column layout primitive for read-only mixed-height content walls; root is a named CSS container query context (`masonry` / inline-size).",
-      "guidePath": "./components/masonry/masonry.guide.json"
+      "agentDocs": "./specs/components/masonry/meta.xml"
     },
     {
       "id": "menu",
       "name": "Menu",
       "summary": "Compound menu built on Base UI Menu with `Menu.Trigger`, `Menu.Popup`, unified item rows, groups, checkbox/radio items, nested submenus, destructive sentiment, and `Menu.createHandle` for detached triggers; `Popup` owns Portal + Positioner + Elevator/Surface Select-like list chrome.",
-      "guidePath": "./components/menu/menu.guide.json"
+      "agentDocs": "./specs/components/menu/meta.xml"
     },
     {
       "id": "meter",
       "name": "Meter",
       "summary": "Shows a determinate metric in a compact horizontal track for static capacity, level, or score values.",
-      "guidePath": "./components/meter/meter.guide.json"
+      "agentDocs": "./specs/components/meter/meta.xml"
     },
     {
       "id": "popover",
       "name": "Popover",
       "summary": "Compound popover built on Base UI Popover with `Popover.Trigger`, `Popover.Sheet`, `Popover.Close`, `Popover.Title`, `Popover.Description`, and `Popover.createHandle` for detached and multiple triggers; `Sheet` encapsulates Portal + Positioner + Popup + Viewport + Title + Description and animates position, size, and content between triggers; `Sheet` with `unstyled` skips the built-in Surface and header so the consumer composes the popup chrome, including `Popover.Title` and `Popover.Description`.",
-      "guidePath": "./components/popover/popover.guide.json"
+      "agentDocs": "./specs/components/popover/meta.xml"
     },
     {
       "id": "progressive-blur",
       "name": "ProgressiveBlur",
       "summary": "Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge.",
-      "guidePath": "./components/progressive-blur/progressive-blur.guide.json"
+      "agentDocs": "./specs/components/progressive-blur/meta.xml"
     },
     {
       "id": "radio",
       "name": "Radio",
       "summary": "Mutually exclusive choice within a RadioGroup, with optional per-option label and helper text.",
-      "guidePath": "./components/radio/radio.guide.json"
+      "agentDocs": "./specs/components/radio/meta.xml"
     },
     {
       "id": "select",
       "name": "Select",
       "summary": "Field-wrapped single-select dropdown with grouped options and field copy.",
-      "guidePath": "./components/select/select.guide.json"
+      "agentDocs": "./specs/components/select/meta.xml"
     },
     {
       "id": "separator",
       "name": "Separator",
       "summary": "Thematic or content divider with horizontal or vertical orientation, token padding, and preset line thickness.",
-      "guidePath": "./components/separator/separator.guide.json"
+      "agentDocs": "./specs/components/separator/meta.xml"
     },
     {
       "id": "shimmer",
       "name": "Shimmer",
       "summary": "Decorative inline text shimmer that inherits typography and color from a parent text primitive.",
-      "guidePath": "./components/shimmer/shimmer.guide.json"
+      "agentDocs": "./specs/components/shimmer/meta.xml"
     },
     {
       "id": "skeleton",
       "name": "Skeleton",
       "summary": "Decorative opacity pulse block sized by props, or Overlay sized by hidden child content.",
-      "guidePath": "./components/skeleton/skeleton.guide.json"
+      "agentDocs": "./specs/components/skeleton/meta.xml"
     },
     {
       "id": "slider",
       "name": "Slider",
       "summary": "Field-wrapped range input supporting single-thumb or two-thumb range selection.",
-      "guidePath": "./components/slider/slider.guide.json"
+      "agentDocs": "./specs/components/slider/meta.xml"
     },
     {
       "id": "spinner",
       "name": "Spinner",
       "summary": "Decorative SVG pulsing loading indicator used inside interactive components.",
-      "guidePath": "./components/spinner/spinner.guide.json"
+      "agentDocs": "./specs/components/spinner/meta.xml"
     },
     {
       "id": "stack",
       "name": "Stack",
       "summary": "Flex layout primitive for arranging children with token spacing, alignment, and padding; optionally enables a named CSS container query context (`stack`) via `enableContainer`.",
-      "guidePath": "./components/stack/stack.guide.json"
+      "agentDocs": "./specs/components/stack/meta.xml"
     },
     {
       "id": "static-noise",
       "name": "StaticNoise",
       "summary": "Decorative SVG turbulence noise overlay for textured surfaces and hero sections. Memory-heavy — use sparingly (rarely).",
-      "guidePath": "./components/static-noise/static-noise.guide.json"
+      "agentDocs": "./specs/components/static-noise/meta.xml"
     },
     {
       "id": "surface",
       "name": "Surface",
-      "summary": "Presentational container with token background, optional border, radius, and padding; `data-vibrant` frosts the fill even without `color` (page shell via `--global-background`); nested surfaces use radius=\"auto\" for concentric corners; optionally enables a named CSS container query context (`surface`) via `enableContainer`.",
-      "guidePath": "./components/surface/surface.guide.json"
+      "summary": "Presentational container with token background, optional border, radius, and padding; `data-vibrant` frosts the fill even without `color` (page shell via `--global-background`); nested surfaces use radius="auto" for concentric corners; optionally enables a named CSS container query context (`surface`) via `enableContainer`.",
+      "agentDocs": "./specs/components/surface/meta.xml"
     },
     {
       "id": "switch",
       "name": "Switch",
       "summary": "Field-wrapped toggle control with medium or small track and optional field copy.",
-      "guidePath": "./components/switch/switch.guide.json"
+      "agentDocs": "./specs/components/switch/meta.xml"
     },
     {
       "id": "tabs",
       "name": "Tabs",
       "summary": "Compound segmented tab control with Surface list chrome, moving indicator, and animated panels.",
-      "guidePath": "./components/tabs/tabs.guide.json"
+      "agentDocs": "./specs/components/tabs/meta.xml"
     },
     {
       "id": "text",
       "name": "Text",
       "summary": "Theme-aware body-copy primitive with tone, family, and responsive body sizing.",
-      "guidePath": "./components/text/text.guide.json"
+      "agentDocs": "./specs/components/text/meta.xml"
     },
     {
       "id": "textarea",
       "name": "Textarea",
       "summary": "Multi-line field control with shared field copy, optional resize, and optional content sizing.",
-      "guidePath": "./components/textarea/textarea.guide.json"
+      "agentDocs": "./specs/components/textarea/meta.xml"
     },
     {
       "id": "textfield",
       "name": "Textfield",
       "summary": "Single-line field input with control-group chrome and optional addons.",
-      "guidePath": "./components/textfield/textfield.guide.json"
+      "agentDocs": "./specs/components/textfield/meta.xml"
     },
     {
       "id": "title",
       "name": "Title",
       "summary": "Theme-aware heading and display typography primitive.",
-      "guidePath": "./components/title/title.guide.json"
+      "agentDocs": "./specs/components/title/meta.xml"
     },
     {
       "id": "toast",
       "name": "Toast",
       "summary": "Non-callable compound Toast namespace for transient notifications, with stacked or anchored placement, Banner high-level API, and optional action buttons.",
-      "guidePath": "./components/toast/toast.guide.json"
+      "agentDocs": "./specs/components/toast/meta.xml"
     },
     {
       "id": "toggle-button",
       "name": "ToggleButton",
       "summary": "Icon-only two-state toggle that swaps resting and optional pressed icons on Base UI Toggle state; `interpolateIcons` (default false) opt-in crossfade + light rotate between dual icons.",
-      "guidePath": "./components/toggle-button/toggle-button.guide.json"
+      "agentDocs": "./specs/components/toggle-button/meta.xml"
     },
     {
       "id": "toggle-group",
       "name": "ToggleGroup",
       "summary": "Toolbar toggle set with shared selection state; Stack direction follows orientation with zero default gap.",
-      "guidePath": "./components/toggle-group/toggle-group.guide.json"
+      "agentDocs": "./specs/components/toggle-group/meta.xml"
     },
     {
       "id": "typewriter",
       "name": "Typewriter",
       "summary": "Decorative inline typewriter animation that inherits typography and color from a parent text primitive.",
-      "guidePath": "./components/typewriter/typewriter.guide.json"
+      "agentDocs": "./specs/components/typewriter/meta.xml"
     },
     {
       "id": "tooltip",
       "name": "Tooltip",
       "summary": "Compound tooltip built on Base UI Tooltip with `Tooltip.Provider`, `Tooltip.Trigger`, `Tooltip.Content`, and `Tooltip.createHandle` for detached and multiple triggers; `Content` encapsulates Portal + Positioner + Popup + Viewport and animates position, size, and content between triggers.",
-      "guidePath": "./components/tooltip/tooltip.guide.json"
+      "agentDocs": "./specs/components/tooltip/meta.xml"
     }
   ],
-  "consumption": "./consumption.json",
-  "themeSurface": "./theme-surface.json"
+  "agentDocsIndex": "./specs/index.xml",
+  "agentDocsProtocol": "./specs/PROTOCOL.md"
 }

package/dist/components/textarea/textarea.js

@@ -9,7 +9,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { Field } from "@base-ui/react/field";
 //#region src/components/textarea/textarea.tsx
 var Textarea = ({ className, description, dirty, disabled, error, fitContent, invalid, label, name, ref, resize, touched, validate, validationDebounceTime, validationMode, ...textareaProps }) => /* @__PURE__ */ jsxs(Field.Root, {
-	className: textarea_module_default.Textarea,
+	className: clsx(textarea_module_default.Textarea, className),
 	dirty,
 	disabled,
 	invalid,
@@ -30,7 +30,7 @@ var Textarea = ({ className, description, dirty, disabled, error, fitContent, in
 		/* @__PURE__ */ jsx(BasicInput, {
 			...textareaProps,
 			ref,
-			className: clsx(textarea_module_default.CustomBasicInput, className),
+			className: textarea_module_default.CustomBasicInput,
 			"data-resize": resize,
 			disabled,
 			fitContent,

package/dist/components/textfield/textfield.js

@@ -11,7 +11,7 @@ import { Field } from "@base-ui/react/field";
 import { Input } from "@base-ui/react/input";
 //#region src/components/textfield/textfield.tsx
 var Textfield = ({ className, description, dirty, disabled, endAddon, error, fitContent, fullWidth = false, invalid, label, name, ref, startAddon, touched, validate, validationDebounceTime, validationMode, ...inputProps }) => /* @__PURE__ */ jsxs(Field.Root, {
-	className: textfield_module_default.Textfield,
+	className: clsx(textfield_module_default.Textfield, className),
 	dirty,
 	disabled,
 	invalid,
@@ -38,7 +38,7 @@ var Textfield = ({ className, description, dirty, disabled, endAddon, error, fit
 			children: /* @__PURE__ */ jsx(BasicInput, {
 				...inputProps,
 				ref,
-				className: clsx(textfield_module_default.CustomBasicInput, className),
+				className: textfield_module_default.CustomBasicInput,
 				disabled,
 				fitContent,
 				render: /* @__PURE__ */ jsx(Input, {})

package/dist/specs/PROTOCOL.md

@@ -0,0 +1,48 @@
+# ViraUI package specs protocol
+
+**Package:** `@viraui/react` agent documentation  
+**Authority after cutover:** navigation index + scoped XML units only. `*.guide.json` is **not** agent API authority.
+
+## Index-first (mandatory)
+
+1. Open `index.xml` before any component or foundation unit.
+2. Use `activity-hints.xml` for activity → load sequences (`choose-component`, `implement`, `foundation-attrs`).
+3. Open only the unit files named for that activity (and the chosen surface).
+4. Do **not** parse the full tree of XML unit files. Failure to route is an index or content defect—not a reason to tree-walk.
+
+## Authority order
+
+1. **Package specs units** for the installed version (`meta`, `props`, `usage`, `a11y`, `patterns`, foundation) — intent, Vira-added props, anti-patterns, public CSS hooks.
+2. Installed package **types / source** — verify accepted props, inherited pass-through, and defaults **after** reading units. Never use types as first discovery.
+3. Examples / stories — examples only; never API authority.
+4. Skills prose — routers and playbooks only; never a second encyclopedia of component API facts.
+
+## Co-versioned resolution
+
+Resolve docs from the **installed** `@viraui/react` package (Node resolution / `node_modules`), not from a newer skills corpus or another checkout. The `version` attribute on `index.xml` must match the installed package version.
+
+### Filesystem recipe (Read tool)
+
+Prefer package subpaths; on disk under the install they map to:
+
+- `node_modules/@viraui/react/dist/specs/PROTOCOL.md`
+- `node_modules/@viraui/react/dist/specs/index.xml`
+- `node_modules/@viraui/react/dist/specs/activity-hints.xml`
+- `node_modules/@viraui/react/dist/specs/components/<id>/*.xml`
+- `node_modules/@viraui/react/dist/specs/foundation/*.xml`
+
+Package exports: `@viraui/react/specs/*`.
+
+## 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.
+
+## Machine surfaces
+
+`catalog.json` is a small tooling index of public components. Narrative discovery uses the specs index + units—not skill encyclopedias or legacy surface JSON.
+
+**Core / preflight units** are hand-authored under `packages/react/src/core/specs/` and published as `specs/foundation/*` (bootstrap, attributes, toggles, theme-topics, elevation, modules).
+
+## Defects
+
+Missing index entry, broken `href`, or empty high-traffic units → fix the package docs. Do not invent props or load every `props.xml`.

package/dist/specs/activity-hints.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<activity_hints>
+  <activity id="choose-component">
+    <description>Pick a ViraUI component for a UI need.</description>
+    <load>
+      <step open="index.xml" />
+      <step open="activity-hints.xml" note="stop unless implementing" />
+    </load>
+    <forbid>Opening all props.xml files</forbid>
+  </activity>
+  <activity id="implement">
+    <description>Implement UI with a chosen component.</description>
+    <load>
+      <step open="index.xml" />
+      <step unit="meta" />
+      <step unit="props" />
+      <step unit="usage" />
+      <step unit="a11y" when="interactive or forms" />
+    </load>
+    <forbid>Opening every component props.xml in the package</forbid>
+  </activity>
+  <activity id="foundation-attrs">
+    <description>Mode, vibrancy, elevation, grow/shrink hooks.</description>
+    <load>
+      <step open="index.xml" />
+      <step open="foundation/attributes.xml" />
+      <step open="foundation/elevation.xml" when="elevation on React or raw DOM" />
+      <step open="foundation/toggles.xml" when="effects involved" />
+      <step open="foundation/modules.xml" when="debugging which preflight CSS module owns a hook" />
+    </load>
+    <forbid>Inventing data-* attributes not listed in foundation units</forbid>
+  </activity>
+  <activity id="bootstrap">
+    <description>Install peers, theme/fonts/preflight import order, root providers.</description>
+    <load>
+      <step open="index.xml" />
+      <step open="foundation/bootstrap.xml" />
+      <step open="foundation/theme-topics.xml" when="custom theme or token groups" />
+    </load>
+    <forbid>Guessing import paths or inventing provider trees</forbid>
+  </activity>
+</activity_hints>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="accordion">
+  <rule>Provide meaningful `trigger` text so each section has an accessible name</rule>
+  <rule>Use `value` when controlling or identifying items programmatically</rule>
+  <rule>Disabled items cannot be expanded through pointer or keyboard</rule>
+</a11y>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="accordion" title="Accordion" category="layout" shared_contract="accordion">
+  <summary>Collapsible sections grouped into open/closed blocks with optional Surface wrapping, shared corner radius, and optional Item color for open-block background.</summary>
+  <exports>
+    <export name="Accordion" />
+  </exports>
+  <related>
+    <ref id="surface" />
+    <ref id="separator" />
+    <ref id="stack" />
+    <ref id="text" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/accordion#api-reference" />
+</meta>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="accordion">
+  <example title="Accordion structure">
+    <tsx><![CDATA[<Accordion>
+  <Accordion.Item trigger="…">…</Accordion.Item>
+</Accordion>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>

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

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="accordion">
+  <when_to_use>
+    <item>Progressive disclosure for related content sections in one surface</item>
+    <item>FAQ or settings groups where only one section may be open by default</item>
+    <item>Multiple open sections when `multiple` is enabled</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Primary navigation that should use links, tabs, or routes directly</item>
+    <item>Expecting to compose public Header/Trigger/Panel parts; those are owned by `Accordion.Item`</item>
+  </when_not_to_use>
+  <prop name="islands" kind="react">
+    <description>When `true`, open/closed blocks render as separated Surface islands with gap between them. When `false`, blocks stay attached with corner radius only on the first and last items. Applies only to items with `useSurface`.</description>
+  </prop>
+  <prop name="Item.border" kind="react">
+    <description>Contrast border side(s) forwarded to the wrapping `Surface` when `useSurface` is `true`. Pass a single side or a list (e.g. `[&quot;bottom&quot;, &quot;left&quot;]`). Omit for no border.</description>
+  </prop>
+  <prop name="Item.children" kind="react">
+    <description>Panel content revealed when the item is open.</description>
+  </prop>
+  <prop name="Item.color" kind="react">
+    <description>Resting background for the item card, forwarded to the wrapping `Surface` when `useSurface` is `true`. Omit for no background.</description>
+  </prop>
+  <prop name="Item.iconClosed" kind="react">
+    <description>Decorative icon shown when the item is closed.</description>
+  </prop>
+  <prop name="Item.iconOpen" kind="react">
+    <description>Decorative icon shown when the item is open.</description>
+  </prop>
+  <prop name="Item.iconPosition" kind="react">
+    <description>Side of the trigger label where the expand/collapse icon is rendered.</description>
+  </prop>
+  <prop name="Item.radius" kind="react">
+    <description>Corner radius token for the wrapping Surface island edges when useSurface is true.</description>
+  </prop>
+  <prop name="Item.trigger" kind="react">
+    <description>Visible trigger label rendered inside the accordion header button.</description>
+  </prop>
+  <prop name="Item.useSurface" kind="react">
+    <description>When `true`, wraps the item in `Surface` (optional open-block background via `color`). When `false`, renders without `Surface` so consumers can insert `Separator` between items; island styling is skipped for that item.</description>
+  </prop>
+  <css_var suffix="island-gap">
+    <description>Gap between separated Surface islands when islands={true}.</description>
+  </css_var>
+  <css_var suffix="radius">
+    <description>Corner radius for Surface island block edges when useSurface is true.</description>
+  </css_var>
+</props>

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="accordion">
+  <do>Progressive disclosure for related content sections in one surface</do>
+  <do>FAQ or settings groups where only one section may be open by default</do>
+  <do>Multiple open sections when `multiple` is enabled</do>
+  <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports</dont>
+  <dont>Rendering an item without trigger text and without an external aria-label strategy</dont>
+</usage>

package/dist/specs/components/annotate/a11y.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="annotate">
+  <rule>Arrow and note are presentational spans with aria-hidden — decorative only and not exposed to assistive tech</rule>
+  <rule>Do not put critical information in note; keep real meaning in children or aria-describedby content</rule>
+  <rule>Children retain native semantics; Annotate itself is a presentational span wrap</rule>
+</a11y>

package/dist/specs/components/annotate/meta.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="annotate" title="Annotate" category="effect" shared_contract="annotate">
+  <summary>Decorative arrow and handwritten label that wraps inline content with optional highlighter mark, positioned via CSS anchor positioning.</summary>
+  <exports>
+    <export name="Annotate" />
+  </exports>
+  <related>
+    <ref id="text" />
+    <ref id="title" />
+    <ref id="tooltip" />
+    <ref id="chip" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+</meta>

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="annotate">
+  <example title="Annotate structure">
+    <tsx><![CDATA[<Annotate note="…">…</Annotate>]]></tsx>
+    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  </example>
+</patterns>