defuss-shadcn 0.8.1 → 0.8.3

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

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,7 +9,7 @@
 [![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.
 
 41 of 68 components need no JavaScript — native HTML and modern CSS cover them entirely.
 
@@ -141,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/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
 

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

@@ -23,8 +23,7 @@
   <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/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">

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;
   }

package/dist/components/alert-dialog/component-skill.md

@@ -62,3 +62,4 @@ The api is bound per dialog; the registry global is
 - No backdrop click dismiss — user must make an explicit choice
 - Escape key is disabled — user must use the action buttons
 - Focus is trapped inside the dialog via native `showModal()`
+- While the alert is modal, `html:has(dialog.alert-dialog:modal)` sets `overflow: hidden` + `scrollbar-gutter: stable` — the page behind cannot scroll and its position is preserved for when the alert closes (no JS scroll-lock).

package/dist/components/button-group/button-group.css

@@ -10,13 +10,17 @@
       margin-inline-start: -1px;
     }
 
-    /* Remove internal radii for connected appearance */
-    & > .btn:not(:first-child):not(:has(+ [role="separator"])) {
+    /* Remove internal radii for connected appearance. The orientation gate is
+       :where()-wrapped so these INLINE-corner rules only ever apply to
+       horizontal groups; ungated they also squared vertical buttons' corners
+       at a higher specificity than the vertical block below, leaving "Top"
+       with a rounded top-left but a square top-right (issue #13). */
+    &:where(:not([data-orientation="vertical"])) > .btn:not(:first-child):not(:has(+ [role="separator"])) {
       border-start-start-radius: 0;
       border-end-start-radius: 0;
     }
 
-    & > .btn:not(:last-child):not([role="separator"] + .btn) {
+    &:where(:not([data-orientation="vertical"])) > .btn:not(:last-child):not([role="separator"] + .btn) {
       border-start-end-radius: 0;
       border-end-end-radius: 0;
     }
@@ -61,26 +65,21 @@
         margin-top: -1px;
       }
 
+      /* Square exactly the BLOCK corners that touch a neighbour — a
+         non-first button squares its top edge, a non-last its bottom
+         edge; the base .btn radius keeps every outer corner rounded on
+         both sides. No per-corner "restore" overrides: the last block's
+         restores re-rounded a corner the previous block had just
+         squared, which (together with the ungated horizontal rules)
+         produced the asymmetric Top/Middle corners of issue #13. */
       & > .btn:not(:first-child) {
         border-start-start-radius: 0;
         border-start-end-radius: 0;
-        border-end-start-radius: var(--radius-md);
       }
 
       & > .btn:not(:last-child) {
         border-end-start-radius: 0;
         border-end-end-radius: 0;
-        border-start-end-radius: var(--radius-md);
-      }
-
-      & > .btn:first-child {
-        border-start-start-radius: var(--radius-md);
-        border-start-end-radius: var(--radius-md);
-      }
-
-      & > .btn:last-child {
-        border-end-start-radius: var(--radius-md);
-        border-end-end-radius: var(--radius-md);
       }
 
       & > [role="separator"] {

package/dist/components/collapsible/collapsible.css

@@ -4,19 +4,26 @@
     border-radius: var(--radius-lg);
     overflow: hidden;
 
-    & ::details-content {
+    /* 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 {
-    .collapsible[open] ::details-content {
+    .collapsible[open]::details-content {
       block-size: 0;
     }
   }
@@ -80,6 +87,7 @@
     .collapsible *::before,
     .collapsible *::after,
     .collapsible::backdrop,
+    .collapsible::details-content,
     .collapsible-chevron,
     .collapsible-chevron *,
     .collapsible-chevron::before,

package/dist/components/combobox/combobox.css

@@ -29,6 +29,39 @@
     opacity: 0.5;
   }
 
+  /* Clear button (injected by combobox.js after the trigger). Anchor-positioned
+     over the trigger's chevron slot; anchored via the same per-instance anchor
+     name the popover uses. `data-placeholder` presence is the single
+     selection marker — the :has() rules below flip chevron and clear in sync,
+     so no JS toggles visibility. */
+  .combobox-clear {
+    position: fixed;
+    inset: auto;
+    margin: 0;
+    top: anchor(top);
+    bottom: anchor(bottom);
+    right: anchor(right);
+    /* center the 20px box exactly over the 16px chevron (1rem trigger padding) */
+    margin-inline-end: 0.875rem;
+    width: 1.25rem;
+    display: none;
+    place-items: center;
+    padding: 0;
+    border: none;
+    border-radius: var(--radius-sm);
+    background: transparent;
+    color: var(--muted-foreground);
+    cursor: pointer;
+
+    &:hover { color: var(--foreground); }
+    &:focus-visible { outline: 2px solid var(--ring); outline-offset: 1px; }
+  }
+
+  .combobox:has(.combobox-value:not([data-placeholder])) {
+    & .combobox-clear { display: grid; }
+    & .combobox-chevron { display: none; }
+  }
+
   .combobox-content {
     position: fixed;
     inset: auto;
@@ -142,6 +175,13 @@
       pointer-events: none;
       opacity: 0.5;
     }
+
+    /* Author `display: flex` overrides the UA's [hidden] { display: none }
+       (author origin always wins), so filter()'s item.hidden = true left
+       non-matching options rendered — and clickable — in the list. */
+    &[hidden] {
+      display: none;
+    }
   }
 
   .combobox-empty {

package/dist/components/combobox/combobox.js

@@ -108,6 +108,30 @@ function init() {
         const anchorId = `--combobox-${popover.id}`;
         trigger.style.anchorName = anchorId;
         popover.style.positionAnchor = anchorId;
+        // Clear button - injected so consumer markup stays minimal (and the
+        // button can't be nested in the trigger's <button>). Visibility is pure
+        // CSS: .combobox-clear shows exactly while data-placeholder is absent
+        // (combobox.css :has() rule); JS only wires the click and focus.
+        const placeholder = valueEl?.dataset.placeholder ?? '';
+        const clearBtn = document.createElement('button');
+        clearBtn.type = 'button';
+        clearBtn.className = 'combobox-clear';
+        clearBtn.setAttribute('aria-label', 'Clear selection');
+        clearBtn.innerHTML =
+            '<svg aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>';
+        clearBtn.style.positionAnchor = anchorId;
+        trigger.after(clearBtn);
+        clearBtn.addEventListener('click', () => {
+            allItems.forEach((i) => { i.setAttribute('aria-selected', 'false'); });
+            if (valueEl) {
+                valueEl.textContent = placeholder;
+                // re-declare data-placeholder: selectItem removed it, and it is the
+                // very marker the CSS :has() rule keys off to hide this button again
+                valueEl.setAttribute('data-placeholder', placeholder);
+            }
+            // the button goes display:none with the selection - keep focus usable
+            trigger.focus();
+        });
         const getVisibleItems = () => allItems.filter((item) => !item.hidden && item.getAttribute('aria-disabled') !== 'true');
         const open = () => {
             // deferred show (safeShowPopover): showPopover() mid-exit crashes the

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

@@ -22,6 +22,7 @@ the search input when the popover opens.
 
 ## Native Web APIs
 - [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) — top-layer rendering and light-dismiss for the dropdown list
+- [`:has()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has) — reveals the injected clear button exactly while a selection exists (`data-placeholder` absent)
 - [CSS Anchor Positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning) — positions the popover relative to the trigger without JS
 - [`@starting-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/@starting-style) — entry animation starting values for popover appearance
 - [`overscroll-behavior`](https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior) — prevents scroll chaining from the listbox to the page
@@ -169,6 +170,7 @@ The registry global is `_defussShadcn.comboboxApi` / `_defussShadcn.comboboxStat
 - The popover animates in via `@starting-style` + `transition-behavior: allow-discrete`
 - The check icon for selected items uses a CSS `::before` pseudo-element
 - Filter matching is case-insensitive and supports substring matching
+- The clear button (`.combobox-clear`, ✕) is **injected by the JS after the trigger** — consumer markup never contains it. It replaces the chevron whenever a value is selected (pure CSS via `:has()`), and clicking it restores the placeholder and deselects every option
 - The empty state element is shown when no items match the filter query
 - Group labels and separators auto-hide when their group has no visible items
 - `overscroll-behavior: contain` prevents scroll chaining from the listbox

package/dist/components/command/command.css

@@ -18,6 +18,14 @@
     dialog.command[open]::backdrop { background: oklch(0 0 0 / 0); }
   }
 
+  /* -- Scroll lock ------------------------------------------- */
+  /* Page behind stays put while the palette is modal (see dialog.css):
+     `:modal` + overflow:hidden freezes the viewport at its current offset. */
+  html:has(dialog.command:modal) {
+    overflow: hidden;
+    scrollbar-gutter: stable;
+  }
+
   .command-input-wrapper {
     display: flex; align-items: center; gap: 0.5rem;
     padding: 0.75rem 1rem; border-bottom: 1px solid var(--border);
@@ -43,6 +51,9 @@
     &:focus-visible { outline: 2px solid var(--ring); outline-offset: -2px; }
     &[aria-disabled="true"] { pointer-events: none; opacity: 0.5; }
     & svg { width: 1rem; height: 1rem; color: var(--muted-foreground); flex-shrink: 0; }
+    /* Same as combobox-item: `display: flex` beats the UA [hidden] rule, and
+       command.ts filter() hides non-matches via the hidden attribute. */
+    &[hidden] { display: none; }
   }
 
   .command-separator { height: 1px; background-color: var(--border); margin: 0.25rem -0.25rem; }

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

@@ -109,3 +109,4 @@ The api is bound per palette dialog; the registry global is
 - The dialog uses `showModal()` — focus is trapped inside and Escape closes it natively.
 - On close, the search input is cleared and all items are restored.
 - No JavaScript positioning is needed — the dialog uses CSS `position: fixed` with `top: 15%`.
+- While the palette is modal, `html:has(dialog.command:modal)` sets `overflow: hidden` + `scrollbar-gutter: stable` — the page behind cannot scroll and its position is preserved for when the palette closes (no JS scroll-lock).

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

@@ -114,5 +114,6 @@ Requires minimal JavaScript — only for trigger wiring and backdrop-click-to-cl
 ## Notes
 
 - Animation uses CSS-only enter via `@starting-style` and exit via `transition` + `allow-discrete`.
+- While the dialog is modal, `html:has(dialog.dialog:modal)` sets `overflow: hidden` + `scrollbar-gutter: stable` — the page behind cannot scroll and its position is preserved for when the dialog closes (no JS scroll-lock).
 - The selector is `dialog.dialog` (element + class) to avoid styling native `<dialog>` elements used elsewhere.
 - For forms inside dialogs, use the `dialog-body` wrapper for the form content.

package/dist/components/dialog/dialog.css

@@ -54,6 +54,18 @@
     }
   }
 
+  /* -- Scroll lock ------------------------------------------- */
+  /* While the dialog is modal the page behind must stay put — closing
+     returns you to exactly the scroll offset you had. `:modal` matches only
+     while opened via showModal(); overflow:hidden freezes the viewport
+     without losing the scroll position (no JS position:fixed hack), and
+     scrollbar-gutter:stable keeps the scrollbar's space reserved so its
+     removal can't shift the layout underneath. */
+  html:has(dialog.dialog:modal) {
+    overflow: hidden;
+    scrollbar-gutter: stable;
+  }
+
   /* -- Content sections ------------------------------------- */
   .dialog-content { padding: 1.5rem; }
   .dialog-header  { margin-bottom: 1rem; }

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

@@ -144,6 +144,7 @@ The registry global is `_defussShadcn.imageApi` / `_defussShadcn.imageStates`.
 - Use `loading="lazy"` on images below the fold for performance.
 - Lightbox supports keyboard: Escape closes, Tab navigates controls.
 - Multiple images with `data-preview` share a single dialog instance.
+- While the lightbox is modal, `html:has(dialog.image-lightbox:modal)` sets `overflow: hidden` + `scrollbar-gutter: stable` — the page behind cannot scroll and its position is preserved for when the lightbox closes (no JS scroll-lock).
 # Image
 
 ## Native basis

package/dist/components/image/image.css

@@ -108,6 +108,14 @@
     }
   }
 
+  /* -- Scroll lock ------------------------------------------- */
+  /* Page behind stays put while the lightbox is modal (see dialog.css):
+     `:modal` + overflow:hidden freezes the viewport at its current offset. */
+  html:has(dialog.image-lightbox:modal) {
+    overflow: hidden;
+    scrollbar-gutter: stable;
+  }
+
   .image-lightbox-content {
     display: flex;
     align-items: center;

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

@@ -10,6 +10,9 @@ supportedStates: default
 
 ## Native basis
 `<label>` element. Browser provides built-in click-to-focus association with form controls.
+The association is the `for`↔`id` pairing: the label's `for` and the control's `id`
+must be the exact same string — click-to-focus and the accessible name both exist
+only because of it.
 
 ---
 
@@ -25,6 +28,7 @@ supportedStates: default
 
 ### Basic
 ```html
+<!-- for and id are one value in two places — keep them identical -->
 <label class="label" for="email">Email</label>
 <input class="input" id="email" type="email">
 ```
@@ -91,7 +95,8 @@ The label auto-dims when the adjacent control is disabled — no `data-disabled`
 |-----------|------|-------|
 | `for` | Always | Matches the `id` of the associated form control |
 
-- Clicking the label focuses the associated input — this is native `<label>` behavior.
+- **One value, written twice:** the label's `for` and the control's `id` must be the exact same string. A mismatch fails silently — the label renders and styles normally but no longer focuses the field or names it for assistive technology. When renaming a control's `id`, update every `for` that pointed at it.
+- Clicking the label focuses the associated input — native `<label>` behavior, and the practical proof the pairing is intact.
 - The required indicator `*` uses `aria-hidden="true"` since the `required` attribute on the input already conveys the requirement to assistive technology.
 - Do not use `<label>` without a `for` attribute or a nested input.
 - In `forced-colors` mode, label text maps to system `LinkText` color.

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

@@ -22,10 +22,12 @@ supportedStates: default
 ## Structure
 
 ### Basic
+The empty-value placeholder stays selectable (no `disabled`) so it doubles as
+the clear/reset entry — re-choosing it empties the box again.
 ```html
 <label class="label" for="fruit">Fruit</label>
 <select class="select" id="fruit">
-  <option value="" disabled selected>Select a fruit</option>
+  <option value="" selected>Select a fruit</option>
   <option value="apple">Apple</option>
   <option value="banana">Banana</option>
   <option value="cherry">Cherry</option>
@@ -52,7 +54,11 @@ supportedStates: default
 
 - Native `<select>` provides full keyboard navigation (arrow keys, type-ahead).
 - Use `<label>` with `for` for description.
-- Use `disabled` on `<option>` elements for placeholder text.
+- The placeholder is `<option value="" selected>` **without** `disabled`: a
+  disabled placeholder can't be re-selected, so a made selection could never be
+  cleared. Keep it selectable and add `required` to the `<select>` when an empty
+  value must not submit — native validation then blocks submission while the
+  placeholder is still the selection.
 
 ---
 
@@ -73,5 +79,8 @@ Set `data-size` on the `.select` trigger button.
 ## Notes
 
 - Uses `appearance: none` with a custom chevron via `background-image` SVG.
+- While the empty option is selected, the closed control renders in
+  `--muted-foreground` (`:has(> option[value=""]:checked)`) so it reads as a
+  placeholder; a real value restores `--foreground`.
 - The dropdown list is rendered by the browser — it cannot be styled.
 - For a fully custom dropdown, use the Combobox component instead.

package/dist/components/select/select.css

@@ -23,6 +23,16 @@
     background-position: right 0.5rem center;
     background-size: 1rem;
 
+    /* Placeholder = the empty-value option. It stays selectable (no
+       `disabled`) so it doubles as the clear/reset entry — choosing it
+       again empties the box (issue #32). While it is the selection the
+       closed control reads as a placeholder; a real value restores
+       --foreground because the base rule's color wins over this one.
+       option:checked matches the *selected* option in every engine. */
+    &:has(> option[value=""]:checked) {
+      color: var(--muted-foreground);
+    }
+
     &:focus {
       border-color: var(--ring);
       box-shadow: 0 0 0 2px oklch(from var(--ring) l c h / 0.2);

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

@@ -123,6 +123,7 @@ The api is bound per sheet element; the registry global is
 
 ## Notes
 
+- While a sheet is modal, `html:has(dialog.sheet:modal)` sets `overflow: hidden` + `scrollbar-gutter: stable` — the page behind cannot scroll and its position is preserved for when the sheet closes (no JS scroll-lock).
 - Right/left sheets have a fixed width of `24rem` with `max-width: 100vw` for small screens.
 - Top/bottom sheets are full width with `height: auto` — they size to their content. Their `.sheet-content` column caps at `48rem` and centers, so content doesn't stretch to the viewport edges.
 - The selector is `dialog.sheet` (element + class) to avoid conflicts with `dialog.dialog`.

package/dist/components/sheet/sheet.css

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

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

@@ -126,7 +126,7 @@ The registry global is `_defussShadcn.sidebarApi` / `_defussShadcn.sidebarStates
 
 ## Notes
 
-- **Mobile**: Desktop sidebar hidden below 768px. Use `<dialog class="sidebar-mobile">` for slide-in sheet.
+- **Mobile**: Desktop sidebar hidden below 768px. Use `<dialog class="sidebar-mobile">` for slide-in sheet. While it is modal, `html:has(.sidebar-mobile:modal)` sets `overflow: hidden` + `scrollbar-gutter: stable` — the page behind cannot scroll and keeps its position (no JS scroll-lock).
 - **Collapsible groups**: `<details class="sidebar-group">` — native toggle, no JS.
 - **Submenus**: `<details class="sidebar-submenu">` for nested nav with left border.
 - **Badges**: `<span class="sidebar-badge">` for notification counts.

package/dist/components/sidebar/sidebar.css

@@ -356,6 +356,14 @@
     .sidebar-mobile[data-side="right"][open] { opacity: 0; translate: 100% 0; }
   }
 
+  /* ── Scroll lock ──────────────────────────────────────────── */
+  /* Page behind stays put while the mobile sheet is modal (see dialog.css):
+     `:modal` + overflow:hidden freezes the viewport at its current offset. */
+  html:has(.sidebar-mobile:modal) {
+    overflow: hidden;
+    scrollbar-gutter: stable;
+  }
+
   /* ── Reduced motion ───────────────────────────────────────── */
   @media (prefers-reduced-motion: reduce) {
     .app-sidebar { transition: none; }