@webjsdev/ui 0.3.9 → 0.3.11

package/README.md

@@ -24,10 +24,12 @@ function calls, not for a layered React abstraction over every primitive:
   Escape, and backdrop overlay all come from the platform. Light DOM
   throughout (no shadow DOM); authored children project through `<slot>`.
 
-Works with any project that uses Tailwind CSS v4 and supports custom elements:
-webjs, Next, Astro, Vite, SvelteKit, Lit, vanilla HTML, as long as Tailwind
-is configured, the components render correctly. Variant names, sizes, and
-data-attribute conventions mirror shadcn's so an AI agent's existing
+**This is the component library for WebJs apps.** It is what `webjs ui init`
+and `webjs ui add` install, and WebJs is the only host it is tested and
+supported on. The output is plain Tailwind CSS v4 classes and standard custom
+elements, so nothing stops it rendering elsewhere, but no other framework is a
+supported target and none is detected or defaulted for. Variant names, sizes,
+and data-attribute conventions mirror shadcn's so an AI agent's existing
 knowledge of shadcn maps directly.
 
 Tier-2 elements extend the `WebComponent({ ... })` factory from
@@ -58,7 +60,7 @@ so on. Follow that block and the markup is fully accessible.
 
 ## Install
 
-### Option A : Webjs users (already have `@webjsdev/cli`)
+### Option A : through `@webjsdev/cli` (the normal path)
 
 Nothing to install. `@webjsdev/ui` is a hard dependency of `@webjsdev/cli`,
 so a global webjs install already includes it. Apps scaffolded with
@@ -69,9 +71,11 @@ webjs ui init
 webjs ui add button card dialog
 ```
 
-### Option B : Everyone else (Next, Astro, Vite, SvelteKit, Lit, vanilla, …)
+### Option B : the standalone binary
 
-Two npm installs, the CLI and the runtime base class, then run the CLI:
+The `webjsui` binary does not require `@webjsdev/cli`, so a WebJs app that
+skipped the global install can reach the kit with two npm installs, the CLI
+and the runtime base class:
 
 ```sh
 npm install -D @webjsdev/ui
@@ -80,15 +84,19 @@ npx webjsui init
 npx webjsui add button card dialog
 ```
 
-The `webjsui` binary is standalone, it doesn't require `@webjsdev/cli`.
-`init` auto-detects your project type (Next / Astro / Vite / Lit / plain)
-and picks sensible defaults.
+Both paths write the same `components.json`. `init` takes no reading of the
+host project: the defaults below are fixed, and `--css <path>` overrides the
+stylesheet it appends the tokens to. Re-running it preserves what an existing
+project already declared (its aliases, stylesheet path, and base color) and
+leaves an existing helper file as you edited it, so it is safe as a repair
+step. Pass `--overwrite` to reset those instead.
 
 ## What `init` writes
 
 - `components.json`, your project's UI config (aliases, base color, Tailwind path)
-- `lib/utils.ts`, the `cn()` class-merge helper
-- Tailwind tokens + CSS variables appended to your global stylesheet
+- `lib/utils/cn.ts`, the `cn()` class-merge helper, and `lib/utils/dom.ts`
+  beside it for the client-only `onBeforeCache()` helper
+- Tailwind tokens + CSS variables appended to `styles/globals.css`
 
 ## What `add` does
 
@@ -109,7 +117,7 @@ always compares against the live upstream.
 
 | Command | Effect |
 |---|---|
-| `webjsui init` | Initialize a project (writes `components.json`, `lib/utils.ts`, the theme tokens). Exits non-zero if the tokens cannot be written. |
+| `webjsui init` | Initialize a project (writes `components.json`, `lib/utils/cn.ts`, the theme tokens). Preserves an existing project's settings and helper files; `-o, --overwrite` resets them. Exits non-zero if the tokens cannot be written. |
 | `webjsui add <names...>` | Add components (copies helpers + a pointer for Tier-1, self-heals theme tokens) |
 | `webjsui list` | List all available components |
 | `webjsui view <name>` | Print a component's projected view (helpers + paste-ready example) and full source |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "type": "module",
-  "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
+  "description": "The AI-first component library for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Class-helper functions for visuals, custom elements only where state matters, source-copied into your repo so you own it.",
   "bin": {
     "webjsui": "bin/webjsui.js"
   },
@@ -37,7 +37,7 @@
     "url": "git+https://github.com/webjsdev/webjs.git",
     "directory": "packages/ui"
   },
-  "homepage": "https://ui.webjs.dev",
+  "homepage": "https://webjs.dev/ui",
   "bugs": "https://github.com/webjsdev/webjs/issues",
   "license": "MIT",
   "keywords": [

package/packages/registry/README.md

@@ -3,11 +3,15 @@
 Internal: sources for the `@webjsdev/ui` component registry.
 
 Not published. `registry.json` is the manifest, and the files it points at
-are the source of truth. The website
-([`@webjsdev/ui-website`](../ui-website)) composes shadcn-compatible JSON on
-demand and serves it at `https://ui.webjs.dev/registry/<name>.json`, which the
-`@webjsdev/ui` CLI fetches. There is no build step, no generated output, no
-`prestart` hook.
+are the source of truth. The marketing site composes shadcn-compatible JSON on
+demand from these sources and serves it at
+`https://webjs.dev/ui/registry/<name>.json`, which the `@webjsdev/ui` CLI
+fetches. There is no build step, no generated output, no `prestart` hook.
+
+The composer and the routes moved out of this package with #1099, when the
+gallery merged into the marketing site. The old `ui.webjs.dev/registry/**`
+URLs still resolve, permanently redirecting to the new ones, because
+already-published CLI versions fetch from them.
 
 ## Layout
 
