@sovereignfs/ui 0.41.0 → 0.54.0

package/src/stories/DesignSystemOverview.stories.tsx

@@ -8,6 +8,9 @@ import { Card } from '../components/Card/Card';
 import { Dialog } from '../components/Dialog/Dialog';
 import { Drawer } from '../components/Drawer/Drawer';
 import { EmptyState } from '../components/EmptyState/EmptyState';
+import { OfflineGate } from '../components/OfflineGate/OfflineGate';
+import { DeviceOnlyGate } from '../components/DeviceOnlyGate/DeviceOnlyGate';
+import { DeviceStorageKeyGate } from '../components/DeviceStorageKeyGate/DeviceStorageKeyGate';
 import { FormField } from '../components/FormField/FormField';
 import { Icon } from '../components/Icon/Icon';
 import type { IconName } from '../components/Icon/Icon';
@@ -21,9 +24,19 @@ import { StatusBadge } from '../components/StatusBadge/StatusBadge';
 import { SplitPane } from '../components/SplitPane/SplitPane';
 import { TagInput } from '../components/TagInput/TagInput';
 import { SuggestionInput } from '../components/SuggestionInput/SuggestionInput';
+import { MobileAppsDrawer } from '../components/MobileAppsDrawer/MobileAppsDrawer';
+import { MobileFooter } from '../components/MobileFooter/MobileFooter';
+import { MobileHeader } from '../components/MobileHeader/MobileHeader';
 import { NavTabs } from '../components/NavTabs/NavTabs';
 import { PageHeader } from '../components/PageHeader/PageHeader';
+import { PageContainer } from '../components/PageContainer/PageContainer';
 import { Popover } from '../components/Popover/Popover';
+import { ResponsiveSurface } from '../components/ResponsiveSurface/ResponsiveSurface';
+import { SwipableMobileCarousel } from '../components/SwipableMobileCarousel/SwipableMobileCarousel';
+import { SwipableMobileCarouselSlide } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlide';
+import { SwipableMobileCarouselSlideHeader } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlideHeader';
+import { SwipableMobileCarouselSlideBody } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody';
+import { SwipableMobileCarouselDots } from '../components/SwipableMobileCarouselDots/SwipableMobileCarouselDots';
 import { SegmentedControl } from '../components/SegmentedControl/SegmentedControl';
 import { Select } from '../components/Select/Select';
 import { Spinner } from '../components/Spinner/Spinner';
@@ -33,6 +46,46 @@ import { ToastProvider, useToast } from '../components/Toast/Toast';
 import { Toggle } from '../components/Toggle/Toggle';
 import { Tooltip } from '../components/Tooltip/Tooltip';
 import { Checkbox } from '../components/Checkbox/Checkbox';
+import { RadioGroup } from '../components/RadioGroup/RadioGroup';
+import { Slider } from '../components/Slider/Slider';
+import { Progress } from '../components/Progress/Progress';
+import {
+  Table,
+  TableHead,
+  TableBody,
+  TableRow,
+  TableHeaderCell,
+  TableCell,
+} from '../components/Table/Table';
+import { Alert } from '../components/Alert/Alert';
+import { Breadcrumb } from '../components/Breadcrumb/Breadcrumb';
+import { LegalLinks } from '../components/LegalLinks/LegalLinks';
+import { Markdown } from '../components/Markdown/Markdown';
+import { Pagination } from '../components/Pagination/Pagination';
+import { Kbd } from '../components/Kbd/Kbd';
+import { Accordion } from '../components/Accordion/Accordion';
+import { AspectRatio } from '../components/AspectRatio/AspectRatio';
+import { ButtonGroup } from '../components/ButtonGroup/ButtonGroup';
+import { Item } from '../components/Item/Item';
+import { Label } from '../components/Label/Label';
+import { ScrollArea } from '../components/ScrollArea/ScrollArea';
+import { Typography } from '../components/Typography/Typography';
+import { Marker } from '../components/Marker/Marker';
+import { Message } from '../components/Message/Message';
+import { MessageScroller } from '../components/MessageScroller/MessageScroller';
+import { HoverCard } from '../components/HoverCard/HoverCard';
+import { ContextMenu } from '../components/ContextMenu/ContextMenu';
+import { Command } from '../components/Command/Command';
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from '../components/Resizable/Resizable';
+import { DataTable } from '../components/DataTable/DataTable';
+import { Combobox } from '../components/Combobox/Combobox';
+import { NavigationMenu } from '../components/NavigationMenu/NavigationMenu';
+import { Menubar } from '../components/Menubar/Menubar';
+import { Collapsible } from '../components/Collapsible/Collapsible';
 import { DragHandleRow } from '../components/DragHandleRow/DragHandleRow';
 import { FileDropzone } from '../components/FileDropzone/FileDropzone';
 import { OverlayHeader } from '../components/OverlayHeader/OverlayHeader';
@@ -466,6 +519,64 @@ function TabsDemo() {
   );
 }
 
