defuss-shadcn 0.7.14 → 0.8.1

package/AGENTS.md

@@ -16,10 +16,13 @@ must surface as a failure with output, never as an agent hanging forever.
 You are working on the **defuss-shadcn** design system repo.
 The consumer-facing system lives in `dist/` — **it is generated**: edit sources in
 `src/` (`bun run build` compiles `.ts` → `.js` and copies everything else 1:1).
-`docs/` is also generated: a 1:1 mirror of `dist/` (whole tree — Pages pages reference
-`../components/…` siblings) published by GitHub Pages; refresh it with `bun run docs`
-(`make build` does this automatically and `verify` fails if the mirror drifts). Never
-edit `docs/` directly — like `dist/`, it is deleted and rebuilt on every `bun run docs`.
+`docs/` is also generated: **only the documentation site** (`dist/documentation/*` +
+`robots.txt`/`sitemap.xml`) published by GitHub Pages — its pages' `../components/…` and
+`../theme/…` references are rewritten to the jsDelivr GitHub CDN (shared transform in
+`scripts/lib/mirror.ts`), so the mirror carries no copies of the component assets.
+Refresh it with `bun run docs` (`make build` does this automatically and `verify`
+fails if the mirror drifts). Never edit `docs/` directly — like `dist/`, it is
+deleted and rebuilt on every `bun run docs`.
 Never edit `dist/` directly; it is deleted and rebuilt on every build.
 
 ---
