@viraui/react 2026.3.11 → 2026.4.0

package/dist/components/toast/toast.guide.json

@@ -1,60 +0,0 @@
-{
-  "name": "Toast",
-  "baseUIApi": "https://base-ui.com/react/components/toast#api-reference",
-  "structure": "<Toast.Provider>\n  <Toast.Portal>\n    <Toast.Viewport>\n      <Toast.Banner toast={…}>\n        <Toast.Action>…</Toast.Action>\n      </Toast.Banner>\n    </Toast.Viewport>\n  </Toast.Portal>\n</Toast.Provider>",
-  "summary": "Non-callable compound Toast namespace for transient notifications, with stacked or anchored placement, Banner high-level API, and optional action buttons.",
-  "whenToUse": [
-    "Confirming a completed action such as save or delete",
-    "Offering a short undo window after a reversible change",
-    "Showing contextual feedback anchored to the control that triggered it",
-    "Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part"
-  ],
-  "whenNotToUse": [
-    "Blocking errors that need immediate correction — use inline field errors or a dialog",
-    "Persistent status that should stay visible — use inline status text or a banner pattern",
-    "Long-form content that needs reading time — use a dialog or dedicated panel"
-  ],
-  "accessibility": [
-    "Pass title and description strings to toastManager.add for screen reader announcements on high-priority toasts",
-    "Keep toast copy concise; users can navigate the toast viewport landmark with F6",
-    "Ensure action and dismiss controls have visible labels",
-    "Use anchored toasts for contextual feedback tied to a specific trigger"
-  ],
-  "antiPatterns": [
-    "Nesting arbitrary components inside Toast.Banner — children must be Toast.Action only",
-    "Stacking many simultaneous toasts without a clear limit",
-    "Using toasts for critical validation errors that block task completion"
-  ],
-  "related": ["Button", "Surface", "Stack", "Dialog"],
-  "properties": {
-    "react": {
-      "Banner.children": {
-        "description": "Optional action buttons. Accepts a single `Toast.Action` or an array of them."
-      },
-      "Banner.className": {
-        "description": "Class name forwarded to the toast root."
-      },
-      "Banner.description": {
-        "description": "Supporting copy below the title."
-      },
-      "Banner.dismissable": {
-        "description": "Whether to render the dismiss control."
-      },
-      "Banner.dismissLabel": {
-        "description": "Label for the dismiss control."
-      },
-      "Banner.onDismiss": {
-        "description": "Called when the dismiss control is activated, before Base UI closes the toast."
-      },
-      "Banner.title": {
-        "description": "Heading above the description. Falls back to `toast.title` from `toastManager.add`."
-      },
-      "Banner.toast": {
-        "description": "Toast instance from `Toast.useToastManager().toasts` or `Toast.createToastManager()`."
-      },
-      "Viewport.position": {
-        "description": "Controls viewport placement and stacking layout hooks."
-      }
-    }
-  }
-}

package/dist/components/toggle-button/toggle-button.guide.json

@@ -1,81 +0,0 @@
-{
-  "name": "ToggleButton",
-  "baseUIApi": "https://base-ui.com/react/components/toggle#api-reference",
-  "structure": "<ToggleButton restingIcon={<Plus />} aria-label=\"Pin\" />",
-  "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.",
-  "whenToUse": [
-    "Toolbar pin, favorite, or mute toggles identified only by icon",
-    "Compact on/off controls that share IconButton size, variant, and loading model",
-    "Two-state actions where pressed state should swap the visible glyph",
-    "Temporally swap icons after user interactions with temporal pressed state, like copy feedback."
-  ],
-  "whenNotToUse": [
-    "Settings-style on/off fields — use Switch",
-    "One-shot actions with no pressed state — use IconButton"
-  ],
-  "accessibility": [
-    "Provide aria-label or aria-labelledby on every ToggleButton — icon alone is not a name",
-    "Base UI Toggle exposes aria-pressed on the rendered button",
-    "Keep the accessible name stable when loading state changes"
-  ],
-  "antiPatterns": [
-    "Using IconButton for persistent pressed toolbar state",
-    "Using Switch for compact icon-only toolbar toggles",
-    "Passing icon or render — ToggleButton owns icon swap and Toggle render wiring"
-  ],
-  "related": ["IconButton", "Button", "Switch", "ToggleGroup"],
-  "properties": {
-    "react": {
-      "interpolateIcons": {
-        "description": "When `pressedIcon` is set, crossfade and rotate between resting and pressed icons (`data-interpolate=\"true\"`). When `false`, swap instantly with no transition."
-      },
-      "loading": {
-        "description": "Shows a centered spinner overlay while preserving the original content width."
-      },
-      "pill": {
-        "description": "Applies a fully rounded pill shape to the button."
-      },
-      "pressedIcon": {
-        "description": "Icon shown while the toggle is pressed."
-      },
-      "pressedVariant": {
-        "description": "Visual variant while the toggle is pressed."
-      },
-      "restingIcon": {
-        "description": "Icon shown while the toggle is not pressed."
-      },
-      "size": {
-        "description": "Controls the visual button size."
-      },
-      "variant": {
-        "description": "Visual variant while the toggle is not pressed."
-      }
-    },
-    "css": {
-      "background": {
-        "description": "Button fill; variant and state selectors preset this."
-      },
-      "color": {
-        "description": "Button label and icon color."
-      },
-      "height": {
-        "description": "Button block size; size prop presets via data attributes."
-      },
-      "icon-size": {
-        "description": "Addon icon size inside the button."
-      },
-      "padding-block": {
-        "description": "Vertical padding inside the button."
-      },
-      "padding-inline": {
-        "description": "Horizontal padding inside the button."
-      },
-      "radius": {
-        "description": "Corner radius; pill sets infinite radius via data-pill."
-      },
-      "spinner-color": {
-        "description": "Loading spinner color on the root."
-      }
-    }
-  }
-}

