@sovereignfs/ui 0.45.0 → 0.83.1

package/src/stories/DesignSystemOverview.stories.tsx

@@ -5,13 +5,18 @@ import { Avatar } from '../components/Avatar/Avatar';
 import { Badge } from '../components/Badge/Badge';
 import { Button } from '../components/Button/Button';
 import { Card } from '../components/Card/Card';
+import { CardTile, CardTileGrid, NewCardTile } from '../components/CardTile/CardTile';
 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';
 import { IconPicker } from '../components/IconPicker/IconPicker';
+import { ColorPicker } from '../components/ColorPicker/ColorPicker';
 import { QuantityStepper } from '../components/QuantityStepper/QuantityStepper';
 import { CheckableListRow } from '../components/CheckableListRow/CheckableListRow';
 import { Input } from '../components/Input/Input';
@@ -19,11 +24,32 @@ import { CodeTextarea } from '../components/CodeTextarea/CodeTextarea';
 import { Textarea } from '../components/Textarea/Textarea';
 import { StatusBadge } from '../components/StatusBadge/StatusBadge';
 import { SplitPane } from '../components/SplitPane/SplitPane';
+import { ThreeColumnLayout } from '../components/ThreeColumnLayout/ThreeColumnLayout';
+import { HeaderFooterLayout } from '../components/HeaderFooterLayout/HeaderFooterLayout';
+import { RootLayout } from '../components/RootLayout/RootLayout';
+import { PageLayout } from '../components/PageLayout/PageLayout';
 import { TagInput } from '../components/TagInput/TagInput';
 import { SuggestionInput } from '../components/SuggestionInput/SuggestionInput';
+import { AppsLauncher } from '../components/AppsLauncher/AppsLauncher';
+import { Header } from '../components/Header/Header';
+import { MobileAppsDrawer } from '../components/MobileAppsDrawer/MobileAppsDrawer';
+import { MobileFooter } from '../components/MobileFooter/MobileFooter';
+import { MobileHeader } from '../components/MobileHeader/MobileHeader';
+import { NavList } from '../components/NavList/NavList';
 import { NavTabs } from '../components/NavTabs/NavTabs';
+import { NotificationsPanel } from '../components/NotificationsPanel/NotificationsPanel';
 import { PageHeader } from '../components/PageHeader/PageHeader';
+import { PageContainer } from '../components/PageContainer/PageContainer';
 import { Popover } from '../components/Popover/Popover';
+import { UserMenu } from '../components/UserMenu/UserMenu';
+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 { SwipeStack } from '../components/SwipeStack/SwipeStack';
+import { SwipeStackCard } from '../components/SwipeStack/SwipeStackCard';
 import { SegmentedControl } from '../components/SegmentedControl/SegmentedControl';
 import { Select } from '../components/Select/Select';
 import { Spinner } from '../components/Spinner/Spinner';
@@ -46,6 +72,9 @@ import {
 } from '../components/Table/Table';
 import { Alert } from '../components/Alert/Alert';
 import { Breadcrumb } from '../components/Breadcrumb/Breadcrumb';
+import { LegalLinks } from '../components/LegalLinks/LegalLinks';
+import { ConsentPrompt } from '../components/ConsentPrompt/ConsentPrompt';
+import { Markdown } from '../components/Markdown/Markdown';
 import { Pagination } from '../components/Pagination/Pagination';
 import { Kbd } from '../components/Kbd/Kbd';
 import { Accordion } from '../components/Accordion/Accordion';
@@ -72,11 +101,13 @@ 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 { GripIcon } from '../components/GripIcon/GripIcon';
+import { StepStrip, type StepStripItem } from '../components/StepStrip/StepStrip';
 import { FileDropzone } from '../components/FileDropzone/FileDropzone';
 import { OverlayHeader } from '../components/OverlayHeader/OverlayHeader';
 import { Sheet } from '../components/Sheet/Sheet';
 import { ConfirmDialog } from '../components/ConfirmDialog/ConfirmDialog';