+function CommandDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button size="sm" onClick={() => setOpen(true)}>
+        Open command palette
+      </Button>
+      <Command
+        open={open}
+        onClose={() => setOpen(false)}
+        aria-label="Command palette"
+        items={[
+          {
+            id: 'new',
+            label: 'New conversation',
+            group: 'Actions',
+            icon: 'plus',
+            onSelect: () => {},
+          },
+          {
+            id: 'export',
+            label: 'Export chat',
+            group: 'Actions',
+            icon: 'upload',
+            onSelect: () => {},
+          },
+          {
+            id: 'profile',
+            label: 'Go to profile',
+            group: 'Navigation',
+            icon: 'user',
+            onSelect: () => {},
+          },
+        ]}
+      />
+    </>
+  );
+}
+
+function ComboboxDemo() {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <div style={{ width: 240 }}>
+      <Combobox
+        options={[
+          { value: 'tasks', label: 'sovereign-tasks' },
+          { value: 'ledger', label: 'sovereign-ledger' },
+          { value: 'shopper', label: 'sovereign-shopper' },
+        ]}
+        value={value}
+        onChange={setValue}
+        placeholder="Select a plugin"
+        aria-label="Plugin"
+      />
+    </div>
+  );
+}
+
 function DialogDemo() {
   const [open, setOpen] = useState(false);
   return (
@@ -535,6 +646,28 @@ function DrawerDemo() {
   );
 }
 
+function MobileAppsDrawerDemo() {
+  const [open, setOpen] = useState(false);
+  const items = [
+    { key: 'home', icon: <Icon name="house" size="lg" aria-hidden />, label: 'Home' },
+    { key: 'notes', icon: <Icon name="file" size="lg" aria-hidden />, label: 'Notes' },
+    { key: 'gallery', icon: <Icon name="grid-2x2" size="lg" aria-hidden />, label: 'Gallery' },
+  ];
+  return (
+    <>
+      <Button size="sm" variant="secondary" onClick={() => setOpen(true)}>
+        Open drawer
+      </Button>
+      <MobileAppsDrawer
+        open={open}
+        onClose={() => setOpen(false)}
+        aria-label="Sections"
+        items={items.map((item) => ({ ...item, onClick: () => setOpen(false) }))}
+      />
+    </>
+  );
+}
+
 function PopoverDemo() {
   const [open, setOpen] = useState(false);
   return (
@@ -825,6 +958,100 @@ function FileDropzoneDemo() {
   );
 }
 
+function ResponsiveSurfaceDemo() {
+  return (
+    <div
+      style={{
+        border: '1px dashed var(--sv-color-border)',
+        borderRadius: 'var(--sv-radius-md)',
+        padding: 'var(--sv-space-4)',
+        fontFamily: ff,
+        fontSize: 'var(--sv-font-size-sm)',
+        color: 'var(--sv-color-text-muted)',
+      }}
+    >
+      <ResponsiveSurface
+        web={
+          <span style={{ color: 'var(--sv-color-text-primary)' }}>
+            Web tree (resize below 768px)
+          </span>
+        }
+        mobile={<span style={{ color: 'var(--sv-color-text-primary)' }}>Mobile tree</span>}
+      />
+    </div>
+  );
+}
+
+const SWIPABLE_CAROUSEL_DEMO_SLIDES = [
+  { key: 'lists', label: 'Lists' },
+  { key: 'groceries', label: 'Groceries' },
+  { key: 'errands', label: 'Errands' },
+];
+
+function SwipableMobileCarouselDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <div
+      style={{
+        height: 220,
+        border: '1px solid var(--sv-color-border)',
+        borderRadius: 'var(--sv-radius-md)',
+        overflow: 'hidden',
+      }}
+    >
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={setActiveIndex}
+        aria-label="Task lists"
+      >
+        {SWIPABLE_CAROUSEL_DEMO_SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            <SwipableMobileCarouselSlideHeader>
+              <div
+                style={{
+                  padding: 'var(--sv-space-3)',
+                  fontFamily: ff,
+                  fontWeight: 'var(--sv-font-weight-semibold)',
+                  color: 'var(--sv-color-text-primary)',
+                }}
+              >
+                {slide.label}
+              </div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody>
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  height: '100%',
+                  fontFamily: ff,
+                  color: 'var(--sv-color-text-muted)',
+                }}
+              >
+                {slide.label} content
+              </div>
+            </SwipableMobileCarouselSlideBody>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </div>
+  );
+}
+
+function SwipableMobileCarouselDotsDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <SwipableMobileCarouselDots
+      count={3}
+      activeIndex={activeIndex}
+      onJump={setActiveIndex}
+      labels={['Lists', 'Groceries', 'Errands']}
+      aria-label="Task lists"
+    />
+  );
+}
+
 function IconPickerDemo() {
   const [value, setValue] = useState<IconName | null>('banana');
   const options: IconName[] = [
@@ -1327,6 +1554,21 @@ font-weight: var(--sv-font-weight-medium);    /* 500 */
 font-weight: var(--sv-font-weight-semibold);  /* 600 */
 font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
           </div>
+
+          <div style={{ marginTop: 'var(--sv-space-4)' }}>
+            <p
+              style={{
+                fontSize: 'var(--sv-font-size-caption)',
+                color: 'var(--sv-color-text-muted)',
+              }}
+            >
+              Every size above is rem-based, so the whole scale responds to the in-app text-size
+              control (Account → Preferences → Appearance, task 10.2), which sets{' '}
+              <code>[data-text-size]</code> on <code>&lt;html&gt;</code> to override{' '}
+              <code>--sv-text-size-scale</code> — see the &quot;Text-size presets&quot; section of
+              the Token Gallery.
+            </p>
+          </div>
         </section>
 
         {/* ── Spacing & Radius ─────────────────────────────────────────── */}
@@ -1486,7 +1728,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
         <section style={{ marginBottom: 'var(--sv-space-12)' }}>
           <SectionHeader
             title="Component gallery"
-            subtitle="All 22 components — click each story in the sidebar for the full API, variants, and controls."
+            subtitle="All 74 components — click each story in the sidebar for the full API, variants, and controls."
           />
 
           <div style={{ marginBottom: 'var(--sv-space-6)' }}>
@@ -1508,7 +1750,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             <ComponentCard
               name="Button"
               importLine="import { Button } from '@sovereignfs/ui';"
-              usage="Primary interactive control. Four variants: primary, secondary, ghost, destructive. Two sizes: md (default), sm. loading disables the button, sets aria-busy, and shows a spinner. 44px min-height under (pointer: coarse); hover behind (hover: hover)."
+              usage="Primary interactive control. Four variants: primary, secondary, ghost, destructive. Three sizes: lg, md (default), sm. loading disables the button, sets aria-busy, and shows a spinner. 44px min-height under (pointer: coarse); hover behind (hover: hover)."
             >
               <Button>Primary</Button>
               <Button variant="secondary">Secondary</Button>
@@ -1516,6 +1758,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               <Button variant="destructive" size="sm">
                 Delete
               </Button>
+              <Button size="lg">Large</Button>
               <Button loading>Saving…</Button>
             </ComponentCard>
 
@@ -1523,7 +1766,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             <ComponentCard
               name="Badge"
               importLine="import { Badge } from '@sovereignfs/ui';"
-              usage="Compact label for roles (role), lifecycle states (status), and type/version tags (mono). RSC-safe."
+              usage="Compact label for roles (role), lifecycle states (status), and type/version tags (mono). sm/md/lg sizes; ALL CAPS by default, or uppercase={false} for title case. RSC-safe."
             >
               <Badge variant="role">Admin</Badge>
               <Badge variant="status" status="active">
@@ -1533,6 +1776,9 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
                 Invited
               </Badge>
               <Badge variant="mono">v1.2.0</Badge>
+              <Badge variant="role" size="lg" uppercase={false}>
+                Owner
+              </Badge>
             </ComponentCard>
 
             {/* StatusBadge */}
@@ -1913,6 +2159,85 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* PageContainer */}
+            <ComponentCard
+              name="PageContainer"
+              importLine="import { PageContainer } from '@sovereignfs/ui';"
+              usage="Constrains and centers a plugin's main content width (sm/md/lg/full). Adds no padding of its own — the runtime shell already pads plugin content. Use instead of local container CSS in a plugin's layout."
+            >
+              <div style={{ width: '100%', background: 'var(--sv-color-surface-sunken)' }}>
+                <PageContainer maxWidth="sm">
+                  <div
+                    style={{
+                      background: 'var(--sv-color-surface-raised)',
+                      border: '1px dashed var(--sv-color-border)',
+                      borderRadius: 'var(--sv-radius-md)',
+                      padding: 'var(--sv-space-4)',
+                    }}
+                  >
+                    maxWidth=&quot;sm&quot;
+                  </div>
+                </PageContainer>
+              </div>
+            </ComponentCard>
+
+            {/* MobileHeader */}
+            <ComponentCard
+              name="MobileHeader"
+              importLine="import { MobileHeader } from '@sovereignfs/ui';"
+              usage="Mobile shell header content row (RFC 0088). Bell and avatarMenu are always rendered by the consumer; logo is optional — omit it for a default 'S' badge (matching the shell's own fallback brand icon), or supply your own. Title is the only content-level override. Presentational only — see Overview/Mobile Patterns for the full immutable/overridable boundary."
+            >
+              <div
+                style={{
+                  width: '100%',
+                  background: 'var(--sv-color-surface)',
+                  border: '1px solid var(--sv-color-border)',
+                  borderRadius: 'var(--sv-radius-md)',
+                  padding: '0 var(--sv-space-3)',
+                }}
+              >
+                <MobileHeader
+                  title="Tasks"
+                  bell={<Icon name="bell" size="lg" aria-label="Notifications" />}
+                  avatarMenu={<Avatar name="Jamie Doe" size="sm" />}
+                />
+              </div>
+            </ComponentCard>
+
+            {/* MobileFooter */}
+            <ComponentCard
+              name="MobileFooter"
+              importLine="import { MobileFooter } from '@sovereignfs/ui';"
+              usage="Mobile shell footer nav row (RFC 0088). The centered launcher (onOpenApps) is always rendered; leftIcons/rightIcons take 1 or 2 items each, symmetric so the launcher stays centered."
+            >
+              <div
+                style={{
+                  width: '100%',
+                  background: 'var(--sv-color-surface)',
+                  border: '1px solid var(--sv-color-border)',
+                  borderRadius: 'var(--sv-radius-md)',
+                  padding: '0 var(--sv-space-3)',
+                }}
+              >
+                <MobileFooter
+                  onOpenApps={() => {}}
+                  leftIcons={[{ icon: <Icon name="house" size="md" aria-hidden />, label: 'Home' }]}
+                  rightIcons={[
+                    { icon: <Icon name="search" size="md" aria-hidden />, label: 'Search' },
+                  ]}
+                />
+              </div>
+            </ComponentCard>
+
+            {/* MobileAppsDrawer */}
+            <ComponentCard
+              name="MobileAppsDrawer"
+              importLine="import { MobileAppsDrawer } from '@sovereignfs/ui';"
+              usage="The mobile 'Apps' bottom sheet: a 3-column tile grid matching the runtime shell's own Apps drawer exactly (56px icon tiles, radius 14px). No header row — Drawer's own grab handle plus swipe-down/scrim-tap dismissal are enough. The tile list is supplied by the consumer via `items` — e.g. installed plugins for the shell, or a plugin's own sections for its own launcher button."
+            >
+              <MobileAppsDrawerDemo />
+            </ComponentCard>
+
             {/* EmptyState */}
             <ComponentCard
               name="EmptyState"
@@ -1931,6 +2256,53 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               />
             </ComponentCard>
 
+            {/* OfflineGate */}
+            <ComponentCard
+              name="OfflineGate"
+              importLine="import { OfflineGate } from '@sovereignfs/ui';"
+              usage="Blocks an administrative/settings surface from rendering possibly-stale cached content while offline, showing an EmptyState instead. Reads the live useIsOffline() hook — toggle DevTools > Network > Offline to see it swap. Wrap the body of a surface like Console or Account where operating against stale data is actively wrong, not every page."
+            >
+              <OfflineGate surfaceName="Console">
+                <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)', fontSize: 14 }}>
+                  Renders normally while online.
+                </p>
+              </OfflineGate>
+            </ComponentCard>
+
+            {/* DeviceOnlyGate */}
+            <ComponentCard
+              name="DeviceOnlyGate"
+              importLine="import { DeviceOnlyGate } from '@sovereignfs/ui';"
+              usage="Blocks a device-only-tier plugin's content on a surface without the durable, encrypted, device-auth-gated store that tier needs. `available` is the caller's own isDeviceOnlyTierAvailable() result (from @sovereignfs/sdk/device-client) — a capability signal, never a security boundary; the real protection is that the data is encrypted regardless."
+            >
+              <DeviceOnlyGate available={false} surfaceName="Wallet">
+                <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)', fontSize: 14 }}>
+                  Renders normally when available.
+                </p>
+              </DeviceOnlyGate>
+            </ComponentCard>
+
+            {/* DeviceStorageKeyGate */}
+            <ComponentCard
+              name="DeviceStorageKeyGate"
+              importLine="import { DeviceStorageKeyGate } from '@sovereignfs/ui';"
+              usage="Blocks a device-only-tier plugin's content until the user has set up their Device Storage Key. `status` is the caller's own getDeviceStorageKeyStatus() result (from @sovereignfs/sdk/device-only-storage). Enrollment is centralized in Account > Security, not per-plugin — `setupAction` is where the caller supplies a link there."
+            >
+              <DeviceStorageKeyGate
+                status="not-set-up"
+                surfaceName="Notes"
+                setupAction={
+                  <a href="/account/security" style={{ color: 'var(--sv-color-accent)' }}>
+                    Go to Account → Security
+                  </a>
+                }
+              >
+                <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)', fontSize: 14 }}>
+                  Renders normally once set up.
+                </p>
+              </DeviceStorageKeyGate>
+            </ComponentCard>
+
             {/* Spinner */}
             <ComponentCard
               name="Spinner"