package/dist/components/toggle-group/toggle-group.guide.json

@@ -1,27 +0,0 @@
-{
-  "name": "ToggleGroup",
-  "baseUIApi": "https://base-ui.com/react/components/toggle-group#api-reference",
-  "structure": "<ToggleGroup>\n  <ToggleButton restingIcon={<Plus />} aria-label=\"List\" value=\"list\" />\n</ToggleGroup>",
-  "summary": "Toolbar toggle set with shared selection state; Stack direction follows orientation with zero default gap.",
-  "whenToUse": [
-    "Segmented icon toolbars such as text alignment or formatting controls",
-    "Single- or multi-select pressed states across related ToggleButton items",
-    "Compact action clusters that need coordinated value and disabled state"
-  ],
-  "whenNotToUse": [
-    "Standalone one-off toggles — use ToggleButton",
-    "Settings-style on/off fields — use Switch",
-    "Tabbed panel navigation — use Tabs"
-  ],
-  "accessibility": [
-    "Provide aria-label or aria-labelledby on the ToggleGroup root",
-    "Provide aria-label or aria-labelledby on every ToggleButton child",
-    "Each ToggleButton exposes aria-pressed; group selection follows Base UI ToggleGroup semantics"
-  ],
-  "antiPatterns": [
-    "Omitting value on ToggleButton children inside a group",
-    "Using Switch for icon-only toolbar toggle sets",
-    "Embedding Surface chrome in the component — wrap demos or app chrome at the consumer"
-  ],
-  "related": ["ToggleButton", "IconButton", "Tabs"]
-}

package/dist/components/tooltip/tooltip.guide.json

@@ -1,40 +0,0 @@
-{
-  "name": "Tooltip",
-  "baseUIApi": "https://base-ui.com/react/components/tooltip#api-reference",
-  "structure": "<Tooltip.Provider>\n  <Tooltip>\n    <Tooltip.Trigger />\n    <Tooltip.Content />\n  </Tooltip>\n</Tooltip.Provider>",
-  "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.",
-  "whenToUse": [
-    "Short hints on hover or focus for toolbar controls and icon buttons",
-    "Per-trigger labels on shared tooltip roots using `payload` and Root render-function children",
-    "Adjacent controls that benefit from shared open/close delay via `Tooltip.Provider`",
-    "Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part"
-  ],
-  "whenNotToUse": [
-    "Rich interactive panels or forms (use Popover or Dialog)",
-    "System-wide transient alerts (use Toast)",
-    "Content that must stay open while the pointer moves into the popup (enable `disableHoverablePopup` only when needed)"
-  ],
-  "accessibility": [
-    "Match trigger `aria-label` to tooltip copy so sighted and assistive users get the same hint",
-    "Keep tooltip copy concise; use Popover when the hint needs paragraphs, links, or controls",
-    "Wrap regions with multiple tooltips in `Tooltip.Provider` for predictable delay grouping"
-  ],
-  "antiPatterns": [
-    "Putting essential-only information in a tooltip with no accessible name on the trigger",
-    "Expecting `Tooltip.Arrow` (it is intentionally not exported or rendered)",
-    "Using tooltip for modal or focus-trapped tasks"
-  ],
-  "related": ["Surface", "Button", "IconButton", "Stack", "Popover", "Icon"],
-  "properties": {
-    "css": {
-      "content-fade-duration": {
-        "description": "content fade duration custom property on the component root."
-      }
-    },
-    "react": {
-      "Content.container": {
-        "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)."
-      }
-    }
-  }
-}