@@ -29,10 +32,11 @@ Never edit `dist/` directly; it is deleted and rebuilt on every build.
 ```
 defuss-shadcn/
 ├── dist/                              ← the distributable (drop into any project)
+│   ├── SKILL.md                       ← agent entry point (generated from src/SKILL_tpl.md + skill frontmatter)
 │   ├── theme/default-semantic-tokens.css      ← design tokens (source of truth for colors, radius, shadows)
 │   ├── components/                    ← self-contained component folders
 │   │   └── {name}/
-│   │       ├── component-skill.md      ← component skill (HTML structure & ARIA reference)
+│   │       ├── component-skill.md      ← component skill (frontmatter + HTML structure & ARIA reference)
 │   │       ├── {name}.css             ← component stylesheet (edit directly)
 │   │       └── {name}.js              ← interaction JS (only for interactive components)
 │   └── documentation/                 ← reference implementations + public website
@@ -54,11 +58,15 @@ defuss-shadcn/
 │   └── prompts/                       ← reusable prompt files
 │       └── component-review.prompt.md
 │
-├── screenshots/                       ← generated default-state PNGs per component in light/ + dark/ (`bun run screenshots`, gitignored)
+├── screenshots/                       ← generated PNGs per component AND per declared state, light/ + dark/ (`bun run screenshots`, gitignored) — SKILL.md maps state names to these files
 ├── scripts/                           ← build & maintenance scripts (no one-shot migrations)
 │   ├── build.ts                       ← src/ → dist/ (tsc type-strip + copy everything else 1:1)
 │   ├── verify.ts                      ← static consistency gate (runs at end of build; `bun run verify`)
-│   ├── sync-docs.ts                   ← mirror dist/ → docs/ for GitHub Pages (`bun run docs`)
+│   ├── sync-docs.ts                   ← mirror dist/documentation → docs/ (CDN-rewritten; `bun run docs`)
+│   ├── lib/mirror.ts                  ← shared docs/ mirror transform (sync-docs + verify compare against it)
+│   ├── lib/search-index.ts            ← docs search index generator (build.ts regenerates it every build)
+│   ├── lib/skill.ts                   ← SKILL.md generation core: frontmatter parser + index renderer (pure)
+│   ├── lib/skill-files.ts             ← dist/SKILL.md index generator from src/SKILL_tpl.md + skill frontmatter (build.ts regenerates every build)
 │   ├── create-screenshots.ts          ← parallel default-state screenshots for agent inspection
 │   ├── lib/audit.ts                   ← undefined-utility audit (used by verify)
 │   ├── lib/snippets.ts                ← shared snippet drift/replace logic (syncers + verify)
@@ -94,6 +102,92 @@ warn-ratchets it still reports, e.g. `STATE_API_LEGACY`, are named migration
 debt with an explicit removal path — not permission to ignore them.) The
 full rationale lives in [ARCH.md](ARCH.md).
 
+### Each component owns its dialog
+
+`dialog.js`'s init claims plain `<dialog>` elements for backdrop-click close —
+via a `dialog:not(.alert-dialog):not(.sheet):not(.command):not([data-init])`
+selector. **Any component that ships its own `<dialog class="…">` with custom
+behavior must be `:not()`-excluded there**, or dialog.js (loaded before every
+component script on all doc pages) stamps `data-init` first and the real
+owner's init silently skips the element — the docs search palette was dead
+exactly this way once. `verify`'s `dialog ownership boundary` gate enforces
+the exclusion list for the three dialog owners (alert-dialog, sheet, command);
+extend the list in both places when a fourth appears.
+
+The docs header search is the shipped command component itself: clicking the
+input (or ⌘/Ctrl+K) opens `<dialog class="command" id="docs-palette">`, fed by
+the build-time index (`scripts/lib/search-index.ts` → `js/search-index.js`,
+NAV entries + every page `<h2>` with TOC-compatible ids). The trigger is
+click/Enter only — never `focus`: `dialog.close()` restores focus to the
+opener synchronously, which would bounce the palette open again.
+
+### README ↔ index parity
+
+`README.md` and `src/documentation/index.html` describe the same system to
+humans and to browser users — **when you update either, update the other in
+the same commit.** They share two claims that drift independently if you
+forget:
+
+- **Pillar set** — the README intro bullets (`- **Name** — …`, under "What
+  this is" and before "Quick start") and the index pillar cards
+  (`<h3 class="card-title">`) must list the same set of pillars.
+- **Hero sentence** — the intro paragraph wording must match
+  (`"No build step for consumers — dist/ is committed and ready to use
+  as-is."` once diverged to a bare `"No build step."`).
+- **CDN dogfooding** — the index carries the "this site loads its assets
+  from the jsDelivr CDN, exactly as README's Via CDN quick start shows — if
+  it renders, the CDN install works" note, which must stay true if the CDN
+  strategy in [`scripts/lib/mirror.ts`](scripts/lib/mirror.ts) ever changes.
+- **CSS-only count** — the "**N of M components need no JavaScript**" line
+  appears in both README.md and the index; `verify`'s
+  `README CSS-only stat` / `index CSS-only stat` gates compare it against
+  the actual `src/components/` tree (a component `.ts` = ships a `.js`).
+  Update both files together whenever a component gains or loses behavior.
+
+`verify` enforces the pillar set (`README ↔ index parity`, hard gate) and the
+**`README ↔ index commit window`** gate: if the two files' last-touch commits
+are neither identical nor within **15 minutes** of each other, the build fails
+as "un-synced edit" — forcing you to land them together. Wording parity itself
+is yours to maintain (no automated text diff; the window is the backstop).
+
+### Changelog (two-commit rule)
+
+Every version in `package.json` needs an entry in
+[`src/documentation/changelog.html`](src/documentation/changelog.html) listing
+**all commit messages** of that release (deploy.sh generates them since the
+last tag; v0.7.14 was the first release after the fork from
+codylindley/shadcn-html, so its entry documents the fork). Each entry shows
+either the release date badge or — once the version is actually **committed** —
+the short git hash of the commit that added the entry, embedded as
+`<code class="changelog-hash">abc1234</code>`. The hash is unknowable before
+that commit exists, so authoring an entry is inherently **two commits**:
+
+1. commit the entry (with date badge),
+2. commit that commit's short hash into the entry.
+
+`verify`'s `changelog ↔ version` gate fails when the committed `package.json`
+version has no entry (or a hash-less / message-less entry for that version);
+its `fix:` line states the two-commit instruction. `scripts/deploy.sh`
+automates the whole flow. Legacy entries (v0.7.13-alpha and earlier) keep
+date-only badges — the hash requirement applies from this rule onward.
+
+### ARCH.md ↔ architecture page sync (REQUIRED)
+
+[`ARCH.md`](ARCH.md) is the repo's design manifesto (why the verifier is the
+authority, how the proof loop works, where the human review sits). The docs
+site publishes it as an Overview page,
+[`src/documentation/architecture.html`](src/documentation/architecture.html) —
+a **generated** render of ARCH.md via `src/architecture_tpl.html`
+(`scripts/lib/arch-page.ts`, regenerated by `build.ts`, mirrored to the docs
+site like every other page).
+
+- **When you edit ARCH.md, run `bun run build` in the same commit** — the page
+  is rebuilt from it. `verify`'s `architecture ↔ ARCH.md` gate fails when the
+  two diverge, exactly like the SKILL.md index.
+- **Never hand-edit `architecture.html`** (or its `dist/` / `docs/` copies):
+  like all generated files it is deleted and rebuilt; the generator would
+  silently revert your edit, and the gate would fail anyway.
+
 ### Native web platform first
 
 Every component starts from a native HTML element or browser API. If the browser
