@sovereignfs/ui 0.21.3 → 0.33.0

package/src/components/DragHandleRow/DragHandleRow.tsx

@@ -0,0 +1,61 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import styles from './DragHandleRow.module.css';
+
+export interface DragHandleRowProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  /** Pass drag-listener and drag-control props from dnd-kit here. */
+  handleProps?: HTMLAttributes<HTMLButtonElement>;
+  isDragging?: boolean;
+}
+
+/**
+ * A row wrapper that surfaces a drag handle on the left.
+ * Consumers attach dnd-kit's useSortable listeners to `handleProps`.
+ */
+export function DragHandleRow({
+  children,
+  handleProps,
+  isDragging,
+  className,
+  ...rest
+}: DragHandleRowProps) {
+  return (
+    <div
+      {...rest}
+      className={[styles.row, isDragging ? styles.dragging : '', className]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <button
+        type="button"
+        aria-label="Drag to reorder"
+        className={styles.handle}
+        tabIndex={-1}
+        {...handleProps}
+      >
+        <DragIcon />
+      </button>
+      <div className={styles.content}>{children}</div>
+    </div>
+  );
+}
+
+function DragIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 14 14"
+      fill="none"
+      aria-hidden="true"
+      className={styles.icon}
+    >
+      {/* Two columns of three dots */}
+      {[3, 7, 11].map((cy) =>
+        [4, 10].map((cx) => (
+          <circle key={`${cx}-${cy}`} cx={cx} cy={cy} r={1.2} fill="currentColor" />
+        )),
+      )}
+    </svg>
+  );
+}

package/src/components/Drawer/Drawer.module.css

@@ -14,6 +14,14 @@
   display: flex;
   align-items: flex-end;
   background: var(--sv-color-scrim);
+  /* Entrance/exit fade — same two-phase-mount pattern as Dialog (see motion.ts
+     and Drawer.tsx). */
+  opacity: 0;
+  transition: opacity var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.scrimOpen {
+  opacity: 1;
 }
 
 .panel {
@@ -28,4 +36,57 @@
   /* Pull content above the home indicator / bottom bar in standalone mode. */
   padding-bottom: env(safe-area-inset-bottom);
   outline: none;
+  /* Slide up from below the viewport. Always a bottom sheet, so unlike Dialog
+     there's no desktop-vs-mobile fork here. */
+  transform: translateY(100%);
+  transition: transform var(--sv-motion-duration-base) var(--sv-motion-ease-out);
+}
+
+.panelOpen {
+  transform: translateY(0);
+}
+
+/* 'half' snapHeight — a fixed height instead of the default content-sized cap
+ * above. Per the design-system's "half screen or less" convention for
+ * Drawer; content taller than this belongs in Sheet instead. */
+.panelHalf {
+  height: 50dvh;
+  max-height: 50dvh;
+}
+
+/* See Dialog.module.css's identical rule for why 0.01ms rather than 0. */
+@media (prefers-reduced-motion: reduce) {
+  .scrim,
+  .panel {
+    transition-duration: 0.01ms;
+  }
+}
+
+/* Grab handle — the sole drag-initiation region for swipe-down-to-dismiss
+ * (see Drawer.tsx's doc comment for why not the whole panel). The visual bar
+ * (::before) stays the small, established 36x4px size; only the hit area
+ * grows to a comfortable touch target. */
+.handle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: var(--sv-touch-target-min, 44px);
+  flex-shrink: 0;
+  cursor: grab;
+  /* JS-driven drag — the browser must not treat a press here as a
+     scroll/pan gesture that would fight it. */
+  touch-action: none;
+}
+
+.handle:active {
+  cursor: grabbing;
+}
+
+.handle::before {
+  content: '';
+  width: 36px;
+  height: 4px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-border-strong);
 }

package/src/components/Drawer/Drawer.tsx

@@ -1,41 +1,84 @@
 'use client';
 
-import { type ReactNode, useEffect, useRef } from 'react';
+import { type PointerEvent as ReactPointerEvent, type ReactNode, useEffect, useRef } from 'react';
 import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { useMountTransition, usePrefersReducedMotion } from '../../motion';
 import styles from './Drawer.module.css';
 