package/dist/components/typewriter/typewriter.guide.json

@@ -1,65 +0,0 @@
-{
-  "name": "Typewriter",
-  "structure": "<Typewriter>…</Typewriter>",
-  "summary": "Decorative inline typewriter animation that inherits typography and color from a parent text primitive.",
-  "whenToUse": [
-    "Hero or marketing copy that cycles through short phrases",
-    "Loading or status labels that reveal text progressively",
-    "Muted intro copy inside Text or Title where motion adds emphasis"
-  ],
-  "whenNotToUse": [
-    "Standalone accessible status updates without a surrounding labeled region",
-    "Long-form content better served by static Text",
-    "Cases where reduced-motion users must see every phrase in a multi-text cycle"
-  ],
-  "accessibility": [
-    "One phrase layer (Ghost when preserveSpace, clipped A11y otherwise) holds the full current phrase and announces via aria-live",
-    "The absolute/in-flow typed layer is aria-hidden and only paints the progressive effect plus caret",
-    "Reduced motion shows the final phrase immediately without cycling delays",
-    "Parent region owns loading or busy semantics when Typewriter is decorative"
-  ],
-  "antiPatterns": [
-    "Using Typewriter as the only source of critical status information",
-    "Embedding layout positioning rules inside the component stylesheet",
-    "Restarting animation on every parent render by passing unstable inline text arrays without stable content",
-    "Setting parent Text or Title trim={false} solely so preserveSpace can reserve wrapped height",
-    "Driving per-character typing through React state (use DOM writes on the typed layer instead)"
-  ],
-  "related": ["Text", "Title", "Shimmer"],
-  "properties": {
-    "react": {
-      "caret": {
-        "description": "Selects the caret style rendered after the typed text."
-      },
-      "caretColor": {
-        "description": "Overrides the caret color."
-      },
-      "delay": {
-        "description": "Sets the initial delay before typing starts, in milliseconds."
-      },
-      "deleteSpeed": {
-        "description": "Sets the delay between deleted characters in milliseconds."
-      },
-      "loop": {
-        "description": "Repeats the phrase cycle after the final phrase is deleted."
-      },
-      "pause": {
-        "description": "Sets the pause after a phrase completes before deletion starts, in milliseconds."
-      },
-      "preserveSpace": {
-        "description": "Reserves the full phrase width and height (including wrap under parent constraints) from first paint through delay, typing, and deletion."
-      },
-      "speed": {
-        "description": "Sets the delay between typed characters in milliseconds."
-      },
-      "texts": {
-        "description": "Cycles through multiple phrases instead of a single `children` string."
-      }
-    },
-    "css": {
-      "caret-color": {
-        "description": "Typewriter caret color."
-      }
-    }
-  }
-}

package/dist/consumption.json

