diff --git a/.changeset/bright-icons-route.md b/.changeset/bright-icons-route.md
new file mode 100644
index 0000000..b05cff9
--- /dev/null
+++ b/.changeset/bright-icons-route.md
@@ -0,0 +1,6 @@
+---
+"@webaseui/svelte": patch
+---
+
+Expand the public Lucide icon name set used by the documentation navigation,
+component contracts, status summaries, and theme controls.
diff --git a/.gitignore b/.gitignore
index 228fbbe..95660c5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,4 @@ coverage/
 .env
 .env.*
 !.env.example
+docs/UI/
diff --git a/apps/docs/src/App.svelte b/apps/docs/src/App.svelte
index d8ec2d8..3e7687b 100644
--- a/apps/docs/src/App.svelte
+++ b/apps/docs/src/App.svelte
@@ -1,69 +1,39 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import {
-    WeBaseAlert,
-    WeBaseBadge,
-    WeBaseButton,
-    WeBaseCard,
-    WeBaseIcon,
-    WeBaseIconButton,
-    WeBaseLink,
-    WeBaseSlider,
-    WeBaseSwitch,
-    WeBaseTabs,
-    WeBaseTooltip
-  } from '@webaseui/svelte';
-  import ComponentPreview from './lib/ComponentPreview.svelte';
-  import {
-    components,
-    groupOrder,
-    inlineParts,
-    packageVersion,
-    type ComponentName
-  } from './lib/reference';
-
-  const tokens = [
-    { key: 'canvas', label: 'Canvas', token: '--webase-color-canvas' },
-    { key: 'surface', label: 'Surface', token: '--webase-color-surface' },
-    { key: 'ink', label: 'Ink', token: '--webase-color-ink' },
-    { key: 'muted', label: 'Muted ink', token: '--webase-color-ink-muted' },
-    { key: 'brand', label: 'Brand', token: '--webase-color-brand' },
-    { key: 'tint', label: 'Brand tint', token: '--webase-color-brand-tint' },
-    { key: 'success', label: 'Success', token: '--webase-color-success' },
-    { key: 'warning', label: 'Warning', token: '--webase-color-warning' },
-    { key: 'error', label: 'Error', token: '--webase-color-error' }
-  ] as const;
-
-  const installCommand = 'npm install @webaseui/core @webaseui/svelte';
-  const importCode = `import '@webaseui/core/theme.css';
-import { WeBaseButton } from '@webaseui/svelte';`;
+  import DocsFooter from './lib/layout/DocsFooter.svelte';
+  import DocsHeader from './lib/layout/DocsHeader.svelte';
+  import SearchDialog from './lib/layout/SearchDialog.svelte';
+  import ComponentPage from './lib/pages/ComponentPage.svelte';
+  import ComponentsPage from './lib/pages/ComponentsPage.svelte';
+  import LandingPage from './lib/pages/LandingPage.svelte';
+  import ReleasePage from './lib/pages/ReleasePage.svelte';
+  import { components } from './lib/data/reference.js';
+  import { currentRoute, routeForPath, type DocsRoute } from './lib/router.js';
+
+  function supportedRoute(candidate: DocsRoute): DocsRoute {
+    if (candidate.kind !== 'component') return candidate;
+    return components.some(({ slug }) => slug === candidate.slug)
+      ? candidate
+      : { kind: 'components', path: '/components' };
+  }
 
+  let route = $state<DocsRoute>(supportedRoute(currentRoute()));
   let dark = $state(false);
   let themeReady = $state(false);
   let mobileNavOpen = $state(false);
   let searchOpen = $state(false);
-  let searchQuery = $state('');
-  let referenceQuery = $state('');
-  let selectedName = $state<ComponentName>('WeBaseButton');
-  let copiedTarget = $state('');
-  let heroTab = $state(0);
-  let heroDensity = $state(64);
-  let heroSaved = $state(false);
-  let searchDialog = $state<HTMLDialogElement>();
-  let searchInput = $state<HTMLInputElement>();
   let searchOpener = $state<HTMLElement>();
-  let copyTimer: number | undefined;
 
