defuss-shadcn 0.7.14 → 0.7.19

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,75 @@ 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.
+
 ### Native web platform first
 
 Every component starts from a native HTML element or browser API. If the browser
@@ -344,6 +421,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 +641,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

package/ARCH.md

@@ -21,11 +21,14 @@ layer is for.
 ## 2. The verifier — the 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.
 
@@ -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
 

package/README.md

@@ -4,17 +4,23 @@
 [![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/)**
+29 of 55 components need no JavaScript — native HTML and modern CSS cover them entirely.
+
+**[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 +45,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 +79,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 +138,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 +154,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 +162,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 +192,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