From e08d2bd5e5758edba756a09e410064fffd3c1ce7 Mon Sep 17 00:00:00 2001
From: Amr Mohammed El-Sheraey <141947355+AmrMsCLL@users.noreply.github.com>
Date: Thu, 1 Oct 2026 23:13:27 +0300
Subject: [PATCH] feat: add the components Strata's foundation needs

Adds Tabs, TagChip with a fixed set of tag colours, Avatar with a presence dot, CodeInput for
one-time codes, Sidebar, and CommandPalette with a Ctrl+K and Cmd+K shortcut hook. AppShell
takes an optional sidebar that sits beside the page on wider screens. The search icon joins the
icon set, and the preview shows every new component.
---
 preview/main.tsx                  |  77 +++++++++-
 src/components/AppShell.tsx       |  17 ++-
 src/components/Avatar.tsx         |  16 ++
 src/components/CodeInput.tsx      |  25 ++++
 src/components/CommandPalette.tsx | 161 ++++++++++++++++++++
 src/components/Icon.tsx           |   1 +
 src/components/Sidebar.tsx        |  50 +++++++
 src/components/Tabs.tsx           |  25 ++++
 src/components/TagChip.tsx        |  41 ++++++
 src/index.ts                      |  11 ++
 src/theme.css                     | 236 ++++++++++++++++++++++++++++++
 test/workspace.spec.tsx           | 174 ++++++++++++++++++++++
 12 files changed, 829 insertions(+), 5 deletions(-)
 create mode 100644 src/components/Avatar.tsx
 create mode 100644 src/components/CodeInput.tsx
 create mode 100644 src/components/CommandPalette.tsx
 create mode 100644 src/components/Sidebar.tsx
 create mode 100644 src/components/Tabs.tsx
 create mode 100644 src/components/TagChip.tsx
 create mode 100644 test/workspace.spec.tsx