-  const selectedComponent = $derived(components.find(({ name }) => name === selectedName) ?? components[0]!);
-  const filteredComponents = $derived.by(() => {
-    const query = referenceQuery.trim().toLocaleLowerCase();
-    if (!query) return components;
-    return components.filter(({ searchText }) => searchText.includes(query));
+  const selectedComponent = $derived.by(() => {
+    if (route.kind !== 'component') return undefined;
+    const componentRoute = route as Extract<DocsRoute, { kind: 'component' }>;
+    return components.find(({ slug }) => slug === componentRoute.slug);
   });
-  const searchResults = $derived.by(() => {
-    const query = searchQuery.trim().toLocaleLowerCase();
-    if (!query) return components.slice(0, 8);
-    return components.filter(({ searchText }) => searchText.includes(query)).slice(0, 12);
+  const pageTitle = $derived.by(() => {
+    if (selectedComponent) return `${selectedComponent.name} - WeBaseUI`;
+    if (route.kind === 'components') return 'Components - WeBaseUI';
+    if (route.kind === 'release') return 'Release - WeBaseUI';
+    return 'WeBaseUI - Svelte component library';
   });
 
   $effect(() => {
@@ -71,22 +41,31 @@ import { WeBaseButton } from '@webaseui/svelte';`;
     if (themeReady) localStorage.setItem('webaseui-theme', dark ? 'dark' : 'light');
   });
 
-  $effect(() => {
-    const dialog = searchDialog;
-    if (!dialog) return;
+  function navigate(path: string) {
+    const target = new URL(path, window.location.origin);
+    const nextRoute = supportedRoute(routeForPath(target.pathname));
+    const currentUrl = `${window.location.pathname}${window.location.hash}`;
+    const nextUrl = `${nextRoute.path}${target.hash}`;
 
-    if (searchOpen && !dialog.open) {
-      dialog.showModal();
-      requestAnimationFrame(() => searchInput?.focus());
-    } else if (!searchOpen && dialog.open) {
-      dialog.close();
-    }
-  });
+    if (currentUrl !== nextUrl) history.pushState(null, '', nextUrl);
+    route = nextRoute;
+    mobileNavOpen = false;
+    searchOpen = false;
 
-  function openSearch(seed = '', trigger?: EventTarget | null) {
+    requestAnimationFrame(() => {
+      if (target.hash) {
+        document.querySelector<HTMLElement>(target.hash)?.scrollIntoView();
+        return;
+      }
+
+      window.scrollTo({ top: 0, behavior: 'auto' });
+      requestAnimationFrame(() => document.querySelector<HTMLElement>('[data-route-focus]')?.focus({ preventScroll: true }));
+    });
+  }
+
+  function openSearch(trigger?: EventTarget | null) {
     const active = trigger instanceof HTMLElement ? trigger : document.activeElement;
     searchOpener = active instanceof HTMLElement ? active : undefined;
-    searchQuery = seed;
     searchOpen = true;
     mobileNavOpen = false;
   }
@@ -101,75 +80,20 @@ import { WeBaseButton } from '@webaseui/svelte';`;
     });
   }
 
-  function scrollBehavior(): ScrollBehavior {
-    return window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';
-  }
-
-  function selectComponent(name: ComponentName, scroll = true) {
-    const component = components.find((item) => item.name === name);
-    if (!component) return;
-
-    selectedName = name;
-    searchOpen = false;
-    mobileNavOpen = false;
-    history.replaceState(null, '', `#component-${component.slug}`);
-
-    requestAnimationFrame(() => {
-      const target = document.getElementById(`component-${component.slug}`);
-      if (scroll) target?.scrollIntoView({ behavior: scrollBehavior(), block: 'start' });
-      target?.focus({ preventScroll: true });
-    });
-  }
-
-  function selectFromHash() {
-    const slug = window.location.hash.match(/^#component-([a-z]+)$/)?.[1];
-    if (!slug) return;
-    const component = components.find((item) => item.slug === slug);
-    if (component) selectedName = component.name;
-  }
-
-  function fallbackCopy(text: string) {
-    const textarea = document.createElement('textarea');
-    textarea.value = text;
-    textarea.setAttribute('readonly', '');
-    textarea.style.position = 'fixed';
-    textarea.style.opacity = '0';
-    document.body.append(textarea);
-    textarea.select();
-    const copied = document.execCommand('copy');
-    textarea.remove();
-    return copied;
-  }
-
-  async function copyText(key: string, text: string) {
-    let copied = false;
-
-    try {
-      if (navigator.clipboard?.writeText) {
-        await navigator.clipboard.writeText(text);
-        copied = true;
-      }
-    } catch {
-      copied = false;
-    }
-
-    if (!copied) copied = fallbackCopy(text);
-    if (!copied) return;
-
-    copiedTarget = key;
-    window.clearTimeout(copyTimer);
-    copyTimer = window.setTimeout(() => {
-      if (copiedTarget === key) copiedTarget = '';
-    }, 1800);
-  }
-
   onMount(() => {
     const storedTheme = localStorage.getItem('webaseui-theme');
     dark = storedTheme ? storedTheme === 'dark' : window.matchMedia('(prefers-color-scheme: dark)').matches;
     themeReady = true;
-    selectFromHash();
 
-    const handleHashChange = () => selectFromHash();
+    if (window.location.pathname !== route.path) history.replaceState(null, '', route.path);
+
+    const handlePopState = () => {
+      const nextRoute = supportedRoute(currentRoute());
+      route = nextRoute;
+      if (window.location.pathname !== nextRoute.path) history.replaceState(null, '', nextRoute.path);
+      mobileNavOpen = false;
+      searchOpen = false;
+    };
     const handleKeydown = (event: KeyboardEvent) => {
       const target = event.target instanceof HTMLElement ? event.target : null;
       const editing = target?.matches('input, textarea, select, [contenteditable="true"]');
@@ -183,383 +107,42 @@ import { WeBaseButton } from '@webaseui/svelte';`;
       }
     };
 
-    window.addEventListener('hashchange', handleHashChange);
+    window.addEventListener('popstate', handlePopState);
     document.addEventListener('keydown', handleKeydown);
 
-    const revealElements = Array.from(document.querySelectorAll<HTMLElement>('[data-reveal]'));
-    const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-    let observer: IntersectionObserver | undefined;
-
-    if (reducedMotion || !('IntersectionObserver' in window)) {
-      revealElements.forEach((element) => element.classList.add('is-visible'));
-    } else {
-      observer = new IntersectionObserver((entries) => {
-        for (const entry of entries) {
-          if (!entry.isIntersecting) continue;
-          entry.target.classList.add('is-visible');
-          observer?.unobserve(entry.target);
-        }
-      }, { threshold: 0.14 });
-      revealElements.forEach((element) => observer?.observe(element));
-    }
-
     return () => {
-      window.clearTimeout(copyTimer);
-      observer?.disconnect();
-      window.removeEventListener('hashchange', handleHashChange);
+      window.removeEventListener('popstate', handlePopState);
       document.removeEventListener('keydown', handleKeydown);
     };
   });
 </script>
 
 <svelte:head>
+  <title>{pageTitle}</title>
   <meta name="theme-color" content={dark ? '#141413' : '#f5f4ed'} />
 </svelte:head>
 
-<header class="site-header">
-  <div class="header-inner">
-    <a class="brand" href="#top" aria-label="WeBaseUI home">
-      <img class="brand-logo" src="/logo.svg" alt="" width="38" height="41" />
-    </a>
-
-      <button class="search-trigger" type="button" aria-label="Search documentation" onclick={(event) => openSearch('', event.currentTarget)}>
-      <WeBaseIcon name="search" size={16} />
-      <span>Search the contract</span>
-      <kbd>Ctrl K</kbd>
-    </button>
-
-    <nav class="primary-nav" aria-label="Documentation">
-      <a href="#tokens">Tokens</a>
-      <a href="#components">Components</a>
-      <a href="#install">Install</a>
-    </nav>
-
-    <div class="header-actions">
-      <div class="theme-control">
-        <span>{dark ? 'Dark' : 'Light'}</span>
-        <WeBaseSwitch label="Toggle dark theme" bind:checked={dark} />
-      </div>
-      <button class="mobile-menu-button" type="button" aria-expanded={mobileNavOpen} aria-controls="mobile-navigation" onclick={() => (mobileNavOpen = !mobileNavOpen)}>
-        {mobileNavOpen ? 'Close' : 'Menu'}
-      </button>
-    </div>
-  </div>
-
-  {#if mobileNavOpen}
-    <nav class="mobile-navigation" id="mobile-navigation" aria-label="Mobile documentation">
-      <a href="#tokens" onclick={() => (mobileNavOpen = false)}>Tokens</a>
-      <a href="#components" onclick={() => (mobileNavOpen = false)}>Components</a>
-      <a href="#install" onclick={() => (mobileNavOpen = false)}>Install</a>
-      <button type="button" onclick={(event) => openSearch('', event.currentTarget)}>Search components</button>
-    </nav>
+<DocsHeader
+  routeKind={route.kind}
+  {dark}
+  {mobileNavOpen}
+  onNavigate={navigate}
+  onToggleMobile={() => (mobileNavOpen = !mobileNavOpen)}
+  onToggleTheme={() => (dark = !dark)}
+  onOpenSearch={openSearch}
+/>
+
+<main>
+  {#if route.kind === 'landing'}
+    <LandingPage onNavigate={navigate} />
+  {:else if route.kind === 'components' || (route.kind === 'component' && !selectedComponent)}
+    <ComponentsPage onNavigate={navigate} />
+  {:else if route.kind === 'component' && selectedComponent}
+    {#key selectedComponent.name}<ComponentPage component={selectedComponent} onNavigate={navigate} />{/key}
+  {:else if route.kind === 'release'}
+    <ReleasePage onNavigate={navigate} />
   {/if}
-</header>
-
-<main id="top">
-  <section class="hero" aria-labelledby="hero-title">
-    <div class="hero-copy-block">
-      <h1 id="hero-title"><span>Build with</span><em>a visible contract.</em></h1>
-      <p class="hero-copy">Accessible Svelte 5 components, named tokens, and a public contract designed to move between products.</p>
-      <div class="hero-actions">
-        <WeBaseButton label="Explore reference" variant="ink" icon="arrow-down" onclick={() => document.querySelector('#components')?.scrollIntoView({ behavior: scrollBehavior() })} />
-        <WeBaseLink href="#install" label="Install packages" variant="action" />
-      </div>
-    </div>
-
-    <div class="hero-stage" aria-label="Interactive WeBaseUI specimen">
-      <h2 class="visually-hidden">Interactive component specimen</h2>
-      <div class="stage-card">
-        <WeBaseCard eyebrow="Live specimen" title="Reference desk" variant="paper">
-          <div class="hero-card-content">
-            <WeBaseTabs items={['Contract', 'Preview', 'Release']} panels={['Public behavior', 'Real components', 'Versioned changes']} bind:active={heroTab} />
-            <WeBaseSlider label="Interface density" bind:value={heroDensity} />
-          </div>
-          {#snippet footer()}
-            <small>Three browser engines</small>
-            <WeBaseBadge label="SSR ready" variant="canonical" />
-          {/snippet}
-        </WeBaseCard>
-      </div>
-
-      <div class="stage-alert">
-        <WeBaseAlert title="Contract verified" message="All 28 public exports are indexed." tone="success" />
-      </div>
-
-      <div class="stage-actions">
-        <WeBaseButton label={heroSaved ? 'Saved' : 'Save specimen'} variant={heroSaved ? 'outline' : 'ink'} icon="check" onclick={() => (heroSaved = !heroSaved)} />
-        <WeBaseIconButton label="Bookmark specimen" icon="bookmark" bind:pressed={heroSaved} />
-        <WeBaseTooltip label="Details" text="Every specimen is imported from the package root." />
-      </div>
-    </div>
-  </section>
-
-  <section class="proof-rail" aria-label="Library baseline" data-reveal>
-    <dl>
-      <div><dt>Components</dt><dd>28</dd></div>
-      <div><dt>Runtime</dt><dd>Svelte 5</dd></div>
-      <div><dt>Engines</dt><dd>3</dd></div>
-      <div><dt>License</dt><dd>MIT</dd></div>
-    </dl>
-  </section>
-
-  <section id="tokens" class="page-section tokens-section" data-reveal>
-    <header class="section-heading">
-      <p class="section-label">Foundation</p>
-      <h2>Tokens carry the identity.</h2>
-      <p>Semantic variables keep color, type, focus, and motion coherent across every framework surface.</p>
-    </header>
-
-    <div class="token-composition">
-      <div class="token-poster" aria-hidden="true">
-        <span class="poster-canvas"></span>
-        <span class="poster-brand"></span>
-        <span class="poster-ink"></span>
-        <span class="poster-signal"></span>
-        <strong>--webase-*</strong>
-      </div>
-
-      <div class="token-index" aria-label="Public color tokens">
-        {#each tokens as token}
-          <article class={`token-chip token-${token.key}`}>
-            <span class="token-swatch" style={`--token-swatch: var(${token.token})`}></span>
-            <div>
-              <strong>{token.label}</strong>
-              <code>{token.token}</code>
-            </div>
-          </article>
-        {/each}
-      </div>
-    </div>
-  </section>
-
-  <section id="components" class="page-section components-section" data-reveal>
-    <header class="section-heading components-heading">
-      <h2>Reference Desk</h2>
-      <p>Search, inspect, and exercise every public component against the versioned API contract.</p>
-      <button type="button" class="section-search-button" onclick={(event) => openSearch('', event.currentTarget)}>
-        <WeBaseIcon name="search" size={17} />
-        Search all 28 components
-      </button>
-    </header>
-
-    <div class="mobile-component-select">
-      <label for="mobile-component">Choose a component</label>
-      <select id="mobile-component" value={selectedName} onchange={(event) => selectComponent((event.currentTarget as HTMLSelectElement).value as ComponentName)}>
-        {#each components as component}
-          <option value={component.name}>{component.name}</option>
-        {/each}
-      </select>
-    </div>
-
-    <div class="reference-shell">
-      <aside class="reference-sidebar" aria-label="Component index">
-        <label class="sidebar-search">
-          <span class="visually-hidden">Filter components</span>
-          <WeBaseIcon name="search" size={15} />
-          <input type="search" placeholder="Filter components" bind:value={referenceQuery} />
-        </label>
-        <p class="sidebar-count">{filteredComponents.length} of {components.length}</p>
-
-        <div class="sidebar-groups">
-          {#each groupOrder as group}
-            {@const groupComponents = filteredComponents.filter((component) => component.group === group)}
-            {#if groupComponents.length > 0}
-              <section class="sidebar-group">
-                <h3>{group}</h3>
-                <div>
-                  {#each groupComponents as component}
-                    <button
-                      type="button"
-                      class:selected={selectedName === component.name}
-                      aria-current={selectedName === component.name ? 'true' : undefined}
-                      onclick={() => selectComponent(component.name, false)}
-                    >
-                      {component.shortName}
-                    </button>
-                  {/each}
-                </div>
-              </section>
-            {/if}
-          {/each}
-
-          {#if filteredComponents.length === 0}
-            <p class="sidebar-empty">No components match this filter.</p>
-          {/if}
-        </div>
-      </aside>
-
-      {#key selectedComponent.name}
-        <article
-          class="reference-detail"
-          id={`component-${selectedComponent.slug}`}
-          data-selected-component={selectedComponent.name}
-          tabindex="-1"
-        >
-          <header class="reference-header">
-            <div>
-              <p>{selectedComponent.group}</p>
-              <h3>{selectedComponent.name}</h3>
-              <p>
-                {#each inlineParts(selectedComponent.summary) as part}
-                  {#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}
-                {/each}
-              </p>
-            </div>
-            <span class="reference-version">v{packageVersion}</span>
-          </header>
-
-          <section class="preview-panel" aria-labelledby="preview-heading">
-            <header>
-              <h4 id="preview-heading">Live specimen</h4>
-              <span>Package root import</span>
-            </header>
-            <div class="preview-canvas">
-              <ComponentPreview name={selectedComponent.name} />
-            </div>
-          </section>
-
-          <div class="reference-lower">
-            <section class="contract-panel" aria-labelledby="contract-heading">
-              <header>
-                <h4 id="contract-heading">Public contract</h4>
-                <span>{selectedComponent.fields.length} fields</span>
-              </header>
-              <dl class="contract-grid">
-                {#each selectedComponent.fields as field}
-                  <div class:contract-wide={field.label === 'Props' || field.label === 'Boundary'}>
-                    <dt>{field.label}</dt>
-                    <dd>
-                      {#each inlineParts(field.value) as part}
-                        {#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}
-                      {/each}
-                    </dd>
-                  </div>
-                {/each}
-              </dl>
-            </section>
-
-            <section class="example-panel" aria-labelledby="example-heading">
-              <header>
-                <h4 id="example-heading">Usage</h4>
-                <button type="button" aria-label={`Copy ${selectedComponent.name} example`} onclick={() => copyText(`example-${selectedComponent.name}`, `import { ${selectedComponent.name} } from '@webaseui/svelte';\n\n${selectedComponent.example}`)}>
-                  {#if copiedTarget === `example-${selectedComponent.name}`}
-                    <WeBaseIcon name="check" size={14} /> Copied
-                  {:else}
-                    Copy
-                  {/if}
-                </button>
-              </header>
-              <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-              <pre role="region" aria-label={`${selectedComponent.name} usage example`} tabindex="0"><code>{`import { ${selectedComponent.name} } from '@webaseui/svelte';\n\n${selectedComponent.example}`}</code></pre>
-            </section>
-          </div>
-        </article>
-      {/key}
-    </div>
-  </section>
-
-  <section id="install" class="page-section install-section" data-reveal>
-    <header class="section-heading">
-      <h2>Install the boundary.</h2>
-      <p>Tokens and Svelte components are versioned independently, then verified together in a clean consumer.</p>
-    </header>
-
-    <div class="install-composition">
-      <article class="install-primary">
-        <header>
-          <span>Packages</span>
-          <button type="button" aria-label="Copy install command" onclick={() => copyText('install', installCommand)}>
-            {#if copiedTarget === 'install'}<WeBaseIcon name="check" size={14} /> Copied{:else}Copy{/if}
-          </button>
-        </header>
-        <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-        <pre role="region" aria-label="Installation command" tabindex="0"><code>{installCommand}</code></pre>
-        <p>@webaseui/svelte v{packageVersion}</p>
-      </article>
-
-      <article class="install-import">
-        <header>
-          <span>Import</span>
-          <button type="button" aria-label="Copy import example" onclick={() => copyText('import', importCode)}>
-            {#if copiedTarget === 'import'}<WeBaseIcon name="check" size={14} /> Copied{:else}Copy{/if}
-          </button>
-        </header>
-        <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-        <pre role="region" aria-label="Import example" tabindex="0"><code>{importCode}</code></pre>
-      </article>
-
-      <aside class="install-notes" aria-label="Release guarantees">
-        <div><strong>Type</strong><span>Generated declarations</span></div>
-        <div><strong>Render</strong><span>SSR and hydration fixture</span></div>
-        <div><strong>Input</strong><span>Keyboard and native form paths</span></div>
-        <div><strong>Engines</strong><span>Chromium, Firefox, WebKit</span></div>
-      </aside>
-    </div>
-  </section>
 </main>
 
-<footer>
-  <a class="footer-brand" href="#top"><img src="/logo.svg" alt="" width="30" height="32" /> <span>WeBaseUI</span></a>
-  <nav aria-label="Footer">
-    <a href="https://github.com/WeOpen/WeBaseUI">GitHub</a>
-    <a href="#components">Reference</a>
-    <span>MIT License</span>
-  </nav>
-</footer>
-
-<dialog
-  class="search-dialog"
-  bind:this={searchDialog}
-  aria-labelledby="search-heading"
-  onclose={() => (searchOpen = false)}
-  onkeydown={(event) => {
-    if (event.key !== 'Escape') return;
-    event.preventDefault();
-    closeSearch();
-  }}
-  onclick={(event) => { if (event.target === searchDialog) closeSearch(); }}
->
-  <div class="search-panel">
-    <header>
-      <div>
-        <p>Global search</p>
-        <h2 id="search-heading">Search the public contract</h2>
-      </div>
-      <WeBaseIconButton label="Close search" icon="x" onclick={closeSearch} />
-    </header>
-
-    <label class="search-input">
-      <span class="visually-hidden">Search components and API fields</span>
-      <WeBaseIcon name="search" size={20} />
-      <input bind:this={searchInput} type="search" placeholder="Try dialog, binding, or form" bind:value={searchQuery} />
-      <kbd>Esc</kbd>
-    </label>
-
-    <div class="search-results" aria-live="polite">
-      <p>{searchQuery ? `${searchResults.length} matches` : 'Browse components'}</p>
-      {#if searchResults.length > 0}
-        <ul>
-          {#each searchResults as component}
-            <li>
-              <button type="button" onclick={() => selectComponent(component.name)}>
-                <span><strong>{component.name}</strong><small>{component.group}</small></span>
-                <span>
-                  {#each inlineParts(component.summary) as part}
-                    {#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}
-                  {/each}
-                </span>
-                <WeBaseIcon name="arrow-right" size={16} />
-              </button>
-            </li>
-          {/each}
-        </ul>
-      {:else}
-        <div class="search-empty">
-          <WeBaseIcon name="archive-x" size={24} />
-          <strong>No contract found</strong>
-          <span>Try a component name, prop, binding, or behavior.</span>
-        </div>
-      {/if}
-    </div>
-  </div>
-</dialog>
+<DocsFooter onNavigate={navigate} />
+<SearchDialog open={searchOpen} onClose={closeSearch} onNavigate={navigate} />
diff --git a/apps/docs/src/app.css b/apps/docs/src/app.css
index 3d41dcd..1bc7353 100644
--- a/apps/docs/src/app.css
+++ b/apps/docs/src/app.css
@@ -56,8 +56,8 @@ pre:focus-visible {
 }
 
 ::selection {
-  color: var(--paper);
-  background: var(--brand);
+  color: var(--ink);
+  background: var(--surface);
 }
 
 .visually-hidden {
@@ -305,6 +305,10 @@ main { overflow: clip; }
   margin-top: 30px;
 }
 
+.hero-actions .ds-link-action {
+  min-height: var(--webase-component-button-height);
+}
+
 .hero-stage {
   position: relative;
   min-width: 0;
@@ -689,6 +693,7 @@ code {
   letter-spacing: .12em;
   text-transform: uppercase;
 }
+.sidebar-group-trigger { display: flex; width: 100%; min-height: 32px; align-items: center; justify-content: space-between; padding: 0; border: 0; color: var(--ink-muted); background: transparent; cursor: pointer; font-family: var(--mono); font-size: 8px; letter-spacing: .12em; text-align: left; text-transform: uppercase; }
 
 .sidebar-group > div { display: grid; gap: 2px; }
 
@@ -1219,7 +1224,7 @@ footer nav a { text-underline-offset: 4px; }
   .stage-alert { animation: layer-in 720ms var(--ease-out) 460ms both; }
   .stage-actions { animation: layer-in 720ms var(--ease-out) 580ms both; }
 
-  [data-reveal] {
+  [data-reveal].reveal-pending {
     opacity: 0;
     transform: translateY(34px);
     transition: opacity 760ms var(--ease-out), transform 760ms var(--ease-out);
@@ -1425,3 +1430,372 @@ footer nav a { text-underline-offset: 4px; }
   .install-primary,
   .install-import { border: 1px solid CanvasText; }
 }
+
+/* Prototype pass: the docs surface uses a quiet editorial grid with a single navy signal. */
+.brand-logo { display: block; }
+.brand-mark {
+  display: grid;
+  width: 34px;
+  height: 34px;
+  place-items: center;
+  border: 1px solid var(--brand);
+  color: var(--paper);
+  background: var(--brand);
+  font-family: var(--display);
+  font-size: 23px;
+  line-height: 1;
+}
+.brand-name {
+  margin-left: 10px;
+  color: var(--ink);
+  font-family: var(--sans);
+  font-size: 14px;
+  font-weight: 650;
+  letter-spacing: -.02em;
+}
+.primary-nav a.active { color: var(--brand); }
+.primary-nav a.active::after { transform: scaleX(1); transform-origin: left; }
+.theme-sun { color: var(--brand); }
+.theme-moon { color: var(--ink-muted); }
+.header-actions .ds-switch-copy { display: none; }
+.landing-page { border-bottom: 1px solid var(--hairline-strong); }
+.hero {
+  min-height: min(620px, calc(100dvh - var(--header-height)));
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  padding-top: 24px;
+  padding-bottom: 56px;
+}
+.hero h1 { max-width: 700px; font-size: clamp(64px, 7vw, 112px); letter-spacing: -.075em; line-height: .84; }
+.hero h1 em { color: var(--ink); font-style: normal; }
+.hero-copy { max-width: 490px; font-size: 17px; }
+.hero-actions { margin-top: 28px; }
+.hero-stage { min-height: 510px; }
+.hero-stage::before,
+.hero-stage::after { display: none; }
+.reference-desk {
+  position: absolute;
+  inset: 7% 3% 3% 8%;
+  display: grid;
+  grid-template-rows: auto auto 1fr auto;
+  border: 1px solid var(--hairline-strong);
+  background: var(--surface);
+  box-shadow: 14px 14px 0 color-mix(in srgb, var(--brand) 12%, transparent);
+  transform: rotate(1.2deg);
+}
+.desk-header,
+.desk-footer { display: flex; align-items: center; justify-content: space-between; gap: 18px; padding: 18px 22px; }
+.desk-header { border-bottom: 1px solid var(--hairline); }
+.desk-header strong { font-family: var(--display); font-size: 25px; font-weight: 500; letter-spacing: -.03em; }
+.desk-header > div { display: flex; gap: 13px; color: var(--brand); }
+.desk-tabs { padding: 0 22px; border-bottom: 1px solid var(--hairline); }
+.desk-tabs .ds-tabs { width: 100%; }
+.desk-tabs .ds-tab-list { justify-content: space-between; border-bottom: 0; }
+.desk-tabs .ds-tab-list button { min-width: 28%; }
+.desk-tabs .ds-tab-panel { position: absolute; width: 1px; height: 1px; padding: 0; overflow: hidden; clip: rect(0 0 0 0); border: 0; }
+.desk-body { display: grid; align-content: center; gap: 16px; padding: 32px 22px; }
+.density-line { display: flex; align-items: baseline; justify-content: space-between; gap: 18px; }
+.density-line span,
+.density-labels,
+.desk-footer,
+.preview-density span { color: var(--ink-muted); font-family: var(--mono); font-size: 9px; letter-spacing: .08em; text-transform: uppercase; }
+.density-line strong { color: var(--brand); font-family: var(--sans); font-size: 12px; font-weight: 600; }
+.density-labels { display: flex; justify-content: space-between; margin-top: -10px; font-size: 8px; }
+.verified-alert { margin-top: 18px; }
+.verified-alert .ds-alert { border-color: color-mix(in srgb, var(--success) 50%, var(--hairline)); }
+.desk-footer { border-top: 1px solid var(--hairline); }
+.desk-footer span { display: inline-flex; align-items: center; gap: 8px; }
+.desk-footer svg { color: var(--brand); }
+.desk-footer code { color: var(--ink); font-size: 10px; }
+.proof-rail { padding-bottom: 0; }
+.proof-rail dl > div { justify-content: flex-start; gap: 12px; }
+.proof-rail dl > div > svg { color: var(--brand); flex: 0 0 auto; }
+.proof-rail dt { margin-right: auto; }
+.proof-rail dd { font-family: var(--sans); font-size: 17px; font-weight: 650; }
+.foundation-section,
+.install-section { width: min(100%, var(--content-max)); margin: 0 auto; padding: clamp(82px, 9vw, 132px) var(--page-gutter); scroll-margin-top: calc(var(--header-height) + 18px); }
+.reference-page { width: min(100%, var(--page-max)); margin: 0 auto; padding: clamp(82px, 9vw, 132px) var(--page-gutter); scroll-margin-top: calc(var(--header-height) + 18px); }
+.foundation-section { padding-top: 52px; }
+.reference-page { padding-top: 32px; }
+.foundation-heading { display: flex; max-width: none; align-items: end; justify-content: space-between; }
+.foundation-heading h2 { max-width: 620px; }
+.foundation-grid { display: grid; grid-template-columns: 1fr 1.25fr 1fr .7fr; gap: clamp(22px, 3vw, 48px); }
+.foundation-group { padding-top: 18px; border-top: 1px solid var(--hairline-strong); }
+.foundation-group h3 { margin: 0 0 15px; color: var(--ink-muted); font-family: var(--mono); font-size: 9px; font-weight: 400; letter-spacing: .12em; text-transform: uppercase; }
+.swatch-row { display: grid; grid-template-columns: repeat(auto-fit, minmax(28px, 1fr)); gap: 7px; }
+.swatch-item { display: grid; gap: 8px; }
+.swatch-item > span { display: block; min-height: 62px; border: 1px solid color-mix(in srgb, var(--ink) 13%, var(--hairline)); }
+.swatch-item code { color: var(--ink-muted); font-size: 9px; }
+.reference-page { border-top: 1px solid var(--hairline-strong); }
+.reference-breadcrumb { margin-bottom: 26px; }
+.reference-breadcrumb a { display: inline-flex; align-items: center; gap: 7px; color: var(--ink-muted); font-family: var(--mono); font-size: 9px; letter-spacing: .08em; text-decoration: none; text-transform: uppercase; }
+.reference-breadcrumb a:hover { color: var(--brand); }
+.reference-header h3 { margin: 0; font-family: var(--display); font-size: clamp(48px, 6vw, 84px); font-weight: 500; letter-spacing: -.06em; line-height: .9; }
+.reference-header > div > p:last-child { max-width: 650px; margin-top: 20px; }
+.preview-panel,
+.contract-panel,
+.example-panel { box-shadow: 8px 8px 0 color-mix(in srgb, var(--brand) 7%, transparent); }
+.preview-panel > header h2,
+.contract-panel > header h2,
+.example-panel > header h2 { margin: 0; font-family: var(--sans); font-size: 11px; font-weight: 650; letter-spacing: .08em; text-transform: uppercase; }
+.preview-density { display: flex; min-width: min(300px, 45%); align-items: center; gap: 9px; }
+.preview-density input { width: 120px; accent-color: var(--brand); }
+.preview-density svg { color: var(--brand); }
+.contract-list { display: grid; }
+.contract-row { display: grid; grid-template-columns: 28px 76px minmax(0, 1fr) 18px; align-items: start; gap: 12px; min-width: 0; padding: 17px 16px; border-bottom: 1px solid var(--hairline); }
+.contract-row:last-child { border-bottom: 0; }
+.contract-icon { color: var(--brand); }
+.contract-row strong { padding-top: 2px; font-family: var(--sans); font-size: 11px; font-weight: 650; }
+.contract-row p { min-width: 0; margin: 0; color: var(--ink-soft); font-size: 13px; line-height: 1.5; }
+.contract-row p code { background: color-mix(in srgb, var(--brand-tint) 62%, transparent); }
+.contract-row > svg { margin-top: 2px; color: var(--ink-muted); }
+.example-panel pre { min-height: 235px; background: color-mix(in srgb, var(--brand-tint) 20%, var(--paper)); }
+.install-section { border-top: 1px solid var(--hairline-strong); }
+
+.components-index,
+.release-page {
+  width: min(100%, var(--content-max));
+  margin: 0 auto;
+  padding: clamp(72px, 8vw, 118px) var(--page-gutter) 132px;
+}
+
+.components-index:focus,
+.release-page:focus { outline: none; }
+
+.components-index-heading,
+.release-heading {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: end;
+  gap: 32px;
+  padding-bottom: 42px;
+  border-bottom: 1px solid var(--hairline-strong);
+}
+
+.components-index-heading h1,
+.release-heading h1 {
+  max-width: 720px;
+  margin: 0;
+  font-family: var(--display);
+  font-size: clamp(64px, 8vw, 112px);
+  font-weight: 500;
+  letter-spacing: -.075em;
+  line-height: .84;
+}
+
+.components-index-heading p:last-child,
+.release-heading p:last-child {
+  max-width: 620px;
+  margin: 22px 0 0;
+  color: var(--ink-soft);
+  font-size: 17px;
+  line-height: 1.6;
+}
+
+.components-index-search {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 12px;
+  min-height: 58px;
+  margin: 34px 0 70px;
+  padding: 0 16px;
+  border: 1px solid var(--hairline-strong);
+  color: var(--brand);
+  background: var(--surface);
+}
+
+.components-index-search:focus-within {
+  border-color: var(--brand);
+  outline: var(--focus-ring);
+  outline-offset: 3px;
+}
+
+.components-index-search input {
+  min-width: 0;
+  border: 0;
+  outline: 0;
+  color: var(--ink);
+  background: transparent;
+  font-size: 15px;
+}
+
+.components-index-search input::placeholder { color: var(--ink-muted); opacity: 1; }
+.components-index-search > span:last-child { color: var(--ink-muted); font-family: var(--mono); font-size: 9px; letter-spacing: .08em; }
+
+.components-index-groups { display: grid; gap: 54px; }
+
+.components-index-group > header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 20px;
+  margin-bottom: 12px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid var(--hairline-strong);
+}
+
+.components-index-group > header h2 {
+  margin: 0;
+  color: var(--ink-muted);
+  font-family: var(--mono);
+  font-size: 10px;
+  font-weight: 400;
+  letter-spacing: .12em;
+  text-transform: uppercase;
+}
+
+.components-index-group > header span { color: var(--brand); font-family: var(--mono); font-size: 10px; }
+.components-index-list { display: grid; }
+
+.component-index-item {
+  display: grid;
+  grid-template-columns: minmax(190px, .65fr) minmax(0, 1.35fr) auto;
+  align-items: center;
+  gap: 22px;
+  min-height: 78px;
+  padding: 13px 10px;
+  border-bottom: 1px solid var(--hairline);
+  color: var(--ink);
+  text-decoration: none;
+  transition: color var(--duration-ui) var(--ease-out), background-color var(--duration-ui) var(--ease-out), transform var(--duration-fast) var(--ease-out);
+}
+
+.component-index-item:first-child { border-top: 1px solid var(--hairline); }
+.component-index-item:hover,
+.component-index-item:focus-visible { color: var(--brand); background: var(--brand-tint); transform: translateX(3px); }
+.component-index-item > span:first-child { display: grid; gap: 4px; }
+.component-index-item strong { font-family: var(--sans); font-size: 14px; font-weight: 650; }
+.component-index-item small { color: var(--ink-muted); font-family: var(--mono); font-size: 8px; letter-spacing: .08em; text-transform: uppercase; }
+.component-index-item > span:nth-child(2) { color: var(--ink-soft); font-size: 13px; line-height: 1.45; }
+.component-index-item svg { color: var(--brand); }
+
+.components-index-empty,
+.release-policy {
+  display: grid;
+  align-items: center;
+  gap: 12px;
+  border: 1px dashed var(--hairline-strong);
+  color: var(--ink-muted);
+}
+
+.components-index-empty { min-height: 250px; place-items: center; align-content: center; text-align: center; }
+.components-index-empty strong { color: var(--ink); font-size: 17px; }
+.components-index-empty span { font-size: 14px; }
+
+.release-heading { align-items: start; }
+.release-signal { display: grid; min-width: 160px; justify-items: start; gap: 8px; padding: 18px 0 0 18px; border-left: 1px solid var(--hairline-strong); color: var(--brand); }
+.release-signal span { color: var(--ink-muted); font-family: var(--mono); font-size: 9px; letter-spacing: .1em; text-transform: uppercase; }
+.release-signal strong { color: var(--ink); font-family: var(--display); font-size: 31px; font-weight: 500; letter-spacing: -.04em; }
+.release-timeline { display: grid; margin-top: 62px; }
+.release-entry { display: grid; grid-template-columns: 80px minmax(0, 760px); gap: 20px; padding: 0 0 48px; }
+.release-marker { position: relative; display: flex; justify-content: center; color: var(--brand); font-family: var(--mono); font-size: 9px; }
+.release-marker::after { position: absolute; top: 25px; bottom: -48px; left: 50%; width: 1px; background: var(--hairline-strong); content: ''; }
+.release-entry:last-child { padding-bottom: 0; }
+.release-entry:last-child .release-marker::after { display: none; }
+.release-marker span { display: grid; width: 30px; height: 30px; place-items: center; border: 1px solid var(--brand); background: var(--paper); }
+.release-entry-copy { border-top: 1px solid var(--hairline-strong); }
+.release-entry-copy > header { display: flex; align-items: start; justify-content: space-between; gap: 20px; padding: 18px 0 16px; }
+.release-entry-copy > header p { margin: 0 0 8px; color: var(--brand); font-family: var(--mono); font-size: 9px; letter-spacing: .1em; text-transform: uppercase; }
+.release-entry-copy h2 { margin: 0; font-family: var(--display); font-size: clamp(32px, 4vw, 52px); font-weight: 500; letter-spacing: -.055em; line-height: .9; }
+.release-entry-copy > header > span { padding: 7px 8px; border: 1px solid var(--hairline); color: var(--ink-muted); font-family: var(--mono); font-size: 8px; letter-spacing: .08em; text-transform: uppercase; }
+.release-entry-copy ul { display: grid; gap: 10px; margin: 0; padding: 0 0 0 18px; color: var(--ink-soft); font-size: 15px; line-height: 1.6; }
+.release-entry-copy li::marker { color: var(--brand); }
+.release-policy { grid-template-columns: auto minmax(0, 1fr) auto; margin-top: 70px; padding: 20px; border-style: solid; background: color-mix(in srgb, var(--brand-tint) 28%, var(--paper)); }
+.release-policy > svg { color: var(--brand); }
+.release-policy strong { color: var(--ink); font-size: 14px; }
+.release-policy p { max-width: 620px; margin: 6px 0 0; color: var(--ink-soft); font-size: 13px; line-height: 1.5; }
+.release-policy a { display: inline-flex; align-items: center; gap: 8px; color: var(--brand); font-family: var(--mono); font-size: 9px; letter-spacing: .08em; text-decoration: none; text-transform: uppercase; }
+
+.sidebar-group > div > a {
+  display: block;
+  min-height: 34px;
+  padding: 9px 10px;
+  border-left: 2px solid transparent;
+  color: var(--ink-soft);
+  font-family: var(--sans);
+  font-size: 11px;
+  text-decoration: none;
+  transition: border-color var(--duration-fast) var(--ease-out), color var(--duration-fast) var(--ease-out), background-color var(--duration-ui) var(--ease-out), transform var(--duration-fast) var(--ease-out);
+}
+.sidebar-group > div > a:hover,
+.sidebar-group > div > a:focus-visible { color: var(--ink); background: color-mix(in srgb, var(--brand-tint) 55%, transparent); transform: translateX(2px); }
+.sidebar-group > div > a.selected { border-left-color: var(--brand); color: var(--brand); background: var(--brand-tint); }
+.reference-header h1 { margin: 0; font-family: var(--display); font-size: clamp(48px, 6vw, 84px); font-weight: 500; letter-spacing: -.06em; line-height: .9; }
+
+@media (max-width: 900px) {
+  .header-inner { grid-template-columns: auto minmax(150px, 1fr) auto; }
+  .primary-nav { display: none; }
+  .mobile-menu-button { display: inline-flex; align-items: center; justify-content: center; }
+  .hero { grid-template-columns: 1fr; }
+  .hero-stage { width: min(720px, 100%); min-height: 520px; margin-inline: auto; }
+  .reference-lower { grid-template-columns: 1fr; }
+  .example-panel { position: static; }
+}
+
+@media (max-width: 680px) {
+  .header-inner { grid-template-columns: auto 1fr auto; padding-inline: 16px; }
+  .brand-name { font-size: 13px; }
+  .header-actions { gap: 6px; }
+  .theme-sun, .theme-moon { display: none; }
+  .hero { min-height: auto; gap: 28px; padding: 26px 20px 56px; }
+  .hero h1 { font-size: clamp(48px, 12.5vw, 54px); }
+  .hero h1 em { white-space: nowrap; }
+  .hero-copy { margin-top: 22px; font-size: 16px; }
+  .hero-actions { align-items: flex-start; flex-direction: row; margin-top: 24px; }
+  .hero-actions > * { width: auto; justify-content: center; }
+  .hero-actions .ds-link { display: none; }
+  .hero-stage { min-height: 340px; }
+  .reference-desk { inset: 3% 0 1% 3%; transform: none; }
+  .desk-header, .desk-footer { padding-inline: 16px; }
+  .desk-header strong { font-size: 21px; }
+  .desk-tabs { padding-inline: 16px; }
+  .desk-body { gap: 10px; padding: 18px 16px; }
+  .verified-alert { margin-top: 8px; }
+  .desk-footer { flex-wrap: nowrap; padding-block: 13px; }
+  .proof-rail { padding-inline: 20px; }
+  .proof-rail dl { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .proof-rail dl > div { min-height: 82px; padding-inline: 12px; }
+  .foundation-section, .install-section, .reference-page { padding-inline: 20px; padding-top: 82px; padding-bottom: 88px; }
+  .reference-page { padding-top: 28px; }
+  .foundation-heading { align-items: start; flex-direction: row; }
+  .foundation-grid { grid-template-columns: 1fr 1.15fr .85fr .75fr; gap: 14px; }
+  .foundation-group { min-width: 0; }
+  .foundation-group h3 { font-size: 8px; }
+  .swatch-row { grid-template-columns: repeat(auto-fit, minmax(9px, 1fr)); gap: 4px; }
+  .swatch-item > span { min-height: 54px; }
+  .swatch-item code { font-size: 7px; }
+  .mobile-component-select { display: grid; position: relative; min-height: 58px; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: 13px; margin-bottom: 28px; padding: 0 16px; border: 1px solid var(--hairline-strong); background: var(--surface); }
+  .mobile-component-select > svg:first-child { color: var(--brand); }
+  .mobile-component-select > svg:last-child { pointer-events: none; }
+  .mobile-component-select label { color: var(--ink); font-family: var(--sans); font-size: 15px; }
+  .mobile-component-select select { position: absolute; inset: 0; width: 100%; height: 100%; opacity: 0; cursor: pointer; }
+  .reference-sidebar { display: none; }
+  .reference-shell { display: block; }
+  .reference-header { grid-template-columns: minmax(0, 1fr) auto; gap: 12px; }
+  .reference-header h3 { font-size: clamp(44px, 11.5vw, 52px); }
+  .reference-version { width: max-content; margin-top: 4px; }
+  .preview-panel > header { align-items: flex-start; flex-direction: column; padding-block: 14px; }
+  .preview-density { width: 100%; min-width: 0; }
+  .preview-density input { flex: 1; width: auto; }
+  .preview-canvas { min-height: 310px; padding: 22px 16px; }
+  .contract-row { grid-template-columns: 25px minmax(0, 1fr) 18px; gap: 10px; }
+  .contract-row strong { grid-column: 2; }
+  .contract-row p { grid-column: 2 / -1; }
+  .contract-row > svg { grid-column: 3; grid-row: 1; }
+  footer { padding-inline: 20px; }
+  .components-index,
+  .release-page { padding-inline: 20px; padding-top: 72px; padding-bottom: 90px; }
+  .components-index-heading,
+  .release-heading { grid-template-columns: 1fr; gap: 24px; padding-bottom: 34px; }
+  .components-index-heading h1,
+  .release-heading h1 { font-size: clamp(58px, 18vw, 78px); }
+  .components-index-heading p:last-child,
+  .release-heading p:last-child { font-size: 16px; }
+  .components-index-search { margin: 24px 0 48px; }
+  .component-index-item { grid-template-columns: minmax(0, 1fr) auto; gap: 12px; }
+  .component-index-item > span:nth-child(2) { display: none; }
+  .release-signal { min-width: 0; padding: 16px 0 0; border-top: 1px solid var(--hairline-strong); border-left: 0; }
+  .release-entry { grid-template-columns: 44px minmax(0, 1fr); gap: 10px; }
+  .release-policy { grid-template-columns: auto minmax(0, 1fr); }
+  .release-policy a { grid-column: 2; }
+}
diff --git a/apps/docs/src/lib/ComponentPreview.svelte b/apps/docs/src/lib/ComponentPreview.svelte
index d064d9d..5afd348 100644
--- a/apps/docs/src/lib/ComponentPreview.svelte
+++ b/apps/docs/src/lib/ComponentPreview.svelte
@@ -29,7 +29,7 @@
     WeBaseToast,
     WeBaseTooltip
   } from '@webaseui/svelte';
-  import type { ComponentName } from './reference';
+  import type { ComponentName } from './data/reference';
 
   interface Props {
     name: ComponentName;
@@ -43,8 +43,8 @@
     { title: 'Release gate', content: 'Cross-browser and accessibility checks run before publish.' }
   ];
   const breadcrumbItems = [
-    { label: 'Docs', href: '#top' },
-    { label: 'Components', href: '#components' },
+    { label: 'Docs', href: '/' },
+    { label: 'Components', href: '/components' },
     { label: 'Button' }
   ];
   const selectOptions = [
@@ -90,11 +90,12 @@
   {:else if name === 'WeBaseBreadcrumbs'}
     <WeBaseBreadcrumbs items={breadcrumbItems} />
   {:else if name === 'WeBaseButton'}
-    <div class="preview-row">
-      <WeBaseButton label="Save changes" variant="ink" icon="check" />
-      <WeBaseButton label="Open guide" variant="outline" icon="arrow-up-right" />
-      <WeBaseButton label="Add note" variant="quiet" icon="plus" />
-      <WeBaseButton label="Working" variant="text" loading />
+    <div class="button-specimen-grid">
+      <div><span>Primary</span><WeBaseButton label="Save changes" variant="ink" /></div>
+      <div><span>Outline</span><WeBaseButton label="Cancel" variant="outline" /></div>
+      <div><span>Disabled</span><WeBaseButton label="Not available" variant="outline" disabled /></div>
+      <div><span>Loading</span><WeBaseButton label="Saving..." loadingLabel="Saving..." variant="ink" loading /></div>
+      <div><span>Icon leading</span><WeBaseButton label="Download" variant="ink" icon="arrow-down" /></div>
     </div>
   {:else if name === 'WeBaseCard'}
     <div class="preview-card-width">
@@ -140,8 +141,8 @@
     </div>
   {:else if name === 'WeBaseLink'}
     <div class="preview-row">
-      <WeBaseLink href="#components" label="Component index" variant="back" />
-      <WeBaseLink href="#install" label="Install" variant="action" />
+      <WeBaseLink href="/components" label="Component index" variant="back" />
+      <WeBaseLink href="/#install" label="Install" variant="action" />
       <WeBaseLink href="https://github.com/WeOpen/WeBaseUI" label="Source" variant="inline" />
     </div>
   {:else if name === 'WeBaseLoader'}
@@ -174,7 +175,7 @@
     <div class="preview-row">
       <WeBaseTag label="Navigation" count="05" selected />
       <WeBaseTag label="Feedback" count="06" variant="brand" />
-      <WeBaseTag label="Overlay" href="#components" variant="outline" />
+      <WeBaseTag label="Overlay" href="/components" variant="outline" />
     </div>
   {:else if name === 'WeBaseTabs'}
     <WeBaseTabs items={['Contract', 'Behavior', 'Release']} panels={['Public props and bindings.', 'Documented interaction boundaries.', 'Versioned change policy.']} bind:active={tab} />
@@ -196,6 +197,9 @@
 <style>
   .component-preview { min-width: 0; }
   .preview-row { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
+  .button-specimen-grid { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 22px 18px; }
+  .button-specimen-grid > div { display: grid; gap: 9px; justify-items: start; }
+  .button-specimen-grid > div > span { color: var(--ink-muted); font-family: var(--mono); font-size: 9px; letter-spacing: .08em; text-transform: uppercase; }
   .preview-stack { display: grid; gap: 16px; }
   .preview-card-width { width: min(520px, 100%); }
   .preview-field-width { width: min(460px, 100%); }
@@ -205,7 +209,14 @@
   .icon-shelf > span { display: grid; min-height: 92px; place-items: center; align-content: center; gap: 10px; border: 1px solid var(--hairline); color: var(--brand); background: color-mix(in srgb, var(--brand-tint) 26%, var(--surface)); }
   .icon-shelf small { color: var(--ink-muted); font-family: var(--mono); font-size: 9px; }
 
+  @media (max-width: 1100px) and (min-width: 681px) {
+    .button-specimen-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+  }
+
   @media (max-width: 680px) {
+    .button-specimen-grid { grid-template-columns: 1fr; }
+    .button-specimen-grid > div { justify-items: stretch; text-align: center; }
+    .button-specimen-grid > div :global(.ds-button) { width: 100%; justify-content: center; }
     .icon-shelf { grid-template-columns: repeat(2, minmax(0, 1fr)); }
     .icon-shelf > span:last-child { grid-column: 1 / -1; }
   }
diff --git a/apps/docs/src/lib/actions/reveal.ts b/apps/docs/src/lib/actions/reveal.ts
new file mode 100644
index 0000000..2403522
--- /dev/null
+++ b/apps/docs/src/lib/actions/reveal.ts
@@ -0,0 +1,37 @@
+export function reveal(node: HTMLElement) {
+  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  let observer: IntersectionObserver | undefined;
+  let fallbackTimer: number | undefined;
+  let revealed = false;
+
+  const show = () => {
+    if (revealed) return;
+    revealed = true;
+    node.classList.remove('reveal-pending');
+    node.classList.add('is-visible');
+    observer?.disconnect();
+    window.clearTimeout(fallbackTimer);
+  };
+
+  node.classList.add('reveal-pending');
+
+  if (reducedMotion || !('IntersectionObserver' in window)) {
+    show();
+  } else {
+    observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) show();
+    }, { threshold: 0.14 });
+    observer.observe(node);
+
+    const bounds = node.getBoundingClientRect();
+    if (bounds.top < window.innerHeight && bounds.bottom > 0) show();
+    else fallbackTimer = window.setTimeout(show, 1600);
+  }
+
+  return {
+    destroy() {
+      observer?.disconnect();
+      window.clearTimeout(fallbackTimer);
+    }
+  };
+}
diff --git a/apps/docs/src/lib/components/ComponentDetail.svelte b/apps/docs/src/lib/components/ComponentDetail.svelte
new file mode 100644
index 0000000..753e628
--- /dev/null
+++ b/apps/docs/src/lib/components/ComponentDetail.svelte
@@ -0,0 +1,44 @@
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+  import { WeBaseIcon } from '@webaseui/svelte';
+  import ComponentPreview from '../ComponentPreview.svelte';
+  import { inlineParts, packageVersion, type ComponentReference } from '../data/reference.js';
+  import { copyText } from '../utils/clipboard.js';
+
+  interface Props {
+    component: ComponentReference;
+    onNavigate: (path: string) => void;
+  }
+
+  let { component, onNavigate }: Props = $props();
+  let density = $state(64);
+  let copied = $state(false);
+  let copyTimer: number | undefined;
+
+  const summary = $derived(component.name === 'WeBaseButton'
+    ? 'A focused action control with explicit visual and keyboard states.'
+    : component.summary);
+
+  async function copyExample() {
+    const source = `import { ${component.name} } from '@webaseui/svelte';\n\n${component.example}`;
+    if (!await copyText(source)) return;
+    copied = true;
+    window.clearTimeout(copyTimer);
+    copyTimer = window.setTimeout(() => (copied = false), 1800);
+  }
+
+  onDestroy(() => window.clearTimeout(copyTimer));
+</script>
+
+<article class="reference-detail" id={`component-${component.slug}`} data-selected-component={component.name} data-route-focus tabindex="-1">
+  <nav class="reference-breadcrumb" aria-label="Component breadcrumb"><a href="/components" onclick={(event) => { event.preventDefault(); onNavigate('/components'); }}><WeBaseIcon name="arrow-left" size={17} />All components</a></nav>
+  <header class="reference-header"><div><p>{component.group}</p><h1 id="reference-title">{component.name}</h1><p>{#each inlineParts(summary) as part}{#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}{/each}</p></div><span class="reference-version">v{packageVersion}</span></header>
+
+  <section class="preview-panel" aria-labelledby="preview-heading"><header><h2 id="preview-heading">Live specimen</h2><div class="preview-density"><span>Density</span><WeBaseIcon name="minus" size={18} /><input type="range" aria-label="Specimen density" min="20" max="90" bind:value={density} /><WeBaseIcon name="plus" size={18} /></div></header><div class="preview-canvas"><ComponentPreview name={component.name} /></div></section>
+
+  <div class="reference-lower">
+    <section class="contract-panel" aria-labelledby="contract-heading"><header><h2 id="contract-heading">Public contract</h2></header><div class="contract-list">{#each component.fields as field}<div class="contract-row"><span class="contract-icon">{#if field.label === 'Props'}<WeBaseIcon name="sliders-horizontal" size={22} />{:else if field.label === 'Events'}<WeBaseIcon name="zap" size={22} />{:else if field.label === 'Keyboard'}<WeBaseIcon name="keyboard" size={22} />{:else}<WeBaseIcon name="scan-square" size={22} />{/if}</span><strong>{field.label}</strong><p>{#each inlineParts(field.value) as part}{#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}{/each}</p><WeBaseIcon name="chevron-right" size={18} /></div>{/each}</div></section>
+
+    <section class="example-panel" aria-labelledby="example-heading"><header><h2 id="example-heading">Usage</h2><button type="button" aria-label={`Copy ${component.name} example`} onclick={copyExample}>{#if copied}<WeBaseIcon name="check" size={16} /> Copied{:else}<WeBaseIcon name="copy" size={16} /> Copy{/if}</button></header><pre role="region" aria-label={`${component.name} usage example`}><code>{`import { ${component.name} } from '@webaseui/svelte';\n\n${component.example}`}</code></pre></section>
+  </div>
+</article>
diff --git a/apps/docs/src/lib/components/ComponentSidebar.svelte b/apps/docs/src/lib/components/ComponentSidebar.svelte
new file mode 100644
index 0000000..a4bfc87
--- /dev/null
+++ b/apps/docs/src/lib/components/ComponentSidebar.svelte
@@ -0,0 +1,60 @@
+<script lang="ts">
+  import { WeBaseIcon } from '@webaseui/svelte';
+  import { components, groupOrder, type ComponentName } from '../data/reference.js';
+
+  interface Props {
+    selectedName: ComponentName;
+    onNavigate: (path: string) => void;
+  }
+
+  let { selectedName, onNavigate }: Props = $props();
+  let query = $state('');
+  let expandedGroup = $state<(typeof groupOrder)[number]>(components.find(({ name }) => name === selectedName)?.group ?? 'Action');
+
+  const filtered = $derived.by(() => {
+    const normalized = query.trim().toLocaleLowerCase();
+    if (!normalized) return components;
+    return components.filter(({ searchText }) => searchText.includes(normalized));
+  });
+
+  $effect(() => {
+    const component = components.find(({ name }) => name === selectedName);
+    if (component) expandedGroup = component.group;
+  });
+</script>
+
+<div class="mobile-component-select">
+  <WeBaseIcon name="grid-2x2" size={22} />
+  <label for="mobile-component">Choose a component</label>
+  <select id="mobile-component" value={selectedName} onchange={(event) => {
+    const component = components.find(({ name }) => name === event.currentTarget.value);
+    if (component) onNavigate(`/components/${component.slug}`);
+  }}>
+    {#each components as component}<option value={component.name}>{component.name}</option>{/each}
+  </select>
+  <WeBaseIcon name="chevron-down" size={20} />
+</div>
+
+<aside class="reference-sidebar" aria-label="Component index">
+  <label class="sidebar-search"><span class="visually-hidden">Filter components</span><WeBaseIcon name="search" size={18} /><input type="search" placeholder="Filter components" bind:value={query} /></label>
+  <p class="sidebar-count">{filtered.length} components</p>
+  <div class="sidebar-groups">
+    {#each groupOrder as group}
+      {@const groupComponents = filtered.filter((component) => component.group === group)}
+      {#if groupComponents.length > 0}
+        {@const groupOpen = expandedGroup === group || Boolean(query.trim())}
+        <section class="sidebar-group">
+          <button class="sidebar-group-trigger" type="button" aria-expanded={groupOpen} onclick={() => (expandedGroup = group)}>{group}<WeBaseIcon name={groupOpen ? 'chevron-down' : 'chevron-right'} size={14} /></button>
+          {#if groupOpen}
+            <div>
+              {#each groupComponents as component}
+                <a href={`/components/${component.slug}`} class:selected={selectedName === component.name} aria-current={selectedName === component.name ? 'page' : undefined} onclick={(event) => { event.preventDefault(); onNavigate(`/components/${component.slug}`); }}>{component.name}</a>
+              {/each}
+            </div>
+          {/if}
+        </section>
+      {/if}
+    {/each}
+    {#if filtered.length === 0}<p class="sidebar-empty">No components match this filter.</p>{/if}
+  </div>
+</aside>
diff --git a/apps/docs/src/lib/reference-utils.ts b/apps/docs/src/lib/data/reference-utils.ts
similarity index 100%
rename from apps/docs/src/lib/reference-utils.ts
rename to apps/docs/src/lib/data/reference-utils.ts
diff --git a/apps/docs/src/lib/reference.ts b/apps/docs/src/lib/data/reference.ts
similarity index 95%
rename from apps/docs/src/lib/reference.ts
rename to apps/docs/src/lib/data/reference.ts
index 5be3c79..07ae128 100644
--- a/apps/docs/src/lib/reference.ts
+++ b/apps/docs/src/lib/data/reference.ts
@@ -1,5 +1,5 @@
-import contractSource from '../../../../packages/webaseui-svelte/API_CONTRACT.md?raw';
-import packageSource from '../../../../packages/webaseui-svelte/package.json?raw';
+import contractSource from '../../../../../packages/webaseui-svelte/API_CONTRACT.md?raw';
+import packageSource from '../../../../../packages/webaseui-svelte/package.json?raw';
 import { inlineParts, parseFields, type ParsedContractField } from './reference-utils.js';
 
 export { inlineParts, parseFields } from './reference-utils.js';
@@ -89,7 +89,7 @@ const usageExamples: Record<ComponentName, string> = {
   WeBaseSkeleton: `<WeBaseSkeleton rows={3} media />`,
   WeBaseSlider: `<WeBaseSlider label="Density" bind:value />`,
   WeBaseSwitch: `<WeBaseSwitch label="Dark theme" bind:checked />`,
-  WeBaseTag: `<WeBaseTag label="Navigation" href="#components" count="05" />`,
+  WeBaseTag: `<WeBaseTag label="Navigation" href="/components" count="05" />`,
   WeBaseTabs: `<WeBaseTabs items={labels} panels={content} bind:active />`,
   WeBaseTextarea: `<WeBaseTextarea label="Notes" bind:value />`,
   WeBaseToast: `<WeBaseToast bind:open title="Saved locally" />`,
diff --git a/apps/docs/src/lib/layout/DocsFooter.svelte b/apps/docs/src/lib/layout/DocsFooter.svelte
new file mode 100644
index 0000000..4edd747
--- /dev/null
+++ b/apps/docs/src/lib/layout/DocsFooter.svelte
@@ -0,0 +1,26 @@
+<script lang="ts">
+  import { WeBaseIcon } from '@webaseui/svelte';
+
+  interface Props {
+    onNavigate: (path: string) => void;
+  }
+
+  let { onNavigate }: Props = $props();
+
+  function navigate(event: MouseEvent, path: string) {
+    event.preventDefault();
+    onNavigate(path);
+  }
+</script>
+
+<footer>
+  <a class="footer-brand" href="/" onclick={(event) => navigate(event, '/') }>
+    <img src="/logo.svg" alt="" width="30" height="32" />
+    <span>WeBaseUI</span>
+  </a>
+  <nav aria-label="Footer">
+    <a href="https://github.com/WeOpen/WeBaseUI">GitHub</a>
+    <a href="/components" onclick={(event) => navigate(event, '/components')}>Reference</a>
+    <span>MIT License</span>
+  </nav>
+</footer>
diff --git a/apps/docs/src/lib/layout/DocsHeader.svelte b/apps/docs/src/lib/layout/DocsHeader.svelte
new file mode 100644
index 0000000..664f63f
--- /dev/null
+++ b/apps/docs/src/lib/layout/DocsHeader.svelte
@@ -0,0 +1,66 @@
+<script lang="ts">
+  import { WeBaseIcon, WeBaseIconButton, WeBaseSwitch } from '@webaseui/svelte';
+
+  interface Props {
+    routeKind: 'landing' | 'components' | 'component' | 'release';
+    dark: boolean;
+    mobileNavOpen: boolean;
+    onNavigate: (path: string) => void;
+    onToggleMobile: () => void;
+    onToggleTheme: () => void;
+    onOpenSearch: (event?: EventTarget | null) => void;
+  }
+
+  let {
+    routeKind,
+    dark,
+    mobileNavOpen,
+    onNavigate,
+    onToggleMobile,
+    onToggleTheme,
+    onOpenSearch
+  }: Props = $props();
+
+  function navigate(event: MouseEvent, path: string) {
+    event.preventDefault();
+    onNavigate(path);
+  }
+</script>
+
+<header class="site-header">
+  <div class="header-inner">
+    <a class="brand" href="/" aria-label="WeBaseUI home" onclick={(event) => navigate(event, '/')}>
+      <img class="brand-logo" src="/logo.svg" alt="" width="38" height="41" />
+    </a>
+
+    <button class="search-trigger" type="button" aria-label="Search documentation" onclick={(event) => onOpenSearch(event.currentTarget)}>
+      <WeBaseIcon name="search" size={20} strokeWidth={1.6} />
+      <span>Search the contract</span>
+      <kbd>Ctrl K</kbd>
+    </button>
+
+    <nav class="primary-nav" aria-label="Documentation">
+      <a href="/components" class:active={routeKind === 'components' || routeKind === 'component'} onclick={(event) => navigate(event, '/components')}>Components</a>
+      <a href="/release" class:active={routeKind === 'release'} onclick={(event) => navigate(event, '/release')}>Release</a>
+    </nav>
+
+    <div class="header-actions">
+      <span class="theme-control">
+        <WeBaseIcon name="sun" size={18} class="theme-sun" />
+        <WeBaseSwitch label="Toggle dark theme" checked={dark} onchange={onToggleTheme} />
+        <WeBaseIcon name="moon" size={18} class="theme-moon" />
+      </span>
+      <button class="mobile-menu-button" type="button" aria-label={mobileNavOpen ? 'Close menu' : 'Menu'} aria-expanded={mobileNavOpen} aria-controls="mobile-navigation" onclick={onToggleMobile}>
+        <WeBaseIcon name={mobileNavOpen ? 'x' : 'menu'} size={27} />
+      </button>
+    </div>
+  </div>
+
+  {#if mobileNavOpen}
+    <nav class="mobile-navigation" id="mobile-navigation" aria-label="Mobile documentation">
+      <a href="/components" onclick={(event) => navigate(event, '/components')}>Components</a>
+      <a href="/release" onclick={(event) => navigate(event, '/release')}>Release</a>
+      <button type="button" onclick={(event) => onOpenSearch(event.currentTarget)}>Search components</button>
+    </nav>
+  {/if}
+</header>
diff --git a/apps/docs/src/lib/layout/SearchDialog.svelte b/apps/docs/src/lib/layout/SearchDialog.svelte
new file mode 100644
index 0000000..8e1a2af
--- /dev/null
+++ b/apps/docs/src/lib/layout/SearchDialog.svelte
@@ -0,0 +1,90 @@
+<script lang="ts">
+  import { WeBaseIcon, WeBaseIconButton } from '@webaseui/svelte';
+  import { components, inlineParts } from '../data/reference.js';
+
+  interface Props {
+    open: boolean;
+    onClose: () => void;
+    onNavigate: (path: string) => void;
+  }
+
+  let { open, onClose, onNavigate }: Props = $props();
+  let dialog = $state<HTMLDialogElement>();
+  let input = $state<HTMLInputElement>();
+  let query = $state('');
+
+  const results = $derived.by(() => {
+    const normalized = query.trim().toLocaleLowerCase();
+    if (!normalized) return components.slice(0, 8);
+    return components.filter(({ searchText }) => searchText.includes(normalized)).slice(0, 12);
+  });
+
+  $effect(() => {
+    if (!dialog) return;
+    if (open && !dialog.open) {
+      query = '';
+      dialog.showModal();
+      requestAnimationFrame(() => input?.focus());
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  });
+
+  function choose(slug: string) {
+    onClose();
+    onNavigate(`/components/${slug}`);
+  }
+</script>
+
+<dialog
+  class="search-dialog"
+  bind:this={dialog}
+  aria-labelledby="search-heading"
+  onclose={onClose}
+  onkeydown={(event) => {
+    if (event.key !== 'Escape') return;
+    event.preventDefault();
+    onClose();
+  }}
+  onclick={(event) => { if (event.target === dialog) onClose(); }}
+>
+  <div class="search-panel">
+    <header>
+      <div>
+        <p>Global search</p>
+        <h2 id="search-heading">Search the public contract</h2>
+      </div>
+      <WeBaseIconButton label="Close search" icon="x" onclick={onClose} />
+    </header>
+
+    <label class="search-input">
+      <span class="visually-hidden">Search components and API fields</span>
+      <WeBaseIcon name="search" size={20} />
+      <input bind:this={input} type="search" placeholder="Try dialog, binding, or form" bind:value={query} />
+      <kbd>Esc</kbd>
+    </label>
+
+    <div class="search-results" aria-live="polite">
+      <p>{query ? `${results.length} matches` : 'Browse components'}</p>
+      {#if results.length > 0}
+        <ul>
+          {#each results as component}
+            <li>
+              <button type="button" onclick={() => choose(component.slug)}>
+                <span><strong>{component.name}</strong><small>{component.group}</small></span>
+                <span>{#each inlineParts(component.summary) as part}{#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}{/each}</span>
+                <WeBaseIcon name="arrow-right" size={16} />
+              </button>
+            </li>
+          {/each}
+        </ul>
+      {:else}
+        <div class="search-empty">
+          <WeBaseIcon name="archive-x" size={24} />
+          <strong>No contract found</strong>
+          <span>Try a component name, prop, binding, or behavior.</span>
+        </div>
+      {/if}
+    </div>
+  </div>
+</dialog>
diff --git a/apps/docs/src/lib/pages/ComponentPage.svelte b/apps/docs/src/lib/pages/ComponentPage.svelte
new file mode 100644
index 0000000..9c73250
--- /dev/null
+++ b/apps/docs/src/lib/pages/ComponentPage.svelte
@@ -0,0 +1,19 @@
+<script lang="ts">
+  import ComponentDetail from '../components/ComponentDetail.svelte';
+  import ComponentSidebar from '../components/ComponentSidebar.svelte';
+  import type { ComponentReference } from '../data/reference.js';
+
+  interface Props {
+    component: ComponentReference;
+    onNavigate: (path: string) => void;
+  }
+
+  let { component, onNavigate }: Props = $props();
+</script>
+
+<section class="reference-page" aria-labelledby="reference-title">
+  <div class="reference-shell">
+    <ComponentSidebar selectedName={component.name} {onNavigate} />
+    <ComponentDetail {component} {onNavigate} />
+  </div>
+</section>
diff --git a/apps/docs/src/lib/pages/ComponentsPage.svelte b/apps/docs/src/lib/pages/ComponentsPage.svelte
new file mode 100644
index 0000000..2408691
--- /dev/null
+++ b/apps/docs/src/lib/pages/ComponentsPage.svelte
@@ -0,0 +1,58 @@
+<script lang="ts">
+  import { WeBaseIcon } from '@webaseui/svelte';
+  import { components, groupOrder, packageVersion } from '../data/reference.js';
+
+  interface Props {
+    onNavigate: (path: string) => void;
+  }
+
+  let { onNavigate }: Props = $props();
+  let query = $state('');
+  const filtered = $derived.by(() => {
+    const normalized = query.trim().toLocaleLowerCase();
+    if (!normalized) return components;
+    return components.filter(({ searchText }) => searchText.includes(normalized));
+  });
+</script>
+
+<section class="components-index" aria-labelledby="components-title" data-route-focus tabindex="-1">
+  <header class="components-index-heading">
+    <div>
+      <p class="section-label">Public reference</p>
+      <h1 id="components-title">Components.</h1>
+      <p>Browse the complete Svelte surface, then open a specimen to inspect its public contract, usage, and behavior.</p>
+    </div>
+    <span class="reference-version">v{packageVersion}</span>
+  </header>
+
+  <label class="components-index-search">
+    <span class="visually-hidden">Filter components</span>
+    <WeBaseIcon name="search" size={18} />
+    <input type="search" placeholder="Filter by name, group, or API field" bind:value={query} />
+    <span>{filtered.length} / {components.length}</span>
+  </label>
+
+  {#if filtered.length > 0}
+    <div class="components-index-groups">
+      {#each groupOrder as group}
+        {@const groupComponents = filtered.filter((component) => component.group === group)}
+        {#if groupComponents.length > 0}
+          <section class="components-index-group" aria-labelledby={`group-${group}`}>
+            <header><h2 id={`group-${group}`}>{group}</h2><span>{groupComponents.length.toString().padStart(2, '0')}</span></header>
+            <div class="components-index-list">
+              {#each groupComponents as component}
+                <a class="component-index-item" href={`/components/${component.slug}`} onclick={(event) => { event.preventDefault(); onNavigate(`/components/${component.slug}`); }}>
+                  <span><strong>{component.shortName}</strong><small>{component.name}</small></span>
+                  <span>{component.summary}</span>
+                  <WeBaseIcon name="arrow-up-right" size={18} />
+                </a>
+              {/each}
+            </div>
+          </section>
+        {/if}
+      {/each}
+    </div>
+  {:else}
+    <div class="components-index-empty"><WeBaseIcon name="archive-x" size={24} /><strong>No components match this filter</strong><span>Try a component name, prop, binding, or behavior.</span></div>
+  {/if}
+</section>
diff --git a/apps/docs/src/lib/pages/LandingPage.svelte b/apps/docs/src/lib/pages/LandingPage.svelte
new file mode 100644
index 0000000..c74d89c
--- /dev/null
+++ b/apps/docs/src/lib/pages/LandingPage.svelte
@@ -0,0 +1,116 @@
+<script lang="ts">
+  import {
+    WeBaseAlert,
+    WeBaseButton,
+    WeBaseIcon,
+    WeBaseLink,
+    WeBaseSlider,
+    WeBaseTabs
+  } from '@webaseui/svelte';
+  import { packageVersion } from '../data/reference.js';
+  import { copyText } from '../utils/clipboard.js';
+  import { reveal } from '../actions/reveal.js';
+
+  interface Props {
+    onNavigate: (path: string) => void;
+  }
+
+  let { onNavigate }: Props = $props();
+
+  const foundationGroups = [
+    { label: 'Neutral', values: ['0', '50', '100', '200', '300'], colors: ['#faf9f5', '#f5f4ed', '#e8e6dc', '#d8d5c9', '#b9b6ad'] },
+    { label: 'Navy', values: ['50', '100', '200', '300', '600', '900'], colors: ['#eef2f7', '#d6e0ed', '#afc2da', '#7696bb', '#2d5a8a', '#1b365d'] },
+    { label: 'Ink', values: ['900', '700', '500', '300', '100'], colors: ['#141413', '#504e49', '#85837d', '#c9c7be', '#faf9f5'] },
+    { label: 'Success', values: ['50', '200', '600'], colors: ['#edf5f0', '#9bc8b1', '#3f7658'] }
+  ];
+  const installCommand = 'npm install @webaseui/core @webaseui/svelte';
+  const importCode = `import '@webaseui/core/theme.css';
+import { WeBaseButton } from '@webaseui/svelte';`;
+
+  let copiedTarget = $state('');
+  let heroTab = $state(1);
+  let heroDensity = $state(64);
+  let copyTimer: number | undefined;
+
+  async function copy(key: string, text: string) {
+    if (!await copyText(text)) return;
+    copiedTarget = key;
+    window.clearTimeout(copyTimer);
+    copyTimer = window.setTimeout(() => {
+      if (copiedTarget === key) copiedTarget = '';
+    }, 1800);
+  }
+</script>
+
+<section class="landing-page" data-route-focus tabindex="-1">
+  <section class="hero" aria-labelledby="hero-title">
+    <div class="hero-copy-block">
+      <h1 id="hero-title"><span>Build with</span><em>a visible contract.</em></h1>
+      <p class="hero-copy">Accessible Svelte 5 components, named tokens, and a public contract designed to move between products.</p>
+      <div class="hero-actions">
+        <WeBaseButton label="Explore reference" variant="ink" icon="arrow-right" onclick={() => onNavigate('/components/button')} />
+        <WeBaseLink href="#install" label="Install packages" variant="action" icon="arrow-down" />
+      </div>
+    </div>
+
+    <div class="hero-stage" aria-label="Interactive WeBaseUI specimen">
+      <h2 class="visually-hidden">Interactive component specimen</h2>
+      <article class="reference-desk">
+        <header class="desk-header">
+          <strong>Reference desk</strong>
+          <div><WeBaseIcon name="book-open" size={22} /><WeBaseIcon name="code-2" size={22} /></div>
+        </header>
+        <div class="desk-tabs">
+          <WeBaseTabs items={['Contract', 'Preview', 'Release']} panels={['Public behavior', 'Real components', 'Versioned changes']} bind:active={heroTab} />
+        </div>
+        <div class="desk-body">
+          <div class="density-line"><span>Interface density</span><strong>Comfortable</strong></div>
+          <WeBaseSlider label="Interface density" bind:value={heroDensity} />
+          <div class="density-labels"><span>Compact</span><span>Spacious</span></div>
+          <div class="verified-alert"><WeBaseAlert title="Contract verified" message="" tone="success" /></div>
+        </div>
+        <footer class="desk-footer">
+          <span><WeBaseIcon name="box" size={22} />28 public exports</span>
+          <span><WeBaseIcon name="server" size={22} />SSR ready</span>
+          <code>v{packageVersion}</code>
+        </footer>
+      </article>
+    </div>
+  </section>
+
+  <section class="proof-rail" aria-label="Library baseline" data-reveal use:reveal>
+    <dl>
+      <div><WeBaseIcon name="grid-2x2" size={25} /><dt>Components</dt><dd>28</dd></div>
+      <div><WeBaseIcon name="code-2" size={25} /><dt>Runtime</dt><dd>Svelte 5</dd></div>
+      <div><WeBaseIcon name="box" size={25} /><dt>Engines</dt><dd>3</dd></div>
+      <div><WeBaseIcon name="file-text" size={25} /><dt>License</dt><dd>MIT</dd></div>
+    </dl>
+  </section>
+
+  <section id="tokens" class="foundation-section" data-reveal use:reveal>
+    <div class="section-heading foundation-heading">
+      <div><h2>Foundation</h2></div>
+      <WeBaseLink href="/components" label="View components" variant="action" icon="arrow-right" onclick={(event) => { event.preventDefault(); onNavigate('/components'); }} />
+    </div>
+    <div class="foundation-grid">
+      {#each foundationGroups as group}
+        <section class="foundation-group" aria-label={`${group.label} color tokens`}>
+          <h3>{group.label}</h3>
+          <div class="swatch-row">
+            {#each group.values as value, index}
+              <div class="swatch-item"><span style={`background: ${group.colors[index]}`}></span><code>{value}</code></div>
+            {/each}
+          </div>
+        </section>
+      {/each}
+    </div>
+  </section>
+
+  <section id="install" class="install-section" data-reveal use:reveal>
+    <div class="section-heading"><p class="section-label">Start here</p><h2>Install the boundary.</h2><p>Tokens and Svelte components are versioned independently, then verified together in a clean consumer.</p></div>
+    <div class="install-composition">
+      <article class="install-primary"><header><span>Packages</span><button type="button" aria-label="Copy install command" onclick={() => copy('install', installCommand)}>{#if copiedTarget === 'install'}<WeBaseIcon name="check" size={14} /> Copied{:else}<WeBaseIcon name="copy" size={14} /> Copy{/if}</button></header><pre role="region" aria-label="Installation command"><code>{installCommand}</code></pre><p>@webaseui/svelte v{packageVersion}</p></article>
+      <article class="install-import"><header><span>Import</span><button type="button" aria-label="Copy import example" onclick={() => copy('import', importCode)}>{#if copiedTarget === 'import'}<WeBaseIcon name="check" size={14} /> Copied{:else}<WeBaseIcon name="copy" size={14} /> Copy{/if}</button></header><pre role="region" aria-label="Import example"><code>{importCode}</code></pre></article>
+    </div>
+  </section>
+</section>
diff --git a/apps/docs/src/lib/pages/ReleasePage.svelte b/apps/docs/src/lib/pages/ReleasePage.svelte
new file mode 100644
index 0000000..d211c18
--- /dev/null
+++ b/apps/docs/src/lib/pages/ReleasePage.svelte
@@ -0,0 +1,45 @@
+<script lang="ts">
+  import { WeBaseIcon } from '@webaseui/svelte';
+  import { packageVersion } from '../data/reference.js';
+
+  interface Props {
+    onNavigate: (path: string) => void;
+  }
+
+  let { onNavigate }: Props = $props();
+
+  const releases = [
+    { version: packageVersion, date: 'Current', label: 'Patch', notes: ['Improved WeBaseTag small-text contrast in light and dark themes.'] },
+    { version: '0.3.1', date: 'Previous', label: 'Patch', notes: ['Declared the package side-effect free so bundlers can tree-shake unused components, styles, and icon code from package-root imports.'] },
+    { version: '0.3.0', date: 'Navigation', label: 'Minor', notes: ['Added semantic WeBaseLink and WeBaseTag navigation primitives for application migrations.'] }
+  ];
+</script>
+
+<section class="release-page" aria-labelledby="release-title" data-route-focus tabindex="-1">
+  <header class="release-heading">
+    <div>
+      <p class="section-label">Version history</p>
+      <h1 id="release-title">Release.</h1>
+      <p>Small, inspectable changes keep the component contract easy to trust. Read the current channel, then follow the public reference for implementation details.</p>
+    </div>
+    <div class="release-signal"><WeBaseIcon name="circle-check" size={22} /><span>Current channel</span><strong>v{packageVersion}</strong></div>
+  </header>
+
+  <div class="release-timeline">
+    {#each releases as release, index}
+      <article class="release-entry">
+        <div class="release-marker" aria-hidden="true"><span>{String(index + 1).padStart(2, '0')}</span></div>
+        <div class="release-entry-copy">
+          <header><div><p>{release.date}</p><h2>v{release.version}</h2></div><span>{release.label}</span></header>
+          <ul>{#each release.notes as note}<li>{note}</li>{/each}</ul>
+        </div>
+      </article>
+    {/each}
+  </div>
+
+  <aside class="release-policy">
+    <WeBaseIcon name="scan-square" size={22} />
+    <div><strong>Every release is a contract decision.</strong><p>Read the component reference for props, events, keyboard behavior, and the consumer example behind each change.</p></div>
+    <a href="/components" onclick={(event) => { event.preventDefault(); onNavigate('/components'); }}>Open components <WeBaseIcon name="arrow-right" size={16} /></a>
+  </aside>
+</section>
diff --git a/apps/docs/src/lib/router.ts b/apps/docs/src/lib/router.ts
new file mode 100644
index 0000000..989ccfe
--- /dev/null
+++ b/apps/docs/src/lib/router.ts
@@ -0,0 +1,28 @@
+export type DocsRoute =
+  | { kind: 'landing'; path: '/' }
+  | { kind: 'components'; path: '/components' }
+  | { kind: 'component'; path: `/components/${string}`; slug: string }
+  | { kind: 'release'; path: '/release' };
+
+function cleanPath(pathname: string) {
+  const path = pathname.replace(/\/+$/, '');
+  return path || '/';
+}
+
+export function routeForPath(pathname: string): DocsRoute {
+  const path = cleanPath(pathname);
+  if (path === '/') return { kind: 'landing', path: '/' };
+  if (path === '/components') return { kind: 'components', path: '/components' };
+  if (path === '/release') return { kind: 'release', path: '/release' };
+
+  const componentMatch = path.match(/^\/components\/([^/]+)$/);
+  if (componentMatch?.[1]) {
+    return { kind: 'component', path: `/components/${componentMatch[1]}`, slug: componentMatch[1] };
+  }
+
+  return { kind: 'landing', path: '/' };
+}
+
+export function currentRoute() {
+  return routeForPath(window.location.pathname);
+}
diff --git a/apps/docs/src/lib/utils/clipboard.ts b/apps/docs/src/lib/utils/clipboard.ts
new file mode 100644
index 0000000..5dff771
--- /dev/null
+++ b/apps/docs/src/lib/utils/clipboard.ts
@@ -0,0 +1,25 @@
+function fallbackCopy(text: string) {
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.setAttribute('readonly', '');
+  textarea.style.position = 'fixed';
+  textarea.style.opacity = '0';
+  document.body.append(textarea);
+  textarea.select();
+  const copied = document.execCommand('copy');
+  textarea.remove();
+  return copied;
+}
+
+export async function copyText(text: string) {
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // Fall back to the synchronous API below.
+  }
+
+  return fallbackCopy(text);
+}
diff --git a/design-qa.md b/design-qa.md
new file mode 100644
index 0000000..be4666f
--- /dev/null
+++ b/design-qa.md
@@ -0,0 +1,54 @@
+# Design QA
+
+## Source Visual Truth
+
+- Desktop landing: `docs/UI/ChatGPT Image 2026年8月19日 07_09_00.png` (1487 x 1058 px)
+- Mobile landing: `docs/UI/ChatGPT Image 2026年8月19日 07_09_05.png` (853 x 1844 px, normalized to 426 x 922 CSS px for comparison)
+- Desktop component reference: `docs/UI/ChatGPT Image 2026年8月19日 07_09_09.png` (1487 x 1058 px)
+- Mobile component reference: `docs/UI/ChatGPT Image 2026年8月19日 07_09_13.png` (853 x 1844 px, normalized to 426 x 922 CSS px for comparison)
+
+## Implementation Evidence
+
+- Desktop landing: `qa-implementation-home-desktop.png` (1487 x 1058 px, CSS viewport 1487 x 1058, device scale 1)
+- Mobile landing: `qa-implementation-home-mobile.png` (426 x 922 px, CSS viewport 426 x 922, device scale 1)
+- Desktop component reference: `qa-implementation-component-desktop.png` (1487 x 1058 px, CSS viewport 1487 x 1058, device scale 1)
+- Mobile component reference: `qa-implementation-component-mobile.png` (426 x 922 px, CSS viewport 426 x 922, device scale 1)
+
+## States And Interactions
+
+- Landing page at `/` with `Preview` tab selected and density at 64%.
+- Component reference at `/components/button` with `WeBaseButton` selected.
+- Verified global search, History API navigation, direct nested-route reloads, component filtering, group expansion, copy feedback, theme switching, mobile navigation, mobile component selection, reduced motion, and no horizontal overflow.
+- Browser console check returned no warnings or errors in the final captured tab.
+
+## Comparison
+
+Compared each source visual with its same-state implementation capture using side-by-side composite images during QA. The required fidelity surfaces were reviewed explicitly:
+
+- Typography: editorial display face, compact mono labels, hierarchy, wrapping, and readable mobile scale.
+- Spacing and layout: two-column desktop composition, proof rail, Foundation reveal, sticky component sidebar, and mobile vertical rhythm.
+- Colors and tokens: paper/surface neutrals, navy brand signal, ink hierarchy, success field, borders, and focus states.
+- Image and asset fidelity: the prototypes use UI surfaces and icons rather than raster imagery; implementation uses the existing logo and Lucide-backed `WeBaseIcon` assets.
+- Copy and content: hero contract message, component API labels, usage examples, version and install copy.
+
+## Findings
+
+No actionable P0, P1, or P2 mismatches remain after the final responsive pass. The desktop hero height and component-page top padding were tightened to restore the prototype's visible section rhythm. Mobile controls were compressed and the component selector was composed as a single-row control to match the mobile reference. Landing reveals now initialize per mounted node, so returning from a component route cannot leave the landing page partially transparent.
+
+Seven visual baselines affected by the approved prototype pass were reviewed and
+regenerated: Alert, Button light/dark/focus, Select mobile/open, and Dialog
+open. The other 40 visual cases remained unchanged, and the complete suite
+passed after the targeted update.
+
+## Verification
+
+- `npm run check`
+- `npm run check:consumer`
+- `npm run check:changeset`
+- `npm audit --audit-level=high`
+- `npm run test:browser` (102 passed across Chromium, Firefox, and WebKit)
+- `npm run test:visual` (47 passed)
+- Serious and critical Axe checks passed in the docs browser suite.
+- `git diff --check` passed.
+
+final result: passed
diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
index 917f4be..b2612c0 100644
--- a/docs/PERFORMANCE.md
+++ b/docs/PERFORMANCE.md
@@ -26,6 +26,24 @@ source sizes explain what changed inside the published artifacts.
 
 ## Reviewed baseline changes
 
+### 2026-08-20: expand the public icon vocabulary
+
+`WeBaseIcon` now exposes 14 additional Lucide names used by the routed
+documentation experience, including navigation, theme, contract, copy, and
+release-status symbols. The component keeps an explicit static icon map so the
+public name union and runtime lookup stay aligned; consumers that render
+`WeBaseIcon` therefore include the expanded vocabulary.
+
+| Metric | Previous | Current | Change |
+| --- | ---: | ---: | ---: |
+| `WeBaseIcon` source gzip | 1,052 B | 1,357 B | +305 B (+29.0%) |
+| Consumer JS gzip | 21,156 B | 22,262 B | +1,106 B (+5.2%) |
+| Consumer total gzip | 26,184 B | 27,292 B | +1,108 B (+4.2%) |
+| Svelte tarball | 40,289 B | 41,277 B | +988 B (+2.5%) |
+
+The icon vocabulary is a deliberate public API expansion and is covered by a
+patch changeset. The package-size gate continues from this reviewed baseline.
+
 ### 2026-08-16: publish the core changelog
 
 `@webaseui/core` now ships an initial `CHANGELOG.md` and includes it in its
diff --git a/docs/SCREEN_READER_AUDIT.md b/docs/SCREEN_READER_AUDIT.md
index 8b7acd4..1edf714 100644
--- a/docs/SCREEN_READER_AUDIT.md
+++ b/docs/SCREEN_READER_AUDIT.md
@@ -36,10 +36,13 @@ role, value or state, and focus destination.
 Copy this table for each candidate. `Blocked` requires a linked P0/P1 decision;
 an RC cannot pass with a blocked required environment.
 
+The candidate packages prepared for this audit are `@webaseui/core@0.2.0-next.0`
+and `@webaseui/svelte@0.4.0-next.0`.
+
 | Candidate | Environment | Versions | Tester and date | Result | Issues |
 | --- | --- | --- | --- | --- | --- |
-| Unscheduled | VoiceOver / Safari | Not recorded | Not run | Pending | None |
-| Unscheduled | NVDA / Firefox or Chrome | Not recorded | Not run | Pending | None |
+| core@0.2.0-next.0 + svelte@0.4.0-next.0 | VoiceOver / Safari | macOS 26.5.2; Safari 26.5.2; VoiceOver 10 | Pending human test | Pending | None |
+| core@0.2.0-next.0 + svelte@0.4.0-next.0 | NVDA / Firefox or Chrome | Windows, browser, and NVDA versions to record | Pending human test | Pending | None |
 
 ## Sign-off rules
 
diff --git a/docs/package-size-baseline.json b/docs/package-size-baseline.json
index eff7662..5c9793b 100644
--- a/docs/package-size-baseline.json
+++ b/docs/package-size-baseline.json
@@ -3,19 +3,19 @@
   "platform": "darwin",
   "packages": {
     "core": {
-      "tarballBytes": 6412,
-      "unpackedBytes": 24054,
+      "tarballBytes": 6648,
+      "unpackedBytes": 24541,
       "css": {
         "bytes": 18769,
         "gzipBytes": 3914
       }
     },
     "svelte": {
-      "tarballBytes": 40289,
-      "unpackedBytes": 174585,
+      "tarballBytes": 41277,
+      "unpackedBytes": 177147,
       "dist": {
-        "bytes": 150786,
-        "gzipBytes": 27176
+        "bytes": 152383,
+        "gzipBytes": 27622
       },
       "entry": {
         "bytes": 7663,
@@ -67,8 +67,8 @@
           "gzipBytes": 1321
         },
         "WeBaseIcon": {
-          "bytes": 3473,
-          "gzipBytes": 1052
+          "bytes": 4767,
+          "gzipBytes": 1357
         },
         "WeBaseIconButton": {
           "bytes": 2186,
@@ -119,8 +119,8 @@
           "gzipBytes": 1366
         },
         "WeBaseTag": {
-          "bytes": 2865,
-          "gzipBytes": 1018
+          "bytes": 3002,
+          "gzipBytes": 1068
         },
         "WeBaseTextarea": {
           "bytes": 3423,
@@ -138,13 +138,13 @@
     }
   },
   "consumer": {
-    "jsBytes": 58027,
-    "jsGzipBytes": 21156,
+    "jsBytes": 62656,
+    "jsGzipBytes": 22262,
     "cssBytes": 24393,
     "cssGzipBytes": 4754,
     "htmlBytes": 409,
-    "htmlGzipBytes": 274,
-    "totalBytes": 82829,
-    "totalGzipBytes": 26184
+    "htmlGzipBytes": 276,
+    "totalBytes": 87458,
+    "totalGzipBytes": 27292
   }
 }
diff --git a/packages/webaseui-svelte/src/lib/components/WeBaseIcon.svelte b/packages/webaseui-svelte/src/lib/components/WeBaseIcon.svelte
index c251a8a..13cc469 100644
--- a/packages/webaseui-svelte/src/lib/components/WeBaseIcon.svelte
+++ b/packages/webaseui-svelte/src/lib/components/WeBaseIcon.svelte
@@ -12,22 +12,36 @@
     | 'arrow-right'
     | 'arrow-up-right'
     | 'bookmark'
+    | 'book-open'
+    | 'box'
     | 'check'
     | 'chevron-down'
     | 'chevron-right'
+    | 'code-2'
     | 'circle-alert'
     | 'circle-check'
+    | 'copy'
+    | 'file-text'
+    | 'grid-2x2'
     | 'heart'
     | 'house'
     | 'info'
+    | 'keyboard'
     | 'loader-circle'
+    | 'menu'
     | 'minus'
+    | 'moon'
     | 'plus'
     | 'search'
+    | 'server'
+    | 'scan-square'
     | 'settings-2'
     | 'sparkles'
+    | 'sliders-horizontal'
+    | 'sun'
     | 'triangle-alert'
     | 'x'
+    | 'zap'
     | 'zoom-in';
 </script>
 
@@ -41,22 +55,36 @@
   import ArrowRight from '@lucide/svelte/icons/arrow-right';
   import ArrowUpRight from '@lucide/svelte/icons/arrow-up-right';
   import Bookmark from '@lucide/svelte/icons/bookmark';
+  import BookOpen from '@lucide/svelte/icons/book-open';
+  import Box from '@lucide/svelte/icons/box';
   import Check from '@lucide/svelte/icons/check';
   import ChevronDown from '@lucide/svelte/icons/chevron-down';
   import ChevronRight from '@lucide/svelte/icons/chevron-right';
+  import Code2 from '@lucide/svelte/icons/code-2';
   import CircleAlert from '@lucide/svelte/icons/circle-alert';
   import CircleCheck from '@lucide/svelte/icons/circle-check';
+  import Copy from '@lucide/svelte/icons/copy';
+  import FileText from '@lucide/svelte/icons/file-text';
+  import Grid2X2 from '@lucide/svelte/icons/grid-2x2';
   import Heart from '@lucide/svelte/icons/heart';
   import House from '@lucide/svelte/icons/house';
   import Info from '@lucide/svelte/icons/info';
+  import Keyboard from '@lucide/svelte/icons/keyboard';
   import LoaderCircle from '@lucide/svelte/icons/loader-circle';
+  import Menu from '@lucide/svelte/icons/menu';
   import Minus from '@lucide/svelte/icons/minus';
+  import Moon from '@lucide/svelte/icons/moon';
   import Plus from '@lucide/svelte/icons/plus';
   import Search from '@lucide/svelte/icons/search';
+  import Server from '@lucide/svelte/icons/server';
+  import ScanSquare from '@lucide/svelte/icons/scan-square';
   import Settings2 from '@lucide/svelte/icons/settings-2';
+  import SlidersHorizontal from '@lucide/svelte/icons/sliders-horizontal';
   import Sparkles from '@lucide/svelte/icons/sparkles';
+  import Sun from '@lucide/svelte/icons/sun';
   import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
   import X from '@lucide/svelte/icons/x';
+  import Zap from '@lucide/svelte/icons/zap';
   import ZoomIn from '@lucide/svelte/icons/zoom-in';
 
   interface Props extends Omit<LucideProps, 'children' | 'fill' | 'iconNode' | 'name' | 'size' | 'strokeWidth'> {
@@ -78,22 +106,36 @@
     'arrow-right': ArrowRight,
     'arrow-up-right': ArrowUpRight,
     'bookmark': Bookmark,
+    'book-open': BookOpen,
+    'box': Box,
     'check': Check,
     'chevron-down': ChevronDown,
     'chevron-right': ChevronRight,
+    'code-2': Code2,
     'circle-alert': CircleAlert,
     'circle-check': CircleCheck,
+    'copy': Copy,
+    'file-text': FileText,
+    'grid-2x2': Grid2X2,
     'heart': Heart,
     'house': House,
     'info': Info,
+    'keyboard': Keyboard,
     'loader-circle': LoaderCircle,
+    'menu': Menu,
     'minus': Minus,
+    'moon': Moon,
     'plus': Plus,
     'search': Search,
+    'server': Server,
+    'scan-square': ScanSquare,
     'settings-2': Settings2,
+    'sliders-horizontal': SlidersHorizontal,
     'sparkles': Sparkles,
+    'sun': Sun,
     'triangle-alert': TriangleAlert,
     'x': X,
+    'zap': Zap,
     'zoom-in': ZoomIn
   };
 
diff --git a/qa-implementation-component-desktop.png b/qa-implementation-component-desktop.png
new file mode 100644
index 0000000..32b1696
Binary files /dev/null and b/qa-implementation-component-desktop.png differ
diff --git a/qa-implementation-component-mobile.png b/qa-implementation-component-mobile.png
new file mode 100644
index 0000000..1463526
Binary files /dev/null and b/qa-implementation-component-mobile.png differ
diff --git a/qa-implementation-home-desktop.png b/qa-implementation-home-desktop.png
new file mode 100644
index 0000000..2fd6600
Binary files /dev/null and b/qa-implementation-home-desktop.png differ
diff --git a/qa-implementation-home-mobile.png b/qa-implementation-home-mobile.png
new file mode 100644
index 0000000..a9f5eb2
Binary files /dev/null and b/qa-implementation-home-mobile.png differ
diff --git a/static/_redirects b/static/_redirects
new file mode 100644
index 0000000..7797f7c
--- /dev/null
+++ b/static/_redirects
@@ -0,0 +1 @@
+/* /index.html 200
diff --git a/tests/browser/specs/docs.spec.ts b/tests/browser/specs/docs.spec.ts
index c117bb2..b3bfbff 100644
--- a/tests/browser/specs/docs.spec.ts
+++ b/tests/browser/specs/docs.spec.ts
@@ -7,12 +7,13 @@ test.beforeEach(async ({ page }) => {
   await page.goto(docsUrl);
 });
 
-test('docs header keeps the logo-only brand, stable anchors, theme, and search', async ({ page }) => {
+test('docs header keeps the logo-only brand, route navigation, theme, and search', async ({ page }) => {
   const brand = page.locator('header .brand');
   await expect(brand.locator('img')).toHaveAttribute('src', '/logo.svg');
-  await expect(brand.locator('strong, small')).toHaveCount(0);
+  await expect(brand.locator('img')).toBeVisible();
+  await expect(brand.locator('.brand-mark, .brand-name')).toHaveCount(0);
 
-  await expect(page.getByRole('navigation', { name: 'Documentation' }).getByRole('link')).toHaveText(['Tokens', 'Components', 'Install']);
+  await expect(page.getByRole('navigation', { name: 'Documentation' }).getByRole('link')).toHaveText(['Components', 'Release']);
 
   await page.getByRole('switch', { name: 'Toggle dark theme' }).click();
   await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
@@ -26,6 +27,11 @@ test('docs header keeps the logo-only brand, stable anchors, theme, and search',
   await expect(page.getByRole('button', { name: 'Search documentation' })).toBeFocused();
 });
 
+test('landing hero actions share the same control height', async ({ page }) => {
+  const heights = await page.locator('.hero-actions > *').evaluateAll((elements) => elements.map((element) => Math.round(element.getBoundingClientRect().height)));
+  expect(heights).toEqual([44, 44]);
+});
+
 test('global search selects a component and exposes its parsed API contract', async ({ page }) => {
   await page.keyboard.press('/');
   const search = page.getByRole('searchbox', { name: 'Search components and API fields' });
@@ -34,35 +40,109 @@ test('global search selects a component and exposes its parsed API contract', as
 
   await page.getByRole('button', { name: /WeBaseDialog/ }).click();
   await expect(page.getByRole('dialog')).toBeHidden();
-  await expect(page).toHaveURL(/#component-dialog$/);
+  await expect(page).toHaveURL(`${docsUrl}/components/dialog`);
   await expect(page.locator('[data-selected-component="WeBaseDialog"]')).toBeVisible();
   await expect(page.locator('[data-selected-component="WeBaseDialog"]')).toBeFocused();
-  await expect(page.getByRole('heading', { name: 'WeBaseDialog', level: 3 })).toBeVisible();
+  await expect(page.getByRole('heading', { name: 'WeBaseDialog', level: 1 })).toBeVisible();
   await expect(page.locator('.contract-panel')).toContainText('showModal()');
 });
 
-test('the reference desk indexes all 28 components and supports local filtering', async ({ page }) => {
-  await expect(page.locator('.sidebar-group button')).toHaveCount(28);
+test('the component index exposes all 28 components and supports local filtering', async ({ page }) => {
+  await page.goto(`${docsUrl}/components`);
+  await expect(page.getByRole('heading', { name: 'Components.', level: 1 })).toBeVisible();
+  await expect(page.locator('.component-index-item')).toHaveCount(28);
 
   await page.getByRole('searchbox', { name: 'Filter components' }).fill('slider');
-  await expect(page.locator('.sidebar-group button')).toHaveCount(1);
-  await page.getByRole('button', { name: 'Slider', exact: true }).click();
+  await expect(page.locator('.component-index-item')).toHaveCount(1);
+  await page.getByRole('link', { name: /Slider/ }).click();
 
+  await expect(page).toHaveURL(`${docsUrl}/components/slider`);
   await expect(page.locator('[data-selected-component="WeBaseSlider"]')).toBeVisible();
   await expect(page.locator('.contract-panel')).toContainText('inputProps');
 });
 
+test('the component detail sidebar supports local filtering', async ({ page }) => {
+  await page.goto(`${docsUrl}/components/button`);
+  await expect(page.locator('.sidebar-count')).toHaveText('28 components');
+  await expect(page.locator('.sidebar-group-trigger')).toHaveCount(12);
+
+  await page.getByRole('searchbox', { name: 'Filter components' }).fill('slider');
+  await expect(page.locator('.sidebar-group > div > a')).toHaveCount(1);
+  await page.getByRole('link', { name: 'WeBaseSlider', exact: true }).click();
+
+  await expect(page.locator('[data-selected-component="WeBaseSlider"]')).toBeVisible();
+  await expect(page.locator('.contract-panel')).toContainText('inputProps');
+});
+
+test('direct component routes and reloads restore the matching sidebar group', async ({ page }) => {
+  await page.goto(`${docsUrl}/components/dialog`);
+
+  await expect(page.locator('[data-selected-component="WeBaseDialog"]')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Overlay' })).toHaveAttribute('aria-expanded', 'true');
+  await expect(page.getByRole('link', { name: 'WeBaseDialog', exact: true })).toHaveAttribute('aria-current', 'page');
+
+  await page.reload();
+  await expect(page).toHaveURL(`${docsUrl}/components/dialog`);
+  await expect(page.locator('[data-selected-component="WeBaseDialog"]')).toBeVisible();
+  await expect(page).toHaveTitle('WeBaseDialog - WeBaseUI');
+
+  await page.goto(`${docsUrl}/components/not-a-component`);
+  await expect(page).toHaveURL(`${docsUrl}/components`);
+  await expect(page.getByRole('heading', { name: 'Components.', level: 1 })).toBeVisible();
+});
+
+test('returning home after visiting a component initializes landing reveals', async ({ page }) => {
+  await page.goto(`${docsUrl}/components/button`);
+  await expect(page.locator('[data-selected-component="WeBaseButton"]')).toBeVisible();
+
+  await page.getByRole('link', { name: 'WeBaseUI home' }).click();
+  await expect(page).toHaveURL(`${docsUrl}/`);
+  await expect(page.locator('.landing-page')).toBeVisible();
+
+  await page.locator('.proof-rail').scrollIntoViewIfNeeded();
+  await expect.poll(() => page.locator('.proof-rail').evaluate((element) => getComputedStyle(element).opacity)).toBe('1');
+  await page.locator('#tokens').scrollIntoViewIfNeeded();
+  await expect.poll(() => page.locator('#tokens').evaluate((element) => getComputedStyle(element).opacity)).toBe('1');
+});
+
 test('usage examples and install commands provide copy feedback', async ({ page }) => {
+  await page.goto(`${docsUrl}/components/button`);
   const exampleCopy = page.getByRole('button', { name: 'Copy WeBaseButton example' });
   await exampleCopy.click();
   await expect(exampleCopy).toContainText('Copied');
 
+  await page.goto(docsUrl);
   await page.locator('#install').scrollIntoViewIfNeeded();
   const installCopy = page.getByRole('button', { name: 'Copy install command' });
   await installCopy.click();
   await expect(installCopy).toContainText('Copied');
 });
 
+test('release is an independent route and browser history restores each page', async ({ page }) => {
+  await page.getByRole('link', { name: 'Components', exact: true }).click();
+  await expect(page).toHaveURL(`${docsUrl}/components`);
+
+  await page.getByRole('link', { name: 'Release', exact: true }).click();
+  await expect(page).toHaveURL(`${docsUrl}/release`);
+  await expect(page.getByRole('heading', { name: 'Release.', level: 1 })).toBeVisible();
+
+  await page.goBack();
+  await expect(page).toHaveURL(`${docsUrl}/components`);
+  await expect(page.getByRole('heading', { name: 'Components.', level: 1 })).toBeVisible();
+
+  await page.goForward();
+  await expect(page).toHaveURL(`${docsUrl}/release`);
+  await expect(page.getByRole('heading', { name: 'Release.', level: 1 })).toBeVisible();
+});
+
+test('production preview serves the application shell for nested routes', async ({ request }) => {
+  for (const path of ['/components', '/components/dialog', '/release']) {
+    const response = await request.get(`${docsUrl}${path}`);
+    expect(response.ok(), `${path} should resolve to the docs shell`).toBe(true);
+    expect(await response.text()).toContain('<div id="app"></div>');
+  }
+});
+
 test('favicon metadata covers scalable, small, touch, and installed-app icons', async ({ page, request }) => {
   const iconHrefs = await page.locator('link[rel~="icon"], link[rel="apple-touch-icon"], link[rel="manifest"]').evaluateAll((links) => {
     return links.map((link) => link.getAttribute('href')).filter((href): href is string => Boolean(href));
@@ -110,6 +190,7 @@ test('mobile navigation and component selection are explicitly composed without
   await expect(page.getByRole('navigation', { name: 'Mobile documentation' })).toBeVisible();
   await page.getByRole('link', { name: 'Components', exact: true }).last().click();
 
+  await page.locator('.component-index-item[href="/components/button"]').click();
   await page.getByLabel('Choose a component').selectOption('WeBaseDialog');
   await expect(page.locator('[data-selected-component="WeBaseDialog"]')).toBeVisible();
 
diff --git a/tests/browser/specs/visual.spec.ts b/tests/browser/specs/visual.spec.ts
index c708e59..86cfaaf 100644
--- a/tests/browser/specs/visual.spec.ts
+++ b/tests/browser/specs/visual.spec.ts
@@ -15,7 +15,7 @@ async function openSpecimen(page: Page, component: VisualComponent, theme: 'ligh
   await page.addInitScript((selectedTheme) => {
     localStorage.setItem('webaseui-theme', selectedTheme);
   }, theme);
-  await page.goto(`${docsUrl}/#component-${component.slug}`);
+  await page.goto(`${docsUrl}/components/${component.slug}`);
   await page.addStyleTag({
     content: `
       body::before { display: none !important; }
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/alert-light-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/alert-light-visual-chromium-darwin.png
index e72da79..d251616 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/alert-light-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/alert-light-visual-chromium-darwin.png differ
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/button-dark-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/button-dark-visual-chromium-darwin.png
index c74c907..77fceaf 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/button-dark-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/button-dark-visual-chromium-darwin.png differ
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/button-focus-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/button-focus-visual-chromium-darwin.png
index 108f8e8..75a5752 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/button-focus-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/button-focus-visual-chromium-darwin.png differ
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/button-light-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/button-light-visual-chromium-darwin.png
index 1501e1a..5e7e3e0 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/button-light-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/button-light-visual-chromium-darwin.png differ
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/dialog-open-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/dialog-open-visual-chromium-darwin.png
index 29ee4d7..e70359e 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/dialog-open-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/dialog-open-visual-chromium-darwin.png differ
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/select-mobile-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/select-mobile-visual-chromium-darwin.png
index d4988b9..9bdba6c 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/select-mobile-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/select-mobile-visual-chromium-darwin.png differ
diff --git a/tests/browser/specs/visual.spec.ts-snapshots/select-open-visual-chromium-darwin.png b/tests/browser/specs/visual.spec.ts-snapshots/select-open-visual-chromium-darwin.png
index e318dc8..ea4c50a 100644
Binary files a/tests/browser/specs/visual.spec.ts-snapshots/select-open-visual-chromium-darwin.png and b/tests/browser/specs/visual.spec.ts-snapshots/select-open-visual-chromium-darwin.png differ
diff --git a/tests/unit/reference-utils.test.ts b/tests/unit/reference-utils.test.ts
index eea5262..20e903d 100644
--- a/tests/unit/reference-utils.test.ts
+++ b/tests/unit/reference-utils.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { inlineParts, parseFields } from '../../apps/docs/src/lib/reference-utils.js';
+import { inlineParts, parseFields } from '../../apps/docs/src/lib/data/reference-utils.js';
 
 describe('parseFields', () => {
   it('parses named fields and joins indented continuation lines', () => {