@@ -1,84 +0,0 @@
-{
-  "summary": "Minimal bootstrap for external apps consuming @viraui/react.",
-  "requiredPackages": {
-    "@viraui/react": "Public components, preflight CSS, and usage guides.",
-    "react": "Peer dependency.",
-    "react-dom": "Peer dependency.",
-    "@base-ui/react": "Peer dependency for wrapped primitives."
-  },
-  "optionalPackages": {
-    "@viraui/foundation": "Preset Vira brand theme CSS, ThemeTypes, and JSON only.",
-    "@viraui/icons": "Optional Vira content glyphs (@viraui/icons/react). Icon slots accept any ReactNode (lucide-react, other libraries, custom SVG). Chrome defaults are inlined in @viraui/react."
-  },
-  "importOrder": [
-    "Compatible theme CSS (preset @viraui/foundation/vira.css, custom theme CSS, or future theme-builder export)",
-    "Consumer font CSS or @font-face rules matching theme font-family strings (for example @fontsource-variable packages)",
-    "@viraui/react/preflight.css"
-  ],
-  "componentCss": {
-    "rule": "Import public components from the @viraui/react root barrel. Component CSS follows the JS module graph through side-effect CSS imports.",
-    "optionalExplicitImport": "@viraui/react/<component>.css for tree-shaking or debugging only; not part of default bootstrap."
-  },
-  "cascadeLayers": {
-    "orderDeclaredIn": "@viraui/react/preflight.css",
-    "alsoRedeclaredIn": "Every emitted component CSS file (first statement)",
-    "order": ["viraui.preflight", "viraui.components", "viraui.overrides"],
-    "rule": "Preflight owns the canonical @layer order; component CSS re-declares the same order so bundlers that inject component CSS before preflight still lock preflight < components < overrides. Default component rules use viraui.components; cross-component same-node overrides use viraui.overrides. Unlayered app CSS beats all Vira layers."
-  },
-  "importMechanism": {
-    "rule": "Load theme CSS, font CSS, and preflight through JavaScript side-effect imports in the app root entry module. Import public components from the @viraui/react root barrel; component CSS follows the emitted JavaScript module graph and is not part of bootstrap.",
-    "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."
-  },
-  "rootProviders": {
-    "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. Overlay composition details stay in colocated *.guide.json and viraui-design composition.md.",
-    "tree": [
-      "Dialog.Provider",
-      "Dialog.IndentBackground (sibling of Indent)",
-      "Dialog.Indent (wraps app + toast viewport)",
-      "Tooltip.Provider",
-      "Toast.Provider toastManager={toastManager}",
-      "children",
-      "Toast.Portal > Toast.Viewport > Toast.Banner per toast"
-    ],
-    "nextJsAppRouter": "Keep CSS side-effect imports in the Server Component root layout. Put the provider tree in a Client Component that wraps children.",
-    "astro": "React context does not cross Astro islands. Providers must live in the same island as the Vira overlays that consume them.",
-    "rtl": "For RTL menus and popups, wrap with Base UI DirectionProvider direction=\"rtl\" and set dir=\"rtl\" on a portal ancestor (usually html)."
-  },
-  "nextJsAppRouter": {
-    "mandatory": true,
-    "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.",
-    "entryModule": "app/layout.tsx",
-    "importOrder": [
-      "Compatible theme CSS (preset @viraui/foundation/vira.css, custom theme CSS, or future theme-builder export)",
-      "Consumer font CSS or @fontsource-variable packages matching theme font-family strings",
-      "@viraui/react/preflight.css"
-    ],
-    "requiredImports": [
-      "import '@viraui/foundation/vira.css'",
-      "import '@fontsource-variable/geist/wght.css'",
-      "import '@fontsource-variable/geist-mono/wght.css'",
-      "import '@viraui/react/preflight.css'"
-    ],
-    "forbidden": {
-      "location": "app/globals.css",
-      "mechanism": "CSS @import",
-      "targets": ["@viraui/foundation/*", "@viraui/react/preflight.css", "@fontsource-variable/*"]
-    },
-    "globalsCssScope": "App-owned global styles only; no @viraui/* or font-package @import",
-    "providers": "Client Component wrapping children; CSS imports stay in app/layout.tsx",
-    "layoutExample": [
-      "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';"
-    ]
-  },
-  "discovery": {
-    "catalog": "@viraui/react/catalog.json",
-    "consumption": "@viraui/react/consumption.json",
-    "themeSurface": "@viraui/react/theme-surface.json",
-    "preflightSurface": "@viraui/react/preflight-surface.json",
-    "componentGuide": "@viraui/react/<component>.guide.json"
-  }
-}

package/dist/preflight-surface.json