+// Matches --sv-motion-duration-base (Drawer.module.css) — see Dialog.tsx's
+// identical constant for why this stays a plain JS number instead of being
+// read from the CSS custom property.
+const MOTION_DURATION_MS = 250;
+
 export interface DrawerProps {
   /** Whether the drawer is shown. When false, nothing renders. */
   open: boolean;
-  /** Called on Esc or scrim click. */
+  /** Called on Esc, scrim click, or a swipe-down past the dismiss threshold. */
   onClose: () => void;
   /** Accessible name for the drawer panel (sets `aria-label`). */
   'aria-label'?: string;
+  /** `'content'` (default) sizes to content, capped at 80dvh. `'half'` fixes
+   *  the panel to 50dvh regardless of content — per the design-system's
+   *  "half screen or less" convention for Drawer, this is the only other
+   *  supported size; taller content should use `Sheet` instead. */
+  snapHeight?: 'content' | 'half';
   children: ReactNode;
 }
 
 const FOCUSABLE =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
+// Downward drag distance (px) past which releasing dismisses the drawer
+// instead of snapping back open. Distance-only, no velocity tracking — matches
+// the swipe-to-reveal gesture already established in consuming plugins (see
+// the mobile design-system plan), not a separate technique invented here.
+const SWIPE_DISMISS_THRESHOLD_PX = 100;
+
 /**
  * Drawer — a dismissable bottom-sheet panel. Used by the mobile shell for
  * plugin navigation; also available to plugins for any bottom-up surface.
  *
- * Behaviour: Esc and scrim-click dismiss; focus moves to the first focusable
- * element on open and is restored on close; Tab is trapped within the panel.
- * The panel respects `env(safe-area-inset-bottom)` so it clears the home
- * indicator in standalone/fullscreen mode. Shares dismissal conventions and
- * tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with `Dialog`.
+ * Behaviour: Esc, scrim click, or dragging the grab handle down past
+ * `SWIPE_DISMISS_THRESHOLD_PX` all dismiss; focus moves to the first
+ * focusable element on open and is restored on close; Tab is trapped within
+ * the panel. The panel respects `env(safe-area-inset-bottom)` so it clears
+ * the home indicator in standalone/fullscreen mode. Shares dismissal
+ * conventions and tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with
+ * `Dialog`.
+ *
+ * Animated open/close: slides up from the bottom, scrim fades. The `open`/
+ * `onClose` API is unchanged — closing stays mounted internally for the exit
+ * transition before actually unmounting; `prefers-reduced-motion: reduce`
+ * collapses it to near-instant.
+ *
+ * The grab handle is the *only* drag-initiation region (not the whole panel)
+ * — dragging from body content would fight that content's own internal
+ * scroll, the same reasoning behind the tasks plugin's edge-zone-only
+ * swipe-to-reveal technique.
  */
-export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: DrawerProps) {
+export function Drawer({
+  open,
+  onClose,
+  'aria-label': ariaLabel,
+  snapHeight = 'content',
+  children,
+}: DrawerProps) {
   const panelRef = useRef<HTMLDivElement>(null);
   const previouslyFocused = useRef<HTMLElement | null>(null);
+  const reducedMotion = usePrefersReducedMotion();
+  const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
+  // Tracks an in-progress handle drag. Kept in a ref (not state) so pointermove
+  // updates the DOM directly at 60fps instead of re-rendering on every event —
+  // same technique as the tasks plugin's swipe-to-reveal rows.
+  const dragStartY = useRef<number | null>(null);
 
+  // Locked for the whole mounted lifetime (including the exit animation), not
+  // just while `open` — see Dialog.tsx's identical comment for why.
   useEffect(() => {
-    if (!open) return;
+    if (!mounted) return;
     lockBodyScroll();
     return unlockBodyScroll;
-  }, [open]);
+  }, [mounted]);
 
   useEffect(() => {
     if (!open) return;
@@ -80,13 +123,56 @@ export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: Dra
     return () => document.removeEventListener('keydown', handleKeyDown);
   }, [open, onClose]);
 
