@usefragments/ui 1.6.0 → 1.7.0

package/src/tokens/_variables.scss

@@ -47,8 +47,8 @@ $fui-base-unit: computed.$computed-base-unit !default;
 // Typography
 // --------------------------------------------
 $fui-font-sans:
-  "Inter Variable",
-  Inter,
+  "Onest Variable",
+  Onest,
   -apple-system,
   BlinkMacSystemFont,
   "Segoe UI",
@@ -188,6 +188,17 @@ $fui-radius-lg: computed.$computed-radius-lg !default;
 $fui-radius-xl: computed.$computed-radius-xl !default;
 $fui-radius-full: computed.$computed-radius-full !default;
 
+// --------------------------------------------
+// Strokes + control tracks (mirror the measurement CSS vars for SCSS fallbacks)
+// --------------------------------------------
+$fui-stroke-hairline: measurements.target-value("stroke", "hairline") !default;
+$fui-stroke-default: measurements.target-value("stroke", "default") !default;
+$fui-stroke-strong: measurements.target-value("stroke", "strong") !default;
+$fui-control-track-micro: measurements.target-value("controlTrack", "micro") !default;
+$fui-control-track-sm: measurements.target-value("controlTrack", "sm") !default;
+$fui-control-track-md: measurements.target-value("controlTrack", "md") !default;
+$fui-control-track-lg: measurements.target-value("controlTrack", "lg") !default;
+
 // --------------------------------------------
 // Transitions
 // --------------------------------------------
@@ -236,9 +247,10 @@ $fui-bg-elevated: computed.$computed-bg-elevated !default;
 $fui-bg-subtle: computed.$computed-bg-subtle !default;
 $fui-bg-hover: computed.$computed-bg-hover !default;
 $fui-bg-active: computed.$computed-bg-active !default;
-// The document canvas stays white in light mode. Component and app surfaces
-// continue to use the computed neutral palette.
-$fui-body-bg: #fff !default;
+// The document canvas is the derived "paper" tone in light mode (carbon 100).
+// Body and main stay on that shared plane; raised component roles provide the
+// contrast instead of consumer-specific page overrides.
+$fui-body-bg: computed.$computed-body-bg !default;
 $fui-main-bg: computed.$computed-main-bg !default;
 
 // Text colors (derived from $fui-neutral palette)
@@ -413,6 +425,19 @@ $fui-icon-2xl: measurements.target-value("icon", "2xl") !default;
 $fui-anim-offset-sm: 4px !default; // Small slide animation
 $fui-anim-offset-md: 8px !default; // Medium slide animation
 
+// Ambient loop durations — infinite animations (spinners, pulses, shimmer).
+// Easing stays per-effect; duration is the system knob.
+$fui-duration-spin: 800ms !default; // Busy indicators
+$fui-duration-pulse: 1500ms !default; // Breathing / attention loops
+$fui-duration-shimmer: 2000ms !default; // Placeholder shimmer
+
+// Overlay stacking layers (kept adjacent so relative order is auditable)
+$fui-overlay-layer-swipe: 49 !default;
+$fui-overlay-layer-backdrop: 50 !default;
+$fui-overlay-layer-modal: 51 !default;
+$fui-overlay-layer-anchored: 52 !default;
+$fui-overlay-layer-tooltip: 60 !default;
+
 // Sidebar (multi-consumer — used by Sidebar, NavigationMenu, Theme)
 $fui-sidebar-item-height: computed.$computed-sidebar-item-height !default; // density-responsive (compact/default: 32px, relaxed: 36px)
 
@@ -427,12 +452,48 @@ $fui-header-z-index: 40 !default;
 // CodeBlock background — shared with Markdown's <pre> prose styling — and
 // selection tint are runtime hooks so consuming apps can preserve their own
 // code-surface treatment without forking either component.