-import { Menu } from '../components/Menu/Menu';
+import { Menu, MenuEntries } from '../components/Menu/Menu';
 import { Calendar } from '../components/Calendar/Calendar';
 import { DatePicker } from '../components/DatePicker/DatePicker';
 import { CurrencyInput } from '../components/CurrencyInput/CurrencyInput';
@@ -236,6 +267,8 @@ const COLOR_GROUPS: Array<{
       { token: '--sv-color-text-on-accent', name: 'text-on-accent' },
       { token: '--sv-color-text-on-error', name: 'text-on-error' },
       { token: '--sv-color-text-on-success', name: 'text-on-success' },
+      { token: '--sv-color-text-on-light-fill', name: 'text-on-light-fill' },
+      { token: '--sv-color-text-on-dark-fill', name: 'text-on-dark-fill' },
     ],
   },
   {
@@ -246,6 +279,12 @@ const COLOR_GROUPS: Array<{
       { token: '--sv-color-border-strong', name: 'border-strong' },
     ],
   },
+  {
+    label: 'Shadow',
+    usage:
+      'High-contrast shadow color for theme presets with hard offset shadows (RFC 0094). Unused by the default theme.',
+    tokens: [{ token: '--sv-color-shadow-strong', name: 'shadow-strong' }],
+  },
   {
     label: 'Accent',
     usage:
@@ -375,6 +414,7 @@ function ColorGroup({
 // ---------------------------------------------------------------------------
 
 const TYPE_SCALE: Array<{ token: string; label: string; note: string }> = [
+  { token: '--sv-font-size-3xl', label: '3xl — 32px', note: 'Document title style' },
   { token: '--sv-font-size-2xl', label: '2xl — 24px', note: 'Page titles' },
   { token: '--sv-font-size-xl', label: 'xl — 20px', note: 'Section headings' },
   { token: '--sv-font-size-lg', label: 'lg — 18px', note: 'Sub-headings' },
@@ -383,6 +423,11 @@ const TYPE_SCALE: Array<{ token: string; label: string; note: string }> = [
   { token: '--sv-font-size-caption', label: 'caption — 13px', note: 'Secondary / supporting copy' },
   { token: '--sv-font-size-xs', label: 'xs — 12px', note: 'Mono identifiers, badges' },
   { token: '--sv-font-size-label', label: 'label — 11px', note: 'All-caps section labels' },
+  {
+    token: '--sv-font-size-2xs',
+    label: '2xs — 10px',
+    note: 'Badge size="xs" — smallest badge tier',
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -631,6 +676,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 (
@@ -795,6 +862,24 @@ function MenuDemo() {
   );
 }
 
+function MenuEntriesDemo() {
+  return (
+    <div style={{ width: '100%', maxWidth: 240 }}>
+      <MenuEntries
+        items={[
+          { type: 'label', label: 'Sort by' },
+          { label: 'Manual', checked: true },
+          { label: 'Title', checked: false },
+          { type: 'separator' },
+          { label: 'Rename', icon: 'pencil' },
+          { label: 'Delete', icon: 'trash-2', destructive: true },
+        ]}
+        onSelect={() => {}}
+      />
+    </div>
+  );
+}
+
 function CalendarDemo() {
   const [value, setValue] = useState<Date | null>(new Date());
   return (
@@ -921,6 +1006,187 @@ function FileDropzoneDemo() {
   );
 }
 
+interface StepStripDemoStop extends StepStripItem {
+  label: string;
+  sublabel: string;
+}
+
+const STEP_STRIP_DEMO_STOPS: StepStripDemoStop[] = [
+  { id: 'lisbon', label: 'Lisbon', sublabel: 'Aug 26 – 28' },
+  { id: 'porto', label: 'Porto', sublabel: 'Aug 28 – 30' },
+];
+
+function StepStripDemo() {
+  const [activeId, setActiveId] = useState('lisbon');
+  return (
+    <StepStrip
+      items={STEP_STRIP_DEMO_STOPS}
+      activeId={activeId}
+      aria-label="Trip stops"
+      onAdd={() => undefined}
+      addLabel="Add a stop"
+      renderItem={(stop, { isActive }) => (
+        <button
+          type="button"
+          onClick={() => setActiveId(stop.id)}
+          style={{
+            boxSizing: 'border-box',
+            minWidth: '150px',
+            padding: 'var(--sv-space-3) var(--sv-space-4)',
+            borderRadius: 'var(--sv-radius-lg)',
+            border: `1px solid ${isActive ? 'var(--sv-color-text-primary)' : 'var(--sv-color-border)'}`,
+            background: isActive
+              ? 'var(--sv-color-text-primary)'
+              : 'var(--sv-color-surface-raised)',
+            color: isActive ? 'var(--sv-color-surface)' : 'var(--sv-color-text-primary)',
+            cursor: 'pointer',
+            textAlign: 'left',
+          }}
+        >
+          <div style={{ fontWeight: 600, fontSize: 'var(--sv-font-size-sm)' }}>{stop.label}</div>
+          <div style={{ fontSize: 'var(--sv-font-size-xs)', opacity: 0.8 }}>{stop.sublabel}</div>
+        </button>
+      )}
+    />
+  );
+}
+
+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"
+    />
+  );
+}
+
+const SWIPE_STACK_DEMO_CARDS = [
+  { id: 'water-plants', title: 'Water the plants' },
+  { id: 'standup', title: 'Team standup · 9:30am' },
+  { id: 'groceries', title: 'Buy groceries' },
+];
+
+function SwipeStackDemo() {
+  return (
+    <div style={{ height: 260, maxWidth: 320 }}>
+      <SwipeStack
+        aria-label="Today's agenda"
+        directions={{
+          up: { label: 'Done', icon: 'check' },
+          down: { label: 'Defer', icon: 'history' },
+        }}
+        onSwipe={() => {}}
+      >
+        {SWIPE_STACK_DEMO_CARDS.map((card) => (
+          <SwipeStackCard key={card.id} cardId={card.id}>
+            <div
+              style={{
+                height: '100%',
+                boxSizing: 'border-box',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                padding: 'var(--sv-space-4)',
+                fontFamily: ff,
+                fontWeight: 'var(--sv-font-weight-semibold)',
+                color: 'var(--sv-color-text-primary)',
+                textAlign: 'center',
+              }}
+            >
+              {card.title}
+            </div>
+          </SwipeStackCard>
+        ))}
+      </SwipeStack>
+    </div>
+  );
+}
+
 function IconPickerDemo() {
   const [value, setValue] = useState<IconName | null>('banana');
   const options: IconName[] = [
@@ -946,6 +1212,26 @@ function IconPickerDemo() {
   );
 }
 
+function ColorPickerDemo() {
+  const [value, setValue] = useState<string | null>('#b5c9e8');
+  const swatches = [
+    { label: 'Sky', value: '#b5c9e8' },
+    { label: 'Sage', value: '#c9e0c4' },
+    { label: 'Sand', value: '#e8d3b5' },
+    { label: 'Clay', value: '#e0c4c4' },
+    { label: 'Lilac', value: '#d8c4e0' },
+  ];
+  return (
+    <ColorPicker
+      swatches={swatches}
+      value={value}
+      onChange={setValue}
+      allowNone
+      aria-label="Board color"
+    />
+  );
+}
+
 function SuggestionInputDemo() {
   const [value, setValue] = useState('ban');
   const options = ['Bananas', 'Banana bread mix']
@@ -1423,6 +1709,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 ─────────────────────────────────────────── */}
@@ -1582,7 +1883,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 77 components — click each story in the sidebar for the full API, variants, and controls."
           />
 
           <div style={{ marginBottom: 'var(--sv-space-6)' }}>
@@ -1620,7 +1921,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). sm/md/lg sizes; ALL CAPS by default, or uppercase={false} for title case. RSC-safe."
+              usage="Compact label for roles (role), lifecycle states (status), and type/version tags (mono). xs/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">
@@ -1633,6 +1934,9 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               <Badge variant="role" size="lg" uppercase={false}>
                 Owner
               </Badge>
+              <Badge variant="status" status="active" size="xs">
+                Connected
+              </Badge>
             </ComponentCard>
 
             {/* StatusBadge */}
@@ -1708,6 +2012,15 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               <IconPickerDemo />
             </ComponentCard>
 
+            {/* ColorPicker */}
+            <ComponentCard
+              name="ColorPicker"
+              importLine="import { ColorPicker } from '@sovereignfs/ui';"
+              usage="Curated swatch suggestions plus a native color-input trigger for picking any color — not just the curated set."
+            >
+              <ColorPickerDemo />
+            </ComponentCard>
+
             {/* QuantityStepper */}
             <ComponentCard
               name="QuantityStepper"
@@ -1781,7 +2094,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             <ComponentCard
               name="Icon"
               importLine="import { Icon } from '@sovereignfs/ui';"
-              usage="SVG icon primitive. 52 bundled icons. Decorative: aria-hidden. Meaningful: aria-label. Three sizes: sm, md, lg."
+              usage="SVG icon primitive. 96 bundled icons. Decorative: aria-hidden. Meaningful: aria-label. Three sizes: sm, md, lg."
             >
               {(
                 [
@@ -1864,6 +2177,15 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               <MenuDemo />
             </ComponentCard>
 
+            {/* MenuEntries */}
+            <ComponentCard
+              name="MenuEntries"
+              importLine="import { MenuEntries } from '@sovereignfs/ui';"
+              usage='The <ul role="menu"> item list itself, factored out of Menu so other adaptive-surface components (ContextMenu, Menubar) can render the exact same items/destructive/checked/icon markup inside their own positioning shell instead of re-deriving it. No panel chrome of its own — the background/border/shadow around it belongs to whichever surface hosts it.'
+            >
+              <MenuEntriesDemo />
+            </ComponentCard>
+
             {/* Calendar */}
             <ComponentCard
               name="Calendar"
@@ -1899,7 +2221,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             <ComponentCard
               name="Toast"
               importLine="import { ToastProvider, useToast } from '@sovereignfs/ui';"
-              usage="Fixed top-right notification stack. Wrap app in ToastProvider; call useToast().show() imperatively. Six categories."
+              usage="Fixed top-right on desktop, bottom-center on mobile. Wrap app in ToastProvider; call useToast().show() imperatively. Six categories."
             >
               <ToastProvider>
                 <ToastDemo />
@@ -1920,6 +2242,38 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* CardTile */}
+            <ComponentCard
+              name="CardTile"
+              importLine="import { CardTile, CardTileGrid, NewCardTile } from '@sovereignfs/ui';"
+              usage="A colored/iconed banner over a footer label, for a grid of navigable top-level entities (projects, boards). Card can't express this — its padding always wraps the whole box, with no bleed slot for a full-width banner. Not link-aware; wrap each tile in the host router's own link component. Pair with NewCardTile for the grid's 'add new' affordance. The icon variant below swaps the card chrome for a plain Finder-style icon + label, for entities that read as a single glyph + name (e.g. a folder)."
+            >
+              <CardTileGrid minTileWidth={140}>
+                <CardTile banner={<Icon name="folder" size="lg" aria-hidden={true} />}>
+                  Q4 Planning
+                </CardTile>
+                <CardTile bannerColor="#c7d8ff">Marketing site</CardTile>
+                <NewCardTile label="New project" />
+              </CardTileGrid>
+              <div style={{ marginTop: 'var(--sv-space-4)' }}>
+                <CardTileGrid dense minTileWidth={100}>
+                  <CardTile
+                    variant="icon"
+                    banner={<Icon name="folder-closed" size="lg" aria-hidden={true} />}
+                  >
+                    Handbook
+                  </CardTile>
+                  <CardTile
+                    variant="icon"
+                    banner={<Icon name="folder-closed" size="lg" aria-hidden={true} />}
+                  >
+                    Q4 Planning
+                  </CardTile>
+                  <NewCardTile variant="icon" label="New" />
+                </CardTileGrid>
+              </div>
+            </ComponentCard>
+
             {/* FormField */}
             <ComponentCard
               name="FormField"
@@ -1998,11 +2352,186 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               />
             </ComponentCard>
 
+            {/* ThreeColumnLayout */}
+            <ComponentCard
+              name="ThreeColumnLayout"
+              importLine="import { ThreeColumnLayout } from '@sovereignfs/ui';"
+              usage="Sidebar + main + optional detail column, for list-app shells (Tasks, Shopper). Purely positional — pass 2 children for sidebar+main, or 3 for sidebar+main+detail; the third is simply omitted when nothing is selected."
+            >
+              <div style={{ width: '100%', height: '220px' }}>
+                <ThreeColumnLayout sidebarWidth={120} detailWidth={140}>
+                  <div
+                    style={{
+                      padding: 'var(--sv-space-3)',
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Sidebar
+                  </div>
+                  <div
+                    style={{
+                      padding: 'var(--sv-space-3)',
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Main
+                  </div>
+                  <div
+                    style={{
+                      padding: 'var(--sv-space-3)',
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Detail
+                  </div>
+                </ThreeColumnLayout>
+              </div>
+            </ComponentCard>
+
+            {/* HeaderFooterLayout */}
+            <ComponentCard
+              name="HeaderFooterLayout"
+              importLine="import { HeaderFooterLayout } from '@sovereignfs/ui';"
+              usage="Header + main + optional footer, both fixed-height and independently optional; main always claims the remaining height. The vertical counterpart to ThreeColumnLayout."
+            >
+              <div style={{ width: '100%', height: '220px' }}>
+                <HeaderFooterLayout
+                  headerHeight={36}
+                  footerHeight={36}
+                  header={
+                    <div
+                      style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        height: '100%',
+                        fontFamily: ffm,
+                        fontSize: 'var(--sv-font-size-xs)',
+                        color: 'var(--sv-color-text-primary)',
+                      }}
+                    >
+                      Header
+                    </div>
+                  }
+                  footer={
+                    <div
+                      style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        height: '100%',
+                        fontFamily: ffm,
+                        fontSize: 'var(--sv-font-size-xs)',
+                        color: 'var(--sv-color-text-primary)',
+                      }}
+                    >
+                      Footer
+                    </div>
+                  }
+                >
+                  <div
+                    style={{
+                      padding: 'var(--sv-space-3)',
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Main (scrolls)
+                  </div>
+                </HeaderFooterLayout>
+              </div>
+            </ComponentCard>
+
+            {/* RootLayout */}
+            <ComponentCard
+              name="RootLayout"
+              importLine="import { RootLayout } from '@sovereignfs/ui';"
+              usage="The root-level layout a plugin's page tree sits in. variant='sidebar' is web-only (sidebar + main); variant='shell' is mobile-only (header + main + footer) — same children, different fork per breakpoint via ResponsiveSurface. Shown here: variant='header', identical on both breakpoints."
+            >
+              <div style={{ width: '100%', height: '160px' }}>
+                <RootLayout variant="header" headerHeight={32}>
+                  <div
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      height: '100%',
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Header
+                  </div>
+                  <div
+                    style={{
+                      padding: 'var(--sv-space-3)',
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Main
+                  </div>
+                </RootLayout>
+              </div>
+            </ComponentCard>
+
+            {/* PageLayout */}
+            <ComponentCard
+              name="PageLayout"
+              importLine="import { PageLayout } from '@sovereignfs/ui';"
+              usage="A single page's content area, nested inside RootLayout's main slot. No padding by default (opt in via padding, same scale as PageContainer). The optional header is page-specific — a board title/toolbar, not the app-level header."
+            >
+              <div
+                style={{
+                  width: '100%',
+                  height: '160px',
+                  border: '1px solid var(--sv-color-border)',
+                }}
+              >
+                <PageLayout
+                  padding="sm"
+                  header={
+                    <div
+                      style={{
+                        padding: 'var(--sv-space-2) var(--sv-space-3)',
+                        borderBottom: '1px solid var(--sv-color-border)',
+                        fontFamily: ffm,
+                        fontSize: 'var(--sv-font-size-xs)',
+                        fontWeight: 600,
+                        color: 'var(--sv-color-text-primary)',
+                      }}
+                    >
+                      Page header
+                    </div>
+                  }
+                >
+                  <div
+                    style={{
+                      fontFamily: ffm,
+                      fontSize: 'var(--sv-font-size-xs)',
+                      color: 'var(--sv-color-text-primary)',
+                    }}
+                  >
+                    Page content
+                  </div>
+                </PageLayout>
+              </div>
+            </ComponentCard>
+
             {/* PageHeader */}
             <ComponentCard
               name="PageHeader"
               importLine="import { PageHeader } from '@sovereignfs/ui';"
-              usage="Plugin page top section. Title + optional description + right-side action slot. Replaces the hand-rolled .pageHeader pattern in every plugin."
+              usage="Plugin page top section. Title + optional description + right-side action slot. Replaces the hand-rolled .pageHeader pattern in every plugin. An optional `icon` renders before the title text on both breakpoints. On mobile, description drops out and onBack/onMenuClick add an optional back button and vertical-ellipsis menu trigger."
             >
               <div style={{ width: '100%' }}>
                 <PageHeader
@@ -2013,6 +2542,223 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* PageContainer */}
+            <ComponentCard
+              name="PageContainer"
+              importLine="import { PageContainer } from '@sovereignfs/ui';"
+              usage="The wrapper every plugin page renders through. Supplies the page gutter (padding: none/sm/md/lg, default md — the runtime shell no longer pads plugin content) and constrains width (maxWidth: sm/md/lg/full, default full). Use instead of declaring padding or max-width in a plugin's own CSS."
+            >
+              <div style={{ width: '100%', background: 'var(--sv-color-surface-sunken)' }}>
+                <PageContainer maxWidth="sm" padding="md">
+                  <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; padding=&quot;md&quot;
+                  </div>
+                </PageContainer>
+              </div>
+            </ComponentCard>
+
+            {/* Header */}
+            <ComponentCard
+              name="Header"
+              importLine="import { Header } from '@sovereignfs/ui';"
+              usage="The web top-bar header for shell: minimal plugins that own their whole viewport (no platform sidebar). Brand badge + optional active plugin on the left; launcher (AppsLauncher), notifications (NotificationsPanel), and avatarMenu (UserMenu) on the right — all real, shared, independently clickable components. Presentational only — see Components/Header for the mobile counterpart (MobileHeader) shown side by side."
+            >
+              <Header
+                instanceName="Sovereign"
+                homeHref="/launcher"
+                plugin={{
+                  // The plugin icon is 28px — the same size as the brand
+                  // badge next to it, not a smaller inline glyph.
+                  name: 'Notes',
+                  icon: (
+                    <span
+                      aria-hidden="true"
+                      style={{
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        width: 28,
+                        height: 28,
+                      }}
+                    >
+                      <span style={{ display: 'inline-flex', transform: 'scale(1.15)' }}>
+                        <Icon name="file" size="lg" aria-hidden />
+                      </span>
+                    </span>
+                  ),
+                  href: '/notes',
+                }}
+                launcher={
+                  <AppsLauncher
+                    items={[
+                      {
+                        key: 'home',
+                        icon: <Icon name="house" size="md" aria-hidden />,
+                        label: 'Home',
+                        href: '/launcher',
+                      },
+                      {
+                        key: 'notes',
+                        icon: <Icon name="file" size="md" aria-hidden />,
+                        label: 'Notes',
+                        href: '/notes',
+                      },
+                    ]}
+                  />
+                }
+                notifications={<NotificationsPanel items={[]} unreadCount={0} />}
+                avatarMenu={
+                  <UserMenu
+                    name="Kasun Benthara"
+                    email="kasun@openfs.io"
+                    items={[
+                      { label: 'Account', icon: 'user', href: '/account' },
+                      { label: 'Sign out', icon: 'log-out', destructive: true, onSelect: () => {} },
+                    ]}
+                    size="sm"
+                  />
+                }
+              />
+            </ComponentCard>
+
+            {/* AppsLauncher */}
+            <ComponentCard
+              name="AppsLauncher"
+              importLine="import { AppsLauncher } from '@sovereignfs/ui';"
+              usage="The desktop 'Apps' switcher — a 28px grid trigger opening a Popover tile grid. The desktop counterpart to MobileAppsDrawer: same items shape (key/icon/label/href/onClick), different chrome. Presentational only — items are supplied already resolved; loading/error are separate props."
+            >
+              <AppsLauncher
+                items={[
+                  {
+                    key: 'home',
+                    icon: <Icon name="house" size="md" aria-hidden />,
+                    label: 'Home',
+                    href: '/launcher',
+                  },
+                  {
+                    key: 'console',
+                    icon: <Icon name="layout-dashboard" size="md" aria-hidden />,
+                    label: 'Console',
+                    href: '/console',
+                  },
+                  {
+                    key: 'notes',
+                    icon: <Icon name="file" size="md" aria-hidden />,
+                    label: 'Notes',
+                    href: '/notes',
+                  },
+                ]}
+              />
+            </ComponentCard>
+
+            {/* NotificationsPanel */}
+            <ComponentCard
+              name="NotificationsPanel"
+              importLine="import { NotificationsPanel } from '@sovereignfs/ui';"
+              usage="The bell trigger + dropdown, generalized from the runtime shell's own NotificationBell — title/Mark all read/Clear all/close, then category-icon + title + time + unread-dot + dismiss rows. Pure presentation: no fetch/SSE/mark-read logic of its own; the consumer supplies already-resolved items and wires onOpen/onDismiss/onMarkAllRead/onClearAll."
+            >
+              <NotificationsPanel
+                items={[
+                  {
+                    id: '1',
+                    icon: <Icon name="layers" size="sm" aria-hidden />,
+                    title: 'Added to a project',
+                    timeLabel: '2d ago',
+                    read: false,
+                    onDismiss: () => {},
+                  },
+                ]}
+                unreadCount={1}
+                onMarkAllRead={() => {}}
+                onClearAll={() => {}}
+              />
+            </ComponentCard>
+
+            {/* UserMenu */}
+            <ComponentCard
+              name="UserMenu"
+              importLine="import { UserMenu } from '@sovereignfs/ui';"
+              usage="The account avatar trigger + dropdown, generalized from the runtime shell's own AccountMenu — accent-filled avatar, a name/email header block, then a plain item list. Presentational only: no auth/session logic — items carry their own onSelect and/or href (e.g. a real 'Sign out' item just does whatever the consuming app's sign-out requires)."
+            >
+              <UserMenu
+                name="Kasun Benthara"
+                email="kasun@openfs.io"
+                items={[
+                  { label: 'Account', icon: 'user', href: '/account' },
+                  {
+                    label: 'Preferences',
+                    icon: 'sliders-horizontal',
+                    href: '/account/preferences',
+                  },
+                  { label: 'Sign out', icon: 'log-out', destructive: true, onSelect: () => {} },
+                ]}
+              />
+            </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"
@@ -2031,6 +2777,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"
@@ -2076,6 +2869,42 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* NavList */}
+            <ComponentCard
+              name="NavList"
+              importLine="import { NavList } from '@sovereignfs/ui';"
+              usage='Vertical list of icon+label rows, optionally grouped under section headers. static: active row highlighted, no chevron — a persistent sidebar. drilldown: trailing chevron on every row, no active state — a native-Settings-app style index. density="compact" (static only) shrinks row height for a short, always-visible list. Framework-agnostic like NavTabs; supply active/renderLink from the consumer.'
+            >
+              <div style={{ width: '100%', maxWidth: 220 }}>
+                <NavList
+                  variant="static"
+                  aria-label="Example sections"
+                  groups={[
+                    {
+                      id: 'overview',
+                      items: [
+                        {
+                          id: 'overview',
+                          label: 'Overview',
+                          href: '#',
+                          icon: 'layout-dashboard',
+                          active: true,
+                        },
+                      ],
+                    },
+                    {
+                      id: 'people',
+                      label: 'People',
+                      items: [
+                        { id: 'users', label: 'Users', href: '#', icon: 'users' },
+                        { id: 'groups', label: 'Groups', href: '#', icon: 'layers' },
+                      ],
+                    },
+                  ]}
+                />
+              </div>
+            </ComponentCard>
+
             {/* Tooltip */}
             <ComponentCard
               name="Tooltip"
@@ -2238,6 +3067,44 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               />
             </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>
+
+            {/* ConsentPrompt */}
+            <ComponentCard
+              name="ConsentPrompt"
+              importLine="import { ConsentPrompt } from '@sovereignfs/ui';"
+              usage="Consent screen shown before one plugin is allowed to read another plugin's data (RFC 0002 data grants) or connect to an external service on the user's behalf. description should come from the provider's own manifest declaration, never caller-supplied copy."
+            >
+              <ConsentPrompt
+                consumerName="Ledger"
+                providerName="Finance Tracker"
+                contract="expenses"
+                description="Monthly expense totals by category, no transaction-level detail."
+                onAllow={() => {}}
+                onDeny={() => {}}
+              />
+            </ComponentCard>
+
+            {/* Markdown */}
+            <ComponentCard
+              name="Markdown"
+              importLine="import { Markdown } from '@sovereignfs/ui';"
+              usage="Renders a constrained markdown subset (headings, paragraphs, bold/italic/code, links, ordered and unordered lists, fenced code blocks, blockquotes) as Typography-based React elements — no HTML string injection. Built for first-party long-form content and model-generated replies; still not a full CommonMark parser (no tables, images, or nested blocks)."
+            >
+              <Markdown
+                content={
+                  '## Heading\n\nA paragraph with **bold** and a [link](/privacy).\n\n- One\n- Two\n\n1. First\n2. Second\n\n```ts\nconst a = 1;\n```'
+                }
+              />
+            </ComponentCard>
+
             {/* Pagination */}
             <ComponentCard
               name="Pagination"
@@ -2668,6 +3535,26 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* GripIcon */}
+            <ComponentCard
+              name="GripIcon"
+              importLine="import { GripIcon } from '@sovereignfs/ui';"
+              usage="Six-dot drag-handle icon, sized via `size` (default 14). No baked-in pointer-events or color — DragHandleRow uses it internally; a floating, absolutely-positioned handle can use it directly."
+            >
+              <div style={{ color: 'var(--sv-color-text-muted)' }}>
+                <GripIcon />
+              </div>
+            </ComponentCard>
+
+            {/* StepStrip */}
+            <ComponentCard
+              name="StepStrip"
+              importLine="import { StepStrip } from '@sovereignfs/ui';"
+              usage="Horizontal connected-chip strip (a route/itinerary sequence) with an optional trailing add chip. Purely presentational — renderItem owns each chip's content, click handling, and any drag-reorder wiring (attach dnd-kit's useSortable the same way DragHandleRow's handleProps expects it)."
+            >
+              <StepStripDemo />
+            </ComponentCard>
+
             {/* FileDropzone */}
             <ComponentCard
               name="FileDropzone"
@@ -2676,6 +3563,42 @@ 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>
+
+            {/* SwipeStack */}
+            <ComponentCard
+              name="SwipeStack"
+              importLine="import { SwipeStack, SwipeStackCard } from '@sovereignfs/ui';"
+              usage="Triage one card at a time by dragging left/right/up/down, plus an always-visible fallback button per configured direction wired to the identical commit path. Every direction is independently optional and has no baked-in meaning — the caller supplies label/icon and reacts to onSwipe; once triggered a direction removes the card for good, there is no reversible 'go back'."
+            >
+              <SwipeStackDemo />
+            </ComponentCard>
           </div>
         </section>
 
@@ -2789,6 +3712,10 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
                 <li>
                   Use <code style={{ fontFamily: ffm }}>--sv-shadow-*</code> for elevation
                 </li>
+                <li>
+                  Use <code style={{ fontFamily: ffm }}>--sv-border-width-hairline</code> instead of
+                  a literal border width (RFC 0094)
+                </li>
               </ul>
             </div>
             <div