diff --git a/.claude/plugins/kurrent-design-system/.claude-plugin/plugin.json b/.claude/plugins/kurrent-design-system/.claude-plugin/plugin.json
new file mode 100644
index 00000000..8312f3bc
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/.claude-plugin/plugin.json
@@ -0,0 +1,5 @@
+{
+  "name": "kurrent-design-system",
+  "version": "1.0.0",
+  "description": "Skill for building and aligning applications to the Kurrent Design System"
+}
diff --git a/.claude/plugins/kurrent-design-system/skills/kurrent-ds/SKILL.md b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/SKILL.md
new file mode 100644
index 00000000..6d417c6b
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: kurrent-ds
+description: This skill should be used when the user asks to "build a UI", "create a page", "add a form", "use Kurrent components", "align to Kurrent Design System", "migrate to Kurrent", "set up theming", "add a sidebar", "create a layout", "use design system components", "add icons", "replace hardcoded colors", or mentions Kurrent UI, @kurrent-ui packages, c2-/f2-/l2- components, or building web/desktop applications that should follow the Kurrent design language.
+---
+
+# Kurrent Design System
+
+Guidance for building and aligning web and desktop applications to the Kurrent Design System — a component library built on Stencil web components with comprehensive theming, form validation, layout primitives, and icon management.
+
+## Package Overview
+
+| Package | Scope | Purpose |
+|---------|-------|---------|
+| `@kurrent-ui/components` | Core UI | Buttons, tables, modals, tabs, toasts, icons, actions |
+| `@kurrent-ui/fields` | Form inputs | Text, select, checkbox, radio, number, textarea |
+| `@kurrent-ui/layout` | Page structure | Page shells, sidebars, headers, panels, breadcrumbs |
+| `@kurrent-ui/forms` | Form logic | Validated form state, working copy data stores |
+| `@kurrent-ui/theme` | Theming | Light/dark/high-contrast themes, CSS custom properties |
+| `@kurrent-ui/utils` | Utilities | Shared helpers and type utilities |
+| `@kurrent-ui/stores` | State | Stencil store primitives |
+| `@kurrent-ui/router` | Routing | Stencil router with URL state management |
+| `@kurrent-ui/editor` | Code editing | Monaco editor wrapper component |
+| `@kurrent-ui/assets` | Static assets | CSS utilities and asset files |
+
+## Component Naming Convention
+
+Components use **web component** custom element tags with version-namespaced prefixes:
+
+- **`c2-*`** — Core components (`c2-button`, `c2-icon`, `c2-tabs`, `c2-modal`)
+- **`f2-*`** — Field components with two levels:
+  - **Input level** (`f2-text-input`, `f2-select-input`, `f2-checkbox`) — raw interactive element, no label or validation
+  - **Field level** (`f2-text-field`, `f2-select-field`, `f2-switch-field`) — wraps input with label, validation messages, and documentation
+- **`l2-*`** — Layout components (`l2-sidebar`, `l2-header`, `l2-breadcrumb`, `l2-panel`)
+
+**Important:** `Page` from `@kurrent-ui/layout` is a Stencil **functional component**, not a custom element. Use it only in Stencil TSX: `<Page pageTitle="...">`.
+
+Some layout components accept **data props** (not child elements):
+- `l2-nav` takes a `navTree` prop (array of `NavNode`)
+- `l2-breadcrumb` takes a `crumbs` prop (array of `Crumb`)
+
+These are standard web components usable in **any framework** — HTML, React, Angular, Vue, Svelte, or Stencil/TSX.
+
+## Quick Decision Guide
+
+| Task | Action |
+|------|--------|
+| Setting up a new project | Read `references/getting-started.md` |
+| Building page layouts | Read `references/layout.md` |
+| Adding forms and validation | Read `references/fields.md` |
+| Using buttons, tables, modals, tabs | Read `references/components.md` |
+| Configuring themes and colors | Read `references/theming.md` |
+| Aligning existing UI to Kurrent | Follow the migration protocol below |
+
+## Core Patterns
+
+### Shadow DOM & Styling
+
+Most components use Shadow DOM. Style them via:
+1. **CSS custom properties** — Components expose `--variable-name` properties for customization
+2. **CSS parts** — Use `::part(name)` to style internal elements
+3. **Slots** — Named slots for content composition (`before`, `after`, `documentation`)
+
+### Theme Integration
+
+```typescript
+import { theme } from '@kurrent-ui/theme';
+```
+
+Apply theme-aware attributes on host elements:
+
+```tsx
+<Host high-contrast={theme.isHighContrast()} dark={theme.isDark()}>
+```
+
+Four built-in themes: `light`, `dark`, `high_contrast_light`, `high_contrast_dark`. Auto-selection respects `prefers-color-scheme` and `prefers-contrast` media queries.
+
+### Form Pattern
+
+```typescript
+import { createValidatedForm } from '@kurrent-ui/forms';
+
+const form = createValidatedForm({
+  name: { initialValue: '', validations: [required()] },
+});
+```
+
+Fields emit `fieldchange` custom events with the new value in `event.detail`. Use `f2-*-field` components (field level) for forms with labels and validation, or `f2-*-input` components (input level) for custom layouts.
+
+### Icon Registration
+
+```typescript
+import { iconStore } from '@kurrent-ui/components';
+// Register icons before use
+iconStore.addIcons(/* icon data */);
+```
+
+Display with `<c2-icon icon="icon-name" size={20} />`.
+
+## Migration Protocol: Aligning Existing UI to Kurrent
+
+When aligning an existing application to the Kurrent Design System:
+
+1. **Audit current UI** — Inventory all pages, forms, navigation, and interactive elements
+2. **Install packages** — Add required `@kurrent-ui/*` packages (see `references/getting-started.md`)
+3. **Set up theming first** — Initialize `@kurrent-ui/theme` and replace hardcoded colors with CSS custom properties (see `references/theming.md`)
+4. **Replace layout structure** — Swap app shell, sidebar, header, and page containers with layout components (see `references/layout.md`)
+5. **Replace interactive components** — Swap buttons, tables, modals, tabs with `c2-*` components (see `references/components.md`)
+6. **Replace form elements** — Swap inputs, selects, checkboxes with `f2-*` fields and wire up form validation (see `references/fields.md`)
+7. **Verify** — Check theming in all four modes, test responsive behavior, validate form flows
+
+## Additional Resources
+
+### Reference Files
+
+For detailed component catalogs, CSS tokens, and usage examples, consult:
+
+- **`references/getting-started.md`** — Installation, framework integration, project setup
+- **`references/components.md`** — Full catalog of core components (c2-*) with props and usage
+- **`references/fields.md`** — Form field components (f2-*), validation, and form patterns
+- **`references/layout.md`** — Page structure components (l2-*), navigation, and layout patterns
+- **`references/theming.md`** — Theme system, color scheme, CSS custom properties, theme API
+
+### Source of Truth
+
+The design system source code is the definitive reference. When in doubt about component APIs, read the component source files directly from the design-system repository:
+- Core components: `packages/components/src/components/`
+- Field components: `packages/fields/src/components/`
+- Layout components: `packages/layout/src/components/`
+- Theme definitions: `packages/theme/src/`
diff --git a/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/components.md b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/components.md
new file mode 100644
index 00000000..47c38191
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/components.md
@@ -0,0 +1,378 @@
+# Core Components (c2-*)
+
+Full catalog of components from `@kurrent-ui/components`.
+
+## Buttons
+
+### c2-button
+
+Primary interactive button.
+
+**Variants:** `default` | `filled` | `outline` | `minimal` | `link` | `delete` | `cancel`
+
+```html
+<c2-button variant="filled">Save</c2-button>
+<c2-button variant="outline">Cancel</c2-button>
+<c2-button variant="delete">Delete</c2-button>
+<c2-button disabled>Disabled</c2-button>
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `variant` | `ButtonVariant` | Visual style |
+| `disabled` | `boolean` | Disable interaction |
+
+**CSS Custom Properties:**
+- `--primary-color`, `--secondary-color`, `--tertiary-color`
+- `--background-color`, `--foreground-color`, `--border-color`
+- `--border-radius`, `--border-width`, `--spacing`
+- `--focus-color`, `--transition-duration`
+
+**CSS Parts:** `button`
+
+### c2-button-link
+
+Button styled as a navigable link.
+
+```html
+<c2-button-link url="/settings" variant="filled">Go to Settings</c2-button-link>
+```
+
+**Additional Props:** `url`, `external` (opens in new tab)
+
+### c2-button-with-confirmation
+
+Button that requires confirmation before executing action.
+
+```html
+<c2-button-with-confirmation
+  variant="delete"
+  confirmText="Are you sure?"
+  onRequestConfirmation={handler}
+>
+  Delete Item
+</c2-button-with-confirmation>
+```
+
+### c2-thinking-button
+
+Async action button that shows state transitions: default -> thinking -> complete/failed -> default.
+
+```tsx
+<c2-thinking-button
+  text="Deploy"
+  action={async (e) => { await deployService(); }}
+  defaultIcon={deployIcon}
+  thinkingIcon={spinnerIcon}
+  completeIcon={checkIcon}
+  failedIcon={errorIcon}
+/>
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `action` | `(e: MouseEvent) => Promise<unknown>` | Async action to execute on click |
+| `text` | `string` | Button label |
+| `variant` | `string` | Button visual style |
+| `disabled` | `boolean` | Disable interaction |
+| `defaultIcon` | `IconDescription` | Icon in default state |
+| `thinkingIcon` | `IconDescription` | Icon while action runs |
+| `completeIcon` | `IconDescription` | Icon on success |
+| `failedIcon` | `IconDescription` | Icon on failure |
+
+## Actions
+
+### c2-actions
+
+Container for action elements.
+
+```html
+<c2-actions>
+  <c2-action>Edit</c2-action>
+  <c2-action-link url="/details" icon={viewIcon}>View</c2-action-link>
+</c2-actions>
+```
+
+### c2-action
+
+A clickable action element (typically used in toolbars, dropdowns, or action bars).
+
+```html
+<c2-action>Edit</c2-action>
+```
+
+### c2-action-link
+
+Action styled as a navigable link with an icon.
+
+```tsx
+<c2-action-link url="/streams/123" icon={viewIcon}>
+  View Stream
+</c2-action-link>
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `url` | `string` | Navigation URL |
+| `icon` | `IconDescription` | Icon to display |
+| `disabled` | `boolean` | Disable interaction |
+| `dot` | `color` | Attention indicator dot |
+
+### c2-action-dropdown
+
+Action with a dropdown menu.
+
+```html
+<c2-action-dropdown>
+  <span slot="label">More Actions</span>
+  <c2-action>Duplicate</c2-action>
+  <c2-action>Archive</c2-action>
+</c2-action-dropdown>
+```
+
+### c2-action-with-confirmation
+
+Action requiring user confirmation before executing.
+
+## Modals
+
+### c2-modal
+
+General-purpose modal dialog with header, body, and footer slots.
+
+```html
+<c2-modal>
+  <span slot="header">Edit User</span>
+  <div>
+    <!-- Modal body content -->
+  </div>
+  <div slot="footer">
+    <c2-button variant="filled">Save</c2-button>
+    <c2-button variant="cancel">Cancel</c2-button>
+  </div>
+</c2-modal>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `header` | `boolean` | `true` | Show header section |
+| `footer` | `boolean` | `true` | Show footer section |
+
+**Slots:** `header`, default (body), `footer`
+
+**Events:** `requestClose`
+
+Typically used with `c2-portal` to render outside the component DOM tree.
+
+### c2-confirm-modal
+
+Pre-built confirmation dialog.
+
+```tsx
+<c2-confirm-modal
+  open={showModal}
+  heading="Confirm Delete"
+  body="This action cannot be undone."
+  confirmText="Delete"
+  cancelText="Cancel"
+  onConfirm={handleConfirm}
+  onCancel={handleCancel}
+/>
+```
+
+## Tables
+
+### c2-table
+
+Data table with sorting, row selection, and customization.
+
+```tsx
+<c2-table
+  columns={[
+    { header: 'Name', cell: (row) => row.name },
+    { header: 'Status', cell: (row) => row.status },
+  ]}
+  data={items}
+/>
+```
+
+**Variants:**
+- **c2-table** — Standard table
+- **c2-table-nested** — Table with expandable nested rows
+- **c2-table-virtualized** — Virtualized table for large datasets with optional detail rows
+
+**CSS Parts:** `table`, `header`, `row`, `cell`
+
+## Tabs
+
+### c2-tabs
+
+Tabbed content container.
+
+```html
+<c2-tabs panels={['Overview', 'Details', 'History']}>
+  <div>Overview content</div>
+  <div>Details content</div>
+  <div>History content</div>
+</c2-tabs>
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `panels` | `string[]` | Tab labels |
+| `activeParam` | `string` | URL search param to sync active tab |
+
+## Icons
+
+### c2-icon
+
+Displays registered SVG icons.
+
+```html
+<c2-icon icon="chevron" size={24} />
+<c2-icon icon="spinner" spin />
+<c2-icon icon={[NAMESPACE, 'icon-name']} />
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `string \| [symbol, string]` | Icon name or namespaced tuple |
+| `size` | `number` | Size in pixels |
+| `angle` | `number` | Rotation angle |
+| `spin` | `boolean` | Animate spinning (auto for "spinner") |
+| `spinDirection` | `'clockwise' \| 'counter-clockwise'` | Spin direction |
+
+**CSS Parts:** `icon`
+
+## Feedback & Status
+
+### c2-badge
+
+Status badge / pill label.
+
+```html
+<c2-badge variant="success">Active</c2-badge>
+<c2-badge variant="error">Failed</c2-badge>
+```
+
+### c2-callout
+
+Informational callout block.
+
+```html
+<c2-callout variant="warning">
+  This operation may take a while.
+</c2-callout>
+```
+
+**Variants:** `info` | `warning` | `error` | `success`
+
+### c2-toast
+
+Toast notification system. Triggered programmatically.
+
+```typescript
+import { toast } from '@kurrent-ui/components';
+
+toast.success({ title: 'Saved', message: 'Changes saved.' });
+toast.error({ title: 'Error', message: 'Something went wrong.' });
+toast.warning({ title: 'Warning', message: 'Check your input.' });
+toast.info({ title: 'Info', message: 'Processing complete.' });
+```
+
+### c2-corner-banner
+
+Corner ribbon banner for status labels (e.g., "Beta", "New").
+
+### c2-counter
+
+Numeric counter display.
+
+## Loading
+
+### c2-loading-dots
+
+Animated loading dots indicator.
+
+```html
+<c2-loading-dots />
+```
+
+### c2-loading-text
+
+Loading placeholder text with animation.
+
+## Navigation & Flow
+
+### c2-pagination
+
+Page navigation for paginated data.
+
+```html
+<c2-pagination
+  pageCount={10}
+  currentPage={1}
+  onPageChange={handlePage}
+/>
+```
+
+### c2-progression
+
+Step progression indicator (wizard-style).
+
+### c2-wizard
+
+Multi-step wizard flow.
+
+## Utility
+
+### c2-popover
+
+Floating content anchored to a trigger element.
+
+```html
+<c2-popover>
+  <button slot="trigger">Open</button>
+  <div>Popover content</div>
+</c2-popover>
+```
+
+### c2-portal
+
+Renders children into a portal (outside component DOM tree). Use for modals and overlays to avoid z-index and overflow issues.
+
+### c2-copy
+
+Copy-to-clipboard button.
+
+```html
+<c2-copy value="text to copy" />
+```
+
+### c2-accordian
+
+Expandable/collapsible content section.
+
+```html
+<c2-accordian heading="Advanced Options">
+  <div>Expanded content here</div>
+</c2-accordian>
+```
+
+**Note:** The component tag is spelled `c2-accordian` (not "accordion") — this is intentional in the design system.
+
+### c2-resize-observer
+
+Utility component that observes and reports element size changes.
diff --git a/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/fields.md b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/fields.md
new file mode 100644
index 00000000..b112f637
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/fields.md
@@ -0,0 +1,348 @@
+# Field Components (f2-*) and Form Patterns
+
+Components from `@kurrent-ui/fields` and `@kurrent-ui/forms` for building validated forms.
+
+## Field vs Input: Two-Level Architecture
+
+Every form element has two levels:
+
+| Level | Naming | Includes | Use When |
+|-------|--------|----------|----------|
+| **Input** | `f2-*-input` (e.g., `f2-text-input`, `f2-select-input`) | Raw interactive element only | Building custom layouts, embedding in tables, or composing manually |
+| **Field** | `f2-*-field` (e.g., `f2-text-field`, `f2-select-field`) | Input + label + validation messages + documentation | Standard forms with labels and validation |
+
+**Exceptions:** `f2-checkbox` and `f2-switch` are input-level tags (no `-input` suffix). Their field-level wrappers are `f2-checkbox-field` (if exists) and `f2-switch-field`.
+
+Always prefer **field-level** components in forms. Use **input-level** only for custom layouts.
+
+## Form Architecture
+
+### Creating a Validated Form
+
+```typescript
+import { createValidatedForm } from '@kurrent-ui/forms';
+
+const form = createValidatedForm({
+  name: {
+    initialValue: '',
+    validations: [required('Name is required')],
+  },
+  email: {
+    initialValue: '',
+    validations: [required(), email('Must be a valid email')],
+  },
+  role: {
+    initialValue: 'viewer',
+  },
+});
+```
+
+### Form Component Pattern (Stencil TSX)
+
+```tsx
+<f2-form onSubmit={handleSubmit}>
+  <f2-text-field
+    label="Name"
+    name="name"
+    value={form.name}
+    messages={form.messages('name')}
+    onFieldchange={(e) => form.set('name', e.detail)}
+  />
+  <f2-text-field
+    label="Email"
+    name="email"
+    value={form.email}
+    messages={form.messages('email')}
+    onFieldchange={(e) => form.set('email', e.detail)}
+  />
+
+  <f2-form-footer>
+    <c2-button variant="filled" type="submit" disabled={!form.valid}>
+      Save
+    </c2-button>
+  </f2-form-footer>
+</f2-form>
+```
+
+### Event Pattern
+
+All field components emit `fieldchange` custom events with the new value in `event.detail`.
+
+In frameworks that don't natively handle custom events (e.g., React), attach listeners via `ref`:
+
+```tsx
+// React example
+const inputRef = useRef(null);
+
+useEffect(() => {
+  const el = inputRef.current;
+  const handler = (e) => setName(e.detail);
+  el?.addEventListener('fieldchange', handler);
+  return () => el?.removeEventListener('fieldchange', handler);
+}, []);
+
+return <f2-text-input ref={inputRef} label="Name" value={name} />;
+```
+
+## Text Input Components
+
+### f2-text-input / f2-text-field
+
+Single-line text input.
+
+```html
+<!-- Input level (no label/validation) -->
+<f2-text-input name="username" placeholder="Enter username" value={value} />
+
+<!-- Field level (with label and validation) -->
+<f2-text-field
+  label="Username"
+  name="username"
+  placeholder="Enter username"
+  value={value}
+  messages={validationMessages}
+  onFieldchange={handler}
+/>
+```
+
+### f2-masked-text-input / f2-masked-text-field
+
+Text input with display masking (e.g., passwords, tokens).
+
+```html
+<f2-masked-text-field label="API Key" name="apiKey" value={apiKey} onFieldchange={handler} />
+```
+
+### f2-typeahead
+
+Text input with autocomplete suggestions.
+
+```html
+<f2-typeahead options={suggestions} onFieldchange={handler} />
+```
+
+### f2-textarea-input / f2-textarea-field
+
+Multi-line text input.
+
+```html
+<f2-textarea-field
+  label="Description"
+  name="description"
+  rows={4}
+  value={description}
+  onFieldchange={handler}
+/>
+```
+
+### f2-text-list-field
+
+List of text inputs for managing multiple values.
+
+## Selection Components
+
+### f2-select-input / f2-select-field
+
+Searchable dropdown select.
+
+```html
+<f2-select-field
+  label="Role"
+  name="role"
+  options={[
+    { value: 'admin', label: 'Admin' },
+    { value: 'viewer', label: 'Viewer' },
+  ]}
+  value={selectedRole}
+  onFieldchange={handler}
+/>
+```
+
+### f2-multi-checkbox-field
+
+Group of checkboxes for selecting multiple values.
+
+```html
+<f2-multi-checkbox-field
+  label="Notifications"
+  name="notifications"
+  options={[
+    { value: 'email', label: 'Email' },
+    { value: 'sms', label: 'SMS' },
+  ]}
+  value={selectedNotifications}
+  onFieldchange={handler}
+/>
+```
+
+## Toggle Components
+
+### f2-checkbox
+
+Single checkbox (input level).
+
+```html
+<f2-checkbox name="terms" checked={accepted} onFieldchange={handler}>
+  Accept terms
+</f2-checkbox>
+```
+
+### f2-switch / f2-switch-field
+
+Toggle switch.
+
+```html
+<!-- Input level -->
+<f2-switch name="feature" checked={enabled} onFieldchange={handler} />
+
+<!-- Field level (with label) -->
+<f2-switch-field label="Enable feature" name="feature" checked={enabled} onFieldchange={handler} />
+```
+
+### f2-radio-card-input / f2-radio-card-field
+
+Radio selection styled as selectable cards.
+
+```html
+<f2-radio-card-field
+  label="Plan"
+  name="plan"
+  options={[
+    { value: 'free', label: 'Free' },
+    { value: 'pro', label: 'Pro' },
+  ]}
+  value={selectedPlan}
+  onFieldchange={handler}
+/>
+```
+
+## Numeric Input
+
+### f2-number-input / f2-number-field
+
+Numeric input with optional step controls.
+
+```html
+<f2-number-field
+  label="Quantity"
+  name="quantity"
+  min={0}
+  max={100}
+  step={1}
+  value={quantity}
+  onFieldchange={handler}
+/>
+```
+
+## Form Structure Components
+
+### f2-form
+
+Form wrapper that handles submission.
+
+```html
+<f2-form onSubmit={handleSubmit}>
+  <!-- field components -->
+</f2-form>
+```
+
+### f2-form-footer
+
+Footer area for form action buttons (submit, cancel).
+
+```html
+<f2-form-footer>
+  <c2-button variant="filled" type="submit">Save</c2-button>
+  <c2-button variant="cancel">Cancel</c2-button>
+</f2-form-footer>
+```
+
+### f2-form-section-divider
+
+Visual divider between form sections.
+
+### f2-validation-messages
+
+Displays validation error messages. Used automatically by field-level components, or manually with input-level components:
+
+```html
+<f2-text-input name="email" value={email} invalid={hasErrors} onFieldchange={handler} />
+<f2-validation-messages messages={form.messages('email')} />
+```
+
+### f2-placeholder-field
+
+Placeholder skeleton for loading states in forms.
+
+## Common Input Props
+
+**Input-level components:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `name` | `string` | Field identifier (required, reflected to attribute) |
+| `value` | varies | Current value |
+| `placeholder` | `string` | Placeholder text |
+| `disabled` | `boolean` | Disable interaction |
+| `readonly` | `boolean` | Read-only mode |
+| `invalid` | `boolean` | Show error visual state |
+
+**Field-level components** (in addition to input props):
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Field label |
+| `messages` | `ValidationMessages` | Validation messages |
+| `documentation` | `string` | Help text |
+| `documentationLink` | `string` | Link for help text |
+| `documentationLinkText` | `string` | Link text for help |
+
+## Common Form Patterns
+
+### Settings Form
+
+```tsx
+const form = createValidatedForm({
+  displayName: { initialValue: user.name, validations: [required()] },
+  email: { initialValue: user.email, validations: [required(), email()] },
+  notifications: { initialValue: user.notifications },
+});
+
+render() {
+  return (
+    <f2-form onSubmit={() => save(form.data)}>
+      <f2-text-field label="Display Name" name="displayName" value={form.displayName}
+        messages={form.messages('displayName')} onFieldchange={e => form.set('displayName', e.detail)} />
+      <f2-text-field label="Email" name="email" value={form.email}
+        messages={form.messages('email')} onFieldchange={e => form.set('email', e.detail)} />
+
+      <f2-form-section-divider />
+
+      <f2-switch-field label="Email Notifications" name="notifications"
+        checked={form.notifications} onFieldchange={e => form.set('notifications', e.detail)} />
+
+      <f2-form-footer>
+        <c2-button variant="filled" type="submit" disabled={!form.valid || !form.changed}>Save</c2-button>
+        <c2-button variant="cancel" onClick={() => form.reset()}>Reset</c2-button>
+      </f2-form-footer>
+    </f2-form>
+  );
+}
+```
+
+### Filter Bar (Input Level)
+
+```tsx
+<f2-select-input
+  name="status"
+  options={statusOptions}
+  value={filters.status}
+  onFieldchange={e => updateFilter('status', e.detail)}
+/>
+<f2-text-input
+  name="search"
+  placeholder="Filter by name..."
+  value={filters.search}
+  onFieldchange={e => updateFilter('search', e.detail)}
+/>
+```
diff --git a/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/getting-started.md b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/getting-started.md
new file mode 100644
index 00000000..26d226d7
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/getting-started.md
@@ -0,0 +1,207 @@
+# Getting Started with Kurrent Design System
+
+## Installation
+
+Install the packages needed for the application:
+
+```bash
+# Core — almost always needed
+npm install @kurrent-ui/theme @kurrent-ui/components
+
+# Forms and fields
+npm install @kurrent-ui/fields @kurrent-ui/forms
+
+# Layout shell (sidebar, header, panels)
+npm install @kurrent-ui/layout
+
+# Optional
+npm install @kurrent-ui/utils @kurrent-ui/router @kurrent-ui/editor @kurrent-ui/stores
+```
+
+## Framework Integration
+
+### Stencil / TSX (Native)
+
+Components are built with Stencil and work natively in Stencil projects. Import and use directly:
+
+```tsx
+import { Component, h } from '@stencil/core';
+import { Page } from '@kurrent-ui/layout';
+
+@Component({ tag: 'my-page', shadow: true })
+export class MyPage {
+  render() {
+    return (
+      <Page pageTitle="Settings">
+        <c2-button variant="filled">Save</c2-button>
+      </Page>
+    );
+  }
+}
+```
+
+**Note:** `Page` is a Stencil functional component (not a custom element tag). Other layout components like `l2-header`, `l2-sidebar`, `l2-panel` are regular web components.
+
+### Plain HTML / Vanilla JS
+
+Load the component loaders and use as custom elements:
+
+```html
+<script type="module">
+  import { defineCustomElements as defineComponents } from '@kurrent-ui/components/loader';
+  import { defineCustomElements as defineLayout } from '@kurrent-ui/layout/loader';
+  import { defineCustomElements as defineFields } from '@kurrent-ui/fields/loader';
+  import { theme } from '@kurrent-ui/theme';
+
+  defineComponents();
+  defineLayout();
+  defineFields();
+
+  // Initialize theme (auto-detects system preference)
+  theme.select('auto');
+</script>
+
+<l2-header>
+  <l2-theme-dropdown slot="right"></l2-theme-dropdown>
+</l2-header>
+<l2-sidebar>
+  <!-- l2-nav requires a navTree prop, set via JS -->
+</l2-sidebar>
+<main>
+  <c2-button variant="filled">Click me</c2-button>
+</main>
+```
+
+**Note:** Data-driven components like `l2-nav` and `l2-breadcrumb` require setting props via JavaScript (e.g., `document.querySelector('l2-nav').navTree = [...]`). The `Page` functional component is only available in Stencil TSX.
+
+### React
+
+Web components work in React with some caveats:
+
+```tsx
+import { defineCustomElements } from '@kurrent-ui/components/loader';
+import { theme } from '@kurrent-ui/theme';
+
+// Call once at app startup
+defineCustomElements();
+theme.select('auto');
+
+function App() {
+  return (
+    <main>
+      <c2-button variant="filled" onClick={() => alert('clicked')}>
+        Save
+      </c2-button>
+    </main>
+  );
+}
+```
+
+**React caveats with web components:**
+- Use `ref` + `addEventListener` for custom events like `fieldchange` (React doesn't natively support custom element events)
+- Boolean attributes: pass `true`/`false` explicitly, not truthy/falsy strings
+- Complex props (objects/arrays): use `ref` to set them via JavaScript, or JSON-serialize to attributes
+- Data-driven components (`l2-nav`, `l2-breadcrumb`): must set props via `ref`
+
+### Angular
+
+Angular supports web components via `CUSTOM_ELEMENTS_SCHEMA`:
+
+```typescript
+// app.module.ts
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+
+@NgModule({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  // ...
+})
+export class AppModule {}
+```
+
+```typescript
+// main.ts
+import { defineCustomElements as defineComponents } from '@kurrent-ui/components/loader';
+import { defineCustomElements as defineLayout } from '@kurrent-ui/layout/loader';
+import { theme } from '@kurrent-ui/theme';
+
+defineComponents();
+defineLayout();
+theme.select('auto');
+```
+
+### Vue
+
+Vue handles web components natively. Configure the compiler to skip Kurrent tags:
+
+```javascript
+// vite.config.js
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) =>
+            tag.startsWith('c2-') || tag.startsWith('f2-') || tag.startsWith('l2-'),
+        },
+      },
+    }),
+  ],
+};
+```
+
+## Theme Initialization
+
+Always initialize the theme early in the application lifecycle:
+
+```typescript
+import { theme } from '@kurrent-ui/theme';
+
+// Auto-detect from system preferences
+theme.select('auto');
+
+// Or force a specific theme
+theme.select('dark');
+theme.select('light');
+theme.select('high_contrast_dark');
+theme.select('high_contrast_light');
+```
+
+The theme system:
+- Injects CSS custom properties into `:root`
+- Persists selection in `localStorage`
+- Supports `prefers-color-scheme` and `prefers-contrast` media queries
+- Propagates to iframes via the `theme` attribute
+
+## Icon Setup
+
+Register icons before rendering any `c2-icon` components:
+
+```typescript
+import { iconStore } from '@kurrent-ui/components';
+
+// Register individual icons
+iconStore.addIcons({
+  name: 'chevron',
+  svg: '<svg>...</svg>',
+});
+
+// Or register a namespace of icons
+import { K_COMPONENTS_ICON_NAMESPACE } from '@kurrent-ui/components';
+// Icons in this namespace are auto-registered
+```
+
+Use the `@kurrent-ui/icon-manager` CLI tool for managing project icons:
+
+```bash
+npx @kurrent-ui/icon-manager --dir=./src/icons
+```
+
+## Key Principles
+
+1. **Use CSS custom properties for all colors** — never hardcode colors; always use `--color-*` tokens
+2. **Initialize theme before first render** — call `theme.select()` in the entry point
+3. **Register icons early** — before any `c2-icon` renders
+4. **Use Shadow DOM parts for customization** — `::part(name)` for styling internals
+5. **Compose with slots** — use named slots for content injection
+6. **Prefer field-level components** — use `f2-*-field` in forms, `f2-*-input` only for custom layouts
+7. **Set data props via JavaScript** — `l2-nav` and `l2-breadcrumb` take data props, not child elements
diff --git a/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/layout.md b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/layout.md
new file mode 100644
index 00000000..099c9f05
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/layout.md
@@ -0,0 +1,395 @@
+# Layout Components and Page Structure
+
+Components from `@kurrent-ui/layout` for building application shells and page structure.
+
+## Application Shell (Stencil TSX)
+
+A typical Kurrent application shell in Stencil:
+
+```tsx
+import { Page } from '@kurrent-ui/layout';
+import type { NavTree, Crumb } from '@kurrent-ui/layout';
+
+const navTree: NavTree = [
+  { title: 'Dashboard', url: '/dashboard' },
+  { title: 'Streams', url: '/streams' },
+  {
+    title: 'Settings',
+    children: [
+      { title: 'General', url: '/settings/general' },
+      { title: 'Users', url: '/settings/users' },
+    ],
+  },
+];
+
+render() {
+  return [
+    <l2-header>
+      <l2-logo slot="left" />
+      <l2-header-dropdown slot="right" label="User">
+        <c2-action>Profile</c2-action>
+        <c2-action>Logout</c2-action>
+      </l2-header-dropdown>
+      <l2-theme-dropdown slot="right" />
+    </l2-header>,
+
+    <l2-sidebar>
+      <l2-nav navTree={navTree} />
+      <l2-sidebar-dropdown slot="footer" label="Help">
+        <c2-action>Documentation</c2-action>
+      </l2-sidebar-dropdown>
+    </l2-sidebar>,
+
+    <Page pageTitle="Dashboard">
+      {/* Page content */}
+    </Page>,
+  ];
+}
+```
+
+## Page Component (Functional Component)
+
+**Important:** `Page` is a Stencil **functional component** exported from `@kurrent-ui/layout`. It is NOT a custom element tag. Use it only in Stencil TSX.
+
+```tsx
+import { Page } from '@kurrent-ui/layout';
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `pageTitle` | `string` | Document title and page heading |
+| `crumbs` | `Crumb[]` | Breadcrumb trail data |
+| `state` | `PageState` | `'loading'` \| `'ready'` \| `['error', unknown]` |
+| `empty` | `boolean` | Show empty state |
+| `renderEmptyState` | `FunctionalComponent` | Custom empty state renderer |
+| `renderErrorState` | `FunctionalComponent<ErrorStateProps>` | Custom error state renderer |
+| `renderLoadingState` | `FunctionalComponent \| false` | Custom loading renderer, or `false` to disable |
+| `headerTitle` | `string \| false` | Override header text, or `false` to hide |
+| `headerRight` | `FunctionalComponent` | Content for the right side of the page header |
+| `progressBarId` | `string` | Loading bar ID (defaults to `'page'`) |
+
+**Usage with state management:**
+
+```tsx
+<Page
+  pageTitle="Users"
+  state={loading ? 'loading' : error ? ['error', error] : 'ready'}
+  crumbs={[
+    { path: '/admin', name: 'Admin' },
+    { path: '/users', name: 'Users' },
+  ]}
+>
+  <c2-table columns={columns} data={users} />
+</Page>
+```
+
+**For non-Stencil frameworks:** Build the page layout manually using `l2-header`, `l2-sidebar`, `l2-breadcrumb`, `l2-panel`, and standard HTML elements. The `Page` functional component handles wiring these together in Stencil.
+
+## Header
+
+### l2-header
+
+Application top bar with slot-based composition.
+
+```html
+<l2-header>
+  <l2-logo slot="left" />
+  <span slot="center">App Name</span>
+  <l2-theme-dropdown slot="right" />
+</l2-header>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `header` | `boolean` | `true` | Show/hide header section |
+| `footer` | `boolean` | `true` | Show/hide footer section |
+
+**Slots:** `left`, `center`, `right`, `under`, `backdrop`
+
+**CSS Parts:** `header`, `left`, `center`, `right`, `under`, `backdrop`
+
+### l2-header-dropdown
+
+Dropdown menu in the header.
+
+```html
+<l2-header-dropdown label="Account">
+  <c2-action>Profile</c2-action>
+  <c2-action>Sign out</c2-action>
+</l2-header-dropdown>
+```
+
+### l2-logo
+
+Brand logo component. Place in header's `left` slot.
+
+## Sidebar Navigation
+
+### l2-sidebar
+
+Side navigation panel using slots.
+
+```html
+<l2-sidebar>
+  <l2-nav navTree={navTree} />
+</l2-sidebar>
+```
+
+**Slots:** default (main content), `after` (content after aside)
+
+Auto-manages `--layout-sidebar-width` CSS variable based on measured width.
+
+### l2-nav
+
+Navigation component driven by a **data prop** (not child elements).
+
+```tsx
+import type { NavTree } from '@kurrent-ui/layout';
+
+const navTree: NavTree = [
+  { title: 'Home', url: '/home' },
+  { title: 'Streams', url: '/streams' },
+  {
+    title: 'Admin',
+    children: [
+      { title: 'Users', url: '/admin/users' },
+      { title: 'Settings', url: '/admin/settings' },
+    ],
+  },
+];
+
+<l2-nav navTree={navTree} />
+```
+
+**NavTree Types:**
+
+```typescript
+type NavTree = NavNode[];
+type NavNode = NavParentNode | NavLeafNode;
+
+interface NavLeafNode {
+  title: string;
+  url: string;
+  disabled?: boolean;
+  external?: boolean;
+  match?: string;      // custom active-match pattern
+  exact?: boolean;     // exact URL match for active state
+}
+
+interface NavParentNode {
+  title: string;
+  disabled?: boolean;
+  children: NavNode[];
+}
+```
+
+### l2-sidebar-dropdown
+
+Dropdown menu within the sidebar.
+
+```html
+<l2-sidebar-dropdown label="Workspace">
+  <c2-action>Switch workspace</c2-action>
+</l2-sidebar-dropdown>
+```
+
+## Content Containers
+
+### l2-panel
+
+Content panel with optional header.
+
+```html
+<l2-panel>
+  <l2-panel-header>
+    <span slot="title">Recent Events</span>
+    <c2-button slot="actions" variant="minimal">Refresh</c2-button>
+  </l2-panel-header>
+  <div>Panel content</div>
+</l2-panel>
+```
+
+### l2-panel-header
+
+Header for panels. **Slots:** `title`, `actions`
+
+### l2-layout-section
+
+Section container for grouping related content.
+
+### l2-layout-hr
+
+Horizontal rule divider between sections.
+
+### l2-layout-auto-label
+
+Auto-labeled layout for key-value display.
+
+### l2-page-title
+
+Page title display component.
+
+## Breadcrumb
+
+### l2-breadcrumb
+
+Breadcrumb trail driven by a **data prop** (not child elements).
+
+```tsx
+import type { Crumb } from '@kurrent-ui/layout';
+
+const crumbs: Crumb[] = [
+  { path: '/streams', name: 'Streams' },
+  { path: '/orders', name: 'Orders' },
+];
+
+<l2-breadcrumb crumbs={crumbs} />
+```
+
+**Crumb Type:**
+
+```typescript
+interface Crumb {
+  path: string;   // relative path from previous crumb
+  name: string;   // display text
+}
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `crumbs` | `Crumb[]` | Array of breadcrumb items |
+| `noValidate` | `boolean` | Disable route validation warnings |
+
+## Navigation Components
+
+### l2-tab-bar
+
+Tab navigation bar for sub-sections of a page.
+
+```html
+<l2-tab-bar
+  tabs={['Overview', 'Events', 'Subscriptions']}
+  activeTab={currentTab}
+  onTabChange={handler}
+/>
+```
+
+### l2-toolbar
+
+Toolbar for page-level actions and filters.
+
+```html
+<l2-toolbar>
+  <c2-button variant="filled">Create</c2-button>
+  <f2-text-input placeholder="Search..." />
+</l2-toolbar>
+```
+
+## Theming Controls
+
+### l2-theme-dropdown
+
+Dropdown for switching between themes. Place in the header.
+
+```html
+<l2-theme-dropdown />
+```
+
+### l2-theme-picker
+
+Full theme picker UI (expanded, not dropdown).
+
+## Status & Empty States
+
+### l2-display-error
+
+Error display for page-level errors.
+
+```html
+<l2-display-error message="Unable to load data" details="Connection timed out" />
+```
+
+### l2-empty-state
+
+Empty state display when no data is available.
+
+```html
+<l2-empty-state heading="No events yet" message="Events will appear here once created." icon="events" />
+```
+
+### l2-loading-bar
+
+Global loading progress bar, typically at the top of the app.
+
+## Layout Utility Components
+
+| Component | Purpose |
+|-----------|---------|
+| `l2-layout-section` | Section grouping |
+| `l2-layout-hr` | Horizontal divider |
+| `l2-layout-auto-label` | Key-value auto-labeling |
+| `l2-layout-link` | Layout-styled link |
+| `l2-layout-button` | Layout-styled button |
+| `l2-sized-panel` | Panel with fixed sizing |
+
+## Common Layout Patterns
+
+### Dashboard Page (Stencil TSX)
+
+```tsx
+<Page pageTitle="Dashboard">
+  <l2-toolbar>
+    <f2-select-field label="Time range" options={timeRanges} value={range} onFieldchange={handler} />
+  </l2-toolbar>
+
+  <l2-panel>
+    <l2-panel-header>
+      <span slot="title">Recent Activity</span>
+    </l2-panel-header>
+    <c2-table columns={columns} data={activities} />
+  </l2-panel>
+</Page>
+```
+
+### Detail Page with Breadcrumbs (Stencil TSX)
+
+```tsx
+<Page
+  pageTitle={stream.name}
+  crumbs={[
+    { path: '/streams', name: 'Streams' },
+    { path: `/${stream.id}`, name: stream.name },
+  ]}
+>
+  <l2-tab-bar tabs={['Events', 'Subscriptions', 'Settings']} activeTab={tab} onTabChange={setTab} />
+
+  {tab === 'Events' && <EventsList streamId={stream.id} />}
+  {tab === 'Settings' && <StreamSettings stream={stream} />}
+</Page>
+```
+
+### Settings Page (Stencil TSX)
+
+```tsx
+<Page pageTitle="Settings">
+  <l2-panel>
+    <l2-panel-header>
+      <span slot="title">General</span>
+    </l2-panel-header>
+    <f2-form onSubmit={saveGeneral}>
+      <f2-text-field label="Cluster Name" name="name" value={settings.name} onFieldchange={handler} />
+      <l2-layout-hr />
+      <f2-switch-field label="Maintenance Mode" name="maintenance" checked={settings.maintenance} onFieldchange={handler} />
+      <f2-form-footer>
+        <c2-button variant="filled" type="submit">Save</c2-button>
+      </f2-form-footer>
+    </f2-form>
+  </l2-panel>
+</Page>
+```
diff --git a/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/theming.md b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/theming.md
new file mode 100644
index 00000000..612420ec
--- /dev/null
+++ b/.claude/plugins/kurrent-design-system/skills/kurrent-ds/references/theming.md
@@ -0,0 +1,222 @@
+# Theme System
+
+The `@kurrent-ui/theme` package provides a comprehensive theming system with four built-in themes, CSS custom property injection, and automatic system preference detection.
+
+## Built-in Themes
+
+| Theme | `shade` | `contrast` | Media Match |
+|-------|---------|------------|-------------|
+| `light` | light | low | default |
+| `dark` | dark | low | `prefers-color-scheme: dark` |
+| `high_contrast_light` | light | high | `prefers-contrast: more` |
+| `high_contrast_dark` | dark | high | Both dark + high contrast |
+
+## Theme API
+
+```typescript
+import { theme } from '@kurrent-ui/theme';
+
+// Selection
+theme.select('auto');                    // Auto-detect from system
+theme.select('dark');                    // Force specific theme
+theme.select('high_contrast_light');     // Force high contrast light
+
+// Querying
+theme.selected;      // 'auto' | 'light' | 'dark' | 'high_contrast_light' | 'high_contrast_dark'
+theme.name;          // Resolved theme name (never 'auto')
+theme.shade;         // 'light' | 'dark'
+theme.contrast;      // 'high' | 'low'
+theme.isDark();      // boolean
+theme.isHighContrast(); // boolean
+
+// Color access
+theme.colors;        // Full color scheme object (BaseScheme)
+theme.colors.background;
+theme.colors.highlight;
+theme.colors.error;
+
+// Change listener
+const unsubscribe = theme.onThemeChange((newTheme) => {
+  console.log('Theme changed to:', newTheme.name);
+});
+// Call unsubscribe() to remove listener
+```
+
+## Complete Color Token Reference
+
+All tokens are injected as CSS custom properties on `:root`.
+
+### Core Colors
+
+| Token | Purpose | Contrast Variant |
+|-------|---------|-----------------|
+| `--color-background` | Page/surface background | `--color-background-contrast` |
+| `--color-foreground` | Primary body text | `--color-foreground-contrast` |
+| `--color-title` | Heading text | `--color-title-contrast` |
+| `--color-highlight` | Brand/accent color | `--color-highlight-contrast` |
+| `--color-link` | Clickable link text | `--color-link-contrast` |
+| `--color-focus` | Focus ring / outline | `--color-focus-contrast` |
+
+### Status Colors
+
+Each status color has a base, alt, and contrast variant:
+
+| Base Token | Alt Token | Contrast Token | Purpose |
+|------------|-----------|----------------|---------|
+| `--color-error` | `--color-error-alt` | `--color-error-contrast` | Errors, destructive |
+| `--color-warning` | `--color-warning-alt` | `--color-warning-contrast` | Warnings, caution |
+| `--color-success` | `--color-success-alt` | `--color-success-contrast` | Success, positive |
+| `--color-info` | `--color-info-alt` | `--color-info-contrast` | Informational |
+
+### Shade Scale
+
+Grayscale steps for borders, dividers, and subtle backgrounds:
+
+| Token | Purpose |
+|-------|---------|
+| `--color-shade-10` | Lightest shade (subtle borders) |
+| `--color-shade-20` | Light dividers |
+| `--color-shade-30` | Medium borders |
+| `--color-shade-40` | Medium-dark elements |
+| `--color-shade-50` | Dark elements |
+| `--color-shade-60` | Darkest shade (heavy borders) |
+
+### Special Tokens
+
+| Token | Purpose |
+|-------|---------|
+| `--color-overlay` | Overlay background (opaque) |
+| `--color-overlay-alpha` | Overlay background (semi-transparent) |
+| `--color-disabled` | Disabled element background |
+| `--color-disabled-border` | Disabled element border |
+| `--color-disabled-contrast` | Disabled element text |
+
+## Using Theme Colors in CSS
+
+Always use CSS custom properties instead of hardcoded colors:
+
+```css
+/* CORRECT */
+.my-component {
+  background-color: var(--color-background);
+  color: var(--color-foreground);
+  border: 1px solid var(--color-shade-30);
+}
+
+.my-component .title {
+  color: var(--color-title);
+}
+
+.my-component .error {
+  color: var(--color-error);
+  background: var(--color-error-alt);
+}
+
+.my-component:focus-visible {
+  outline: 2px solid var(--color-focus);
+}
+
+/* INCORRECT — hardcoded colors break theme switching */
+.my-component {
+  background-color: #ffffff;
+  color: #333333;
+  border: 1px solid #e0e0e0;
+}
+```
+
+## Theme-Aware Component Rendering
+
+In Stencil components, apply theme attributes for CSS-based theme adaptation:
+
+```tsx
+import { theme } from '@kurrent-ui/theme';
+
+@Component({ tag: 'my-component', shadow: true, styleUrl: 'my-component.css' })
+export class MyComponent {
+  render() {
+    return (
+      <Host high-contrast={theme.isHighContrast()} dark={theme.isDark()}>
+        <slot />
+      </Host>
+    );
+  }
+}
+```
+
+Then in CSS:
+
+```css
+:host {
+  background: var(--color-background);
+  color: var(--color-foreground);
+}
+
+:host([dark]) {
+  /* Dark-specific overrides if needed */
+}
+
+:host([high-contrast]) {
+  /* High contrast overrides if needed */
+}
+```
+
+## Theme Persistence
+
+The theme system automatically persists the user's selection to `localStorage`. On page load:
+
+1. Check `localStorage` for saved preference
+2. If `'auto'` or no saved preference, detect from system media queries
+3. Apply resolved theme
+4. Listen for system preference changes (if `'auto'`)
+
+## Iframe Theme Propagation
+
+For apps with iframes, the theme propagates automatically via a `theme` attribute. Child iframes receive the parent's theme selection.
+
+## Adding a Theme Picker to the UI
+
+Use the layout package's built-in components:
+
+```html
+<!-- Dropdown in header -->
+<l2-theme-dropdown />
+
+<!-- Or full picker component -->
+<l2-theme-picker />
+```
+
+These components handle selection, persistence, and visual feedback automatically.
+
+## Responding to Theme Changes
+
+Register a callback to react when the theme changes:
+
+```typescript
+import { theme } from '@kurrent-ui/theme';
+
+theme.onThemeChange((currentTheme) => {
+  // Update chart colors, canvas rendering, etc.
+  updateChartColors(currentTheme.colors);
+});
+```
+
+## Migration: Replacing Hardcoded Colors
+
+When migrating an existing app to the Kurrent theme system:
+
+1. Search for hardcoded color values (`#`, `rgb(`, `hsl(`, named colors)
+2. Map each to the nearest `--color-*` token
+3. Replace with `var(--color-token)`
+4. Test in all four themes (light, dark, high-contrast light, high-contrast dark)
+
+Common mappings:
+| Hardcoded | Replace With |
+|-----------|-------------|
+| White / `#fff` backgrounds | `var(--color-background)` |
+| Black / dark text | `var(--color-foreground)` |
+| Bold/heading text | `var(--color-title)` |
+| Brand blue/purple | `var(--color-highlight)` |
+| Red errors | `var(--color-error)` |
+| Green success | `var(--color-success)` |
+| Gray borders | `var(--color-shade-20)` to `var(--color-shade-40)` |
+| Disabled gray | `var(--color-disabled)` |