@@ -344,6 +438,23 @@ contract grows; never re-declare the globals inside a component file.
 Legacy components in its `STATE_API_LEGACY` list warn only until migrated —
 remove a name from the list in the same commit that migrates the component.
 
+### Theme radius consistency (REQUIRED)
+
+A theme is **one identity, two palettes** — light and dark are the same
+theme, so its shape (`radius`) must be **identical in both modes**. If Doom64
+is hard-square in dark mode it is hard-square in light mode; if ChatGPT is
+pill-round in dark, light is pill-round too. A theme that only declares
+`radius` in one mode silently reverts the other to the default rounding, so
+toggling dark mode "changes the theme's shape" — reported (Doom64, Retro
+Arcade) and now gated.
+
+- In `src/documentation/js/themes.ts`, declare `radius` in **both** the
+  `light` and `dark` block of every theme, with the same value.
+- `verify`'s `theme radius consistency` gate fails the build otherwise.
+- Same principle for **contrast**: every theme's sidebar text pairs must
+  reach WCAG AA (≥ 4.5) in *both* modes — see the `theme sidebar contrast`
+  gate. Re-tune one mode's color and you own both.
+
 ### Tokens are the source of truth for design values
 
 `dist/theme/default-semantic-tokens.css` defines all CSS custom properties. These must match
@@ -547,8 +658,29 @@ status of newer APIs (`popover`, anchor positioning, `@starting-style`, etc.).
 Component skills document **how to build the HTML** for a component. CSS and JS live in
 their own files alongside the skill — edit `.css` and `.js` directly.
 
+Every component skill **must open with a YAML frontmatter block** — it is the machine-readable
+discovery layer `dist/SKILL.md` (the agent entry point) is generated from. `verify`'s
+`skill frontmatter` gate fails without it, and `SKILL.md ↔ skills` fails when the generated
+index lags (rebuild with `bun run build`):
+
+```markdown
+---
+name: Dialog
+why: Native <dialog> + showModal(): focus trap, Escape, ::backdrop, and inert background are browser-provided.
+when: Modals for forms, detail views, or previews — unless the answer is mandatory (then alert-dialog).
+where: dist/components/dialog/dialog.css + dist/components/dialog/dialog.js
+supportedStates: default, open
+---
+```
+
+- **name** — display name (Title Case) · **why** — what its native basis buys · **when** — which
+  use it for, and when to pick a sibling instead · **where** — the shipped files
+  (`dist/components/{name}/{name}.css` + `.js` if interactive) · **supportedStates** — the exact
+  State API names (matches `{name}States`, `default` first; CSS-only components: `default`).
+
 Every component skill must include these sections in order:
 
