defuss-shadcn 0.7.19 → 0.8.1

package/AGENTS.md

@@ -171,6 +171,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 +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,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/README.md

@@ -11,7 +11,9 @@
 
 **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.
 
-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)
 

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

@@ -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/architecture_tpl.html

@@ -0,0 +1,154 @@
+<!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">
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/15.0.7/marked.min.js" defer integrity="sha384-H+hy9ULve6xfxRkWIh/YOtvDdpXgV2fmAGQkIDTxIgZwNoaoBal14Di2YTMR6MzR" crossorigin="anonymous"></script>
+  <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/blog/blog.css

@@ -0,0 +1,122 @@
+/* -- Blog (marketing) ----------------------------------------------
+   Insights grid: media card with category/read-time meta, line-clamped
+   excerpt, and author row composed from the avatar component. */
+
+@layer components {
+  .mk-blog {
+    container: mk-blog / inline-size;
+    display: flex;
+    flex-direction: column;
+    gap: 3rem;
+    width: 100%;
+    max-width: 80rem;
+    margin-inline: auto;
+    padding-inline: 1.25rem;
+  }
+
+  .mk-blog-head { display: flex; gap: 1.25rem; align-items: flex-start; }
+
+  .mk-blog-head-copy {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 0.75rem;
+    width: 100%;
+    max-width: 48rem;
+    text-align: left;
+  }
+
+  .mk-blog-eyebrow { color: var(--primary); font-size: 1rem; font-weight: 500; }
+
+  .mk-blog-title {
+    margin: 0;
+    font-size: 1.875rem;
+    font-weight: 500;
+    letter-spacing: -0.025em;
+    text-wrap: balance;
+  }
+
+  .mk-blog-desc { margin: 0; max-width: 42rem; color: var(--muted-foreground); font-size: 1rem; text-wrap: pretty; }
+
+  .mk-blog-see-all { display: none; margin-inline-start: auto; align-self: flex-end; flex-shrink: 0; }
+
+  .mk-blog-grid { display: grid; gap: 1.25rem; width: 100%; }
+
+  .mk-blog-card { display: flex; flex-direction: column; color: inherit; text-decoration: none; }
+
+  .mk-blog-media {
+    position: relative;
+    aspect-ratio: 3 / 2;
+    width: 100%;
+    margin: 0;
+    overflow: hidden;
+    border-radius: var(--radius-lg);
+    background: var(--muted);
+
+    & img {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      display: block;
+      transition: opacity 150ms ease;
+    }
+  }
+
+  .mk-blog-card:hover .mk-blog-media img { opacity: 0.9; }
+
+  .mk-blog-body { display: flex; flex: 1; flex-direction: column; gap: 0.75rem; padding-block: 0.875rem; }
+
+  .mk-blog-meta { display: flex; align-items: center; justify-content: space-between; gap: 0.75rem; }
+
+  .mk-blog-category { color: var(--primary); font-size: 0.875rem; font-weight: 500; }
+
+  .mk-blog-read { color: var(--muted-foreground); font-size: 0.875rem; }
+
+  .mk-blog-copy { display: grid; gap: 0.25rem; }
+
+  .mk-blog-card-title {
+    margin: 0;
+    font-size: 1.125rem;
+    font-weight: 500;
+    letter-spacing: -0.025em;
+    text-wrap: balance;
+  }
+
+  /* excerpt clamp: exactly 3 lines (source: line-clamp-3) */
+  .mk-blog-excerpt {
+    margin: 0;
+    color: var(--muted-foreground);
+    font-size: 0.875rem;
+    text-wrap: pretty;
+    display: -webkit-box;
+    -webkit-line-clamp: 3;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  .mk-blog-author { display: flex; align-items: center; gap: 0.5rem; margin-block-start: auto; }
+
+  .mk-blog-author-name { font-size: 0.875rem; font-weight: 500; }
+
+  .mk-blog-author-date { color: var(--muted-foreground); font-size: 0.75rem; }
+
+  @container mk-blog (min-width: 30rem) {
+    .mk-blog-grid { grid-template-columns: 1fr 1fr; }
+  }
+
+  @container mk-blog (min-width: 52rem) {
+    .mk-blog-title { font-size: 2.25rem; }
+    .mk-blog-see-all { display: inline-flex; }
+    .mk-blog-grid { grid-template-columns: repeat(3, 1fr); gap: 2.25rem; }
+  }
+
+  /* -- Accessibility ------------------------------------------- */
+  @media (prefers-reduced-motion: reduce) {
+    .mk-blog-media img { transition: none; }
+  }
+
+  @media (forced-colors: active) {
+    .mk-blog-card { color: LinkText; }
+  }
+}

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

@@ -0,0 +1,85 @@
+---
+name: 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.
+where: dist/components/blog/blog.css
+supportedStates: default
+---
+
+# Pattern: Blog
+
+## Native basis
+The whole card is a single `<a>` wrapping the preview — one tab stop,
+one click target. Excerpt clamping uses `-webkit-line-clamp` (shipped
+everywhere), media uses `aspect-ratio`; authors compose the
+[Avatar](../avatar/component-skill.md) component.
+
+---
+
+## Native Web APIs
+- [`line-clamp`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-line-clamp) — 3-line excerpt cut with ellipsis
+- [`aspect-ratio`](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) — 3:2 preview frames
+- [Avatar](../avatar/component-skill.md) — author identity row
+- [Container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries) — 1 → 2 → 3 columns
+
+---
+
+## Structure
+
+```html
+<section class="mk-blog">
+  <div class="mk-blog-head">
+    <div class="mk-blog-head-copy">
+      <span class="mk-blog-eyebrow">Blog</span>
+      <h2 class="mk-blog-title">Acme Inc. Insights</h2>
+      <p class="mk-blog-desc">Tips to work smarter and finish faster.</p>
+    </div>
+    <a href="#" class="btn mk-blog-see-all" data-variant="secondary">See all</a>
+  </div>
+  <div class="mk-blog-grid">
+    <a href="#" class="mk-blog-card">
+      <figure class="mk-blog-media">
+        <img src="images/mk-wide.png" alt="Team in flow at a whiteboard" />
+      </figure>
+      <div class="mk-blog-body">
+        <div class="mk-blog-meta">
+          <span class="mk-blog-category">Productivity</span>
+          <span class="mk-blog-read">8 min read</span>
+        </div>
+        <div class="mk-blog-copy">
+          <h3 class="mk-blog-card-title">5 Ways AI Helps Teams Stay in Flow</h3>
+          <p class="mk-blog-excerpt">Simple ways to cut distractions and keep your team focused.</p>
+        </div>
+        <div class="mk-blog-author">
+          <span class="avatar" data-size="sm">
+            <img class="avatar-image" src="images/mk-portrait.png" alt="" />
+          </span>
+          <div class="flex flex-col">
+            <span class="mk-blog-author-name">Sophie Tan</span>
+            <time class="mk-blog-author-date" datetime="2025-09-04">4 Sept, 2025</time>
+          </div>
+        </div>
+      </div>
+    </a>
+  </div>
+</section>
+```
+
+The author avatar is decorative next to the visible name → `alt=""` on the author image.
+
+---
+
+## ARIA
+
+| Attribute   | Element          | Purpose                                |
+|-------------|------------------|----------------------------------------|
+| `<time>`    | date             | Machine-readable date, human format    |
+| `alt=""`    | author photo     | Redundant beside the name text         |
+| one `<h3>`  | card title       | Headings stay navigable across cards   |
+
+---
+
+## Notes
+- Card links need distinct accessible names — the `<h3>` title provides it; don't duplicate the title in `alt` AND `aria-label`.
+- "See all" sits `margin-inline-start: auto` and only shows ≥ 48rem container width (source's `hidden lg:flex`).
+- Hover only dims the image (`opacity .9`) — never transform-lift whole cards; motion-sensitive users get none of it under reduced-motion.