@@ -2032,6 +2404,540 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               })()}
             </ComponentCard>
 
+            {/* RadioGroup */}
+            <ComponentCard
+              name="RadioGroup"
+              importLine="import { RadioGroup } from '@sovereignfs/ui';"
+              usage="Single-select list of options. Renders real <input type=radio> elements sharing one name, so arrow-key navigation between options is native browser behavior, not hand-rolled."
+            >
+              {(() => {
+                const [size, setSize] = useState('md');
+                return (
+                  <RadioGroup
+                    items={[
+                      { label: 'Small', value: 'sm' },
+                      { label: 'Medium', value: 'md' },
+                      { label: 'Large', value: 'lg' },
+                    ]}
+                    value={size}
+                    onChange={setSize}
+                    aria-label="Size"
+                  />
+                );
+              })()}
+            </ComponentCard>
+
+            {/* Slider */}
+            <ComponentCard
+              name="Slider"
+              importLine="import { Slider } from '@sovereignfs/ui';"
+              usage="Single-thumb range input. A native <input type=range> under custom styling — arrow keys, Home/End, and touch-drag all come from the browser."
+            >
+              {(() => {
+                const [value, setValue] = useState(50);
+                return (
+                  <div style={{ width: 240 }}>
+                    <Slider value={value} onChange={setValue} min={0} max={100} label="Volume" />
+                  </div>
+                );
+              })()}
+            </ComponentCard>
+
+            {/* Progress */}
+            <ComponentCard
+              name="Progress"
+              importLine="import { Progress } from '@sovereignfs/ui';"
+              usage="Determinate progress bar. role=progressbar with aria-valuenow/min/max so screen readers announce the current value."
+            >
+              <div style={{ width: 240 }}>
+                <Progress value={65} label="Upload progress" />
+              </div>
+            </ComponentCard>
+
+            {/* Table */}
+            <ComponentCard
+              name="Table"
+              importLine="import { Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell } from '@sovereignfs/ui';"
+              usage="Thin, styled wrappers around the native table elements. Not a data grid — no sort/filter/virtualization. Scrolls horizontally (masked-edge fade) at any viewport size."
+            >
+              <Table>
+                <TableHead>
+                  <TableRow>
+                    <TableHeaderCell>Plugin</TableHeaderCell>
+                    <TableHeaderCell>Status</TableHeaderCell>
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  <TableRow>
+                    <TableCell>sovereign-tasks</TableCell>
+                    <TableCell>Active</TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell>sovereign-shopper</TableCell>
+                    <TableCell>Disabled</TableCell>
+                  </TableRow>
+                </TableBody>
+              </Table>
+            </ComponentCard>
+
+            {/* Alert */}
+            <ComponentCard
+              name="Alert"
+              importLine="import { Alert } from '@sovereignfs/ui';"
+              usage="Inline, non-dismissible banner. Distinct from Toast (transient) and SystemBanner (instance-wide) — for form-level errors or explaining an empty/blocked state. Leading icon defaults per variant; pass icon to override or icon={false} to suppress."
+            >
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+                <Alert variant="error" heading="Something went wrong">
+                  We couldn’t save your changes. Check your connection and try again.
+                </Alert>
+                <Alert variant="success">Invite sent.</Alert>
+                <Alert variant="neutral">This project has no members yet.</Alert>
+              </div>
+            </ComponentCard>
+
+            {/* Breadcrumb */}
+            <ComponentCard
+              name="Breadcrumb"
+              importLine="import { Breadcrumb } from '@sovereignfs/ui';"
+              usage="Link trail. The last item (no href) renders as plain text with aria-current=page. Pass renderLink to keep navigation client-side inside overlay-shell plugins."
+            >
+              <Breadcrumb
+                items={[
+                  { label: 'Console', href: '/console' },
+                  { label: 'Plugins', href: '/console/plugins' },
+                  { label: 'sovereign-tasks' },
+                ]}
+              />
+            </ComponentCard>
+
+            {/* LegalLinks */}
+            <ComponentCard
+              name="LegalLinks"
+              importLine="import { LegalLinks } from '@sovereignfs/ui';"
+              usage="Privacy Policy / Terms of Service link row for standalone auth pages (login, register, forgot/reset password). Pass renderLink to keep navigation client-side if ever mounted inside an SPA-like shell."
+            >
+              <LegalLinks />
+            </ComponentCard>
+
+            {/* Markdown */}
+            <ComponentCard
+              name="Markdown"
+              importLine="import { Markdown } from '@sovereignfs/ui';"
+              usage="Renders a constrained markdown subset (headings, paragraphs, bold/italic/code, links, lists, blockquotes) as Typography-based React elements — no HTML string injection. Built for first-party long-form content pages (privacy policy, terms of service), not arbitrary or user-supplied markdown."
+            >
+              <Markdown
+                content={
+                  '## Heading\n\nA paragraph with **bold** and a [link](/privacy).\n\n- One\n- Two'
+                }
+              />
+            </ComponentCard>
+
+            {/* Pagination */}
+            <ComponentCard
+              name="Pagination"
+              importLine="import { Pagination } from '@sovereignfs/ui';"
+              usage="Page-number / prev-next control. Shows first, last, and pages near the current one, with an ellipsis for gaps once the page count grows."
+            >
+              {(() => {
+                const [page, setPage] = useState(4);
+                return <Pagination page={page} totalPages={12} onChange={setPage} />;
+              })()}
+            </ComponentCard>
+
+            {/* Kbd */}
+            <ComponentCard
+              name="Kbd"
+              importLine="import { Kbd } from '@sovereignfs/ui';"
+              usage="Inline keyboard-key styling. Renders a real <kbd> element."
+            >
+              <span style={{ display: 'inline-flex', alignItems: 'center', gap: 4 }}>
+                <Kbd>Ctrl</Kbd>
+                <span>+</span>
+                <Kbd>K</Kbd>
+              </span>
+            </ComponentCard>
+
+            {/* Collapsible */}
+            <ComponentCard
+              name="Collapsible"
+              importLine="import { Collapsible } from '@sovereignfs/ui';"
+              usage="Single expand/collapse primitive. Independently useful (e.g. a 'show more' toggle), and composed internally by Accordion."
+            >
+              {(() => {
+                const [open, setOpen] = useState(false);
+                return (
+                  <Collapsible open={open} onOpenChange={setOpen} trigger="Advanced settings">
+                    These settings are rarely needed — change them only if you know what you're
+                    doing.
+                  </Collapsible>
+                );
+              })()}
+            </ComponentCard>
+
+            {/* Accordion */}
+            <ComponentCard
+              name="Accordion"
+              importLine="import { Accordion } from '@sovereignfs/ui';"
+              usage="One or more Collapsible sections. type=single closes other sections when one opens; type=multiple allows any number open at once."
+            >
+              {(() => {
+                const [openIds, setOpenIds] = useState<string[]>(['plugins']);
+                return (
+                  <Accordion
+                    items={[
+                      {
+                        id: 'plugins',
+                        trigger: 'What plugins ship by default?',
+                        content:
+                          'Only the platform plugins (Console, Launcher, Account) plus Sovereign Tasks.',
+                      },
+                      {
+                        id: 'hosting',
+                        trigger: 'Can I self-host this?',
+                        content:
+                          'Yes — Sovereign is designed to be self-hosted via Docker Compose.',
+                      },
+                    ]}
+                    type="single"
+                    openIds={openIds}
+                    onOpenIdsChange={setOpenIds}
+                  />
+                );
+              })()}
+            </ComponentCard>
+
+            {/* AspectRatio */}
+            <ComponentCard
+              name="AspectRatio"
+              importLine="import { AspectRatio } from '@sovereignfs/ui';"
+              usage="Constrains content (image, video, embed) to a fixed ratio."
+            >
+              <div style={{ width: 200 }}>
+                <AspectRatio ratio={16 / 9}>
+                  <div
+                    style={{
+                      width: '100%',
+                      height: '100%',
+                      background: 'var(--sv-color-surface-sunken)',
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      color: 'var(--sv-color-text-muted)',
+                      fontSize: 'var(--sv-font-size-xs)',
+                    }}
+                  >
+                    16:9
+                  </div>
+                </AspectRatio>
+              </div>
+            </ComponentCard>
+
+            {/* ButtonGroup */}
+            <ComponentCard
+              name="ButtonGroup"
+              importLine="import { ButtonGroup } from '@sovereignfs/ui';"
+              usage="Visually joins adjacent Buttons into one control (shared border, connected corners)."
+            >
+              <ButtonGroup aria-label="View">
+                <Button variant="secondary" size="sm">
+                  Day
+                </Button>
+                <Button variant="secondary" size="sm">
+                  Week
+                </Button>
+                <Button variant="secondary" size="sm">
+                  Month
+                </Button>
+              </ButtonGroup>
+            </ComponentCard>
+
+            {/* Item */}
+            <ComponentCard
+              name="Item"
+              importLine="import { Item } from '@sovereignfs/ui';"
+              usage="Generic row primitive: leading slot, title + optional description, trailing slot. For settings rows and list rows that don't fit Menu's own item shape."
+            >
+              <Item
+                title="Notifications"
+                description="Manage email and push alerts"
+                leading={<Icon name="bell" aria-hidden />}
+                trailing={<Icon name="chevron-right" size="sm" aria-hidden />}
+                onClick={() => {}}
+              />
+            </ComponentCard>
+
+            {/* Label */}
+            <ComponentCard
+              name="Label"
+              importLine="import { Label } from '@sovereignfs/ui';"
+              usage="Standalone accessible form label, independent of FormField. Use FormField when a control needs hint/error text too."
+            >
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+                <Label htmlFor="label-demo-input">Email address</Label>
+                <input
+                  id="label-demo-input"
+                  type="email"
+                  placeholder="you@example.com"
+                  style={{
+                    padding: 'var(--sv-space-2) var(--sv-space-3)',
+                    border: '1px solid var(--sv-color-border-strong)',
+                    borderRadius: 'var(--sv-radius-md)',
+                    fontFamily: 'var(--sv-font-family)',
+                    fontSize: 'var(--sv-font-size-sm)',
+                  }}
+                />
+              </div>
+            </ComponentCard>
+
+            {/* ScrollArea */}
+            <ComponentCard
+              name="ScrollArea"
+              importLine="import { ScrollArea } from '@sovereignfs/ui';"
+              usage="Styled scrollable container — thin, token-colored scrollbar instead of the OS default. Native overflow scrolling underneath."
+            >
+              <ScrollArea maxHeight={120}>
+                <div style={{ display: 'flex', flexDirection: 'column', gap: 8, padding: 4 }}>
+                  {Array.from({ length: 10 }, (_, i) => (
+                    <div key={i} style={{ fontSize: 13 }}>
+                      Row {i + 1}
+                    </div>
+                  ))}
+                </div>
+              </ScrollArea>
+            </ComponentCard>
+
+            {/* Typography */}
+            <ComponentCard
+              name="Typography"
+              importLine="import { Typography } from '@sovereignfs/ui';"
+              usage="Text bound to the design system's font-size/weight scale. Pass `as` to override the rendered tag while keeping the variant's visual style."
+            >
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+                <Typography variant="h3">Heading 3</Typography>
+                <Typography variant="body">Body copy for descriptions.</Typography>
+                <Typography variant="caption">Caption — secondary text.</Typography>
+              </div>
+            </ComponentCard>
+
+            {/* Marker */}
+            <ComponentCard
+              name="Marker"
+              importLine="import { Marker } from '@sovereignfs/ui';"
+              usage="Inline citation/reference marker — attributes part of an assistant answer to a source (Sovereign Harness 'source trace', RFC 0040)."
+            >
+              <p style={{ fontSize: 14, margin: 0 }}>
+                Your next task is due Thursday
+                <Marker index={1} label="Source: Tasks" onClick={() => {}} />.
+              </p>
+            </ComponentCard>
+
+            {/* Message */}
+            <ComponentCard
+              name="Message"
+              importLine="import { Message } from '@sovereignfs/ui';"
+              usage="A single chat turn for the Sovereign Harness assistant. role is user/assistant/tool, matching harness_messages (RFC 0040). Content is caller-controlled ReactNode."
+            >
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+                <Message sender="user">What's on my plate this week?</Message>
+                <Message sender="assistant">You have 3 tasks due this week.</Message>
+              </div>
+            </ComponentCard>
+
+            {/* MessageScroller */}
+            <ComponentCard
+              name="MessageScroller"
+              importLine="import { MessageScroller } from '@sovereignfs/ui';"
+              usage="Auto-scrolling chat container. Scrolls to the newest message while the user is near the bottom; shows a 'New messages' button instead of yanking them down if they've scrolled up."
+            >
+              <div style={{ height: 160, border: '1px solid var(--sv-color-border)' }}>
+                <MessageScroller>
+                  <Message sender="user">Hi there</Message>
+                  <Message sender="assistant">How can I help?</Message>
+                </MessageScroller>
+              </div>
+            </ComponentCard>
+
+            {/* HoverCard */}
+            <ComponentCard
+              name="HoverCard"
+              importLine="import { HoverCard } from '@sovereignfs/ui';"
+              usage="Hover-triggered popover on desktop, tap-to-toggle on touch. Built on Popover for positioning — adds hover-intent timing and the touch fallback. Opens on keyboard focus too."
+            >
+              <HoverCard
+                aria-label="User preview"
+                trigger={
+                  <button
+                    type="button"
+                    style={{ background: 'none', border: 'none', padding: 0, cursor: 'pointer' }}
+                  >
+                    <Avatar name="Jane Smith" size="sm" />
+                  </button>
+                }
+              >
+                <div style={{ padding: 'var(--sv-space-3)', fontSize: 14 }}>
+                  <div style={{ fontWeight: 600 }}>Jane Smith</div>
+                  <div style={{ color: 'var(--sv-color-text-muted)' }}>jane@example.com</div>
+                </div>
+              </HoverCard>
+            </ComponentCard>
+
+            {/* ContextMenu */}
+            <ComponentCard
+              name="ContextMenu"
+              importLine="import { ContextMenu } from '@sovereignfs/ui';"
+              usage="Right-click menu on desktop, long-press on touch. Desktop positioning reuses Popover's collision detection anchored to the click point; touch opens the same items in a Drawer."
+            >
+              <ContextMenu
+                aria-label="Row actions"
+                items={[
+                  { label: 'Rename', onSelect: () => {} },
+                  { label: 'Duplicate', onSelect: () => {} },
+                  { type: 'separator' },
+                  { label: 'Delete', destructive: true, onSelect: () => {} },
+                ]}
+              >
+                <div
+                  style={{
+                    padding: 'var(--sv-space-4)',
+                    border: '1px dashed var(--sv-color-border-strong)',
+                    borderRadius: 'var(--sv-radius-md)',
+                    textAlign: 'center',
+                    fontSize: 14,
+                    color: 'var(--sv-color-text-muted)',
+                  }}
+                >
+                  Right-click here
+                </div>
+              </ContextMenu>
+            </ComponentCard>
+
+            {/* NavigationMenu */}
+            <ComponentCard
+              name="NavigationMenu"
+              importLine="import { NavigationMenu } from '@sovereignfs/ui';"
+              usage="Top-level nav bar where some items open a flyout panel. Desktop-oriented — a hover-triggered flyout bar has no mobile equivalent."
+            >
+              <NavigationMenu
+                aria-label="Main"
+                items={[
+                  { label: 'Home', href: '/home' },
+                  {
+                    label: 'Products',
+                    content: (
+                      <div style={{ padding: 'var(--sv-space-3)', fontSize: 14 }}>
+                        Tasks · Ledger · Shopper
+                      </div>
+                    ),
+                  },
+                ]}
+              />
+            </ComponentCard>
+
+            {/* Menubar */}
+            <ComponentCard
+              name="Menubar"
+              importLine="import { Menubar } from '@sovereignfs/ui';"
+              usage="Desktop app-style menu bar (File/Edit/View...). A thin composition of NavigationMenu with MenuEntries as each item's flyout content."
+            >
+              <Menubar
+                menus={[
+                  {
+                    label: 'File',
+                    items: [
+                      { label: 'New conversation', onSelect: () => {} },
+                      { label: 'Export', onSelect: () => {} },
+                    ],
+                  },
+                  {
+                    label: 'Edit',
+                    items: [
+                      { label: 'Undo', onSelect: () => {} },
+                      { label: 'Redo', onSelect: () => {} },
+                    ],
+                  },
+                ]}
+              />
+            </ComponentCard>
+
+            {/* Command */}
+            <ComponentCard
+              name="Command"
+              importLine="import { Command } from '@sovereignfs/ui';"
+              usage="⌘K-style command palette. Opened via Dialog for the modal shell — adds the search input, substring filtering, and arrow-key/Enter selection. Controlled: consumer owns the open state."
+            >
+              <CommandDemo />
+            </ComponentCard>
+
+            {/* Resizable */}
+            <ComponentCard
+              name="Resizable"
+              importLine="import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@sovereignfs/ui';"
+              usage="A row or column of resizable panes. Each handle resizes only its two immediate neighbor panels. Desktop-oriented — panels render at their default sizes on touch."
+            >
+              <div style={{ width: '100%', height: 160 }}>
+                <ResizablePanelGroup direction="horizontal">
+                  <ResizablePanel defaultSize={30} minSize={15} maxSize={50}>
+                    <div
+                      style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        height: '100%',
+                        fontSize: 14,
+                        color: 'var(--sv-color-text-muted)',
+                      }}
+                    >
+                      Sidebar
+                    </div>
+                  </ResizablePanel>
+                  <ResizableHandle aria-label="Resize sidebar" />
+                  <ResizablePanel defaultSize={70}>
+                    <div
+                      style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        height: '100%',
+                        fontSize: 14,
+                        color: 'var(--sv-color-text-muted)',
+                      }}
+                    >
+                      Content
+                    </div>
+                  </ResizablePanel>
+                </ResizablePanelGroup>
+              </div>
+            </ComponentCard>
+
+            {/* DataTable */}
+            <ComponentCard
+              name="DataTable"
+              importLine="import { DataTable } from '@sovereignfs/ui';"
+              usage="Sortable table built on Table. Column-driven: pass columns + data instead of composing TableRow/TableCell by hand. Clicking a sortable header cycles ascending → descending → unsorted."
+            >
+              <DataTable
+                columns={[
+                  { key: 'name', header: 'Plugin', sortable: true },
+                  { key: 'installs', header: 'Installs', sortable: true, align: 'end' },
+                ]}
+                data={[
+                  { id: 'tasks', name: 'sovereign-tasks', installs: 482 },
+                  { id: 'ledger', name: 'sovereign-ledger', installs: 219 },
+                  { id: 'shopper', name: 'sovereign-shopper', installs: 37 },
+                ]}
+                getRowKey={(row) => row.id}
+              />
+            </ComponentCard>
+
+            {/* Combobox */}
+            <ComponentCard
+              name="Combobox"
+              importLine="import { Combobox } from '@sovereignfs/ui';"
+              usage="A searchable single-select: Popover on desktop, a bottom-sheet Drawer on mobile. For a short fixed list where search adds no value, use Select's native <select> instead."
+            >
+              <ComboboxDemo />
+            </ComponentCard>
+
             {/* DragHandleRow */}
             <ComponentCard
               name="DragHandleRow"