-$fui-code-bg: #171717 !default;
+// Light stop is the paper tertiary well — not a second dark grey.
+$fui-code-bg: light-dark(#{$fui-bg-tertiary}, #{$fui-dark-bg-tertiary}) !default;
+// Accent capsule — the tertiary well + wash/hairline, so the earned moment
+// sits *into* the page rather than floating a white slab on it (lifted-verdict
+// direction, 2026-08-22). Do not mix toward black: that paints a dark slab on
+// the light canvas.
+$fui-card-accent-bg: $fui-bg-tertiary !default;
+$fui-card-accent-border: color-mix(in srgb, $fui-color-accent 30%, $fui-border) !default;
+// Softer than a panel: the capsule is a moment, not another card.
+$fui-card-accent-radius: $fui-radius-xl !default;
+// Selection tint tracks the accent (pine light / sage dark), not the button
+// chrome — the ink-first default theme paints buttons with the inverse
+// surface, which would grey out code selection.
 $fui-code-selection-bg: color-mix(
   in srgb,
-  var(--fui-button-primary-base, #006b57) 30%,
+  var(--fui-color-accent, #f56138) 30%,
   transparent
 ) !default;
+// Default code ink follows primary text so unhighlighted fallback and shiki
+// `css-variables` foreground stay on the same contrast floor.
+$fui-code-text: $fui-text-primary !default;
+// Syntax ink for CodeBlock's css-variables theme. Each light stop is ≥ 4.5:1
+// on the light code well; each dark stop is ≥ 4.5:1 on the dark code well
+// (gated by read-safe-contrast.test.ts).
+$fui-code-token-keyword: #9a3412 !default;
+$fui-code-token-string: #166534 !default;
+$fui-code-token-comment: #5c5348 !default;
+$fui-code-token-function: #1e3a8a !default;
+$fui-code-token-number: #92400e !default;
+$fui-code-token-punctuation: #3d3429 !default;
+$fui-code-token-variable: #3d3429 !default;
+$fui-dark-code-token-keyword: #f56138 !default;
+$fui-dark-code-token-string: #7dcea0 !default;
+$fui-dark-code-token-comment: #a89b8c !default;
+$fui-dark-code-token-function: #8cb4e8 !default;
+$fui-dark-code-token-number: #e8b86d !default;
+$fui-dark-code-token-punctuation: #c9c2b8 !default;
+$fui-dark-code-token-variable: #f0ede9 !default;
+// Prose/link ink. Light is a darker accent step so 4.5:1 holds on
+// --fui-app-main-bg; dark keeps the theme accent (already ≥ 4.5).
+$fui-link-ink: #9a3412 !default;
+$fui-dark-link-ink: $fui-dark-color-accent !default;
 
 // --------------------------------------------
 // CSS Custom Properties Export
@@ -525,6 +586,20 @@ $fui-code-selection-bg: color-mix(
     --fui-transition-fast: #{$fui-transition-fast};
     --fui-transition-normal: #{$fui-transition-normal};
 
+    // Motion primitives
+    --fui-anim-offset-sm: #{$fui-anim-offset-sm};
+    --fui-anim-offset-md: #{$fui-anim-offset-md};
+    --fui-duration-spin: #{$fui-duration-spin};
+    --fui-duration-pulse: #{$fui-duration-pulse};
+    --fui-duration-shimmer: #{$fui-duration-shimmer};
+
+    // Overlay stacking layers
+    --fui-overlay-layer-swipe: #{$fui-overlay-layer-swipe};
+    --fui-overlay-layer-backdrop: #{$fui-overlay-layer-backdrop};
+    --fui-overlay-layer-modal: #{$fui-overlay-layer-modal};
+    --fui-overlay-layer-anchored: #{$fui-overlay-layer-anchored};
+    --fui-overlay-layer-tooltip: #{$fui-overlay-layer-tooltip};
+
     // Colors — Accent (light-dark for automatic dark mode)
     --fui-color-accent: light-dark(#{$fui-color-accent}, #{$fui-dark-color-accent});
     --fui-color-on-accent: light-dark(#{$fui-color-on-accent}, #{$fui-dark-color-on-accent});
@@ -626,15 +701,36 @@ $fui-code-selection-bg: color-mix(
     --fui-border-strong: light-dark(#{$fui-border-strong}, #{$fui-dark-border-strong});
     --fui-border-subtle: color-mix(in srgb, var(--fui-border-default) 68%, transparent);
 
+    // Placeholder fills. A skeleton has to read as a *missing fact* against the
+    // card it sits in — a hairline-weight tint is invisible on paper, so the
+    // base leans on the border colour and the highlight is the shimmer stop.
+    --fui-skeleton: color-mix(in srgb, var(--fui-border-default) 62%, var(--fui-bg-secondary));
+    --fui-skeleton-hi: color-mix(in srgb, var(--fui-border-default) 24%, var(--fui-bg-secondary));
+
     // Native browser text selection tracks the accent (pine in light, sage in
     // dark) as a soft wash — matching the Flight Recorder accent-tint.
     // Component-selected states stay tuned per control density.
     --fui-selection-bg: light-dark(
-      color-mix(in srgb, var(--fui-color-accent, #006b57) 18%, transparent),
-      color-mix(in srgb, var(--fui-color-accent, #7fc9b3) 22%, transparent)
+      color-mix(in srgb, var(--fui-color-accent, #f56138) 18%, transparent),
+      color-mix(in srgb, var(--fui-color-accent, #f56138) 22%, transparent)
     );
     --fui-selection-color: var(--fui-text-primary);
 
+    // Persistent neutral selection for navigation, segmented controls, fields,
+    // and rows. Keep this separate from --fui-bg-active: active is the brief
+    // pointer-down state; selected must remain visible without dominating its
+    // surrounding surface.
+    --fui-control-selected-bg: color-mix(in srgb, var(--fui-text-primary) 9%, transparent);
+
+    // Checked/value controls carry product meaning, so they follow the accent
+    // rather than button chrome. This keeps Checkbox, RadioGroup, and Switch
+    // stable when a consumer customizes primary actions independently.
+    --fui-control-checked-bg: var(--fui-color-accent);
+    --fui-control-checked-bg-hover: var(--fui-color-accent-hover);
+    --fui-control-checked-border: var(--fui-color-accent);
+    --fui-control-checked-border-hover: var(--fui-color-accent-hover);
+    --fui-control-checked-color: var(--fui-color-on-accent);
+
     // Form chrome (shared by Input, Textarea, Select, Combobox, DatePicker,
     // ColorPicker, Editor, and listbox-style controls).
     --fui-field-bg: color-mix(in srgb, var(--fui-bg-elevated) 72%, transparent);
@@ -646,7 +742,7 @@ $fui-code-selection-bg: color-mix(
       var(--fui-border-strong)
     );
     --fui-field-border-focus: var(--fui-text-primary);
-    --fui-field-selection-bg: color-mix(in srgb, var(--fui-text-primary) 8%, transparent);
+    --fui-field-selection-bg: var(--fui-control-selected-bg);
     --fui-field-selection-bg-hover: color-mix(in srgb, var(--fui-text-primary) 11%, transparent);
     --fui-field-selection-border: var(--fui-border-strong);
     --fui-field-selection-color: var(--fui-text-primary);
@@ -673,28 +769,36 @@ $fui-code-selection-bg: color-mix(
 
     // Button chrome. Every theme uses flat fills: hierarchy comes from colour,
     // border, and state contrast rather than a second raised/gradient material.
-    // Radius remains brand-aware for compatibility with consumer themes.
-    --fui-button-primary-base: light-dark(#006b57, #006b57);
-    --fui-button-primary-hover: light-dark(#187762, #187762);
-    --fui-button-primary-active: light-dark(#005f4c, #005f4c);
-    --fui-button-primary-border-hover: color-mix(
-      in srgb,
-      var(--fui-button-primary-active) 86%,
-      black 14%
-    );
-    --fui-button-primary-border: color-mix(
-      in srgb,
-      var(--fui-button-primary-active) 74%,
-      black 26%
-    );
-    --fui-button-primary-color: #fff;
-
+    //
+    // The Fragments default is ink-first: the primary action wears the inverse
+    // surface (near-black on paper, near-white on charcoal) with the accent
+    // reserved for meaning — links, selection, focus, "contract passing".
+    // A consumer-supplied $fui-brand switches primary chrome to the accent
+    // ramp so their brand colour actually paints their buttons (previously the
+    // chrome stayed pine regardless of seed).
     @if $fui-brand-is-default {
-      --fui-button-radius: var(--fui-radius-full);
+      --fui-button-primary-base: var(--fui-bg-inverse);
+      --fui-button-primary-hover: light-dark(
+        color-mix(in srgb, var(--fui-bg-inverse) 88%, white),
+        #ffffff
+      );
+      --fui-button-primary-active: light-dark(
+        color-mix(in srgb, var(--fui-bg-inverse) 92%, black),
+        color-mix(in srgb, var(--fui-bg-inverse) 94%, black)
+      );
+      --fui-button-primary-color: var(--fui-text-inverse);
+      --fui-button-radius: var(--fui-radius-xl);
     } @else {
+      --fui-button-primary-base: var(--fui-color-accent);
+      --fui-button-primary-hover: var(--fui-color-accent-hover);
+      --fui-button-primary-active: var(--fui-color-accent-active);
+      --fui-button-primary-color: var(--fui-color-on-accent);
       --fui-button-radius: var(--fui-radius-lg);
     }
 
+    --fui-button-primary-border: var(--fui-button-primary-base);
+    --fui-button-primary-border-hover: var(--fui-button-primary-hover);
+
     --fui-button-primary-bg: var(--fui-button-primary-base);
     --fui-button-primary-bg-hover: var(--fui-button-primary-hover);
     --fui-button-primary-bg-active: var(--fui-button-primary-active);
@@ -730,6 +834,33 @@ $fui-code-selection-bg: color-mix(
 
     --fui-code-bg: #{$fui-code-bg};
     --fui-code-selection-bg: #{$fui-code-selection-bg};
+    --fui-code-text: var(--fui-text-primary);
+    --fui-code-token-keyword: light-dark(
+      #{$fui-code-token-keyword},
+      #{$fui-dark-code-token-keyword}
+    );
+    --fui-code-token-string: light-dark(#{$fui-code-token-string}, #{$fui-dark-code-token-string});
+    --fui-code-token-comment: light-dark(
+      #{$fui-code-token-comment},
+      #{$fui-dark-code-token-comment}
+    );
+    --fui-code-token-function: light-dark(
+      #{$fui-code-token-function},
+      #{$fui-dark-code-token-function}
+    );
+    --fui-code-token-number: light-dark(#{$fui-code-token-number}, #{$fui-dark-code-token-number});
+    --fui-code-token-punctuation: light-dark(
+      #{$fui-code-token-punctuation},
+      #{$fui-dark-code-token-punctuation}
+    );
+    --fui-code-token-variable: light-dark(
+      #{$fui-code-token-variable},
+      #{$fui-dark-code-token-variable}
+    );
+    --fui-link-ink: light-dark(#{$fui-link-ink}, #{$fui-dark-link-ink});
+    --fui-card-accent-bg: var(--fui-bg-tertiary);
+    --fui-card-accent-border: color-mix(in srgb, var(--fui-color-accent) 30%, var(--fui-border));
+    --fui-card-accent-radius: #{$fui-card-accent-radius};
 
     // Popup/menu active-item highlight — neutral, deliberately stronger than
     // --fui-bg-hover (which is tuned for subtle surface hovers and reads as ~invisible
@@ -740,15 +871,18 @@ $fui-code-selection-bg: color-mix(
     // Product shell and navigation chrome. These stay neutral-first so a
     // dashboard page reads as one system instead of brand-tinted islands.
     --fui-app-canvas-bg: var(--fui-body-bg);
-    --fui-app-main-bg: var(--fui-main-bg);
-    --fui-app-sidebar-bg: color-mix(in srgb, var(--fui-bg-primary) 78%, var(--fui-bg-secondary));
+    // Same surface order in both themes: the rail is recessed, the main
+    // reading sheet is raised. Light: tertiary paper rail, body-bg sheet.
+    // Dark keeps the lifted rail on a deeper body.
+    --fui-app-main-bg: var(--fui-body-bg);
+    --fui-app-sidebar-bg: var(--fui-bg-tertiary);
     --fui-sidebar-bg: var(--fui-app-sidebar-bg);
     --fui-sidebar-border: var(--fui-border-default);
     --fui-sidebar-item-color: var(--fui-text-secondary);
     --fui-sidebar-item-icon-color: var(--fui-text-tertiary);
     --fui-sidebar-item-hover-bg: var(--fui-bg-hover);
     --fui-sidebar-item-hover-color: var(--fui-text-primary);
-    --fui-sidebar-item-active-bg: color-mix(in srgb, var(--fui-text-primary) 8%, transparent);
+    --fui-sidebar-item-active-bg: var(--fui-control-selected-bg);
     --fui-sidebar-item-active-border: transparent;
     --fui-sidebar-item-active-color: var(--fui-text-primary);
     --fui-sidebar-item-active-indicator: transparent;
@@ -759,6 +893,11 @@ $fui-code-selection-bg: color-mix(
     --fui-badge-dot-color: currentColor;
     --fui-card-radius: var(--fui-radius-lg);
     --fui-card-bg: color-mix(in srgb, var(--fui-bg-elevated) 92%, transparent);
+    // Full-bleed card chrome (for example `Card.Header divided`) shares the
+    // raised-neutral plane with shell controls. Keep the semantic alias
+    // component-specific so consumers can tune card hierarchy without
+    // changing every subtle surface.
+    --fui-card-header-bg: var(--fui-bg-subtle);
     --fui-card-border: color-mix(in srgb, var(--fui-border-default) 86%, transparent);
     --fui-card-outlined-border: var(--fui-card-border);
     --fui-card-shadow: inset 0 1px 0
@@ -791,7 +930,7 @@ $fui-code-selection-bg: color-mix(
     --fui-table-header-border: var(--fui-border-strong);
     --fui-table-row-hover-bg: var(--fui-bg-hover);
     --fui-table-row-active-bg: var(--fui-bg-active);
-    --fui-table-row-selected-bg: color-mix(in srgb, var(--fui-text-primary) 8%, transparent);
+    --fui-table-row-selected-bg: var(--fui-control-selected-bg);
     --fui-table-row-selected-border: var(--fui-border-strong);
     --fui-table-subrow-bg: color-mix(in srgb, var(--fui-bg-secondary) 62%, transparent);
 
@@ -799,17 +938,18 @@ $fui-code-selection-bg: color-mix(
     --fui-tabs-pills-bg: color-mix(in srgb, var(--fui-text-primary) 5%, transparent);
     --fui-tabs-pills-border: var(--fui-border-default);
     --fui-tabs-pill-hover-bg: transparent;
-    --fui-tabs-pill-active-bg: color-mix(in srgb, var(--fui-text-primary) 9%, transparent);
+    --fui-tabs-pill-active-bg: var(--fui-control-selected-bg);
     --fui-tabs-pill-active-border: transparent;
     --fui-tabs-pill-active-shadow: none;
-    --fui-toggle-group-selected-bg: var(--fui-selection-bg);
-    --fui-toggle-group-selected-border: color-mix(
-      in srgb,
-      var(--fui-color-accent) 42%,
-      transparent
-    );
+    --fui-toggle-group-selected-bg: var(--fui-control-selected-bg);
+    --fui-toggle-group-selected-border: transparent;
     --fui-toggle-group-selected-shadow: none;
 
+    // Header search is persistent shell chrome rather than a ghost action.
+    // One surface step above divided card headers keeps this global affordance
+    // easy to find in both themes without turning it into a selected control.
+    --fui-header-search-bg: var(--fui-bg-hover);
+
     // Shadows (not <color> type — light-dark() can't be used, handled in dark overrides)
     --fui-shadow-sm: #{$fui-shadow-sm};
     --fui-shadow-md: #{$fui-shadow-md};
@@ -1091,6 +1231,11 @@ $fui-code-selection-bg: color-mix(
   --fui-bg-highlight: color-mix(in srgb, var(--fui-text-primary) 10%, transparent);
   --fui-body-bg: #{$fui-dark-body-bg};
   --fui-main-bg: #{$fui-dark-main-bg};
+  --fui-app-main-bg: var(--fui-main-bg);
+  // Paper primary == secondary in dark, so a mix of the two is a no-op.
+  // Tertiary is the lifted rail; main stays the deeper body.
+  --fui-app-sidebar-bg: var(--fui-bg-tertiary);
+  --fui-sidebar-bg: var(--fui-app-sidebar-bg);
   --fui-bg-inverse: #{$fui-dark-bg-inverse};
 
   // Text

package/src/utils/a11y.tsx

@@ -1,6 +1,6 @@
-'use client';
+"use client";
 
-import * as React from 'react';
+import * as React from "react";
 
 // ============================================
 // Unique ID Generator
@@ -27,7 +27,7 @@ export function useId(prefix?: string): string {
 
   const [id] = React.useState(() => {
     if (reactId) return reactId;
-    return `${prefix ? `${prefix}-` : 'fui-'}${++idCounter}`;
+    return `${prefix ? `${prefix}-` : "fui-"}${++idCounter}`;
   });
 
   return id;
@@ -55,45 +55,45 @@ export function useId(prefix?: string): string {
  * ```
  */
 export function useAnnounce(): {
-  announce: (message: string, priority?: 'polite' | 'assertive') => void;
+  announce: (message: string, priority?: "polite" | "assertive") => void;
 } {
   const politeRef = React.useRef<HTMLDivElement | null>(null);
   const assertiveRef = React.useRef<HTMLDivElement | null>(null);
 
   React.useEffect(() => {
     // Create live regions on mount
-    const polite = document.createElement('div');
-    polite.setAttribute('aria-live', 'polite');
-    polite.setAttribute('aria-atomic', 'true');
-    polite.setAttribute('role', 'status');
+    const polite = document.createElement("div");
+    polite.setAttribute("aria-live", "polite");
+    polite.setAttribute("aria-atomic", "true");
+    polite.setAttribute("role", "status");
     Object.assign(polite.style, {
-      position: 'absolute',
-      width: '1px',
-      height: '1px',
-      padding: '0',
-      margin: '-1px',
-      overflow: 'hidden',
-      clip: 'rect(0, 0, 0, 0)',
-      whiteSpace: 'nowrap',
-      border: '0',
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: "0",
     });
     document.body.appendChild(polite);
     politeRef.current = polite;
 
-    const assertive = document.createElement('div');
-    assertive.setAttribute('aria-live', 'assertive');
-    assertive.setAttribute('aria-atomic', 'true');
-    assertive.setAttribute('role', 'alert');
+    const assertive = document.createElement("div");
+    assertive.setAttribute("aria-live", "assertive");
+    assertive.setAttribute("aria-atomic", "true");
+    assertive.setAttribute("role", "alert");
     Object.assign(assertive.style, {
-      position: 'absolute',
-      width: '1px',
-      height: '1px',
-      padding: '0',
-      margin: '-1px',
-      overflow: 'hidden',
-      clip: 'rect(0, 0, 0, 0)',
-      whiteSpace: 'nowrap',
-      border: '0',
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: "0",
     });
     document.body.appendChild(assertive);
     assertiveRef.current = assertive;
@@ -106,11 +106,11 @@ export function useAnnounce(): {
   }, []);
 
   const announce = React.useCallback(
-    (message: string, priority: 'polite' | 'assertive' = 'polite') => {
-      const region = priority === 'assertive' ? assertiveRef.current : politeRef.current;
+    (message: string, priority: "polite" | "assertive" = "polite") => {
+      const region = priority === "assertive" ? assertiveRef.current : politeRef.current;
       if (region) {
         // Clear and re-set to ensure announcement
-        region.textContent = '';
+        region.textContent = "";
         // Use requestAnimationFrame to ensure the clear is processed
         requestAnimationFrame(() => {
           region.textContent = message;
@@ -146,20 +146,20 @@ export function usePrefersReducedMotion(): boolean {
   const [prefersReducedMotion, setPrefersReducedMotion] = React.useState(false);
 
   React.useEffect(() => {
-    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
 
     const handleChange = (event: MediaQueryListEvent) => {
       setPrefersReducedMotion(event.matches);
     };
 
     // Modern browsers
-    mediaQuery.addEventListener('change', handleChange);
+    mediaQuery.addEventListener("change", handleChange);
 
     // Set initial value
     setPrefersReducedMotion(mediaQuery.matches);
 
     return () => {
-      mediaQuery.removeEventListener('change', handleChange);
+      mediaQuery.removeEventListener("change", handleChange);
     };
   }, []);
 
@@ -183,17 +183,17 @@ export function usePrefersContrast(): boolean {
   const [prefersContrast, setPrefersContrast] = React.useState(false);
 
   React.useEffect(() => {
-    const mediaQuery = window.matchMedia('(prefers-contrast: more)');
+    const mediaQuery = window.matchMedia("(prefers-contrast: more)");
 
     const handleChange = (event: MediaQueryListEvent) => {
       setPrefersContrast(event.matches);
     };
 
-    mediaQuery.addEventListener('change', handleChange);
+    mediaQuery.addEventListener("change", handleChange);
     setPrefersContrast(mediaQuery.matches);
 
     return () => {
-      mediaQuery.removeEventListener('change', handleChange);
+      mediaQuery.removeEventListener("change", handleChange);
     };
   }, []);
 
@@ -219,10 +219,7 @@ export function usePrefersContrast(): boolean {
  * return <div ref={dialogRef}>...</div>;
  * ```
  */
-export function useFocusTrap(
-  ref: React.RefObject<HTMLElement | null>,
-  active: boolean
-): void {
+export function useFocusTrap(ref: React.RefObject<HTMLElement | null>, active: boolean): void {
   const previousActiveElement = React.useRef<Element | null>(null);
 
   React.useEffect(() => {
@@ -238,7 +235,7 @@ export function useFocusTrap(
     }
 
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== 'Tab') return;
+      if (event.key !== "Tab") return;
 
       const focusable = getFocusableElements(container);
       if (focusable.length === 0) return;
@@ -261,10 +258,10 @@ export function useFocusTrap(
       }
     };
 
-    container.addEventListener('keydown', handleKeyDown);
+    container.addEventListener("keydown", handleKeyDown);
 
     return () => {
-      container.removeEventListener('keydown', handleKeyDown);
+      container.removeEventListener("keydown", handleKeyDown);
 
       // Restore focus when trap is deactivated
       if (previousActiveElement.current instanceof HTMLElement) {
@@ -315,11 +312,11 @@ export function handleArrowNavigation(
   items: readonly unknown[],
   currentIndex: number,
   options: {
-    orientation?: 'horizontal' | 'vertical' | 'both';
+    orientation?: "horizontal" | "vertical" | "both";
     loop?: boolean;
   } = {}
 ): number | undefined {
-  const { orientation = 'vertical', loop = true } = options;
+  const { orientation = "vertical", loop = true } = options;
   const length = items.length;
 
   if (length === 0) return undefined;
@@ -327,8 +324,8 @@ export function handleArrowNavigation(
   let newIndex: number | undefined;
 
   switch (event.key) {
-    case 'ArrowDown':
-      if (orientation === 'horizontal') return undefined;
+    case "ArrowDown":
+      if (orientation === "horizontal") return undefined;
       event.preventDefault();
       newIndex = currentIndex + 1;
       if (newIndex >= length) {
@@ -336,8 +333,8 @@ export function handleArrowNavigation(
       }
       break;
 
-    case 'ArrowUp':
-      if (orientation === 'horizontal') return undefined;
+    case "ArrowUp":
+      if (orientation === "horizontal") return undefined;
       event.preventDefault();
       newIndex = currentIndex - 1;
       if (newIndex < 0) {
@@ -345,8 +342,8 @@ export function handleArrowNavigation(
       }
       break;
 
-    case 'ArrowRight':
-      if (orientation === 'vertical') return undefined;
+    case "ArrowRight":
+      if (orientation === "vertical") return undefined;
       event.preventDefault();
       newIndex = currentIndex + 1;
       if (newIndex >= length) {
@@ -354,8 +351,8 @@ export function handleArrowNavigation(
       }
       break;
 
-    case 'ArrowLeft':
-      if (orientation === 'vertical') return undefined;
+    case "ArrowLeft":
+      if (orientation === "vertical") return undefined;
       event.preventDefault();
       newIndex = currentIndex - 1;
       if (newIndex < 0) {
@@ -363,12 +360,12 @@ export function handleArrowNavigation(
       }
       break;
 
-    case 'Home':
+    case "Home":
       event.preventDefault();
       newIndex = 0;
       break;
 
-    case 'End':
+    case "End":
       event.preventDefault();
       newIndex = length - 1;
       break;
@@ -384,7 +381,7 @@ export function handleArrowNavigation(
 // Screen Reader Only Component
 // ============================================
 
-export interface VisuallyHiddenProps {
+export interface A11yVisuallyHiddenProps {
   children: React.ReactNode;
   /** If true, becomes visible when focused (useful for skip links) */
   focusable?: boolean;
@@ -408,19 +405,22 @@ export interface VisuallyHiddenProps {
  * </VisuallyHidden>
  * ```
  */
-export function VisuallyHidden({ children, focusable = false }: VisuallyHiddenProps): React.ReactElement {
+export function A11yVisuallyHidden({
+  children,
+  focusable = false,
+}: A11yVisuallyHiddenProps): React.ReactElement {
   const style: React.CSSProperties = focusable
     ? {}
     : {
-        position: 'absolute',
-        width: '1px',
-        height: '1px',
-        padding: '0',
-        margin: '-1px',
-        overflow: 'hidden',
-        clip: 'rect(0, 0, 0, 0)',
-        whiteSpace: 'nowrap',
-        border: '0',
+        position: "absolute",
+        width: "1px",
+        height: "1px",
+        padding: "0",
+        margin: "-1px",
+        overflow: "hidden",
+        clip: "rect(0, 0, 0, 0)",
+        whiteSpace: "nowrap",
+        border: "0",
       };
 
   return (

package/src/utils/aria.ts

@@ -1,11 +1,11 @@
-import * as React from 'react';
+import * as React from "react";
 
 /**
  * Merge multiple aria ID values into a single space-separated string.
  * Filters out undefined/empty values. Returns undefined if no valid IDs.
  */
 export function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
-  const merged = ids.filter(Boolean).join(' ').trim();
+  const merged = ids.filter(Boolean).join(" ").trim();
   return merged.length > 0 ? merged : undefined;
 }
 
@@ -19,7 +19,7 @@ export function normalizeError(error?: boolean | string): {
 } {
   return {
     hasError: !!error,
-    errorMessage: typeof error === 'string' ? error : undefined,
+    errorMessage: typeof error === "string" ? error : undefined,
   };
 }