@@ -26,10 +30,10 @@ overrides → merged CSS, same `files[]` shape.
 
 ## Wire endpoints
 
-Served by `@webjsdev/ui-website` (`app/_lib/registry.server.ts` +
-`app/registry/**`):
+Served by the marketing site (`website/modules/ui/queries/registry.server.ts`
+composes, `website/app/ui/registry/**` routes):
 
-- `GET /registry/<name>.json`: single registry item (`type: registry:ui` /
+- `GET /ui/registry/<name>.json`: single registry item (`type: registry:ui` /
   `registry:theme` / `registry:lib`), with file contents inlined.
-- `GET /registry/index.json`: flat metadata-only list.
-- `GET /registry`: full manifest with every item's content inlined.
+- `GET /ui/registry/index.json`: flat metadata-only list.
+- `GET /ui/registry`: full manifest with every item's content inlined.

package/packages/registry/components/accordion.ts

@@ -24,6 +24,24 @@
  *
  * Design tokens used: --border, --ring, --foreground.
  *
+ * A11y (mostly handled by the native primitives):
+ *   Build it on `<details>` + `<summary>`, which is where nearly all of this
+ *   comes from: the browser supplies the button semantics, the expanded state,
+ *   Enter / Space activation, and focus, with no ARIA to hand-write. Do not
+ *   reimplement it with a `<div>` and `aria-expanded`.
+ *   Put the trigger classes on the `<summary>` ITSELF, not on a `<button>` or
+ *   `<div>` nested inside it. A nested interactive element inside a `<summary>`
+ *   is the #1078-class bug: the focusable thing and the labelled thing come
+ *   apart, and the summary's own name goes empty.
+ *   The chevron is decorative, so keep it `aria-hidden="true"`.
+ *   `name` on `<details>` is what gives exclusive-open behaviour natively, so
+ *   prefer it over JS that closes siblings.
+ *   Use a real heading inside the `<summary>` when the section title belongs in
+ *   the document outline, and pick its level from the surrounding page.
+ *   Never rely on the collapsed state to HIDE something that must stay
+ *   available: collapsed content is not reachable by find-in-page on every
+ *   engine, so nothing essential should live only there.
+ *
  * @example
  * ```html
  * <div class=${accordionClass()}>

package/packages/registry/components/alert-dialog.ts

@@ -44,8 +44,29 @@
  * Keyboard: Escape is blocked (alert dialogs require explicit choice);
  * Tab cycles trapped within the dialog (native focus trap).
  *
+ * A11y (owned by the element, but SUPPLY A TITLE):
+ *   On open the element names and describes the panel from the
+ *   `data-slot="alert-dialog-title"` / `alert-dialog-description` nodes,
+ *   falling back to the first heading / paragraph. An `aria-label` or
+ *   `aria-labelledby` you put on `<ui-alert-dialog-content>` is forwarded onto
+ *   the panel and wins over both.
+ *   A modal MUST have an accessible name, so with no title node and no name of
+ *   your own the panel falls back to a generic `aria-label="Alert dialog"`.
+ *   Treat that as a bug in your markup rather than a feature: this dialog
+ *   interrupts the user to demand an explicit choice and blocks Escape, so
+ *   naming it "Alert dialog" tells them nothing about what they are deciding.
+ *
  * Design tokens used: --background, --border, --muted-foreground.
  *
+ * Scroll lock (#1144): opening the dialog locks body scroll, which hides the
+ * page scrollbar and would widen the viewport. The lock reserves the scrollbar
+ * gutter so the width never changes and a `position: fixed` header stays put.
+ * Where the engine ignores `scrollbar-gutter` (WebKit today) it publishes the
+ * leftover width on <html> as `--wj-scrollbar-compensation`, so a fixed header
+ * opts in with `border-right: var(--wj-scrollbar-compensation, 0px) solid transparent`
+ * (a transparent border composes with existing padding, and a background paints
+ * across it, so a header keeps its own chrome full bleed).
+ *
  * @example
  * ```html
  * <ui-alert-dialog>
@@ -104,29 +125,130 @@ function installStyles(): void {
   document.head.appendChild(style);
 }
 
-// Body scroll lock. Refcounted so nested dialogs unlock in order. Kept in
-// lockstep with dialog.ts (not imported) so `webjs ui add alert-dialog`
+// Page scroll lock, refcounted so nested dialogs release safely in ANY order.
+// Kept in lockstep with dialog.ts (not imported) so `webjs ui add alert-dialog`
 // doesn't pull in the full dialog component.
-let scrollLockCount = 0;
-let savedOverflow = '';
-let savedPaddingRight = '';
+//
+// Hiding the page scrollbar widens the viewport by the scrollbar's width, so
+// anything laid out against the viewport moves. Padding the page holds in-flow
+// content still, but a `position: fixed` header lays out against the initial
+// containing block, never against any padding box, so padding alone leaves it
+// sliding right by half the scrollbar width. Two mechanisms fix it:
+//
+//   1. Reserve the scrollbar gutter for the duration of the lock, so the
+//      viewport width never changes and NOTHING moves, in flow or fixed. This
+//      needs no cooperation from the page. Measured honoured on Chromium.
+//   2. Where the engine ignores it (measured on WebKit), fall back to
+//      padding <html> and publish the leftover width as
+//      `--wj-scrollbar-compensation` on it, so a fixed element can opt in with
+//      `border-right: var(--wj-scrollbar-compensation, 0px) solid transparent`.
+//
+// Everything below is MEASURED rather than assumed, because engines disagree
+// about both scrollbar geometry and gutter support. When mechanism 1 works the
+// measured residual is zero, so no padding is applied and the custom property is
+// never set: the two mechanisms cannot double-compensate.
+//
+// The lock's state is DOCUMENT level, so it is keyed on globalThis rather than
+// module scope. dialog.ts and alert-dialog.ts ship as separate copies (so
+// `webjs ui add alert-dialog` stays self contained), and two independent
+// counters mutating the same <html> can only be released safely in LIFO order.
+// They are not: `disconnectedCallback` fires in tree order and the #766
+// before-cache close runs in registration order, so a confirm inside a dialog
+// releases OUTER first, and the inner unlock would then re-apply the values it
+// captured with nothing left to clear them, leaving <html> padded for good. One
+// shared counter makes release order irrelevant.
+interface ScrollLockState {
+  count: number;
+  overflow: string;
+  rootPaddingRight: string;
+  scrollbarGutter: string;
+  compensation: string;
+}
+
+const SCROLLBAR_COMPENSATION = '--wj-scrollbar-compensation';
+
+function scrollLockState(): ScrollLockState {
+  // The key follows the framework's global-key prefix (see `__webjsSonnerBus` in
+  // sonner.ts, the same pattern for the same reason), and the cast is typed
+  // rather than a string-keyed bag, so a change to the shape is a type error in
+  // both copies instead of a silent undefined at runtime.
+  const store = globalThis as unknown as { __webjsScrollLock?: ScrollLockState };
+  let state = store.__webjsScrollLock;
+  if (!state) {
+    state = { count: 0, overflow: '', rootPaddingRight: '', scrollbarGutter: '', compensation: '' };
+    store.__webjsScrollLock = state;
+  }
+  return state;
+}
 
 function lockScroll(): void {
-  if (scrollLockCount === 0) {
-    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
-    savedOverflow = document.body.style.overflow;
-    savedPaddingRight = document.body.style.paddingRight;
-    document.body.style.overflow = 'hidden';
-    if (scrollbarWidth > 0) document.body.style.paddingRight = `${scrollbarWidth}px`;
+  const state = scrollLockState();
+  if (state.count === 0) {
+    const root = document.documentElement;
+    const body = document.body;
+    const rootStyle = getComputedStyle(root);
+
+    state.overflow = body.style.overflow;
+    state.rootPaddingRight = root.style.paddingRight;
+    state.scrollbarGutter = root.style.scrollbarGutter;
+    state.compensation = root.style.getPropertyValue(SCROLLBAR_COMPENSATION);
+
+    // <html> is an in-flow block filling the initial containing block, so its
+    // border box IS the viewport width, and it is re-laid-out synchronously.
+    // A `position: fixed` probe is NOT a substitute: WebKit keeps reporting its
+    // old box until the next rendering update, so it reads a zero delta and the
+    // compensation below never fires.
+    const widthBefore = root.getBoundingClientRect().width;
+    const padBefore = parseFloat(rootStyle.paddingRight) || 0;
+    // An engine with no `scrollbar-gutter` at all reads back undefined, which
+    // must be treated as "the page has not chosen" so the gutter is still
+    // attempted (setting an unsupported property is a harmless no-op, and the
+    // measured residual below is what actually decides the fallback).
+    const chosenGutter = rootStyle.scrollbarGutter || 'auto';
+
+    // Reserve the gutter, but only when the page has not already made its own
+    // choice. An app running `stable both-edges` keeps both gutters through the
+    // lock, and overwriting that with the single-edge value would drop one and
+    // introduce the very shift this exists to prevent.
+    if (chosenGutter === 'auto' && window.innerWidth > root.clientWidth) {
+      root.style.scrollbarGutter = 'stable';
+    }
+    body.style.overflow = 'hidden';
+
+    const grew = root.getBoundingClientRect().width - widthBefore;
+    if (grew > 0) {
+      // Padding the ROOT holds in-flow content still whatever the body's own
+      // width is (a `max-width` body does not widen with the viewport, so
+      // padding the body would miss it), and it leaves the page's own body
+      // padding untouched.
+      root.style.paddingRight = `${padBefore + grew}px`;
+      // A fixed box lays out against the viewport, so no padding here can reach
+      // it. Publish what it moved by and let it opt in.
+      root.style.setProperty(SCROLLBAR_COMPENSATION, `${grew}px`);
+    }
   }
-  scrollLockCount++;
+  state.count++;
 }
 
 function unlockScroll(): void {
-  scrollLockCount = Math.max(0, scrollLockCount - 1);
-  if (scrollLockCount === 0) {
-    document.body.style.overflow = savedOverflow;
-    document.body.style.paddingRight = savedPaddingRight;
+  const state = scrollLockState();
+  // An unlock with no matching lock is a no-op, NOT the last release: clamping to
+  // zero and restoring would replay a stale snapshot onto whatever the page owns
+  // now. Belt-and-braces as things stand, because _teardown() only unlocks what
+  // its own element locked, so no path through the components can reach here with
+  // a zero count. It is kept because the cost is one comparison and the failure
+  // it prevents is silent.
+  if (state.count === 0) return;
+  state.count--;
+  if (state.count === 0) {
+    const root = document.documentElement;
+    document.body.style.overflow = state.overflow;
+    root.style.paddingRight = state.rootPaddingRight;
+    root.style.scrollbarGutter = state.scrollbarGutter;
+    // Restored rather than removed, so a value the PAGE set before any dialog
+    // opened survives the lock.
+    if (state.compensation) root.style.setProperty(SCROLLBAR_COMPENSATION, state.compensation);
+    else root.style.removeProperty(SCROLLBAR_COMPENSATION);
   }
 }
 
@@ -147,6 +269,7 @@ export class UiAlertDialog extends WebComponent({
   }
 
   _disposeBeforeCache?: () => void;
+  _scrollLocked?: boolean;
 
   connectedCallback(): void {
     installStyles();
@@ -195,14 +318,33 @@ export class UiAlertDialog extends WebComponent({
   }
 
   _setup(): void {
+    // A detached element must not lock: `updated()` defers this to a microtask,
+    // and a removal in between already ran _teardown() as a no-op, so locking
+    // here would never be released (nothing disconnects twice).
+    if (!this.isConnected) return;
     const content = this._content;
     if (!content) return;
-    lockScroll();
+    // Idempotent, because the count is an integer and the flag is a boolean. A
+    // coalesced hide() then show() in one task produces ONE update whose
+    // changedProperties still reports open, so _setup() can run twice with no
+    // _teardown() between; double-counting there would leave the page locked for
+    // the rest of the session.
+    if (!this._scrollLocked) {
+      lockScroll();
+      this._scrollLocked = true;
+    }
     content.showModal();
   }
 
   _teardown(): void {
-    unlockScroll();
+    // Release only what THIS element locked. _setup() returns before locking
+    // when there is no content child, so an unconditional unlock here would
+    // consume ANOTHER open dialog's count and restore the page out from under
+    // it, dropping its compensation while it is still open.
+    if (this._scrollLocked) {
+      this._scrollLocked = false;
+      unlockScroll();
+    }
     this._content?.close();
   }
 }
@@ -267,18 +409,57 @@ export class UiAlertDialogContent extends WebComponent({
   // description is data-slot="alert-dialog-description" (falling back to the
   // first paragraph). Author-set ARIA always wins. Inlined rather than shared
   // with dialog.ts so `webjs ui add alert-dialog` stays self-contained.
+  // The description is independent of the NAME, so it is wired on every path,
+  // including the two authored-name early returns.
+  _wireDescription(panel: Element): void {
+    const authored = this.getAttribute('aria-describedby');
+    if (authored) {
+      panel.setAttribute('aria-describedby', authored);
+      return;
+    }
+    const desc =
+      this.querySelector('[data-slot="alert-dialog-description"]') ?? this.querySelector('p');
+    if (desc && !panel.hasAttribute('aria-describedby')) {
+      panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-alert-desc'));
+    }
+  }
+
   _wireLabels(): void {
     const panel = this.querySelector('[data-slot="alert-dialog-content"]');
     if (!panel) return;
+    // A name the author put on <ui-alert-dialog-content> is where they
+    // naturally write it, but role="alertdialog" lives on the inner panel.
+    //
+    // Each authored-name branch RETURNS rather than falling through to the
+    // title wiring. Falling through would set aria-labelledby from the title
+    // alongside the forwarded aria-label, and aria-labelledby beats aria-label
+    // per accname, so the title would silently win over the author's name.
+    const authoredLabelledBy = this.getAttribute('aria-labelledby');
+    if (authoredLabelledBy) {
+      panel.setAttribute('aria-labelledby', authoredLabelledBy);
+      this._wireDescription(panel);
+      return;
+    }
+    const authoredLabel = this.getAttribute('aria-label');
+    if (authoredLabel) {
+      panel.setAttribute('aria-label', authoredLabel);
+      // An authored name replaces the title as the NAME, so a stale
+      // aria-labelledby from an earlier open must go or it would win over it.
+      panel.removeAttribute('aria-labelledby');
+      this._wireDescription(panel);
+      return;
+    }
     const title =
       this.querySelector('[data-slot="alert-dialog-title"]') ?? this.querySelector('h1, h2, h3');
-    const desc =
-      this.querySelector('[data-slot="alert-dialog-description"]') ?? this.querySelector('p');
     if (title && !panel.hasAttribute('aria-labelledby')) {
       panel.setAttribute('aria-labelledby', ensureId(title as HTMLElement, 'ui-alert-title'));
     }
-    if (desc && !panel.hasAttribute('aria-describedby')) {
-      panel.setAttribute('aria-describedby', ensureId(desc as HTMLElement, 'ui-alert-desc'));
+    this._wireDescription(panel);
+    // APG: a modal MUST have an accessible name, and this one interrupts the
+    // user to demand a decision, so an unnamed one is worse here than
+    // anywhere. A floor, not a substitute for a real title; a title wins.
+    if (!panel.hasAttribute('aria-labelledby') && !panel.hasAttribute('aria-label')) {
+      panel.setAttribute('aria-label', 'Alert dialog');
     }
   }
 

package/packages/registry/components/aspect-ratio.ts

@@ -8,6 +8,18 @@
  *
  * Design tokens used: none (layout only).
  *
+ * A11y (required for accessible output):
+ *   Layout only, so it adds no semantics and takes none away. What matters is
+ *   the CONTENT you put inside it: an `<img>` still needs an `alt` (empty
+ *   `alt=""` when it is purely decorative), an `<iframe>` still needs a `title`,
+ *   and a `<video>` still needs its captions.
+ *   Reserving the ratio IS the accessibility win: the box keeps its space before
+ *   the media loads, so the page does not shift under someone who is already
+ *   reading or aiming at a target (WCAG 2.4.x-adjacent).
+ *   Do not clip meaningful content to make a ratio fit. If a crop would hide
+ *   part of an image that carries information, put that information in the
+ *   surrounding text too.
+ *
  * @example
  * ```html
  * <div style="aspect-ratio: 16/9;" class="${aspectRatioClass()}">

package/packages/registry/components/card.ts

@@ -13,11 +13,30 @@
  *
  * Design tokens used: --card, --card-foreground, --muted-foreground, --border.
  *
+ * A11y (required for accessible output):
+ *   Use a REAL HEADING for `cardTitleClass()` whenever the card has a
+ *   meaningful title. The helper only styles text, so on a `<div>` the title is
+ *   invisible to the heading outline a screen reader user navigates by, and on a
+ *   page of cards they get an unstructured wall. Pick the level that fits the
+ *   surrounding document (`<h2>` under the page `<h1>`, `<h3>` inside a
+ *   sectioned region); do not pick it for the font size, which the class sets.
+ *   The card root is a plain `<div>` with no role, which is correct: it is a
+ *   visual container. Give it a role only when it really is one thing, and then
+ *   name it, e.g. `<section aria-labelledby="<the title's id">` for a landmark,
+ *   or `role="listitem"` inside a `role="list"` for a card grid.
+ *   A WHOLE-CARD LINK is the trap. Do not wrap the card in an `<a>` around a
+ *   header, body, and buttons: it swallows the nested controls and gives a
+ *   screen reader user one enormous link whose name is the entire card text.
+ *   Put the link on the title instead and let the card be a container.
+ *   Keep the reading order of the DOM matching the visual order.
+ *   `cardActionClass()` places an action at the top right, but it stays after
+ *   the title and description in the markup, which is what you want announced.
+ *
  * @example
  * ```html
  * <div class=${cardClass()}>
  *   <div class=${cardHeaderClass()}>
- *     <div class=${cardTitleClass()}>Notifications</div>
+ *     <h3 class=${cardTitleClass()}>Notifications</h3>
  *     <div class=${cardDescriptionClass()}>You have 3 unread messages.</div>
  *     <div class=${cardActionClass()}>
  *       <button class=${buttonClass({ variant: 'ghost', size: 'sm' })}>Mark all read</button>

package/packages/registry/components/checkbox.ts

@@ -12,10 +12,45 @@
  * Design tokens used: --input, --primary, --primary-foreground, --background,
  * --ring, --destructive.
  *
+ * A11y (required for accessible output):
+ *   `data-slot="checkbox"` is REQUIRED, not decoration. The injected stylesheet
+ *   keys the checkmark on it, so without it a checked box renders as a filled
+ *   square with no tick: the checked and unchecked states then differ by colour
+ *   alone, which is exactly what WCAG 1.4.1 rules out. Every example here
+ *   carries it; keep it when you copy one.
+ *   Associate a label with the input, either `<label for>` pointing at the
+ *   input's `id` (as below) or by nesting the input inside the `<label>`. A
+ *   checkbox with no label has no accessible name.
+ *   Group related checkboxes in a `<fieldset>` with a `<legend>` naming the
+ *   group, so the set is announced as one thing rather than N loose controls.
+ *   Set `aria-invalid="true"` on a failed checkbox (the class styles it) and
+ *   point `aria-describedby` at the element holding the error text.
+ *   The indeterminate state is a PROPERTY, not an attribute
+ *   (`el.indeterminate = true`). Do NOT add `aria-checked="mixed"` alongside it:
+ *   the browser already maps a native checkbox's `indeterminate` to a mixed
+ *   checked state, and hand-writing the ARIA duplicates a state the host
+ *   language owns, which is discouraged precisely because the two can then
+ *   disagree. Set the property and leave the ARIA alone.
+ *
  * @example
  * ```html
- * <input type="checkbox" name="terms" id="terms" class=${checkboxClass()}>
- * <label class=${labelClass()} for="terms">I accept the terms</label>
+ * <div class="flex items-center gap-2">
+ *   <input type="checkbox" data-slot="checkbox" name="terms" id="terms" class=${checkboxClass()}>
+ *   <label class=${labelClass()} for="terms">I accept the terms</label>
+ * </div>
+ *
+ * <!-- A group of related checkboxes is named by its legend. -->
+ * <fieldset class=${stackClass({ gap: 'sm' })}>
+ *   <legend class=${fieldLabelClass()}>Email preferences</legend>
+ *   <div class="flex items-center gap-2">
+ *     <input type="checkbox" data-slot="checkbox" name="digest" id="pref-digest" class=${checkboxClass()}>
+ *     <label class=${labelClass()} for="pref-digest">Weekly digest</label>
+ *   </div>
+ *   <div class="flex items-center gap-2">
+ *     <input type="checkbox" data-slot="checkbox" name="security" id="pref-security" class=${checkboxClass()}>
+ *     <label class=${labelClass()} for="pref-security">Security alerts</label>
+ *   </div>
+ * </fieldset>
  * ```
  */
 import { cn } from '../lib/utils.ts';
@@ -93,7 +128,14 @@ export function installCheckboxStyles(): void {
 
 if (typeof document !== 'undefined') installCheckboxStyles();
 
-/** Tailwind classes for a styled native `<input type="checkbox">`. Add `data-slot="checkbox"` for the checkmark style to apply. */
+/**
+ * Tailwind classes for a styled native `<input type="checkbox">`.
+ *
+ * PAIR THIS WITH `data-slot="checkbox"` ON THE SAME INPUT. The injected
+ * stylesheet keys the checkmark and the indeterminate dash on that attribute,
+ * so the class alone gives you a box that fills with colour when checked but
+ * never draws a tick, leaving the two states distinguishable by colour only.
+ */
 export function checkboxClass(): string {
   return cn(CHECKBOX_CLASS);
 }

package/packages/registry/components/collapsible.ts

@@ -17,6 +17,21 @@
  *
  * Design tokens used: --border, --ring, --foreground.
  *
+ * A11y (mostly handled by the native primitives):
+ *   Build it on `<details>` + `<summary>`. The browser gives you the button
+ *   semantics, the expanded state, Enter / Space activation, and focus for free,
+ *   with no ARIA to hand-write. Do not rebuild it from a `<div>` plus
+ *   `aria-expanded`.
+ *   Put the trigger classes on the `<summary>` ITSELF, never on a `<button>` or
+ *   `<div>` nested inside it: nesting an interactive element in a `<summary>`
+ *   splits the focusable element from the labelled one and empties the summary's
+ *   accessible name.
+ *   Give the `<summary>` real text. A summary whose only content is an icon has
+ *   no accessible name, so an icon-only trigger needs an `aria-label` and an
+ *   `aria-hidden="true"` icon.
+ *   Do not put anything essential ONLY inside collapsed content: it is not
+ *   reachable by find-in-page on every engine.
+ *
  * @example
  * ```html
  * <details class=${collapsibleClass()}>