diff --git a/preview/main.tsx b/preview/main.tsx
index a37daa5..d92b33c 100644
--- a/preview/main.tsx
+++ b/preview/main.tsx
@@ -1,7 +1,10 @@
-import { StrictMode, useState, type ReactNode } from 'react';
+import { StrictMode, useCallback, useState, type ReactNode } from 'react';
 import { createRoot } from 'react-dom/client';
 import {
   AppShell,
+  Avatar,
+  CodeInput,
+  CommandPalette,
   ConfirmDialog,
   Dialog,
   EmptyState,
@@ -14,13 +17,19 @@ import {
   OutageGate,
   Pagination,
   Popover,
+  Sidebar,
   SmoothImage,
   SnackbarProvider,
+  Tabs,
+  TagChip,
+  tagColors,
   TextAreaField,
   TextField,
   Toggle,
   timeAgo,
+  useCommandShortcut,
   useSnackbar,
+  type CommandItem,
   type IconName,
 } from '../src/index.ts';
 import './styles.css';
@@ -38,7 +47,13 @@ const colors = [
   ['wip', 'bg-wip'],
   ['dormant', 'bg-dormant'],
 ];
-const icons: IconName[] = ['bell', 'compass', 'filter', 'gamepad', 'home', 'library', 'user'];
+const icons: IconName[] = ['bell', 'compass', 'filter', 'gamepad', 'home', 'library', 'search', 'user'];
+const commands: CommandItem[] = [
+  { group: 'Go to', href: '#workspace', id: 'notes', label: 'Notes', hint: 'g n' },
+  { group: 'Go to', href: '#workspace', id: 'agenda', label: 'Agenda', hint: 'g a' },
+  { group: 'Actions', id: 'task', label: 'New task', onSelect: () => {} },
+  { group: 'Actions', id: 'note', label: 'New note', onSelect: () => {} },
+];
 const outageListeners = new Set<() => void>();
 
 function Section({ children, title }: { children: ReactNode; title: string }) {
@@ -65,6 +80,10 @@ function SnackbarDemo() {
 
 function Preview() {
   const [dialog, setDialog] = useState<'plain' | 'confirm' | null>(null);
+  const [palette, setPalette] = useState(false);
+  const [query, setQuery] = useState('');
+  const openPalette = useCallback(() => setPalette(true), []);
+  useCommandShortcut(openPalette);
   const [checked, setChecked] = useState(true);
   const [page, setPage] = useState(3);
 
@@ -240,6 +259,60 @@ function Preview() {
         )}
       </Section>
 
+      <Section title="Workspace">
+        <Tabs
+          items={[
+            { active: true, href: '#workspace', label: 'Profile' },
+            { active: false, href: '#workspace', label: 'Security' },
+            { active: false, href: '#workspace', label: 'Sessions' },
+          ]}
+          label="Settings"
+        />
+        <div className="chip-row">
+          {tagColors.map((color) => (
+            <TagChip color={color} key={color} label={color} />
+          ))}
+          <TagChip color="blue" href="#workspace" label="linked" />
+          <TagChip color="green" label="removable" onRemove={() => {}} />
+        </div>
+        <div className="flex items-center gap-3">
+          <Avatar name="Amr" present />
+          <Avatar name="Sam" />
+          <Avatar name="Lee" present size="sm" />
+        </div>
+        <div className="max-w-xs">
+          <CodeInput hint="From your authenticator app." label="Six-digit code" name="code" />
+        </div>
+        <div className="h-72 max-w-60 overflow-hidden rounded-xl border border-line">
+          <Sidebar
+            label="Areas"
+            sections={[
+              {
+                items: [
+                  { active: true, href: '#workspace', icon: 'home', label: 'Home' },
+                  { active: false, badge: 4, href: '#workspace', icon: 'bell', label: 'Inbox' },
+                ],
+              },
+              { label: 'spaces', items: [{ active: false, href: '#workspace', label: 'Friends trip' }] },
+            ]}
+          />
+        </div>
+        <button className="secondary-button inline-flex w-fit" onClick={openPalette} type="button">
+          Open command palette (Ctrl+K)
+        </button>
+        {palette && (
+          <CommandPalette
+            items={commands.filter((command) => command.label.toLowerCase().includes(query.toLowerCase()))}
+            onClose={() => {
+              setPalette(false);
+              setQuery('');
+            }}
+            onQueryChange={setQuery}
+            query={query}
+          />
+        )}
+      </Section>
+
       <Section title="Snackbar">
         <SnackbarDemo />
       </Section>
diff --git a/src/components/AppShell.tsx b/src/components/AppShell.tsx
index d0680d8..0a0cd6e 100644
--- a/src/components/AppShell.tsx
+++ b/src/components/AppShell.tsx
@@ -21,6 +21,7 @@ export function AppShell({
   children,
   footer,
   nav,
+  sidebar,
   tabs,
 }: {
   actions?: ReactNode;
@@ -29,6 +30,7 @@ export function AppShell({
   children: ReactNode;
   footer?: ReactNode;
   nav: ShellNavItem[];
+  sidebar?: ReactNode;
   tabs: ShellTab[];
 }) {
   const Link = useLink();
@@ -62,9 +64,18 @@ export function AppShell({
         </div>
         {alert}
       </header>
-      <main className="shell flex-1 py-8 sm:py-14" id="content">
-        {children}
-      </main>
+      {sidebar ? (
+        <div className="flex flex-1">
+          <aside className="sidebar-panel hidden md:block">{sidebar}</aside>
+          <main className="shell min-w-0 flex-1 py-8 sm:py-14" id="content">
+            {children}
+          </main>
+        </div>
+      ) : (
+        <main className="shell flex-1 py-8 sm:py-14" id="content">
+          {children}
+        </main>
+      )}
       {footer}
       <nav aria-label="Main" className="tab-bar md:hidden" style={{ '--tab-count': tabs.length } as CSSProperties}>
         {tabs.map((tab) =>
diff --git a/src/components/Avatar.tsx b/src/components/Avatar.tsx
new file mode 100644
index 0000000..c2fdc85
--- /dev/null
+++ b/src/components/Avatar.tsx
@@ -0,0 +1,16 @@
+export function Avatar({
+  name,
+  present,
+  size = 'md',
+}: {
+  name: string;
+  present?: boolean;
+  size?: 'sm' | 'md';
+}) {
+  return (
+    <span aria-label={present ? `${name}, here now` : name} className={`avatar avatar-${size}`} role="img">
+      <span aria-hidden="true">{name.trim().charAt(0).toUpperCase()}</span>
+      {present && <span aria-hidden="true" className="presence-dot" />}
+    </span>
+  );
+}
diff --git a/src/components/CodeInput.tsx b/src/components/CodeInput.tsx
new file mode 100644
index 0000000..f4cad80
--- /dev/null
+++ b/src/components/CodeInput.tsx
@@ -0,0 +1,25 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+import { TextField } from './Field.js';
+
+export function CodeInput({
+  length = 6,
+  ...props
+}: Omit<InputHTMLAttributes<HTMLInputElement>, 'maxLength' | 'pattern' | 'type'> & {
+  error?: string;
+  hint?: ReactNode;
+  label: ReactNode;
+  length?: number;
+}) {
+  return (
+    <TextField
+      autoComplete="one-time-code"
+      className="code-input"
+      inputMode="numeric"
+      maxLength={length}
+      pattern={`\\d{${length}}`}
+      spellCheck={false}
+      type="text"
+      {...props}
+    />
+  );
+}
diff --git a/src/components/CommandPalette.tsx b/src/components/CommandPalette.tsx
new file mode 100644
index 0000000..f8398f2
--- /dev/null
+++ b/src/components/CommandPalette.tsx
@@ -0,0 +1,161 @@
+import { useEffect, useId, useRef, useState, type KeyboardEvent } from 'react';
+import { useLink } from '../UiProvider.js';
+import { Icon } from './Icon.js';
+
+export interface Command {
+  group: string;
+  hint?: string;
+  id: string;
+  label: string;
+}
+
+export type CommandItem = Command & ({ href: string } | { onSelect: () => void });
+
+export function useCommandShortcut(open: () => void) {
+  useEffect(() => {
+    const listen = (event: globalThis.KeyboardEvent) => {
+      if (event.key.toLowerCase() === 'k' && (event.ctrlKey || event.metaKey)) {
+        event.preventDefault();
+        open();
+      }
+    };
+    document.addEventListener('keydown', listen);
+    return () => document.removeEventListener('keydown', listen);
+  }, [open]);
+}
+
+export function CommandPalette({
+  emptyLabel = 'Nothing matches',
+  items,
+  label = 'Search and commands',
+  onClose,
+  onQueryChange,
+  placeholder = 'Search or run a command',
+  query,
+}: {
+  emptyLabel?: string;
+  items: CommandItem[];
+  label?: string;
+  onClose: () => void;
+  onQueryChange: (query: string) => void;
+  placeholder?: string;
+  query: string;
+}) {
+  const Link = useLink();
+  const dialog = useRef<HTMLDialogElement>(null);
+  const listId = useId();
+  const [active, setActive] = useState(0);
+  const groups = [...new Set(items.map((item) => item.group))];
+  const ordered = groups.flatMap((group) => items.filter((item) => item.group === group));
+  const activeItem = ordered[Math.min(active, ordered.length - 1)];
+  const optionId = (item: CommandItem) => `${listId}-${item.id}`;
+
+  useEffect(() => {
+    const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    dialog.current?.showModal();
+    return () => opener?.focus();
+  }, []);
+
+  useEffect(() => setActive(0), [query]);
+
+  useEffect(() => {
+    document.getElementById(`${listId}-${activeItem?.id}`)?.scrollIntoView?.({ block: 'nearest' });
+  }, [activeItem?.id, listId]);
+
+  function move(event: KeyboardEvent<HTMLInputElement>) {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      if (ordered.length === 0) return;
+      const step = event.key === 'ArrowDown' ? 1 : -1;
+      setActive((current) => (Math.min(current, ordered.length - 1) + step + ordered.length) % ordered.length);
+    } else if (event.key === 'Enter' && activeItem) {
+      event.preventDefault();
+      document.getElementById(optionId(activeItem))?.click();
+    }
+  }
+
+  return (
+    <dialog
+      aria-label={label}
+      className="command-palette"
+      onCancel={(event) => {
+        event.preventDefault();
+        onClose();
+      }}
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+      ref={dialog}
+    >
+      <div className="flex items-center gap-3 border-b border-line px-4">
+        <span className="text-faint">
+          <Icon name="search" size={18} />
+        </span>
+        <input
+          aria-activedescendant={activeItem ? optionId(activeItem) : undefined}
+          aria-autocomplete="list"
+          aria-controls={listId}
+          aria-expanded="true"
+          aria-label={label}
+          autoFocus
+          className="command-input"
+          onChange={(event) => onQueryChange(event.target.value)}
+          onKeyDown={move}
+          placeholder={placeholder}
+          role="combobox"
+          type="text"
+          value={query}
+        />
+        <kbd className="mono-sm text-faint">esc</kbd>
+      </div>
+      <div className="command-list" id={listId} role="listbox">
+        {ordered.length === 0 ? (
+          <p className="m-0 px-4 py-6 text-center text-sm text-muted">{emptyLabel}</p>
+        ) : (
+          groups.map((group) => (
+            <div aria-label={group} className="py-1.5" key={group} role="group">
+              <p aria-hidden="true" className="eyebrow m-0 px-4 py-1.5">
+                {group}
+              </p>
+              {ordered
+                .filter((item) => item.group === group)
+                .map((item) => {
+                  const props = {
+                    'aria-selected': item === activeItem,
+                    className: 'command-option',
+                    id: optionId(item),
+                    onMouseMove: () => setActive(ordered.indexOf(item)),
+                    role: 'option',
+                    tabIndex: -1,
+                  };
+                  const content = (
+                    <>
+                      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+                      {item.hint && <span className="mono-sm shrink-0 text-faint">{item.hint}</span>}
+                    </>
+                  );
+                  return 'href' in item ? (
+                    <Link {...props} href={item.href} key={item.id} onClick={onClose}>
+                      {content}
+                    </Link>
+                  ) : (
+                    <button
+                      {...props}
+                      key={item.id}
+                      onClick={() => {
+                        onClose();
+                        item.onSelect();
+                      }}
+                      type="button"
+                    >
+                      {content}
+                    </button>
+                  );
+                })}
+            </div>
+          ))
+        )}
+      </div>
+    </dialog>
+  );
+}
diff --git a/src/components/Icon.tsx b/src/components/Icon.tsx
index 1882e49..14e7b19 100644
--- a/src/components/Icon.tsx
+++ b/src/components/Icon.tsx
@@ -6,6 +6,7 @@ const paths = {
     'M6 11h4M8 9v4M15 12h.01M18 10h.01M17.3 5H6.7a4 4 0 0 0-3.96 3.43l-.73 5.12A2.8 2.8 0 0 0 4.8 16.8c.9 0 1.7-.5 2.1-1.3L8 14h8l1.1 1.5c.4.8 1.2 1.3 2.1 1.3a2.8 2.8 0 0 0 2.79-3.25l-.73-5.12A4 4 0 0 0 17.3 5z',
   home: 'M3 10.5 12 3l9 7.5V20a1 1 0 0 1-1 1h-5v-6h-6v6H4a1 1 0 0 1-1-1z',
   library: 'M5 4h3v16H5zM10 4h3v16h-3zM15.2 4.6l2.9-.8 3.5 15.6-2.9.8z',
+  search: 'M21 21l-4.35-4.35M11 19a8 8 0 1 0 0-16 8 8 0 0 0 0 16z',
   user: 'M20 21a8 8 0 0 0-16 0M12 13a5 5 0 1 0 0-10 5 5 0 0 0 0 10z',
 };
 
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
new file mode 100644
index 0000000..7636a9a
--- /dev/null
+++ b/src/components/Sidebar.tsx
@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+import { useLink } from '../UiProvider.js';
+import { Icon, type IconName } from './Icon.js';
+
+export interface SidebarItem {
+  active: boolean;
+  badge?: number;
+  href: string;
+  icon?: IconName;
+  label: string;
+}
+
+export interface SidebarSection {
+  items: SidebarItem[];
+  label?: string;
+}
+
+export function Sidebar({
+  footer,
+  label,
+  sections,
+}: {
+  footer?: ReactNode;
+  label: string;
+  sections: SidebarSection[];
+}) {
+  const Link = useLink();
+  return (
+    <nav aria-label={label} className="sidebar">
+      {sections.map((section, index) => (
+        <div className="grid gap-0.5" key={section.label ?? index}>
+          {section.label && <p className="eyebrow m-0 px-3 pb-1.5">{section.label}</p>}
+          {section.items.map((item) => (
+            <Link
+              aria-current={item.active ? 'page' : undefined}
+              className="sidebar-item"
+              href={item.href}
+              key={item.href}
+            >
+              {item.icon && <Icon name={item.icon} size={18} />}
+              <span className="min-w-0 flex-1 truncate">{item.label}</span>
+              {item.badge ? <span className="mono-sm text-faint">{item.badge > 99 ? '99+' : item.badge}</span> : null}
+            </Link>
+          ))}
+        </div>
+      ))}
+      {footer && <div className="mt-auto">{footer}</div>}
+    </nav>
+  );
+}
diff --git a/src/components/Tabs.tsx b/src/components/Tabs.tsx
new file mode 100644
index 0000000..8e38b7c
--- /dev/null
+++ b/src/components/Tabs.tsx
@@ -0,0 +1,25 @@
+import { useLink } from '../UiProvider.js';
+
+export interface TabItem {
+  active: boolean;
+  href: string;
+  label: string;
+}
+
+export function Tabs({ items, label }: { items: TabItem[]; label: string }) {
+  const Link = useLink();
+  return (
+    <nav aria-label={label} className="scroll-x flex gap-2 border-b border-line">
+      {items.map((item) => (
+        <Link
+          aria-current={item.active ? 'page' : undefined}
+          className="tab-link -mb-px"
+          href={item.href}
+          key={item.href}
+        >
+          {item.label}
+        </Link>
+      ))}
+    </nav>
+  );
+}
diff --git a/src/components/TagChip.tsx b/src/components/TagChip.tsx
new file mode 100644
index 0000000..bf575fc
--- /dev/null
+++ b/src/components/TagChip.tsx
@@ -0,0 +1,41 @@
+import { useLink } from '../UiProvider.js';
+
+export const tagColors = ['gray', 'red', 'orange', 'yellow', 'green', 'teal', 'blue', 'purple', 'pink'] as const;
+
+export type TagColor = (typeof tagColors)[number];
+
+export function TagChip({
+  color = 'gray',
+  href,
+  label,
+  onRemove,
+}: {
+  color?: TagColor;
+  href?: string;
+  label: string;
+  onRemove?: () => void;
+}) {
+  const Link = useLink();
+  const content = (
+    <>
+      <span aria-hidden="true" className="tag-dot" />
+      {label}
+    </>
+  );
+  return (
+    <span className={`tag-chip tag-${color}`}>
+      {href ? (
+        <Link className="tag-chip-label" href={href}>
+          {content}
+        </Link>
+      ) : (
+        <span className="tag-chip-label">{content}</span>
+      )}
+      {onRemove && (
+        <button aria-label={`Remove ${label}`} className="tag-chip-remove" onClick={onRemove} type="button">
+          ×
+        </button>
+      )}
+    </span>
+  );
+}
diff --git a/src/index.ts b/src/index.ts
index 55a258a..26f88bc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,12 @@
 export { AppShell, type ShellNavItem, type ShellTab } from './components/AppShell.js';
+export { Avatar } from './components/Avatar.js';
+export { CodeInput } from './components/CodeInput.js';
+export {
+  CommandPalette,
+  useCommandShortcut,
+  type Command,
+  type CommandItem,
+} from './components/CommandPalette.js';
 export { ConfirmDialog } from './components/ConfirmDialog.js';
 export { Dialog } from './components/Dialog.js';
 export { EmptyState } from './components/EmptyState.js';
@@ -9,6 +17,7 @@ export { Menu, type MenuItem } from './components/Menu.js';
 export { OutageGate } from './components/OutageGate.js';
 export { Pagination } from './components/Pagination.js';
 export { Popover } from './components/Popover.js';
+export { Sidebar, type SidebarItem, type SidebarSection } from './components/Sidebar.js';
 export {
   actionSkeletonClass,
   FormPanelSkeleton,
@@ -22,6 +31,8 @@ export {
 } from './components/Skeleton.js';
 export { SmoothImage } from './components/SmoothImage.js';
 export { SnackbarProvider, useSnackbar } from './components/Snackbar.js';
+export { Tabs, type TabItem } from './components/Tabs.js';
+export { TagChip, tagColors, type TagColor } from './components/TagChip.js';
 export { Toggle } from './components/Toggle.js';
 export { errorMessage, isAbortError } from './lib/errors.js';
 export { timeAgo } from './lib/timeAgo.js';
diff --git a/src/theme.css b/src/theme.css
index de59958..04f7230 100644
--- a/src/theme.css
+++ b/src/theme.css
@@ -782,6 +782,242 @@ body {
     border-radius: 0.375rem;
     background: var(--color-line-soft);
   }
+
+  .tag-chip {
+    display: inline-flex;
+    align-items: center;
+    border: 1px solid color-mix(in srgb, var(--tag-color) 35%, var(--color-line));
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--tag-color) 12%, transparent);
+    color: var(--color-ink);
+    font-size: 0.78rem;
+    line-height: 1.5;
+  }
+
+  .tag-chip-label {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.1rem 0.6rem;
+    color: inherit;
+    text-decoration: none;
+  }
+
+  a.tag-chip-label:hover {
+    color: #fff;
+  }
+
+  .tag-chip:has(.tag-chip-remove) .tag-chip-label {
+    padding-right: 0.25rem;
+  }
+
+  .tag-dot {
+    width: 0.45rem;
+    height: 0.45rem;
+    flex: none;
+    border-radius: 999px;
+    background: var(--tag-color);
+  }
+
+  .tag-chip-remove {
+    border: 0;
+    background: transparent;
+    padding: 0 0.5rem 0 0.15rem;
+    color: var(--color-muted);
+    line-height: 1;
+  }
+
+  .tag-chip-remove:hover {
+    color: var(--color-ink);
+  }
+
+  .tag-gray {
+    --tag-color: #8b8b95;
+  }
+
+  .tag-red {
+    --tag-color: #e5736b;
+  }
+
+  .tag-orange {
+    --tag-color: #e0915a;
+  }
+
+  .tag-yellow {
+    --tag-color: #d7b24a;
+  }
+
+  .tag-green {
+    --tag-color: #5fbf7f;
+  }
+
+  .tag-teal {
+    --tag-color: #4fb8b0;
+  }
+
+  .tag-blue {
+    --tag-color: #6a9eea;
+  }
+
+  .tag-purple {
+    --tag-color: #a388e8;
+  }
+
+  .tag-pink {
+    --tag-color: #e07fb5;
+  }
+
+  .avatar {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    border: 1px solid var(--color-line);
+    border-radius: 999px;
+    background: var(--color-line-soft);
+    color: var(--color-ink);
+    font-weight: 620;
+  }
+
+  .avatar-sm {
+    width: 1.75rem;
+    height: 1.75rem;
+    font-size: 0.75rem;
+  }
+
+  .avatar-md {
+    width: 2.25rem;
+    height: 2.25rem;
+    font-size: 0.9rem;
+  }
+
+  .presence-dot {
+    position: absolute;
+    right: -0.1rem;
+    bottom: -0.1rem;
+    width: 0.65rem;
+    height: 0.65rem;
+    border: 2px solid var(--color-paper);
+    border-radius: 999px;
+    background: var(--color-live);
+  }
+
+  .code-input input {
+    font-family: var(--font-mono);
+    font-size: 1.25rem;
+    letter-spacing: 0.4em;
+  }
+
+  .sidebar-panel {
+    position: sticky;
+    top: var(--header-height);
+    width: 15rem;
+    height: calc(100dvh - var(--header-height));
+    flex: none;
+    overflow-y: auto;
+    border-right: 1px solid var(--color-line-soft);
+  }
+
+  .sidebar {
+    display: flex;
+    min-height: 100%;
+    flex-direction: column;
+    gap: 1.25rem;
+    padding: 1.25rem 0.75rem;
+  }
+
+  .sidebar-item {
+    display: flex;
+    align-items: center;
+    gap: 0.65rem;
+    border-radius: var(--radius-field);
+    padding: 0.45rem 0.75rem;
+    color: var(--color-muted);
+    font-size: 0.9rem;
+    text-decoration: none;
+    transition:
+      background-color 140ms ease,
+      color 140ms ease;
+  }
+
+  .sidebar-item:hover {
+    background: var(--color-line-soft);
+    color: var(--color-ink);
+  }
+
+  .sidebar-item[aria-current='page'] {
+    background: var(--color-line-soft);
+    color: var(--color-ink);
+  }
+
+  .command-palette {
+    width: min(100% - 2rem, 36rem);
+    max-height: min(32rem, calc(100dvh - 4rem));
+    margin: 12dvh auto auto;
+    overflow: hidden;
+    border: 1px solid var(--color-line);
+    border-radius: var(--radius-card);
+    background: var(--color-surface);
+    padding: 0;
+    color: var(--color-ink);
+    box-shadow: var(--shadow-popover);
+  }
+
+  .command-palette[open] {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .command-palette::backdrop {
+    background: color-mix(in srgb, var(--color-paper) 80%, transparent);
+  }
+
+  input.command-input {
+    border: 0;
+    background: transparent;
+    padding: 1rem 0;
+  }
+
+  input.command-input:focus-visible {
+    outline: none;
+  }
+
+  .command-list {
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    padding-bottom: 0.4rem;
+  }
+
+  .command-option {
+    display: flex;
+    width: 100%;
+    align-items: center;
+    gap: 0.75rem;
+    border: 0;
+    background: transparent;
+    padding: 0.6rem 1rem;
+    color: var(--color-muted);
+    font-size: 0.9rem;
+    text-align: left;
+    text-decoration: none;
+  }
+
+  .command-option[aria-selected='true'] {
+    background: var(--color-line-soft);
+    color: var(--color-ink);
+  }
+
+  @media (max-width: 39.99rem) {
+    .command-palette {
+      width: 100%;
+      max-width: none;
+      max-height: 85dvh;
+      margin: auto 0 0;
+      border-radius: var(--radius-card) var(--radius-card) 0 0;
+      padding-bottom: env(safe-area-inset-bottom);
+    }
+  }
 }
 
 @media (prefers-reduced-motion: no-preference) {
diff --git a/test/workspace.spec.tsx b/test/workspace.spec.tsx
new file mode 100644
index 0000000..f54214b
--- /dev/null
+++ b/test/workspace.spec.tsx
@@ -0,0 +1,174 @@
+import { act } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  AppShell,
+  Avatar,
+  CodeInput,
+  CommandPalette,
+  Sidebar,
+  Tabs,
+  TagChip,
+  useCommandShortcut,
+  type CommandItem,
+} from '../src/index.ts';
+import { click, press, render } from './render.tsx';
+
+describe('Tabs', () => {
+  it('marks the current tab', async () => {
+    const { container } = await render(
+      <Tabs
+        items={[
+          { active: false, href: '/settings', label: 'Profile' },
+          { active: true, href: '/settings/security', label: 'Security' },
+        ]}
+        label="Settings"
+      />,
+    );
+
+    expect(container.querySelector('nav')?.getAttribute('aria-label')).toBe('Settings');
+    expect(container.querySelector('[aria-current="page"]')?.textContent).toBe('Security');
+  });
+});
+
+describe('TagChip', () => {
+  it('shows the colour and offers removal with a named button', async () => {
+    const onRemove = vi.fn();
+    const { container } = await render(<TagChip color="teal" label="Trip" onRemove={onRemove} />);
+
+    expect(container.querySelector('.tag-chip')?.classList.contains('tag-teal')).toBe(true);
+    await click(container.querySelector('button[aria-label="Remove Trip"]')!);
+    expect(onRemove).toHaveBeenCalledOnce();
+  });
+
+  it('links to a filter when given an href', async () => {
+    const { container } = await render(<TagChip href="/tags/trip" label="Trip" />);
+    expect(container.querySelector('a')?.getAttribute('href')).toBe('/tags/trip');
+  });
+});
+
+describe('Avatar', () => {
+  it('shows the initial and announces presence', async () => {
+    const { container } = await render(<Avatar name="amr" present />);
+
+    const avatar = container.querySelector('[role="img"]')!;
+    expect(avatar.textContent).toBe('A');
+    expect(avatar.getAttribute('aria-label')).toBe('amr, here now');
+    expect(avatar.querySelector('.presence-dot')).not.toBeNull();
+  });
+});
+
+describe('CodeInput', () => {
+  it('asks for a numeric one-time code of the given length', async () => {
+    const { container } = await render(<CodeInput label="Code" name="code" />);
+
+    const input = container.querySelector('input')!;
+    expect(input.getAttribute('autocomplete')).toBe('one-time-code');
+    expect(input.getAttribute('inputmode')).toBe('numeric');
+    expect(input.maxLength).toBe(6);
+    expect(input.getAttribute('pattern')).toBe('\\d{6}');
+  });
+});
+
+describe('Sidebar and AppShell', () => {
+  it('renders the sidebar beside the page with the current item marked', async () => {
+    const { container } = await render(
+      <AppShell
+        brand={{ href: '/', mark: null, name: 'Strata' }}
+        nav={[]}
+        sidebar={
+          <Sidebar
+            label="Areas"
+            sections={[
+              {
+                label: 'personal',
+                items: [
+                  { active: true, href: '/', icon: 'home', label: 'Home' },
+                  { active: false, badge: 120, href: '/inbox', icon: 'bell', label: 'Inbox' },
+                ],
+              },
+            ]}
+          />
+        }
+        tabs={[{ active: true, href: '/', icon: 'home', label: 'Home' }]}
+      >
+        <p>Page</p>
+      </AppShell>,
+    );
+
+    const sidebar = container.querySelector('aside nav[aria-label="Areas"]')!;
+    expect(sidebar.querySelector('[aria-current="page"]')?.textContent).toBe('Home');
+    expect(sidebar.textContent).toContain('99+');
+    expect(container.querySelector('aside + main#content')?.textContent).toBe('Page');
+  });
+});
+
+describe('CommandPalette', () => {
+  const items: CommandItem[] = [
+    { group: 'Go to', href: '/notes', id: 'notes', label: 'Notes' },
+    { group: 'Go to', href: '/agenda', id: 'agenda', label: 'Agenda' },
+    { group: 'Actions', id: 'new-task', label: 'New task', onSelect: vi.fn() },
+  ];
+
+  async function open(onClose = vi.fn(), list = items) {
+    const view = await render(
+      <CommandPalette items={list} onClose={onClose} onQueryChange={() => {}} query="" />,
+    );
+    const input = view.container.querySelector<HTMLInputElement>('input[role="combobox"]')!;
+    return { ...view, input, onClose };
+  }
+
+  it('opens as a modal with the first result active', async () => {
+    const { container, input } = await open();
+
+    expect(container.querySelector('dialog')?.open).toBe(true);
+    const active = document.getElementById(input.getAttribute('aria-activedescendant')!);
+    expect(active?.textContent).toBe('Notes');
+    expect(active?.getAttribute('aria-selected')).toBe('true');
+  });
+
+  it('moves through every group with the arrow keys and wraps', async () => {
+    const { input } = await open();
+    const activeLabel = () => document.getElementById(input.getAttribute('aria-activedescendant')!)?.textContent;
+
+    await press(input, 'ArrowDown');
+    expect(activeLabel()).toBe('Agenda');
+    await press(input, 'ArrowDown');
+    expect(activeLabel()).toBe('New task');
+    await press(input, 'ArrowDown');
+    expect(activeLabel()).toBe('Notes');
+    await press(input, 'ArrowUp');
+    expect(activeLabel()).toBe('New task');
+  });
+
+  it('runs the active action on Enter and closes', async () => {
+    const onSelect = vi.fn();
+    const { input, onClose } = await open(vi.fn(), [{ group: 'Actions', id: 'a', label: 'New note', onSelect }]);
+
+    await press(input, 'Enter');
+
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('says when nothing matches', async () => {
+    const { container } = await open(vi.fn(), []);
+    expect(container.querySelector('[role="listbox"]')?.textContent).toBe('Nothing matches');
+  });
+
+  it('opens from Ctrl+K or Cmd+K', async () => {
+    const onOpen = vi.fn();
+    function Shortcut() {
+      useCommandShortcut(onOpen);
+      return null;
+    }
+    await render(<Shortcut />);
+
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', ctrlKey: true }));
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'K', metaKey: true }));
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k' }));
+    });
+
+    expect(onOpen).toHaveBeenCalledTimes(2);
+  });
+});