From 6b6aa5cb6a18423d932902bed44bd1eeb74fd2b4 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 11:32:12 -0700
Subject: [PATCH 01/10] docs: spec for docs composites cycle 2 (parallelized
 A+B+C)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...26-07-06-docs-composites-cycle-2-design.md | 134 ++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-06-docs-composites-cycle-2-design.md

diff --git a/docs/superpowers/specs/2026-07-06-docs-composites-cycle-2-design.md b/docs/superpowers/specs/2026-07-06-docs-composites-cycle-2-design.md
new file mode 100644
index 0000000..d522337
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-06-docs-composites-cycle-2-design.md
@@ -0,0 +1,134 @@
+# Docs composites — cycle 2 (parallelized)
+
+Ports the remaining Tier-2 docs composites (groups A + B + C from `COMPONENTS.md`)
+from the authoritative `Elide Docs.dc.html` mockup. `CommandPalette` (group D)
+stays deferred — it needs the Command-primitive decision (Base UI Combobox vs.
+themed cmdk) and gets its own cycle.
+
+Work is fanned out across parallel Sonnet-5 agents. This document is the shared
+contract every agent reads.
+
+## Scope
+
+| # | Composite | Mockup source (line refs in `Elide Docs.dc.html`) |
+| --- | --- | --- |
+| A1 | `AppNav` | NAV, L64–88 (brand + DOCS pill · nav links · search trigger · theme toggle · locale · changelog · install) |
+| A2 | `SectionTabs` | SECTION TABS, L90–99 (Start·Runtime·Toolchain·API·Resources + version dot) |
+| A3 | `Sidebar` (`SectionSwitcher`, `SidebarGroup`, `SidebarItem`) | SIDEBAR, L102–123 & L667–698 |
+| A4 | `TableOfContents` | RIGHT RAIL "On this page", L184–190; FLOATING/MINI TOC L896, L1027 |
+| A5 | `MobileNav` | MOBILE, L202–297 (app bar + bottom "Search or ask AI" bar + Sheet drawer) |
+| B1 | `CardGrid` + `FeatureCard` | "Start here" cards L236–239; section-landing card grid (2a) |
+| B2 | `StatStrip` | 2a compatibility stat strip |
+| B3 | `AiActions` | "Use with AI" panel, L191–195 |
+| B4 | `CopyCommand` | install one-liner `curl elide.sh \| bash`, L234 |
+| C1 | `ApiMethod` + `ParamRow` | 2b node:fs reference, L461–582 |
+| C2 | `SupportMatrix` (`DataTable`) | SUPPORT MATRIX, L566 |
+| C3 | `StatusBadge` | API status pills — thin wrapper over existing `Badge` status tones |
+
+## Shared contract (every agent obeys)
+
+1. **Files, scoped.** Each agent creates **only**:
+   - `packages/ui/src/components/<kebab-name>.tsx`
+   - `packages/ui/src/stories/<PascalName>.stories.tsx`
+   - `packages/ui/src/components/<kebab-name>.test.tsx` (jsdom unit test)
+
+   Agents **must not** edit `src/index.ts`, `package.json`, `styles.css`,
+   `turbo.json`, `components.json`, `@elide/tokens`, or anything under
+   `.github/`. The integrator (main session) wires exports and runs the
+   aggregate build. `styles.css` already `@source`-globs `./components` and
+   `./stories`, so no CSS change is needed.
+
+2. **Theme only from tokens.** Use the CSS variables the mockup uses
+   (`var(--nav-bg)`, `var(--border)`, `var(--border-strong)`, `var(--fg)`,
+   `var(--fg-muted)`, `var(--fg-subtle)`, `var(--primary)`, `var(--primary-soft)`,
+   `var(--bg)`, `var(--bg-elev)`, `var(--bg-elev2)`, `var(--brand)`, `--code-*`,
+   `--syn-*`). Never hardcode a raw hex from the mockup. The one exception the
+   mockup itself makes is the **changelog violet** (`#9747ff`) — reuse the
+   existing `Button` `variant="changelog"` rather than re-inlining it.
+   Tailwind utility classes map to tokens already (`bg-background`, `text-muted-foreground`,
+   `border-border`, …); prefer them, and use `style={{}}` with `var(--…)` only
+   where no utility exists. Follow the idiom already in `callout.tsx` /
+   `breadcrumbs.tsx` / `page-footer-nav.tsx`.
+
+3. **Composition over new primitives.** Reuse shipped components — `Button`,
+   `Badge`, `Tooltip`, `Popover`, `DropdownMenu`, `Sheet`, `NavigationMenu`,
+   `Separator`, `ScrollArea`, `Breadcrumbs`. Group A also has `Accordion`,
+   `Select`, and `Avatar` available (pre-generated in Phase 0). Do not add new
+   npm dependencies; if you think you need one, stop and flag it.
+
+4. **Icons:** `lucide-react` only. Relative imports (`../lib/utils`,
+   `./button`) — no `@/` alias.
+
+5. **Props:** typed, exported `interface`/`type`; sensible defaults; data-driven
+   (arrays of items) so consumers pass content. Match the variants/props already
+   listed in `COMPONENTS.md` for the component. Forward `className` and merge with
+   `cn(...)`. `aria-*`: nav landmarks (`<nav aria-label>`), `aria-current="page"`
+   for active items, accessible names on icon-only buttons.
+
+6. **Story:** `title: "Composites/<Name>"`, `layout` param as fits, realistic
+   Elide content (not lorem). Include a `play` interaction test where the
+   component is interactive (toggle, open drawer, switch tab) using
+   `expect`/`userEvent`/`within`/`waitFor` from `storybook/test`. Assert exact
+   expected values, not "not-equal-to-before" (see the ThemeProvider lesson).
+
+7. **Unit test (`*.test.tsx`, jsdom):** Testing Library — `render`, query by
+   role/text, `userEvent` for interaction, assert with `@testing-library/jest-dom`
+   matchers. Cover: renders provided items, active/current state, external-link /
+   `comingSoon` variants, and any callback (`onSelect`, `onOpenChange`). Keep it
+   to component logic — visual fidelity is the story/Chromatic's job.
+
+8. **Verify your own slice** with `bunx tsc --noEmit -p packages/ui/tsconfig.json`
+   and `bunx eslint packages/ui/src/components/<name>.tsx packages/ui/src/stories/<Name>.stories.tsx packages/ui/src/components/<name>.test.tsx`.
+   Do **not** run the full Playwright/browser suite (the integrator runs it once
+   to avoid 11 concurrent browsers). Return a short report: files created,
+   exported symbol names + types (so the integrator can write `index.ts`), and
+   any dep/primitive you had to flag.
+
+## Test infrastructure (Phase 0, integrator)
+
+A second Vitest project runs pure unit tests in **jsdom** alongside the existing
+Storybook browser-mode suite:
+
+- `packages/ui/vitest.config.ts` — `environment: "jsdom"`, `globals: true`,
+  `setupFiles` loading `@testing-library/jest-dom`, `include: ["src/**/*.test.{ts,tsx}"]`,
+  coverage via `@vitest/coverage-v8` emitting `lcov` + `json` + `text` into
+  `packages/ui/coverage/`, `coverage.include: ["src/components/**"]`.
+- devDeps added to `packages/ui`: `vitest`, `jsdom`, `@testing-library/react`,
+  `@testing-library/user-event`, `@testing-library/jest-dom`, `@vitest/coverage-v8`.
+- `packages/ui` scripts: `"test": "vitest run"`, `"test:coverage": "vitest run --coverage"`.
+- `turbo.json` `test` task already fans across workspaces → picks up the new
+  `packages/ui` test automatically; `apps/storybook` browser suite also emits
+  coverage to `apps/storybook/coverage/`.
+- Proven before fan-out with a unit test against an already-shipped component
+  (`badge.test.tsx`) so agents have a green target to copy.
+
+## Codecov (Phase 1, dedicated agent)
+
+- `codecov.yml` at repo root: carryforward flags `ui-unit` (jsdom) and
+  `ui-browser` (Storybook), reasonable `project`/`patch` targets (informational,
+  not blocking initially), ignore `**/*.stories.tsx` and `src/stories/**`.
+- CI: in `.github/workflows/check.test.yml`, after the test run, upload both
+  `coverage/lcov.info` reports to Codecov with `codecov/codecov-action`
+  (SHA-pinned, matching the repo's pinning convention), flagged per project,
+  `fail_ci_if_error: false`, token from `secrets.CODECOV_TOKEN` (user provides).
+- README: add the Codecov badge.
+- This agent owns CI + `codecov.yml` only; it does **not** touch component files
+  or the vitest configs (the integrator sets `coverage` output in those).
+
+## Phasing
+
+- **Phase 0 (integrator, sequential):** stand up jsdom test infra + prove it;
+  pre-generate `Accordion`, `Select`, `Avatar` via the shadcn Base-UI flow
+  (interactive, Button-overwrite gotcha) and export them; `bun run build` green.
+- **Phase 1 (parallel, Sonnet 5):** 12 composite agents + 1 Codecov agent, per
+  the contract above.
+- **Phase 2 (integrator):** wire `index.ts` exports; `bun run build` + `lint` +
+  both test suites; fix seams; visual-verify a couple via the browser MCP;
+  update `COMPONENTS.md`; commit logically; open PR; address Copilot/Chromatic.
+
+## Non-goals
+
+- `CommandPalette` (group D) — deferred.
+- Tier-3 marketing widgets.
+- No new runtime npm deps. No Shiki yet (CodeBlock already shipped without it;
+  syntax highlighting is a separate future task).

From b4beb728267e762db048d5296c5e71cbe8b0dd1e Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 11:56:46 -0700
Subject: [PATCH 02/10] test(ui): jsdom unit-test project + Accordion/Select
 primitives
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add a jsdom Vitest project in packages/ui (Testing Library, coverage via
  v8 → lcov) for pure component unit tests, separate from the Storybook
  browser-mode suite. Proven with badge.test.tsx.
- tsconfig.test.json typechecks tests+stories with vitest globals; base
  tsconfig excludes test files so the library build stays clean.
- Pre-generate Accordion + Select (shadcn Base UI), themed from tokens,
  for the cycle-2 sidebar/section-switcher composites.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitignore                                |   3 +
 bun.lock                                  |  80 ++++++++-
 packages/ui/package.json                  |  14 +-
 packages/ui/src/components/accordion.tsx  |  72 ++++++++
 packages/ui/src/components/badge.test.tsx |  21 +++
 packages/ui/src/components/select.tsx     | 199 ++++++++++++++++++++++
 packages/ui/src/index.ts                  |   5 +
 packages/ui/src/test-setup.ts             |   9 +
 packages/ui/tsconfig.json                 |   3 +-
 packages/ui/tsconfig.test.json            |   9 +
 packages/ui/vitest.config.ts              |  24 +++
 11 files changed, 435 insertions(+), 4 deletions(-)
 create mode 100644 packages/ui/src/components/accordion.tsx
 create mode 100644 packages/ui/src/components/badge.test.tsx
 create mode 100644 packages/ui/src/components/select.tsx
 create mode 100644 packages/ui/src/test-setup.ts
 create mode 100644 packages/ui/tsconfig.test.json
 create mode 100644 packages/ui/vitest.config.ts

diff --git a/.gitignore b/.gitignore
index 959a732..40a79ae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,6 @@ storybook-static/
 .turbo/
 *.log
 .DS_Store
+
+# Coverage output
+coverage/
diff --git a/bun.lock b/bun.lock
index 4542c69..246d16a 100644
--- a/bun.lock
+++ b/bun.lock
@@ -62,16 +62,24 @@
       },
       "devDependencies": {
         "@eslint/js": "^10.0.1",
+        "@storybook/react-vite": "^10.4.6",
+        "@testing-library/jest-dom": "^6.6.3",
+        "@testing-library/react": "^16.3.0",
+        "@testing-library/user-event": "^14.6.1",
         "@types/react": "^19.2.17",
         "@types/react-dom": "^19.2.3",
+        "@vitejs/plugin-react": "^6.0.3",
+        "@vitest/coverage-v8": "^4.1.10",
         "eslint": "^10.6.0",
         "globals": "^17.7.0",
+        "jsdom": "^26.1.0",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",
         "storybook": "^10.4.6",
         "tsup": "^8.5.1",
         "typescript": "^6.0.3",
         "typescript-eslint": "^8.62.1",
+        "vitest": "^4.1.10",
       },
       "peerDependencies": {
         "react": ">=18",
@@ -82,6 +90,8 @@
   "packages": {
     "@adobe/css-tools": ["@adobe/css-tools@4.5.0", "", {}, "sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q=="],
 
+    "@asamuzakjp/css-color": ["@asamuzakjp/css-color@3.2.0", "", { "dependencies": { "@csstools/css-calc": "^2.1.3", "@csstools/css-color-parser": "^3.0.9", "@csstools/css-parser-algorithms": "^3.0.4", "@csstools/css-tokenizer": "^3.0.3", "lru-cache": "^10.4.3" } }, "sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw=="],
+
     "@babel/code-frame": ["@babel/code-frame@7.29.7", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.29.7", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw=="],
 
     "@babel/compat-data": ["@babel/compat-data@7.29.7", "", {}, "sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg=="],
@@ -160,6 +170,16 @@
 
     "@chromatic-com/storybook": ["@chromatic-com/storybook@5.2.1", "", { "dependencies": { "@neoconfetti/react": "^1.0.0", "chromatic": "16.10.0", "jsonfile": "^6.1.0", "strip-ansi": "^7.1.0" }, "peerDependencies": { "storybook": "^0.0.0-0 || ^10.1.0 || ^10.1.0-0 || ^10.2.0-0 || ^10.3.0-0 || ^10.4.0-0 || ^10.5.0-0 || ^10.6.0-0" } }, "sha512-z6I7NJk/0VngA64y5TNYaB4Hc2X8+90n4op6lBt9PvWk5TmIlFLDqdX33rlrwbNRkkYijVgA/wO04rVYXi5Mlg=="],
 
+    "@csstools/color-helpers": ["@csstools/color-helpers@5.1.0", "", {}, "sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA=="],
+
+    "@csstools/css-calc": ["@csstools/css-calc@2.1.4", "", { "peerDependencies": { "@csstools/css-parser-algorithms": "^3.0.5", "@csstools/css-tokenizer": "^3.0.4" } }, "sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ=="],
+
+    "@csstools/css-color-parser": ["@csstools/css-color-parser@3.1.0", "", { "dependencies": { "@csstools/color-helpers": "^5.1.0", "@csstools/css-calc": "^2.1.4" }, "peerDependencies": { "@csstools/css-parser-algorithms": "^3.0.5", "@csstools/css-tokenizer": "^3.0.4" } }, "sha512-nbtKwh3a6xNVIp/VRuXV64yTKnb1IjTAEEh3irzS+HkKjAOYLTGNb9pmVNntZ8iVBHcWDA2Dof0QtPgFI1BaTA=="],
+
+    "@csstools/css-parser-algorithms": ["@csstools/css-parser-algorithms@3.0.5", "", { "peerDependencies": { "@csstools/css-tokenizer": "^3.0.4" } }, "sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ=="],
+
+    "@csstools/css-tokenizer": ["@csstools/css-tokenizer@3.0.4", "", {}, "sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw=="],
+
     "@elide/storybook": ["@elide/storybook@workspace:apps/storybook"],
 
     "@elide/tokens": ["@elide/tokens@workspace:packages/tokens"],
@@ -510,6 +530,8 @@
 
     "@testing-library/jest-dom": ["@testing-library/jest-dom@6.9.1", "", { "dependencies": { "@adobe/css-tools": "^4.4.0", "aria-query": "^5.0.0", "css.escape": "^1.5.1", "dom-accessibility-api": "^0.6.3", "picocolors": "^1.1.1", "redent": "^3.0.0" } }, "sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA=="],
 
+    "@testing-library/react": ["@testing-library/react@16.3.2", "", { "dependencies": { "@babel/runtime": "^7.12.5" }, "peerDependencies": { "@testing-library/dom": "^10.0.0", "@types/react": "^18.0.0 || ^19.0.0", "@types/react-dom": "^18.0.0 || ^19.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g=="],
+
     "@testing-library/user-event": ["@testing-library/user-event@14.6.1", "", { "peerDependencies": { "@testing-library/dom": ">=7.21.4" } }, "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw=="],
 
     "@tmcp/adapter-valibot": ["@tmcp/adapter-valibot@0.1.6", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "@valibot/to-json-schema": "^1.3.0", "valibot": "^1.1.0" }, "peerDependencies": { "tmcp": "^1.17.0" } }, "sha512-drirZeNinhYLiRSMksN+m//u0ImFxtGRk1Vp425Xp/7CbBXFQdjAG+f7grssyHAukbVTGzmWsMMP6ejrGVErUA=="],
@@ -612,6 +634,8 @@
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
 
+    "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+
     "ajv": ["ajv@6.15.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw=="],
 
     "ansi-colors": ["ansi-colors@4.1.3", "", {}, "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw=="],
@@ -682,10 +706,16 @@
 
     "css.escape": ["css.escape@1.5.1", "", {}, "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg=="],
 
+    "cssstyle": ["cssstyle@4.6.0", "", { "dependencies": { "@asamuzakjp/css-color": "^3.2.0", "rrweb-cssom": "^0.8.0" } }, "sha512-2z+rWdzbbSZv6/rhtvzvqeZQHrBaqgogqt85sqFNbabZOuFbCVFb8kPeEtZjiKkbrm395irpNKiYeFeLiQnFPg=="],
+
     "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
 
+    "data-urls": ["data-urls@5.0.0", "", { "dependencies": { "whatwg-mimetype": "^4.0.0", "whatwg-url": "^14.0.0" } }, "sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg=="],
+
     "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
 
+    "decimal.js": ["decimal.js@10.6.0", "", {}, "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg=="],
+
     "deep-eql": ["deep-eql@5.0.2", "", {}, "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q=="],
 
     "deep-is": ["deep-is@0.1.4", "", {}, "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ=="],
@@ -716,6 +746,8 @@
 
     "enquirer": ["enquirer@2.4.1", "", { "dependencies": { "ansi-colors": "^4.1.1", "strip-ansi": "^6.0.1" } }, "sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ=="],
 
+    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
+
     "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
 
     "es-module-lexer": ["es-module-lexer@2.3.0", "", {}, "sha512-KLdwQm2NvGLDkQDCGvmiQrhkd0JbMzXthwQAUgWjQuQdBLFa3eiBP5arXZyA+f8x+x7OXgud6bq2rxjGtHV2tw=="],
@@ -798,8 +830,14 @@
 
     "hasown": ["hasown@2.0.4", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A=="],
 
+    "html-encoding-sniffer": ["html-encoding-sniffer@4.0.0", "", { "dependencies": { "whatwg-encoding": "^3.1.1" } }, "sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ=="],
+
     "html-escaper": ["html-escaper@2.0.2", "", {}, "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg=="],
 
+    "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
+
+    "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
+
     "human-id": ["human-id@4.2.0", "", { "bin": { "human-id": "dist/cli.js" } }, "sha512-K3GbkIWqyvvlpfhBPlbEvD97TtqBpAYA4kt+cn2lD2x2HuohzZCibcA2nOlnJT6exqvJLggoB5nv2dNf192nEA=="],
 
     "iconv-lite": ["iconv-lite@0.7.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ=="],
@@ -822,6 +860,8 @@
 
     "is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
 
+    "is-potential-custom-element-name": ["is-potential-custom-element-name@1.0.1", "", {}, "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ=="],
+
     "is-subdir": ["is-subdir@1.2.0", "", { "dependencies": { "better-path-resolve": "1.0.0" } }, "sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw=="],
 
     "is-windows": ["is-windows@1.0.2", "", {}, "sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA=="],
@@ -844,6 +884,8 @@
 
     "js-yaml": ["js-yaml@4.3.0", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q=="],
 
+    "jsdom": ["jsdom@26.1.0", "", { "dependencies": { "cssstyle": "^4.2.1", "data-urls": "^5.0.0", "decimal.js": "^10.5.0", "html-encoding-sniffer": "^4.0.0", "http-proxy-agent": "^7.0.2", "https-proxy-agent": "^7.0.6", "is-potential-custom-element-name": "^1.0.1", "nwsapi": "^2.2.16", "parse5": "^7.2.1", "rrweb-cssom": "^0.8.0", "saxes": "^6.0.0", "symbol-tree": "^3.2.4", "tough-cookie": "^5.1.1", "w3c-xmlserializer": "^5.0.0", "webidl-conversions": "^7.0.0", "whatwg-encoding": "^3.1.1", "whatwg-mimetype": "^4.0.0", "whatwg-url": "^14.1.1", "ws": "^8.18.0", "xml-name-validator": "^5.0.0" }, "peerDependencies": { "canvas": "^3.0.0" }, "optionalPeers": ["canvas"] }, "sha512-Cvc9WUhxSMEo4McES3P7oK3QaXldCfNWp7pl2NNeiIFlCoLr3kfq9kb1fxftiwk1FLV7CvpvDfonxtzUDeSOPg=="],
+
     "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
 
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
@@ -898,7 +940,7 @@
 
     "loupe": ["loupe@3.2.1", "", {}, "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ=="],
 
-    "lru-cache": ["lru-cache@11.5.1", "", {}, "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A=="],
+    "lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
 
     "lucide-react": ["lucide-react@1.23.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-38BpJcD0JhFosxHApP/BYsBetLpQFRoTRzEzstM/XCc3jsAG7wqaY1lgVwxiUe3xqYE+lNxo2PkCmYwXWrwwIw=="],
 
@@ -938,6 +980,8 @@
 
     "node-releases": ["node-releases@2.0.50", "", {}, "sha512-J6l92tKHX6w8Jy5nO1Vuc01NoIiRGi/d6qBKVxh+IQ8Cr3b6HbVNfKiF8ZpFKufTwpwxMmce2W3iQZ861ZRyTg=="],
 
+    "nwsapi": ["nwsapi@2.2.24", "", {}, "sha512-7YRhZ3jS45LwmSCT4b2sVFHt/WuovaktDU07QrtOBY2PXskss5a9jfmR9jptyumwXST+rFjrmppMY1KT/yn35A=="],
+
     "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
 
     "obug": ["obug@2.1.3", "", {}, "sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg=="],
@@ -964,6 +1008,8 @@
 
     "package-manager-detector": ["package-manager-detector@0.2.11", "", { "dependencies": { "quansync": "^0.2.7" } }, "sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ=="],
 
+    "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
+
     "path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
 
     "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
@@ -1042,12 +1088,16 @@
 
     "rollup": ["rollup@4.62.2", "", { "dependencies": { "@types/estree": "1.0.9" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.62.2", "@rollup/rollup-android-arm64": "4.62.2", "@rollup/rollup-darwin-arm64": "4.62.2", "@rollup/rollup-darwin-x64": "4.62.2", "@rollup/rollup-freebsd-arm64": "4.62.2", "@rollup/rollup-freebsd-x64": "4.62.2", "@rollup/rollup-linux-arm-gnueabihf": "4.62.2", "@rollup/rollup-linux-arm-musleabihf": "4.62.2", "@rollup/rollup-linux-arm64-gnu": "4.62.2", "@rollup/rollup-linux-arm64-musl": "4.62.2", "@rollup/rollup-linux-loong64-gnu": "4.62.2", "@rollup/rollup-linux-loong64-musl": "4.62.2", "@rollup/rollup-linux-ppc64-gnu": "4.62.2", "@rollup/rollup-linux-ppc64-musl": "4.62.2", "@rollup/rollup-linux-riscv64-gnu": "4.62.2", "@rollup/rollup-linux-riscv64-musl": "4.62.2", "@rollup/rollup-linux-s390x-gnu": "4.62.2", "@rollup/rollup-linux-x64-gnu": "4.62.2", "@rollup/rollup-linux-x64-musl": "4.62.2", "@rollup/rollup-openbsd-x64": "4.62.2", "@rollup/rollup-openharmony-arm64": "4.62.2", "@rollup/rollup-win32-arm64-msvc": "4.62.2", "@rollup/rollup-win32-ia32-msvc": "4.62.2", "@rollup/rollup-win32-x64-gnu": "4.62.2", "@rollup/rollup-win32-x64-msvc": "4.62.2", "fsevents": "~2.3.2" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-RFnrW4lhXA3s3eqHDZvN654g8OTjzRfqpIRJYczCGB6HzphckVAi/Qh4tbPUbRuDi7s1Llv8g/NspLkttY3gTA=="],
 
+    "rrweb-cssom": ["rrweb-cssom@0.8.0", "", {}, "sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw=="],
+
     "run-applescript": ["run-applescript@7.1.0", "", {}, "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q=="],
 
     "run-parallel": ["run-parallel@1.2.0", "", { "dependencies": { "queue-microtask": "^1.2.2" } }, "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA=="],
 
     "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
 
+    "saxes": ["saxes@6.0.0", "", { "dependencies": { "xmlchars": "^2.2.0" } }, "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA=="],
+
     "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
 
     "semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="],
@@ -1092,6 +1142,8 @@
 
     "supports-preserve-symlinks-flag": ["supports-preserve-symlinks-flag@1.0.0", "", {}, "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w=="],
 
+    "symbol-tree": ["symbol-tree@3.2.4", "", {}, "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw=="],
+
     "tailwind-merge": ["tailwind-merge@3.6.0", "", {}, "sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w=="],
 
     "tailwindcss": ["tailwindcss@4.3.2", "", {}, "sha512-WtctNNSH8A9jlMIqxzuYumOHU5uGZyRv0Q5svQl+oEPy5w84YpBxdb7MdqyiSPQge5jTJ6zFQLq0PFygdccSBA=="],
@@ -1116,12 +1168,20 @@
 
     "tinyspy": ["tinyspy@4.0.4", "", {}, "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q=="],
 
+    "tldts": ["tldts@6.1.86", "", { "dependencies": { "tldts-core": "^6.1.86" }, "bin": { "tldts": "bin/cli.js" } }, "sha512-WMi/OQ2axVTf/ykqCQgXiIct+mSQDFdH2fkwhPwgEwvJ1kSzZRiinb0zF2Xb8u4+OqPChmyI6MEu4EezNJz+FQ=="],
+
+    "tldts-core": ["tldts-core@6.1.86", "", {}, "sha512-Je6p7pkk+KMzMv2XXKmAE3McmolOQFdxkKw0R8EYNr7sELW46JqnNeTX8ybPiQgvg1ymCoF8LXs5fzFaZvJPTA=="],
+
     "tmcp": ["tmcp@1.19.4", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "json-rpc-2.0": "^1.7.1", "sqids": "^0.3.0", "uri-template-matcher": "^1.1.1", "valibot": "^1.1.0" } }, "sha512-fMoUJ3Gef9iA0yKZNeW2SQCCKTluCwghUyOz/qxPS8XxrQk6Jlw4lgql3S+s6L//FteLeSJ7erKxMWl727mZoQ=="],
 
     "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
 
     "totalist": ["totalist@3.0.1", "", {}, "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ=="],
 
+    "tough-cookie": ["tough-cookie@5.1.2", "", { "dependencies": { "tldts": "^6.1.32" } }, "sha512-FVDYdxtnj0G6Qm/DhNPSb8Ju59ULcup3tuJxkFb5K8Bv2pUXILbf0xZWU8PX8Ov19OXljbUyveOFwRMwkXzO+A=="],
+
+    "tr46": ["tr46@5.1.1", "", { "dependencies": { "punycode": "^2.3.1" } }, "sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw=="],
+
     "tree-kill": ["tree-kill@1.2.2", "", { "bin": { "tree-kill": "cli.js" } }, "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A=="],
 
     "ts-api-utils": ["ts-api-utils@2.5.0", "", { "peerDependencies": { "typescript": ">=4.8.4" } }, "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA=="],
@@ -1166,8 +1226,18 @@
 
     "vitest": ["vitest@4.1.10", "", { "dependencies": { "@vitest/expect": "4.1.10", "@vitest/mocker": "4.1.10", "@vitest/pretty-format": "4.1.10", "@vitest/runner": "4.1.10", "@vitest/snapshot": "4.1.10", "@vitest/spy": "4.1.10", "@vitest/utils": "4.1.10", "es-module-lexer": "^2.0.0", "expect-type": "^1.3.0", "magic-string": "^0.30.21", "obug": "^2.1.1", "pathe": "^2.0.3", "picomatch": "^4.0.3", "std-env": "^4.0.0-rc.1", "tinybench": "^2.9.0", "tinyexec": "^1.0.2", "tinyglobby": "^0.2.15", "tinyrainbow": "^3.1.0", "vite": "^6.0.0 || ^7.0.0 || ^8.0.0", "why-is-node-running": "^2.3.0" }, "peerDependencies": { "@edge-runtime/vm": "*", "@opentelemetry/api": "^1.9.0", "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0", "@vitest/browser-playwright": "4.1.10", "@vitest/browser-preview": "4.1.10", "@vitest/browser-webdriverio": "4.1.10", "@vitest/coverage-istanbul": "4.1.10", "@vitest/coverage-v8": "4.1.10", "@vitest/ui": "4.1.10", "happy-dom": "*", "jsdom": "*" }, "optionalPeers": ["@edge-runtime/vm", "@opentelemetry/api", "@types/node", "@vitest/browser-playwright", "@vitest/browser-preview", "@vitest/browser-webdriverio", "@vitest/coverage-istanbul", "@vitest/coverage-v8", "@vitest/ui", "happy-dom", "jsdom"], "bin": { "vitest": "./vitest.mjs" } }, "sha512-R9jUTe5S4Qb0HCd4TNqpC7oGcrMssMRGXLW80ubjWsW9VH5GF8y1Y0SFLY9AbqSk6nt0PnOx4H4WNJYZ13GUPw=="],
 
+    "w3c-xmlserializer": ["w3c-xmlserializer@5.0.0", "", { "dependencies": { "xml-name-validator": "^5.0.0" } }, "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA=="],
+
+    "webidl-conversions": ["webidl-conversions@7.0.0", "", {}, "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g=="],
+
     "webpack-virtual-modules": ["webpack-virtual-modules@0.6.2", "", {}, "sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ=="],
 
+    "whatwg-encoding": ["whatwg-encoding@3.1.1", "", { "dependencies": { "iconv-lite": "0.6.3" } }, "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ=="],
+
+    "whatwg-mimetype": ["whatwg-mimetype@4.0.0", "", {}, "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg=="],
+
+    "whatwg-url": ["whatwg-url@14.2.0", "", { "dependencies": { "tr46": "^5.1.0", "webidl-conversions": "^7.0.0" } }, "sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw=="],
+
     "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
 
     "why-is-node-running": ["why-is-node-running@2.3.0", "", { "dependencies": { "siginfo": "^2.0.0", "stackback": "0.0.2" }, "bin": { "why-is-node-running": "cli.js" } }, "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w=="],
@@ -1178,6 +1248,10 @@
 
     "wsl-utils": ["wsl-utils@0.1.0", "", { "dependencies": { "is-wsl": "^3.1.0" } }, "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw=="],
 
+    "xml-name-validator": ["xml-name-validator@5.0.0", "", {}, "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg=="],
+
+    "xmlchars": ["xmlchars@2.2.0", "", {}, "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw=="],
+
     "yallist": ["yallist@3.1.1", "", {}, "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="],
 
     "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
@@ -1248,6 +1322,8 @@
 
     "micromatch/picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],
 
+    "path-scurry/lru-cache": ["lru-cache@11.5.1", "", {}, "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A=="],
+
     "pretty-format/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
     "read-yaml-file/js-yaml": ["js-yaml@3.15.0", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog=="],
@@ -1270,6 +1346,8 @@
 
     "vitest/@vitest/spy": ["@vitest/spy@4.1.10", "", {}, "sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw=="],
 
+    "whatwg-encoding/iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
+
     "@manypkg/find-root/find-up/locate-path": ["locate-path@5.0.0", "", { "dependencies": { "p-locate": "^4.1.0" } }, "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g=="],
 
     "@manypkg/find-root/fs-extra/jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 1afce49..3c4050f 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -21,7 +21,9 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
     "dev": "tsup src/index.ts --format esm --dts --watch",
-    "lint": "eslint src"
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -38,15 +40,23 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@storybook/react-vite": "^10.4.6",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.6.0",
     "globals": "^17.7.0",
+    "jsdom": "^26.1.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "storybook": "^10.4.6",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.62.1"
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^4.1.10"
   }
 }
diff --git a/packages/ui/src/components/accordion.tsx b/packages/ui/src/components/accordion.tsx
new file mode 100644
index 0000000..182e888
--- /dev/null
+++ b/packages/ui/src/components/accordion.tsx
@@ -0,0 +1,72 @@
+import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"
+
+import { cn } from "../lib/utils"
+import { ChevronDownIcon, ChevronUpIcon } from "lucide-react"
+
+function Accordion({ className, ...props }: AccordionPrimitive.Root.Props) {
+  return (
+    <AccordionPrimitive.Root
+      data-slot="accordion"
+      className={cn("flex w-full flex-col", className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionItem({ className, ...props }: AccordionPrimitive.Item.Props) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn("not-last:border-b", className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: AccordionPrimitive.Trigger.Props) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "group/accordion-trigger relative flex flex-1 items-start justify-between rounded-lg border border-transparent py-2.5 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:after:border-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon data-slot="accordion-trigger-icon" className="pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden" />
+        <ChevronUpIcon data-slot="accordion-trigger-icon" className="pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  )
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: AccordionPrimitive.Panel.Props) {
+  return (
+    <AccordionPrimitive.Panel
+      data-slot="accordion-content"
+      className="overflow-hidden text-sm data-open:animate-accordion-down data-closed:animate-accordion-up"
+      {...props}
+    >
+      <div
+        className={cn(
+          "h-(--accordion-panel-height) pt-0 pb-2.5 data-ending-style:h-0 data-starting-style:h-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
+          className
+        )}
+      >
+        {children}
+      </div>
+    </AccordionPrimitive.Panel>
+  )
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }
diff --git a/packages/ui/src/components/badge.test.tsx b/packages/ui/src/components/badge.test.tsx
new file mode 100644
index 0000000..7fb1ba1
--- /dev/null
+++ b/packages/ui/src/components/badge.test.tsx
@@ -0,0 +1,21 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { Badge } from "./badge";
+
+describe("Badge", () => {
+  it("renders its children", () => {
+    render(<Badge>Beta</Badge>);
+    expect(screen.getByText("Beta")).toBeInTheDocument();
+  });
+
+  it("renders a status dot when `dot` is set", () => {
+    const { container } = render(<Badge dot>Live</Badge>);
+    // The dot is a decorative leading span with bg-current.
+    expect(container.querySelector("span > span.bg-current")).toBeInTheDocument();
+  });
+
+  it("merges a consumer className", () => {
+    render(<Badge className="custom-x">Tag</Badge>);
+    expect(screen.getByText("Tag")).toHaveClass("custom-x");
+  });
+});
diff --git a/packages/ui/src/components/select.tsx b/packages/ui/src/components/select.tsx
new file mode 100644
index 0000000..31a96c5
--- /dev/null
+++ b/packages/ui/src/components/select.tsx
@@ -0,0 +1,199 @@
+import * as React from "react"
+import { Select as SelectPrimitive } from "@base-ui/react/select"
+
+import { cn } from "../lib/utils"
+import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react"
+
+const Select = SelectPrimitive.Root
+
+function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn("scroll-my-1 p-1", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
+  return (
+    <SelectPrimitive.Value
+      data-slot="select-value"
+      className={cn("flex flex-1 text-left", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectTrigger({
+  className,
+  size = "default",
+  children,
+  ...props
+}: SelectPrimitive.Trigger.Props & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        "flex w-fit items-center justify-between gap-1.5 rounded-lg border border-input bg-transparent py-2 pr-2 pl-2.5 text-sm whitespace-nowrap transition-colors outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded-[min(var(--radius-md),10px)] *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 dark:bg-input/30 dark:hover:bg-input/50 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon
+        render={
+          <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
+        }
+      />
+    </SelectPrimitive.Trigger>
+  )
+}
+
+function SelectContent({
+  className,
+  children,
+  side = "bottom",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  alignItemWithTrigger = true,
+  ...props
+}: SelectPrimitive.Popup.Props &
+  Pick<
+    SelectPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger"
+  >) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        alignItemWithTrigger={alignItemWithTrigger}
+        className="isolate z-50"
+      >
+        <SelectPrimitive.Popup
+          data-slot="select-content"
+          data-align-trigger={alignItemWithTrigger}
+          className={cn("relative isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
+          {...props}
+        >
+          <SelectScrollUpButton />
+          <SelectPrimitive.List>{children}</SelectPrimitive.List>
+          <SelectScrollDownButton />
+        </SelectPrimitive.Popup>
+      </SelectPrimitive.Positioner>
+    </SelectPrimitive.Portal>
+  )
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: SelectPrimitive.GroupLabel.Props) {
+  return (
+    <SelectPrimitive.GroupLabel
+      data-slot="select-label"
+      className={cn("px-1.5 py-1 text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: SelectPrimitive.Item.Props) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "relative flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        className
+      )}
+      {...props}
+    >
+      <SelectPrimitive.ItemText className="flex flex-1 shrink-0 gap-2 whitespace-nowrap">
+        {children}
+      </SelectPrimitive.ItemText>
+      <SelectPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <CheckIcon className="pointer-events-none" />
+      </SelectPrimitive.ItemIndicator>
+    </SelectPrimitive.Item>
+  )
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: SelectPrimitive.Separator.Props) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpArrow>) {
+  return (
+    <SelectPrimitive.ScrollUpArrow
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "top-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <ChevronUpIcon
+      />
+    </SelectPrimitive.ScrollUpArrow>
+  )
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownArrow>) {
+  return (
+    <SelectPrimitive.ScrollDownArrow
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "bottom-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <ChevronDownIcon
+      />
+    </SelectPrimitive.ScrollDownArrow>
+  )
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 66ee118..0d235ce 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -34,6 +34,11 @@ export {
   NavigationMenuContent, NavigationMenuLink, NavigationMenuIndicator,
   NavigationMenuPositioner, navigationMenuTriggerStyle,
 } from "./components/navigation-menu";
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "./components/accordion";
+export {
+  Select, SelectContent, SelectGroup, SelectItem, SelectLabel,
+  SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue,
+} from "./components/select";
 
 // As components are ported from the mockups they are exported here. Base-UI-backed
 // primitives (Dialog, Popover, DropdownMenu, Combobox/Command, Tooltip, Tabs,
diff --git a/packages/ui/src/test-setup.ts b/packages/ui/src/test-setup.ts
new file mode 100644
index 0000000..3936862
--- /dev/null
+++ b/packages/ui/src/test-setup.ts
@@ -0,0 +1,9 @@
+// Registers jest-dom matchers (toBeInTheDocument, toHaveAttribute, …) on
+// Vitest's `expect`, and clears the jsdom tree between tests.
+import "@testing-library/jest-dom/vitest";
+import { afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+afterEach(() => {
+  cleanup();
+});
diff --git a/packages/ui/tsconfig.json b/packages/ui/tsconfig.json
index 56ff1c6..069b46e 100644
--- a/packages/ui/tsconfig.json
+++ b/packages/ui/tsconfig.json
@@ -12,5 +12,6 @@
     "types": ["react"],
     "ignoreDeprecations": "6.0"
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx"]
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx", "src/test-setup.ts"]
 }
diff --git a/packages/ui/tsconfig.test.json b/packages/ui/tsconfig.test.json
new file mode 100644
index 0000000..caba9f5
--- /dev/null
+++ b/packages/ui/tsconfig.test.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["react", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": []
+}
diff --git a/packages/ui/vitest.config.ts b/packages/ui/vitest.config.ts
new file mode 100644
index 0000000..4eadaf0
--- /dev/null
+++ b/packages/ui/vitest.config.ts
@@ -0,0 +1,24 @@
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+// Pure component unit tests in jsdom (logic/DOM/props/callbacks), run separately
+// from the Storybook browser-mode suite in apps/storybook (which owns visual +
+// interaction/play tests in real Chromium). Both emit coverage; Codecov merges
+// the `ui-unit` and `ui-browser` flags.
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    name: "ui-unit",
+    environment: "jsdom",
+    globals: true,
+    setupFiles: ["./src/test-setup.ts"],
+    include: ["src/**/*.test.{ts,tsx}"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "lcov"],
+      reportsDirectory: "./coverage",
+      include: ["src/components/**"],
+      exclude: ["src/**/*.test.{ts,tsx}", "src/**/*.stories.tsx"],
+    },
+  },
+});

From 0e2616c09c573fcf2282df528a5da15a3ec95750 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 12:24:46 -0700
Subject: [PATCH 03/10] =?UTF-8?q?feat(ui):=20docs=20composites=20cycle=202?=
 =?UTF-8?q?=20=E2=80=94=20nav=20shell,=20content,=20and=20API-reference?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ports the remaining Tier-2 docs composites from the Elide Docs mockup,
themed entirely from @elide/tokens. Each ships a Storybook story (with a
play interaction test where interactive) and a jsdom unit test.

Navigation shell:
- AppNav — brand, nav links, search trigger, theme/locale, changelog, install
- SectionTabs — top-level section bar with active underline + version dot
- Sidebar (+ SectionSwitcher, SidebarGroup, SidebarItem) — active/external/comingSoon
- TableOfContents — "On this page" with IntersectionObserver scroll-spy + mono variant
- MobileNav — condensed bar + Sheet drawer + persistent search bar

Content & landing:
- CardGrid + FeatureCard — responsive category cards with icon/badge/external
- StatStrip — bordered stat grid with primary emphasis
- AiActions — "Use with AI" panel (copy-as-markdown + external links)
- CopyCommand — one-line command block with copy affordance

API reference:
- StatusBadge — thin wrapper over Badge mapping ApiStatus tones
- ApiMethod + ParamRow — method entry with signature, params, example CodeBlock
- SupportMatrix — semantic status table (accessible, not color-only)

Also hardens the shared CopyButton (code-block): swallow clipboard
rejections and reflect the copied state in aria-label so assistive tech
announces it. SectionTabs preventDefault on controlled onSelect so it
doesn't double-navigate. Token names from the mockup mapped to the real
@elide/tokens vars (--fg-* → --*-foreground, --syn-* → --eld-syntax-*, etc.).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 COMPONENTS.md                                 |  32 +--
 .../ui/src/components/ai-actions.test.tsx     |  58 ++++++
 packages/ui/src/components/ai-actions.tsx     | 100 +++++++++
 .../ui/src/components/api-method.test.tsx     |  48 +++++
 packages/ui/src/components/api-method.tsx     | 103 ++++++++++
 packages/ui/src/components/app-nav.test.tsx   |  41 ++++
 packages/ui/src/components/app-nav.tsx        | 140 +++++++++++++
 packages/ui/src/components/card-grid.test.tsx |  90 ++++++++
 packages/ui/src/components/card-grid.tsx      | 120 +++++++++++
 packages/ui/src/components/code-block.tsx     |   7 +-
 .../ui/src/components/copy-command.test.tsx   |  36 ++++
 packages/ui/src/components/copy-command.tsx   |  41 ++++
 .../ui/src/components/mobile-nav.test.tsx     |  59 ++++++
 packages/ui/src/components/mobile-nav.tsx     | 176 ++++++++++++++++
 .../ui/src/components/section-tabs.test.tsx   |  42 ++++
 packages/ui/src/components/section-tabs.tsx   |  86 ++++++++
 packages/ui/src/components/sidebar.test.tsx   |  99 +++++++++
 packages/ui/src/components/sidebar.tsx        | 192 ++++++++++++++++++
 .../ui/src/components/stat-strip.test.tsx     |  41 ++++
 packages/ui/src/components/stat-strip.tsx     |  59 ++++++
 .../ui/src/components/status-badge.test.tsx   |  30 +++
 packages/ui/src/components/status-badge.tsx   |  31 +++
 .../ui/src/components/support-matrix.test.tsx |  65 ++++++
 packages/ui/src/components/support-matrix.tsx |  93 +++++++++
 .../src/components/table-of-contents.test.tsx |  54 +++++
 .../ui/src/components/table-of-contents.tsx   | 102 ++++++++++
 packages/ui/src/index.ts                      |  27 +++
 packages/ui/src/stories/AiActions.stories.tsx |  57 ++++++
 packages/ui/src/stories/ApiMethod.stories.tsx |  64 ++++++
 packages/ui/src/stories/AppNav.stories.tsx    |  50 +++++
 packages/ui/src/stories/CardGrid.stories.tsx  |  94 +++++++++
 .../ui/src/stories/CopyCommand.stories.tsx    |  45 ++++
 packages/ui/src/stories/MobileNav.stories.tsx |  68 +++++++
 .../ui/src/stories/SectionTabs.stories.tsx    |  53 +++++
 packages/ui/src/stories/Sidebar.stories.tsx   |  78 +++++++
 packages/ui/src/stories/StatStrip.stories.tsx |  41 ++++
 .../ui/src/stories/StatusBadge.stories.tsx    |  39 ++++
 .../ui/src/stories/SupportMatrix.stories.tsx  |  39 ++++
 .../src/stories/TableOfContents.stories.tsx   |  57 ++++++
 39 files changed, 2639 insertions(+), 18 deletions(-)
 create mode 100644 packages/ui/src/components/ai-actions.test.tsx
 create mode 100644 packages/ui/src/components/ai-actions.tsx
 create mode 100644 packages/ui/src/components/api-method.test.tsx
 create mode 100644 packages/ui/src/components/api-method.tsx
 create mode 100644 packages/ui/src/components/app-nav.test.tsx
 create mode 100644 packages/ui/src/components/app-nav.tsx
 create mode 100644 packages/ui/src/components/card-grid.test.tsx
 create mode 100644 packages/ui/src/components/card-grid.tsx
 create mode 100644 packages/ui/src/components/copy-command.test.tsx
 create mode 100644 packages/ui/src/components/copy-command.tsx
 create mode 100644 packages/ui/src/components/mobile-nav.test.tsx
 create mode 100644 packages/ui/src/components/mobile-nav.tsx
 create mode 100644 packages/ui/src/components/section-tabs.test.tsx
 create mode 100644 packages/ui/src/components/section-tabs.tsx
 create mode 100644 packages/ui/src/components/sidebar.test.tsx
 create mode 100644 packages/ui/src/components/sidebar.tsx
 create mode 100644 packages/ui/src/components/stat-strip.test.tsx
 create mode 100644 packages/ui/src/components/stat-strip.tsx
 create mode 100644 packages/ui/src/components/status-badge.test.tsx
 create mode 100644 packages/ui/src/components/status-badge.tsx
 create mode 100644 packages/ui/src/components/support-matrix.test.tsx
 create mode 100644 packages/ui/src/components/support-matrix.tsx
 create mode 100644 packages/ui/src/components/table-of-contents.test.tsx
 create mode 100644 packages/ui/src/components/table-of-contents.tsx
 create mode 100644 packages/ui/src/stories/AiActions.stories.tsx
 create mode 100644 packages/ui/src/stories/ApiMethod.stories.tsx
 create mode 100644 packages/ui/src/stories/AppNav.stories.tsx
 create mode 100644 packages/ui/src/stories/CardGrid.stories.tsx
 create mode 100644 packages/ui/src/stories/CopyCommand.stories.tsx
 create mode 100644 packages/ui/src/stories/MobileNav.stories.tsx
 create mode 100644 packages/ui/src/stories/SectionTabs.stories.tsx
 create mode 100644 packages/ui/src/stories/Sidebar.stories.tsx
 create mode 100644 packages/ui/src/stories/StatStrip.stories.tsx
 create mode 100644 packages/ui/src/stories/StatusBadge.stories.tsx
 create mode 100644 packages/ui/src/stories/SupportMatrix.stories.tsx
 create mode 100644 packages/ui/src/stories/TableOfContents.stories.tsx

diff --git a/COMPONENTS.md b/COMPONENTS.md
index eccf2ee..0921323 100644
--- a/COMPONENTS.md
+++ b/COMPONENTS.md
@@ -24,12 +24,12 @@ radii, type. See the package README.
 | `Dialog` | **done** | — | modal base |
 | `Sheet` / `Drawer` | **done** | side | **mobile nav drawer** |
 | `Tabs` | **done** | — | (content tabbing) |
-| `Select` / `NativeSelect` | registry | — | forms |
+| `Select` / `NativeSelect` | **done** | — | forms |
 | `Combobox` / `Command` | deferred | — | **⌘K command palette** — deferred to CommandPalette composite (see note) |
 | `Switch` | **done** | — | theme toggle option |
 | `Separator` | **done** | orientation | nav dividers |
 | `ScrollArea` | **done** | — | sidebar / palette scroll |
-| `Accordion` | registry | — | FAQ, collapsible nav groups |
+| `Accordion` | **done** | — | FAQ, collapsible nav groups |
 | `Breadcrumb` | registry | — | page breadcrumbs |
 | `NavigationMenu` | **done** | — | primary nav links |
 | `Avatar` | registry | — | (marketing) |
@@ -39,23 +39,23 @@ radii, type. See the package README.
 | Component | Status | Composition / props | Source |
 | --- | --- | --- | --- |
 | `Callout` | **done** | tone: note·tip·important·warning·caution; `title` | guide admonitions |
-| `CodeBlock` | todo | variant: editor·terminal; `filename`, `lang`, `lineNumbers`, `statusBar` (vim NORMAL), `highlight`; slot: `CopyButton` | SQLite editor, terminal, snippet blocks |
-| `CopyButton` | todo | `value`, `size` | code block + copy-command |
-| `CopyCommand` | todo | `command`, prompt glyph | install one-liner |
-| `AppNav` | todo | brand · `NavLinks` · `SearchTrigger` · `ThemeToggle` · `LocaleSwitcher` · `ChangelogButton` · `InstallButton` | top nav (all pages) |
-| `SectionTabs` | todo | `items`, `active` | Start·Runtime·Toolchain·API·Resources |
-| `Sidebar` | todo | `SectionSwitcher`, `NavGroup`, `NavItem` (active, external, comingSoon), progress | left nav |
-| `TableOfContents` | todo | `items`, active-on-scroll; mono variant for API methods | right rail "On this page" |
-| `AiActions` | todo | Copy as Markdown · View as text · Open in ChatGPT/Claude | right rail panel |
+| `CodeBlock` | **done** | variant: editor·terminal; `filename`, `lang`, `lineNumbers`, `statusBar` (vim NORMAL), `highlight`; slot: `CopyButton` | SQLite editor, terminal, snippet blocks |
+| `CopyButton` | **done** | `value`, `size` | code block + copy-command |
+| `CopyCommand` | **done** | `command`, prompt glyph | install one-liner |
+| `AppNav` | **done** | brand · `NavLinks` · `SearchTrigger` · `ThemeToggle` · `LocaleSwitcher` · `ChangelogButton` · `InstallButton` | top nav (all pages) |
+| `SectionTabs` | **done** | `items`, `active` | Start·Runtime·Toolchain·API·Resources |
+| `Sidebar` | **done** | `SectionSwitcher`, `NavGroup`, `NavItem` (active, external, comingSoon), progress | left nav |
+| `TableOfContents` | **done** | `items`, active-on-scroll; mono variant for API methods | right rail "On this page" |
+| `AiActions` | **done** | Copy as Markdown · View as text · Open in ChatGPT/Claude | right rail panel |
 | `Breadcrumbs` | **done** | `segments` | above page title |
 | `PageFooterNav` | **done** | `prev?`, `next?` (right-grouped cards) | bottom prev/next |
-| `CardGrid` + `FeatureCard` | todo | cols; card: icon·title·description·badge·href | "Start here", category grid |
-| `StatStrip` | todo | `stats: {value,label}[]` | API landing metrics |
-| `StatusBadge` | todo | thin wrapper over `Badge` status tones | reference status |
-| `ApiMethod` + `ParamRow` | todo | `signature`, `status`, params, example slot | node:fs entries |
-| `SupportMatrix` / `DataTable` | todo | columns, status cells (✓/✗) | method support table |
+| `CardGrid` + `FeatureCard` | **done** | cols; card: icon·title·description·badge·href | "Start here", category grid |
+| `StatStrip` | **done** | `stats: {value,label}[]` | API landing metrics |
+| `StatusBadge` | **done** | thin wrapper over `Badge` status tones | reference status |
+| `ApiMethod` + `ParamRow` | **done** | `signature`, `status`, params, example slot | node:fs entries |
+| `SupportMatrix` / `DataTable` | **done** | columns, status cells (✓/✗) | method support table |
 | `CommandPalette` | registry+ | built on `Command`; groups: pages·actions; recent | ⌘K overlay |
-| `MobileNav` | todo | top bar + `Sheet` drawer + bottom "Search or ask AI" bar | mobile screens |
+| `MobileNav` | **done** | top bar + `Sheet` drawer + bottom "Search or ask AI" bar | mobile screens |
 | `ThemeProvider` / `useTheme` | **done** | class/`data-theme` on `<html>`, persisted | dark/light toggle |
 
 ## Tier 3 — Marketing widgets (from elide.dev)
diff --git a/packages/ui/src/components/ai-actions.test.tsx b/packages/ui/src/components/ai-actions.test.tsx
new file mode 100644
index 0000000..b4a3f27
--- /dev/null
+++ b/packages/ui/src/components/ai-actions.test.tsx
@@ -0,0 +1,58 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { AiActions } from "./ai-actions";
+
+describe("AiActions", () => {
+  it("renders the panel with its title", () => {
+    render(<AiActions />);
+    expect(screen.getByText("Use with AI")).toBeInTheDocument();
+  });
+
+  it("supports a custom title", () => {
+    render(<AiActions title="Ask an assistant" />);
+    expect(screen.getByText("Ask an assistant")).toBeInTheDocument();
+  });
+
+  it("omits the Copy as Markdown button when no markdown is given", () => {
+    render(<AiActions />);
+    expect(screen.queryByRole("button", { name: /Copy as Markdown/ })).not.toBeInTheDocument();
+  });
+
+  it("copies the markdown to the clipboard when Copy as Markdown is clicked", async () => {
+    // `userEvent.setup()` installs its own clipboard stub as a getter-only
+    // property, so it must be overridden *after* setup (and via
+    // `defineProperty`, since plain assignment fails against the getter).
+    const user = userEvent.setup();
+    const writeText = vi.fn();
+    Object.defineProperty(navigator, "clipboard", { value: { writeText }, configurable: true });
+
+    render(<AiActions markdown="# Elide Overview" />);
+    await user.click(screen.getByRole("button", { name: /Copy as Markdown/ }));
+
+    expect(writeText).toHaveBeenCalledWith("# Elide Overview");
+  });
+
+  it("renders an external action as a new-tab anchor with an external-link icon", () => {
+    render(<AiActions actions={[{ label: "Open in Claude", href: "https://claude.ai", external: true }]} />);
+
+    const link = screen.getByRole("link", { name: "Open in Claude" });
+    expect(link).toHaveAttribute("target", "_blank");
+    expect(link.getAttribute("rel")).toContain("noopener");
+    expect(link.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("renders a non-external action as a plain anchor with no target", () => {
+    render(<AiActions actions={[{ label: "View as text", href: "#raw" }]} />);
+    expect(screen.getByRole("link", { name: "View as text" })).not.toHaveAttribute("target");
+  });
+
+  it("renders a callback action as a button and fires onClick", async () => {
+    const onClick = vi.fn();
+    const user = userEvent.setup();
+    render(<AiActions actions={[{ label: "Regenerate", onClick }]} />);
+
+    await user.click(screen.getByRole("button", { name: "Regenerate" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/ui/src/components/ai-actions.tsx b/packages/ui/src/components/ai-actions.tsx
new file mode 100644
index 0000000..a178a35
--- /dev/null
+++ b/packages/ui/src/components/ai-actions.tsx
@@ -0,0 +1,100 @@
+import * as React from "react";
+import { Check, Copy, ExternalLink, Sparkles } from "lucide-react";
+import { cn } from "../lib/utils";
+
+/**
+ * AiActions — the "Use with AI" panel in the docs right rail: copy the page as
+ * Markdown, or hand it off to an assistant (Open in Claude/ChatGPT, view as
+ * plain text). Actions are data-driven so callers own the destinations.
+ */
+export interface AiActionItem {
+  label: string;
+  href?: string;
+  icon?: React.ReactNode;
+  /** Opens `href` in a new tab and shows an external-link glyph. */
+  external?: boolean;
+  onClick?: () => void;
+}
+
+export interface AiActionsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  title?: React.ReactNode;
+  /** When given, renders a "Copy as Markdown" button that writes this to the clipboard. */
+  markdown?: string;
+  actions?: AiActionItem[];
+}
+
+const itemClass =
+  "flex items-center gap-2 rounded-lg border border-border bg-muted px-2.5 py-2 text-left text-[12.5px] font-medium text-foreground no-underline transition-colors hover:bg-accent";
+
+export function AiActions({
+  title = "Use with AI",
+  markdown,
+  actions = [],
+  className,
+  ...props
+}: AiActionsProps) {
+  const [copied, setCopied] = React.useState(false);
+
+  return (
+    <div
+      className={cn("flex flex-col gap-2 rounded-xl border border-border bg-card p-3.5", className)}
+      {...props}
+    >
+      <div className="mb-0.5 flex items-center gap-1.5 font-mono text-[11px] font-semibold tracking-wider text-subtle-foreground uppercase">
+        <Sparkles aria-hidden className="h-[13px] w-[13px] text-[var(--primary)]" />
+        {title}
+      </div>
+
+      {markdown ? (
+        <button
+          type="button"
+          onClick={() => {
+            void navigator.clipboard?.writeText(markdown);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1500);
+          }}
+          className={itemClass}
+        >
+          {copied ? (
+            <Check aria-hidden className="h-3.5 w-3.5 shrink-0" />
+          ) : (
+            <Copy aria-hidden className="h-3.5 w-3.5 shrink-0" />
+          )}
+          {copied ? "Copied" : "Copy as Markdown"}
+        </button>
+      ) : null}
+
+      {actions.map((action) => {
+        const content = (
+          <>
+            <span className="flex-1">{action.label}</span>
+            {action.icon ??
+              (action.external ? (
+                <ExternalLink aria-hidden className="h-[13px] w-[13px] shrink-0 text-subtle-foreground" />
+              ) : null)}
+          </>
+        );
+        return action.href ? (
+          <a
+            key={action.label}
+            href={action.href}
+            onClick={action.onClick}
+            className={cn(itemClass, "justify-between")}
+            {...(action.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+          >
+            {content}
+          </a>
+        ) : (
+          <button
+            key={action.label}
+            type="button"
+            onClick={action.onClick}
+            className={cn(itemClass, "justify-between")}
+          >
+            {content}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/api-method.test.tsx b/packages/ui/src/components/api-method.test.tsx
new file mode 100644
index 0000000..3c70c66
--- /dev/null
+++ b/packages/ui/src/components/api-method.test.tsx
@@ -0,0 +1,48 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { ApiMethod, ParamRow } from "./api-method";
+
+describe("ParamRow", () => {
+  it("renders the name, type, and description", () => {
+    render(<ParamRow name="path" type="string | Buffer | URL" description="Filename to read." />);
+    expect(screen.getByText("path")).toBeInTheDocument();
+    expect(screen.getByText("string | Buffer | URL")).toBeInTheDocument();
+    expect(screen.getByText("Filename to read.")).toBeInTheDocument();
+  });
+});
+
+describe("ApiMethod", () => {
+  it("renders the signature and status badge", () => {
+    const { container } = render(
+      <ApiMethod signature="fs.readFile(path[, options], callback)" status="supported" />,
+    );
+    expect(container).toHaveTextContent("fs.readFile(path[, options], callback)");
+    expect(screen.getByText("Supported")).toBeInTheDocument();
+  });
+
+  it("renders params via ParamRow", () => {
+    render(
+      <ApiMethod
+        signature="fs.readFile()"
+        params={[
+          { name: "path", type: "string", description: "Filename." },
+          { name: "callback", type: "Function", description: "Called on completion." },
+        ]}
+      />,
+    );
+    expect(screen.getByText("path")).toBeInTheDocument();
+    expect(screen.getByText("callback")).toBeInTheDocument();
+    expect(screen.getByText("Called on completion.")).toBeInTheDocument();
+  });
+
+  it("uses anchorId as the element id and links to it", () => {
+    const { container } = render(<ApiMethod signature="fs.readFile()" anchorId="fs-readfile" />);
+    expect(container.querySelector("#fs-readfile")).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /Link to/ })).toHaveAttribute("href", "#fs-readfile");
+  });
+
+  it("renders example content", () => {
+    render(<ApiMethod signature="fs.readFile()" example={<div>{'console.log("hi")'}</div>} />);
+    expect(screen.getByText('console.log("hi")')).toBeInTheDocument();
+  });
+});
diff --git a/packages/ui/src/components/api-method.tsx b/packages/ui/src/components/api-method.tsx
new file mode 100644
index 0000000..40e9de1
--- /dev/null
+++ b/packages/ui/src/components/api-method.tsx
@@ -0,0 +1,103 @@
+import * as React from "react";
+import { Hash } from "lucide-react";
+import { cn } from "../lib/utils";
+import { StatusBadge, type ApiStatus } from "./status-badge";
+
+/**
+ * ParamRow — one parameter line inside an `ApiMethod` entry: a fixed-width
+ * monospace name, its type, and a free-form description (may contain inline
+ * `code`).
+ */
+export interface ParamRowProps {
+  name: string;
+  type: string;
+  description?: React.ReactNode;
+  className?: string;
+}
+
+export function ParamRow({ name, type, description, className }: ParamRowProps) {
+  return (
+    <div className={cn("flex items-baseline gap-3", className)}>
+      <code className="w-24 shrink-0 font-mono text-[12.5px] text-[var(--primary)]">{name}</code>
+      <span className="shrink-0 font-mono text-xs text-[var(--eld-syntax-type)]">{type}</span>
+      {description ? (
+        <span className="text-[13.5px] text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary)]">
+          {description}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+/** Emphasize the function-name portion of a plain-string signature (up to the first `(`). */
+function emphasizeSignature(signature: string | React.ReactNode) {
+  if (typeof signature !== "string") return signature;
+  const parenIndex = signature.indexOf("(");
+  if (parenIndex === -1) return signature;
+  return (
+    <>
+      <span className="text-[var(--eld-syntax-function)]">{signature.slice(0, parenIndex)}</span>
+      {signature.slice(parenIndex)}
+    </>
+  );
+}
+
+/**
+ * ApiMethod — a single method entry in a node:-compatibility reference page
+ * (mockup 2b, node:fs): a signature + status + anchor link, a description,
+ * typed params (`ParamRow`), and an optional example — pass a shipped
+ * `CodeBlock` as `example`.
+ */
+export interface ApiMethodProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
+  signature: string | React.ReactNode;
+  status?: ApiStatus;
+  description?: React.ReactNode;
+  params?: ParamRowProps[];
+  example?: React.ReactNode;
+  /** Anchor id for TOC/deep-linking; also renders a `#` link next to the signature. */
+  anchorId?: string;
+}
+
+export function ApiMethod({
+  signature,
+  status,
+  description,
+  params,
+  example,
+  anchorId,
+  className,
+  ...props
+}: ApiMethodProps) {
+  return (
+    <div id={anchorId} className={cn("border-t border-border pt-6", className)} {...props}>
+      <div className="mb-3 flex flex-wrap items-center gap-2.5">
+        <code className="font-mono text-[17px] font-medium leading-snug text-foreground">
+          {emphasizeSignature(signature)}
+        </code>
+        {status ? <StatusBadge status={status} size="sm" /> : null}
+        {anchorId ? (
+          <a
+            href={`#${anchorId}`}
+            aria-label={`Link to ${typeof signature === "string" ? signature : "this method"}`}
+            className="text-[var(--primary)] opacity-55 transition-opacity hover:opacity-100"
+          >
+            <Hash aria-hidden className="h-3.5 w-3.5" />
+          </a>
+        ) : null}
+      </div>
+      {description ? (
+        <p className="mb-4 max-w-[640px] text-[14.5px] leading-relaxed text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary)]">
+          {description}
+        </p>
+      ) : null}
+      {params && params.length > 0 ? (
+        <div className="mb-4 flex flex-col gap-2">
+          {params.map((param) => (
+            <ParamRow key={param.name} {...param} />
+          ))}
+        </div>
+      ) : null}
+      {example ? <div className="max-w-[640px]">{example}</div> : null}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/app-nav.test.tsx b/packages/ui/src/components/app-nav.test.tsx
new file mode 100644
index 0000000..00f47b8
--- /dev/null
+++ b/packages/ui/src/components/app-nav.test.tsx
@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { AppNav } from "./app-nav";
+
+const links = [
+  { label: "Docs", href: "#docs", active: true },
+  { label: "Enterprise", href: "#enterprise" },
+  { label: "Blog", href: "#blog" },
+  { label: "Pricing", href: "#pricing" },
+];
+
+describe("AppNav", () => {
+  it("renders every link", () => {
+    render(<AppNav links={links} />);
+    expect(screen.getByRole("link", { name: "Docs" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Enterprise" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Blog" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Pricing" })).toBeInTheDocument();
+  });
+
+  it("marks the active link with aria-current, and only that link", () => {
+    render(<AppNav links={links} />);
+    expect(screen.getByRole("link", { name: "Docs" })).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("link", { name: "Enterprise" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("renders the install button", () => {
+    render(<AppNav links={links} />);
+    expect(screen.getByRole("link", { name: "Install" })).toBeInTheDocument();
+  });
+
+  it("calls onSearchClick when the search trigger is clicked", async () => {
+    const user = userEvent.setup();
+    const onSearchClick = vi.fn();
+    render(<AppNav links={links} onSearchClick={onSearchClick} />);
+
+    await user.click(screen.getByRole("button", { name: "Search" }));
+    expect(onSearchClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/ui/src/components/app-nav.tsx b/packages/ui/src/components/app-nav.tsx
new file mode 100644
index 0000000..89ed08e
--- /dev/null
+++ b/packages/ui/src/components/app-nav.tsx
@@ -0,0 +1,140 @@
+import * as React from "react";
+import { ChevronDown, Globe, History, Search, Sparkles, Sun } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "./button";
+
+/**
+ * AppNav — the 56px top nav bar present on every docs page: brand + "DOCS"
+ * pill, primary section links, a search trigger, and the theme/locale/
+ * changelog/install cluster. Purely presentational — callers own routing,
+ * theme state, and the search/locale overlays; this just renders the bar and
+ * fires callbacks.
+ */
+export interface NavLink {
+  label: string;
+  href: string;
+  active?: boolean;
+}
+
+export interface AppNavProps extends React.ComponentProps<"nav"> {
+  links: NavLink[];
+  /** Defaults to a text/mark fallback — pass your own logo element to override. */
+  logo?: React.ReactNode;
+  searchPlaceholder?: string;
+  /** Current locale label shown in the switcher (e.g. "EN"). */
+  locale?: string;
+  installHref?: string;
+  changelogHref?: string;
+  onSearchClick?: () => void;
+  onThemeToggle?: () => void;
+  onLocaleClick?: () => void;
+}
+
+const defaultLogo = (
+  <span className="flex items-center gap-1.5">
+    <span
+      aria-hidden
+      className="flex h-5 w-5 items-center justify-center rounded-md text-[11px] font-bold text-white [background:var(--eld-gradient-brand)]"
+    >
+      e
+    </span>
+    <span className="font-display text-sm font-semibold text-foreground">Elide</span>
+  </span>
+);
+
+export function AppNav({
+  links,
+  logo,
+  searchPlaceholder = "Search or ask AI…",
+  locale = "EN",
+  installHref = "/install",
+  changelogHref = "/changelog",
+  onSearchClick,
+  onThemeToggle,
+  onLocaleClick,
+  className,
+  ...props
+}: AppNavProps) {
+  return (
+    <nav
+      aria-label="Main navigation"
+      className={cn(
+        "flex h-14 items-center gap-[18px] border-b border-border px-[22px] backdrop-blur-xl [background:var(--nav-background)]",
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex items-center gap-2">
+        {logo ?? defaultLogo}
+        <span className="rounded-md border border-border-strong px-[7px] py-0.5 font-mono text-[10px] font-semibold tracking-wider text-muted-foreground">
+          DOCS
+        </span>
+      </div>
+
+      <span aria-hidden className="h-[22px] w-px bg-border" />
+
+      <div className="flex items-center gap-0.5 text-[13.5px]">
+        {links.map((link) => (
+          <a
+            key={link.href}
+            href={link.href}
+            aria-current={link.active ? "page" : undefined}
+            className={cn(
+              "rounded-[7px] px-2.5 py-1.5 transition-colors hover:bg-[var(--hover)]",
+              link.active
+                ? "font-medium text-foreground"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            {link.label}
+          </a>
+        ))}
+      </div>
+
+      <span className="flex-1" />
+
+      <button
+        type="button"
+        onClick={onSearchClick}
+        aria-label="Search"
+        className="flex h-[34px] w-[280px] items-center gap-2 rounded-[9px] border border-border bg-muted px-3 text-subtle-foreground transition-colors hover:border-border-strong"
+      >
+        <Search aria-hidden className="h-[15px] w-[15px] shrink-0" />
+        <span className="flex-1 text-left text-[13px]">{searchPlaceholder}</span>
+        <Sparkles aria-hidden className="h-[13px] w-[13px] shrink-0 text-primary" />
+        <kbd className="rounded-[5px] border border-border-strong px-1.5 py-px font-mono text-[11px] font-medium">
+          ⌘K
+        </kbd>
+      </button>
+
+      <button
+        type="button"
+        onClick={onThemeToggle}
+        aria-label="Toggle theme"
+        className="flex h-[34px] w-[34px] items-center justify-center rounded-[9px] border border-border text-muted-foreground transition-colors hover:bg-[var(--hover)] hover:text-foreground"
+      >
+        <Sun aria-hidden className="h-4 w-4" />
+      </button>
+
+      <button
+        type="button"
+        onClick={onLocaleClick}
+        aria-label="Language"
+        className="flex h-[34px] items-center gap-1.5 rounded-[9px] border border-border px-[11px] text-[12.5px] font-medium text-muted-foreground transition-colors hover:bg-[var(--hover)] hover:text-foreground"
+      >
+        <Globe aria-hidden className="h-[15px] w-[15px]" />
+        {locale}
+        <ChevronDown aria-hidden className="h-[13px] w-[13px]" />
+      </button>
+
+      <Button variant="changelog" size="sm" render={<a href={changelogHref} />}>
+        <History aria-hidden className="h-[15px] w-[15px]" />
+        Changelog
+      </Button>
+
+      <Button variant="gradient" size="sm" render={<a href={installHref} />}>
+        Install
+      </Button>
+    </nav>
+  );
+}
diff --git a/packages/ui/src/components/card-grid.test.tsx b/packages/ui/src/components/card-grid.test.tsx
new file mode 100644
index 0000000..1009706
--- /dev/null
+++ b/packages/ui/src/components/card-grid.test.tsx
@@ -0,0 +1,90 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { CardGrid, FeatureCard } from "./card-grid";
+
+describe("FeatureCard", () => {
+  it("renders the title and description", () => {
+    render(<FeatureCard title="API Overview" description="Runtime, globals, and modules." />);
+    expect(screen.getByText("API Overview")).toBeInTheDocument();
+    expect(screen.getByText("Runtime, globals, and modules.")).toBeInTheDocument();
+  });
+
+  it("renders a trailing badge", () => {
+    render(<FeatureCard title="Node Compatibility" badge={<span>24</span>} />);
+    expect(screen.getByText("24")).toBeInTheDocument();
+  });
+
+  it("renders as a link when given an href", () => {
+    render(<FeatureCard title="Web Standards" href="/web-standards" />);
+    expect(screen.getByRole("link", { name: /Web Standards/ })).toHaveAttribute(
+      "href",
+      "/web-standards",
+    );
+  });
+
+  it("opens external links in a new tab with a safe rel and shows the external icon", () => {
+    render(<FeatureCard title="Database Modules" href="https://example.com" external />);
+    const link = screen.getByRole("link", { name: /Database Modules/ });
+    expect(link).toHaveAttribute("target", "_blank");
+    expect(link.getAttribute("rel")).toContain("noopener");
+    expect(link.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("does not render as a link when no href is given", () => {
+    render(<FeatureCard title="Host APIs" />);
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+  });
+
+  it("calls onSelect when clicked", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<FeatureCard title="Host APIs" href="#host-apis" onSelect={onSelect} />);
+    await user.click(screen.getByRole("link", { name: /Host APIs/ }));
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  it("is keyboard-activatable when rendered without an href", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<FeatureCard title="Database Modules" onSelect={onSelect} />);
+    const card = screen.getByRole("button", { name: /Database Modules/ });
+    card.focus();
+    await user.keyboard("{Enter}");
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("CardGrid", () => {
+  it("renders every child", () => {
+    render(
+      <CardGrid>
+        <FeatureCard title="One" />
+        <FeatureCard title="Two" />
+        <FeatureCard title="Three" />
+      </CardGrid>,
+    );
+    expect(screen.getByText("One")).toBeInTheDocument();
+    expect(screen.getByText("Two")).toBeInTheDocument();
+    expect(screen.getByText("Three")).toBeInTheDocument();
+  });
+
+  it("defaults to three columns", () => {
+    const { container } = render(
+      <CardGrid>
+        <FeatureCard title="One" />
+      </CardGrid>,
+    );
+    expect(container.firstChild).toHaveClass("lg:grid-cols-3");
+  });
+
+  it("applies a requested column count", () => {
+    const { container } = render(
+      <CardGrid columns={2}>
+        <FeatureCard title="One" />
+      </CardGrid>,
+    );
+    expect(container.firstChild).toHaveClass("sm:grid-cols-2");
+    expect(container.firstChild).not.toHaveClass("lg:grid-cols-3");
+  });
+});
diff --git a/packages/ui/src/components/card-grid.tsx b/packages/ui/src/components/card-grid.tsx
new file mode 100644
index 0000000..7177584
--- /dev/null
+++ b/packages/ui/src/components/card-grid.tsx
@@ -0,0 +1,120 @@
+import * as React from "react";
+import { ExternalLink } from "lucide-react";
+import { cn } from "../lib/utils";
+
+/**
+ * FeatureCard — an icon-chip card that links (or triggers a callback) into a
+ * section: category tiles on the API landing page, the mobile "Start here"
+ * list. Renders as an anchor when `href` is given, otherwise a clickable
+ * `div` so a caller can drive navigation itself via `onSelect`.
+ */
+export interface FeatureCardProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  href?: string;
+  icon?: React.ReactNode;
+  /** Trailing indicator, e.g. a count `Badge`. */
+  badge?: React.ReactNode;
+  /** Opens `href` in a new tab and shows an external-link glyph. */
+  external?: boolean;
+  onSelect?: () => void;
+}
+
+const cardBase =
+  "group flex flex-col gap-2 rounded-xl border border-border bg-card p-4 text-left no-underline transition-[transform,background-color,border-color]";
+const cardInteractive =
+  "cursor-pointer hover:-translate-y-px hover:border-border-strong hover:bg-[var(--hover)]";
+
+export function FeatureCard({
+  title,
+  description,
+  href,
+  icon,
+  badge,
+  external,
+  onSelect,
+  className,
+  ...props
+}: FeatureCardProps) {
+  const interactive = Boolean(href || onSelect);
+  const cardClassName = cn(cardBase, interactive && cardInteractive, className);
+
+  const content = (
+    <>
+      {icon ? (
+        <span className="flex h-8 w-8 items-center justify-center rounded-[9px] bg-[var(--primary-soft)] text-[var(--primary-emphasis)] [&_svg]:h-[17px] [&_svg]:w-[17px]">
+          {icon}
+        </span>
+      ) : null}
+      <div className="flex items-center gap-2">
+        <span className="text-[14.5px] font-semibold text-foreground">{title}</span>
+        {external ? (
+          <ExternalLink aria-hidden className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+        ) : null}
+        {badge ? <span className="ml-auto shrink-0">{badge}</span> : null}
+      </div>
+      {description ? (
+        <p className="text-[12.5px] leading-relaxed text-muted-foreground">{description}</p>
+      ) : null}
+    </>
+  );
+
+  if (href) {
+    return (
+      <a
+        href={href}
+        onClick={onSelect}
+        className={cardClassName}
+        {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+        {...props}
+      >
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <div
+      role={onSelect ? "button" : undefined}
+      tabIndex={onSelect ? 0 : undefined}
+      onClick={onSelect}
+      onKeyDown={
+        onSelect
+          ? (event) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                onSelect();
+              }
+            }
+          : undefined
+      }
+      className={cardClassName}
+      {...props}
+    >
+      {content}
+    </div>
+  );
+}
+
+/**
+ * CardGrid — responsive wrapper for `FeatureCard`s (or arbitrary children):
+ * the "Browse by category" API grid, the mobile "Start here" stack.
+ * Collapses to a single column on small widths regardless of `columns`.
+ */
+export interface CardGridProps extends React.HTMLAttributes<HTMLDivElement> {
+  columns?: 1 | 2 | 3;
+}
+
+const columnClasses: Record<NonNullable<CardGridProps["columns"]>, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-1 sm:grid-cols-2",
+  3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+};
+
+export function CardGrid({ columns = 3, className, children, ...props }: CardGridProps) {
+  return (
+    <div className={cn("grid gap-3.5", columnClasses[columns], className)} {...props}>
+      {children}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/code-block.tsx b/packages/ui/src/components/code-block.tsx
index e0061fd..76fd492 100644
--- a/packages/ui/src/components/code-block.tsx
+++ b/packages/ui/src/components/code-block.tsx
@@ -19,9 +19,12 @@ export function CopyButton({
   return (
     <button
       type="button"
-      aria-label={label || "Copy"}
+      aria-label={copied ? "Copied" : label || "Copy"}
       onClick={() => {
-        void navigator.clipboard?.writeText(value);
+        // Swallow clipboard rejections (e.g. no permission in a headless/denied
+        // context) — the copy is optimistic and a failure shouldn't surface as an
+        // unhandled promise rejection.
+        void navigator.clipboard?.writeText(value)?.catch(() => {});
         setCopied(true);
         setTimeout(() => setCopied(false), 1500);
       }}
diff --git a/packages/ui/src/components/copy-command.test.tsx b/packages/ui/src/components/copy-command.test.tsx
new file mode 100644
index 0000000..5eed9db
--- /dev/null
+++ b/packages/ui/src/components/copy-command.test.tsx
@@ -0,0 +1,36 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { CopyCommand } from "./copy-command";
+
+describe("CopyCommand", () => {
+  it("renders the command and the default prompt glyph", () => {
+    render(<CopyCommand command="curl elide.sh | bash" />);
+    expect(screen.getByText("curl elide.sh | bash")).toBeInTheDocument();
+    expect(screen.getByText("$")).toBeInTheDocument();
+  });
+
+  it("supports a custom prompt glyph", () => {
+    render(<CopyCommand command="elide run app.ts" prompt=">" />);
+    expect(screen.getByText(">")).toBeInTheDocument();
+  });
+
+  it("gives the copy button an accessible name", () => {
+    render(<CopyCommand command="curl elide.sh | bash" />);
+    expect(screen.getByRole("button", { name: "Copy" })).toBeInTheDocument();
+  });
+
+  it("copies the command to the clipboard when the copy button is clicked", async () => {
+    // `userEvent.setup()` installs its own clipboard stub as a getter-only
+    // property, so it must be overridden *after* setup (and via
+    // `defineProperty`, since plain assignment fails against the getter).
+    const user = userEvent.setup();
+    const writeText = vi.fn();
+    Object.defineProperty(navigator, "clipboard", { value: { writeText }, configurable: true });
+
+    render(<CopyCommand command="curl elide.sh | bash" />);
+    await user.click(screen.getByRole("button", { name: "Copy" }));
+
+    expect(writeText).toHaveBeenCalledWith("curl elide.sh | bash");
+  });
+});
diff --git a/packages/ui/src/components/copy-command.tsx b/packages/ui/src/components/copy-command.tsx
new file mode 100644
index 0000000..b5cd7ee
--- /dev/null
+++ b/packages/ui/src/components/copy-command.tsx
@@ -0,0 +1,41 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { CopyButton } from "./code-block";
+
+/**
+ * CopyCommand — the single-line install command (`$ curl elide.sh | bash`):
+ * a prompt glyph, the command in monospace, and a copy affordance. Shares the
+ * dark code surface with `CodeBlock` and reuses its `CopyButton`.
+ */
+export interface CopyCommandProps extends React.HTMLAttributes<HTMLDivElement> {
+  command: string;
+  /** Prompt glyph shown before the command. */
+  prompt?: string;
+  /** Visible label next to the copy icon; icon-only (matching the mockup) when omitted. */
+  label?: string;
+}
+
+export function CopyCommand({ command, prompt = "$", label = "", className, ...props }: CopyCommandProps) {
+  return (
+    <div
+      className={cn("flex items-center gap-2.5 rounded-xl border px-3.5 py-3", className)}
+      style={{ background: "var(--code-background)", borderColor: "var(--code-border)" }}
+      {...props}
+    >
+      <span
+        aria-hidden
+        className="font-mono text-[12.5px]"
+        style={{ color: "var(--eld-syntax-comment)" }}
+      >
+        {prompt}
+      </span>
+      <code
+        className="flex-1 overflow-x-auto font-mono text-[12.5px] whitespace-nowrap"
+        style={{ color: "var(--eld-syntax-default)" }}
+      >
+        {command}
+      </code>
+      <CopyButton value={command} label={label} className="shrink-0 border-[var(--code-border)]" />
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/mobile-nav.test.tsx b/packages/ui/src/components/mobile-nav.test.tsx
new file mode 100644
index 0000000..b03859f
--- /dev/null
+++ b/packages/ui/src/components/mobile-nav.test.tsx
@@ -0,0 +1,59 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { MobileNav } from "./mobile-nav";
+
+const groups = [
+  {
+    label: "Introduction",
+    items: [
+      { label: "Overview", href: "#overview", active: true },
+      { label: "Install Elide", href: "#install" },
+    ],
+  },
+  {
+    label: "By language",
+    items: [{ label: "Python", href: "#python" }],
+  },
+];
+
+describe("MobileNav", () => {
+  it("renders the top app bar's hamburger and search buttons", () => {
+    render(<MobileNav groups={groups} />);
+    expect(screen.getByRole("button", { name: "Open navigation" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Search" })).toBeInTheDocument();
+  });
+
+  it("opens the drawer on hamburger click, revealing the grouped links", async () => {
+    const user = userEvent.setup();
+    render(<MobileNav groups={groups} />);
+
+    // Sheet portals its content to document.body — not present until opened.
+    expect(screen.queryByRole("link", { name: "Overview" })).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Open navigation" }));
+
+    expect(screen.getByRole("navigation", { name: "Mobile navigation" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Overview" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Install Elide" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Python" })).toBeInTheDocument();
+  });
+
+  it("marks the active drawer item with aria-current", async () => {
+    const user = userEvent.setup();
+    render(<MobileNav groups={groups} />);
+    await user.click(screen.getByRole("button", { name: "Open navigation" }));
+
+    expect(screen.getByRole("link", { name: "Overview" })).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("link", { name: "Install Elide" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("fires onSearch when the bottom search bar is clicked", async () => {
+    const user = userEvent.setup();
+    const onSearch = vi.fn();
+    render(<MobileNav groups={groups} onSearch={onSearch} />);
+
+    await user.click(screen.getByRole("button", { name: /search or ask ai/i }));
+    expect(onSearch).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/ui/src/components/mobile-nav.tsx b/packages/ui/src/components/mobile-nav.tsx
new file mode 100644
index 0000000..85fbace
--- /dev/null
+++ b/packages/ui/src/components/mobile-nav.tsx
@@ -0,0 +1,176 @@
+import * as React from "react";
+import { History, Menu, Search, Sparkle } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "./button";
+import { Sheet, SheetTrigger, SheetContent } from "./sheet";
+
+/**
+ * MobileNav — the docs shell at phone width (mockup 3b): a condensed top app
+ * bar, a slide-in section drawer (built on the shipped `Sheet`), and a
+ * persistent bottom "Search or ask AI" bar. Data-driven and presentational —
+ * callers own routing (`href`s) and the search/AI action.
+ */
+export interface MobileNavItem {
+  label: string;
+  href?: string;
+  active?: boolean;
+}
+
+export interface MobileNavGroup {
+  label: string;
+  items: MobileNavItem[];
+}
+
+export interface MobileNavSection {
+  title: string;
+  subtitle?: string;
+  icon?: React.ReactNode;
+}
+
+export interface MobileNavProps extends Omit<React.ComponentProps<"div">, "onSearch"> {
+  /** Grouped drawer links, e.g. "Introduction" / "By language". */
+  groups: MobileNavGroup[];
+  /** The current section's header, shown atop the drawer (e.g. "Start"). */
+  section?: MobileNavSection;
+  /** Brand slot rendered in the app bar (logo + wordmark, a "DOCS" pill, …). */
+  logo?: React.ReactNode;
+  /** Fired by the app-bar search icon and the bottom search pill. */
+  onSearch?: () => void;
+  /** Renders the drawer footer as a link when set, a plain button otherwise. */
+  changelogHref?: string;
+  searchPlaceholder?: string;
+  /** Controlled drawer state; falls back to internal state when omitted. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export function MobileNav({
+  groups,
+  section,
+  logo,
+  onSearch,
+  changelogHref,
+  searchPlaceholder = "Search or ask AI…",
+  open,
+  onOpenChange,
+  className,
+  children,
+  ...props
+}: MobileNavProps) {
+  const [internalOpen, setInternalOpen] = React.useState(false);
+  const drawerOpen = open ?? internalOpen;
+  const setDrawerOpen = React.useCallback(
+    (next: boolean) => {
+      if (open === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [open, onOpenChange],
+  );
+
+  return (
+    <Sheet open={drawerOpen} onOpenChange={setDrawerOpen}>
+      <div className={cn("flex flex-col bg-background text-foreground", className)} {...props}>
+        <header className="flex h-[52px] shrink-0 items-center gap-3 border-b border-border px-4">
+          <SheetTrigger
+            render={
+              <Button
+                variant="outline"
+                size="icon"
+                aria-label="Open navigation"
+                className={cn(
+                  drawerOpen && "border-[var(--primary)] bg-[var(--primary-soft)] text-[var(--primary)]",
+                )}
+              />
+            }
+          >
+            <Menu aria-hidden className="h-[18px] w-[18px]" />
+          </SheetTrigger>
+          <div className="flex flex-1 items-center gap-2 overflow-hidden">{logo}</div>
+          <Button variant="outline" size="icon" aria-label="Search" onClick={onSearch}>
+            <Search aria-hidden className="h-[17px] w-[17px]" />
+          </Button>
+        </header>
+
+        {children}
+
+        <div className="mt-auto shrink-0 border-t border-border bg-[var(--nav-background)] px-4 py-3">
+          <button
+            type="button"
+            onClick={onSearch}
+            className="flex h-11 w-full items-center gap-2.5 rounded-xl border border-[var(--border-strong)] bg-[var(--muted)] px-3.5 text-[var(--subtle-foreground)]"
+          >
+            <Search aria-hidden className="h-4 w-4 text-[var(--primary)]" />
+            <span className="flex-1 text-left text-sm">{searchPlaceholder}</span>
+            <Sparkle aria-hidden className="h-[15px] w-[15px] text-[var(--primary)]" />
+          </button>
+        </div>
+      </div>
+
+      <SheetContent side="left" showCloseButton={false} className="flex w-72 flex-col gap-5 p-4">
+        {section ? (
+          <div className="flex items-center gap-2.5">
+            {section.icon ? (
+              <span
+                aria-hidden
+                className="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg bg-[var(--primary-soft)] text-[var(--primary)]"
+              >
+                {section.icon}
+              </span>
+            ) : null}
+            <div>
+              <div className="text-sm font-semibold text-foreground">{section.title}</div>
+              {section.subtitle ? (
+                <div className="text-xs text-[var(--subtle-foreground)]">{section.subtitle}</div>
+              ) : null}
+            </div>
+          </div>
+        ) : null}
+
+        <nav aria-label="Mobile navigation" className="flex flex-1 flex-col gap-4 overflow-y-auto">
+          {groups.map((group) => (
+            <div key={group.label} className="flex flex-col gap-1">
+              <div className="px-2.5 font-mono text-[10.5px] font-semibold uppercase tracking-wider text-[var(--subtle-foreground)]">
+                {group.label}
+              </div>
+              {group.items.map((item) => {
+                const linkClassName = cn(
+                  "rounded-lg px-2.5 py-2 text-sm",
+                  item.active
+                    ? "font-semibold text-[var(--primary)] bg-[var(--primary-soft)]"
+                    : "text-muted-foreground",
+                );
+                return item.href ? (
+                  <a
+                    key={item.label}
+                    href={item.href}
+                    aria-current={item.active ? "page" : undefined}
+                    className={linkClassName}
+                  >
+                    {item.label}
+                  </a>
+                ) : (
+                  <span
+                    key={item.label}
+                    aria-current={item.active ? "page" : undefined}
+                    className={linkClassName}
+                  >
+                    {item.label}
+                  </span>
+                );
+              })}
+            </div>
+          ))}
+        </nav>
+
+        <Button
+          variant="changelog"
+          className="w-full justify-start"
+          render={changelogHref ? <a href={changelogHref} /> : undefined}
+        >
+          <History aria-hidden className="h-[15px] w-[15px]" />
+          Changelog
+        </Button>
+      </SheetContent>
+    </Sheet>
+  );
+}
diff --git a/packages/ui/src/components/section-tabs.test.tsx b/packages/ui/src/components/section-tabs.test.tsx
new file mode 100644
index 0000000..f98d4ca
--- /dev/null
+++ b/packages/ui/src/components/section-tabs.test.tsx
@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { SectionTabs } from "./section-tabs";
+
+const items = [
+  { label: "Start", href: "#start" },
+  { label: "Runtime", href: "#runtime", active: true },
+  { label: "Toolchain", href: "#toolchain" },
+];
+
+describe("SectionTabs", () => {
+  it("renders every item as a link", () => {
+    render(<SectionTabs items={items} />);
+    expect(screen.getByRole("link", { name: "Start" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Runtime" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Toolchain" })).toBeInTheDocument();
+  });
+
+  it("marks the active item with aria-current, and only that item", () => {
+    render(<SectionTabs items={items} />);
+    expect(screen.getByRole("link", { name: "Runtime" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    expect(screen.getByRole("link", { name: "Start" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("renders the version label", () => {
+    render(<SectionTabs items={items} version={{ label: "v1.0.0-beta5", status: "ok" }} />);
+    expect(screen.getByText("v1.0.0-beta5")).toBeInTheDocument();
+  });
+
+  it("calls onSelect with the item's href when clicked", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<SectionTabs items={items} onSelect={onSelect} />);
+
+    await user.click(screen.getByRole("link", { name: "Toolchain" }));
+    expect(onSelect).toHaveBeenCalledWith("#toolchain");
+  });
+});
diff --git a/packages/ui/src/components/section-tabs.tsx b/packages/ui/src/components/section-tabs.tsx
new file mode 100644
index 0000000..a5f7b78
--- /dev/null
+++ b/packages/ui/src/components/section-tabs.tsx
@@ -0,0 +1,86 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * SectionTabs — the 46px top-level section bar under the main nav (Start ·
+ * Runtime · Toolchain · API Reference · Resources), with a right-aligned
+ * version indicator. These are plain section links, not ARIA tabs — there is
+ * no associated tabpanel, so we render a `<nav>` of anchors rather than
+ * `role="tablist"`.
+ */
+export interface SectionTabItem {
+  label: string;
+  href: string;
+  active?: boolean;
+}
+
+export interface SectionTabsVersion {
+  label: string;
+  status?: "ok" | "beta" | "warn";
+}
+
+export interface SectionTabsProps extends Omit<React.ComponentProps<"nav">, "onSelect"> {
+  items: SectionTabItem[];
+  version?: SectionTabsVersion;
+  onSelect?: (href: string) => void;
+}
+
+const dotColor: Record<NonNullable<SectionTabsVersion["status"]>, string> = {
+  ok: "var(--eld-success-strong)",
+  beta: "var(--eld-info)",
+  warn: "var(--eld-warning-strong)",
+};
+
+export function SectionTabs({ items, version, onSelect, className, ...props }: SectionTabsProps) {
+  return (
+    <nav
+      aria-label="Sections"
+      className={cn(
+        "flex h-[46px] items-center gap-1 border-b border-border bg-background px-[22px]",
+        className,
+      )}
+      {...props}
+    >
+      {items.map((item) => (
+        <a
+          key={item.href}
+          href={item.href}
+          aria-current={item.active ? "page" : undefined}
+          onClick={
+            onSelect
+              ? (e) => {
+                  // Controlled selection: the consumer handles routing, so
+                  // suppress the anchor's own in-page hash navigation.
+                  e.preventDefault();
+                  onSelect(item.href);
+                }
+              : undefined
+          }
+          className={cn(
+            "relative px-3 py-3.5 text-[13.5px] text-muted-foreground transition-colors",
+            item.active && "font-semibold text-[var(--primary)]",
+          )}
+        >
+          {item.label}
+          {item.active ? (
+            <span
+              aria-hidden
+              className="absolute inset-x-3 -bottom-px h-0.5 rounded-full bg-[var(--primary)]"
+            />
+          ) : null}
+        </a>
+      ))}
+      <span className="flex-1" />
+      {version ? (
+        <span className="flex items-center gap-1.5 font-mono text-xs font-medium text-muted-foreground/80">
+          <span
+            aria-hidden
+            className="h-[7px] w-[7px] rounded-full"
+            style={{ background: dotColor[version.status ?? "ok"] }}
+          />
+          {version.label}
+        </span>
+      ) : null}
+    </nav>
+  );
+}
diff --git a/packages/ui/src/components/sidebar.test.tsx b/packages/ui/src/components/sidebar.test.tsx
new file mode 100644
index 0000000..e6973ed
--- /dev/null
+++ b/packages/ui/src/components/sidebar.test.tsx
@@ -0,0 +1,99 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { Sidebar, SidebarGroup, SidebarItem, SectionSwitcher } from "./sidebar";
+
+const sections = [
+  { id: "start", title: "Start", subtitle: "Get running in minutes" },
+  { id: "runtime", title: "Runtime", subtitle: "Run, serve, debug, and inspect" },
+];
+
+describe("SidebarItem", () => {
+  it("renders a link with the given label and href", () => {
+    render(<SidebarItem label="Debugging" href="#debugging" />);
+    expect(screen.getByRole("link", { name: "Debugging" })).toHaveAttribute("href", "#debugging");
+  });
+
+  it("marks the active item with aria-current", () => {
+    render(<SidebarItem label="Debugging" href="#debugging" active />);
+    expect(screen.getByRole("link", { name: "Debugging" })).toHaveAttribute("aria-current", "page");
+  });
+
+  it("does not set aria-current on inactive items", () => {
+    render(<SidebarItem label="REPL" href="#repl" />);
+    expect(screen.getByRole("link", { name: "REPL" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("renders external items with a trailing icon and target/rel", () => {
+    render(<SidebarItem label="elide.dev" href="https://elide.dev" external />);
+    const link = screen.getByRole("link", { name: "elide.dev" });
+    expect(link).toHaveAttribute("target", "_blank");
+    expect(link).toHaveAttribute("rel", "noopener noreferrer");
+    expect(link.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("fires onSelect when clicked", async () => {
+    const onSelect = vi.fn();
+    render(<SidebarItem label="Debugging" href="#debugging" onSelect={onSelect} />);
+    await userEvent.click(screen.getByRole("link", { name: "Debugging" }));
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders comingSoon items as non-navigating and marked 'Soon'", async () => {
+    const onSelect = vi.fn();
+    render(<SidebarItem label="Remote Debugging" comingSoon onSelect={onSelect} />);
+    expect(screen.queryByRole("link", { name: /Remote Debugging/ })).not.toBeInTheDocument();
+    const item = screen.getByText("Remote Debugging");
+    expect(item).toHaveAttribute("aria-disabled", "true");
+    expect(screen.getByText("Soon")).toBeInTheDocument();
+    await userEvent.click(item);
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});
+
+describe("SidebarGroup", () => {
+  it("renders its label and every item", () => {
+    render(
+      <SidebarGroup
+        label="Guides"
+        items={[
+          { label: "Debugging", href: "#debugging" },
+          { label: "REPL", href: "#repl" },
+        ]}
+      />,
+    );
+    expect(screen.getByText("Guides")).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Debugging" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "REPL" })).toBeInTheDocument();
+  });
+});
+
+describe("Sidebar", () => {
+  it("renders the section switcher and every group's items", () => {
+    render(
+      <Sidebar
+        sections={sections}
+        activeSectionId="runtime"
+        groups={[{ label: "Guides", items: [{ label: "Debugging", href: "#debugging", active: true }] }]}
+      />,
+    );
+    expect(screen.getByRole("navigation", { name: "Sidebar" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Runtime/ })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Debugging" })).toHaveAttribute("aria-current", "page");
+  });
+});
+
+describe("SectionSwitcher", () => {
+  it("opens to list every section and fires onSectionChange on select", async () => {
+    const onSectionChange = vi.fn();
+    render(<SectionSwitcher sections={sections} activeId="runtime" onSectionChange={onSectionChange} />);
+
+    await userEvent.click(screen.getByRole("button", { name: /Runtime/ }));
+
+    // The popup portals to document.body — `screen` already queries there.
+    const option = await screen.findByRole("menuitem", { name: /Start/ });
+    await userEvent.click(option);
+
+    expect(onSectionChange).toHaveBeenCalledWith("start");
+  });
+});
diff --git a/packages/ui/src/components/sidebar.tsx b/packages/ui/src/components/sidebar.tsx
new file mode 100644
index 0000000..b580433
--- /dev/null
+++ b/packages/ui/src/components/sidebar.tsx
@@ -0,0 +1,192 @@
+import * as React from "react";
+import { Check, ChevronDown, ExternalLink } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Badge } from "./badge";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "./dropdown-menu";
+
+/**
+ * Sidebar — the left nav column on docs pages: a `SectionSwitcher` (jumps
+ * between top-level doc sections, e.g. Runtime ↔ Toolchain) above a static
+ * stack of labeled `SidebarGroup`s. Purely presentational — callers own
+ * routing and pass `active`/`comingSoon` per item.
+ */
+export interface SidebarSection {
+  id: string;
+  title: string;
+  subtitle?: string;
+  icon?: React.ReactNode;
+}
+
+export interface SectionSwitcherProps extends React.ComponentProps<"button"> {
+  sections: SidebarSection[];
+  activeId: string;
+  onSectionChange?: (id: string) => void;
+}
+
+export function SectionSwitcher({
+  sections,
+  activeId,
+  onSectionChange,
+  className,
+  ...props
+}: SectionSwitcherProps) {
+  const active = sections.find((section) => section.id === activeId) ?? sections[0];
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <button
+            type="button"
+            className={cn(
+              "flex w-full items-center justify-between gap-2 rounded-lg border border-border bg-muted px-2.5 py-2 text-left transition-colors hover:bg-[var(--hover)]",
+              className,
+            )}
+            {...props}
+          >
+            <span className="flex min-w-0 items-center gap-2.5">
+              {active?.icon ? (
+                <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-[var(--primary-soft)] text-[var(--primary)]">
+                  {active.icon}
+                </span>
+              ) : null}
+              <span className="flex min-w-0 flex-col">
+                <span className="truncate text-[13.5px] font-semibold text-foreground">
+                  {active?.title}
+                </span>
+                {active?.subtitle ? (
+                  <span className="truncate text-[11px] text-subtle-foreground">
+                    {active.subtitle}
+                  </span>
+                ) : null}
+              </span>
+            </span>
+            <ChevronDown aria-hidden className="h-3.5 w-3.5 shrink-0 text-subtle-foreground" />
+          </button>
+        }
+      />
+      <DropdownMenuContent align="start" className="w-64">
+        {sections.map((section) => (
+          <DropdownMenuItem
+            key={section.id}
+            onClick={() => onSectionChange?.(section.id)}
+            className="items-center gap-2.5 py-1.5"
+          >
+            {section.icon ? (
+              <span className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-[var(--primary-soft)] text-[var(--primary)]">
+                {section.icon}
+              </span>
+            ) : null}
+            <span className="flex min-w-0 flex-col">
+              <span className="truncate font-medium text-foreground">{section.title}</span>
+              {section.subtitle ? (
+                <span className="truncate text-xs text-muted-foreground">{section.subtitle}</span>
+              ) : null}
+            </span>
+            {section.id === activeId ? (
+              <Check aria-hidden className="ml-auto h-4 w-4 shrink-0 text-[var(--primary)]" />
+            ) : null}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+export interface SidebarItemProps {
+  label: string;
+  href?: string;
+  active?: boolean;
+  /** Opens in a new tab and shows a trailing external-link icon. */
+  external?: boolean;
+  /** Renders muted with a "Soon" marker instead of a navigable link. */
+  comingSoon?: boolean;
+  onSelect?: () => void;
+}
+
+export function SidebarItem({ label, href, active, external, comingSoon, onSelect }: SidebarItemProps) {
+  if (comingSoon) {
+    return (
+      <span
+        aria-disabled="true"
+        className="flex items-center justify-between gap-2 rounded-lg px-2.5 py-1.5 text-[13.5px] text-muted-foreground/60"
+      >
+        {label}
+        <Badge variant="neutral" size="sm" className="shrink-0">
+          Soon
+        </Badge>
+      </span>
+    );
+  }
+
+  return (
+    <a
+      href={href}
+      aria-current={active ? "page" : undefined}
+      target={external ? "_blank" : undefined}
+      rel={external ? "noopener noreferrer" : undefined}
+      onClick={onSelect}
+      className={cn(
+        "flex items-center justify-between gap-2 rounded-lg px-2.5 py-1.5 text-[13.5px] transition-colors",
+        active
+          ? "bg-[var(--primary-soft)] font-semibold text-[var(--primary)]"
+          : "text-muted-foreground hover:bg-[var(--hover)] hover:text-foreground",
+      )}
+    >
+      {label}
+      {external ? <ExternalLink aria-hidden className="h-3.5 w-3.5 shrink-0" /> : null}
+    </a>
+  );
+}
+
+export interface SidebarGroupProps extends React.ComponentProps<"div"> {
+  label: string;
+  items: SidebarItemProps[];
+}
+
+export function SidebarGroup({ label, items, className, ...props }: SidebarGroupProps) {
+  return (
+    <div className={cn("flex flex-col gap-0.5", className)} {...props}>
+      <div className="px-2.5 pb-1 font-mono text-[11px] font-semibold tracking-wider text-subtle-foreground uppercase">
+        {label}
+      </div>
+      {items.map((item) => (
+        <SidebarItem key={item.label} {...item} />
+      ))}
+    </div>
+  );
+}
+
+export interface SidebarProps extends Omit<React.ComponentProps<"nav">, "onSelect"> {
+  sections: SidebarSection[];
+  activeSectionId: string;
+  onSectionChange?: (id: string) => void;
+  groups: { label: string; items: SidebarItemProps[] }[];
+}
+
+export function Sidebar({
+  sections,
+  activeSectionId,
+  onSectionChange,
+  groups,
+  className,
+  ...props
+}: SidebarProps) {
+  return (
+    <nav
+      aria-label="Sidebar"
+      className={cn("flex w-[264px] flex-col gap-[22px] border-r border-border bg-background p-3.5", className)}
+      {...props}
+    >
+      <SectionSwitcher sections={sections} activeId={activeSectionId} onSectionChange={onSectionChange} />
+      {groups.map((group) => (
+        <SidebarGroup key={group.label} label={group.label} items={group.items} />
+      ))}
+    </nav>
+  );
+}
diff --git a/packages/ui/src/components/stat-strip.test.tsx b/packages/ui/src/components/stat-strip.test.tsx
new file mode 100644
index 0000000..2b9d07a
--- /dev/null
+++ b/packages/ui/src/components/stat-strip.test.tsx
@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { StatStrip } from "./stat-strip";
+
+const stats = [
+  { value: "24", label: "Node modules" },
+  { value: "94%", label: "Test262 pass rate", emphasis: true },
+  { value: "89%", label: "WinterTC coverage" },
+];
+
+describe("StatStrip", () => {
+  it("renders every stat's value and label", () => {
+    render(<StatStrip stats={stats} />);
+    for (const stat of stats) {
+      expect(screen.getByText(stat.value)).toBeInTheDocument();
+      expect(screen.getByText(stat.label)).toBeInTheDocument();
+    }
+  });
+
+  it("renders one cell per stat", () => {
+    const { container } = render(<StatStrip stats={stats} />);
+    expect(container.querySelectorAll("dd")).toHaveLength(stats.length);
+  });
+
+  it("emphasizes only the flagged stat's value", () => {
+    render(<StatStrip stats={stats} />);
+    expect(screen.getByText("94%")).toHaveClass("text-[var(--primary)]");
+    expect(screen.getByText("24")).not.toHaveClass("text-[var(--primary)]");
+    expect(screen.getByText("89%")).not.toHaveClass("text-[var(--primary)]");
+  });
+
+  it("exposes an accessible label on the region", () => {
+    const { container } = render(<StatStrip stats={stats} />);
+    expect(container.querySelector("dl")).toHaveAttribute("aria-label", "Statistics");
+  });
+
+  it("accepts a custom aria-label", () => {
+    const { container } = render(<StatStrip stats={stats} aria-label="Compatibility metrics" />);
+    expect(container.querySelector("dl")).toHaveAttribute("aria-label", "Compatibility metrics");
+  });
+});
diff --git a/packages/ui/src/components/stat-strip.tsx b/packages/ui/src/components/stat-strip.tsx
new file mode 100644
index 0000000..2217d3d
--- /dev/null
+++ b/packages/ui/src/components/stat-strip.tsx
@@ -0,0 +1,59 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * StatStrip — composite. The bordered row of headline figures at the top of
+ * API landing pages (module count, Test262 pass rate, WinterTC coverage). A
+ * single stat may be `emphasis`-ed to draw the eye to a standout figure.
+ */
+export interface Stat {
+  value: React.ReactNode;
+  label: string;
+  /** Render the value in the primary accent color instead of the default foreground. */
+  emphasis?: boolean;
+}
+
+export interface StatStripProps extends React.ComponentProps<"dl"> {
+  stats: Stat[];
+  /** Number of columns; defaults to one column per stat (a single row). */
+  columns?: number;
+}
+
+export function StatStrip({
+  stats,
+  columns,
+  className,
+  "aria-label": ariaLabel = "Statistics",
+  ...props
+}: StatStripProps) {
+  const cols = columns ?? stats.length;
+  return (
+    <dl
+      aria-label={ariaLabel}
+      className={cn("m-0 grid overflow-hidden rounded-xl border border-border", className)}
+      style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}
+      {...props}
+    >
+      {stats.map((stat, i) => {
+        const lastInRow = (i + 1) % cols === 0;
+        const last = i === stats.length - 1;
+        return (
+          <div
+            key={i}
+            className={cn("flex flex-col gap-1.5 p-5", !lastInRow && !last && "border-r border-border")}
+          >
+            <dd
+              className={cn(
+                "m-0 font-display text-[28px] font-bold leading-none",
+                stat.emphasis ? "text-[var(--primary)]" : "text-foreground",
+              )}
+            >
+              {stat.value}
+            </dd>
+            <dt className="text-xs text-muted-foreground">{stat.label}</dt>
+          </div>
+        );
+      })}
+    </dl>
+  );
+}
diff --git a/packages/ui/src/components/status-badge.test.tsx b/packages/ui/src/components/status-badge.test.tsx
new file mode 100644
index 0000000..e0d590c
--- /dev/null
+++ b/packages/ui/src/components/status-badge.test.tsx
@@ -0,0 +1,30 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { StatusBadge, type ApiStatus } from "./status-badge";
+
+describe("StatusBadge", () => {
+  const cases: [ApiStatus, string][] = [
+    ["implemented", "Implemented"],
+    ["supported", "Supported"],
+    ["partial", "Partial"],
+    ["missing", "Missing"],
+    ["planned", "Planned"],
+  ];
+
+  it.each(cases)("renders the default label and a dot for status=%s", (status, label) => {
+    const { container } = render(<StatusBadge status={status} />);
+    expect(screen.getByText(label)).toBeInTheDocument();
+    expect(container.querySelector("span > span.bg-current")).toBeInTheDocument();
+  });
+
+  it("allows overriding the label via the `label` prop", () => {
+    render(<StatusBadge status="supported" label="31 of 38 methods" />);
+    expect(screen.getByText("31 of 38 methods")).toBeInTheDocument();
+    expect(screen.queryByText("Supported")).not.toBeInTheDocument();
+  });
+
+  it("allows overriding the label via children", () => {
+    render(<StatusBadge status="partial">Custom child label</StatusBadge>);
+    expect(screen.getByText("Custom child label")).toBeInTheDocument();
+  });
+});
diff --git a/packages/ui/src/components/status-badge.tsx b/packages/ui/src/components/status-badge.tsx
new file mode 100644
index 0000000..732582b
--- /dev/null
+++ b/packages/ui/src/components/status-badge.tsx
@@ -0,0 +1,31 @@
+import { Badge, type BadgeProps } from "./badge";
+
+/**
+ * StatusBadge — thin wrapper over `Badge`'s status tones. Maps an API-support
+ * status (as used across the node:-compatibility reference pages) to a badge
+ * variant, dot, and default label.
+ */
+export type ApiStatus = "implemented" | "supported" | "partial" | "missing" | "planned";
+
+const STATUS_CONFIG: Record<ApiStatus, { variant: NonNullable<BadgeProps["variant"]>; label: string }> = {
+  implemented: { variant: "supported", label: "Implemented" },
+  supported: { variant: "supported", label: "Supported" },
+  partial: { variant: "partial", label: "Partial" },
+  missing: { variant: "missing", label: "Missing" },
+  planned: { variant: "missing", label: "Planned" },
+};
+
+export interface StatusBadgeProps extends Omit<BadgeProps, "variant" | "dot"> {
+  status: ApiStatus;
+  /** Override the default per-status label. */
+  label?: string;
+}
+
+export function StatusBadge({ status, label, children, ...props }: StatusBadgeProps) {
+  const { variant, label: defaultLabel } = STATUS_CONFIG[status];
+  return (
+    <Badge dot variant={variant} {...props}>
+      {children ?? label ?? defaultLabel}
+    </Badge>
+  );
+}
diff --git a/packages/ui/src/components/support-matrix.test.tsx b/packages/ui/src/components/support-matrix.test.tsx
new file mode 100644
index 0000000..c6d242b
--- /dev/null
+++ b/packages/ui/src/components/support-matrix.test.tsx
@@ -0,0 +1,65 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { SupportMatrix, type SupportRow } from "./support-matrix";
+
+const rows: SupportRow[] = [
+  { method: "readFile / readFileSync", status: "yes", notes: "All encodings." },
+  { method: "scrypt / pbkdf2", status: "partial", notes: "Async form only; sync pending." },
+  { method: "watch / watchFile", status: "no", notes: "Not yet implemented." },
+];
+
+describe("SupportMatrix", () => {
+  it("renders a table with the provided rows", () => {
+    render(<SupportMatrix rows={rows} />);
+    expect(screen.getByRole("table")).toBeInTheDocument();
+    expect(screen.getAllByRole("row")).toHaveLength(rows.length + 1); // + header row
+  });
+
+  it("renders method and notes text for each row", () => {
+    render(<SupportMatrix rows={rows} />);
+    expect(screen.getByText("readFile / readFileSync")).toBeInTheDocument();
+    expect(screen.getByText("All encodings.")).toBeInTheDocument();
+    expect(screen.getByText("scrypt / pbkdf2")).toBeInTheDocument();
+    expect(screen.getByText("watch / watchFile")).toBeInTheDocument();
+  });
+
+  it("exposes an accessible label per status, never color alone", () => {
+    render(<SupportMatrix rows={rows} />);
+    expect(screen.getByRole("img", { name: "Supported" })).toBeInTheDocument();
+    expect(screen.getByRole("img", { name: "Partial" })).toBeInTheDocument();
+    expect(screen.getByRole("img", { name: "Not supported" })).toBeInTheDocument();
+  });
+
+  it("gives header cells scope=\"col\"", () => {
+    render(<SupportMatrix rows={rows} />);
+    for (const label of ["Method", "Status", "Notes"]) {
+      expect(screen.getByRole("columnheader", { name: label })).toHaveAttribute("scope", "col");
+    }
+  });
+
+  it("supports custom columns", () => {
+    render(
+      <SupportMatrix
+        rows={rows}
+        columns={[
+          { key: "method", label: "API" },
+          { key: "status", label: "Available", align: "center" },
+          { key: "notes", label: "Detail" },
+        ]}
+      />,
+    );
+    expect(screen.getByRole("columnheader", { name: "API" })).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "Available" })).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "Detail" })).toBeInTheDocument();
+  });
+
+  it("sets an accessible caption on the table", () => {
+    render(<SupportMatrix rows={rows} caption="node:fs method support" />);
+    expect(screen.getByRole("table", { name: "node:fs method support" })).toBeInTheDocument();
+  });
+
+  it("merges a consumer className onto the root", () => {
+    const { container } = render(<SupportMatrix rows={rows} className="custom-x" />);
+    expect(container.firstChild).toHaveClass("custom-x");
+  });
+});
diff --git a/packages/ui/src/components/support-matrix.tsx b/packages/ui/src/components/support-matrix.tsx
new file mode 100644
index 0000000..3554637
--- /dev/null
+++ b/packages/ui/src/components/support-matrix.tsx
@@ -0,0 +1,93 @@
+import * as React from "react";
+import { Check, CircleDot, X, type LucideIcon } from "lucide-react";
+import { cn } from "../lib/utils";
+
+/**
+ * SupportMatrix — composite. The bordered reference table used on API pages to
+ * show per-method support ("Method support", node:fs and friends). Status is
+ * conveyed with an icon *and* an accessible label — never color alone.
+ */
+export type SupportStatus = "yes" | "no" | "partial";
+
+export interface SupportRow {
+  method: React.ReactNode;
+  status: SupportStatus;
+  notes?: React.ReactNode;
+}
+
+export interface SupportMatrixColumn {
+  key: string;
+  label: string;
+  align?: "left" | "center";
+}
+
+export interface SupportMatrixProps extends React.ComponentProps<"div"> {
+  columns?: SupportMatrixColumn[];
+  rows: SupportRow[];
+  /** Accessible table name. Visually hidden — the visible heading lives outside the table. */
+  caption?: string;
+}
+
+const DEFAULT_COLUMNS: SupportMatrixColumn[] = [
+  { key: "method", label: "Method" },
+  { key: "status", label: "Status", align: "center" },
+  { key: "notes", label: "Notes" },
+];
+
+const STATUS_META: Record<SupportStatus, { label: string; icon: LucideIcon; color: string }> = {
+  yes: { label: "Supported", icon: Check, color: "var(--eld-success-strong)" },
+  no: { label: "Not supported", icon: X, color: "var(--subtle-foreground)" },
+  partial: { label: "Partial", icon: CircleDot, color: "var(--eld-warning-strong)" },
+};
+
+export function SupportMatrix({
+  columns = DEFAULT_COLUMNS,
+  rows,
+  caption = "Support matrix",
+  className,
+  ...props
+}: SupportMatrixProps) {
+  return (
+    <div className={cn("overflow-hidden rounded-xl border border-border", className)} {...props}>
+      <table className="w-full border-collapse text-sm">
+        <caption className="sr-only">{caption}</caption>
+        <thead className="bg-[var(--muted)]">
+          <tr>
+            {columns.map((column) => (
+              <th
+                key={column.key}
+                scope="col"
+                className={cn(
+                  "px-4 py-2.5 font-mono text-xs font-semibold uppercase tracking-wide text-[var(--subtle-foreground)]",
+                  column.align === "center" ? "text-center" : "text-left",
+                )}
+              >
+                {column.label}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, i) => {
+            const status = STATUS_META[row.status];
+            const StatusIcon = status.icon;
+            return (
+              <tr key={i} className="border-t border-border">
+                <td className="px-4 py-2.5 font-mono text-[var(--primary)]">{row.method}</td>
+                <td className="px-4 py-2.5 text-center">
+                  <StatusIcon
+                    role="img"
+                    aria-label={status.label}
+                    className="inline-block h-4 w-4"
+                    style={{ color: status.color }}
+                  />
+                </td>
+                <td className="px-4 py-2.5 text-muted-foreground">{row.notes}</td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/table-of-contents.test.tsx b/packages/ui/src/components/table-of-contents.test.tsx
new file mode 100644
index 0000000..e0716f0
--- /dev/null
+++ b/packages/ui/src/components/table-of-contents.test.tsx
@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { TableOfContents } from "./table-of-contents";
+
+const items = [
+  { id: "overview", label: "Overview" },
+  { id: "installation", label: "Installation" },
+  { id: "advanced", label: "Advanced usage", depth: 1 },
+];
+
+describe("TableOfContents", () => {
+  it("renders all items", () => {
+    render(<TableOfContents items={items} activeId="overview" />);
+    expect(screen.getByText("Overview")).toBeInTheDocument();
+    expect(screen.getByText("Installation")).toBeInTheDocument();
+    expect(screen.getByText("Advanced usage")).toBeInTheDocument();
+  });
+
+  it("marks the controlled activeId as current with primary styling", () => {
+    render(<TableOfContents items={items} activeId="installation" />);
+    const active = screen.getByRole("link", { name: "Installation" });
+    expect(active).toHaveAttribute("aria-current", "location");
+    expect(active).toHaveClass("text-[var(--primary)]");
+
+    const inactive = screen.getByRole("link", { name: "Overview" });
+    expect(inactive).not.toHaveAttribute("aria-current");
+  });
+
+  it("indents nested items further than top-level ones", () => {
+    render(<TableOfContents items={items} activeId="overview" />);
+    const nested = screen.getByRole("link", { name: "Advanced usage" });
+    const top = screen.getByRole("link", { name: "Overview" });
+    expect(parseFloat(nested.style.paddingLeft)).toBeGreaterThan(
+      parseFloat(top.style.paddingLeft),
+    );
+  });
+
+  it("calls onSelect with the item id when clicked", async () => {
+    const onSelect = vi.fn();
+    const user = userEvent.setup();
+    render(<TableOfContents items={items} activeId="overview" onSelect={onSelect} />);
+    await user.click(screen.getByRole("link", { name: "Installation" }));
+    expect(onSelect).toHaveBeenCalledWith("installation");
+  });
+
+  it("degrades gracefully without IntersectionObserver when uncontrolled", () => {
+    // jsdom has no IntersectionObserver; the component must not throw and
+    // should render with no active item rather than self-managing state.
+    expect(() => render(<TableOfContents items={items} />)).not.toThrow();
+    const links = screen.getAllByRole("link");
+    expect(links.every((link) => !link.hasAttribute("aria-current"))).toBe(true);
+  });
+});
diff --git a/packages/ui/src/components/table-of-contents.tsx b/packages/ui/src/components/table-of-contents.tsx
new file mode 100644
index 0000000..d9908d8
--- /dev/null
+++ b/packages/ui/src/components/table-of-contents.tsx
@@ -0,0 +1,102 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * TableOfContents — the "On this page" right-rail nav that lists in-page
+ * anchor headings. Pass `activeId` to control the highlighted item directly
+ * (e.g. from route state); omit it and the component scroll-spies the
+ * headings itself via `IntersectionObserver`.
+ */
+export interface TocItem {
+  id: string;
+  label: string;
+  /** Nesting level for sub-headings (h3 under h2, etc). Defaults to 0. */
+  depth?: number;
+}
+
+export interface TableOfContentsProps extends Omit<React.ComponentProps<"nav">, "onSelect"> {
+  items: TocItem[];
+  /** Controlled active item id. When omitted, the component scroll-spies. */
+  activeId?: string;
+  /** `mono` renders labels in JetBrains Mono, for API method listings. */
+  variant?: "default" | "mono";
+  title?: string;
+  onSelect?: (id: string) => void;
+}
+
+export function TableOfContents({
+  items,
+  activeId,
+  variant = "default",
+  title = "On this page",
+  onSelect,
+  className,
+  ...props
+}: TableOfContentsProps) {
+  const [visibleIds, setVisibleIds] = React.useState<Set<string>>(() => new Set());
+
+  React.useEffect(() => {
+    // Controlled from outside — don't fight the caller with our own observer.
+    if (activeId !== undefined) return;
+    // jsdom (and older browsers) have no IntersectionObserver; degrade to "no
+    // active item" rather than throwing.
+    if (typeof IntersectionObserver === "undefined") return;
+
+    const targets = items
+      .map((item) => document.getElementById(item.id))
+      .filter((el): el is HTMLElement => el !== null);
+    if (targets.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        setVisibleIds((prev) => {
+          const next = new Set(prev);
+          for (const entry of entries) {
+            if (entry.isIntersecting) next.add(entry.target.id);
+            else next.delete(entry.target.id);
+          }
+          return next;
+        });
+      },
+      { rootMargin: "0px 0px -70% 0px" },
+    );
+    targets.forEach((el) => observer.observe(el));
+    return () => observer.disconnect();
+  }, [items, activeId]);
+
+  const spiedId = items.find((item) => visibleIds.has(item.id))?.id;
+  const currentId = activeId ?? spiedId;
+
+  return (
+    <nav
+      aria-label="Table of contents"
+      className={cn("flex flex-col gap-[11px]", className)}
+      {...props}
+    >
+      <div className="font-mono text-[11px] font-semibold uppercase tracking-wider text-subtle-foreground">
+        {title}
+      </div>
+      {items.map((item) => {
+        const isActive = item.id === currentId;
+        return (
+          <a
+            key={item.id}
+            href={`#${item.id}`}
+            aria-current={isActive ? "location" : undefined}
+            onClick={onSelect ? () => onSelect(item.id) : undefined}
+            style={{ paddingLeft: 11 + (item.depth ?? 0) * 12 }}
+            className={cn(
+              "border-l-2 text-[13px] no-underline transition-colors",
+              variant === "mono" && "font-mono",
+              isActive
+                ? "border-[var(--primary)] font-semibold text-[var(--primary)]"
+                : "border-transparent text-muted-foreground hover:text-foreground",
+            )}
+          >
+            {item.label}
+          </a>
+        );
+      })}
+    </nav>
+  );
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 0d235ce..3235010 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -40,6 +40,33 @@ export {
   SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue,
 } from "./components/select";
 
+// --- Tier-2 docs composites (cycle 2, ported from the Elide Docs mockup) ---
+export { AppNav, type AppNavProps, type NavLink } from "./components/app-nav";
+export {
+  SectionTabs, type SectionTabsProps, type SectionTabItem, type SectionTabsVersion,
+} from "./components/section-tabs";
+export {
+  Sidebar, SectionSwitcher, SidebarGroup, SidebarItem,
+  type SidebarProps, type SectionSwitcherProps, type SidebarGroupProps,
+  type SidebarItemProps, type SidebarSection,
+} from "./components/sidebar";
+export {
+  TableOfContents, type TableOfContentsProps, type TocItem,
+} from "./components/table-of-contents";
+export {
+  MobileNav, type MobileNavProps, type MobileNavItem, type MobileNavGroup, type MobileNavSection,
+} from "./components/mobile-nav";
+export { CardGrid, FeatureCard, type CardGridProps, type FeatureCardProps } from "./components/card-grid";
+export { StatStrip, type Stat, type StatStripProps } from "./components/stat-strip";
+export { AiActions, type AiActionsProps, type AiActionItem } from "./components/ai-actions";
+export { CopyCommand, type CopyCommandProps } from "./components/copy-command";
+export { StatusBadge, type ApiStatus, type StatusBadgeProps } from "./components/status-badge";
+export { ApiMethod, ParamRow, type ApiMethodProps, type ParamRowProps } from "./components/api-method";
+export {
+  SupportMatrix, type SupportMatrixProps, type SupportMatrixColumn,
+  type SupportRow, type SupportStatus,
+} from "./components/support-matrix";
+
 // As components are ported from the mockups they are exported here. Base-UI-backed
 // primitives (Dialog, Popover, DropdownMenu, Combobox/Command, Tooltip, Tabs,
 // Select, Sheet, NavigationMenu, ScrollArea, Accordion) are added via the shadcn
diff --git a/packages/ui/src/stories/AiActions.stories.tsx b/packages/ui/src/stories/AiActions.stories.tsx
new file mode 100644
index 0000000..c352f12
--- /dev/null
+++ b/packages/ui/src/stories/AiActions.stories.tsx
@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { FileText } from "lucide-react";
+import { AiActions } from "../components/ai-actions";
+
+const meta = {
+  title: "Composites/AiActions",
+  component: AiActions,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof AiActions>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const pageMarkdown = `# Elide Overview
+
+A polyglot runtime and toolchain in one native binary — run JS, TS, and
+Python; compile Java and Kotlin; serve apps.
+
+\`\`\`sh
+curl elide.sh | bash
+\`\`\`
+`;
+
+export const Default: Story = {
+  args: {
+    markdown: pageMarkdown,
+    actions: [
+      { label: "Open in Claude", href: "https://claude.ai/new?q=Elide+Overview", external: true },
+      { label: "Open in ChatGPT", href: "https://chatgpt.com/?q=Elide+Overview", external: true },
+      { label: "View as text", icon: <FileText aria-hidden className="h-[13px] w-[13px]" />, href: "#raw" },
+    ],
+  },
+  render: (args) => (
+    <div style={{ maxWidth: 260 }}>
+      <AiActions {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Use with AI")).toBeInTheDocument();
+    await expect(canvas.getByRole("button", { name: /Copy as Markdown/ })).toBeInTheDocument();
+
+    const claude = canvas.getByRole("link", { name: "Open in Claude" });
+    await expect(claude).toHaveAttribute("target", "_blank");
+    await expect(claude.getAttribute("rel")).toContain("noopener");
+  },
+};
+
+export const CopyOnly: Story = {
+  args: { markdown: pageMarkdown },
+  render: (args) => (
+    <div style={{ maxWidth: 260 }}>
+      <AiActions {...args} />
+    </div>
+  ),
+};
diff --git a/packages/ui/src/stories/ApiMethod.stories.tsx b/packages/ui/src/stories/ApiMethod.stories.tsx
new file mode 100644
index 0000000..950f478
--- /dev/null
+++ b/packages/ui/src/stories/ApiMethod.stories.tsx
@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { ApiMethod } from "../components/api-method";
+import { CodeBlock } from "../components/code-block";
+
+const meta = {
+  title: "Composites/ApiMethod",
+  component: ApiMethod,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof ApiMethod>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const readFileExample = `const { readFile } = require("node:fs/promises");
+const text = await readFile("./config.json", "utf8");
+console.log(JSON.parse(text));`;
+
+export const ReadFile: Story = {
+  args: {
+    signature: "fs.readFile(path[, options], callback)",
+    status: "supported",
+    anchorId: "fs-readfile",
+    description: (
+      <>
+        Asynchronously reads the entire contents of a file. The <code>promises</code> variant
+        returns the contents instead of using a callback.
+      </>
+    ),
+    params: [
+      { name: "path", type: "string | Buffer | URL", description: "Filename to read." },
+      {
+        name: "options",
+        type: "Object | string",
+        description: (
+          <>
+            <code>encoding</code> and <code>flag</code> — defaults to a Buffer.
+          </>
+        ),
+      },
+      {
+        name: "callback",
+        type: "Function",
+        description: (
+          <>
+            Called with <code>(err, data)</code>.
+          </>
+        ),
+      },
+    ],
+    example: <CodeBlock filename="example.ts" lang="ts" code={readFileExample} />,
+  },
+  render: (args) => (
+    <div style={{ maxWidth: 720 }}>
+      <ApiMethod {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Supported")).toBeInTheDocument();
+    await expect(canvas.getByText("path")).toBeInTheDocument();
+    await expect(canvas.getByRole("link", { name: /Link to/ })).toHaveAttribute("href", "#fs-readfile");
+  },
+};
diff --git a/packages/ui/src/stories/AppNav.stories.tsx b/packages/ui/src/stories/AppNav.stories.tsx
new file mode 100644
index 0000000..2d0e3c4
--- /dev/null
+++ b/packages/ui/src/stories/AppNav.stories.tsx
@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import { AppNav } from "../components/app-nav";
+
+const meta = {
+  title: "Composites/AppNav",
+  component: AppNav,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof AppNav>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const links = [
+  { label: "Docs", href: "#docs", active: true },
+  { label: "Enterprise", href: "#enterprise" },
+  { label: "Blog", href: "#blog" },
+  { label: "Pricing", href: "#pricing" },
+];
+
+export const Default: Story = {
+  args: {
+    links,
+    onSearchClick: fn(),
+    onThemeToggle: fn(),
+    onLocaleClick: fn(),
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByRole("link", { name: "Docs" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByRole("link", { name: "Enterprise" })).not.toHaveAttribute(
+      "aria-current",
+    );
+
+    await userEvent.click(canvas.getByRole("button", { name: "Search" }));
+    await expect(args.onSearchClick).toHaveBeenCalledTimes(1);
+  },
+};
+
+export const CustomLocale: Story = {
+  args: {
+    links,
+    locale: "FR",
+    searchPlaceholder: "Rechercher ou demander à l'IA…",
+  },
+};
diff --git a/packages/ui/src/stories/CardGrid.stories.tsx b/packages/ui/src/stories/CardGrid.stories.tsx
new file mode 100644
index 0000000..d4a8d69
--- /dev/null
+++ b/packages/ui/src/stories/CardGrid.stories.tsx
@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { BookOpen, Boxes, Database, Globe, Layers, Server } from "lucide-react";
+import { CardGrid, FeatureCard } from "../components/card-grid";
+import { Badge } from "../components/badge";
+
+const meta = {
+  title: "Composites/CardGrid",
+  component: CardGrid,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof CardGrid>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The "Browse by category" grid from the API Reference landing page. */
+export const ApiCategories: Story = {
+  render: () => (
+    <CardGrid columns={3}>
+      <FeatureCard
+        href="#api-overview"
+        icon={<BookOpen />}
+        title="API Overview"
+        description="How guest code sees the runtime, globals, and modules."
+      />
+      <FeatureCard
+        href="#node-compatibility"
+        icon={<Boxes />}
+        title="Node Compatibility"
+        description="assert, buffer, crypto, fs, stream, test, and more."
+        badge={
+          <Badge variant="primary" size="sm">
+            24
+          </Badge>
+        }
+      />
+      <FeatureCard
+        href="#web-standards"
+        icon={<Globe />}
+        title="Web Standards"
+        description="Fetch, Streams, URL, Encoding, Web Crypto, DOM events."
+      />
+      <FeatureCard
+        href="#wintercg"
+        icon={<Layers />}
+        title="WinterCG"
+        description="DOMException, Messaging, Navigator, Performance."
+      />
+      <FeatureCard
+        href="#host-apis"
+        icon={<Server />}
+        title="Host APIs"
+        description="elide:crypto, host filesystem, process, network transport."
+      />
+      <FeatureCard
+        href="https://github.com/elide-dev/elide"
+        icon={<Database />}
+        title="Database Modules"
+        description="Embedded elide:sqlite and friends — no bindings to install."
+        external
+      />
+    </CardGrid>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const nodeCompat = canvas.getByRole("link", { name: /Node Compatibility/ });
+    await expect(nodeCompat).toBeInTheDocument();
+    await expect(canvas.getByText("24")).toBeInTheDocument();
+
+    const database = canvas.getByRole("link", { name: /Database Modules/ });
+    await expect(database).toHaveAttribute("target", "_blank");
+    await expect(database.getAttribute("rel")).toContain("noopener");
+  },
+};
+
+/** The mobile "Start here" list — one column, no icon chip badges. */
+export const StartHere: Story = {
+  render: () => (
+    <CardGrid columns={1} style={{ maxWidth: 360 }}>
+      <FeatureCard
+        href="#install"
+        icon={<BookOpen />}
+        title="Install Elide"
+        description="Five ways to install"
+      />
+      <FeatureCard
+        href="#run-code"
+        icon={<Boxes />}
+        title="Run Code"
+        description="JS, TS, and Python"
+      />
+    </CardGrid>
+  ),
+};
diff --git a/packages/ui/src/stories/CopyCommand.stories.tsx b/packages/ui/src/stories/CopyCommand.stories.tsx
new file mode 100644
index 0000000..2bec609
--- /dev/null
+++ b/packages/ui/src/stories/CopyCommand.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { CopyCommand } from "../components/copy-command";
+
+const meta = {
+  title: "Composites/CopyCommand",
+  component: CopyCommand,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof CopyCommand>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const InstallOneLiner: Story = {
+  args: {
+    command: "curl elide.sh | bash",
+  },
+  render: (args) => (
+    <div style={{ maxWidth: 420 }}>
+      <CopyCommand {...args} />
+    </div>
+  ),
+};
+
+// Labeled variant makes the copied/uncopied state visible as text, so the
+// interaction test below can assert on it directly.
+export const WithLabel: Story = {
+  args: {
+    command: "curl elide.sh | bash",
+    label: "Copy",
+  },
+  render: (args) => (
+    <div style={{ maxWidth: 420 }}>
+      <CopyCommand {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole("button", { name: "Copy" });
+
+    await userEvent.click(button);
+
+    await waitFor(() => expect(canvas.getByRole("button", { name: "Copied" })).toBeInTheDocument());
+  },
+};
diff --git a/packages/ui/src/stories/MobileNav.stories.tsx b/packages/ui/src/stories/MobileNav.stories.tsx
new file mode 100644
index 0000000..3ac8d22
--- /dev/null
+++ b/packages/ui/src/stories/MobileNav.stories.tsx
@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, screen, userEvent, within } from "storybook/test";
+import { Compass } from "lucide-react";
+import { MobileNav } from "../components/mobile-nav";
+
+const meta = {
+  title: "Composites/MobileNav",
+  component: MobileNav,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MobileNav>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const groups = [
+  {
+    label: "Introduction",
+    items: [
+      { label: "Overview", href: "#overview", active: true },
+      { label: "Install Elide", href: "#install" },
+      { label: "Run your first script", href: "#first-script" },
+    ],
+  },
+  {
+    label: "By language",
+    items: [
+      { label: "Java & Kotlin", href: "#jvm" },
+      { label: "Python", href: "#python" },
+      { label: "JavaScript & TypeScript", href: "#js" },
+    ],
+  },
+];
+
+export const Default: Story = {
+  args: {
+    groups,
+    section: {
+      title: "Start",
+      subtitle: "Get running in minutes",
+      icon: <Compass aria-hidden className="h-4 w-4" />,
+    },
+    logo: <span className="text-sm font-semibold text-foreground">Elide</span>,
+    changelogHref: "#changelog",
+    onSearch: fn(),
+  },
+  render: (args) => (
+    <div className="h-[640px]">
+      <MobileNav {...args} className="h-full" />
+    </div>
+  ),
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Bottom "Search or ask AI" bar fires onSearch.
+    await userEvent.click(canvas.getByRole("button", { name: /search or ask ai/i }));
+    await expect(args.onSearch).toHaveBeenCalledTimes(1);
+
+    // Sheet portals the drawer to document.body, so query there once open.
+    await userEvent.click(canvas.getByRole("button", { name: "Open navigation" }));
+    const body = within(document.body);
+    await expect(body.getByRole("link", { name: "Overview" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(body.getByRole("link", { name: "Java & Kotlin" })).toBeInTheDocument();
+    await expect(screen.getByRole("navigation", { name: "Mobile navigation" })).toBeInTheDocument();
+  },
+};
diff --git a/packages/ui/src/stories/SectionTabs.stories.tsx b/packages/ui/src/stories/SectionTabs.stories.tsx
new file mode 100644
index 0000000..9238350
--- /dev/null
+++ b/packages/ui/src/stories/SectionTabs.stories.tsx
@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import { SectionTabs } from "../components/section-tabs";
+
+const meta = {
+  title: "Composites/SectionTabs",
+  component: SectionTabs,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof SectionTabs>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Runtime: Story = {
+  args: {
+    items: [
+      { label: "Start", href: "#start" },
+      { label: "Runtime", href: "#runtime", active: true },
+      { label: "Toolchain", href: "#toolchain" },
+      { label: "API Reference", href: "#api" },
+      { label: "Resources", href: "#resources" },
+    ],
+    version: { label: "v1.0.0-beta5", status: "ok" },
+    onSelect: fn(),
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByRole("link", { name: "Runtime" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByRole("link", { name: "Start" })).not.toHaveAttribute(
+      "aria-current",
+    );
+
+    await userEvent.click(canvas.getByRole("link", { name: "Toolchain" }));
+    await expect(args.onSelect).toHaveBeenCalledWith("#toolchain");
+  },
+};
+
+export const ApiReference: Story = {
+  args: {
+    items: [
+      { label: "Start", href: "#start" },
+      { label: "Runtime", href: "#runtime" },
+      { label: "Toolchain", href: "#toolchain" },
+      { label: "API Reference", href: "#api", active: true },
+      { label: "Resources", href: "#resources" },
+    ],
+    version: { label: "v1.0.0-beta5", status: "ok" },
+  },
+};
diff --git a/packages/ui/src/stories/Sidebar.stories.tsx b/packages/ui/src/stories/Sidebar.stories.tsx
new file mode 100644
index 0000000..a1d88c5
--- /dev/null
+++ b/packages/ui/src/stories/Sidebar.stories.tsx
@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { BookOpen, Code2, Rocket, SquareTerminal, Wrench } from "lucide-react";
+import { Sidebar, type SidebarSection } from "../components/sidebar";
+
+const sections: SidebarSection[] = [
+  { id: "start", title: "Start", subtitle: "Get running in minutes", icon: <Rocket className="h-4 w-4" /> },
+  {
+    id: "runtime",
+    title: "Runtime",
+    subtitle: "Run, serve, debug, and inspect",
+    icon: <SquareTerminal className="h-4 w-4" />,
+  },
+  { id: "toolchain", title: "Toolchain", subtitle: "Build, test, and package", icon: <Wrench className="h-4 w-4" /> },
+  { id: "api", title: "API Reference", subtitle: "node:fs, node:http, and more", icon: <Code2 className="h-4 w-4" /> },
+  { id: "resources", title: "Resources", subtitle: "Guides, FAQs, and support", icon: <BookOpen className="h-4 w-4" /> },
+];
+
+const groups = [
+  {
+    label: "Getting started",
+    items: [
+      { label: "Getting Started", href: "#getting-started" },
+      { label: "CLI Reference", href: "#cli-reference" },
+    ],
+  },
+  {
+    label: "Guides",
+    items: [
+      { label: "Debugging", href: "#debugging", active: true },
+      { label: "Connect an IDE", href: "#connect-ide" },
+      { label: "Development Server", href: "#dev-server" },
+      { label: "MCP Server", href: "#mcp-server" },
+      { label: "REPL", href: "#repl" },
+      { label: "Filesystem Sandbox", href: "#fs-sandbox" },
+      { label: "Polyglot Interop", href: "#polyglot-interop" },
+      { label: "elide.dev", href: "https://elide.dev", external: true },
+      { label: "Remote Debugging", comingSoon: true },
+    ],
+  },
+];
+
+const meta = {
+  title: "Composites/Sidebar",
+  component: Sidebar,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof Sidebar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Runtime: Story = {
+  args: {
+    sections,
+    activeSectionId: "runtime",
+    groups,
+  },
+};
+
+export const SwitchSection: Story = {
+  args: {
+    sections,
+    activeSectionId: "runtime",
+    groups,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const trigger = canvas.getByRole("button", { name: /Runtime/ });
+    await userEvent.click(trigger);
+
+    // The menu popup portals to document.body, not the story canvas.
+    const body = within(document.body);
+    await waitFor(() => expect(body.getByRole("menuitem", { name: /^Start/ })).toBeInTheDocument());
+    await expect(body.getByRole("menuitem", { name: /Toolchain/ })).toBeInTheDocument();
+    await expect(body.getByRole("menuitem", { name: /API Reference/ })).toBeInTheDocument();
+    await expect(body.getByRole("menuitem", { name: /Resources/ })).toBeInTheDocument();
+  },
+};
diff --git a/packages/ui/src/stories/StatStrip.stories.tsx b/packages/ui/src/stories/StatStrip.stories.tsx
new file mode 100644
index 0000000..0b63740
--- /dev/null
+++ b/packages/ui/src/stories/StatStrip.stories.tsx
@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { StatStrip } from "../components/stat-strip";
+
+const meta = {
+  title: "Composites/StatStrip",
+  component: StatStrip,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof StatStrip>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ApiCompatibility: Story = {
+  args: {
+    stats: [
+      { value: "24", label: "Node modules" },
+      { value: "94%", label: "Test262 pass rate", emphasis: true },
+      { value: "89%", label: "WinterTC coverage" },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("24")).toBeInTheDocument();
+    await expect(canvas.getByText("Node modules")).toBeInTheDocument();
+    const testPassRate = canvas.getByText("94%");
+    await expect(testPassRate).toBeInTheDocument();
+    await expect(testPassRate).toHaveClass("text-[var(--primary)]");
+  },
+};
+
+export const FourColumns: Story = {
+  args: {
+    stats: [
+      { value: "6", label: "API surfaces" },
+      { value: "312", label: "Test suites" },
+      { value: "1.2M", label: "Downloads/mo" },
+      { value: "0", label: "Native bindings" },
+    ],
+  },
+};
diff --git a/packages/ui/src/stories/StatusBadge.stories.tsx b/packages/ui/src/stories/StatusBadge.stories.tsx
new file mode 100644
index 0000000..3b76b89
--- /dev/null
+++ b/packages/ui/src/stories/StatusBadge.stories.tsx
@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { StatusBadge, type ApiStatus } from "../components/status-badge";
+
+const meta = {
+  title: "Composites/StatusBadge",
+  component: StatusBadge,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof StatusBadge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const STATUSES: ApiStatus[] = ["implemented", "supported", "partial", "missing", "planned"];
+
+export const AllStatuses: Story = {
+  // `status` is required by the component; this story renders the full set itself,
+  // so the arg is a placeholder the custom render ignores.
+  args: { status: "supported" },
+  render: () => (
+    <div style={{ display: "flex", gap: 12, alignItems: "center", flexWrap: "wrap" }}>
+      {STATUSES.map((status) => (
+        <StatusBadge key={status} status={status} />
+      ))}
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Implemented")).toBeInTheDocument();
+    await expect(canvas.getByText("Supported")).toBeInTheDocument();
+    await expect(canvas.getByText("Partial")).toBeInTheDocument();
+    await expect(canvas.getByText("Missing")).toBeInTheDocument();
+    await expect(canvas.getByText("Planned")).toBeInTheDocument();
+  },
+};
+
+export const CustomLabel: Story = {
+  args: { status: "supported", label: "31 of 38 methods" },
+};
diff --git a/packages/ui/src/stories/SupportMatrix.stories.tsx b/packages/ui/src/stories/SupportMatrix.stories.tsx
new file mode 100644
index 0000000..744ff7a
--- /dev/null
+++ b/packages/ui/src/stories/SupportMatrix.stories.tsx
@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { SupportMatrix } from "../components/support-matrix";
+
+const meta = {
+  title: "Composites/SupportMatrix",
+  component: SupportMatrix,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof SupportMatrix>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const NodeFs: Story = {
+  args: {
+    caption: "node:fs method support",
+    rows: [
+      { method: "readFile / readFileSync", status: "yes", notes: "All encodings." },
+      { method: "writeFile / writeFileSync", status: "yes", notes: "Atomic replace supported." },
+      { method: "readdir / stat", status: "yes", notes: "withFileTypes supported." },
+      {
+        method: "watch / watchFile",
+        status: "no",
+        notes: "Not yet implemented — tracking in v1.1.",
+      },
+    ],
+  },
+};
+
+export const WithPartialSupport: Story = {
+  args: {
+    caption: "node:crypto method support",
+    rows: [
+      { method: "createHash / createHmac", status: "yes", notes: "SHA-1/256/384/512, MD5." },
+      { method: "randomBytes / randomUUID", status: "yes", notes: "Backed by the host CSPRNG." },
+      { method: "scrypt / pbkdf2", status: "partial", notes: "Async form only; sync pending." },
+      { method: "createSign / createVerify", status: "no", notes: "Not yet implemented." },
+    ],
+  },
+};
diff --git a/packages/ui/src/stories/TableOfContents.stories.tsx b/packages/ui/src/stories/TableOfContents.stories.tsx
new file mode 100644
index 0000000..1eacfcf
--- /dev/null
+++ b/packages/ui/src/stories/TableOfContents.stories.tsx
@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { TableOfContents } from "../components/table-of-contents";
+
+const meta = {
+  title: "Composites/TableOfContents",
+  component: TableOfContents,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof TableOfContents>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const items = [
+  { id: "overview", label: "Overview" },
+  { id: "installation", label: "Installation" },
+  { id: "quickstart", label: "Quickstart" },
+  { id: "configuration", label: "Configuration" },
+  { id: "faq", label: "FAQ" },
+];
+
+export const Default: Story = {
+  args: {
+    items,
+    // Controlled here so the story renders deterministically without a real
+    // scrollable page for IntersectionObserver to spy on.
+    activeId: "installation",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const active = canvas.getByRole("link", { name: "Installation" });
+    await expect(active.getAttribute("aria-current")).toBe("location");
+    const inactive = canvas.getByRole("link", { name: "Overview" });
+    await expect(inactive.getAttribute("aria-current")).toBe(null);
+  },
+};
+
+const methodItems = [
+  { id: "readfile", label: "readFile()" },
+  { id: "writefile", label: "writeFile()" },
+  { id: "mkdir", label: "mkdir()" },
+  { id: "rmdir", label: "rmdir()", depth: 1 },
+];
+
+export const Mono: Story = {
+  args: {
+    items: methodItems,
+    activeId: "writefile",
+    variant: "mono",
+    title: "Methods",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const active = canvas.getByRole("link", { name: "writeFile()" });
+    await expect(active.getAttribute("aria-current")).toBe("location");
+  },
+};

From a9c2c7dc096177191bd074435f6dfb5589a48869 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 12:24:54 -0700
Subject: [PATCH 04/10] ci: Codecov coverage reporting for both test suites

- codecov.yml: ui-unit (jsdom) and ui-browser (Storybook) flags, both
  carryforward, informational status while coverage fills in.
- apps/storybook/vitest.config.ts: v8 coverage output (allowExternal, since
  the instrumented sources live in packages/ui/src, outside this app root).
- check.test.yml: run both suites with `turbo run test -- --coverage`, then
  upload each lcov under its flag via codecov/codecov-action (SHA-pinned v7.0.0),
  fail_ci_if_error:false, token from secrets.CODECOV_TOKEN.
- README: Codecov badge.

Requires the CODECOV_TOKEN repo secret to be added.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/check.test.yml | 23 +++++++++++++---
 README.md                        |  2 ++
 apps/storybook/package.json      |  3 ++-
 apps/storybook/vitest.config.ts  | 16 +++++++++++
 codecov.yml                      | 46 ++++++++++++++++++++++++++++++++
 5 files changed, 86 insertions(+), 4 deletions(-)
 create mode 100644 codecov.yml

diff --git a/.github/workflows/check.test.yml b/.github/workflows/check.test.yml
index 06d2efc..50361ff 100644
--- a/.github/workflows/check.test.yml
+++ b/.github/workflows/check.test.yml
@@ -9,7 +9,7 @@ permissions:
 
 jobs:
   test:
-    name: "Vitest (stories)"
+    name: "Vitest (unit + stories)"
     runs-on: ${{ vars.RUNNER_DEFAULT || 'ubuntu-latest' }}
     permissions:
       contents: read
@@ -38,5 +38,22 @@ jobs:
         run: bun install --frozen-lockfile
       - name: "Setup: Playwright Chromium"
         run: bunx playwright install --with-deps chromium
-      - name: "Test: Stories via Vitest (browser mode)"
-        run: bun run test
+      - name: "Test: Vitest (jsdom unit + Storybook browser mode) with coverage"
+        # `-- --coverage` forwards through Turbo's passthrough args to every
+        # workspace's `test` script (`vitest run`), so both suites emit their
+        # own coverage/lcov.info without a dedicated turbo task.
+        run: bunx turbo run test -- --coverage
+      - name: "Coverage: Upload ui-unit (jsdom) to Codecov"
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          files: packages/ui/coverage/lcov.info
+          flags: ui-unit
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+      - name: "Coverage: Upload ui-browser (Storybook) to Codecov"
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          files: apps/storybook/coverage/lcov.info
+          flags: ui-browser
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
diff --git a/README.md b/README.md
index 132e449..148ba28 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # components
 
+[![codecov](https://codecov.io/gh/elide-dev/components/graph/badge.svg)](https://codecov.io/gh/elide-dev/components)
+
 Elide's shared UI. One repository, consumed by many: the docs site (Astro) and
 the marketing site both depend on it, so brand, tokens, and behavior stay in one
 place and move together.
diff --git a/apps/storybook/package.json b/apps/storybook/package.json
index c44d9ea..e8a0e26 100644
--- a/apps/storybook/package.json
+++ b/apps/storybook/package.json
@@ -8,7 +8,8 @@
     "build": "storybook build",
     "build-storybook": "storybook build",
     "chromatic": "chromatic --exit-zero-on-changes",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@elide/tokens": "workspace:*",
diff --git a/apps/storybook/vitest.config.ts b/apps/storybook/vitest.config.ts
index 92e2ba0..d826835 100644
--- a/apps/storybook/vitest.config.ts
+++ b/apps/storybook/vitest.config.ts
@@ -6,6 +6,14 @@ import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
 // assertions live in each story's `play` function. Storybook's plugin reuses
 // the .storybook config (framework, Tailwind viteFinal, decorators), and since
 // Storybook 10.3 the addon applies the preview annotations automatically.
+//
+// Coverage is v8, same as the jsdom suite in packages/ui/vitest.config.ts.
+// Stories live in packages/ui/src, outside this app's root, so `allowExternal`
+// must be on or v8 drops those files before include/exclude ever runs. Once
+// external files are allowed, matching is substring-based (picomatch
+// `contains: true`), so the same `src/components/**` glob used in
+// packages/ui/vitest.config.ts matches here too. Codecov merges this suite's
+// `ui-browser` flag with `ui-unit`.
 export default defineConfig({
   plugins: [storybookTest({ configDir: ".storybook" })],
   test: {
@@ -16,5 +24,13 @@ export default defineConfig({
       headless: true,
       instances: [{ browser: "chromium" }],
     },
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "lcov"],
+      reportsDirectory: "./coverage",
+      allowExternal: true,
+      include: ["src/components/**"],
+      exclude: ["src/**/*.test.{ts,tsx}", "src/**/*.stories.tsx"],
+    },
   },
 });
diff --git a/codecov.yml b/codecov.yml
new file mode 100644
index 0000000..cb495fc
--- /dev/null
+++ b/codecov.yml
@@ -0,0 +1,46 @@
+# Two suites report coverage for the same components under two flags:
+#   ui-unit    — jsdom unit suite (packages/ui/vitest.config.ts)
+#   ui-browser — Storybook browser-mode suite (apps/storybook/vitest.config.ts)
+# Both exercise packages/ui/src/components; Codecov merges them into one view.
+# Status checks are informational only while the suites are still filling in —
+# flip to blocking once coverage on `main` is representative.
+codecov:
+  require_ci_to_pass: false
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true
+
+flags:
+  ui-unit:
+    paths:
+      - packages/ui/src/components/
+    carryforward: true
+  ui-browser:
+    paths:
+      - packages/ui/src/components/
+    carryforward: true
+
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  require_changes: false
+
+ignore:
+  - "**/*.stories.tsx"
+  - "**/stories/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/dist/**"
+  - "**/.storybook/**"
+  - "**/*.config.ts"
+  - "**/*.config.js"
+  - "**/*.config.mjs"

From 9cdd6cc9bc370e4b9a84aa3cca63aaf0af495da3 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 13:10:45 -0700
Subject: [PATCH 05/10] fix(ui): real syntax highlighting, Elide logo, and
 self-hosted fonts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CodeBlock now syntax-highlights `code` via prism-react-renderer with a
  Prism theme mapped onto the --eld-syntax-* tokens (TS, Bash, JSON, etc.),
  instead of rendering raw monochrome text. `children` still overrides for
  pre-highlighted markup. Composite code blocks (ApiMethod, CopyCommand) are
  now colored.
- Add ElideLogo/ElideMark/ElideWordmark — the real brand marks inlined as SVG
  (no external asset request, so they render in SSR/Storybook/Chromatic). Used
  as AppNav's default logo in place of the placeholder glyph.
- Self-host fonts via @fontsource (Inter/Instrument Sans/JetBrains Mono)
  instead of a remote Google Fonts @import, which Chromatic's capture env
  blocks — snapshots were falling back to system fonts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 bun.lock                                      | 16 ++++
 packages/tokens/package.json                  |  5 ++
 packages/tokens/src/fonts.css                 | 27 +++++-
 packages/ui/package.json                      |  1 +
 packages/ui/src/components/app-nav.tsx        | 13 +--
 packages/ui/src/components/code-block.tsx     | 85 +++++++++++++++++--
 packages/ui/src/components/elide-logo.tsx     | 70 +++++++++++++++
 packages/ui/src/index.ts                      |  1 +
 packages/ui/src/stories/CodeBlock.stories.tsx | 41 +++------
 9 files changed, 210 insertions(+), 49 deletions(-)
 create mode 100644 packages/ui/src/components/elide-logo.tsx

diff --git a/bun.lock b/bun.lock
index 246d16a..d779499 100644
--- a/bun.lock
+++ b/bun.lock
@@ -47,6 +47,11 @@
     "packages/tokens": {
       "name": "@elide/tokens",
       "version": "0.1.0",
+      "dependencies": {
+        "@fontsource/instrument-sans": "^5.2.8",
+        "@fontsource/inter": "^5.2.8",
+        "@fontsource/jetbrains-mono": "^5.2.8",
+      },
     },
     "packages/ui": {
       "name": "@elide/ui",
@@ -57,6 +62,7 @@
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "lucide-react": "^1.23.0",
+        "prism-react-renderer": "^2.4.1",
         "tailwind-merge": "^3.6.0",
         "tw-animate-css": "^1.4.0",
       },
@@ -268,6 +274,12 @@
 
     "@floating-ui/utils": ["@floating-ui/utils@0.2.11", "", {}, "sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg=="],
 
+    "@fontsource/instrument-sans": ["@fontsource/instrument-sans@5.2.8", "", {}, "sha512-TJRYVbjZPx4DGMMU5lb5eFKrP3iLe9h7rz8Pk+dP958IZKiyHjYGXXwQZapVbBXcQN+YOiviVhAWxrjv8g6Z6g=="],
+
+    "@fontsource/inter": ["@fontsource/inter@5.2.8", "", {}, "sha512-P6r5WnJoKiNVV+zvW2xM13gNdFhAEpQ9dQJHt3naLvfg+LkF2ldgSLiF4T41lf1SQCM9QmkqPTn4TH568IRagg=="],
+
+    "@fontsource/jetbrains-mono": ["@fontsource/jetbrains-mono@5.2.8", "", {}, "sha512-6w8/SG4kqvIMu7xd7wt6x3idn1Qux3p9N62s6G3rfldOUYHpWcc2FKrqf+Vo44jRvqWj2oAtTHrZXEP23oSKwQ=="],
+
     "@humanfs/core": ["@humanfs/core@0.19.2", "", { "dependencies": { "@humanfs/types": "^0.15.0" } }, "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA=="],
 
     "@humanfs/node": ["@humanfs/node@0.16.8", "", { "dependencies": { "@humanfs/core": "^0.19.2", "@humanfs/types": "^0.15.0", "@humanwhocodes/retry": "^0.4.0" } }, "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ=="],
@@ -578,6 +590,8 @@
 
     "@types/node": ["@types/node@12.20.55", "", {}, "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ=="],
 
+    "@types/prismjs": ["@types/prismjs@1.26.6", "", {}, "sha512-vqlvI7qlMvcCBbVe0AKAb4f97//Hy0EBTaiW8AalRnG/xAN5zOiWWyrNqNXeq8+KAuvRewjCVY1+IPxk4RdNYw=="],
+
     "@types/react": ["@types/react@19.2.17", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw=="],
 
     "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
@@ -1052,6 +1066,8 @@
 
     "pretty-format": ["pretty-format@27.5.1", "", { "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", "react-is": "^17.0.1" } }, "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ=="],
 
+    "prism-react-renderer": ["prism-react-renderer@2.4.1", "", { "dependencies": { "@types/prismjs": "^1.26.0", "clsx": "^2.0.0" }, "peerDependencies": { "react": ">=16.0.0" } }, "sha512-ey8Ls/+Di31eqzUxC46h8MksNuGx/n0AAC8uKpwFau4RPDYLuE3EXTp8N8G2vX2N7UC/+IXeNUnlWBGGcAG+Ig=="],
+
     "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
 
     "quansync": ["quansync@0.2.11", "", {}, "sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA=="],
diff --git a/packages/tokens/package.json b/packages/tokens/package.json
index 57fb5f5..d77daa9 100644
--- a/packages/tokens/package.json
+++ b/packages/tokens/package.json
@@ -23,5 +23,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch"
+  },
+  "dependencies": {
+    "@fontsource/instrument-sans": "^5.2.8",
+    "@fontsource/inter": "^5.2.8",
+    "@fontsource/jetbrains-mono": "^5.2.8"
   }
 }
diff --git a/packages/tokens/src/fonts.css b/packages/tokens/src/fonts.css
index 8097604..eabb892 100644
--- a/packages/tokens/src/fonts.css
+++ b/packages/tokens/src/fonts.css
@@ -1,4 +1,23 @@
-/* Elide web fonts. Swap these <link>-style @imports for self-hosted woff2 in
- * production (the docs repo self-hosts JetBrains Mono already). Kept here so a
- * consumer gets a reasonable rendering with a single import. */
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Instrument+Sans:wght@500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap");
+/* Elide web fonts — self-hosted via @fontsource (woff2 bundled in node_modules).
+ * Self-hosting (rather than a remote Google Fonts @import) keeps rendering
+ * deterministic offline and in capture environments like Chromatic, where an
+ * external font request is blocked and would otherwise fall back to system
+ * fonts. Bundlers (Vite/Tailwind) resolve these bare specifiers and inline the
+ * woff2. Only the weights the design system actually uses are pulled in. */
+
+/* Inter — body / UI (--eld-font-sans) */
+@import "@fontsource/inter/400.css";
+@import "@fontsource/inter/500.css";
+@import "@fontsource/inter/600.css";
+@import "@fontsource/inter/700.css";
+
+/* Instrument Sans — display / headings (--eld-font-display) */
+@import "@fontsource/instrument-sans/400.css";
+@import "@fontsource/instrument-sans/500.css";
+@import "@fontsource/instrument-sans/600.css";
+@import "@fontsource/instrument-sans/700.css";
+
+/* JetBrains Mono — code / mono (--eld-font-mono) */
+@import "@fontsource/jetbrains-mono/400.css";
+@import "@fontsource/jetbrains-mono/500.css";
+@import "@fontsource/jetbrains-mono/700.css";
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 3c4050f..97fc520 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -35,6 +35,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.23.0",
+    "prism-react-renderer": "^2.4.1",
     "tailwind-merge": "^3.6.0",
     "tw-animate-css": "^1.4.0"
   },
diff --git a/packages/ui/src/components/app-nav.tsx b/packages/ui/src/components/app-nav.tsx
index 89ed08e..f9c8f47 100644
--- a/packages/ui/src/components/app-nav.tsx
+++ b/packages/ui/src/components/app-nav.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 import { ChevronDown, Globe, History, Search, Sparkles, Sun } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Button } from "./button";
+import { ElideLogo } from "./elide-logo";
 
 /**
  * AppNav — the 56px top nav bar present on every docs page: brand + "DOCS"
@@ -30,17 +31,7 @@ export interface AppNavProps extends React.ComponentProps<"nav"> {
   onLocaleClick?: () => void;
 }
 
-const defaultLogo = (
-  <span className="flex items-center gap-1.5">
-    <span
-      aria-hidden
-      className="flex h-5 w-5 items-center justify-center rounded-md text-[11px] font-bold text-white [background:var(--eld-gradient-brand)]"
-    >
-      e
-    </span>
-    <span className="font-display text-sm font-semibold text-foreground">Elide</span>
-  </span>
-);
+const defaultLogo = <ElideLogo />;
 
 export function AppNav({
   links,
diff --git a/packages/ui/src/components/code-block.tsx b/packages/ui/src/components/code-block.tsx
index 76fd492..bb0e047 100644
--- a/packages/ui/src/components/code-block.tsx
+++ b/packages/ui/src/components/code-block.tsx
@@ -1,5 +1,6 @@
 import * as React from "react";
 import { Check, Copy } from "lucide-react";
+import { Highlight, type PrismTheme } from "prism-react-renderer";
 import { cn } from "../lib/utils";
 
 /**
@@ -40,6 +41,77 @@ export function CopyButton({
   );
 }
 
+/**
+ * Prism theme mapped entirely onto the Elide `--eld-syntax-*` tokens, so the
+ * highlighter tracks the design system (and both light/dark, since the tokens
+ * are `var()` references). Colors are applied as inline styles by the renderer.
+ */
+const eldPrismTheme: PrismTheme = {
+  plain: { color: "var(--eld-syntax-default)", backgroundColor: "transparent" },
+  styles: [
+    { types: ["comment", "prolog", "doctype", "cdata"], style: { color: "var(--eld-syntax-comment)", fontStyle: "italic" } },
+    { types: ["keyword", "control-flow", "at-rule", "rule", "important", "tag", "selector"], style: { color: "var(--eld-syntax-keyword)" } },
+    { types: ["string", "char", "attr-value", "template-string", "url", "regex"], style: { color: "var(--eld-syntax-string)" } },
+    { types: ["number", "boolean", "constant", "symbol", "inserted", "unit"], style: { color: "var(--eld-syntax-number)" } },
+    { types: ["function", "function-variable", "method", "deleted"], style: { color: "var(--eld-syntax-function)" } },
+    { types: ["class-name", "maybe-class-name", "builtin", "namespace", "type-annotation"], style: { color: "var(--eld-syntax-type)" } },
+    { types: ["parameter", "property", "property-access", "variable", "attr-name", "entity"], style: { color: "var(--eld-syntax-param)" } },
+    { types: ["operator", "punctuation"], style: { color: "var(--eld-syntax-default)" } },
+  ],
+};
+
+/** Map the friendly `lang` prop to a Prism grammar id (falls back to plain text). */
+const LANG_ALIASES: Record<string, string> = {
+  ts: "typescript",
+  typescript: "typescript",
+  tsx: "tsx",
+  js: "javascript",
+  javascript: "javascript",
+  jsx: "jsx",
+  json: "json",
+  bash: "bash",
+  sh: "bash",
+  shell: "bash",
+  zsh: "bash",
+  console: "bash",
+  terminal: "bash",
+  css: "css",
+  html: "markup",
+  xml: "markup",
+  md: "markdown",
+  markdown: "markdown",
+  py: "python",
+  python: "python",
+  yaml: "yaml",
+  yml: "yaml",
+  sql: "sql",
+  go: "go",
+};
+
+function prismLang(lang?: string): string {
+  if (!lang) return "text";
+  return LANG_ALIASES[lang.toLowerCase()] ?? lang.toLowerCase();
+}
+
+/** Prism-highlighted code lines, themed from `--eld-syntax-*`. */
+function Highlighted({ code, lang }: { code: string; lang?: string }) {
+  return (
+    <Highlight theme={eldPrismTheme} code={code} language={prismLang(lang)}>
+      {({ tokens, getLineProps, getTokenProps }) => (
+        <>
+          {tokens.map((line, i) => (
+            <span key={i} {...getLineProps({ line })} className="block">
+              {line.map((token, j) => (
+                <span key={j} {...getTokenProps({ token })} />
+              ))}
+            </span>
+          ))}
+        </>
+      )}
+    </Highlight>
+  );
+}
+
 /**
  * CodeBlock — the signature Elide code surface. Dark in both themes (matches the
  * Figma Code Block). Two variants:
@@ -47,8 +119,9 @@ export function CopyButton({
  *                 and an optional vim-style status bar with the magenta NORMAL badge.
  *   - "terminal": a "TERMINAL" title row and prompt output.
  *
- * `children` should be already-highlighted markup (Shiki at build time, or hand
- * spans in stories). `code` is the raw text — used for copy and line counting.
+ * By default `code` is syntax-highlighted with Prism using the `lang` grammar,
+ * themed from the `--eld-syntax-*` tokens. Pass `children` to override with your
+ * own pre-highlighted markup (e.g. Shiki output).
  */
 export interface CodeBlockProps {
   variant?: "editor" | "terminal";
@@ -80,8 +153,10 @@ export function CodeBlock({
   statusBar = variant === "editor",
   className,
 }: CodeBlockProps) {
-  const lines = code.replace(/\n$/, "").split("\n");
-  const body = children ?? code;
+  const trimmed = code.replace(/\n$/, "");
+  const lines = trimmed.split("\n");
+  // `children` (pre-highlighted) wins; otherwise highlight the raw code.
+  const body = children ?? <Highlighted code={trimmed} lang={variant === "terminal" ? lang ?? "bash" : lang} />;
 
   if (variant === "terminal") {
     return (
@@ -90,7 +165,7 @@ export function CodeBlock({
           className="flex h-8 items-center gap-2 border-b px-3.5 font-mono text-[11px] font-semibold uppercase tracking-wider text-[var(--eld-syntax-line-number)]"
           style={elev}
         >
-          <span className="i">{lang ?? "Terminal"}</span>
+          <span>{lang ?? "Terminal"}</span>
         </div>
         <pre className="m-0 overflow-x-auto p-4 font-mono text-[13px] leading-[1.7] text-[var(--eld-syntax-default)]">
           {body}
diff --git a/packages/ui/src/components/elide-logo.tsx b/packages/ui/src/components/elide-logo.tsx
new file mode 100644
index 0000000..daa0621
--- /dev/null
+++ b/packages/ui/src/components/elide-logo.tsx
@@ -0,0 +1,70 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Elide brand marks, inlined as SVG so they render everywhere without an
+ * external asset request (works in SSR, Storybook, and Chromatic capture).
+ *
+ * - `ElideMark` — the gradient hexagon glyph.
+ * - `ElideWordmark` — the "elide" wordmark, drawn in `currentColor`.
+ * - `ElideLogo` — the nav lockup (mark + wordmark), used as AppNav's default logo.
+ */
+export function ElideMark({ className, ...props }: React.SVGProps<SVGSVGElement>) {
+  // Unique gradient id per instance so multiple marks on a page don't collide.
+  const gid = React.useId();
+  return (
+    <svg
+      viewBox="0 0 102.700292 114.027098"
+      role="img"
+      aria-label="Elide"
+      className={cn("h-[23px] w-auto", className)}
+      {...props}
+    >
+      <defs>
+        <linearGradient id={gid} x1="51.350146" y1="114.027098" x2="51.350146" y2="0" gradientUnits="userSpaceOnUse">
+          <stop offset="0" stopColor="#662d91" />
+          <stop offset="1" stopColor="#e7008c" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gid})`}
+        d="M102.700292,78.149657v-42.272216c0-5.266571-2.809682-10.133083-7.370666-12.766369L58.720812,1.974964c-4.560984-2.633285-10.180348-2.633285-14.741333,0L7.370666,23.111072c-4.560984,2.633285-7.370666,7.499798-7.370666,12.766369v42.272216c0,5.266571,2.809682,10.133083,7.370666,12.766369l36.608813,21.136108c4.560984,2.633285,10.180348,2.633285,14.741333,0l36.608813-21.136108c4.560984-2.633285,7.370666-7.499798,7.370666-12.766369Z"
+      />
+      <path
+        fill="#ffffff"
+        d="M51.350146,102.206307c-1.573011,0-3.146023-.405097-4.549025-1.21508l-31.262343-18.049408c-2.805898-1.619965-4.548919-4.639011-4.548919-7.878942v-36.098815c0-3.239931,1.743021-6.258976,4.548813-7.878942l31.262555-18.049196c2.805898-1.620177,6.291834-1.620177,9.097944,0l31.262343,18.049196c2.805898,1.619965,4.548919,4.639011,4.548919,7.878942,0,3.240143-1.743127,6.2594-4.549131,7.879154l-1.984256,1.14555,1.984468,1.145762c2.805898,1.619965,4.548919,4.639011,4.548919,7.878942s-1.743021,6.258976-4.548813,7.878942l-1.984574,1.145762,1.984468,1.145762c2.805898,1.619965,4.548919,4.639011,4.548919,7.878942s-1.743021,6.258976-4.548813,7.878942l-31.262555,18.049408c-1.402896.809983-2.975907,1.21508-4.548919,1.21508ZM51.350146,18.330171c-.44707,0-.894139.115106-1.292877.345318l-31.262449,18.049196c-.797476.460425-1.292877,1.318527-1.292877,2.239376v36.098815c0,.920849.495402,1.778952,1.292877,2.239376l31.262449,18.049408c.797476.460425,1.788279.460425,2.585755,0l31.262449-18.049408c.797476-.460425,1.292877-1.318527,1.292877-2.239376s-.495402-1.778952-1.292877-2.239376l-5.24051-3.025617-22.765898,13.143935c-2.80611,1.619965-6.292046,1.619965-9.097944,0l-15.636948-9.027884c-2.848824-1.644767-4.549343-4.590679-4.548919-7.880214.00053-3.289535,1.70179-6.235023,4.551039-7.878942l1.982984-1.144278-1.92257-1.109937c-2.844055-1.642012-4.544573-4.582836-4.548919-7.866859-.004452-3.284023,1.688224-6.229511,4.527933-7.878942l15.583635-9.052473c2.809926-1.632048,6.304129-1.636924,9.118718-.011871l22.756889,13.138636,5.24051-3.025617c.797582-.460425,1.292877-1.318527,1.292877-2.239376s-.495402-1.778952-1.292877-2.239376l-31.262449-18.049196c-.398738-.230212-.845808-.345318-1.292877-.345318ZM39.66242,60.770848l-5.24157,3.024345c-1.167278.673466-1.293407,1.790399-1.293513,2.239376,0,.448978.125811,1.56591,1.292983,2.2398l15.636948,9.027884c.797476.460425,1.788279.460425,2.585755,0l19.509857-11.26408-9.119248-5.264994-7.134568,4.119232c-2.80611,1.620177-6.292046,1.620177-9.097944,0l-7.138701-4.121563ZM69.545715,57.013469l9.119248,5.264994,5.24051-3.025617c.797476-.460425,1.292877-1.318527,1.292877-2.239376s-.495402-1.778952-1.292877-2.239376l-5.24051-3.025617-9.119248,5.264994ZM46.176516,57.012198l3.880752,2.240648c.797476.460425,1.788279.460425,2.585755,0l3.878526-2.239376-3.87948-2.2398c-.797264-.460213-1.787855-.460001-2.585119-.000424l-3.880434,2.238952ZM51.349086,47.919235c1.573223,0,3.145917.404885,4.548919,1.214868l7.135627,4.119656,9.119248-5.264994-19.500954-11.258781c-.799808-.461273-1.792837-.460425-2.591796.003392l-15.583423,9.052262c-1.16325.675798-1.287472,1.791247-1.286836,2.239376s.127825,1.563366,1.292877,2.235985l5.180625,2.991064,7.139019-4.119232c1.402154-.809135,2.974635-1.213596,4.546693-1.213596Z"
+      />
+    </svg>
+  );
+}
+
+export function ElideWordmark({ className, ...props }: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 179.42 42.36"
+      role="img"
+      aria-label="Elide"
+      className={cn("h-[14px] w-auto", className)}
+      {...props}
+    >
+      <path
+        fill="currentColor"
+        d="m172.76 22.75c0 1.05-.72 1.6-1.6 1.6h-17.68c-.91 0-1.65-.74-1.65-1.65v-1.54c0-.94.72-1.82 1.6-1.82h17.74c.88 0 1.6.77 1.6 1.82v1.6zm6.66-4.57c0-3.03-2.48-5.34-5.34-5.34h-23.41c-2.86 0-5.34 1.98-5.34 5.34v18.9c.06 3.2 2.37 5.29 5.34 5.29h25.78c1.05 0 2.97-1.05 2.97-2.92v-.77c0-1.32-1.49-2.81-2.97-2.81h-23.03c-.88 0-1.6-.72-1.6-1.6v-2.64c0-.91.74-1.65 1.65-1.65h20.6c3.2 0 5.4-2.26 5.34-5.18v-6.61zm-151.99 4.57c0 1.05-.72 1.6-1.6 1.6h-17.68c-.91 0-1.65-.74-1.65-1.65v-1.54c0-.94.72-1.82 1.6-1.82h17.74c.88 0 1.6.77 1.6 1.82v1.6zm6.67-4.57c0-3.03-2.48-5.34-5.34-5.34h-23.42c-2.86 0-5.34 1.98-5.34 5.34v18.9c.06 3.2 2.37 5.29 5.34 5.29h25.78c1.05 0 2.97-1.05 2.97-2.92v-.77c0-1.32-1.49-2.81-2.97-2.81h-23.02c-.88 0-1.6-.72-1.6-1.6v-2.64c0-.91.74-1.65 1.65-1.65h20.6c3.2 0 5.4-2.26 5.34-5.18v-6.61zm98.5 17.68h-17.63c-.97 0-1.76-.79-1.76-1.76v-12.95c0-.94.72-1.82 1.6-1.82h17.79c.91 0 1.65.74 1.65 1.65v13.22c0 .91-.74 1.65-1.65 1.65zm5.34-35.86h-.88c-2.04 0-2.81 1.49-2.81 2.81v8.37c0 .91-.74 1.65-1.65 1.65h-20.6c-3.08 0-5.29 2.31-5.29 5.34v18.9c.06 3.25 2.31 5.29 5.29 5.29h23.47c2.81 0 5.29-2.53 5.29-5.29v-34.26c0-1.32-.88-2.81-2.81-2.81zm-80.21 35.86c-.91 0-1.65-.74-1.65-1.65v-31.4c0-1.32-.61-2.81-2.81-2.81h-13.44c-1.6 0-2.75 1.49-2.75 2.81v.88c0 1.32 1.16 2.81 2.75 2.81h8.1c.91 0 1.65.74 1.65 1.65v26.06c0 .91-.74 1.65-1.65 1.65h-8.1c-1.6 0-2.75 1.49-2.75 2.81v.88c0 1.49.99 2.81 2.75 2.81h26c1.6 0 2.75-1.16 2.75-2.81v-.88c0-1.32-.99-2.81-2.75-2.81zm30.36-28.75c1.65 0 3.08-1.38 3.08-3.14v-.88c0-1.76-1.43-3.08-3.08-3.08h-.88c-1.65 0-3.08 1.32-3.08 3.08v.88c0 1.76 1.43 3.14 3.08 3.14zm2.81 8.54c0-1.16-.61-2.81-2.81-2.81h-13.44c-1.6 0-2.81.94-2.81 2.81v.88c0 1.76 1.21 2.81 2.81 2.81h8.1c.91 0 1.65.74 1.65 1.65v13.22c0 .91-.74 1.65-1.65 1.65h-8.1c-1.16 0-2.81 1.21-2.81 2.81v.88c0 1.65 1.65 2.81 2.81 2.81h26c1.6 0 2.81-1.32 2.81-2.81v-.88c0-1.32-1.21-2.81-2.81-2.81h-8.1c-.91 0-1.65-.74-1.65-1.65z"
+      />
+    </svg>
+  );
+}
+
+export interface ElideLogoProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Hide the wordmark, showing only the hexagon glyph. */
+  markOnly?: boolean;
+}
+
+export function ElideLogo({ markOnly, className, ...props }: ElideLogoProps) {
+  return (
+    <span className={cn("inline-flex items-center gap-[9px] text-foreground", className)} {...props}>
+      <ElideMark aria-hidden={!markOnly} className="h-[23px]" />
+      {markOnly ? null : <ElideWordmark aria-hidden className="h-[14px]" />}
+    </span>
+  );
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 3235010..47a8b37 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -42,6 +42,7 @@ export {
 
 // --- Tier-2 docs composites (cycle 2, ported from the Elide Docs mockup) ---
 export { AppNav, type AppNavProps, type NavLink } from "./components/app-nav";
+export { ElideLogo, ElideMark, ElideWordmark, type ElideLogoProps } from "./components/elide-logo";
 export {
   SectionTabs, type SectionTabsProps, type SectionTabItem, type SectionTabsVersion,
 } from "./components/section-tabs";
diff --git a/packages/ui/src/stories/CodeBlock.stories.tsx b/packages/ui/src/stories/CodeBlock.stories.tsx
index be220fd..c3e7c37 100644
--- a/packages/ui/src/stories/CodeBlock.stories.tsx
+++ b/packages/ui/src/stories/CodeBlock.stories.tsx
@@ -2,10 +2,6 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, within } from "storybook/test";
 import { CodeBlock } from "../components/code-block";
 
-const S = ({ c, children }: { c: string; children: React.ReactNode }) => (
-  <span style={{ color: `var(--eld-syntax-${c})` }}>{children}</span>
-);
-
 const meta = {
   title: "Docs/CodeBlock",
   component: CodeBlock,
@@ -15,38 +11,28 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-const sqlite = `const { Database } = require("sqlite");
+const tsSource = `import { Database } from "elide:sqlite";
 
 const db = new Database(":memory:");
 db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
 
-const user = db.prepare("SELECT * FROM users WHERE id = 1").get();
+const user = db.prepare<{ id: number; name: string }>(
+  "SELECT * FROM users WHERE id = ?",
+).get(1);
 console.log(\`Hello from \${user.name}!\`);`;
 
+// Code is syntax-highlighted by the component from `lang` (Prism, themed via the
+// --eld-syntax-* tokens) — stories just pass raw source.
 export const Editor: Story = {
   args: {
     variant: "editor",
-    filename: "app.js",
-    lang: "js",
-    code: sqlite,
+    filename: "app.ts",
+    lang: "ts",
+    code: tsSource,
   },
   render: (args) => (
     <div style={{ maxWidth: 640 }}>
-      <CodeBlock {...args}>
-        <S c="keyword">const</S> {"{ "}
-        <S c="type">Database</S>
-        {" } "}
-        <S c="keyword">=</S> <S c="function">require</S>(<S c="string">"sqlite"</S>);
-        {"\n\n"}
-        <S c="keyword">const</S> db <S c="keyword">=</S> <S c="keyword">new</S>{" "}
-        <S c="type">Database</S>(<S c="string">":memory:"</S>);{"\n"}
-        db.<S c="function">exec</S>(
-        <S c="string">"CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"</S>);{"\n\n"}
-        <S c="keyword">const</S> user <S c="keyword">=</S> db.
-        <S c="function">prepare</S>(<S c="string">"SELECT * FROM users WHERE id = 1"</S>).
-        <S c="function">get</S>();{"\n"}
-        console.<S c="function">log</S>(<S c="string">{"`Hello from ${user.name}!`"}</S>);
-      </CodeBlock>
+      <CodeBlock {...args} />
     </div>
   ),
   // The icon-only copy button must have an accessible name (regression guard for
@@ -61,14 +47,11 @@ export const Terminal: Story = {
   args: {
     variant: "terminal",
     lang: "bash",
-    code: "$ elide app.ts\nHello from Elide!",
+    code: "$ elide run app.ts\nHello from Elide!\n$ elide install",
   },
   render: (args) => (
     <div style={{ maxWidth: 640 }}>
-      <CodeBlock {...args}>
-        <S c="comment">$</S> elide app.ts{"\n"}
-        <span style={{ color: "#3fb950" }}>Hello from Elide!</span>
-      </CodeBlock>
+      <CodeBlock {...args} />
     </div>
   ),
 };

From 0408b98d8260f1d9308abc14b0bc74fb66e1eaf0 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 13:11:07 -0700
Subject: [PATCH 06/10] fix(a11y): color-contrast + dialog name; address
 Copilot review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Accessibility (Storybook a11y / Chromatic):
- Accent text used --primary (#d4007f), which fails WCAG AA on the dark
  surfaces (3.87:1). Switch text usages to --primary-emphasis (the design
  system's on-surface accent — magenta-400 on dark), leaving bg/border accents
  alone. Fixes SectionTabs, ApiMethod/ParamRow, SupportMatrix, MobileNav,
  TableOfContents, Sidebar, StatStrip, AiActions.
- --subtle-foreground was neutral-500 (#737373) in dark, failing AA for the
  small mono micro-labels; step it up to neutral-400 (light unchanged).
- MobileNav's Sheet drawer (role=dialog) had no accessible name -> add aria-label.

Copilot review:
- ai-actions: swallow clipboard writeText rejection (matches CopyButton).
- stat-strip: emit <dt> before <dd> for valid <dl> markup; order-* preserves
  the value-on-top layout.

Story/test class assertions updated to the -emphasis token to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/tokens/src/tokens.css                  |  4 +++-
 packages/ui/src/components/ai-actions.tsx       |  6 ++++--
 packages/ui/src/components/api-method.tsx       |  8 ++++----
 packages/ui/src/components/mobile-nav.tsx       | 17 +++++++++++------
 packages/ui/src/components/section-tabs.tsx     |  2 +-
 packages/ui/src/components/sidebar.tsx          |  8 ++++----
 packages/ui/src/components/stat-strip.test.tsx  |  6 +++---
 packages/ui/src/components/stat-strip.tsx       |  8 +++++---
 packages/ui/src/components/support-matrix.tsx   |  2 +-
 .../src/components/table-of-contents.test.tsx   |  2 +-
 .../ui/src/components/table-of-contents.tsx     |  2 +-
 packages/ui/src/stories/StatStrip.stories.tsx   |  2 +-
 12 files changed, 39 insertions(+), 28 deletions(-)

diff --git a/packages/tokens/src/tokens.css b/packages/tokens/src/tokens.css
index 6bd6b0c..3d66274 100644
--- a/packages/tokens/src/tokens.css
+++ b/packages/tokens/src/tokens.css
@@ -142,7 +142,9 @@
 
   --muted: var(--eld-neutral-800);
   --muted-foreground: var(--eld-neutral-400);
-  --subtle-foreground: var(--eld-neutral-500);
+  /* neutral-500 (#737373) fails WCAG AA for small text on the dark surfaces;
+     step up to neutral-400 so micro-labels clear 4.5:1 (light stays 500). */
+  --subtle-foreground: var(--eld-neutral-400);
 
   --accent: var(--eld-neutral-700);
   --accent-foreground: var(--eld-neutral-50);
diff --git a/packages/ui/src/components/ai-actions.tsx b/packages/ui/src/components/ai-actions.tsx
index a178a35..ad9487f 100644
--- a/packages/ui/src/components/ai-actions.tsx
+++ b/packages/ui/src/components/ai-actions.tsx
@@ -41,7 +41,7 @@ export function AiActions({
       {...props}
     >
       <div className="mb-0.5 flex items-center gap-1.5 font-mono text-[11px] font-semibold tracking-wider text-subtle-foreground uppercase">
-        <Sparkles aria-hidden className="h-[13px] w-[13px] text-[var(--primary)]" />
+        <Sparkles aria-hidden className="h-[13px] w-[13px] text-[var(--primary-emphasis)]" />
         {title}
       </div>
 
@@ -49,7 +49,9 @@ export function AiActions({
         <button
           type="button"
           onClick={() => {
-            void navigator.clipboard?.writeText(markdown);
+            // Swallow clipboard rejections (no permission / headless) so a failed
+            // copy doesn't surface as an unhandled promise rejection.
+            void navigator.clipboard?.writeText(markdown)?.catch(() => {});
             setCopied(true);
             setTimeout(() => setCopied(false), 1500);
           }}
diff --git a/packages/ui/src/components/api-method.tsx b/packages/ui/src/components/api-method.tsx
index 40e9de1..08fb310 100644
--- a/packages/ui/src/components/api-method.tsx
+++ b/packages/ui/src/components/api-method.tsx
@@ -18,10 +18,10 @@ export interface ParamRowProps {
 export function ParamRow({ name, type, description, className }: ParamRowProps) {
   return (
     <div className={cn("flex items-baseline gap-3", className)}>
-      <code className="w-24 shrink-0 font-mono text-[12.5px] text-[var(--primary)]">{name}</code>
+      <code className="w-24 shrink-0 font-mono text-[12.5px] text-[var(--primary-emphasis)]">{name}</code>
       <span className="shrink-0 font-mono text-xs text-[var(--eld-syntax-type)]">{type}</span>
       {description ? (
-        <span className="text-[13.5px] text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary)]">
+        <span className="text-[13.5px] text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary-emphasis)]">
           {description}
         </span>
       ) : null}
@@ -79,14 +79,14 @@ export function ApiMethod({
           <a
             href={`#${anchorId}`}
             aria-label={`Link to ${typeof signature === "string" ? signature : "this method"}`}
-            className="text-[var(--primary)] opacity-55 transition-opacity hover:opacity-100"
+            className="text-[var(--primary-emphasis)] opacity-55 transition-opacity hover:opacity-100"
           >
             <Hash aria-hidden className="h-3.5 w-3.5" />
           </a>
         ) : null}
       </div>
       {description ? (
-        <p className="mb-4 max-w-[640px] text-[14.5px] leading-relaxed text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary)]">
+        <p className="mb-4 max-w-[640px] text-[14.5px] leading-relaxed text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary-emphasis)]">
           {description}
         </p>
       ) : null}
diff --git a/packages/ui/src/components/mobile-nav.tsx b/packages/ui/src/components/mobile-nav.tsx
index 85fbace..0e17732 100644
--- a/packages/ui/src/components/mobile-nav.tsx
+++ b/packages/ui/src/components/mobile-nav.tsx
@@ -78,7 +78,7 @@ export function MobileNav({
                 size="icon"
                 aria-label="Open navigation"
                 className={cn(
-                  drawerOpen && "border-[var(--primary)] bg-[var(--primary-soft)] text-[var(--primary)]",
+                  drawerOpen && "border-[var(--primary)] bg-[var(--primary-soft)] text-[var(--primary-emphasis)]",
                 )}
               />
             }
@@ -99,20 +99,25 @@ export function MobileNav({
             onClick={onSearch}
             className="flex h-11 w-full items-center gap-2.5 rounded-xl border border-[var(--border-strong)] bg-[var(--muted)] px-3.5 text-[var(--subtle-foreground)]"
           >
-            <Search aria-hidden className="h-4 w-4 text-[var(--primary)]" />
+            <Search aria-hidden className="h-4 w-4 text-[var(--primary-emphasis)]" />
             <span className="flex-1 text-left text-sm">{searchPlaceholder}</span>
-            <Sparkle aria-hidden className="h-[15px] w-[15px] text-[var(--primary)]" />
+            <Sparkle aria-hidden className="h-[15px] w-[15px] text-[var(--primary-emphasis)]" />
           </button>
         </div>
       </div>
 
-      <SheetContent side="left" showCloseButton={false} className="flex w-72 flex-col gap-5 p-4">
+      <SheetContent
+        side="left"
+        showCloseButton={false}
+        aria-label={section?.title ? `${section.title} navigation` : "Navigation menu"}
+        className="flex w-72 flex-col gap-5 p-4"
+      >
         {section ? (
           <div className="flex items-center gap-2.5">
             {section.icon ? (
               <span
                 aria-hidden
-                className="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg bg-[var(--primary-soft)] text-[var(--primary)]"
+                className="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg bg-[var(--primary-soft)] text-[var(--primary-emphasis)]"
               >
                 {section.icon}
               </span>
@@ -136,7 +141,7 @@ export function MobileNav({
                 const linkClassName = cn(
                   "rounded-lg px-2.5 py-2 text-sm",
                   item.active
-                    ? "font-semibold text-[var(--primary)] bg-[var(--primary-soft)]"
+                    ? "font-semibold text-[var(--primary-emphasis)] bg-[var(--primary-soft)]"
                     : "text-muted-foreground",
                 );
                 return item.href ? (
diff --git a/packages/ui/src/components/section-tabs.tsx b/packages/ui/src/components/section-tabs.tsx
index a5f7b78..100033a 100644
--- a/packages/ui/src/components/section-tabs.tsx
+++ b/packages/ui/src/components/section-tabs.tsx
@@ -58,7 +58,7 @@ export function SectionTabs({ items, version, onSelect, className, ...props }: S
           }
           className={cn(
             "relative px-3 py-3.5 text-[13.5px] text-muted-foreground transition-colors",
-            item.active && "font-semibold text-[var(--primary)]",
+            item.active && "font-semibold text-[var(--primary-emphasis)]",
           )}
         >
           {item.label}
diff --git a/packages/ui/src/components/sidebar.tsx b/packages/ui/src/components/sidebar.tsx
index b580433..3347a6c 100644
--- a/packages/ui/src/components/sidebar.tsx
+++ b/packages/ui/src/components/sidebar.tsx
@@ -51,7 +51,7 @@ export function SectionSwitcher({
           >
             <span className="flex min-w-0 items-center gap-2.5">
               {active?.icon ? (
-                <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-[var(--primary-soft)] text-[var(--primary)]">
+                <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-[var(--primary-soft)] text-[var(--primary-emphasis)]">
                   {active.icon}
                 </span>
               ) : null}
@@ -78,7 +78,7 @@ export function SectionSwitcher({
             className="items-center gap-2.5 py-1.5"
           >
             {section.icon ? (
-              <span className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-[var(--primary-soft)] text-[var(--primary)]">
+              <span className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-[var(--primary-soft)] text-[var(--primary-emphasis)]">
                 {section.icon}
               </span>
             ) : null}
@@ -89,7 +89,7 @@ export function SectionSwitcher({
               ) : null}
             </span>
             {section.id === activeId ? (
-              <Check aria-hidden className="ml-auto h-4 w-4 shrink-0 text-[var(--primary)]" />
+              <Check aria-hidden className="ml-auto h-4 w-4 shrink-0 text-[var(--primary-emphasis)]" />
             ) : null}
           </DropdownMenuItem>
         ))}
@@ -134,7 +134,7 @@ export function SidebarItem({ label, href, active, external, comingSoon, onSelec
       className={cn(
         "flex items-center justify-between gap-2 rounded-lg px-2.5 py-1.5 text-[13.5px] transition-colors",
         active
-          ? "bg-[var(--primary-soft)] font-semibold text-[var(--primary)]"
+          ? "bg-[var(--primary-soft)] font-semibold text-[var(--primary-emphasis)]"
           : "text-muted-foreground hover:bg-[var(--hover)] hover:text-foreground",
       )}
     >
diff --git a/packages/ui/src/components/stat-strip.test.tsx b/packages/ui/src/components/stat-strip.test.tsx
index 2b9d07a..ac0aed4 100644
--- a/packages/ui/src/components/stat-strip.test.tsx
+++ b/packages/ui/src/components/stat-strip.test.tsx
@@ -24,9 +24,9 @@ describe("StatStrip", () => {
 
   it("emphasizes only the flagged stat's value", () => {
     render(<StatStrip stats={stats} />);
-    expect(screen.getByText("94%")).toHaveClass("text-[var(--primary)]");
-    expect(screen.getByText("24")).not.toHaveClass("text-[var(--primary)]");
-    expect(screen.getByText("89%")).not.toHaveClass("text-[var(--primary)]");
+    expect(screen.getByText("94%")).toHaveClass("text-[var(--primary-emphasis)]");
+    expect(screen.getByText("24")).not.toHaveClass("text-[var(--primary-emphasis)]");
+    expect(screen.getByText("89%")).not.toHaveClass("text-[var(--primary-emphasis)]");
   });
 
   it("exposes an accessible label on the region", () => {
diff --git a/packages/ui/src/components/stat-strip.tsx b/packages/ui/src/components/stat-strip.tsx
index 2217d3d..b0965bf 100644
--- a/packages/ui/src/components/stat-strip.tsx
+++ b/packages/ui/src/components/stat-strip.tsx
@@ -42,15 +42,17 @@ export function StatStrip({
             key={i}
             className={cn("flex flex-col gap-1.5 p-5", !lastInRow && !last && "border-r border-border")}
           >
+            {/* Semantic order is <dt> (term/label) then <dd> (value); `order-*`
+                keeps the value visually on top per the mockup. */}
+            <dt className="order-2 text-xs text-muted-foreground">{stat.label}</dt>
             <dd
               className={cn(
-                "m-0 font-display text-[28px] font-bold leading-none",
-                stat.emphasis ? "text-[var(--primary)]" : "text-foreground",
+                "order-1 m-0 font-display text-[28px] font-bold leading-none",
+                stat.emphasis ? "text-[var(--primary-emphasis)]" : "text-foreground",
               )}
             >
               {stat.value}
             </dd>
-            <dt className="text-xs text-muted-foreground">{stat.label}</dt>
           </div>
         );
       })}
diff --git a/packages/ui/src/components/support-matrix.tsx b/packages/ui/src/components/support-matrix.tsx
index 3554637..d9a8ad0 100644
--- a/packages/ui/src/components/support-matrix.tsx
+++ b/packages/ui/src/components/support-matrix.tsx
@@ -73,7 +73,7 @@ export function SupportMatrix({
             const StatusIcon = status.icon;
             return (
               <tr key={i} className="border-t border-border">
-                <td className="px-4 py-2.5 font-mono text-[var(--primary)]">{row.method}</td>
+                <td className="px-4 py-2.5 font-mono text-[var(--primary-emphasis)]">{row.method}</td>
                 <td className="px-4 py-2.5 text-center">
                   <StatusIcon
                     role="img"
diff --git a/packages/ui/src/components/table-of-contents.test.tsx b/packages/ui/src/components/table-of-contents.test.tsx
index e0716f0..1db8951 100644
--- a/packages/ui/src/components/table-of-contents.test.tsx
+++ b/packages/ui/src/components/table-of-contents.test.tsx
@@ -21,7 +21,7 @@ describe("TableOfContents", () => {
     render(<TableOfContents items={items} activeId="installation" />);
     const active = screen.getByRole("link", { name: "Installation" });
     expect(active).toHaveAttribute("aria-current", "location");
-    expect(active).toHaveClass("text-[var(--primary)]");
+    expect(active).toHaveClass("text-[var(--primary-emphasis)]");
 
     const inactive = screen.getByRole("link", { name: "Overview" });
     expect(inactive).not.toHaveAttribute("aria-current");
diff --git a/packages/ui/src/components/table-of-contents.tsx b/packages/ui/src/components/table-of-contents.tsx
index d9908d8..d9bc26f 100644
--- a/packages/ui/src/components/table-of-contents.tsx
+++ b/packages/ui/src/components/table-of-contents.tsx
@@ -89,7 +89,7 @@ export function TableOfContents({
               "border-l-2 text-[13px] no-underline transition-colors",
               variant === "mono" && "font-mono",
               isActive
-                ? "border-[var(--primary)] font-semibold text-[var(--primary)]"
+                ? "border-[var(--primary)] font-semibold text-[var(--primary-emphasis)]"
                 : "border-transparent text-muted-foreground hover:text-foreground",
             )}
           >
diff --git a/packages/ui/src/stories/StatStrip.stories.tsx b/packages/ui/src/stories/StatStrip.stories.tsx
index 0b63740..d39d862 100644
--- a/packages/ui/src/stories/StatStrip.stories.tsx
+++ b/packages/ui/src/stories/StatStrip.stories.tsx
@@ -25,7 +25,7 @@ export const ApiCompatibility: Story = {
     await expect(canvas.getByText("Node modules")).toBeInTheDocument();
     const testPassRate = canvas.getByText("94%");
     await expect(testPassRate).toBeInTheDocument();
-    await expect(testPassRate).toHaveClass("text-[var(--primary)]");
+    await expect(testPassRate).toHaveClass("text-[var(--primary-emphasis)]");
   },
 };
 

From 982730fd361940052d422a7f7eab153aba77e8a3 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 13:14:19 -0700
Subject: [PATCH 07/10] ci: Codecov Test Analytics + Bundle Analysis

- Both Vitest suites emit JUnit XML (test-report.junit.xml); check.test.yml
  uploads them via codecov/test-results-action (SHA-pinned v1.2.1), running on
  failure too so failing/flaky tests surface in Codecov Test Analytics.
- Storybook Vite build runs @codecov/vite-plugin (bundleName elide-storybook)
  for Bundle Analysis, gated on CODECOV_TOKEN; job.storybook.yml passes the
  token into the build env.

The @elide/ui library is built with tsup (esbuild), which has no first-party
Codecov bundler plugin, so bundle analysis covers the Storybook build only.
Both features use the existing CODECOV_TOKEN secret.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/check.test.yml    |  8 ++++
 .github/workflows/job.storybook.yml |  4 ++
 .gitignore                          |  3 ++
 apps/storybook/.storybook/main.ts   | 10 +++++
 apps/storybook/package.json         |  1 +
 apps/storybook/vitest.config.ts     |  2 +
 bun.lock                            | 65 ++++++++++++++++++++++++++++-
 packages/ui/vitest.config.ts        |  3 ++
 8 files changed, 94 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/check.test.yml b/.github/workflows/check.test.yml
index 50361ff..00f986f 100644
--- a/.github/workflows/check.test.yml
+++ b/.github/workflows/check.test.yml
@@ -43,6 +43,14 @@ jobs:
         # workspace's `test` script (`vitest run`), so both suites emit their
         # own coverage/lcov.info without a dedicated turbo task.
         run: bunx turbo run test -- --coverage
+      - name: "Test Analytics: Upload results to Codecov"
+        # Upload JUnit results even when tests fail, so failing/flaky tests show
+        # up in Codecov Test Analytics.
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@0fa95f0e1eeaafde2c782583b36b28ad0d8c77d3 # v1.2.1
+        with:
+          files: packages/ui/test-report.junit.xml,apps/storybook/test-report.junit.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
       - name: "Coverage: Upload ui-unit (jsdom) to Codecov"
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
diff --git a/.github/workflows/job.storybook.yml b/.github/workflows/job.storybook.yml
index d97473c..8513673 100644
--- a/.github/workflows/job.storybook.yml
+++ b/.github/workflows/job.storybook.yml
@@ -37,7 +37,11 @@ jobs:
       - name: "Install: Dependencies"
         run: bun install --frozen-lockfile
       - name: "Build: Storybook static site"
+        # CODECOV_TOKEN enables the @codecov/vite-plugin bundle-analysis upload
+        # during the Vite build (no-op if the secret is absent).
         run: bunx turbo run build --filter=@elide/storybook
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       - name: "Artifact: Upload storybook-static"
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
diff --git a/.gitignore b/.gitignore
index 40a79ae..d3506ef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,6 @@ storybook-static/
 
 # Coverage output
 coverage/
+
+# Test reports
+*.junit.xml
diff --git a/apps/storybook/.storybook/main.ts b/apps/storybook/.storybook/main.ts
index 5af6015..a1b202b 100644
--- a/apps/storybook/.storybook/main.ts
+++ b/apps/storybook/.storybook/main.ts
@@ -21,6 +21,16 @@ const config: StorybookConfig = {
     const { default: tailwindcss } = await import("@tailwindcss/vite");
     cfg.plugins = cfg.plugins ?? [];
     cfg.plugins.push(tailwindcss());
+    // Codecov bundle analysis — uploads bundle stats when CODECOV_TOKEN is set
+    // (CI build). No-op locally without a token.
+    const { codecovVitePlugin } = await import("@codecov/vite-plugin");
+    cfg.plugins.push(
+      codecovVitePlugin({
+        enableBundleAnalysis: process.env.CODECOV_TOKEN !== undefined,
+        bundleName: "elide-storybook",
+        uploadToken: process.env.CODECOV_TOKEN,
+      }),
+    );
     return cfg;
   },
 };
diff --git a/apps/storybook/package.json b/apps/storybook/package.json
index e8a0e26..92b9c5c 100644
--- a/apps/storybook/package.json
+++ b/apps/storybook/package.json
@@ -19,6 +19,7 @@
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.2.1",
+    "@codecov/vite-plugin": "^2.0.1",
     "@storybook/addon-a11y": "^10.4.6",
     "@storybook/addon-mcp": "^0.6.0",
     "@storybook/addon-vitest": "^10.4.6",
diff --git a/apps/storybook/vitest.config.ts b/apps/storybook/vitest.config.ts
index d826835..6bf3007 100644
--- a/apps/storybook/vitest.config.ts
+++ b/apps/storybook/vitest.config.ts
@@ -18,6 +18,8 @@ export default defineConfig({
   plugins: [storybookTest({ configDir: ".storybook" })],
   test: {
     name: "storybook",
+    // JUnit output feeds Codecov Test Analytics (uploaded in CI).
+    reporters: ["default", ["junit", { outputFile: "./test-report.junit.xml" }]],
     browser: {
       enabled: true,
       provider: playwright(),
diff --git a/bun.lock b/bun.lock
index d779499..c62b0a2 100644
--- a/bun.lock
+++ b/bun.lock
@@ -24,6 +24,7 @@
       },
       "devDependencies": {
         "@chromatic-com/storybook": "^5.2.1",
+        "@codecov/vite-plugin": "^2.0.1",
         "@storybook/addon-a11y": "^10.4.6",
         "@storybook/addon-mcp": "^0.6.0",
         "@storybook/addon-vitest": "^10.4.6",
@@ -94,6 +95,16 @@
     },
   },
   "packages": {
+    "@actions/core": ["@actions/core@3.0.1", "", { "dependencies": { "@actions/exec": "^3.0.0", "@actions/http-client": "^4.0.0" } }, "sha512-a6d/Nwahm9fliVGRhdhofo40HjHQasUPusmc7vBfyky+7Z+P2A1J68zyFVaNcEclc/Se+eO595oAr5nwEIoIUA=="],
+
+    "@actions/exec": ["@actions/exec@3.0.0", "", { "dependencies": { "@actions/io": "^3.0.2" } }, "sha512-6xH/puSoNBXb72VPlZVm7vQ+svQpFyA96qdDBvhB8eNZOE8LtPf9L4oAsfzK/crCL8YZ+19fKYVnM63Sl+Xzlw=="],
+
+    "@actions/github": ["@actions/github@9.1.1", "", { "dependencies": { "@actions/http-client": "^3.0.2", "@octokit/core": "^7.0.6", "@octokit/plugin-paginate-rest": "^14.0.0", "@octokit/plugin-rest-endpoint-methods": "^17.0.0", "@octokit/request": "^10.0.7", "@octokit/request-error": "^7.1.0", "undici": "^6.23.0" } }, "sha512-tL5JbYOBZHc0ngEnCsaDcryUizIUIlQyIMwy1Wkx93H5HzbBJ7TbiPx2PnFjBwZW0Vh05JmfFZhecE6gglYegA=="],
+
+    "@actions/http-client": ["@actions/http-client@4.0.1", "", { "dependencies": { "tunnel": "^0.0.6", "undici": "^6.23.0" } }, "sha512-+Nvd1ImaOZBSoPbsUtEhv+1z99H12xzncCkz0a3RuehINE81FZSe2QTj3uvAPTcJX/SCzUQHQ0D1GrPMbrPitg=="],
+
+    "@actions/io": ["@actions/io@3.0.2", "", {}, "sha512-nRBchcMM+QK1pdjO7/idu86rbJI5YHUKCvKs0KxnSYbVe3F51UfGxuZX4Qy/fWlp6l7gWFwIkrOzN+oUK03kfw=="],
+
     "@adobe/css-tools": ["@adobe/css-tools@4.5.0", "", {}, "sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q=="],
 
     "@asamuzakjp/css-color": ["@asamuzakjp/css-color@3.2.0", "", { "dependencies": { "@csstools/css-calc": "^2.1.3", "@csstools/css-color-parser": "^3.0.9", "@csstools/css-parser-algorithms": "^3.0.4", "@csstools/css-tokenizer": "^3.0.3", "lru-cache": "^10.4.3" } }, "sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw=="],
@@ -176,6 +187,10 @@
 
     "@chromatic-com/storybook": ["@chromatic-com/storybook@5.2.1", "", { "dependencies": { "@neoconfetti/react": "^1.0.0", "chromatic": "16.10.0", "jsonfile": "^6.1.0", "strip-ansi": "^7.1.0" }, "peerDependencies": { "storybook": "^0.0.0-0 || ^10.1.0 || ^10.1.0-0 || ^10.2.0-0 || ^10.3.0-0 || ^10.4.0-0 || ^10.5.0-0 || ^10.6.0-0" } }, "sha512-z6I7NJk/0VngA64y5TNYaB4Hc2X8+90n4op6lBt9PvWk5TmIlFLDqdX33rlrwbNRkkYijVgA/wO04rVYXi5Mlg=="],
 
+    "@codecov/bundler-plugin-core": ["@codecov/bundler-plugin-core@2.0.1", "", { "dependencies": { "@actions/core": "^3.0.0", "@actions/github": "^9.0.0", "chalk": "4.1.2", "semver": "^7.5.4", "unplugin": "^1.10.1", "zod": "^3.22.4" } }, "sha512-TkdKn/rEwZQ723M7DDUmHe5r0IJa23rUT4TAx5jXmg12wGZGAHGWWU7LKeQsYCsKdLMxK7bLaGk9M++4wSRD5w=="],
+
+    "@codecov/vite-plugin": ["@codecov/vite-plugin@2.0.1", "", { "dependencies": { "@codecov/bundler-plugin-core": "^2.0.1", "unplugin": "^1.10.1" }, "peerDependencies": { "vite": "4.x || 5.x || 6.x" } }, "sha512-w7nGA9SSc0WECzn05yRrw3uN8293I620Kd9x97I0kyyxUjtWxCMmlgmAbS364gJZYvljd0A6iQyAigVV2dOX9A=="],
+
     "@csstools/color-helpers": ["@csstools/color-helpers@5.1.0", "", {}, "sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA=="],
 
     "@csstools/css-calc": ["@csstools/css-calc@2.1.4", "", { "peerDependencies": { "@csstools/css-parser-algorithms": "^3.0.5", "@csstools/css-tokenizer": "^3.0.4" } }, "sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ=="],
@@ -318,6 +333,26 @@
 
     "@nodelib/fs.walk": ["@nodelib/fs.walk@1.2.8", "", { "dependencies": { "@nodelib/fs.scandir": "2.1.5", "fastq": "^1.6.0" } }, "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg=="],
 
+    "@octokit/auth-token": ["@octokit/auth-token@6.0.0", "", {}, "sha512-P4YJBPdPSpWTQ1NU4XYdvHvXJJDxM6YwpS0FZHRgP7YFkdVxsWcpWGy/NVqlAA7PcPCnMacXlRm1y2PFZRWL/w=="],
+
+    "@octokit/core": ["@octokit/core@7.0.6", "", { "dependencies": { "@octokit/auth-token": "^6.0.0", "@octokit/graphql": "^9.0.3", "@octokit/request": "^10.0.6", "@octokit/request-error": "^7.0.2", "@octokit/types": "^16.0.0", "before-after-hook": "^4.0.0", "universal-user-agent": "^7.0.0" } }, "sha512-DhGl4xMVFGVIyMwswXeyzdL4uXD5OGILGX5N8Y+f6W7LhC1Ze2poSNrkF/fedpVDHEEZ+PHFW0vL14I+mm8K3Q=="],
+
+    "@octokit/endpoint": ["@octokit/endpoint@11.0.3", "", { "dependencies": { "@octokit/types": "^16.0.0", "universal-user-agent": "^7.0.2" } }, "sha512-FWFlNxghg4HrXkD3ifYbS/IdL/mDHjh9QcsNyhQjN8dplUoZbejsdpmuqdA76nxj2xoWPs7p8uX2SNr9rYu0Ag=="],
+
+    "@octokit/graphql": ["@octokit/graphql@9.0.3", "", { "dependencies": { "@octokit/request": "^10.0.6", "@octokit/types": "^16.0.0", "universal-user-agent": "^7.0.0" } }, "sha512-grAEuupr/C1rALFnXTv6ZQhFuL1D8G5y8CN04RgrO4FIPMrtm+mcZzFG7dcBm+nq+1ppNixu+Jd78aeJOYxlGA=="],
+
+    "@octokit/openapi-types": ["@octokit/openapi-types@27.0.0", "", {}, "sha512-whrdktVs1h6gtR+09+QsNk2+FO+49j6ga1c55YZudfEG+oKJVvJLQi3zkOm5JjiUXAagWK2tI2kTGKJ2Ys7MGA=="],
+
+    "@octokit/plugin-paginate-rest": ["@octokit/plugin-paginate-rest@14.0.0", "", { "dependencies": { "@octokit/types": "^16.0.0" }, "peerDependencies": { "@octokit/core": ">=6" } }, "sha512-fNVRE7ufJiAA3XUrha2omTA39M6IXIc6GIZLvlbsm8QOQCYvpq/LkMNGyFlB1d8hTDzsAXa3OKtybdMAYsV/fw=="],
+
+    "@octokit/plugin-rest-endpoint-methods": ["@octokit/plugin-rest-endpoint-methods@17.0.0", "", { "dependencies": { "@octokit/types": "^16.0.0" }, "peerDependencies": { "@octokit/core": ">=6" } }, "sha512-B5yCyIlOJFPqUUeiD0cnBJwWJO8lkJs5d8+ze9QDP6SvfiXSz1BF+91+0MeI1d2yxgOhU/O+CvtiZ9jSkHhFAw=="],
+
+    "@octokit/request": ["@octokit/request@10.0.11", "", { "dependencies": { "@octokit/endpoint": "^11.0.3", "@octokit/request-error": "^7.0.2", "@octokit/types": "^16.0.0", "content-type": "^2.0.0", "json-with-bigint": "^3.5.3", "universal-user-agent": "^7.0.2" } }, "sha512-+s7HUxjfFqOMS9VlIwDffq0MikjSAK0gSpG73W+meAvVAvX4MBrHYTK5Bj3Uot55qFT4gzUtfzE4mGWY4Br8/Q=="],
+
+    "@octokit/request-error": ["@octokit/request-error@7.1.0", "", { "dependencies": { "@octokit/types": "^16.0.0" } }, "sha512-KMQIfq5sOPpkQYajXHwnhjCC0slzCNScLHs9JafXc4RAJI+9f+jNDlBNaIMTvazOPLgb4BnlhGJOTbnN0wIjPw=="],
+
+    "@octokit/types": ["@octokit/types@16.0.0", "", { "dependencies": { "@octokit/openapi-types": "^27.0.0" } }, "sha512-sKq+9r1Mm4efXW1FCk7hFSeJo4QKreL/tTbR0rz/qx/r1Oa2VV83LTA/H/MuCOX7uCIJmQVRKBcbmWoySjAnSg=="],
+
     "@oxc-parser/binding-android-arm-eabi": ["@oxc-parser/binding-android-arm-eabi@0.127.0", "", { "os": "android", "cpu": "arm" }, "sha512-0LC7ye4hvqbIKxAzThzvswgHLFu2AURKzYLeSVvLdu2TBOYWQDmHnTqPLeA597BcUCxiLqLsS4CJ5uoI5WYWCQ=="],
 
     "@oxc-parser/binding-android-arm64": ["@oxc-parser/binding-android-arm64@0.127.0", "", { "os": "android", "cpu": "arm64" }, "sha512-b5jtVTH6AU5CJXHNdj7Jj9IEiR9yVjjnwHzPJhGyHGPdcsZSzBCkS9GBbV33niRMvKthDwQRFRJfI4a+k4PvYg=="],
@@ -656,7 +691,7 @@
 
     "ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
 
-    "ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
+    "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
 
     "any-promise": ["any-promise@1.3.0", "", {}, "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A=="],
 
@@ -678,6 +713,8 @@
 
     "baseline-browser-mapping": ["baseline-browser-mapping@2.10.42", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-c/jurFrDLyui7o1J86yLkRu4LMsTYcBohveus7/I2Hzdn9KIP2bdJPTue/lR1KH46enoPbD77GKeSYNdyPoD3Q=="],
 
+    "before-after-hook": ["before-after-hook@4.0.0", "", {}, "sha512-q6tR3RPqIB1pMiTRMFcZwuG5T8vwp+vUvEG0vuI6B+Rikh5BfPp2fQ82c925FOs+b0lcFQ8CFrL+KbilfZFhOQ=="],
+
     "better-path-resolve": ["better-path-resolve@1.0.0", "", { "dependencies": { "is-windows": "^1.0.0" } }, "sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g=="],
 
     "brace-expansion": ["brace-expansion@5.0.7", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA=="],
@@ -696,6 +733,8 @@
 
     "chai": ["chai@5.3.3", "", { "dependencies": { "assertion-error": "^2.0.1", "check-error": "^2.1.1", "deep-eql": "^5.0.1", "loupe": "^3.1.0", "pathval": "^2.0.0" } }, "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw=="],
 
+    "chalk": ["chalk@4.1.2", "", { "dependencies": { "ansi-styles": "^4.1.0", "supports-color": "^7.1.0" } }, "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA=="],
+
     "chardet": ["chardet@2.2.0", "", {}, "sha512-rddelWYNPRrXq6PtNEN2S3f6t9ILzvqaN5pVgi4kqt9jHQaXIial9PznB5iSPVlQSLNaaH22ItWz3EJtQ10+OA=="],
 
     "check-error": ["check-error@2.1.3", "", {}, "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA=="],
@@ -708,12 +747,18 @@
 
     "clsx": ["clsx@2.1.1", "", {}, "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA=="],
 
+    "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
+
+    "color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
+
     "commander": ["commander@4.1.1", "", {}, "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA=="],
 
     "confbox": ["confbox@0.1.8", "", {}, "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w=="],
 
     "consola": ["consola@3.4.2", "", {}, "sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA=="],
 
+    "content-type": ["content-type@2.0.0", "", {}, "sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ=="],
+
     "convert-source-map": ["convert-source-map@2.0.0", "", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],
 
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
@@ -910,6 +955,8 @@
 
     "json-stable-stringify-without-jsonify": ["json-stable-stringify-without-jsonify@1.0.1", "", {}, "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw=="],
 
+    "json-with-bigint": ["json-with-bigint@3.5.8", "", {}, "sha512-eq/4KP6K34kwa7TcFdtvnftvHCD9KvHOGGICWwMFc4dOOKF5t4iYqnfLK8otCRCRv06FXOzGGyqE8h8ElMvvdw=="],
+
     "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
 
     "jsonfile": ["jsonfile@6.2.1", "", { "dependencies": { "universalify": "^2.0.0" }, "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q=="],
@@ -1212,6 +1259,8 @@
 
     "tsup": ["tsup@8.5.1", "", { "dependencies": { "bundle-require": "^5.1.0", "cac": "^6.7.14", "chokidar": "^4.0.3", "consola": "^3.4.0", "debug": "^4.4.0", "esbuild": "^0.27.0", "fix-dts-default-cjs-exports": "^1.0.0", "joycon": "^3.1.1", "picocolors": "^1.1.1", "postcss-load-config": "^6.0.1", "resolve-from": "^5.0.0", "rollup": "^4.34.8", "source-map": "^0.7.6", "sucrase": "^3.35.0", "tinyexec": "^0.3.2", "tinyglobby": "^0.2.11", "tree-kill": "^1.2.2" }, "peerDependencies": { "@microsoft/api-extractor": "^7.36.0", "@swc/core": "^1", "postcss": "^8.4.12", "typescript": ">=4.5.0" }, "optionalPeers": ["@microsoft/api-extractor", "@swc/core", "postcss", "typescript"], "bin": { "tsup": "dist/cli-default.js", "tsup-node": "dist/cli-node.js" } }, "sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing=="],
 
+    "tunnel": ["tunnel@0.0.6", "", {}, "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="],
+
     "turbo": ["turbo@2.10.3", "", { "optionalDependencies": { "@turbo/darwin-64": "2.10.3", "@turbo/darwin-arm64": "2.10.3", "@turbo/linux-64": "2.10.3", "@turbo/linux-arm64": "2.10.3", "@turbo/windows-64": "2.10.3", "@turbo/windows-arm64": "2.10.3" }, "bin": { "turbo": "bin/turbo" } }, "sha512-uZIqzfgtWbyqu1Tqwdd0giRnPGgL0ejbcdF8eZLJhtTTVSrOgArZGzYeXTD6XNcc7ANgdhqex11Y9bHBeyiQLQ=="],
 
     "tw-animate-css": ["tw-animate-css@1.4.0", "", {}, "sha512-7bziOlRqH0hJx80h/3mbicLW7o8qLsH5+RaLR2t+OHM3D0JlWGODQKQ4cxbK7WlvmUxpcj6Kgu6EKqjrGFe3QQ=="],
@@ -1224,9 +1273,13 @@
 
     "ufo": ["ufo@1.6.4", "", {}, "sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA=="],
 
+    "undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
+
+    "universal-user-agent": ["universal-user-agent@7.0.3", "", {}, "sha512-TmnEAEAsBJVZM/AADELsK76llnwcf9vMKuPz8JflO1frO8Lchitr0fNaN9d+Ap0BjKtqWqd/J17qeDnXh8CL2A=="],
+
     "universalify": ["universalify@0.1.2", "", {}, "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg=="],
 
-    "unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
+    "unplugin": ["unplugin@1.16.1", "", { "dependencies": { "acorn": "^8.14.0", "webpack-virtual-modules": "^0.6.2" } }, "sha512-4/u/j4FrCKdi17jaxuJA0jClGxB1AvU2hw/IuayPc4ay1XGaJs/rbb4v5WKwAjNifjmXK9PIFyuPiaK8azyR9w=="],
 
     "update-browserslist-db": ["update-browserslist-db@1.2.3", "", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": { "update-browserslist-db": "cli.js" } }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
 
@@ -1272,6 +1325,10 @@
 
     "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
 
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+
+    "@actions/github/@actions/http-client": ["@actions/http-client@3.0.2", "", { "dependencies": { "tunnel": "^0.0.6", "undici": "^6.23.0" } }, "sha512-JP38FYYpyqvUsz+Igqlc/JG6YO9PaKuvqjM3iGvaLqFnJ7TFmcLyy2IDrY0bI0qCQug8E9K+elv5ZNfw62ZJzA=="],
+
     "@babel/code-frame/js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
 
     "@babel/core/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
@@ -1300,6 +1357,8 @@
 
     "@rolldown/binding-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@1.11.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw=="],
 
+    "@storybook/csf-plugin/unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
+
     "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.11.2", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.2", "tslib": "^2.4.0" }, "bundled": true }, "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA=="],
 
     "@tailwindcss/oxide-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@1.11.2", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA=="],
@@ -1342,6 +1401,8 @@
 
     "pretty-format/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
+    "pretty-format/ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
+
     "read-yaml-file/js-yaml": ["js-yaml@3.15.0", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog=="],
 
     "recast/source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
diff --git a/packages/ui/vitest.config.ts b/packages/ui/vitest.config.ts
index 4eadaf0..89f7e0a 100644
--- a/packages/ui/vitest.config.ts
+++ b/packages/ui/vitest.config.ts
@@ -13,6 +13,9 @@ export default defineConfig({
     globals: true,
     setupFiles: ["./src/test-setup.ts"],
     include: ["src/**/*.test.{ts,tsx}"],
+    // JUnit output feeds Codecov Test Analytics (uploaded in CI); the default
+    // reporter stays on for readable local runs.
+    reporters: ["default", ["junit", { outputFile: "./test-report.junit.xml" }]],
     coverage: {
       provider: "v8",
       reporter: ["text", "json", "lcov"],

From 16c7244c2de4f0cbf7784396bc10697012077074 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 13:26:31 -0700
Subject: [PATCH 08/10] fix(a11y): readable API-reference text in light theme

ApiMethod rendered the signature function-name and ParamRow type using the
code-surface syntax tokens (--eld-syntax-function pale yellow, --eld-syntax-type
teal). Those are tuned for the always-dark code surface and become unreadable on
the light page background. Use theme-aware tokens: the signature name -> the
--primary-emphasis accent, the param type -> muted-foreground. Clears the
remaining light-theme color-contrast violations (Chromatic tests both themes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/ui/src/components/api-method.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/components/api-method.tsx b/packages/ui/src/components/api-method.tsx
index 08fb310..d48efbf 100644
--- a/packages/ui/src/components/api-method.tsx
+++ b/packages/ui/src/components/api-method.tsx
@@ -19,7 +19,7 @@ export function ParamRow({ name, type, description, className }: ParamRowProps)
   return (
     <div className={cn("flex items-baseline gap-3", className)}>
       <code className="w-24 shrink-0 font-mono text-[12.5px] text-[var(--primary-emphasis)]">{name}</code>
-      <span className="shrink-0 font-mono text-xs text-[var(--eld-syntax-type)]">{type}</span>
+      <span className="shrink-0 font-mono text-xs text-muted-foreground">{type}</span>
       {description ? (
         <span className="text-[13.5px] text-muted-foreground [&_code]:font-mono [&_code]:text-[var(--primary-emphasis)]">
           {description}
@@ -36,7 +36,7 @@ function emphasizeSignature(signature: string | React.ReactNode) {
   if (parenIndex === -1) return signature;
   return (
     <>
-      <span className="text-[var(--eld-syntax-function)]">{signature.slice(0, parenIndex)}</span>
+      <span className="text-[var(--primary-emphasis)]">{signature.slice(0, parenIndex)}</span>
       {signature.slice(parenIndex)}
     </>
   );

From def8d902c174a53525177432a4e3a4af49f51fd8 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 13:36:22 -0700
Subject: [PATCH 09/10] feat(ui): i18n string layer + MessagesProvider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Break every string a component renders itself (labels, placeholders, ARIA
names, status text) out of the components into a default English dictionary
(src/i18n/messages.ts), read via useMessages(). Consumers translate the catalog
by wrapping in <MessagesProvider messages={locale}> — a PartialMessages dict
deep-merged (two levels) over the defaults. Explicit props (e.g. AppNav
searchPlaceholder, AiActions title) still override per-instance.

Wired: AppNav, MobileNav, SectionTabs, Sidebar, TableOfContents, CodeBlock/
CopyButton, AiActions, SupportMatrix, StatusBadge. Exues MessagesProvider,
useMessages, defaultMessages, Messages, PartialMessages.

Also: the nav search placeholder default is now "Search or ask" (was
"Search or ask AI…").

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/ui/src/components/ai-actions.tsx     |  8 +-
 packages/ui/src/components/app-nav.tsx        | 20 +++--
 packages/ui/src/components/code-block.tsx     | 12 ++-
 .../ui/src/components/mobile-nav.test.tsx     |  2 +-
 packages/ui/src/components/mobile-nav.tsx     | 18 ++--
 packages/ui/src/components/section-tabs.tsx   |  4 +-
 packages/ui/src/components/sidebar.tsx        |  7 +-
 packages/ui/src/components/status-badge.tsx   | 21 ++---
 packages/ui/src/components/support-matrix.tsx | 18 ++--
 .../ui/src/components/table-of-contents.tsx   |  8 +-
 packages/ui/src/i18n/messages.ts              | 89 +++++++++++++++++++
 packages/ui/src/i18n/provider.tsx             | 29 ++++++
 packages/ui/src/index.ts                      |  4 +
 packages/ui/src/stories/MobileNav.stories.tsx |  4 +-
 14 files changed, 194 insertions(+), 50 deletions(-)
 create mode 100644 packages/ui/src/i18n/messages.ts
 create mode 100644 packages/ui/src/i18n/provider.tsx

diff --git a/packages/ui/src/components/ai-actions.tsx b/packages/ui/src/components/ai-actions.tsx
index ad9487f..5c37e1d 100644
--- a/packages/ui/src/components/ai-actions.tsx
+++ b/packages/ui/src/components/ai-actions.tsx
@@ -1,6 +1,7 @@
 import * as React from "react";
 import { Check, Copy, ExternalLink, Sparkles } from "lucide-react";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * AiActions — the "Use with AI" panel in the docs right rail: copy the page as
@@ -27,12 +28,13 @@ const itemClass =
   "flex items-center gap-2 rounded-lg border border-border bg-muted px-2.5 py-2 text-left text-[12.5px] font-medium text-foreground no-underline transition-colors hover:bg-accent";
 
 export function AiActions({
-  title = "Use with AI",
+  title,
   markdown,
   actions = [],
   className,
   ...props
 }: AiActionsProps) {
+  const m = useMessages();
   const [copied, setCopied] = React.useState(false);
 
   return (
@@ -42,7 +44,7 @@ export function AiActions({
     >
       <div className="mb-0.5 flex items-center gap-1.5 font-mono text-[11px] font-semibold tracking-wider text-subtle-foreground uppercase">
         <Sparkles aria-hidden className="h-[13px] w-[13px] text-[var(--primary-emphasis)]" />
-        {title}
+        {title ?? m.aiActions.title}
       </div>
 
       {markdown ? (
@@ -62,7 +64,7 @@ export function AiActions({
           ) : (
             <Copy aria-hidden className="h-3.5 w-3.5 shrink-0" />
           )}
-          {copied ? "Copied" : "Copy as Markdown"}
+          {copied ? m.aiActions.copied : m.aiActions.copyAsMarkdown}
         </button>
       ) : null}
 
diff --git a/packages/ui/src/components/app-nav.tsx b/packages/ui/src/components/app-nav.tsx
index f9c8f47..3518302 100644
--- a/packages/ui/src/components/app-nav.tsx
+++ b/packages/ui/src/components/app-nav.tsx
@@ -3,6 +3,7 @@ import { ChevronDown, Globe, History, Search, Sparkles, Sun } from "lucide-react
 import { cn } from "../lib/utils";
 import { Button } from "./button";
 import { ElideLogo } from "./elide-logo";
+import { useMessages } from "../i18n/provider";
 
 /**
  * AppNav — the 56px top nav bar present on every docs page: brand + "DOCS"
@@ -36,7 +37,7 @@ const defaultLogo = <ElideLogo />;
 export function AppNav({
   links,
   logo,
-  searchPlaceholder = "Search or ask AI…",
+  searchPlaceholder,
   locale = "EN",
   installHref = "/install",
   changelogHref = "/changelog",
@@ -46,9 +47,10 @@ export function AppNav({
   className,
   ...props
 }: AppNavProps) {
+  const m = useMessages();
   return (
     <nav
-      aria-label="Main navigation"
+      aria-label={m.appNav.navLabel}
       className={cn(
         "flex h-14 items-center gap-[18px] border-b border-border px-[22px] backdrop-blur-xl [background:var(--nav-background)]",
         className,
@@ -58,7 +60,7 @@ export function AppNav({
       <div className="flex items-center gap-2">
         {logo ?? defaultLogo}
         <span className="rounded-md border border-border-strong px-[7px] py-0.5 font-mono text-[10px] font-semibold tracking-wider text-muted-foreground">
-          DOCS
+          {m.appNav.docsBadge}
         </span>
       </div>
 
@@ -87,11 +89,11 @@ export function AppNav({
       <button
         type="button"
         onClick={onSearchClick}
-        aria-label="Search"
+        aria-label={m.appNav.searchLabel}
         className="flex h-[34px] w-[280px] items-center gap-2 rounded-[9px] border border-border bg-muted px-3 text-subtle-foreground transition-colors hover:border-border-strong"
       >
         <Search aria-hidden className="h-[15px] w-[15px] shrink-0" />
-        <span className="flex-1 text-left text-[13px]">{searchPlaceholder}</span>
+        <span className="flex-1 text-left text-[13px]">{searchPlaceholder ?? m.appNav.searchPlaceholder}</span>
         <Sparkles aria-hidden className="h-[13px] w-[13px] shrink-0 text-primary" />
         <kbd className="rounded-[5px] border border-border-strong px-1.5 py-px font-mono text-[11px] font-medium">
           ⌘K
@@ -101,7 +103,7 @@ export function AppNav({
       <button
         type="button"
         onClick={onThemeToggle}
-        aria-label="Toggle theme"
+        aria-label={m.appNav.toggleTheme}
         className="flex h-[34px] w-[34px] items-center justify-center rounded-[9px] border border-border text-muted-foreground transition-colors hover:bg-[var(--hover)] hover:text-foreground"
       >
         <Sun aria-hidden className="h-4 w-4" />
@@ -110,7 +112,7 @@ export function AppNav({
       <button
         type="button"
         onClick={onLocaleClick}
-        aria-label="Language"
+        aria-label={m.appNav.language}
         className="flex h-[34px] items-center gap-1.5 rounded-[9px] border border-border px-[11px] text-[12.5px] font-medium text-muted-foreground transition-colors hover:bg-[var(--hover)] hover:text-foreground"
       >
         <Globe aria-hidden className="h-[15px] w-[15px]" />
@@ -120,11 +122,11 @@ export function AppNav({
 
       <Button variant="changelog" size="sm" render={<a href={changelogHref} />}>
         <History aria-hidden className="h-[15px] w-[15px]" />
-        Changelog
+        {m.appNav.changelog}
       </Button>
 
       <Button variant="gradient" size="sm" render={<a href={installHref} />}>
-        Install
+        {m.appNav.install}
       </Button>
     </nav>
   );
diff --git a/packages/ui/src/components/code-block.tsx b/packages/ui/src/components/code-block.tsx
index bb0e047..7decbca 100644
--- a/packages/ui/src/components/code-block.tsx
+++ b/packages/ui/src/components/code-block.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 import { Check, Copy } from "lucide-react";
 import { Highlight, type PrismTheme } from "prism-react-renderer";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * CopyButton — copies `value` to the clipboard, flips to a check for 1.5s.
@@ -10,17 +11,19 @@ import { cn } from "../lib/utils";
 export function CopyButton({
   value,
   className,
-  label = "Copy",
+  label,
 }: {
   value: string;
   className?: string;
+  /** Visible label; omit or pass "" for an icon-only button. Defaults to the localized "Copy". */
   label?: string;
 }) {
+  const m = useMessages();
   const [copied, setCopied] = React.useState(false);
   return (
     <button
       type="button"
-      aria-label={copied ? "Copied" : label || "Copy"}
+      aria-label={copied ? m.codeBlock.copied : label || m.codeBlock.copy}
       onClick={() => {
         // Swallow clipboard rejections (e.g. no permission in a headless/denied
         // context) — the copy is optimistic and a failure shouldn't surface as an
@@ -36,7 +39,7 @@ export function CopyButton({
       )}
     >
       {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
-      {label ? <span>{copied ? "Copied" : label}</span> : null}
+      {label ? <span>{copied ? m.codeBlock.copied : label}</span> : null}
     </button>
   );
 }
@@ -153,6 +156,7 @@ export function CodeBlock({
   statusBar = variant === "editor",
   className,
 }: CodeBlockProps) {
+  const m = useMessages();
   const trimmed = code.replace(/\n$/, "");
   const lines = trimmed.split("\n");
   // `children` (pre-highlighted) wins; otherwise highlight the raw code.
@@ -165,7 +169,7 @@ export function CodeBlock({
           className="flex h-8 items-center gap-2 border-b px-3.5 font-mono text-[11px] font-semibold uppercase tracking-wider text-[var(--eld-syntax-line-number)]"
           style={elev}
         >
-          <span>{lang ?? "Terminal"}</span>
+          <span>{lang ?? m.codeBlock.terminal}</span>
         </div>
         <pre className="m-0 overflow-x-auto p-4 font-mono text-[13px] leading-[1.7] text-[var(--eld-syntax-default)]">
           {body}
diff --git a/packages/ui/src/components/mobile-nav.test.tsx b/packages/ui/src/components/mobile-nav.test.tsx
index b03859f..6d8b0dd 100644
--- a/packages/ui/src/components/mobile-nav.test.tsx
+++ b/packages/ui/src/components/mobile-nav.test.tsx
@@ -53,7 +53,7 @@ describe("MobileNav", () => {
     const onSearch = vi.fn();
     render(<MobileNav groups={groups} onSearch={onSearch} />);
 
-    await user.click(screen.getByRole("button", { name: /search or ask ai/i }));
+    await user.click(screen.getByRole("button", { name: /search or ask/i }));
     expect(onSearch).toHaveBeenCalledTimes(1);
   });
 });
diff --git a/packages/ui/src/components/mobile-nav.tsx b/packages/ui/src/components/mobile-nav.tsx
index 0e17732..3a0518c 100644
--- a/packages/ui/src/components/mobile-nav.tsx
+++ b/packages/ui/src/components/mobile-nav.tsx
@@ -3,11 +3,12 @@ import { History, Menu, Search, Sparkle } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Button } from "./button";
 import { Sheet, SheetTrigger, SheetContent } from "./sheet";
+import { useMessages } from "../i18n/provider";
 
 /**
  * MobileNav — the docs shell at phone width (mockup 3b): a condensed top app
  * bar, a slide-in section drawer (built on the shipped `Sheet`), and a
- * persistent bottom "Search or ask AI" bar. Data-driven and presentational —
+ * persistent bottom "Search or ask" bar. Data-driven and presentational —
  * callers own routing (`href`s) and the search/AI action.
  */
 export interface MobileNavItem {
@@ -50,13 +51,14 @@ export function MobileNav({
   logo,
   onSearch,
   changelogHref,
-  searchPlaceholder = "Search or ask AI…",
+  searchPlaceholder,
   open,
   onOpenChange,
   className,
   children,
   ...props
 }: MobileNavProps) {
+  const m = useMessages();
   const [internalOpen, setInternalOpen] = React.useState(false);
   const drawerOpen = open ?? internalOpen;
   const setDrawerOpen = React.useCallback(
@@ -76,7 +78,7 @@ export function MobileNav({
               <Button
                 variant="outline"
                 size="icon"
-                aria-label="Open navigation"
+                aria-label={m.mobileNav.openNavigation}
                 className={cn(
                   drawerOpen && "border-[var(--primary)] bg-[var(--primary-soft)] text-[var(--primary-emphasis)]",
                 )}
@@ -86,7 +88,7 @@ export function MobileNav({
             <Menu aria-hidden className="h-[18px] w-[18px]" />
           </SheetTrigger>
           <div className="flex flex-1 items-center gap-2 overflow-hidden">{logo}</div>
-          <Button variant="outline" size="icon" aria-label="Search" onClick={onSearch}>
+          <Button variant="outline" size="icon" aria-label={m.mobileNav.searchLabel} onClick={onSearch}>
             <Search aria-hidden className="h-[17px] w-[17px]" />
           </Button>
         </header>
@@ -100,7 +102,7 @@ export function MobileNav({
             className="flex h-11 w-full items-center gap-2.5 rounded-xl border border-[var(--border-strong)] bg-[var(--muted)] px-3.5 text-[var(--subtle-foreground)]"
           >
             <Search aria-hidden className="h-4 w-4 text-[var(--primary-emphasis)]" />
-            <span className="flex-1 text-left text-sm">{searchPlaceholder}</span>
+            <span className="flex-1 text-left text-sm">{searchPlaceholder ?? m.mobileNav.searchPlaceholder}</span>
             <Sparkle aria-hidden className="h-[15px] w-[15px] text-[var(--primary-emphasis)]" />
           </button>
         </div>
@@ -109,7 +111,7 @@ export function MobileNav({
       <SheetContent
         side="left"
         showCloseButton={false}
-        aria-label={section?.title ? `${section.title} navigation` : "Navigation menu"}
+        aria-label={section?.title ? `${section.title} navigation` : m.mobileNav.dialogLabel}
         className="flex w-72 flex-col gap-5 p-4"
       >
         {section ? (
@@ -131,7 +133,7 @@ export function MobileNav({
           </div>
         ) : null}
 
-        <nav aria-label="Mobile navigation" className="flex flex-1 flex-col gap-4 overflow-y-auto">
+        <nav aria-label={m.mobileNav.navLabel} className="flex flex-1 flex-col gap-4 overflow-y-auto">
           {groups.map((group) => (
             <div key={group.label} className="flex flex-col gap-1">
               <div className="px-2.5 font-mono text-[10.5px] font-semibold uppercase tracking-wider text-[var(--subtle-foreground)]">
@@ -173,7 +175,7 @@ export function MobileNav({
           render={changelogHref ? <a href={changelogHref} /> : undefined}
         >
           <History aria-hidden className="h-[15px] w-[15px]" />
-          Changelog
+          {m.mobileNav.changelog}
         </Button>
       </SheetContent>
     </Sheet>
diff --git a/packages/ui/src/components/section-tabs.tsx b/packages/ui/src/components/section-tabs.tsx
index 100033a..9c10dba 100644
--- a/packages/ui/src/components/section-tabs.tsx
+++ b/packages/ui/src/components/section-tabs.tsx
@@ -1,5 +1,6 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * SectionTabs — the 46px top-level section bar under the main nav (Start ·
@@ -32,9 +33,10 @@ const dotColor: Record<NonNullable<SectionTabsVersion["status"]>, string> = {
 };
 
 export function SectionTabs({ items, version, onSelect, className, ...props }: SectionTabsProps) {
+  const m = useMessages();
   return (
     <nav
-      aria-label="Sections"
+      aria-label={m.sectionTabs.navLabel}
       className={cn(
         "flex h-[46px] items-center gap-1 border-b border-border bg-background px-[22px]",
         className,
diff --git a/packages/ui/src/components/sidebar.tsx b/packages/ui/src/components/sidebar.tsx
index 3347a6c..03953d7 100644
--- a/packages/ui/src/components/sidebar.tsx
+++ b/packages/ui/src/components/sidebar.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
 import { Check, ChevronDown, ExternalLink } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Badge } from "./badge";
+import { useMessages } from "../i18n/provider";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -110,6 +111,7 @@ export interface SidebarItemProps {
 }
 
 export function SidebarItem({ label, href, active, external, comingSoon, onSelect }: SidebarItemProps) {
+  const m = useMessages();
   if (comingSoon) {
     return (
       <span
@@ -118,7 +120,7 @@ export function SidebarItem({ label, href, active, external, comingSoon, onSelec
       >
         {label}
         <Badge variant="neutral" size="sm" className="shrink-0">
-          Soon
+          {m.sidebar.comingSoon}
         </Badge>
       </span>
     );
@@ -177,9 +179,10 @@ export function Sidebar({
   className,
   ...props
 }: SidebarProps) {
+  const m = useMessages();
   return (
     <nav
-      aria-label="Sidebar"
+      aria-label={m.sidebar.navLabel}
       className={cn("flex w-[264px] flex-col gap-[22px] border-r border-border bg-background p-3.5", className)}
       {...props}
     >
diff --git a/packages/ui/src/components/status-badge.tsx b/packages/ui/src/components/status-badge.tsx
index 732582b..be0f357 100644
--- a/packages/ui/src/components/status-badge.tsx
+++ b/packages/ui/src/components/status-badge.tsx
@@ -1,18 +1,19 @@
 import { Badge, type BadgeProps } from "./badge";
+import { useMessages } from "../i18n/provider";
 
 /**
  * StatusBadge — thin wrapper over `Badge`'s status tones. Maps an API-support
  * status (as used across the node:-compatibility reference pages) to a badge
- * variant, dot, and default label.
+ * variant, dot, and default (localized) label.
  */
 export type ApiStatus = "implemented" | "supported" | "partial" | "missing" | "planned";
 
-const STATUS_CONFIG: Record<ApiStatus, { variant: NonNullable<BadgeProps["variant"]>; label: string }> = {
-  implemented: { variant: "supported", label: "Implemented" },
-  supported: { variant: "supported", label: "Supported" },
-  partial: { variant: "partial", label: "Partial" },
-  missing: { variant: "missing", label: "Missing" },
-  planned: { variant: "missing", label: "Planned" },
+const STATUS_VARIANT: Record<ApiStatus, NonNullable<BadgeProps["variant"]>> = {
+  implemented: "supported",
+  supported: "supported",
+  partial: "partial",
+  missing: "missing",
+  planned: "missing",
 };
 
 export interface StatusBadgeProps extends Omit<BadgeProps, "variant" | "dot"> {
@@ -22,10 +23,10 @@ export interface StatusBadgeProps extends Omit<BadgeProps, "variant" | "dot"> {
 }
 
 export function StatusBadge({ status, label, children, ...props }: StatusBadgeProps) {
-  const { variant, label: defaultLabel } = STATUS_CONFIG[status];
+  const m = useMessages();
   return (
-    <Badge dot variant={variant} {...props}>
-      {children ?? label ?? defaultLabel}
+    <Badge dot variant={STATUS_VARIANT[status]} {...props}>
+      {children ?? label ?? m.statusBadge[status]}
     </Badge>
   );
 }
diff --git a/packages/ui/src/components/support-matrix.tsx b/packages/ui/src/components/support-matrix.tsx
index d9a8ad0..e9f0be9 100644
--- a/packages/ui/src/components/support-matrix.tsx
+++ b/packages/ui/src/components/support-matrix.tsx
@@ -1,6 +1,8 @@
 import * as React from "react";
 import { Check, CircleDot, X, type LucideIcon } from "lucide-react";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
+import type { Messages } from "../i18n/messages";
 
 /**
  * SupportMatrix — composite. The bordered reference table used on API pages to
@@ -34,23 +36,24 @@ const DEFAULT_COLUMNS: SupportMatrixColumn[] = [
   { key: "notes", label: "Notes" },
 ];
 
-const STATUS_META: Record<SupportStatus, { label: string; icon: LucideIcon; color: string }> = {
-  yes: { label: "Supported", icon: Check, color: "var(--eld-success-strong)" },
-  no: { label: "Not supported", icon: X, color: "var(--subtle-foreground)" },
-  partial: { label: "Partial", icon: CircleDot, color: "var(--eld-warning-strong)" },
+const STATUS_META: Record<SupportStatus, { messageKey: keyof Messages["supportMatrix"]; icon: LucideIcon; color: string }> = {
+  yes: { messageKey: "supported", icon: Check, color: "var(--eld-success-strong)" },
+  no: { messageKey: "notSupported", icon: X, color: "var(--subtle-foreground)" },
+  partial: { messageKey: "partial", icon: CircleDot, color: "var(--eld-warning-strong)" },
 };
 
 export function SupportMatrix({
   columns = DEFAULT_COLUMNS,
   rows,
-  caption = "Support matrix",
+  caption,
   className,
   ...props
 }: SupportMatrixProps) {
+  const m = useMessages();
   return (
     <div className={cn("overflow-hidden rounded-xl border border-border", className)} {...props}>
       <table className="w-full border-collapse text-sm">
-        <caption className="sr-only">{caption}</caption>
+        <caption className="sr-only">{caption ?? m.supportMatrix.caption}</caption>
         <thead className="bg-[var(--muted)]">
           <tr>
             {columns.map((column) => (
@@ -71,13 +74,14 @@ export function SupportMatrix({
           {rows.map((row, i) => {
             const status = STATUS_META[row.status];
             const StatusIcon = status.icon;
+            const statusLabel = m.supportMatrix[status.messageKey];
             return (
               <tr key={i} className="border-t border-border">
                 <td className="px-4 py-2.5 font-mono text-[var(--primary-emphasis)]">{row.method}</td>
                 <td className="px-4 py-2.5 text-center">
                   <StatusIcon
                     role="img"
-                    aria-label={status.label}
+                    aria-label={statusLabel}
                     className="inline-block h-4 w-4"
                     style={{ color: status.color }}
                   />
diff --git a/packages/ui/src/components/table-of-contents.tsx b/packages/ui/src/components/table-of-contents.tsx
index d9bc26f..c1548d7 100644
--- a/packages/ui/src/components/table-of-contents.tsx
+++ b/packages/ui/src/components/table-of-contents.tsx
@@ -1,5 +1,6 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { useMessages } from "../i18n/provider";
 
 /**
  * TableOfContents — the "On this page" right-rail nav that lists in-page
@@ -28,11 +29,12 @@ export function TableOfContents({
   items,
   activeId,
   variant = "default",
-  title = "On this page",
+  title,
   onSelect,
   className,
   ...props
 }: TableOfContentsProps) {
+  const m = useMessages();
   const [visibleIds, setVisibleIds] = React.useState<Set<string>>(() => new Set());
 
   React.useEffect(() => {
@@ -69,12 +71,12 @@ export function TableOfContents({
 
   return (
     <nav
-      aria-label="Table of contents"
+      aria-label={m.tableOfContents.navLabel}
       className={cn("flex flex-col gap-[11px]", className)}
       {...props}
     >
       <div className="font-mono text-[11px] font-semibold uppercase tracking-wider text-subtle-foreground">
-        {title}
+        {title ?? m.tableOfContents.title}
       </div>
       {items.map((item) => {
         const isActive = item.id === currentId;
diff --git a/packages/ui/src/i18n/messages.ts b/packages/ui/src/i18n/messages.ts
new file mode 100644
index 0000000..0d7a1be
--- /dev/null
+++ b/packages/ui/src/i18n/messages.ts
@@ -0,0 +1,89 @@
+/**
+ * Default (English) UI strings for @elide/ui, broken out for i18n. Every
+ * user-facing string a component renders itself (labels, placeholders, ARIA
+ * names, status text) lives here rather than being hardcoded, so a consuming
+ * app can translate the catalog by supplying a locale dictionary to
+ * `MessagesProvider`. Content passed in as props (nav items, method params,
+ * etc.) is the consumer's responsibility to localize.
+ *
+ * Shape is two levels: `messages.<component>.<key>`. Add new strings here (not
+ * inline in components) and read them via `useMessages()`.
+ */
+export const en = {
+  appNav: {
+    navLabel: "Main navigation",
+    docsBadge: "DOCS",
+    searchPlaceholder: "Search or ask",
+    searchLabel: "Search",
+    toggleTheme: "Toggle theme",
+    language: "Language",
+    changelog: "Changelog",
+    install: "Install",
+  },
+  mobileNav: {
+    openNavigation: "Open navigation",
+    navLabel: "Mobile navigation",
+    dialogLabel: "Navigation menu",
+    searchPlaceholder: "Search or ask",
+    searchLabel: "Search",
+    changelog: "Changelog",
+  },
+  sectionTabs: {
+    navLabel: "Sections",
+  },
+  sidebar: {
+    navLabel: "Sidebar",
+    comingSoon: "Soon",
+  },
+  tableOfContents: {
+    title: "On this page",
+    navLabel: "Table of contents",
+  },
+  codeBlock: {
+    copy: "Copy",
+    copied: "Copied",
+    terminal: "Terminal",
+  },
+  copyCommand: {
+    copy: "Copy",
+    copied: "Copied",
+  },
+  aiActions: {
+    title: "Use with AI",
+    copyAsMarkdown: "Copy as Markdown",
+    copied: "Copied",
+  },
+  supportMatrix: {
+    caption: "Support matrix",
+    supported: "Supported",
+    partial: "Partial",
+    notSupported: "Not supported",
+  },
+  statusBadge: {
+    implemented: "Implemented",
+    supported: "Supported",
+    partial: "Partial",
+    missing: "Missing",
+    planned: "Planned",
+  },
+} as const;
+
+/** The full messages dictionary shape (mutable — `en` is `as const`). */
+export type Messages = {
+  -readonly [K in keyof typeof en]: { -readonly [P in keyof (typeof en)[K]]: string };
+};
+
+/** A partial override: any subset of components, any subset of their keys. */
+export type PartialMessages = {
+  [K in keyof Messages]?: Partial<Messages[K]>;
+};
+
+/** Two-level merge of an override dictionary over the English defaults. */
+export function mergeMessages(base: Messages, override?: PartialMessages): Messages {
+  if (!override) return base;
+  const out = {} as Record<keyof Messages, Record<string, string>>;
+  for (const key of Object.keys(base) as (keyof Messages)[]) {
+    out[key] = { ...base[key], ...(override[key] ?? {}) };
+  }
+  return out as Messages;
+}
diff --git a/packages/ui/src/i18n/provider.tsx b/packages/ui/src/i18n/provider.tsx
new file mode 100644
index 0000000..31dc735
--- /dev/null
+++ b/packages/ui/src/i18n/provider.tsx
@@ -0,0 +1,29 @@
+import * as React from "react";
+import { en, mergeMessages, type Messages, type PartialMessages } from "./messages";
+
+/**
+ * i18n for @elide/ui. Components read their own chrome strings from
+ * `useMessages()`; wrap the app in `<MessagesProvider messages={locale}>` to
+ * translate them. Without a provider, English defaults (`en`) are used.
+ *
+ *   import { MessagesProvider } from "@elide/ui";
+ *   import fr from "./locales/fr.json"; // a PartialMessages dictionary
+ *   <MessagesProvider messages={fr}>{app}</MessagesProvider>
+ */
+const MessagesContext = React.createContext<Messages>(en);
+
+export interface MessagesProviderProps {
+  /** Locale dictionary; deep-merged (two levels) over the English defaults. */
+  messages?: PartialMessages;
+  children: React.ReactNode;
+}
+
+export function MessagesProvider({ messages, children }: MessagesProviderProps) {
+  const value = React.useMemo(() => mergeMessages(en, messages), [messages]);
+  return <MessagesContext.Provider value={value}>{children}</MessagesContext.Provider>;
+}
+
+/** Access the merged message dictionary (defaults ⊕ provider override). */
+export function useMessages(): Messages {
+  return React.useContext(MessagesContext);
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 47a8b37..e63def5 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -3,6 +3,10 @@ export { Badge, badgeVariants, type BadgeProps } from "./components/badge";
 export { Callout, type CalloutProps } from "./components/callout";
 export { CodeBlock, CopyButton, type CodeBlockProps } from "./components/code-block";
 export { cn } from "./lib/utils";
+export {
+  MessagesProvider, useMessages, type MessagesProviderProps,
+} from "./i18n/provider";
+export { en as defaultMessages, type Messages, type PartialMessages } from "./i18n/messages";
 export { ThemeProvider, useTheme, type Theme, type ThemeProviderProps } from "./components/theme-provider";
 export { Breadcrumbs, type BreadcrumbSegment, type BreadcrumbsProps } from "./components/breadcrumbs";
 export { PageFooterNav, type PageFooterNavLink, type PageFooterNavProps } from "./components/page-footer-nav";
diff --git a/packages/ui/src/stories/MobileNav.stories.tsx b/packages/ui/src/stories/MobileNav.stories.tsx
index 3ac8d22..017294b 100644
--- a/packages/ui/src/stories/MobileNav.stories.tsx
+++ b/packages/ui/src/stories/MobileNav.stories.tsx
@@ -51,8 +51,8 @@ export const Default: Story = {
   play: async ({ args, canvasElement }) => {
     const canvas = within(canvasElement);
 
-    // Bottom "Search or ask AI" bar fires onSearch.
-    await userEvent.click(canvas.getByRole("button", { name: /search or ask ai/i }));
+    // Bottom "Search or ask" bar fires onSearch.
+    await userEvent.click(canvas.getByRole("button", { name: /search or ask/i }));
     await expect(args.onSearch).toHaveBeenCalledTimes(1);
 
     // Sheet portals the drawer to document.body, so query there once open.

From 73fff24f609d6690d30eb5f507560855ce91df50 Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.dev>
Date: Mon, 6 Jul 2026 13:37:12 -0700
Subject: [PATCH 10/10] fix(a11y): expose ElideLogo's mark so the lockup has an
 accessible name

ElideLogo aria-hidden'd both the mark and the wordmark in the default case, so
the brand lockup announced nothing. Keep the mark exposed (role="img"
aria-label="Elide") with the wordmark decorative, so it's announced once.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/ui/src/components/elide-logo.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/elide-logo.tsx b/packages/ui/src/components/elide-logo.tsx
index daa0621..3c4dbd7 100644
--- a/packages/ui/src/components/elide-logo.tsx
+++ b/packages/ui/src/components/elide-logo.tsx
@@ -63,7 +63,9 @@ export interface ElideLogoProps extends React.HTMLAttributes<HTMLSpanElement> {
 export function ElideLogo({ markOnly, className, ...props }: ElideLogoProps) {
   return (
     <span className={cn("inline-flex items-center gap-[9px] text-foreground", className)} {...props}>
-      <ElideMark aria-hidden={!markOnly} className="h-[23px]" />
+      {/* The mark keeps its role="img" aria-label="Elide" so the lockup is
+          announced once; the wordmark is decorative alongside it. */}
+      <ElideMark className="h-[23px]" />
       {markOnly ? null : <ElideWordmark aria-hidden className="h-[14px]" />}
     </span>
   );