@boostdev/design-system-components 1.0.3 → 1.1.0

package/src/components/interaction/Popover/Popover.spec.tsx

@@ -2,6 +2,15 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Popover } from './Popover';
 
+// jsdom doesn't implement CSS.supports — provide a minimal stub so the
+// polyfill guard in Popover.tsx doesn't throw.
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'CSS', {
+    value: { supports: () => true },
+    configurable: true,
+  });
+});
+
 describe('Popover', () => {
   it('renders the trigger', () => {
     render(
@@ -18,7 +27,9 @@ describe('Popover', () => {
         <button type="button">Open</button>
       </Popover>
     );
-    expect(screen.queryByText('Panel content')).not.toBeInTheDocument();
+    // The dialog element is always in DOM; closed state = no open attribute.
+    const dialog = document.querySelector('dialog');
+    expect(dialog).not.toHaveAttribute('open');
   });
 
   it('shows the panel when trigger is clicked', async () => {
@@ -29,7 +40,7 @@ describe('Popover', () => {
       </Popover>
     );
     await user.click(screen.getByRole('button', { name: 'Open' }));
-    expect(screen.getByText('Panel content')).toBeInTheDocument();
+    expect(document.querySelector('dialog')).toHaveAttribute('open');
   });
 
   it('closes the panel when trigger is clicked again', async () => {
@@ -41,7 +52,7 @@ describe('Popover', () => {
     );
     await user.click(screen.getByRole('button', { name: 'Toggle' }));
     await user.click(screen.getByRole('button', { name: 'Toggle' }));
-    expect(screen.queryByText('Panel content')).not.toBeInTheDocument();
+    expect(document.querySelector('dialog')).not.toHaveAttribute('open');
   });
 
   it('closes the panel when Escape is pressed', async () => {
@@ -53,7 +64,7 @@ describe('Popover', () => {
     );
     await user.click(screen.getByRole('button', { name: 'Open' }));
     await user.keyboard('{Escape}');
-    expect(screen.queryByText('Panel content')).not.toBeInTheDocument();
+    expect(document.querySelector('dialog')).not.toHaveAttribute('open');
   });
 
   it('sets aria-expanded on the trigger when open', async () => {
@@ -69,6 +80,21 @@ describe('Popover', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
   });
 
+  it('sets anchor-name on the trigger and position-anchor on the panel', () => {
+    render(
+      <Popover content={<p>Panel</p>}>
+        <button type="button">Open</button>
+      </Popover>
+    );
+    const trigger = screen.getByRole('button');
+    const dialog = document.querySelector('dialog')!;
+    // Both should reference the same CSS anchor ident.
+    const anchorName = trigger.style.getPropertyValue('anchor-name');
+    const positionAnchor = dialog.style.getPropertyValue('position-anchor');
+    expect(anchorName).toMatch(/^--popover-/);
+    expect(positionAnchor).toBe(anchorName);
+  });
+
   it('renders role="region" with aria-label when aria-label prop is provided', async () => {
     const user = userEvent.setup();
     render(
@@ -90,4 +116,42 @@ describe('Popover', () => {
     await user.click(screen.getByRole('button', { name: 'Open' }));
     expect(screen.queryByRole('region')).not.toBeInTheDocument();
   });
+
+  it('constrains maxHeight when trigger is near the bottom of the viewport', async () => {
+    const user = userEvent.setup();
+    Object.defineProperty(window, 'innerHeight', { value: 600, configurable: true });
+    Object.defineProperty(window, 'innerWidth', { value: 1024, configurable: true });
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
+      top: 530, bottom: 550, left: 100, right: 200, width: 100, height: 20,
+      x: 100, y: 530, toJSON: () => {},
+    });
+    render(
+      <Popover content={<p>Panel</p>} placement="bottom">
+        <button type="button">Open</button>
+      </Popover>
+    );
+    await user.click(screen.getByRole('button', { name: 'Open' }));
+    const dialog = document.querySelector('dialog')!;
+    // max-height = vh - rect.bottom - GAP * 2 = 600 - 550 - 16 = 34
+    expect(dialog.style.maxHeight).toBe('34px');
+  });
+
+  it('constrains maxWidth when trigger is near the right edge of the viewport', async () => {
+    const user = userEvent.setup();
+    Object.defineProperty(window, 'innerHeight', { value: 600, configurable: true });
+    Object.defineProperty(window, 'innerWidth', { value: 400, configurable: true });
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockReturnValue({
+      top: 100, bottom: 120, left: 350, right: 390, width: 40, height: 20,
+      x: 350, y: 100, toJSON: () => {},
+    });
+    render(
+      <Popover content={<p>Panel</p>} placement="bottom">
+        <button type="button">Open</button>
+      </Popover>
+    );
+    await user.click(screen.getByRole('button', { name: 'Open' }));
+    const dialog = document.querySelector('dialog')!;
+    // max-width = vw - rect.left - GAP = 400 - 350 - 8 = 42
+    expect(dialog.style.maxWidth).toBe('42px');
+  });
 });

package/src/components/interaction/Popover/Popover.stories.tsx

@@ -3,7 +3,7 @@ import { Popover } from './Popover';
 import { Button } from '../Button/Button';
 
 const meta = {
-  title: 'Interaction/Popover',
+  title: 'React/Interaction/Popover',
   component: Popover,
   argTypes: {
     placement: { control: 'radio', options: ['top', 'bottom', 'left', 'right'] },

package/src/components/interaction/Popover/Popover.tsx

@@ -3,6 +3,7 @@ import {
   ReactNode,
   cloneElement,
   isValidElement,
+  useCallback,
   useEffect,
   useId,
   useRef,
@@ -10,12 +11,23 @@ import {
 } from 'react';
 import css from './Popover.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
-interface PopoverProps {
+const GAP = 8; // --bds-space_xs
+
+// Load the CSS Anchor Positioning polyfill once, only in browsers that need it.
+// The CSS.supports guard is defensive: older environments may not expose it at all.
+if (
+  typeof window !== 'undefined' &&
+  !(typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('anchor-name: --a'))
+) {
+  import('@oddbird/css-anchor-positioning').catch(() => {});
+}
+
+interface PopoverProps extends WithClassName {
   children: ReactElement;
   content: ReactNode;
   placement?: 'top' | 'bottom' | 'left' | 'right';
-  className?: string;
   'aria-label'?: string;
 }
 
@@ -28,35 +40,77 @@ export function Popover({
 }: Readonly<PopoverProps>) {
   const [isOpen, setIsOpen] = useState(false);
   const containerRef = useRef<HTMLSpanElement>(null);
-  const panelId = useId();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const rawId = useId();
+  // CSS anchor-name must be a valid custom-ident: strip non-word characters.
+  const anchorName = `--popover-${rawId.replace(/\W/g, '') || 'a'}`;
+  const panelId = rawId;
 
+  // Light-dismiss: close on outside click or Escape key.
   useEffect(() => {
     if (!isOpen) return;
-
-    const handlePointerDown = (e: PointerEvent) => {
-      if (!containerRef.current?.contains(e.target as Node)) {
+    const handleMouseDown = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
         setIsOpen(false);
       }
     };
     const handleKeyDown = (e: KeyboardEvent) => {
       if (e.key === 'Escape') setIsOpen(false);
     };
-
-    document.addEventListener('pointerdown', handlePointerDown);
+    document.addEventListener('mousedown', handleMouseDown);
     document.addEventListener('keydown', handleKeyDown);
     return () => {
-      document.removeEventListener('pointerdown', handlePointerDown);
+      document.removeEventListener('mousedown', handleMouseDown);
       document.removeEventListener('keydown', handleKeyDown);
     };
   }, [isOpen]);
 
+  // CSS anchor positioning handles placement. JS only constrains max-height/max-width
+  // so tall content scrolls rather than overflows the viewport.
+  const constrainPanel = useCallback(() => {
+    const dialog = dialogRef.current;
+    const container = containerRef.current;
+    if (!dialog || !container) return;
+    const rect = container.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    dialog.style.maxHeight = '';
+    dialog.style.maxWidth = '';
+    if (placement === 'bottom') {
+      dialog.style.maxHeight = `${Math.max(0, vh - rect.bottom - GAP * 2)}px`;
+      dialog.style.maxWidth = `${Math.max(0, vw - rect.left - GAP)}px`;
+    } else if (placement === 'top') {
+      dialog.style.maxHeight = `${Math.max(0, rect.top - GAP * 2)}px`;
+      dialog.style.maxWidth = `${Math.max(0, vw - rect.left - GAP)}px`;
+    } else if (placement === 'right') {
+      dialog.style.maxHeight = `${Math.max(0, vh - rect.top - GAP)}px`;
+      dialog.style.maxWidth = `${Math.max(0, vw - rect.right - GAP * 2)}px`;
+    } else {
+      dialog.style.maxHeight = `${Math.max(0, vh - rect.top - GAP)}px`;
+      dialog.style.maxWidth = `${Math.max(0, rect.left - GAP * 2)}px`;
+    }
+  }, [placement]);
+
+  const toggle = useCallback(() => {
+    if (isOpen) {
+      setIsOpen(false);
+    } else {
+      constrainPanel();
+      setIsOpen(true);
+    }
+  }, [isOpen, constrainPanel]);
+
   const trigger = isValidElement(children)
     ? cloneElement(children as ReactElement<Record<string, unknown>>, {
         'aria-expanded': isOpen,
         'aria-controls': panelId,
         'aria-haspopup': true,
+        style: {
+          ...((children.props as Record<string, unknown>).style as object | undefined),
+          anchorName,
+        },
         onClick: (e: MouseEvent) => {
-          setIsOpen(prev => !prev);
+          toggle();
           const existingOnClick = (children.props as Record<string, unknown>).onClick;
           if (typeof existingOnClick === 'function') existingOnClick(e);
         },
@@ -66,16 +120,18 @@ export function Popover({
   return (
     <span ref={containerRef} className={cn(css.wrapper, className)}>
       {trigger}
-      {isOpen && (
-        <div
-          id={panelId}
-          role={ariaLabel ? 'region' : undefined}
-          aria-label={ariaLabel}
-          className={cn(css.panel, css[`--placement_${placement}`])}
-        >
-          {content}
-        </div>
-      )}
+      <dialog
+        ref={dialogRef}
+        id={panelId}
+        open={isOpen}
+        data-placement={placement}
+        role={ariaLabel ? 'region' : undefined}
+        aria-label={ariaLabel}
+        className={css.panel}
+        style={{ positionAnchor: anchorName }}
+      >
+        {content}
+      </dialog>
     </span>
   );
 }

package/src/components/interaction/Rating/Rating.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { Rating } from './Rating';
 
 const meta = {
-  title: 'Interaction/Rating',
+  title: 'React/Interaction/Rating',
   component: Rating,
   argTypes: {
     value: { control: { type: 'range', min: 0, max: 5, step: 1 } },

package/src/components/interaction/Rating/Rating.tsx

@@ -1,10 +1,10 @@
 import css from './Rating.module.css';
 import { cn } from '@boostdev/design-system-foundation';
+import type { WithClassName } from '../../../types';
 
-interface RatingProps {
+interface RatingProps extends WithClassName {
   value: number;
   max?: number;
-  className?: string;
 }
 
 export function Rating({ value, max = 5, className }: RatingProps) {

package/src/components/interaction/Toast/Toast.module.css

@@ -1,12 +1,17 @@
 @layer component {
   .toastContainer {
     position: fixed;
+    inset: unset; /* override UA popover default (inset: 0) */
     bottom: var(--bds-space_xl);
     right: var(--bds-space_xl);
     display: flex;
     flex-direction: column;
     gap: var(--bds-space_m);
-    z-index: var(--bds-z-index_toast);
+
+    /* z-index removed — top layer renders above all fixed/sticky elements */
+    border: none; /* override UA popover default */
+    padding: 0; /* override UA popover default */
+    background: transparent; /* override UA popover default */
   }
 
   .toast {

package/src/components/interaction/Toast/Toast.spec.tsx

@@ -32,6 +32,27 @@ describe('Toast', () => {
     vi.useRealTimers();
   });
 
+  it('renders the toast container as a manual popover', () => {
+    render(
+      <ToastProvider>
+        <div />
+      </ToastProvider>
+    );
+    const container = document.querySelector('[popover]');
+    expect(container).toHaveAttribute('popover', 'manual');
+  });
+
+  it('renders the toast container as a labelled notifications region', () => {
+    render(
+      <ToastProvider>
+        <div />
+      </ToastProvider>
+    );
+    const container = document.querySelector('[popover="manual"]');
+    expect(container).toHaveAttribute('role', 'region');
+    expect(container).toHaveAttribute('aria-label', 'Notifications');
+  });
+
   it('throws when useToast is used outside ToastProvider', () => {
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
     const Bad = () => { useToast(); return null; };

package/src/components/interaction/Toast/Toast.stories.tsx

@@ -3,7 +3,7 @@ import { ToastProvider, useToast } from './Toast';
 import { Button } from '../Button/Button';
 
 const meta = {
-  title: 'Interaction/Toast',
+  title: 'React/Interaction/Toast',
   component: ToastProvider,
 } satisfies Meta<typeof ToastProvider>;
 

package/src/components/interaction/Toast/Toast.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, createContext, useContext, ReactNode, useCallback, useMemo } from 'react';
+import { useState, useEffect, createContext, useContext, ReactNode, useCallback, useMemo, useRef } from 'react';
 import css from './Toast.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 
@@ -18,6 +18,7 @@ const ToastContext = createContext<ToastContextType | undefined>(undefined);
 
 export function ToastProvider({ children }: { children: ReactNode }) {
   const [toasts, setToasts] = useState<Toast[]>([]);
+  const containerRef = useRef<HTMLDivElement>(null);
 
   const showToast = useCallback((message: string, variant: ToastVariant) => {
     const id = Math.random().toString(36).substring(2, 9);
@@ -28,12 +29,31 @@ export function ToastProvider({ children }: { children: ReactNode }) {
     setToasts(prev => prev.filter(toast => toast.id !== id));
   }, []);
 
+  // Sync the popover's top-layer visibility with the toast queue.
+  // showPopover() is a no-op when already open (safe to call multiple times).
+  // hidePopover() throws InvalidStateError when already hidden, so catch silently.
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    if (toasts.length > 0) {
+      container.showPopover?.();
+    } else {
+      try { container.hidePopover?.(); } catch { /* already hidden on initial mount */ }
+    }
+  }, [toasts.length]);
+
   const value = useMemo(() => ({ showToast }), [showToast]);
 
   return (
     <ToastContext.Provider value={value}>
       {children}
-      <div className={css.toastContainer}>
+      <div
+        ref={containerRef}
+        popover="manual"
+        role="region"
+        aria-label="Notifications"
+        className={css.toastContainer}
+      >
         {toasts.map(toast => (
           <ToastItem
             key={toast.id}

package/src/components/interaction/form/Checkbox/Checkbox.mdx

@@ -44,8 +44,8 @@ Binary toggle for opt-in/opt-out choices. Renders a styled native `<input type="
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--checkbox_color-active`</td><td>`var(--bds-active)`</td><td>Checked background</td></tr>
-<tr><td>`--checkbox_color-on-active`</td><td>`var(--bds-on-active)`</td><td>Checkmark colour</td></tr>
+<tr><td>`--checkbox_color-active`</td><td>`var(--bdc-color_active)`</td><td>Checked background</td></tr>
+<tr><td>`--checkbox_color-on-active`</td><td>`var(--bdc-color_on-active)`</td><td>Checkmark colour</td></tr>
 </tbody>
 </table>
 

package/src/components/interaction/form/Checkbox/Checkbox.module.css

@@ -33,8 +33,8 @@
   }
 
   .checkbox:checked {
-    background-color: var(--checkbox_color-active, var(--bds-color_green));
-    --bdc_color: var(--checkbox_color-active, var(--bds-color_green));
+    background-color: var(--checkbox_color-active, var(--bdc-color_active));
+    --bdc_color: var(--checkbox_color-active, var(--bdc-color_active));
   }
 
   .checkbox:checked::after {
@@ -44,7 +44,7 @@
     top: 0.2em;
     width: 0.5em;
     height: 1em;
-    border: solid var(--checkbox_color-on-active, var(--bds-color_on-green));
+    border: solid var(--checkbox_color-on-active, var(--bdc-color_on-active));
     border-width: 0 2px 2px 0;
     transform: rotate(45deg);
   }

package/src/components/interaction/form/Checkbox/Checkbox.native.spec.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '../../../../native/ThemeContext';
+import { Checkbox } from './Checkbox.native';
+
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider>{ui}</ThemeProvider>);
+}
+
+describe('Checkbox (native)', () => {
+  it('has checkbox role with label', () => {
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" />);
+    expect(screen.getByRole('checkbox', { name: 'Accept terms' })).toBeInTheDocument();
+  });
+
+  it('shows the checkmark when checked', () => {
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" checked={true} />);
+    expect(screen.getByText('✓')).toBeInTheDocument();
+  });
+
+  it('hides the checkmark when unchecked', () => {
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" checked={false} />);
+    expect(screen.queryByText('✓')).not.toBeInTheDocument();
+  });
+
+  it('checkmark uses theme color (contrast regression: was hardcoded #fff)', () => {
+    // Previously the checkmark had color: '#fff' hardcoded in the StyleSheet.
+    // Now it uses colors.colorOnInteractive from the theme, which is #000 in dark
+    // mode — fixing the 2.52:1 contrast failure on the dark interactive blue.
+    renderWithTheme(<Checkbox label="Accept terms" name="terms" checked={true} />);
+    const checkmark = screen.getByText('✓');
+    // The color must be applied as an inline style (overrides StyleSheet), not absent.
+    // In light mode colorOnInteractive=#fff; in dark mode it is #000.
+    expect(checkmark.style.color).toBeTruthy();
+  });
+
+  it('renders with error message', () => {
+    renderWithTheme(
+      <Checkbox label="Accept terms" name="terms" error="You must accept." />,
+    );
+    expect(screen.getByRole('alert')).toHaveTextContent('You must accept.');
+  });
+});

package/src/components/interaction/form/Checkbox/Checkbox.native.stories.tsx

@@ -0,0 +1,36 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider } from '../../../../native/ThemeContext';
+import { Checkbox } from './Checkbox.native';
+
+const meta = {
+  tags: ['!stable', 'alpha'],
+  title: 'React Native/Form/Checkbox',
+  component: Checkbox,
+  decorators: [(Story) => <ThemeProvider><Story /></ThemeProvider>],
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unchecked: Story = { args: { label: 'Accept terms', name: 'terms', checked: false } };
+export const Checked: Story = { args: { label: 'Accept terms', name: 'terms', checked: true } };
+export const Disabled: Story = { args: { label: 'Accept terms', name: 'terms', disabled: true } };
+export const DisabledChecked: Story = { args: { label: 'Accept terms', name: 'terms', checked: true, disabled: true } };
+export const WithError: Story = {
+  args: { label: 'Accept terms', name: 'terms', error: 'You must accept the terms.' },
+};
+export const WithHint: Story = {
+  args: { label: 'Subscribe to newsletter', name: 'newsletter', hint: 'Max one email per week.' },
+};
+export const Interactive: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    return (
+      <ThemeProvider>
+        <Checkbox label="Accept terms and conditions" name="terms" checked={checked} onChange={setChecked} />
+      </ThemeProvider>
+    );
+  },
+};

package/src/components/interaction/form/Checkbox/Checkbox.native.tsx

@@ -0,0 +1,80 @@
+import { ReactNode } from 'react';
+import { StyleSheet, View, Pressable, StyleProp, ViewStyle } from 'react-native';
+import { spacing, border } from '../../../../native/tokens';
+import { useTheme } from '../../../../native/ThemeContext';
+import { Label } from '../atoms/Label.native';
+import { Message } from '../atoms/Message.native';
+
+interface CheckboxProps {
+  label: ReactNode;
+  name: string;
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  error?: string;
+  hint?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+const BOX = 22;
+
+const styles = StyleSheet.create({
+  container: {
+    gap: spacing.xxs,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.xs,
+    minHeight: 44,
+  },
+  box: {
+    width: BOX,
+    height: BOX,
+    borderRadius: border.radius.xs,
+    borderWidth: 2,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  checkmark: {
+    fontSize: 14,
+    fontWeight: '700',
+    lineHeight: 16,
+  },
+});
+
+export function Checkbox({
+  label,
+  name,
+  checked = false,
+  onChange,
+  disabled = false,
+  error,
+  hint,
+  style,
+}: CheckboxProps) {
+  const { colors } = useTheme();
+
+  const borderColor = error ? colors.colorError : checked ? colors.colorInteractive : colors.colorBgSubtle;
+  const bgColor = checked ? colors.colorInteractive : 'transparent';
+
+  return (
+    <View style={[styles.container, style]}>
+      <Pressable
+        onPress={() => !disabled && onChange?.(!checked)}
+        accessibilityRole="checkbox"
+        accessibilityLabel={typeof label === 'string' ? label : name}
+        accessibilityState={{ checked, disabled }}
+        disabled={disabled}
+        style={({ pressed }) => [styles.row, pressed && { opacity: 0.7 }, disabled && { opacity: 0.4 }]}
+      >
+        <View style={[styles.box, { borderColor, backgroundColor: bgColor }]}>
+          {checked && <Label label="✓" style={[styles.checkmark, { color: colors.colorOnInteractive }]} />}
+        </View>
+        <Label label={label} />
+      </Pressable>
+      <Message type="error" message={error} />
+      <Message type="hint" message={hint} />
+    </View>
+  );
+}

package/src/components/interaction/form/Checkbox/Checkbox.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { Checkbox } from './Checkbox';
 
 const meta = {
-  title: 'Form/Checkbox',
+  title: 'React/Form/Checkbox',
   component: Checkbox,
 } satisfies Meta<typeof Checkbox>;
 

package/src/components/interaction/form/Checkbox/Checkbox.tsx

@@ -4,13 +4,13 @@ import { Message } from '../atoms/Message';
 import { Label } from '../atoms/Label';
 import { cn } from '@boostdev/design-system-foundation';
 import { InputContainer } from '../atoms/InputContainer';
+import type { WithClassName } from '../../../../types';
 
-interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+interface CheckboxProps extends WithClassName, Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
   label: ReactNode;
   name: string;
   error?: string;
   hint?: string;
-  className?: string;
 }
 
 export function Checkbox({ label, name, error, hint, className, ...props }: CheckboxProps) {

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.mdx

@@ -0,0 +1,44 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './CheckboxGroup.stories';
+
+<Meta of={Stories} />
+
+# CheckboxGroup
+
+Groups multiple `Checkbox` inputs under a shared label. Renders a `<fieldset>` with a `<legend>` for accessible grouping.
+
+## When to use
+- Multi-select option sets where several choices can be active simultaneously
+- Any time two or more checkboxes share a common label or question
+
+## When not to use
+- A single independent toggle — use `Checkbox` on its own
+- Mutually exclusive choices — use `RadioGroup`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### Required
+<Canvas of={Stories.Required} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Wraps checkboxes in a `<fieldset>` with a `<legend>` — screen readers announce the group label before each option
+- `disabled` on the group sets the HTML `disabled` attribute on the `<fieldset>`, which disables all child inputs
+- `aria-required` is set on the `<fieldset>` when `required` is true
+- Error and hint messages are linked via `aria-describedby`