defuss-shadcn 0.7.19 → 0.8.2

package/AGENTS.md

@@ -17,12 +17,18 @@ 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: **only the documentation site** (`dist/documentation/*` +
-`robots.txt`/`sitemap.xml`) published by GitHub Pages — its pages' `../components/…` and
+`robots.txt`/`sitemap.xml` + a `404.html` copy of `index.html` so GitHub Pages never
+serves an empty page for dead links) 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`.
+Because the docs pages load their assets from jsDelivr `@latest` (newest git tag),
+a fresh release keeps serving the **previous** release's CSS/JS until jsDelivr's
+cache expires (12h edge, 7d browser). After `bun run deploy`, run
+`bun run purge-cdn` (`make purge-cdn`) to force `@latest` to re-resolve to the
+new tag immediately.
 Never edit `dist/` directly; it is deleted and rebuilt on every build.
 
 ---
@@ -45,7 +51,7 @@ defuss-shadcn/
 │       ├── css/docs-theme.css         ← doc-site font overrides (not part of the system)
 │       ├── css/layout.css             ← doc-site layout (not part of the system)
 │       ├── js/layout.js               ← SPA router, <site-header>/<site-nav> web components
-│       ├── js/site.js                 ← doc-site-only JS (tabs, copy buttons, skill modal, code collapse)
+│       ├── js/site.js                 ← doc-site-only JS (tabs, copy buttons, code collapse)
 │       ├── js/shiki-highlight.js      ← Shiki-based syntax highlighting (ES module, CDN)
 │       ├── js/themes.js               ← tweakcn color theme presets (global THEMES array)
 │       └── js/theme-switcher.js       ← applies theme overrides to CSS custom properties
@@ -73,7 +79,8 @@ defuss-shadcn/
 │   ├── sync-css-snippets.ts           ← re-embed component CSS into doc pages after edits
 │   ├── sync-js-snippets.ts            ← re-embed component JS into doc pages after edits
 │   ├── push.sh                        ← commit + push dev → main (non-release)
-│   └── deploy.sh                      ← release: version bump, changelog, tag, GitHub release
+│   ├── deploy.sh                      ← release: version bump, changelog, tag, GitHub release
+│   └── purge-cdn.ts                   ← purge jsDelivr @latest cache for all dist assets (run after deploy)
 ├── tests/                             ← UI tests (Vitest browser mode + Playwright)
 │   ├── helpers.ts                     ← loads real doc pages in a same-origin iframe
 │   ├── ui.test.ts                     ← end-to-end tests of the actual site UI
@@ -171,6 +178,23 @@ 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
@@ -958,6 +982,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,7 +18,7 @@ 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: **41 check groups** over the shipped
@@ -68,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*:
@@ -131,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/Makefile

@@ -2,7 +2,7 @@
 # KISS: every target delegates to package.json so there is one source of truth.
 
 .DEFAULT_GOAL := help
-.PHONY: help setup dev test test-run coverage e2e lint verify screenshots build docs
+.PHONY: help setup dev test test-run coverage e2e lint verify screenshots build docs purge-cdn
 
 help: ## Show available targets
 	@grep -E '^[a-zA-Z0-9_-]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
@@ -35,6 +35,9 @@ typecheck: ## Strict tsc type-check of tests/ and scripts/ (no emit)
 docs: ## Build, then mirror dist/ → docs/ for GitHub Pages
 	bun run docs
 
+purge-cdn: ## Purge jsDelivr @latest cache for all dist assets (run after deploy)
+	bun run purge-cdn
+
 # Full pipeline: fast checks first, compile, refresh screenshots (the verify
 # gate requires them fresh vs. the new dist/), then gate + tests. Calls
 # scripts/build.ts directly because `bun run build` would run verify BEFORE

package/README.md

@@ -9,9 +9,11 @@
 [![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.
+**A UI component system that scales with _local_ 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.
 
-29 of 55 components need no JavaScript — native HTML and modern CSS cover them entirely.
+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)
 
@@ -139,7 +141,8 @@ 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 the generated **documentation
-site** (only `dist/documentation/` + the SEO files) that GitHub Pages publishes — the
+site** (only `dist/documentation/` + the SEO files + a `404.html` copy of `index.html` so
+GitHub Pages never serves an empty page for dead links) 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.

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=="],

package/dist/SKILL.md

@@ -4,7 +4,7 @@
 
 # defuss-shadcn — Agent Skill
 
-**A UI component system that scales with AI.** Themeable components built on semantic HTML, modern CSS, and vanilla JavaScript. No framework, zero dependencies — `dist/` is committed and ready to use as-is. This file is the entry point for an AI agent integrating the library: read it once, then read only the component skills you need.
+**A UI component system that scales with _local_ AI.** Themeable components built on semantic HTML, modern CSS, and vanilla JavaScript. No framework, zero dependencies — `dist/` is committed and ready to use as-is. This file is the entry point for an AI agent integrating the library: read it once, then read only the component skills you need.
 
 ## Integrate
 
@@ -108,6 +108,24 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/badge.png
 **Skill:** [components/badge/component-skill.md](components/badge/component-skill.md)
 
+## Blog
+
+**Why:** Post cards are `<a>` + `<img>` + clamped text — line-clamp and aspect-ratio give the editorial layout for free.
+**When:** Insights/news teasers on a marketing page; the full article list is a table or card grid instead.
+**Files:** dist/components/blog/blog.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/blog.png
+**Skill:** [components/blog/component-skill.md](components/blog/component-skill.md)
+
+## Brand Logos
+
+**Why:** Logos as currentColor SVGs recolor with the theme automatically — a row of marks needs zero behavior.
+**When:** "Trusted by" social proof band under a Hero — not for user-uploaded arbitrary images.
+**Files:** dist/components/brand-logos/brand-logos.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/brand-logos.png
+**Skill:** [components/brand-logos/component-skill.md](components/brand-logos/component-skill.md)
+
 ## Breadcrumb
 
 **Why:** nav > ol markup with aria-current="page" — the accessibility comes free with the markup, not from JS.
@@ -243,6 +261,24 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/dropdown.png, screenshots/{light,dark}/dropdown-open.png
 **Skill:** [components/dropdown/component-skill.md](components/dropdown/component-skill.md)
 
+## FAQ
+
+**Why:** Icon-card answers stay visible — no disclosure widget to wire, so screen readers and crawlers see every answer.
+**When:** Support section on a marketing page; for many long Q&As use the Accordion (native <details>) instead.
+**Files:** dist/components/faq/faq.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/faq.png
+**Skill:** [components/faq/component-skill.md](components/faq/component-skill.md)
+
+## Feature Details
+
+**Why:** Two-image feature split with a rule between — a grid with an auto-stretched divider column, no JS.
+**When:** "Benefits" section of a marketing page; for a feature list without imagery use cards instead.
+**Files:** dist/components/feature-details/feature-details.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/feature-details.png
+**Skill:** [components/feature-details/component-skill.md](components/feature-details/component-skill.md)
+
 ## File Input
 
 **Why:** A <label> wrapping the native file input with styled drag-over and filled states.
@@ -261,6 +297,24 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/form.png
 **Skill:** [components/form/component-skill.md](components/form/component-skill.md)
 
+## Get In Touch
+
+**Why:** A bordered contact CTA card — avatar overlap is negative margins + outline, not positioning math.
+**When:** End-of-page "want to know more?" band; for an actual contact form use Form + Input components.
+**Files:** dist/components/get-in-touch/get-in-touch.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/get-in-touch.png
+**Skill:** [components/get-in-touch/component-skill.md](components/get-in-touch/component-skill.md)
+
+## Hero
+
+**Why:** Headline, description and CTAs in one centered copy block — native flow layout and container queries, nothing to script.
+**When:** First section of a marketing page; pair with the Product Showcase block when you need a video.
+**Files:** dist/components/hero/hero.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/hero.png
+**Skill:** [components/hero/component-skill.md](components/hero/component-skill.md)
+
 ## Icon
 
 **Why:** Consistent 24px stroke wrappers around lucide icons, sized via data-size.
@@ -306,6 +360,15 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/navigation-menu.png, screenshots/{light,dark}/navigation-menu-open.png
 **Skill:** [components/navigation-menu/component-skill.md](components/navigation-menu/component-skill.md)
 
+## Newsletter
+
+**Why:** A real <form> with <input type="email"> — native validation, keyboard, and autofill come free.
+**When:** Sign-up band on a marketing page; for multi-field sign-up use the Form component.
+**Files:** dist/components/newsletter/newsletter.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/newsletter.png
+**Skill:** [components/newsletter/component-skill.md](components/newsletter/component-skill.md)
+
 ## Number Input
 
 **Why:** Input plus stepper buttons bound to native min/max/step and arrow-key behavior.
@@ -333,6 +396,24 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/popover.png, screenshots/{light,dark}/popover-open.png
 **Skill:** [components/popover/component-skill.md](components/popover/component-skill.md)
 
+## Pricing
+
+**Why:** Plan cards are a stretch-aligned grid; the billing toggle is native radios plus :has(), so one checked input flips every plan with zero JS.
+**When:** Plans/tiers section of a marketing page; a single plan needs no grid — one card suffices.
+**Files:** dist/components/pricing/pricing.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/pricing.png
+**Skill:** [components/pricing/component-skill.md](components/pricing/component-skill.md)
+
+## Product Showcase
+
+**Why:** A poster frame + one real <button> starts a native <video controls> — the browser draws every playback affordance once the video is visible.
+**When:** Hero pairing or standalone product video; a static screenshot needs only the poster <img> (drop the video and button).
+**Files:** dist/components/product-showcase/product-showcase.css + dist/components/product-showcase/product-showcase.js
+**Supported states:** default, playing
+**Screenshots:** screenshots/{light,dark}/product-showcase.png, screenshots/{light,dark}/product-showcase-playing.png
+**Skill:** [components/product-showcase/component-skill.md](components/product-showcase/component-skill.md)
+
 ## Progress
 
 **Why:** Native <progress value max> — semantics and rendering come free.
@@ -396,6 +477,24 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/sidebar.png, screenshots/{light,dark}/sidebar-collapsed.png
 **Skill:** [components/sidebar/component-skill.md](components/sidebar/component-skill.md)
 
+## Site Footer
+
+**Why:** Link columns + social row is pure grid/flex markup in a <footer> landmark — no behavior to script.
+**When:** Bottom of marketing pages; the doc site's own footer is separate chrome (<footer> in layout.js).
+**Files:** dist/components/site-footer/site-footer.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/site-footer.png
+**Skill:** [components/site-footer/component-skill.md](components/site-footer/component-skill.md)
+
+## Site Header
+
+**Why:** A marketing page header is pure layout — flexbox + a container query replace any JS show/hide of the nav.
+**When:** Top of a marketing/landing page — for the doc site's own chrome use <site-header> instead.
+**Files:** dist/components/site-header/site-header.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/site-header.png
+**Skill:** [components/site-header/component-skill.md](components/site-header/component-skill.md)
+
 ## Skeleton
 
 **Why:** Shimmering placeholder blocks shaped like the content that will arrive.
@@ -441,6 +540,15 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/statistic.png
 **Skill:** [components/statistic/component-skill.md](components/statistic/component-skill.md)
 
+## Stats
+
+**Why:** Metric band = a grid of rule-led numbers; text alignment and tabular-nums do what a chart library would.
+**When:** "Trusted by teams everywhere" social proof with hard numbers; not a data dashboard.
+**Files:** dist/components/stats/stats.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/stats.png
+**Skill:** [components/stats/component-skill.md](components/stats/component-skill.md)
+
 ## Steps
 
 **Why:** Ordered list of process steps with aria-current="step" on the active one.
@@ -477,6 +585,15 @@ In the **source repository** additionally: `screenshots/{light,dark}/{name}.png`
 **Screenshots:** screenshots/{light,dark}/tabs.png, screenshots/{light,dark}/tabs-active.png
 **Skill:** [components/tabs/component-skill.md](components/tabs/component-skill.md)
 
+## Testimonials
+
+**Why:** A pull-quote plus photo cards with floating review overlays — backdrop-filter and stacking replace any JS layering.
+**When:** Social-proof band on a marketing page; for short quotes without photos a plain blockquote is enough.
+**Files:** dist/components/testimonials/testimonials.css
+**Supported states:** default
+**Screenshots:** screenshots/{light,dark}/testimonials.png
+**Skill:** [components/testimonials/component-skill.md](components/testimonials/component-skill.md)
+
 ## Textarea
 
 **Why:** Native textarea with field-sizing: content — auto-grows with zero JavaScript.

package/dist/SKILL_tpl.md

@@ -4,7 +4,7 @@
 
 # defuss-shadcn — Agent Skill
 
-**A UI component system that scales with AI.** Themeable components built on semantic HTML, modern CSS, and vanilla JavaScript. No framework, zero dependencies — `dist/` is committed and ready to use as-is. This file is the entry point for an AI agent integrating the library: read it once, then read only the component skills you need.
+**A UI component system that scales with _local_ AI.** Themeable components built on semantic HTML, modern CSS, and vanilla JavaScript. No framework, zero dependencies — `dist/` is committed and ready to use as-is. This file is the entry point for an AI agent integrating the library: read it once, then read only the component skills you need.
 
 ## Integrate
 

package/dist/architecture_tpl.html

@@ -0,0 +1,153 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <link rel="icon" href="images/favicon.webp" type="image/webp">
+  <meta name="description" content="How defuss-shadcn scales with AI: AGENTS.md teaches, a deterministic verifier enforces, screenshots prove, humans review before release.">
+  <meta property="og:title" content="Architecture — defuss-shadcn">
+  <meta property="og:description" content="How defuss-shadcn scales with AI: AGENTS.md teaches, a deterministic verifier enforces, screenshots prove, humans review before release.">
+  <meta property="og:type" content="website">
+  <meta property="og:url" content="https://kyr0.github.io/defuss-shadcn/documentation/architecture.html">
+  <meta property="og:site_name" content="defuss-shadcn">
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="Architecture — defuss-shadcn">
+  <meta name="twitter:description" content="How defuss-shadcn scales with AI: AGENTS.md teaches, a deterministic verifier enforces, screenshots prove, humans review before release.">
+  <title>Architecture — defuss-shadcn</title>
+  <script src="js/themes.js"></script>
+  <script src="js/theme-switcher.js"></script>
+  <script src="js/layout.js"></script>
+  <script src="js/search-index.js"></script>
+  <link rel="stylesheet" href="../theme/default-semantic-tokens.css">
+  <link rel="stylesheet" href="css/docs-theme.css">
+  <link rel="stylesheet" href="css/docs-utilities.css">
+  <link rel="stylesheet" href="css/layout.css">
+    <link rel="stylesheet" href="../components/button/button.css">
+  <link rel="stylesheet" href="../components/card/card.css">
+  <link rel="stylesheet" href="../components/dialog/dialog.css">
+  <link rel="stylesheet" href="../components/badge/badge.css">
+  <link rel="stylesheet" href="../components/input/input.css">
+  <link rel="stylesheet" href="../components/accordion/accordion.css">
+  <link rel="stylesheet" href="../components/tabs/tabs.css">
+  <link rel="stylesheet" href="../components/dropdown/dropdown.css">
+  <link rel="stylesheet" href="../components/toast/toast.css">
+  <link rel="stylesheet" href="../components/combobox/combobox.css">
+  <link rel="stylesheet" href="../components/sheet/sheet.css">
+  <link rel="stylesheet" href="../components/toggle/toggle.css">
+  <link rel="stylesheet" href="../components/icon/icon.css">
+  <link rel="stylesheet" href="../components/typography/typography.css">
+  <link rel="stylesheet" href="../components/separator/separator.css">
+  <link rel="stylesheet" href="../components/label/label.css">
+  <link rel="stylesheet" href="../components/toggle-group/toggle-group.css">
+  <link rel="stylesheet" href="../components/button-group/button-group.css">
+  <link rel="stylesheet" href="../components/toolbar/toolbar.css">
+  <link rel="stylesheet" href="../components/textarea/textarea.css">
+  <link rel="stylesheet" href="../components/checkbox/checkbox.css">
+  <link rel="stylesheet" href="../components/radio/radio.css">
+  <link rel="stylesheet" href="../components/switch/switch.css">
+  <link rel="stylesheet" href="../components/slider/slider.css">
+  <link rel="stylesheet" href="../components/select/select.css">
+  <link rel="stylesheet" href="../components/number-input/number-input.css">
+  <link rel="stylesheet" href="../components/file-input/file-input.css">
+  <link rel="stylesheet" href="../components/color-picker/color-picker.css">
+  <link rel="stylesheet" href="../components/date-picker/date-picker.css">
+  <link rel="stylesheet" href="../components/form/form.css">
+  <link rel="stylesheet" href="../components/avatar/avatar.css">
+  <link rel="stylesheet" href="../components/image/image.css">
+  <link rel="stylesheet" href="../components/statistic/statistic.css">
+  <link rel="stylesheet" href="../components/table/table.css">
+  <link rel="stylesheet" href="../components/collapsible/collapsible.css">
+  <link rel="stylesheet" href="../components/timeline/timeline.css">
+  <link rel="stylesheet" href="../components/tree-view/tree-view.css">
+  <link rel="stylesheet" href="../components/calendar/calendar.css">
+  <link rel="stylesheet" href="../components/spinner/spinner.css">
+  <link rel="stylesheet" href="../components/skeleton/skeleton.css">
+  <link rel="stylesheet" href="../components/progress/progress.css">
+  <link rel="stylesheet" href="../components/alert/alert.css">
+  <link rel="stylesheet" href="../components/alert-dialog/alert-dialog.css">
+  <link rel="stylesheet" href="../components/popover/popover.css">
+  <link rel="stylesheet" href="../components/tooltip/tooltip.css">
+  <link rel="stylesheet" href="../components/context-menu/context-menu.css">
+  <link rel="stylesheet" href="../components/command/command.css">
+  <link rel="stylesheet" href="../components/breadcrumb/breadcrumb.css">
+  <link rel="stylesheet" href="../components/pagination/pagination.css">
+  <link rel="stylesheet" href="../components/steps/steps.css">
+  <link rel="stylesheet" href="../components/navigation-menu/navigation-menu.css">
+  <link rel="stylesheet" href="../components/scroll-area/scroll-area.css">
+  <link rel="stylesheet" href="../components/carousel/carousel.css">
+  <link rel="stylesheet" href="../components/sidebar/sidebar.css">
+  <link rel="stylesheet" href="../components/sortable/sortable.css">
+  <link rel="stylesheet" href="../components/site-header/site-header.css">
+  <link rel="stylesheet" href="../components/hero/hero.css">
+  <link rel="stylesheet" href="../components/product-showcase/product-showcase.css">
+  <link rel="stylesheet" href="../components/brand-logos/brand-logos.css">
+  <link rel="stylesheet" href="../components/feature-details/feature-details.css">
+  <link rel="stylesheet" href="../components/testimonials/testimonials.css">
+  <link rel="stylesheet" href="../components/stats/stats.css">
+  <link rel="stylesheet" href="../components/pricing/pricing.css">
+  <link rel="stylesheet" href="../components/blog/blog.css">
+  <link rel="stylesheet" href="../components/faq/faq.css">
+  <link rel="stylesheet" href="../components/get-in-touch/get-in-touch.css">
+  <link rel="stylesheet" href="../components/newsletter/newsletter.css">
+  <link rel="stylesheet" href="../components/site-footer/site-footer.css">
+</head>
+<body>
+  <site-header></site-header>
+
+  <div class="flex" style="margin-top: 3.5rem; min-height: calc(100vh - 3.5rem);">
+    <site-nav></site-nav>
+
+    <main style="flex: 1; min-width: 0; max-width: 44rem; padding: 2rem 3.5rem 8rem;">
+      <div class="page-header">
+<p class="text-sm text-muted-foreground mb-3" style="font-family:var(--font-mono);">defuss-shadcn / architecture</p>
+  <h1 style="font-family:var(--font-display);font-size:2.5rem;font-weight:400;letter-spacing:-0.035em;margin:0 0 0.75rem;">Architecture</h1>
+  <p class="text-muted-foreground leading-relaxed mb-10" style="max-width:38rem;">
+    How defuss-shadcn scales with AI:
+    <a href="https://github.com/kyr0/defuss-shadcn/blob/main/AGENTS.md" style="color:var(--primary);text-decoration:underline;text-underline-offset:4px;">AGENTS.md</a>
+    teaches,
+    <a href="https://github.com/kyr0/defuss-shadcn/blob/main/scripts/verify.ts" style="color:var(--primary);text-decoration:underline;text-underline-offset:4px;">a deterministic verifier</a>
+    enforces, screenshots prove, and a human reviews before every release. This page is generated from
+    <a href="https://github.com/kyr0/defuss-shadcn/blob/main/ARCH.md" style="color:var(--primary);text-decoration:underline;text-underline-offset:4px;">ARCH.md</a>
+    on every build — a verify gate fails if the two ever diverge.
+  </p>
+      </div>
+
+<!-- ARCH_BODY -->
+
+    </main>
+  </div>
+
+  <script src="js/site.js" defer></script>
+  <script type="module" src="js/shiki-highlight.js"></script>
+  <script type="module" src="../components/accordion/accordion.js"></script>
+  <script type="module" src="../components/combobox/combobox.js"></script>
+  <script type="module" src="../components/dialog/dialog.js"></script>
+  <script type="module" src="../components/dropdown/dropdown.js"></script>
+  <script type="module" src="../components/sheet/sheet.js"></script>
+  <script type="module" src="../components/tabs/tabs.js"></script>
+  <script type="module" src="../components/toast/toast.js"></script>
+  <script type="module" src="../components/toggle/toggle.js"></script>
+  <script type="module" src="../components/toggle-group/toggle-group.js"></script>
+  <script type="module" src="../components/toolbar/toolbar.js"></script>
+  <script type="module" src="../components/number-input/number-input.js"></script>
+  <script type="module" src="../components/color-picker/color-picker.js"></script>
+  <script type="module" src="../components/avatar/avatar.js"></script>
+  <script type="module" src="../components/image/image.js"></script>
+  <script type="module" src="../components/tree-view/tree-view.js"></script>
+  <script type="module" src="../components/calendar/calendar.js"></script>
+  <script type="module" src="../components/alert-dialog/alert-dialog.js"></script>
+  <script type="module" src="../components/popover/popover.js"></script>
+  <script type="module" src="../components/tooltip/tooltip.js"></script>
+  <script type="module" src="../components/context-menu/context-menu.js"></script>
+  <script type="module" src="../components/command/command.js"></script>
+  <script type="module" src="../components/navigation-menu/navigation-menu.js"></script>
+  <script type="module" src="../components/sidebar/sidebar.js"></script>
+  <script type="module" src="../components/carousel/carousel.js"></script>
+  <script type="module" src="../components/slider/slider.js"></script>
+  <script type="module" src="../components/sortable/sortable.js"></script>
+  <script type="module" src="../components/product-showcase/product-showcase.js"></script>
+  <script src="https://unpkg.com/lucide@1.8.0" integrity="sha384-+8nbzwDAyu5kAjqtR/XKxIgPHQD2TflvbZgeDZn5t3JP+OOogNH1jXnfel8ZAgzS" crossorigin="anonymous"></script>
+  <script>globalThis.lucide?.createIcons();</script>
+</body>
+</html>

package/dist/components/accordion/accordion.css

@@ -11,20 +11,27 @@
 
     &:last-child { border-bottom: none; }
 
-    /* -- Content animation (CSS-only) ------------------------- */
-    & ::details-content {
+    /* -- Content animation (CSS-only) -------------------------
+       Two gotchas, both required for the panel to glide:
+       1. `::details-content` must attach to the compound (`&::details-content`,
+          NOT `& ::details-content` — the descendant form never matches, the
+          pseudo's originating element is the subject itself).
+       2. `block-size: auto` is a keyword — without interpolate-size the
+          0→auto pair is non-interpolable and the transition silently snaps. */
+    &::details-content {
       block-size: 0;
       overflow-y: clip;
+      interpolate-size: allow-keywords;
       transition: block-size 200ms ease, content-visibility 200ms allow-discrete;
     }
 
-    &[open] ::details-content {
+    &[open]::details-content {
       block-size: auto;
     }
   }
 
   @starting-style {
-    .accordion-item[open] ::details-content {
+    .accordion-item[open]::details-content {
       block-size: 0;
     }
   }
@@ -76,7 +83,7 @@
    (REQUIRED for all components — AGENTS.md "Accessibility CSS"). */
 @media (prefers-reduced-motion: reduce) {
   @layer components {
-    .accordion-item ::details-content { transition: none; }
+    .accordion-item::details-content { transition: none; }
     .accordion-trigger { transition: none; }
   }
 }

package/dist/components/accordion/accordion.js

@@ -116,6 +116,18 @@ function init() {
             getState: () => accordionApi.getState(accordion),
         };
         items.forEach((item) => {
+            // Cancellable pre-event: closing the LAST open item of a non-collapsible
+            // single accordion is denied here, before the DOM changes. Reopening it
+            // in the `toggle` handler instead would visibly flicker close→open now
+            // that the ::details-content height transition animates.
+            item.addEventListener('beforetoggle', (e) => {
+                if (accordion._applying)
+                    return; // programmatic state change in progress
+                if (e.newState !== 'closed' || collapsible)
+                    return;
+                if (!Array.from(items).some((i) => i !== item && i.open))
+                    e.preventDefault();
+            });
             item.addEventListener('toggle', () => {
                 if (accordion._applying)
                     return; // programmatic state change in progress
@@ -126,6 +138,10 @@ function init() {
                     });
                 }
                 else if (!collapsible) {
+                    // fallback for browsers without beforetoggle (which the deny above
+                    // needs): reopen, accepting the flicker — better than losing the
+                    // single-open guarantee. Modern browsers never reach this branch
+                    // because a denied beforetoggle fires no toggle event at all.
                     const anyOpen = Array.from(items).some((i) => i.open);
                     if (!anyOpen)
                         item.open = true;

package/dist/components/accordion/component-skill.md

@@ -171,3 +171,4 @@ These are all browser-native — no JS needed.
 - Content height animation uses `::details-content` pseudo-element with `block-size` transition and `@starting-style` for the enter animation — fully CSS-only, no JS measurement needed
 - Set `data-type="single"` for accordion behavior (only one open); omit for disclosure list (any number open)
 - Set `data-collapsible` alongside `data-type="single"` to allow all items to be closed
+- A non-collapsible single accordion never closes its last open item: the attempt is denied in the cancellable `beforetoggle` event (`preventDefault()`), so the click is a silent no-op. Reopening in `toggle` instead would visibly flicker close-then-open

package/dist/components/alert-dialog/alert-dialog.css

@@ -50,6 +50,14 @@
     }
   }
 
+  /* -- Scroll lock ------------------------------------------- */
+  /* Page behind stays put while the alert is modal (see dialog.css):
+     `:modal` + overflow:hidden freezes the viewport at its current offset. */
+  html:has(dialog.alert-dialog:modal) {
+    overflow: hidden;
+    scrollbar-gutter: stable;
+  }
+
   .alert-dialog-content {
     padding: 1.5rem;
   }