@@ -1,233 +0,0 @@
-{
-  "summary": "Data attributes and related CSS custom properties exposed by @viraui/react/preflight.css.",
-  "prerequisite": "Import compatible theme CSS, then @viraui/react/preflight.css. See @viraui/react/consumption.json.",
-  "sourceModules": [
-    {
-      "id": "themes",
-      "file": "modes.css",
-      "purpose": "Runtime color-scheme hints for light, dark, and inverted mode."
-    },
-    {
-      "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))."
-    },
-    {
-      "id": "typography",
-      "file": "typography.css",
-      "purpose": "Semantic HTML element typography and link styling opt-out."
-    },
-    {
-      "id": "elevations",
-      "file": "elevations.css",
-      "purpose": "Theme-gated resting and hover box-shadow elevation stacks plus unlayered box-shadow transitions."
-    },
-    {
-      "id": "layout",
-      "file": "layout.css",
-      "purpose": "Flex growth and shrink utilities via data-grow / data-shrink for Stack and component children."
-    },
-    {
-      "id": "vibrancy",
-      "file": "vibrancy.css",
-      "purpose": "Theme-gated backdrop-filter vibrancy on elements that opt in with data-vibrant."
-    }
-  ],
-  "attributes": [
-    {
-      "name": "data-mode",
-      "module": "themes",
-      "values": ["light", "dark", "inverted"],
-      "presence": "value required",
-      "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.",
-      "whenToUse": [
-        "Toggle runtime light or dark mode on html, body, or a layout wrapper",
-        "Scope a subtree to one mode while the rest of the page stays unchanged",
-        "Invert color-scheme on a nested surface that must contrast the active theme, for example a primary Chip addon inside a primary Button"
-      ],
-      "whenNotToUse": [
-        "As a substitute for loading compatible theme CSS",
-        "To swap brand stylesheets; use theme CSS imports instead"
-      ],
-      "related": ["data-mode is independent from brand stylesheet selection; see runtime-enhancements.md"]
-    },
-    {
-      "name": "data-no-link-style",
-      "module": "typography",
-      "values": ["(boolean presence)"],
-      "presence": "boolean attribute on anchor elements",
-      "effect": "Excludes the anchor from preflight default link styling (interactive color, no underline, animated underline on unclassed links).",
-      "whenToUse": [
-        "Links that must keep component-owned or custom link chrome",
-        "Anchors inside Button, IconButton, or other interactive surfaces"
-      ],
-      "whenNotToUse": ["Standard inline prose links that should inherit preflight link styling"],
-      "related": []
-    },
-    {
-      "name": "data-elevation",
-      "module": "elevations",
-      "values": ["0", "1", "2", "3", "4"],
-      "presence": "value required",
-      "effect": "When the active theme sets --effect-shadows, applies resting box-shadow stack for the chosen elevation level.",
-      "whenToUse": [
-        "Static surfaces such as cards, panels, and popovers",
-        "Direct DOM usage without the Elevator component"
-      ],
-      "whenNotToUse": [
-        "When Elevator or getElevationProps already sets elevation hooks on the target element",
-        "When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)"
-      ],
-      "related": ["Elevator", "Surface", "getElevationProps", "--effect-shadows"]
-    },
-    {
-      "name": "data-elevation-hover",
-      "module": "elevations",
-      "values": ["0", "1", "2", "3", "4"],
-      "presence": "optional value",
-      "effect": "When the active theme sets --effect-shadows, applies a different elevation level on :hover than the resting data-elevation value.",
-      "whenToUse": [
-        "Interactive surfaces that should lift on hover",
-        "Pair with data-elevation for resting and hover shadow levels"
-      ],
-      "whenNotToUse": [
-        "When hover elevation is not desired; omit the attribute entirely",
-        "When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)"
-      ],
-      "related": ["Elevator", "getElevationProps", "--effect-shadows"]
-    },
-    {
-      "name": "data-elevation-direction",
-      "module": "elevations",
-      "values": ["bottom", "top", "left", "right"],
-      "presence": "optional; defaults to bottom when data-elevation is present",
-      "effect": "When the active theme sets --effect-shadows, casts the shadow downward, upward, to the left, or to the right.",
-      "whenToUse": ["Side drawers, top bars, or lateral panels where shadow direction matters"],
-      "whenNotToUse": [
-        "When default bottom cast is sufficient",
-        "When the theme sets --effect-shadows: initial (attr is a no-op for box-shadow)"
-      ],
-      "related": ["Elevator", "getElevationProps", "--effect-shadows"]
-    },
-    {
-      "name": "data-grow",
-      "module": "layout",
-      "values": ["true", "false"],
-      "presence": "optional; omit for default flex growth",
-      "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.",
-      "whenToUse": [
-        "Force grow or opt out on an expandChildren direct child",
-        "Fixed-width icons, indicators, or trailing slots (false)"
-      ],
-      "whenNotToUse": [
-        "When default flex growth is already correct",
-        "Expecting ancestor data-grow to change nested expandChildren children"
-      ],
-      "related": ["Stack", "--vira-flex-grow"]
-    },
-    {
-      "name": "data-shrink",
-      "module": "layout",
-      "values": ["true", "false"],
-      "presence": "optional; omit for default flex shrink",
-      "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.",
-      "whenToUse": [
-        "Force shrink or resist shrink on that flex item",
-        "Labels, icons, or controls that must keep intrinsic width (false)"
-      ],
-      "whenNotToUse": [
-        "When default flex shrink is already correct",
-        "Expecting ancestor data-shrink to change nested flex consumers"
-      ],
-      "related": ["Stack", "--vira-flex-shrink"]
-    },
-    {
-      "name": "data-vibrant",
-      "module": "vibrancy",
-      "values": ["(boolean presence)"],
-      "presence": "boolean attribute; value ignored",
-      "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.",
-      "whenToUse": [
-        "Glass / frosted panels on Surface or other hosts over busy backgrounds",
-        "Match overlay chrome (Dialog/Popover/Menu/Toast) that ships with data-vibrant"
-      ],
-      "whenNotToUse": [
-        "When the theme does not expose --effect-vibrancy (attr is a no-op for filters)",
-        "Hand-rolling backdrop-filter CSS instead of the documented attr"
-      ],
-      "related": ["Surface", "--effect-vibrancy", "--vibrancy-blur", "--vibrancy-brightness"]
-    }
-  ],
-  "customProperties": [
-    {
-      "name": "--is-light-mode",
-      "module": "themes",
-      "setBy": "html root in core.css from contrast-color(var(--global-background))",
-      "default": "black",
-      "purpose": "Registers the active theme polarity for @container root queries; data-mode=\"inverted\" flips color-scheme against this value."
-    },
-    {
-      "name": "--shadow-color",
-      "module": "elevations",
-      "setBy": "inline style or component elevation mapping",
-      "default": "oklch(0% 0 0)",
-      "purpose": "Shadow tint for data-elevation stacks."
-    },
-    {
-      "name": "--extra-shadow",
-      "module": "elevations",
-      "setBy": "inline style or component elevation mapping",
-      "default": "0 0 0 1px transparent",
-      "purpose": "Additional box-shadow layer appended to elevation stacks, for example hairline borders."
-    },
-    {
-      "name": "--elevation-transition-duration",
-      "module": "elevations",
-      "setBy": "inline style or theme override",
-      "default": "160ms",
-      "purpose": "Duration for data-elevation box-shadow transitions."
-    },
-    {
-      "name": "--elevation-transition-easing",
-      "module": "elevations",
-      "setBy": "inline style or theme override",
-      "default": "ease",
-      "purpose": "Timing function for data-elevation box-shadow transitions."
-    },
-    {
-      "name": "--vira-flex-grow",
-      "module": "layout",
-      "setBy": "data-grow=\"true\" or data-grow=\"false\"; registered in global-properties.css",
-      "default": "1 (initial-value); inherits: false; Stack expandChildren uses var(--vira-flex-grow, 1)",
-      "purpose": "Local grow signal for Stack expandChildren / child flex defaults; does not inherit so ancestor data-grow cannot poison nested stacks."
-    },
-    {
-      "name": "--vira-flex-shrink",
-      "module": "layout",
-      "setBy": "data-shrink=\"true\" or data-shrink=\"false\"; registered in global-properties.css",
-      "default": "1 (initial-value); inherits: false",
-      "purpose": "Local shrink signal for flex defaults; does not inherit so ancestor data-shrink cannot poison descendants."
-    },
-    {
-      "name": "--__corner-shape",
-      "module": "core",
-      "setBy": "ViraUI components on the same element as infinite / pill radius (CSS modules or React style); registered in global-properties.css",
-      "default": "guaranteed-invalid (no initial-value); inherits: false; preflight uses var(--__corner-shape, var(--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."
-    }
-  ],
-  "antiPatterns": [
-    "Using data-elevation without importing @viraui/react/preflight.css",
-    "Fighting data-mode color-scheme rules without documenting a deliberate override",
-    "Applying data-no-link-style to prose links that should use the default interactive underline treatment",
-    "Inventing backdrop-filter CSS instead of data-vibrant when vibrancy is desired",
-    "Inventing box-shadow CSS instead of data-elevation when theme-gated shadows are desired",
-    "Shipping a new consumer-facing data-* without updating preflight-surface.json and viraui-design/custom-attributes.md",
-    "Relying on ancestor data-grow / data-shrink to control nested Stack expandChildren (props do not inherit)"
-  ],
-  "discovery": {
-    "consumption": "@viraui/react/consumption.json",
-    "themeSurface": "@viraui/react/theme-surface.json",
-    "elevationUtility": "Elevator and getElevationProps from @viraui/react"
-  }
-}