@sovereignfs/ui 0.54.0 → 0.83.1

package/src/stories/DesignSystemOverview.stories.tsx

@@ -5,6 +5,7 @@ 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';
@@ -15,6 +16,7 @@ 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';
@@ -22,21 +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';
@@ -60,6 +73,7 @@ import {
 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';
@@ -87,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';
@@ -251,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' },
     ],
   },
   {
@@ -261,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:
@@ -390,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' },
@@ -398,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',
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -832,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 (
@@ -958,6 +1006,51 @@ 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
@@ -1052,6 +1145,48 @@ function SwipableMobileCarouselDotsDemo() {
   );
 }
 
+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[] = [
@@ -1077,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']
@@ -1728,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 74 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)' }}>
@@ -1766,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">
@@ -1779,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 */}
@@ -1854,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"
@@ -1927,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."
             >
               {(
                 [
@@ -2010,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"
@@ -2045,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 />
@@ -2066,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"
@@ -2144,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
@@ -2163,10 +2546,10 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             <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."
+              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">
+                <PageContainer maxWidth="sm" padding="md">
                   <div
                     style={{
                       background: 'var(--sv-color-surface-raised)',
@@ -2175,12 +2558,150 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
                       padding: 'var(--sv-space-4)',
                     }}
                   >
-                    maxWidth=&quot;sm&quot;
+                    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"
@@ -2348,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"
@@ -2519,15 +3076,31 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               <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, 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."
+              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'
+                  '## 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>
@@ -2962,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"
@@ -2997,6 +3590,15 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             >
               <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>
 
@@ -3110,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