+0. **Frontmatter** — `name` / `why` / `when` / `where` / `supportedStates` (see above — REQUIRED)
 1. **Native basis** — which HTML element/API it builds on
 2. **Native Web APIs** — bulleted list of significant platform APIs with MDN links (see format below)
 3. **Structure** — complete HTML markup with all attributes
@@ -843,6 +975,7 @@ The sidebar is ordered by dependency (primitives first):
 8. Overlays (Popover, Tooltip, Context Menu, Dialog, Sheet, Accordion, Command)
 9. Navigation (Breadcrumb, Pagination, Steps, Tabs, Dropdown Menu, Navigation Menu)
 10. Application (Sidebar)
+11. Marketing (Site Header, Hero, Product Showcase, Brand Logos, Feature Details, Testimonials, Stats, Pricing, Blog, FAQ, Get In Touch, Newsletter, Site Footer) — CSS-only page sections composed from the same tokens + primitives
 
 To reorder, edit the `NAV` array in `layout.js`.
 

package/ARCH.md

@@ -1,13 +1,13 @@
-# ARCH — How this framework scales without a human reviewer
+# ARCH — How this framework scales with AI
 
-defuss-shadcn is built for an era where **coding agents do the work**. The
+`defuss-shadcn` is built for an era where **coding agents do the work**. The
 scaling bottleneck is no longer writing components — it is *trusting* them.
 This repo solves trust with a closed loop: every artifact an agent produces
 passes through mechanical quality gates designed by a human senior software engineer, and the gates talk back to the AI agent in the form of executable instructions. An agent can reach "done" only by satisfying every gate; the goal is unreachable any other way.
 
-The method has four parts.
+The method has five parts.
 