@@ -2064,6 +2970,33 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             >
               <FileDropzoneDemo />
             </ComponentCard>
+
+            {/* ResponsiveSurface */}
+            <ComponentCard
+              name="ResponsiveSurface"
+              importLine="import { ResponsiveSurface } from '@sovereignfs/ui';"
+              usage="Renders an entirely different component tree below a breakpoint, not a CSS squeeze of the same one — only the active side is ever mounted. See also the useResponsiveLayout hook for non-JSX values."
+            >
+              <ResponsiveSurfaceDemo />
+            </ComponentCard>
+
+            {/* SwipableMobileCarousel */}
+            <ComponentCard
+              name="SwipableMobileCarousel"
+              importLine="import { SwipableMobileCarousel, SwipableMobileCarouselSlide, SwipableMobileCarouselSlideHeader, SwipableMobileCarouselSlideBody } from '@sovereignfs/ui';"
+              usage="Compound component for swiping between full-width slides. A Slide's Header/Footer always render; only Body's own loading prop gates its content, so a title can show immediately while the body's own fetch is still in flight. Owns mount-window/reorder mechanics only — never put cross-slide aggregation or a detail overlay inside a Slide."
+            >
+              <SwipableMobileCarouselDemo />
+            </ComponentCard>
+
+            {/* SwipableMobileCarouselDots */}
+            <ComponentCard
+              name="SwipableMobileCarouselDots"
+              importLine="import { SwipableMobileCarouselDots } from '@sovereignfs/ui';"
+              usage="A real, tappable, labeled slide indicator (role=tablist/tab) — standalone and reusable outside SwipableMobileCarousel too, and its default renderIndicator."
+            >
+              <SwipableMobileCarouselDotsDemo />
+            </ComponentCard>
           </div>
         </section>