-  if (!open) return null;
+  // Swipe-down-to-dismiss, initiated only from the grab handle (see the
+  // component doc comment for why not the whole panel). Drags the panel
+  // directly via inline style while active (transition: none, so it tracks
+  // the finger 1:1 with no lag) and lets go on release: clearing the inline
+  // transform in the same commit that re-enables the CSS transition makes
+  // the panel animate from wherever the drag ended to its resolved position
+  // — open (snap back) or closed (the exit transition, same as a
+  // programmatic close) — rather than jump-cutting there. Same technique as
+  // the tasks plugin's row swipe-to-reveal.
+  function handleHandlePointerDown(e: ReactPointerEvent) {
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragStartY.current = e.clientY;
+  }
+
+  function handleHandlePointerMove(e: ReactPointerEvent) {
+    const startY = dragStartY.current;
+    if (startY === null) return;
+    const dy = Math.max(0, e.clientY - startY); // upward drag has no effect — already fully open
+    const panel = panelRef.current;
+    if (!panel) return;
+    panel.style.transition = 'none';
+    panel.style.transform = `translateY(${dy}px)`;
+  }
+
+  // Releases the drag and resolves it to open (snap back) or closed, based on
+  // distance. Shared by pointerup (a completed gesture) and pointercancel
+  // (the browser took the gesture away, e.g. for a system gesture) — cancel
+  // always snaps back rather than honoring the distance, since it wasn't a
+  // deliberate release.
+  function releaseDrag(e: ReactPointerEvent, honorDistance: boolean) {
+    const startY = dragStartY.current;
+    dragStartY.current = null;
+    if (startY === null) return;
+    const dy = Math.max(0, e.clientY - startY);
+    const panel = panelRef.current;
+    if (panel) {
+      panel.style.transform = '';
+      panel.style.transition = '';
+    }
+    if (honorDistance && dy > SWIPE_DISMISS_THRESHOLD_PX) onClose();
+  }
+
+  if (!mounted) return null;
+  const isOpenPhase = phase === 'open';
 
   return (
     // role="presentation" removes the scrim from the AT (it is purely visual).
     // e.target check lets clicks inside the panel bubble without triggering dismiss.
     <div
-      className={styles.scrim}
+      className={[styles.scrim, isOpenPhase ? styles.scrimOpen : ''].filter(Boolean).join(' ')}
       role="presentation"
       onClick={(e) => {
         if (e.target === e.currentTarget) onClose();
@@ -101,8 +187,26 @@ export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: Dra
         aria-modal="true"
         aria-label={ariaLabel}
         tabIndex={-1}
-        className={styles.panel}
+        className={[
+          styles.panel,
+          snapHeight === 'half' ? styles.panelHalf : '',
+          isOpenPhase ? styles.panelOpen : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
       >
+        {/* The only drag-initiation region for swipe-down-to-dismiss — see the
+            component doc comment for why not the whole panel. Decorative +
+            functional, so no aria-label of its own; Esc and the scrim remain
+            the accessible dismiss paths. */}
+        <div
+          className={styles.handle}
+          aria-hidden="true"
+          onPointerDown={handleHandlePointerDown}
+          onPointerMove={handleHandlePointerMove}
+          onPointerUp={(e) => releaseDrag(e, true)}
+          onPointerCancel={(e) => releaseDrag(e, false)}
+        />
         {children}
       </div>
     </div>

package/src/components/Drawer/__tests__/Drawer.test.tsx

@@ -1,10 +1,48 @@
 // @vitest-environment jsdom
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
 import { Drawer } from '../Drawer';
 
+// Drawer's exit animation reads prefers-reduced-motion via matchMedia, which
+// jsdom does not implement. `matches: false` (motion enabled) exercises the
+// normal animated path; the actual reduced-motion behaviour is covered by
+// motion.ts's own tests.
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+// jsdom does not implement Element.setPointerCapture/releasePointerCapture
+// (another documented gap, alongside matchMedia and HTMLDialogElement) — the
+// grab handle's pointerdown handler calls setPointerCapture unconditionally.
+function installPointerCapture() {
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = () => {};
+  }
+  if (!Element.prototype.releasePointerCapture) {
+    Element.prototype.releasePointerCapture = () => {};
+  }
+}
+
 describe('Drawer', () => {
-  afterEach(cleanup);
+  beforeEach(() => {
+    installMatchMedia();
+    installPointerCapture();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
 
   it('renders nothing when closed', () => {
     render(
@@ -53,4 +91,87 @@ describe('Drawer', () => {
     fireEvent.click(scrim);
     expect(onClose).toHaveBeenCalledOnce();
   });
+
+  it('applies the half snapHeight class', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav" snapHeight="half">
+        Body
+      </Drawer>,
+    );
+    expect(screen.getByRole('dialog').className).toMatch(/panelHalf/);
+  });
+
+  it('does not apply the half snapHeight class by default (content-sized)', () => {
+    render(
+      <Drawer open onClose={() => {}} aria-label="Nav">
+        Body
+      </Drawer>,
+    );
+    expect(screen.getByRole('dialog').className).not.toMatch(/panelHalf/);
+  });
+
+  describe('swipe-down-to-dismiss (grab handle)', () => {
+    // The handle is the panel's first child, aria-hidden and unlabeled —
+    // same "select via DOM position" approach the scrim-click test above
+    // already uses for a similarly unlabeled element.
+    function getHandle() {
+      return screen.getByRole('dialog').firstElementChild as HTMLElement;
+    }
+
+    it('dismisses when dragged past the threshold', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 0 });
+      fireEvent.pointerMove(handle, { clientY: 150 });
+      fireEvent.pointerUp(handle, { clientY: 150 }); // 150px > 100px threshold
+      expect(onClose).toHaveBeenCalledOnce();
+    });
+
+    it('snaps back without dismissing when released under the threshold', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 0 });
+      fireEvent.pointerMove(handle, { clientY: 40 });
+      fireEvent.pointerUp(handle, { clientY: 40 }); // 40px < 100px threshold
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it('snaps back without dismissing on pointercancel, regardless of distance', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 0 });
+      fireEvent.pointerMove(handle, { clientY: 200 }); // well past the threshold
+      fireEvent.pointerCancel(handle, { clientY: 200 });
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it('ignores upward drags (already fully open)', () => {
+      const onClose = vi.fn();
+      render(
+        <Drawer open onClose={onClose} aria-label="Nav">
+          Body
+        </Drawer>,
+      );
+      const handle = getHandle();
+      fireEvent.pointerDown(handle, { clientY: 100 });
+      fireEvent.pointerMove(handle, { clientY: 0 }); // upward
+      fireEvent.pointerUp(handle, { clientY: 0 });
+      expect(onClose).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/components/FormField/FormField.module.css

@@ -2,6 +2,11 @@
   display: flex;
   flex-direction: column;
   gap: var(--sv-space-1);
+  /* Every local .field/.fieldGroup class this component replaced set this
+     explicitly. Without it, a parent with align-items: flex-start (needed so
+     submit buttons don't stretch full-width) shrink-wraps this wrapper to its
+     content's intrinsic width instead of filling the available space. */
+  width: 100%;
 }
 
 .label {

package/src/components/FormField/FormField.tsx

@@ -2,32 +2,59 @@ import type { ReactNode } from 'react';
 import { useId } from 'react';
 import styles from './FormField.module.css';
 
+/** Props to spread onto the field's actual form control. */
+export interface FormFieldRenderProps {
+  id: string;
+  'aria-describedby'?: string;
+  'aria-invalid'?: boolean;
+  required?: boolean;
+}
+
 export interface FormFieldProps {
   label: string;
   hint?: string;
   error?: string;
-  htmlFor?: string;
+  /** Explicit control id. Auto-generated via `useId()` when omitted. */
+  id?: string;
   required?: boolean;
-  children: ReactNode;
   className?: string;
+  /** Render prop — receives the props that must be spread onto the control
+   * so the label, hint, and error stay associated with it. */
+  children: (field: FormFieldRenderProps) => ReactNode;
 }
 
+/**
+ * FormField — accessible label + hint/error wrapper for a single form control.
+ * Wires `htmlFor`/`id` and `aria-describedby`/`aria-invalid` onto the control
+ * itself (via the render-prop `field` object), not a surrounding element, so
+ * screen readers reliably announce the hint or error as part of the control.
+ */
 export function FormField({
   label,
   hint,
   error,
-  htmlFor,
+  id,
   required = false,
-  children,
   className,
+  children,
 }: FormFieldProps) {
-  const hintId = useId();
-  const errorId = useId();
-  const describedBy = [hint && hintId, error && errorId].filter(Boolean).join(' ') || undefined;
+  const generatedId = useId();
+  const fieldId = id ?? generatedId;
+  const hintId = `${fieldId}-hint`;
+  const errorId = `${fieldId}-error`;
+  const describedBy =
+    [hint && !error && hintId, error && errorId].filter(Boolean).join(' ') || undefined;
+
+  const field: FormFieldRenderProps = {
+    id: fieldId,
+    'aria-describedby': describedBy,
+    'aria-invalid': error ? true : undefined,
+    required: required || undefined,
+  };
 
   return (
     <div className={[styles.field, className].filter(Boolean).join(' ')}>
-      <label className={styles.label} htmlFor={htmlFor}>
+      <label className={styles.label} htmlFor={fieldId}>
         {label}
         {required && (
           <span className={styles.required} aria-hidden="true">
@@ -35,9 +62,7 @@ export function FormField({
           </span>
         )}
       </label>
-      {/* Clone the child to inject aria-describedby — or just render children
-          and let the consumer wire htmlFor/id themselves */}
-      <div aria-describedby={describedBy}>{children}</div>
+      {children(field)}
       {hint && !error && (
         <p id={hintId} className={styles.hint}>
           {hint}

package/src/components/FormField/__tests__/FormField.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { FormField } from '../FormField';
+
+afterEach(cleanup);
+
+describe('FormField', () => {
+  it('associates the label with the control via htmlFor/id', () => {
+    render(
+      <FormField label="Email" id="email">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    expect(screen.getByLabelText('Email')).toBeDefined();
+  });
+
+  it('generates an id when none is provided', () => {
+    render(<FormField label="Email">{(field) => <input {...field} />}</FormField>);
+    const input = screen.getByLabelText('Email') as HTMLInputElement;
+    expect(input.id).toBeTruthy();
+  });
+
+  it('wires the hint to the control via aria-describedby', () => {
+    render(
+      <FormField label="Username" hint="Letters and numbers only." id="username">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    const input = screen.getByLabelText('Username');
+    const hint = screen.getByText('Letters and numbers only.');
+    expect(input.getAttribute('aria-describedby')).toBe(hint.id);
+  });
+
+  it('wires the error to the control via aria-describedby and marks it invalid', () => {
+    render(
+      <FormField label="Password" error="Too short." id="password">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    const input = screen.getByLabelText('Password');
+    const error = screen.getByText('Too short.');
+    expect(input.getAttribute('aria-describedby')).toBe(error.id);
+    expect(input.getAttribute('aria-invalid')).toBe('true');
+  });
+
+  it('renders the error with role="alert"', () => {
+    render(
+      <FormField label="Password" error="Too short." id="password">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    expect(screen.getByRole('alert').textContent).toBe('Too short.');
+  });
+
+  it('hides the hint when an error is present', () => {
+    render(
+      <FormField label="Password" hint="At least 8 characters." error="Too short." id="password">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    expect(screen.queryByText('At least 8 characters.')).toBeNull();
+  });
+
+  it('shows a required indicator and sets required on the control', () => {
+    render(
+      <FormField label="Full name" required id="name">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    const input = screen.getByLabelText(/Full name/) as HTMLInputElement;
+    expect(input.required).toBe(true);
+  });
+
+  it('does not set aria-describedby when there is no hint or error', () => {
+    render(
+      <FormField label="Nickname" id="nickname">
+        {(field) => <input {...field} />}
+      </FormField>,
+    );
+    expect(screen.getByLabelText('Nickname').hasAttribute('aria-describedby')).toBe(false);
+  });
+});

package/src/components/Icon/Icon.module.css

@@ -6,6 +6,11 @@
   /* Color follows the surrounding text via currentColor — no token needed. */
 }
 
+.xs {
+  width: var(--sv-icon-size-xs);
+  height: var(--sv-icon-size-xs);
+}
+
 .sm {
   width: var(--sv-icon-size-sm);
   height: var(--sv-icon-size-sm);

package/src/components/Icon/Icon.stories.tsx

@@ -18,7 +18,7 @@ const meta = {
   },
   argTypes: {
     name: { control: 'select', options: ALL_NAMES },
-    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    size: { control: 'select', options: ['xs', 'sm', 'md', 'lg'] },
   },
 } satisfies Meta<typeof Icon>;
 
@@ -35,17 +35,18 @@ export const Meaningful: Story = {
   args: { name: 'settings', size: 'md', 'aria-label': 'Open settings' },
 };
 
+export const SizeExtraSmall: Story = { args: { name: 'bell', size: 'xs', 'aria-hidden': true } };
 export const SizeSmall: Story = { args: { name: 'bell', size: 'sm', 'aria-hidden': true } };
 export const SizeMedium: Story = { args: { name: 'bell', size: 'md', 'aria-hidden': true } };
 export const SizeLarge: Story = { args: { name: 'bell', size: 'lg', 'aria-hidden': true } };
 
-/** Full icon grid — every name across all three sizes. */
+/** Full icon grid — every name across all four sizes. */
 export const AllIcons: Story = {
   parameters: { layout: 'padded' },
   args: { name: 'house', 'aria-hidden': true },
   render: (_args) => (
     <div>
-      {(['sm', 'md', 'lg'] as const).map((sz) => (
+      {(['xs', 'sm', 'md', 'lg'] as const).map((sz) => (
         <section key={sz} style={{ marginBottom: 32 }}>
           <h3
             style={{

package/src/components/Icon/Icon.tsx

@@ -12,7 +12,7 @@ export interface IconProps {
   /** Name of the icon from the curated Sovereign set. */
   name: IconName;
   /** Visual size. Defaults to `"md"` (20 px). */
-  size?: 'sm' | 'md' | 'lg';
+  size?: 'xs' | 'sm' | 'md' | 'lg';
   /** Additional CSS class applied to the SVG element. */
   className?: string;
 }