-## 1. AGENTS.md — the philosophy layer
+## 1. AGENTS.md — the philosophy/instruction layer
 
 [`AGENTS.md`](AGENTS.md) tells a coding agent **how to work, what to
 implement where, and why**: the native-web-platform-first rules (`<dialog>`,
@@ -18,14 +18,17 @@ model reads before and while it works. Prose, however, is advisory: an agent
 can misread it, skip it, or claim compliance. That is exactly what the next
 layer is for.
 
-## 2. The verifier — the authority layer
+## 2. The deterministic verifier — an authority layer
 
 [`scripts/verify.ts`](scripts/verify.ts) is a custom, code-implemented audit
-of everything prose cannot guarantee: **34 check groups** over the shipped
-tree — skills exist, doc pages exist, tokens are tweakcn-compatible, snippets
-match source, dist is a 1:1 build of src, every declared state has a
-screenshot/skill/doc/e2e artifact, cross-page imports are complete, links
-resolve, paths are portable, the working tree is committed, and more. Each
+of everything prose cannot guarantee: **41 check groups** over the shipped
+tree — skills exist (with discovery frontmatter), doc pages exist, tokens are
+tweakcn-compatible, snippets match source, dist is a 1:1 build of src, every
+declared state has a screenshot/skill/doc/e2e artifact, cross-page imports are
+complete, links resolve, paths are portable, the working tree is committed, the
+committed version has a changelog entry carrying its commit hash (AGENTS.md
+"Changelog"), the generated dist/SKILL.md agent index matches the skills,
+and more. Each
 check reads the *actual* files and computes the truth; nothing is taken on
 word.
 
@@ -65,7 +68,7 @@ to ignore it. The two files are one system: prose explains the *why*, the
 verifier enforces the *what*, and prose points at the verifier as the final
 word (`bun run verify` is the single "am I done?" question).
 
-## 4. The surrounding gates — verification is not enough by itself
+## 4. The surrounding gates — suppressing hallucination, AI slop and overstating claims
 
 The verifier checks *consistency*. The loop wraps it with gates that check
 *behavior, quality, and appearance*:
@@ -75,7 +78,7 @@ The verifier checks *consistency*. The loop wraps it with gates that check
 | Lint | oxlint (`bun run lint`) | src/, tests/, scripts/ stay warning-clean |
 | Type-check | strict `tsc --noEmit` | tests/ and scripts/ compile |
 | Unit/integration | Vitest browser mode (`bun run test:run`) | real doc pages in a real Chromium iframe behave |
-| E2E | 55 standalone Playwright scripts (`bun run e2e`) | every component's documented surface — interactions, keyboard, computed CSS |
+| E2E | 56 standalone Playwright scripts (`bun run e2e`) | every component's documented surface — interactions, keyboard, computed CSS — plus the doc site itself (renders, SPA nav, search) |
 | Screenshots | `bun run screenshots` | every declared **state × light/dark** PNG exists, is fresh vs. its input fingerprint, and the render manifest hash-detects drift |
 | Git hygiene | verify check #23 | every verified byte is committed — what CI/other agents see is exactly what passed |
 
@@ -105,7 +108,7 @@ flowchart TD
     B --> C["make build"]
     subgraph GATES["mechanical quality gates (no human in the loop)"]
         direction LR
-        L["oxlint<br/>typecheck"] --> P["compile src → dist<br/>1:1 build"] --> SS["screenshots<br/>every state × light/dark<br/>fingerprint-fresh"] --> V["verify.ts<br/>34 consistency gates<br/>incl. 'working tree committed'"] --> Q["Vitest UI tests<br/>55 Playwright e2e"]
+        L["oxlint<br/>typecheck"] --> P["compile src → dist<br/>1:1 build"] --> SS["screenshots<br/>every state × light/dark<br/>fingerprint-fresh"] --> V["verify.ts<br/>41 consistency gates<br/>incl. 'working tree committed'"] --> Q["Vitest UI tests<br/>56 Playwright e2e"]
     end
     C --> GATES
 
@@ -128,3 +131,19 @@ the loop until the work is actually good* — which is precisely the point:
 human review does not scale to an army of agents, but a verifier that
 audits every byte, speaks repair instructions, and is the only door out
 does.
+
+## 5. Human expert final review before release
+
+The human expert only reviews the code, documentation and visual representation after all quality gates have passed and the visual evidence has been captured - right before a new version is released.
+
+Should the human expert find any issues during this final review, the feedback is fed back into the loop, and the agents must address it before a new version can be released. If a regression or a new "unknown unknown" fail case is discovered, the human expert will either instruct the agent to add this to the AGENTS.md or let the agent implement yet another verifier logic to add a new static and deterministic quality gate, preventing the same issue from slipping through in future iterations.
+
+As for the Agent Harness, this method has a huge advantage compared to more automated or harness-native solutions:
+
+1. It doesn't matter what VLM model is used. As long as the model is capable enough, it can handle the task including multimodal reasoning and visual inspection of the screenshots.
+
+2. AGENTS.md and the verifier logic are decoupled from the specific VLM model. This means that improvements or changes to the VLM model do not require modifications to the agent's instructions or the verifier, ensuring long-term maintainability and flexibility.
+
+3. The human still has oversight over both the development process (and thus can intercept in case of errors or unexpected behavior) and the release process, ensuring that the quality gates are meaningful, implemented changes are safe and correct, and that the released version meets all of the desired standards, set by the human expert.
+
+4. Spec-driven development is absolutely possible by simply creating plans or bug reports in the ./issues folder - decoupling the agentic engineering process from any 3rd party project management tool, while still maintaining a clear and structured workflow for the agents to follow - even in case the harness fails right in the middle of an  implementation loop.

package/README.md

@@ -4,17 +4,25 @@
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![No dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 ![HTML CSS JS](https://img.shields.io/badge/stack-HTML%20·%20CSS%20·%20JS-orange)
+[![npm version](https://img.shields.io/npm/v/defuss-shadcn.svg?logo=npm)](https://www.npmjs.com/package/defuss-shadcn)
+[![npm downloads](https://img.shields.io/npm/dm/defuss-shadcn.svg)](https://www.npmjs.com/package/defuss-shadcn)
+[![TypeScript definitions](https://img.shields.io/npm/types/defuss-shadcn.svg)](https://www.npmjs.com/package/defuss-shadcn)
+[![Socket Badge](https://badge.socket.dev/npm/package/defuss-shadcn/latest)](https://socket.dev/npm/package/defuss-shadcn)
 
 **A UI component system that scales with AI.** Themeable components built on semantic HTML, modern CSS, and vanilla JavaScript. No framework. No build step for consumers — `dist/` is committed and ready to use as-is. The simplest possible foundation for AI-driven prototyping.
 
-**[Documentation & Live Demos →](https://kyr0.github.io/defuss-shadcn/documentation/)**
+41 of 68 components need no JavaScript — native HTML and modern CSS cover them entirely.
+
+The set includes 13 marketing blocks (Site Header, Hero, Pricing, Testimonials, Blog, Footer, …) — full-page sections composed from the same tokens and primitives, all CSS-only.
+
+**[Documentation & Live Demos →](https://kyr0.github.io/defuss-shadcn/)** · [Architecture (ARCH.md)](ARCH.md) · [Agent integration guide (dist/SKILL.md)](dist/SKILL.md)
 
 ## What this is
 
 A portable UI component system built on the [shadcn/ui](https://ui.shadcn.com) token model.
 
 - **Themeable** — full shadcn semantic token model. Swap a [tweakcn](https://tweakcn.com) theme and every component updates instantly
-- **Component Skills** — every component includes a structured skill — markup, variants, ARIA, and wiring conventions — grounded in web standards
+- **Component Skills** — every component includes a structured skill — markup, variants, named states, ARIA, and wiring conventions — grounded in web standards
 - **Observable state** — interactive components expose a State API (`el.api.setState('open')`, `el.api.getState()`), so agents and tests can drive every documented state by name without knowing the implementation
 - **Accessible** — built on native HTML elements and WAI-ARIA patterns. Keyboard navigation, focus management, and screen reader support by default
 - **Framework Free** — runs in any browser, zero dependencies, no build pipeline required
@@ -39,7 +47,7 @@ A portable UI component system built on the [shadcn/ui](https://ui.shadcn.com) t
 
 ### Self-hosting
 
-Download the full system and drop it into any project. All the files are static — no build step, no dependencies. Point an AI at the folder and it has everything it needs: component skills to read, CSS to include, JS to wire up, and the entire documentation site with working examples of every component.
+Download the full system and drop it into any project. All the files are static — no build step, no dependencies. Point an AI at `dist/SKILL.md` and it has everything it needs: the library's integration guide and philosophy, an index of every component skill (why/when/where + supported states), CSS to include, JS to wire up, and the entire documentation site with working examples of every component.
 
 **[Download latest (.zip)](https://github.com/kyr0/defuss-shadcn/archive/refs/heads/main.zip)**
 
@@ -73,7 +81,7 @@ Tokens are compatible with [tweakcn.com](https://tweakcn.com) theme exports. To
 
 ## Components
 
-See the **[full component list with live demos →](https://kyr0.github.io/defuss-shadcn/documentation/)**
+See the **[full component list with live demos →](https://kyr0.github.io/defuss-shadcn/)**
 
 ## Design principles
 
@@ -132,8 +140,11 @@ bun run test:run   # run the UI test suite (headless Chromium)
 ```
 
 `src/` is the authoring tree (`.ts` + html/css/md/fonts); `dist/` is its compiled, 1:1
-mirror, committed and the only thing that ships. `docs/` is a generated 1:1 mirror of
-`dist/` that GitHub Pages publishes — refresh with `bun run docs`, never edit it directly.
+mirror, committed and the only thing that ships. `docs/` is the generated **documentation
+site** (only `dist/documentation/` + the SEO files) that GitHub Pages publishes — the
+pages' `../components/…` / `../theme/…` references are rewritten to the jsDelivr GitHub
+CDN by the mirror ([scripts/lib/mirror.ts](scripts/lib/mirror.ts)), so docs/ carries no
+copies of the component assets. Refresh with `bun run docs`, never edit it directly.
 
 A `Makefile` wraps the common tasks: `make setup` (install deps + Playwright browsers),
 `make dev`, `make test-run`, `make coverage`, `make e2e`, `make lint` (oxlint),
@@ -145,7 +156,7 @@ the same loop CI runs.
 of every build) and the contract every coding agent must satisfy. It checks, among others:
 
 - **structure** — component skills, doc pages, CSS/JS imports on every page, sidebar links,
-  `.preview` blocks, `dist/` freshness (1:1 with `src/`), `docs/` mirror byte-identical
+  `.preview` blocks, `dist/` freshness (1:1 with `src/`), `docs/` mirror current (CDN-rewritten)
 - **consistency** — inline source snippets match the real files (and are properly escaped),
   skill ↔ docs ↔ CSS variant parity, State API contract + per-state coverage across
   screenshots/docs/skill/e2e, changelog & version markers, doc command references
@@ -153,7 +164,8 @@ of every build) and the contract every coding agent must satisfy. It checks, amo
 - **quality** — token boundary rule (only tweakcn-defined `var(--*)`), undefined utility
   classes, `prefers-reduced-motion` coverage, init idempotency (double-binding guard),
   dead links (parsed with linkedom), portable paths (no machine-absolute paths),
-  strict typecheck, render drift (screenshot pixels changed without input changes)
+  strict typecheck, render drift (screenshot pixels changed without input changes),
+  theme sidebar contrast (every preset's nav text reaches WCAG AA on its real background)
 - **hygiene** — working tree committed, so a green build is a committed build
 
 Every failing check prints the offending files **and the exact fix** — the verifier is
@@ -182,9 +194,10 @@ fixture page using the component in **all** of its documented configurations (ev
 variant, size, and State API state), driven by plain Playwright against the unmodified
 files in `dist/` (`bun run e2e`). This is the verification loop a coding agent runs
 after touching any component — the shipped files themselves are asserted, so "it
-compiles" is never mistaken for "it works". The rollout is in progress (`verify` lists
-the components still missing one) and its parity rule keeps fixture, docs and code in
-lockstep as they land.
+compiles" is never mistaken for "it works". Every component ships one (the gate is
+hard), and its parity rule keeps fixture, docs and code in lockstep as they change.
+The documentation site itself is covered too ([`tests/e2e/documentation.e2e.ts`](tests/e2e/documentation.e2e.ts)):
+the intro page renders, the SPA router navigates, and the header search opens the command palette (generated index, page + section results).
 
 ## Credits
 

package/bun.lock

@@ -12,6 +12,7 @@
         "linkedom": "^0.18.13",
         "oxlint": "^1.81.0",
         "playwright": "^1.63.0",
+        "simple-icons": "^16.30.0",
         "typescript": "^7.0.2",
         "vite": "^8.2.2",
         "vitest": "^5.0.0",
@@ -289,6 +290,8 @@
 
     "siginfo": ["siginfo@2.0.0", "", {}, "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g=="],
 
+    "simple-icons": ["simple-icons@16.30.0", "", {}, "sha512-YX/HmgEqjpn5Zs3myzKp8ek5Ti+TdrkvNWn9skGLetg9tOg0cTjYizj9ESAYJn4xwc0GQYVGzQxBELDfbxq7WQ=="],
+
     "sirv": ["sirv@3.0.2", "", { "dependencies": { "@polka/url": "^1.0.0-next.24", "mrmime": "^2.0.0", "totalist": "^3.0.0" } }, "sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g=="],
 
     "source-map-js": ["source-map-js@1.2.1", "", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],