shadcn-glass-ui 1.0.7 → 1.0.8

package/dist/components.d.ts

@@ -21,6 +21,71 @@ declare interface AICardGlassProps extends React.HTMLAttributes<HTMLDivElement>
 
 export declare const AlertGlass: ForwardRefExoticComponent<AlertGlassProps & RefAttributes<HTMLDivElement>>;
 
+/**
+ * Props for the AlertGlass component
+ *
+ * A glass-themed alert with semantic variants, dismissible option, and automatic icon selection.
+ * Features theme-aware styling and WCAG-compliant role attributes.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Dismissible alerts include a keyboard-accessible close button (Tab + Enter/Space)
+ * - **Focus Management:** Close button receives visible focus ring (WCAG 2.4.7)
+ * - **Screen Readers:** Uses `role="alert"` for immediate announcement to screen readers (WCAG 4.1.3)
+ * - **Icon Semantics:** Icons are decorative and hidden from screen readers with `aria-hidden="true"`
+ * - **Variant Semantics:** Each variant uses distinct colors and icons for multi-modal communication (color + icon)
+ * - **Touch Targets:** Dismiss button meets minimum 44x44px touch target (WCAG 2.5.5)
+ * - **Color Contrast:** All variant text and backgrounds meet WCAG AA contrast ratio 4.5:1
+ * - **Motion:** Transitions respect `prefers-reduced-motion` settings
+ *
+ * @example
+ * ```tsx
+ * // Basic alert (info/default variant)
+ * <AlertGlass title="Information" variant="default">
+ *   This is an informational message
+ * </AlertGlass>
+ *
+ * // Error alert with aria-live for dynamic updates
+ * <AlertGlass variant="destructive" title="Error" aria-live="assertive">
+ *   Your session has expired. Please log in again.
+ * </AlertGlass>
+ *
+ * // Success alert
+ * <AlertGlass variant="success" title="Success">
+ *   Your changes have been saved successfully.
+ * </AlertGlass>
+ *
+ * // Warning alert
+ * <AlertGlass variant="warning" title="Warning">
+ *   Your subscription expires in 3 days.
+ * </AlertGlass>
+ *
+ * // Dismissible alert with accessible close button
+ * <AlertGlass
+ *   variant="default"
+ *   title="Welcome"
+ *   dismissible
+ *   onDismiss={() => setShowAlert(false)}
+ * >
+ *   Check out our new features!
+ * </AlertGlass>
+ *
+ * // Alert without title
+ * <AlertGlass variant="destructive">
+ *   Quick error message without title
+ * </AlertGlass>
+ *
+ * // Form validation alert
+ * <form onSubmit={handleSubmit}>
+ *   {formError && (
+ *     <AlertGlass variant="destructive" title="Validation Error" role="alert">
+ *       {formError}
+ *     </AlertGlass>
+ *   )}
+ *   <InputGlass label="Email" />
+ *   <ButtonGlass type="submit">Submit</ButtonGlass>
+ * </form>
+ * ```
+ */
 declare interface AlertGlassProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'title'>, VariantProps<typeof alertVariants> {
     readonly title?: string;
     readonly children: ReactNode;
@@ -99,6 +164,70 @@ declare type AvatarStatus = 'online' | 'offline' | 'busy' | 'away';
 
 export declare const BadgeGlass: ForwardRefExoticComponent<BadgeGlassProps & RefAttributes<HTMLSpanElement>>;
 
+/**
+ * Props for the BadgeGlass component
+ *
+ * A glass-themed badge with semantic variants and optional animated status dot.
+ * Features shadcn/ui compatible variants plus extended Glass UI variants.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Badges are non-interactive by default (display-only)
+ * - **Focus Management:** N/A - badges do not receive focus unless wrapped in interactive elements
+ * - **Screen Readers:** Semantic `<span>` element, content announced naturally
+ * - **Status Indicators:** Use `aria-label` to provide context for status badges (e.g., "Status: Active")
+ * - **Animated Dot:** Pulse animation respects `prefers-reduced-motion` settings
+ * - **Touch Targets:** N/A for display badges, ensure 44x44px if wrapping in button/link (WCAG 2.5.5)
+ * - **Color Contrast:** All variant text meets WCAG AA contrast ratio 4.5:1 against badge background
+ * - **Motion:** Dot pulse animation can be disabled for users with motion sensitivity
+ *
+ * @example
+ * ```tsx
+ * // Basic badge with variant
+ * <BadgeGlass variant="default">New</BadgeGlass>
+ *
+ * // Status badge with aria-label for screen readers
+ * <BadgeGlass variant="success" aria-label="Status: Active">
+ *   Active
+ * </BadgeGlass>
+ *
+ * // Different variants (shadcn/ui compatible)
+ * <BadgeGlass variant="default">Default</BadgeGlass>
+ * <BadgeGlass variant="secondary">Secondary</BadgeGlass>
+ * <BadgeGlass variant="destructive">Error</BadgeGlass>
+ * <BadgeGlass variant="outline">Outline</BadgeGlass>
+ *
+ * // Extended Glass UI variants
+ * <BadgeGlass variant="success">Success</BadgeGlass>
+ * <BadgeGlass variant="warning">Warning</BadgeGlass>
+ * <BadgeGlass variant="info">Info</BadgeGlass>
+ *
+ * // With animated status dot
+ * <BadgeGlass variant="success" dot aria-label="Status: Online">
+ *   Online
+ * </BadgeGlass>
+ * <BadgeGlass variant="destructive" dot aria-label="Status: Offline">
+ *   Offline
+ * </BadgeGlass>
+ *
+ * // Size variants
+ * <BadgeGlass size="sm">Small</BadgeGlass>
+ * <BadgeGlass size="md">Medium</BadgeGlass>
+ * <BadgeGlass size="lg">Large</BadgeGlass>
+ *
+ * // Inside interactive elements (ensure accessible labels)
+ * <button aria-label="Filter by active status">
+ *   Filter: <BadgeGlass variant="success">Active</BadgeGlass>
+ * </button>
+ *
+ * // Count badge with semantic meaning
+ * <div>
+ *   <span>Notifications</span>
+ *   <BadgeGlass variant="destructive" aria-label="3 unread notifications">
+ *     3
+ *   </BadgeGlass>
+ * </div>
+ * ```
+ */
 declare interface BadgeGlassProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'>, VariantProps<typeof badgeVariants> {
     readonly children: ReactNode;
     readonly variant?: BadgeVariant;
@@ -131,22 +260,33 @@ export declare const ButtonGlass: ForwardRefExoticComponent<ButtonGlassProps & R
  * A glass-themed button with ripple effects, loading states, and icon support.
  * Features theme-aware styling and hover animations.
  *
+ * @accessibility
+ * - **Keyboard Navigation:** Fully keyboard accessible with native `<button>` element
+ * - **Focus Management:** Visible focus ring using `--focus-glow` CSS variable (WCAG 2.4.7)
+ * - **Screen Readers:** Semantic `<button>` element, disabled state announced automatically
+ * - **Loading State:** When loading=true, button is disabled and loading spinner is visible
+ * - **Touch Targets:** Minimum 44x44px touch target (WCAG 2.5.5) via size variants
+ * - **Color Contrast:** All variants meet WCAG AA contrast ratio 4.5:1 minimum
+ * - **Motion:** Respects `prefers-reduced-motion` for ripple/shine animations
+ *
  * @example
  * ```tsx
  * // Basic button
  * <ButtonGlass variant="primary">Click me</ButtonGlass>
  *
- * // With icon
+ * // With icon and aria-label for icon-only buttons
  * <ButtonGlass icon={Check} iconPosition="left">Save</ButtonGlass>
+ * <ButtonGlass icon={X} size="icon" aria-label="Close dialog" />
  *
- * // Loading state
- * <ButtonGlass loading>Processing...</ButtonGlass>
+ * // Loading state (automatically disables and shows spinner)
+ * <ButtonGlass loading aria-live="polite">Processing...</ButtonGlass>
  *
  * // Different variants
  * <ButtonGlass variant="ghost">Cancel</ButtonGlass>
  * <ButtonGlass variant="success">Confirm</ButtonGlass>
+ * <ButtonGlass variant="destructive">Delete</ButtonGlass>
  *
- * // As a link (asChild pattern)
+ * // As a link (asChild pattern) - maintains semantic HTML
  * <ButtonGlass asChild variant="primary">
  *   <a href="/dashboard">Go to Dashboard</a>
  * </ButtonGlass>
@@ -155,6 +295,11 @@ export declare const ButtonGlass: ForwardRefExoticComponent<ButtonGlassProps & R
  * <ButtonGlass asChild variant="ghost">
  *   <Link href="/settings">Settings</Link>
  * </ButtonGlass>
+ *
+ * // Form submit button
+ * <ButtonGlass type="submit" variant="primary">
+ *   Submit Form
+ * </ButtonGlass>
  * ```
  */
 declare interface ButtonGlassProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'style'>, VariantProps<typeof buttonGlassVariants> {
@@ -245,6 +390,79 @@ declare interface CareerStatsHeaderGlassProps extends HTMLAttributes<HTMLDivElem
 
 export declare const CheckboxGlass: ForwardRefExoticComponent<CheckboxGlassProps & RefAttributes<HTMLInputElement>>;
 
+/**
+ * Props for the CheckboxGlass component
+ *
+ * A glass-themed checkbox with accessible keyboard navigation, focus management,
+ * and touch-friendly targets. Features glow effects and theme-aware styling.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Full keyboard support with Enter/Space to toggle, Tab to focus (WCAG 2.1.1)
+ * - **Focus Management:** Visible focus ring using `--focus-glow` CSS variable (WCAG 2.4.7)
+ * - **Screen Readers:** Dual implementation with native `<input type="checkbox">` (hidden) + visual `<div role="checkbox">`
+ * - **ARIA Attributes:** Uses `role="checkbox"` and `aria-checked` for proper state announcement
+ * - **Label Association:** Visual label automatically associated with checkbox via `<label>` wrapper
+ * - **Touch Targets:** 44x44px minimum touch area per Apple HIG (WCAG 2.5.5 compliance)
+ * - **Color Contrast:** Check mark and backgrounds meet WCAG AA contrast ratio 4.5:1
+ * - **Motion:** Transitions respect `prefers-reduced-motion` settings
+ *
+ * @example
+ * ```tsx
+ * // Basic checkbox with label
+ * <CheckboxGlass checked={agreed} onChange={setAgreed} label="I agree to terms" />
+ *
+ * // Checkbox with accessible name (no visual label)
+ * <CheckboxGlass
+ *   checked={checked}
+ *   onChange={setChecked}
+ *   aria-label="Select all items"
+ * />
+ *
+ * // Form integration with validation
+ * <form onSubmit={handleSubmit}>
+ *   <CheckboxGlass
+ *     checked={newsletter}
+ *     onChange={setNewsletter}
+ *     label="Subscribe to newsletter"
+ *     aria-describedby="newsletter-help"
+ *   />
+ *   <p id="newsletter-help">Receive weekly updates</p>
+ *   <CheckboxGlass
+ *     checked={terms}
+ *     onChange={setTerms}
+ *     label="Accept terms and conditions"
+ *     required
+ *     aria-invalid={submitted && !terms}
+ *   />
+ *   {submitted && !terms && (
+ *     <span role="alert">You must accept the terms</span>
+ *   )}
+ * </form>
+ *
+ * // Disabled checkbox (state announced to screen readers)
+ * <CheckboxGlass
+ *   checked={true}
+ *   onChange={() => {}}
+ *   label="This option is locked"
+ *   disabled
+ * />
+ *
+ * // Checkbox group with fieldset
+ * <fieldset>
+ *   <legend>Select your interests</legend>
+ *   <CheckboxGlass
+ *     checked={interests.tech}
+ *     onChange={(checked) => setInterests({ ...interests, tech: checked })}
+ *     label="Technology"
+ *   />
+ *   <CheckboxGlass
+ *     checked={interests.design}
+ *     onChange={(checked) => setInterests({ ...interests, design: checked })}
+ *     label="Design"
+ *   />
+ * </fieldset>
+ * ```
+ */
 declare interface CheckboxGlassProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange'> {
     readonly checked: boolean;
     readonly onChange?: (checked: boolean) => void;
@@ -392,6 +610,87 @@ declare interface ContributionMetricsGlassProps extends HTMLAttributes<HTMLDivEl
 
 export declare const DropdownGlass: React_2.ForwardRefExoticComponent<DropdownGlassProps & React_2.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Props for the DropdownGlass component
+ *
+ * A glass-themed dropdown menu with accessible keyboard navigation, based on Radix UI primitives.
+ * Features theme-aware styling, smooth animations, and WCAG-compliant interactions.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Arrow keys navigate menu items, Enter/Space activates, Escape closes (WCAG 2.1.1)
+ * - **Focus Management:** Focus trapped within menu when open, returned to trigger on close (WCAG 2.4.3)
+ * - **Screen Readers:** Uses `role="menu"` and `role="menuitem"` for proper menu semantics (WCAG 4.1.3)
+ * - **ARIA Attributes:** Items marked with `data-highlighted` state for screen reader announcement
+ * - **Trigger Association:** Menu automatically associated with trigger button via Radix UI primitives
+ * - **Touch Targets:** All menu items meet minimum 44x44px touch target (WCAG 2.5.5)
+ * - **Color Contrast:** Menu text and backgrounds meet WCAG AA contrast ratio 4.5:1
+ * - **Motion:** Open/close animations respect `prefers-reduced-motion` settings
+ *
+ * @example
+ * ```tsx
+ * // Basic dropdown with icon items
+ * <DropdownGlass
+ *   trigger={
+ *     <button aria-label="Open menu">
+ *       <MoreVertical className="w-5 h-5" />
+ *     </button>
+ *   }
+ *   items={[
+ *     { label: 'Edit', icon: Edit, onClick: handleEdit },
+ *     { label: 'Delete', icon: Trash, onClick: handleDelete, danger: true }
+ *   ]}
+ * />
+ *
+ * // Dropdown with dividers and alignment
+ * <DropdownGlass
+ *   trigger={<ButtonGlass>Actions</ButtonGlass>}
+ *   align="right"
+ *   items={[
+ *     { label: 'View', icon: Eye, onClick: () => navigate('/view') },
+ *     { label: 'Edit', icon: Edit, onClick: () => setEditMode(true) },
+ *     { divider: true },
+ *     { label: 'Archive', icon: Archive, onClick: handleArchive },
+ *     { divider: true },
+ *     { label: 'Delete', icon: Trash, onClick: handleDelete, danger: true }
+ *   ]}
+ * />
+ *
+ * // Dropdown in table row (ensure trigger has accessible label)
+ * <DropdownGlass
+ *   trigger={
+ *     <button aria-label={`Actions for ${user.name}`}>
+ *       <MoreHorizontal />
+ *     </button>
+ *   }
+ *   items={[
+ *     { label: 'View Profile', onClick: () => viewProfile(user.id) },
+ *     { label: 'Send Message', onClick: () => sendMessage(user.id) }
+ *   ]}
+ * />
+ *
+ * // Dropdown with keyboard-friendly trigger
+ * <DropdownGlass
+ *   trigger={
+ *     <ButtonGlass
+ *       icon={Settings}
+ *       variant="ghost"
+ *       aria-haspopup="menu"
+ *       aria-label="Settings menu"
+ *     >
+ *       Settings
+ *     </ButtonGlass>
+ *   }
+ *   items={[
+ *     { label: 'Preferences', icon: Sliders, onClick: () => navigate('/settings/preferences') },
+ *     { label: 'Security', icon: Lock, onClick: () => navigate('/settings/security') },
+ *     { divider: true },
+ *     { label: 'Log Out', icon: LogOut, onClick: handleLogout }
+ *   ]}
+ * />
+ *
+ * // Advanced: Using Radix primitives directly (see component JSDoc for examples)
+ * ```
+ */
 declare interface DropdownGlassProps {
     readonly trigger: React_2.ReactNode;
     readonly items: readonly DropdownItem[];
@@ -520,14 +819,56 @@ export declare const GlassCard: ForwardRefExoticComponent<GlassCardProps & RefAt
 /**
  * Props for the GlassCard component
  *
+ * A glass-themed container with configurable blur, glow effects, and hover animations.
+ * Features polymorphic rendering via `asChild` for semantic HTML flexibility.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** When used with `asChild` as a link/button, inherits native keyboard support (Enter/Space activation)
+ * - **Focus Management:** Focus ring applied to child element when using `asChild` pattern with interactive elements
+ * - **Screen Readers:** Semantic HTML preserved via `asChild` - use appropriate elements (`<a>`, `<button>`, `<article>`)
+ * - **Hover State:** Hover effects are purely visual and do not affect functionality (progressive enhancement)
+ * - **Touch Targets:** When interactive, ensure child element meets minimum 44x44px touch target (WCAG 2.5.5)
+ * - **Color Contrast:** Card border and background meet WCAG AA contrast requirements, content contrast is consumer's responsibility
+ * - **Motion:** Hover scale animation respects `prefers-reduced-motion` settings via CSS transitions
+ *
  * @example
  * ```tsx
  * // Basic card
  * <GlassCard intensity="medium">Content</GlassCard>
  *
- * // As a clickable link
+ * // As a clickable link with accessible name
  * <GlassCard asChild intensity="medium">
- *   <a href="/details">View Details</a>
+ *   <a href="/details" aria-label="View product details">
+ *     <h3>Product Title</h3>
+ *     <p>Description</p>
+ *   </a>
+ * </GlassCard>
+ *
+ * // Different intensity levels
+ * <GlassCard intensity="subtle">Subtle blur</GlassCard>
+ * <GlassCard intensity="medium">Standard blur</GlassCard>
+ * <GlassCard intensity="strong">Heavy blur</GlassCard>
+ *
+ * // With glow effects
+ * <GlassCard glow="blue">Blue glow card</GlassCard>
+ * <GlassCard glow="violet">Violet glow card</GlassCard>
+ * <GlassCard glow="cyan">Cyan glow card</GlassCard>
+ *
+ * // As a button (interactive) with role
+ * <GlassCard asChild hover intensity="medium">
+ *   <button onClick={handleClick} aria-label="Open settings">
+ *     <Settings className="w-6 h-6" />
+ *     <span>Settings</span>
+ *   </button>
+ * </GlassCard>
+ *
+ * // Article card with semantic HTML
+ * <GlassCard asChild intensity="medium" padding="lg">
+ *   <article>
+ *     <header><h2>Article Title</h2></header>
+ *     <p>Article content...</p>
+ *     <footer>Published: Jan 1, 2025</footer>
+ *   </article>
  * </GlassCard>
  * ```
  */
@@ -604,18 +945,61 @@ export declare const InputGlass: ForwardRefExoticComponent<InputGlassProps & Ref
  * A glass-themed input field with labels, validation states, and icon support.
  * Features focus glow effects and theme-aware styling.
  *
+ * @accessibility
+ * - **Keyboard Navigation:** Full keyboard support with native `<input>` element, standard tab navigation
+ * - **Focus Management:** Visible focus ring using `--focus-glow` CSS variable (WCAG 2.4.7)
+ * - **Screen Readers:** Semantic `<label>` elements properly associated via `htmlFor`, error/success messages announced with `aria-describedby`
+ * - **Error State:** Red border and error message displayed below input, programmatically associated for screen readers
+ * - **Success State:** Green border and success message displayed below input, programmatically associated for screen readers
+ * - **Touch Targets:** Minimum 44x44px touch target on mobile devices (WCAG 2.5.5)
+ * - **Color Contrast:** All text meets WCAG AA contrast ratio 4.5:1 minimum against backgrounds
+ * - **Motion:** Icon color transitions respect `prefers-reduced-motion` settings
+ *
  * @example
  * ```tsx
  * // Basic input with label
  * <InputGlass label="Email" placeholder="you@example.com" />
  *
- * // With validation states
+ * // With aria-describedby for additional context
+ * <InputGlass
+ *   label="Username"
+ *   placeholder="Enter username"
+ *   aria-describedby="username-help"
+ * />
+ * <span id="username-help">Must be 3-20 characters</span>
+ *
+ * // With validation states (automatically announced to screen readers)
  * <InputGlass label="Username" error="Username is required" />
  * <InputGlass label="Password" success="Strong password" type="password" />
  *
- * // With icon
- * <InputGlass icon={Search} placeholder="Search..." />
- * <InputGlass icon={Mail} iconPosition="right" />
+ * // With icon and accessible label
+ * <InputGlass
+ *   icon={Search}
+ *   placeholder="Search..."
+ *   aria-label="Search products"
+ * />
+ * <InputGlass icon={Mail} iconPosition="right" type="email" />
+ *
+ * // Disabled state (automatically announced)
+ * <InputGlass label="Email" disabled value="locked@example.com" />
+ *
+ * // Form integration with accessible error handling
+ * <form onSubmit={handleSubmit}>
+ *   <InputGlass
+ *     label="Email"
+ *     type="email"
+ *     required
+ *     error={errors.email}
+ *     aria-invalid={!!errors.email}
+ *   />
+ *   <InputGlass
+ *     label="Password"
+ *     type="password"
+ *     icon={Lock}
+ *     error={errors.password}
+ *   />
+ *   <ButtonGlass type="submit">Sign In</ButtonGlass>
+ * </form>
  * ```
  */
 declare interface InputGlassProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>, VariantProps<typeof inputVariants> {
@@ -863,6 +1247,100 @@ declare interface ModalOverlayProps {
     className?: string;
 }
 
+/**
+ * Props for ModalGlass.Root component
+ *
+ * Root component that provides context and manages open/close state for the modal.
+ * Handles keyboard events, body scroll lock, and accessibility attributes.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Escape key closes modal, Tab key traps focus within modal content
+ * - **Focus Management:** Focus automatically moved to modal on open, returned to trigger on close (WCAG 2.4.3)
+ * - **Screen Readers:** Uses `role="dialog"` and `aria-modal="true"` for proper modal semantics (WCAG 4.1.3)
+ * - **Title Association:** Modal title automatically linked via `aria-labelledby="modal-title"`
+ * - **Description Association:** Optional description linked via `aria-describedby="modal-description"`
+ * - **Body Scroll Lock:** Prevents background scrolling when modal is open (improves UX and focus management)
+ * - **Touch Targets:** All interactive elements (close button, action buttons) meet 44x44px minimum (WCAG 2.5.5)
+ * - **Color Contrast:** Modal content and overlay meet WCAG AA contrast requirements
+ * - **Motion:** Open/close animations respect `prefers-reduced-motion` settings
+ *
+ * @example
+ * ```tsx
+ * // Basic modal with title and description
+ * <ModalGlass.Root open={open} onOpenChange={setOpen}>
+ *   <ModalGlass.Overlay />
+ *   <ModalGlass.Content>
+ *     <ModalGlass.Header>
+ *       <ModalGlass.Title>Confirm Action</ModalGlass.Title>
+ *       <ModalGlass.Description>
+ *         This action cannot be undone.
+ *       </ModalGlass.Description>
+ *       <ModalGlass.Close />
+ *     </ModalGlass.Header>
+ *     <ModalGlass.Body>
+ *       <p>Are you sure you want to proceed?</p>
+ *     </ModalGlass.Body>
+ *     <ModalGlass.Footer>
+ *       <ButtonGlass variant="ghost" onClick={() => setOpen(false)}>
+ *         Cancel
+ *       </ButtonGlass>
+ *       <ButtonGlass variant="destructive" onClick={handleConfirm}>
+ *         Confirm
+ *       </ButtonGlass>
+ *     </ModalGlass.Footer>
+ *   </ModalGlass.Content>
+ * </ModalGlass.Root>
+ *
+ * // Different sizes
+ * <ModalGlass.Root open={open} onOpenChange={setOpen} size="sm">
+ *   {// Small modal content}
+ * </ModalGlass.Root>
+ * <ModalGlass.Root open={open} onOpenChange={setOpen} size="lg">
+ *   {// Large modal content}
+ * </ModalGlass.Root>
+ *
+ * // Form modal with proper focus management
+ * <ModalGlass.Root open={open} onOpenChange={setOpen}>
+ *   <ModalGlass.Overlay />
+ *   <ModalGlass.Content>
+ *     <ModalGlass.Header>
+ *       <ModalGlass.Title>Create Account</ModalGlass.Title>
+ *       <ModalGlass.Close />
+ *     </ModalGlass.Header>
+ *     <ModalGlass.Body>
+ *       <form id="signup-form" onSubmit={handleSubmit}>
+ *         <InputGlass label="Email" type="email" required />
+ *         <InputGlass label="Password" type="password" required />
+ *       </form>
+ *     </ModalGlass.Body>
+ *     <ModalGlass.Footer>
+ *       <ButtonGlass variant="ghost" onClick={() => setOpen(false)}>
+ *         Cancel
+ *       </ButtonGlass>
+ *       <ButtonGlass type="submit" form="signup-form">
+ *         Sign Up
+ *       </ButtonGlass>
+ *     </ModalGlass.Footer>
+ *   </ModalGlass.Content>
+ * </ModalGlass.Root>
+ *
+ * // Alert modal (no close button)
+ * <ModalGlass.Root open={showAlert} onOpenChange={setShowAlert}>
+ *   <ModalGlass.Overlay />
+ *   <ModalGlass.Content>
+ *     <ModalGlass.Header>
+ *       <ModalGlass.Title>Session Expired</ModalGlass.Title>
+ *     </ModalGlass.Header>
+ *     <ModalGlass.Body>
+ *       Your session has expired. Please log in again.
+ *     </ModalGlass.Body>
+ *     <ModalGlass.Footer>
+ *       <ButtonGlass onClick={handleLogin}>Log In</ButtonGlass>
+ *     </ModalGlass.Footer>
+ *   </ModalGlass.Content>
+ * </ModalGlass.Root>
+ * ```
+ */
 declare interface ModalRootProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Open state */
     open: boolean;
@@ -1223,6 +1701,89 @@ declare interface TabsListProps extends React.HTMLAttributes<HTMLDivElement> {
     className?: string;
 }
 
+/**
+ * Props for TabsGlass.Root component
+ *
+ * Root component that manages tab state and provides context for child components.
+ * Features accessible keyboard navigation and ARIA attributes.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Arrow keys navigate between tabs, Tab moves to tab panel content (WCAG 2.1.1)
+ * - **Focus Management:** Visible focus ring on active tab using `--focus-glow` CSS variable (WCAG 2.4.7)
+ * - **Screen Readers:** Uses `role="tablist"`, `role="tab"`, `role="tabpanel"` for proper tab semantics (WCAG 4.1.3)
+ * - **ARIA Attributes:** Tabs marked with `aria-selected`, panels with `aria-hidden` for state announcement
+ * - **Active State:** Visual indicator (underline) plus color change for multi-modal feedback
+ * - **Touch Targets:** Tab triggers meet minimum 44x44px touch target (WCAG 2.5.5)
+ * - **Color Contrast:** Active and inactive tab text meet WCAG AA contrast ratio 4.5:1
+ * - **Motion:** Transitions and indicator animations respect `prefers-reduced-motion` settings
+ *
+ * @example
+ * ```tsx
+ * // Basic tabs
+ * <TabsGlass.Root value={activeTab} onValueChange={setActiveTab}>
+ *   <TabsGlass.List>
+ *     <TabsGlass.Trigger value="overview">Overview</TabsGlass.Trigger>
+ *     <TabsGlass.Trigger value="analytics">Analytics</TabsGlass.Trigger>
+ *     <TabsGlass.Trigger value="settings">Settings</TabsGlass.Trigger>
+ *   </TabsGlass.List>
+ *   <TabsGlass.Content value="overview">
+ *     <h2>Overview</h2>
+ *     <p>Overview content here</p>
+ *   </TabsGlass.Content>
+ *   <TabsGlass.Content value="analytics">
+ *     <h2>Analytics</h2>
+ *     <p>Analytics content here</p>
+ *   </TabsGlass.Content>
+ *   <TabsGlass.Content value="settings">
+ *     <h2>Settings</h2>
+ *     <p>Settings content here</p>
+ *   </TabsGlass.Content>
+ * </TabsGlass.Root>
+ *
+ * // Tabs with icons (ensure accessible labels)
+ * <TabsGlass.Root value={activeTab} onValueChange={setActiveTab}>
+ *   <TabsGlass.List>
+ *     <TabsGlass.Trigger value="home" aria-label="Home dashboard">
+ *       <Home className="w-4 h-4" />
+ *     </TabsGlass.Trigger>
+ *     <TabsGlass.Trigger value="search" aria-label="Search">
+ *       <Search className="w-4 h-4" />
+ *     </TabsGlass.Trigger>
+ *   </TabsGlass.List>
+ *   <TabsGlass.Content value="home">Dashboard content</TabsGlass.Content>
+ *   <TabsGlass.Content value="search">Search content</TabsGlass.Content>
+ * </TabsGlass.Root>
+ *
+ * // Disabled tab (announced to screen readers)
+ * <TabsGlass.Root value={activeTab} onValueChange={setActiveTab}>
+ *   <TabsGlass.List>
+ *     <TabsGlass.Trigger value="tab1">Available Tab</TabsGlass.Trigger>
+ *     <TabsGlass.Trigger value="tab2" disabled>
+ *       Locked Tab
+ *     </TabsGlass.Trigger>
+ *   </TabsGlass.List>
+ *   <TabsGlass.Content value="tab1">Content 1</TabsGlass.Content>
+ * </TabsGlass.Root>
+ *
+ * // Form tabs with proper focus management
+ * <TabsGlass.Root value={currentStep} onValueChange={setCurrentStep}>
+ *   <TabsGlass.List aria-label="Registration steps">
+ *     <TabsGlass.Trigger value="account">Account Info</TabsGlass.Trigger>
+ *     <TabsGlass.Trigger value="profile">Profile Details</TabsGlass.Trigger>
+ *     <TabsGlass.Trigger value="confirm">Confirmation</TabsGlass.Trigger>
+ *   </TabsGlass.List>
+ *   <TabsGlass.Content value="account">
+ *     <InputGlass label="Email" type="email" />
+ *   </TabsGlass.Content>
+ *   <TabsGlass.Content value="profile">
+ *     <InputGlass label="Name" />
+ *   </TabsGlass.Content>
+ *   <TabsGlass.Content value="confirm">
+ *     <p>Review your information</p>
+ *   </TabsGlass.Content>
+ * </TabsGlass.Root>
+ * ```
+ */
 declare interface TabsRootProps {
     /** Current active tab value */
     value: string;
@@ -1270,6 +1831,75 @@ declare const toggleSizes: (props?: ({
 
 export declare const TooltipGlass: ForwardRefExoticComponent<TooltipGlassProps & RefAttributes<HTMLDivElement>>;
 
+/**
+ * Props for the TooltipGlass component
+ *
+ * A glass-themed tooltip with configurable positioning and unified dark design.
+ * Features smooth animations and WCAG-compliant accessibility attributes.
+ *
+ * @accessibility
+ * - **Keyboard Navigation:** Tooltip appears on focus for keyboard users (same as hover)
+ * - **Focus Management:** Tooltip does not trap focus, allows normal navigation flow
+ * - **Screen Readers:** Uses `aria-describedby` to associate tooltip with trigger element (WCAG 4.1.3)
+ * - **ARIA Attributes:** Tooltip marked with `role="tooltip"` and unique ID for proper association
+ * - **Dismissible:** Tooltip dismisses on mouse leave, focus blur, or Escape key
+ * - **Touch Targets:** N/A - tooltips appear on hover/focus, do not require direct interaction
+ * - **Color Contrast:** Tooltip text meets WCAG AA contrast ratio 4.5:1 against dark background
+ * - **Motion:** Fade-in animation respects `prefers-reduced-motion` settings
+ *
+ * @example
+ * ```tsx
+ * // Basic tooltip
+ * <TooltipGlass content="Click to edit">
+ *   <button><Edit className="w-4 h-4" /></button>
+ * </TooltipGlass>
+ *
+ * // Different positions
+ * <TooltipGlass content="Top tooltip" position="top">
+ *   <ButtonGlass>Hover me</ButtonGlass>
+ * </TooltipGlass>
+ * <TooltipGlass content="Bottom tooltip" position="bottom">
+ *   <ButtonGlass>Hover me</ButtonGlass>
+ * </TooltipGlass>
+ * <TooltipGlass content="Left tooltip" position="left">
+ *   <ButtonGlass>Hover me</ButtonGlass>
+ * </TooltipGlass>
+ * <TooltipGlass content="Right tooltip" position="right">
+ *   <ButtonGlass>Hover me</ButtonGlass>
+ * </TooltipGlass>
+ *
+ * // Icon button with accessible tooltip (provides label)
+ * <TooltipGlass content="Delete item">
+ *   <ButtonGlass
+ *     icon={Trash}
+ *     size="icon"
+ *     variant="ghost"
+ *     aria-label="Delete item"
+ *   />
+ * </TooltipGlass>
+ *
+ * // Informational tooltip on text
+ * <TooltipGlass content="This feature requires a Pro subscription">
+ *   <span className="underline decoration-dotted">Pro Feature</span>
+ * </TooltipGlass>
+ *
+ * // Badge with tooltip for additional context
+ * <TooltipGlass content="Last updated 2 hours ago" position="top">
+ *   <BadgeGlass variant="success" dot>
+ *     Active
+ *   </BadgeGlass>
+ * </TooltipGlass>
+ *
+ * // Disabled button with explanation tooltip
+ * <TooltipGlass content="Save your changes first to enable this action">
+ *   <span>
+ *     <ButtonGlass disabled aria-describedby="tooltip-id">
+ *       Export
+ *     </ButtonGlass>
+ *   </span>
+ * </TooltipGlass>
+ * ```
+ */
 declare interface TooltipGlassProps extends VariantProps<typeof tooltipPositions> {
     readonly children: ReactNode;
     readonly content: string;