diff --git a/package-lock.json b/package-lock.json
index 90950245c7a..dcb82006e4a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8441,6 +8441,13 @@
         "vue": "^3.5.0"
       }
     },
+    "node_modules/@wc-toolkit/type-parser": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/@wc-toolkit/type-parser/-/type-parser-1.3.1.tgz",
+      "integrity": "sha512-xmRf9B3L37IO7HXSf/37Uv1xWlsA3GluslA4Ao8S0pFFlo5qEwrlgsnBxcxtnSh36zkoLC7p8VpW5dvRNbk8vg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@web/config-loader": {
       "version": "0.1.3",
       "dev": true,
@@ -12042,6 +12049,13 @@
       "version": "1.5.250",
       "license": "ISC"
     },
+    "node_modules/element-internals-polyfill": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/element-internals-polyfill/-/element-internals-polyfill-3.0.2.tgz",
+      "integrity": "sha512-uB0/Qube3lkwh8SmkTnGIyUgJ9YdqVSzIoHMRCEQjAbD4Y5UzsVbch1tIxjTgUe5k3gy1U0ZMKMJ90A81lqwig==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/emoji-regex": {
       "version": "8.0.0",
       "license": "MIT"
@@ -25283,8 +25297,10 @@
         "@types/node": "^25.6.0",
         "@vitest/coverage-v8": "4.1.10",
         "@wc-toolkit/storybook-helpers": "^10.3.0",
+        "@wc-toolkit/type-parser": "^1.3.1",
         "del": "^8.0.1",
         "dom-accessibility-api": "^0.7.1",
+        "element-internals-polyfill": "^3.0.2",
         "esbuild": "^0.28.0",
         "globby": "^16.2.0",
         "happy-dom": "^20.9.0",
diff --git a/packages/craftcms-legacy/cp/src/js/AssetImageEditor.js b/packages/craftcms-legacy/cp/src/js/AssetImageEditor.js
index e2f505e5d48..fd4b4e5a58d 100644
--- a/packages/craftcms-legacy/cp/src/js/AssetImageEditor.js
+++ b/packages/craftcms-legacy/cp/src/js/AssetImageEditor.js
@@ -930,15 +930,17 @@ Craft.AssetImageEditor = Garnish.Modal.extend(
       });
 
       // Straighten slider — the <craft-slide-rule> web component (replaces the
-      // legacy Craft.SlideRuleInput), driven via its start/change/end events.
+      // legacy Craft.SlideRuleInput). The grid follows the drag gesture, and
+      // the image follows `input`, which fires continuously through the drag
+      // (`change` only fires once, on release).
       this.straighteningInput = document.getElementById('slide-rule');
-      this.straighteningInput.addEventListener('start', () => {
+      this.straighteningInput.addEventListener('craft-drag-start', () => {
         this._showGrid();
       });
-      this.straighteningInput.addEventListener('change', () => {
+      this.straighteningInput.addEventListener('input', () => {
         this.straighten(this.straighteningInput);
       });
-      this.straighteningInput.addEventListener('end', () => {
+      this.straighteningInput.addEventListener('craft-drag-end', () => {
         this._hideGrid();
         this._cleanupFocalPointAfterStraighten();
       });
diff --git a/packages/craftcms-legacy/cp/src/js/CraftGlobalSidebar.js b/packages/craftcms-legacy/cp/src/js/CraftGlobalSidebar.js
index 509c6d745b6..372d0fbd012 100644
--- a/packages/craftcms-legacy/cp/src/js/CraftGlobalSidebar.js
+++ b/packages/craftcms-legacy/cp/src/js/CraftGlobalSidebar.js
@@ -7,8 +7,8 @@ class CraftGlobalSidebar extends HTMLElement {
     this.trigger = this.querySelector('#sidebar-trigger');
 
     if (this.trigger) {
-      this.trigger.addEventListener('open', this.expand.bind(this));
-      this.trigger.addEventListener('close', this.collapse.bind(this));
+      this.trigger.addEventListener('craft-show', this.expand.bind(this));
+      this.trigger.addEventListener('craft-hide', this.collapse.bind(this));
     }
   }
 
diff --git a/packages/craftcms-legacy/cpcompat/src/cp-compat.js b/packages/craftcms-legacy/cpcompat/src/cp-compat.js
index e7192a873c0..71f9ec45e05 100644
--- a/packages/craftcms-legacy/cpcompat/src/cp-compat.js
+++ b/packages/craftcms-legacy/cpcompat/src/cp-compat.js
@@ -566,15 +566,8 @@
       this.setValue(value, false);
 
       var self = this;
-      this.$container.on('value-change', function (event) {
-        if (
-          event &&
-          event.originalEvent &&
-          event.originalEvent.detail &&
-          typeof event.originalEvent.detail.value === 'number'
-        ) {
-          self.setValue(event.originalEvent.detail.value);
-        }
+      this.$container.on('change', function () {
+        self.setValue(self.$container[0].value);
       });
     }
 
@@ -604,11 +597,7 @@
         el.removeAttribute('described-by');
       }
 
-      if (this.settings.readOnly) {
-        el.setAttribute('read-only', '');
-      } else {
-        el.removeAttribute('read-only');
-      }
+      el.readonly = !!this.settings.readOnly;
 
       this.$buttons = this.$container.find('.slide-picker__segment');
 
diff --git a/packages/craftcms-legacy/dashboard/src/Dashboard.js b/packages/craftcms-legacy/dashboard/src/Dashboard.js
index 15021687402..199329bb45c 100644
--- a/packages/craftcms-legacy/dashboard/src/Dashboard.js
+++ b/packages/craftcms-legacy/dashboard/src/Dashboard.js
@@ -774,8 +774,8 @@ import './dashboard.scss';
 
       refreshColspanPicker();
 
-      this.colspanPicker.addEventListener('value-change', ({detail}) => {
-        const colspan = detail.value;
+      this.colspanPicker.addEventListener('change', () => {
+        const colspan = this.colspanPicker.value;
 
         // Update the widget and grid
         this.setColspan(colspan);
diff --git a/packages/craftcms-ui/.storybook/preview.ts b/packages/craftcms-ui/.storybook/preview.ts
index 253dd644efa..0558650355a 100644
--- a/packages/craftcms-ui/.storybook/preview.ts
+++ b/packages/craftcms-ui/.storybook/preview.ts
@@ -50,9 +50,29 @@ const preview: Preview = {
       },
     },
 
+    docs: {
+      // Show each story's source in a "Code" panel alongside Controls, so the
+      // markup is available from the story view and not only from the docs
+      // page. Stories that pin `docs.source.code` supply that value here too.
+      codePanel: true,
+    },
+
     options: {
       storySort: {
         method: 'alphabetical',
+        // Everything else sorts alphabetically beneath these. Getting Started
+        // leads because a first-time reader lands on the sidebar, and Tokens
+        // trails because it explains what the component pages reference.
+        order: [
+          'Getting Started',
+          ['Introduction', 'Installation', 'Theming'],
+          'Components',
+          'Form Controls',
+          ['Choice Controls', 'Select Controls', 'Text Controls'],
+          'JavaScript API',
+          ['Factory', 'Utilities', 'Services', 'Reactive Controllers'],
+          'Tokens',
+        ],
       },
     },
 
diff --git a/packages/craftcms-ui/custom-elements-manifest.config.mjs b/packages/craftcms-ui/custom-elements-manifest.config.mjs
index e2767bf8ccc..b1c577e5a8d 100644
--- a/packages/craftcms-ui/custom-elements-manifest.config.mjs
+++ b/packages/craftcms-ui/custom-elements-manifest.config.mjs
@@ -1,3 +1,26 @@
+import {getTsProgram, typeParserPlugin} from '@wc-toolkit/type-parser';
+
+/**
+ * The type parser warns once for every type it declines to expand: DOM
+ * interfaces reached through a property (`Element`, `HTMLCanvasElement`), the
+ * component classes themselves, and anything past its depth or property
+ * limits. Expanding those was never the point — only the union aliases behind
+ * `size`, `variant`, and `appearance` reach the Storybook controls — so the
+ * bail-out notices are dropped here.
+ *
+ * The filter is deliberately narrow. Real parser warnings, such as a bad
+ * `tsconfig.json`, use a different prefix and still print. The parser calls
+ * `console.warn(colorFormat, message)`, so the message is the second argument.
+ */
+const SKIPPED_TYPE_NOTICE = '[type-parser] - Skipped parsing type';
+const consoleWarn = console.warn;
+console.warn = (...args) => {
+  if (args.some((arg) => typeof arg === 'string' && arg.includes(SKIPPED_TYPE_NOTICE))) {
+    return;
+  }
+  consoleWarn(...args);
+};
+
 /**
  * A leaked TypeScript AST node (e.g. a `SourceFile`, which holds a circular
  * `parent` pointer) is a TS node, not a manifest value. The CEM manifest schema
@@ -47,7 +70,21 @@ export default {
   globs: ['src/components/**/*.ts'],
   exclude: ['**/*.stories.ts', '**/*.styles.ts', '**/*.test.ts'],
   outdir: 'dist',
+  // The type parser needs a real TypeScript program so it can resolve type
+  // aliases (`SizeValue`) back to their union members ('small' | 'medium' |
+  // 'large'). Without this the manifest only records the alias name, and
+  // Storybook renders a text box instead of a select.
+  overrideModuleCreation: ({ts, globs}) => {
+    const program = getTsProgram(ts, globs, 'tsconfig.json');
+    return program
+      .getSourceFiles()
+      .filter((sf) => globs.find((glob) => sf.fileName.includes(glob)));
+  },
   plugins: [
+    // Expand type aliases into `parsedTypes`, which `.storybook/preview.ts`
+    // reads via `setStorybookHelpersConfig({typeRef: 'parsedTypes'})`.
+    typeParserPlugin({propertyName: 'parsedTypes'}),
+
     // Add a plugin to prevent inheritance tree analysis errors
     {
       name: 'skip-external-inheritance',
@@ -73,6 +110,62 @@ export default {
         });
       },
     },
+    // The manifest is the package's public API description: Storybook's
+    // property tables and editors' IntelliSense are generated from it. The
+    // analyzer records every class member it finds, so without this the tables
+    // list internals — `craft-permission-tree` advertised a `#treeId`, and 45
+    // elements between them exposed 408 members no consumer can call.
+    //
+    // Dropped: TypeScript `private`/`protected`, JS `#private` fields, and the
+    // `_`/`__` prefixes Lion and this package use for the same thing. Anything
+    // meant to be public and prefixed should be renamed rather than exempted.
+    {
+      name: 'drop-internal-members',
+      packageLinkPhase({customElementsManifest}) {
+        const isInternal = (member) =>
+          member.privacy === 'private' ||
+          member.privacy === 'protected' ||
+          member.name?.startsWith('#') ||
+          member.name?.startsWith('_');
+
+        customElementsManifest?.modules?.forEach((module) => {
+          module?.declarations?.forEach((declaration) => {
+            if (declaration.members) {
+              declaration.members = declaration.members.filter(
+                (member) => !isInternal(member)
+              );
+            }
+          });
+        });
+      },
+    },
+
+    // The analyzer also infers events from `dispatchEvent()` calls, reading the
+    // first argument literally — so a helper that dispatches
+    // `new CustomEvent(type, …)` is recorded as an event named `type`. That is
+    // an artifact of the call site, not API, and it reaches the docs tables.
+    //
+    // Once a class declares its events with `@fires`, that list is taken as the
+    // whole story and inferred extras are dropped. A class with no `@fires` is
+    // left alone, so nothing is hidden from the guard that requires every
+    // remaining event to be described.
+    {
+      name: 'declared-events-win',
+      packageLinkPhase({customElementsManifest}) {
+        customElementsManifest?.modules?.forEach((module) => {
+          module?.declarations?.forEach((declaration) => {
+            const events = declaration.events;
+
+            if (!events?.some((event) => event.description)) {
+              return;
+            }
+
+            declaration.events = events.filter((event) => event.description);
+          });
+        });
+      },
+    },
+
     // Strip any leaked TS AST nodes so the analyzer can serialize the manifest.
     // analyzer@0.11.0 (under Node 24) leaks `SourceFile` nodes into the manifest,
     // and their circular `parent` pointers crash the final `JSON.stringify`. Runs
diff --git a/packages/craftcms-ui/package.json b/packages/craftcms-ui/package.json
index e20b513aa60..d2cd520ce98 100644
--- a/packages/craftcms-ui/package.json
+++ b/packages/craftcms-ui/package.json
@@ -15,6 +15,7 @@
     "web-components"
   ],
   "scripts": {
+    "pretest": "npm run build:manifest",
     "test": "vp test run",
     "test:dev": "vp test",
     "test:coverage": "vp test run --coverage",
@@ -26,7 +27,9 @@
     "check:exports": "attw --pack .",
     "check:types": "tsc --noEmit",
     "prestorybook": "npm run build:manifest",
-    "storybook": "storybook dev -p 6006",
+    "watch:manifest": "npm run build:manifest -- --watch",
+    "storybook": "run-p -l watch:manifest storybook:dev",
+    "storybook:dev": "storybook dev -p 6006",
     "prebuild:storybook": "npm run build:manifest",
     "build:storybook": "storybook build",
     "build:manifest": "custom-elements-manifest analyze --litelement --outdir dist",
@@ -99,8 +102,10 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "4.1.10",
     "@wc-toolkit/storybook-helpers": "^10.3.0",
+    "@wc-toolkit/type-parser": "^1.3.1",
     "del": "^8.0.1",
     "dom-accessibility-api": "^0.7.1",
+    "element-internals-polyfill": "^3.0.2",
     "esbuild": "^0.28.0",
     "globby": "^16.2.0",
     "happy-dom": "^20.9.0",
diff --git a/packages/craftcms-ui/src/components/action-item/ActionItem.mdx b/packages/craftcms-ui/src/components/action-item/ActionItem.mdx
new file mode 100644
index 00000000000..9ad5e2dec74
--- /dev/null
+++ b/packages/craftcms-ui/src/components/action-item/ActionItem.mdx
@@ -0,0 +1,109 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ActionItemStories from './action-item.stories';
+
+<Meta of={ActionItemStories} name="Docs" />
+
+# Action Item
+
+`<craft-action-item>` is a single entry in a menu.
+It renders as a button, or as a link when `href` is set, and carries an optional leading icon, a label, and an optional trailing shortcut or suffix.
+
+<Canvas of={ActionItemStories.Default} sourceState="shown" />
+
+Action items are usually supplied to [Action Menu](?path=/docs/components-action-menu--docs) rather than placed by hand — in data-driven mode it builds them from an `actions` array.
+Reach for the element directly when you are slotting your own menu content.
+
+An item has no width of its own; it fills whatever menu contains it.
+The examples below sit in a menu-sized container so the layout reads correctly.
+
+## Content
+
+`icon` renders artwork before the label, and the `icon` slot replaces it when you need something the icon set does not cover:
+
+<Canvas of={ActionItemStories.WithIcon} sourceState="shown" />
+
+The `suffix` slot holds trailing content, before any shortcut:
+
+<Canvas of={ActionItemStories.WithSuffix} sourceState="shown" />
+
+A `shortcut` is shown at the end of the item.
+It is display only — the item renders the keys but does not bind them, so the shortcut has to be wired up separately:
+
+<Canvas of={ActionItemStories.WithShortcut} sourceState="shown" />
+
+Pass an object to name the modifiers:
+
+<Canvas of={ActionItemStories.WithComplexShortcut} sourceState="shown" />
+
+## States
+
+`active` marks the entry a menu opens onto, or the option already in effect.
+It is reflected, so it can be styled from outside the component:
+
+<Canvas of={ActionItemStories.Active} sourceState="shown" />
+
+`disabled` dims the item and stops it being activated:
+
+<Canvas of={ActionItemStories.Disabled} sourceState="shown" />
+
+`variant` colors the item.
+Reach for `danger` on a destructive entry, so it reads as one before it is clicked:
+
+<Canvas of={ActionItemStories.Variants} sourceState="shown" />
+
+## Buttons, Links, and Checkboxes
+
+By default an item is a `<button>`.
+Setting `href` makes it an `<a>` instead, which is what you want for anything that navigates — it gets the browser's own link affordances, including opening in a new tab:
+
+<Canvas of={ActionItemStories.Link} sourceState="shown" />
+
+`type="checkbox"` reserves room for a checkmark before the icon, so a list of options stays aligned whether or not each one is checked.
+The `checkmark` slot replaces the default check:
+
+<Canvas of={ActionItemStories.Checkable} sourceState="shown" />
+
+## Running an Action
+
+Set `action` to an action descriptor, or a URL string, and the item runs it when activated.
+It reports progress in place: a spinner while an HTTP action is in flight, then a check or a cross, before returning to its label.
+
+```html
+<craft-action-item icon="trash" variant="danger"> Delete </craft-action-item>
+```
+
+```js
+item.action = {
+  type: 'http',
+  method: 'POST',
+  url: '/actions/entries/delete',
+  // Prompts before the request goes out.
+  confirm: 'Delete this entry?',
+};
+item.feedback = {success: {message: 'Deleted'}, error: {message: 'Failed'}};
+```
+
+Confirmation belongs to the action descriptor, not the item.
+`feedback` supplies the messages shown in place of the label, and `feedback-duration` controls how long they stay.
+
+Each transition emits `craft-state-change`, whose `detail` carries the new `state`, the action's `actionType`, and any feedback data — useful when a menu needs to react to an item's progress.
+
+## Theming
+
+An item inherits the palette of any `data-color` ancestor, so a menu can tint its entries without overriding tokens:
+
+<Canvas of={ActionItemStories.Colors} sourceState="shown" />
+
+## Accessibility
+
+The item renders a real `<button>` or `<a>`, so it is focusable and activates on Enter and Space without any help.
+Focus is delegated into the shadow root, which means `item.focus()` lands on the control rather than the host — that is how the parent menu's arrow-key navigation works.
+
+Two things are on you:
+
+- **Give an icon-only item a label.** The default slot is the accessible name. An item with nothing but an `icon` is nameless.
+- **Do not put controls in the `suffix` slot.** The slot sits inside the item's own button, so an interactive suffix nests a control inside a control — a shape assistive technology cannot present, and one that swallows the click meant for the item. The item marks the suffix in red when it finds one, the same way [Button](?path=/docs/components-button--docs) marks itself when it has no accessible name.
+
+## Properties
+
+<ArgTypes of={ActionItemStories} />
diff --git a/packages/craftcms-ui/src/components/action-item/action-item.stories.ts b/packages/craftcms-ui/src/components/action-item/action-item.stories.ts
index 5905df51fed..6ca8949cdfe 100644
--- a/packages/craftcms-ui/src/components/action-item/action-item.stories.ts
+++ b/packages/craftcms-ui/src/components/action-item/action-item.stories.ts
@@ -1,147 +1,150 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import '../icon/icon.js';
 import '../button/button.js';
 import './action-item.js';
+import type CraftActionItem from './action-item.js';
 import {Color} from '@src/constants/colors';
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `action-item.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftActionItem>('craft-action-item');
+
+type ActionItemArgs = CraftActionItem & typeof args;
+
+/** Action items are sized by their menu, so the stories supply one. */
+const stage = (story: () => unknown) => html`
+  <style>
+    .stage {
+      padding: var(--c-spacing-sm);
+      border-radius: var(--c-radius-sm);
+      width: calc(320rem / 16);
+      background-color: var(--c-surface-raised);
+      box-shadow: var(--c-shadow-raised);
+    }
+  </style>
+  <div class="stage">${story()}</div>
+`;
+
 const meta = {
   title: 'Components/Action Item',
   component: 'craft-action-item',
-  argTypes: {},
-  parameters: {
-    layout: 'centered',
-    a11y: {test: 'todo'},
-  },
-  decorators: [
-    (story) => html`
-      <style>
-        .stage {
-          padding: var(--c-spacing-sm);
-          border-radius: var(--c-radius-sm);
-          width: calc(320rem / 16);
-          background-color: var(--c-surface-raised);
-          box-shadow: var(--c-shadow-raised);
-        }
-      </style>
-      <div class="stage">${story()}</div>
-    `,
-  ],
-  render: ({active, indicator, href, icon, checked}) => {
-    return html`
-      <craft-action-item
-        icon="${icon}"
-        ?active="${active}"
-        ?href="${href}"
-        ?checked="${checked}"
-        >View in a new tab</craft-action-item
-      >
-    `;
-  },
-} satisfies Meta<any>;
+  args: {...args, 'default-slot': 'View in a new tab'},
+  argTypes,
+  parameters: {layout: 'centered'},
+  decorators: [stage],
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<ActionItemArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<ActionItemArgs>;
+
+/** A plain item is a button carrying nothing but its label. */
+export const Default: Story = {};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+/** `icon` renders leading artwork before the label. */
+export const WithIcon: Story = {
+  args: {icon: 'up-right-from-square'},
 };
 
+/** `active` marks the entry a menu opens onto, or the option already in effect. */
 export const Active: Story = {
-  args: {
-    active: true,
-  },
+  args: {active: true, icon: 'up-right-from-square'},
 };
 
-export const WithIcon: Story = {
-  args: {
-    icon: 'up-right-from-square',
-  },
+/** `disabled` dims the item and stops it being activated. */
+export const Disabled: Story = {
+  args: {disabled: true, icon: 'up-right-from-square'},
 };
 
-export const WithSuffix: Story = {
-  args: {
-    icon: 'up-right-from-square',
-  },
-  render() {
-    return html`
-      <craft-action-item
-        >View in a new tab
-        <craft-button slot="suffix" size="small">Suffix</craft-button>
-      </craft-action-item>
-    `;
-  },
+/** Setting `href` renders the item as a link rather than a button. */
+export const Link: Story = {
+  args: {href: 'https://craftcms.com', 'default-slot': 'Open craftcms.com'},
 };
 
-export const Link: Story = {
+/** `variant` colors the item — `danger` for a destructive entry. */
+export const Variants: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-action-item icon="pen">Edit</craft-action-item>
+    <craft-action-item icon="trash" variant="danger">Delete</craft-action-item>
+  `,
+};
+
+/**
+ * The `suffix` slot holds trailing content, before any shortcut.
+ *
+ * Note that an interactive suffix nests a control inside the item's own
+ * button, which axe flags as `nested-interactive`. Prefer static content here
+ * until the item renders its suffix outside the button.
+ */
+export const WithSuffix: Story = {
+  // The violation is the component's structure, not this story's markup.
+  parameters: {a11y: {test: 'todo'}},
   args: {
-    href: 'https://craftcms.com',
+    'suffix-slot': '<craft-button size="small">Suffix</craft-button>',
   },
 };
 
+/** A `shortcut` string is shown at the end of the item. It is display only. */
 export const WithShortcut: Story = {
-  args: {},
-  render({icon, active, href, checked}) {
-    return html`
-      <craft-action-item icon="file" shortcut="S"> Save </craft-action-item>
-    `;
-  },
+  args: {icon: 'file', shortcut: 'S', 'default-slot': 'Save'},
 };
 
+/** An object shortcut names its modifiers. */
 export const WithComplexShortcut: Story = {
-  args: {},
-  render() {
-    return html`
-      <craft-action-item
-        icon="file"
-        shortcut='{"key": "S", "alt": true, "shift": true}'
-      >
-        Save
-      </craft-action-item>
-    `;
+  args: {
+    icon: 'file',
+    shortcut: '{"key": "S", "alt": true, "shift": true}',
+    'default-slot': 'Save',
   },
 };
 
-export const CheckableWithIcon: Story = {
-  args: {
-    checked: true,
-    icon: 'up-right-from-square',
-  },
-  render({icon, active, href, checked}) {
-    return html`
-      <craft-action-item icon="home" ?href="${href}" checked type="checkbox">
-        <div>
-          <div class="font-bold">Entry Type</div>
-          <pre>entryType</pre>
-        </div>
-      </craft-action-item>
-      <craft-action-item
-        icon="newspaper"
-        active
-        ?href="${href}"
-        type="checkbox"
-      >
-        <div>
-          <div class="font-bold">Entry Type</div>
-          <pre>entryType</pre>
-        </div>
-      </craft-action-item>
-    `;
-  },
+/**
+ * `type="checkbox"` reserves room for a checkmark before the icon, so a list
+ * of options stays aligned whether or not each one is checked.
+ */
+export const Checkable: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-action-item icon="home" type="checkbox" checked>
+      <div>
+        <div class="font-bold">Entry Type</div>
+        <pre>entryType</pre>
+      </div>
+    </craft-action-item>
+    <craft-action-item icon="newspaper" type="checkbox" active>
+      <div>
+        <div class="font-bold">Entry Type</div>
+        <pre>entryType</pre>
+      </div>
+    </craft-action-item>
+  `,
 };
 
+/** An item inherits the palette of any `data-color` ancestor. */
 export const Colors: Story = {
-  render() {
-    return html`
-      ${Object.entries(Color).map(([name, value]) => {
-        return html`<craft-action-item data-color="${value}"
-          >With color ${name}</craft-action-item
-        >`;
-      })}
-    `;
+  parameters: {
+    controls: {disable: true},
+    // A full-palette grid necessarily includes colors that fall below the
+    // contrast threshold on this surface; that is what the grid is showing.
+    a11y: {test: 'todo'},
   },
+  render: () => html`
+    ${Object.entries(Color).map(
+      ([name, value]) =>
+        html`<craft-action-item data-color="${value}"
+          >With color ${name}</craft-action-item
+        >`
+    )}
+  `,
 };
diff --git a/packages/craftcms-ui/src/components/action-item/action-item.test.ts b/packages/craftcms-ui/src/components/action-item/action-item.test.ts
new file mode 100644
index 00000000000..5436bf94525
--- /dev/null
+++ b/packages/craftcms-ui/src/components/action-item/action-item.test.ts
@@ -0,0 +1,71 @@
+import {expect, test} from 'vite-plus/test';
+import {html, render} from 'lit';
+
+import './action-item.js';
+import '../button/button.js';
+
+async function mount(template: unknown) {
+  const host = document.createElement('div');
+  document.body.append(host);
+  render(template as never, host);
+  const element = host.firstElementChild as HTMLElement & {
+    updateComplete: Promise<unknown>;
+  };
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+function flagged(element: HTMLElement): boolean {
+  return !!element.shadowRoot?.querySelector('.action-item__suffix.a11y-error');
+}
+
+test('a plain suffix is not flagged', async () => {
+  const item = await mount(
+    html`<craft-action-item>
+      Duplicate <span slot="suffix">⌘D</span>
+    </craft-action-item>`
+  );
+
+  expect(flagged(item)).toBe(false);
+});
+
+test('an empty suffix is not flagged', async () => {
+  const item = await mount(
+    html`<craft-action-item>Duplicate</craft-action-item>`
+  );
+
+  expect(flagged(item)).toBe(false);
+});
+
+test('a button in the suffix is flagged', async () => {
+  const item = await mount(
+    html`<craft-action-item>
+      Duplicate
+      <craft-button slot="suffix" aria-label="More">…</craft-button>
+    </craft-action-item>`
+  );
+
+  expect(flagged(item)).toBe(true);
+});
+
+test('a native control in the suffix is flagged', async () => {
+  const item = await mount(
+    html`<craft-action-item>
+      Duplicate <input slot="suffix" aria-label="Rename" />
+    </craft-action-item>`
+  );
+
+  expect(flagged(item)).toBe(true);
+});
+
+test('a link in the suffix is flagged', async () => {
+  const item = await mount(
+    html`<craft-action-item>
+      Duplicate <a slot="suffix" href="/help">Help</a>
+    </craft-action-item>`
+  );
+
+  expect(flagged(item)).toBe(true);
+});
diff --git a/packages/craftcms-ui/src/components/action-item/action-item.ts b/packages/craftcms-ui/src/components/action-item/action-item.ts
index dae63b07ae1..7da5605e925 100644
--- a/packages/craftcms-ui/src/components/action-item/action-item.ts
+++ b/packages/craftcms-ui/src/components/action-item/action-item.ts
@@ -3,9 +3,13 @@ import {property, state} from 'lit/decorators.js';
 import styles from './action-item.styles.js';
 import {type AsyncState, AsyncStates} from '@src/types';
 import variantsStyles from '@src/styles/variants.styles';
+import {LightDomController} from '@src/controllers/LightDomController';
+import a11yErrorStyles from '@src/styles/a11y-error.styles.js';
 import {classMap} from 'lit/directives/class-map.js';
 
 import '../shortcut/shortcut.js';
+import '../icon/icon.js';
+import '../spinner/spinner.js';
 import {
   type ActionFeedback,
   type BaseAction,
@@ -15,11 +19,42 @@ import {
 } from '@src/actions';
 import {Variant, type VariantValue} from '@src/constants/variants';
 
+/** Anything that takes focus, and so cannot sit inside the item's own button. */
+const INTERACTIVE = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  '[tabindex]:not([tabindex="-1"])',
+  'craft-button',
+  'craft-action-item',
+  'craft-checkbox',
+  'craft-switch',
+].join(', ');
+
 /**
- * @summary Either a link or button typically used in a menu.
+ * @summary A single entry in a menu, rendered as a button or — when `href` is
+ * set — as a link. Action items carry an optional leading icon, a label, an
+ * optional trailing shortcut or suffix, and can run an action on click.
+ *
+ * When `action` is set the item runs it on click and reports progress in
+ * place: a spinner while an HTTP action is in flight, then a check or a cross,
+ * before returning to its label. `feedback` supplies the messages and
+ * `feedback-duration` controls how long they stay.
+ *
+ * @slot - The item's label.
+ * @slot icon - Leading artwork, replacing the icon `icon` would render.
+ * @slot checkmark - The checked indicator, shown when `type` is `checkbox`.
+ *   Defaults to a check icon while `checked` is set.
+ * @slot suffix - Trailing content, shown before the shortcut.
+ *
+ * @fires {CustomEvent} craft-state-change - Emitted whenever the item's
+ *   action moves between idle, loading, success, and error. `detail` carries
+ *   the new `state`, the action's `actionType`, and any feedback data.
  */
 export default class CraftActionItem extends LitElement {
-  static override styles = [variantsStyles, styles];
+  static override styles = [variantsStyles, a11yErrorStyles, styles];
 
   /**
    * Delegate focus into the shadow root, so `host.focus()` (used by
@@ -31,28 +66,65 @@ export default class CraftActionItem extends LitElement {
     delegatesFocus: true,
   };
 
+  /** Name of the icon to render before the label. */
   @property() icon: string | null = null;
+
   /**
    * Optional Craft color name used to tint the item's icon. The icon renders
    * with `currentColor`, so we set the icon element's `color` to a matching
    * `--c-color-*` token.
    */
   @property({attribute: 'icon-color'}) iconColor: string | null = null;
+
+  /** Renders the item as a link to this URL instead of as a button. */
   @property() href: string | null = null;
+
+  /** Prevents the item from being activated, and dims it. */
   @property({type: Boolean}) disabled: boolean = false;
+
+  /**
+   * The semantic color group the item draws its tokens from. `danger` is the
+   * one to reach for on a destructive entry.
+   */
   @property({reflect: true}) variant: VariantValue = Variant.Neutral;
+
+  /** Whether a `checkbox` item is checked. Ignored for a `button` item. */
   @property({type: Boolean}) checked: boolean = false;
-  @property({type: Boolean}) active: boolean = false;
+
+  /**
+   * Marks the item as the current one — the entry a menu opens onto, or the
+   * option already in effect. Reflected so it can be styled from outside.
+   */
+  @property({type: Boolean, reflect: true}) active: boolean = false;
+
+  /**
+   * `checkbox` reserves room for a checkmark before the icon, so a list of
+   * options stays aligned whether or not each one is checked.
+   */
   @property() type: 'button' | 'checkbox' = 'button';
+
+  /**
+   * The action to run when the item is activated. Accepts an action
+   * descriptor or a URL string. A descriptor's own `confirm` prompts before
+   * the action runs.
+   */
   @property({type: Object}) action: BaseAction | string | null = null;
+
+  /** Messages shown in place of the label after an action succeeds or fails. */
   @property({type: Object}) feedback: ActionFeedback | null = null;
+
+  /** How long feedback stays before the item returns to idle, in milliseconds. */
   @property({type: Number, attribute: 'feedback-duration'})
   feedbackDuration: number = 1000;
-  @property() confirm: string | null = null;
 
   @state() private state: AsyncState = AsyncStates.Idle;
   @state() private feedbackMessage: string | null = null;
 
+  /**
+   * A keyboard shortcut shown at the end of the item. Either a plain string
+   * (`"S"`, `"ctrl+k"`) or an object naming the modifiers. Display only — the
+   * item does not bind the key.
+   */
   @property({
     converter: {
       fromAttribute(value: string | null) {
@@ -80,7 +152,7 @@ export default class CraftActionItem extends LitElement {
   shortcut: string | {alt?: boolean; shift?: boolean; key: string} | null =
     null;
 
-  renderShortcut() {
+  protected renderShortcut() {
     if (typeof this.shortcut === 'string') {
       return html`<craft-shortcut>${this.shortcut}</craft-shortcut>`;
     }
@@ -106,12 +178,20 @@ export default class CraftActionItem extends LitElement {
     this.removeEventListener('click', this);
   }
 
+  /**
+
+   * Moves the item into an async state, optionally with feedback to announce.
+   * Called by the item itself while running an action; call it directly when
+   * driving the item from outside.
+
+   */
+
   setState(state: AsyncState, detail: FeedbackData = {}) {
     this.state = state;
     this.feedbackMessage = detail.message ?? null;
 
     this.dispatchEvent(
-      new CustomEvent('action:change-state', {
+      new CustomEvent('craft-state-change', {
         bubbles: true,
         composed: true,
         detail: {
@@ -123,6 +203,13 @@ export default class CraftActionItem extends LitElement {
     );
   }
 
+  /**
+
+   * The DOM `EventListener` interface, so the item can be passed to
+   * `addEventListener()` directly. Runs the item's action.
+
+   */
+
   async handleEvent(event: Event) {
     if (this.disabled) {
       event.preventDefault();
@@ -153,7 +240,7 @@ export default class CraftActionItem extends LitElement {
     }
   }
 
-  renderCheckbox() {
+  protected renderCheckbox() {
     return html`<span class="action-item__check">
       <slot name="checkmark">
         ${this.checked ? html`<craft-icon name="check"></craft-icon>` : nothing}
@@ -161,7 +248,7 @@ export default class CraftActionItem extends LitElement {
     </span>`;
   }
 
-  renderIcon() {
+  protected renderIcon() {
     switch (this.state) {
       case AsyncStates.Loading:
         return html`<craft-spinner style="--size: 0.8em"></craft-spinner>`;
@@ -191,7 +278,7 @@ export default class CraftActionItem extends LitElement {
     }
   }
 
-  renderPrefix() {
+  protected renderPrefix() {
     const hasIcon = !!this.querySelector('[slot="icon"]') || !!this.icon;
 
     return html`
@@ -202,7 +289,34 @@ export default class CraftActionItem extends LitElement {
     `;
   }
 
-  renderBody() {
+  /**
+   * Whether something focusable has been slotted into `suffix`. The slot sits
+   * inside the item's own button or link, so a control there nests a control
+   * inside a control — a shape assistive technology cannot present, and one
+   * that swallows the click meant for the item.
+   *
+   * Flagged the way `craft-button` flags a button with no accessible name:
+   * loudly, in the place it went wrong, because it is a mistake to fix rather
+   * than a state to handle.
+   */
+  @state() private _hasNestedControl = false;
+
+  /**
+   * Re-checks whenever the light DOM moves, rather than on `slotchange`:
+   * content is commonly slotted in after the item mounts, and a menu built at
+   * runtime is exactly where this mistake gets made.
+   */
+  private _lightDom = new LightDomController(this, {
+    onChange: () => this._checkSuffixForControls(),
+  });
+
+  private _checkSuffixForControls() {
+    this._hasNestedControl = Array.from(this.children).some(
+      (child) => child.slot === 'suffix' && child.matches(INTERACTIVE)
+    );
+  }
+
+  protected renderBody() {
     return html`
       ${this.renderPrefix()}
 
@@ -210,7 +324,12 @@ export default class CraftActionItem extends LitElement {
         ${this.feedbackMessage ? this.feedbackMessage : html`<slot></slot>`}
       </span>
 
-      <span class="action-item__suffix">
+      <span
+        class="${classMap({
+          'action-item__suffix': true,
+          'a11y-error': this._hasNestedControl,
+        })}"
+      >
         <slot name="suffix"></slot>
         ${this.shortcut ? this.renderShortcut() : nothing}
       </span>
diff --git a/packages/craftcms-ui/src/components/action-menu/ActionMenu.mdx b/packages/craftcms-ui/src/components/action-menu/ActionMenu.mdx
new file mode 100644
index 00000000000..d4c42c9e008
--- /dev/null
+++ b/packages/craftcms-ui/src/components/action-menu/ActionMenu.mdx
@@ -0,0 +1,76 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ActionMenuStories from './action-menu.stories';
+
+<Meta of={ActionMenuStories} name="Docs" />
+
+# Action Menu
+
+`<craft-action-menu>` is a menu of actions, built on [Popover](?path=/docs/components-popover--docs).
+
+<Canvas of={ActionMenuStories.Default} sourceState="shown" />
+
+It is where per-object actions live throughout the control panel — the ellipsis button on a chip, a card, or an index row.
+
+## Two Modes
+
+**Slot-based**, where you author the items yourself:
+
+<Canvas of={ActionMenuStories.Default} sourceState="shown" />
+
+**Data-driven**, where you set the `actions` property and the component builds the menu:
+
+<Canvas of={ActionMenuStories.DataDriven} sourceState="shown" />
+
+Prefer data-driven where the actions come from data, which is most of the time — it handles the sorting, the dividers, and the item rendering. Note that `danger` items sort to the bottom automatically, so a destructive action is never adjacent to a routine one.
+
+`actions` is a property rather than an attribute, so bind it with `.actions`.
+
+<Canvas of={ActionMenuStories.DataDrivenWithDisplay} sourceState="shown" />
+
+## The Invoker
+
+A default invoker is generated, and a slotted one replaces it:
+
+<Canvas
+  of={ActionMenuStories.DataDrivenWithCustomInvoker}
+  sourceState="shown"
+/>
+
+<Canvas of={ActionMenuStories.DataDrivenDisabled} sourceState="shown" />
+
+<Canvas of={ActionMenuStories.SlotBasedDisabled} sourceState="shown" />
+
+## Searching
+
+<Canvas of={ActionMenuStories.Searchable} sourceState="shown" />
+
+<Canvas of={ActionMenuStories.SearchableDataDriven} sourceState="shown" />
+
+`searchable` adds a filter, for menus long enough that scanning is work.
+
+<Canvas of={ActionMenuStories.SearchableWithHiddenItems} sourceState="shown" />
+
+Items can carry extra search terms — a handle, an alias — so a person can find an entry by something other than its visible label.
+
+## Keyboard
+
+The menu follows the WAI-ARIA menu-button pattern, adapted:
+
+- Opening moves focus to the search input when `searchable`, or to the first item otherwise
+- Arrow keys move through the items, wrapping
+- From the search input, Down and Up jump to the first and last item
+- Home and End jump to the ends
+- Typing while an item is focused returns to the search input
+- Escape clears the filter first, then closes
+
+That last one is deliberate: a filtered menu has two states to leave, and closing outright would discard the filter and the menu together.
+
+## Accessibility
+
+The `change` event carries the chosen item in `detail.item` — the descriptor in data-driven mode, the element in slot-based mode.
+
+Give the invoker a real name. The generated one is labelled, but a custom invoker is yours to name, and an unnamed ellipsis button is announced as nothing at all.
+
+## Properties
+
+<ArgTypes of={ActionMenuStories} />
diff --git a/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts b/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts
index cc659624a5f..0c3b1d60054 100644
--- a/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts
+++ b/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts
@@ -1,5 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 import {ref} from 'lit/directives/ref.js';
 
@@ -11,10 +13,21 @@ import type CraftActionMenu from './action-menu.js';
 import type {ActionMenuItem} from './action-menu.types.js';
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `action-menu.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftActionMenu>('craft-action-menu');
+
+type CraftActionMenuArgs = CraftActionMenu & typeof args;
+
 const meta = {
   title: 'Components/Action Menu',
   component: 'craft-action-menu',
-  argTypes: {},
+  args,
+  argTypes,
   render: ({label, open}) => {
     return html`
       <craft-action-menu ?opened="${open}">
@@ -51,10 +64,10 @@ const meta = {
       </craft-action-menu>
     `;
   },
-} satisfies Meta<any>;
+} satisfies Meta<CraftActionMenuArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftActionMenuArgs>;
 
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
 export const Default: Story = {
diff --git a/packages/craftcms-ui/src/components/action-menu/action-menu.ts b/packages/craftcms-ui/src/components/action-menu/action-menu.ts
index 55f79c0efea..f0e5c3c2da5 100644
--- a/packages/craftcms-ui/src/components/action-menu/action-menu.ts
+++ b/packages/craftcms-ui/src/components/action-menu/action-menu.ts
@@ -15,7 +15,7 @@ import type {
 
 import '../action-item/action-item.js';
 
-export type ActionMenuChangeDetail =
+export type ActionMenuSelectDetail =
   | {item: ActionMenuItemButton | ActionMenuItemLink}
   | {item: CraftActionItem};
 
@@ -61,7 +61,7 @@ export type {
  * @slot invoker - Element that triggers the menu.
  * @slot content - Action items to be rendered in the menu.
  *
- * @fires {CustomEvent<ActionMenuChangeDetail>} change - Emitted when the user
+ * @fires {CustomEvent<ActionMenuSelectDetail>} craft-select - Emitted when the user
  *   clicks an item. In data-driven mode `event.detail.item` is the
  *   `ActionMenuItemButton` or `ActionMenuItemLink` descriptor; in slot-based
  *   mode it is the clicked `craft-action-item` element.
@@ -132,10 +132,10 @@ export default class CraftActionMenu extends CraftPopover {
   @property({type: Boolean, reflect: true}) searchable = false;
 
   @queryAssignedElements({slot: 'invoker'})
-  invokerNodes!: HTMLElement[];
+  protected invokerNodes!: HTMLElement[];
 
   @queryAssignedElements({slot: 'content'})
-  contentNodes!: HTMLElement[];
+  protected contentNodes!: HTMLElement[];
 
   private uid: string = uuid();
 
@@ -166,7 +166,7 @@ export default class CraftActionMenu extends CraftPopover {
       .forEach((item) => {
         item.addEventListener('click', () => {
           this.opened = false;
-          // In data-driven mode the 'change' event is dispatched from
+          // In data-driven mode the 'craft-select' event is dispatched from
           // _renderItem (which has access to the descriptor). For slot-based
           // mode this is the only click handler, so dispatch it here.
           if (this.actions === undefined) {
@@ -180,10 +180,10 @@ export default class CraftActionMenu extends CraftPopover {
     item: ActionMenuItemButton | ActionMenuItemLink | CraftActionItem
   ): void {
     this.dispatchEvent(
-      new CustomEvent<ActionMenuChangeDetail>('change', {
+      new CustomEvent<ActionMenuSelectDetail>('craft-select', {
         bubbles: true,
         composed: true,
-        detail: {item} as ActionMenuChangeDetail,
+        detail: {item} as ActionMenuSelectDetail,
       })
     );
   }
diff --git a/packages/craftcms-ui/src/components/avatar/Avatar.mdx b/packages/craftcms-ui/src/components/avatar/Avatar.mdx
new file mode 100644
index 00000000000..0c6e850b04d
--- /dev/null
+++ b/packages/craftcms-ui/src/components/avatar/Avatar.mdx
@@ -0,0 +1,42 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as AvatarStories from './avatar.stories';
+
+<Meta of={AvatarStories} name="Docs" />
+
+# Avatar
+
+`<craft-avatar>` stands in for a person or an object with their initials on a gradient disc.
+
+<Canvas of={AvatarStories.Default} sourceState="shown" />
+
+It draws initials rather than loading a picture, which makes it the right choice where there may not be one — a user with no photo, an object with no thumbnail. When there _is_ an image, use [Thumbnail](?path=/docs/components-thumbnail--docs).
+
+## Initials
+
+The initials come from `label`: one capital per word, so "Brad Bell" gives BB.
+
+<Canvas of={AvatarStories.SingleName} sourceState="shown" />
+
+Without a label there is nothing to derive them from, and the avatar shows a question mark:
+
+<Canvas of={AvatarStories.NoLabel} sourceState="shown" />
+
+That fallback is a signal, not a design. Treat a question mark as a missing `label` rather than as a placeholder to leave in place.
+
+## Sizing and Colour
+
+Size and the two gradient stops are custom properties, so a set of avatars can be themed together:
+
+<Canvas of={AvatarStories.Themed} sourceState="shown" />
+
+## Accessibility
+
+A labelled avatar is an SVG with `role="img"` whose title is the label, so it is announced as the person it represents rather than as two letters.
+
+Without a label there is nothing to announce, so the disc is `aria-hidden` instead of being exposed as an unnamed image — the same rule [Icon](?path=/docs/components-icon--docs) follows.
+
+Where an avatar sits beside the same name in text, the name would be announced twice. That is the case for leaving the label off deliberately.
+
+## Properties
+
+<ArgTypes of={AvatarStories} />
diff --git a/packages/craftcms-ui/src/components/avatar/avatar.stories.ts b/packages/craftcms-ui/src/components/avatar/avatar.stories.ts
index ff86d955749..293a0358008 100644
--- a/packages/craftcms-ui/src/components/avatar/avatar.stories.ts
+++ b/packages/craftcms-ui/src/components/avatar/avatar.stories.ts
@@ -1,62 +1,56 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
-import type CraftAvatar from './avatar.js';
+
 import {html} from 'lit';
 import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
-const {events, args, argTypes, template} = getStorybookHelpers('craft-avatar');
+
 import './avatar.js';
+import type CraftAvatar from './avatar.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftAvatar>('craft-avatar');
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
-const meta: Meta<CraftAvatar> = {
+type AvatarArgs = CraftAvatar & typeof args;
+
+const meta = {
   title: 'Components/Avatar',
   component: 'craft-avatar',
-  args,
+  args: {...args, label: 'Brad Bell'},
   argTypes,
+  parameters: {layout: 'centered'},
   render: (args) => template(args),
-  parameters: {
-    actions: {
-      handles: events,
-    },
-  },
-};
+} satisfies Meta<AvatarArgs>;
 
 export default meta;
-type Story = StoryObj<CraftAvatar & typeof args>;
-
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-  parameters: {
-    a11y: {
-      config: {
-        rules: [
-          {
-            id: 'svg-img-alt', // TODO: figure out best way of handling alt text for avatars
-            enabled: false,
-          },
-        ],
-      },
-    },
-  },
+type Story = StoryObj<AvatarArgs>;
+
+/** Initials are derived from the label — one letter per word. */
+export const Default: Story = {};
+
+/** A single-word label gives a single initial. */
+export const SingleName: Story = {
+  args: {label: 'Craft'},
 };
 
-export const CustomColors: Story = {
-  args: {
-    colorStart: 'green',
-    colorEnd: 'black',
-  },
-  render: (args) => html`
-    <craft-avatar
-      style="--color-start: ${args.colorStart}; --color-end: ${args.colorEnd}"
-      label="Brian Hanson"
-    ></craft-avatar>
-  `,
+/** Without a label the avatar falls back to a question mark. */
+export const NoLabel: Story = {
+  args: {label: null},
 };
 
-export const CustomSize: Story = {
-  args: {},
-  render: (args) => html`
-    <craft-avatar label="Brian Hanson">BH</craft-avatar>
-    <craft-avatar style="--size: 60px;" label="M">MD</craft-avatar>
-    <craft-avatar style="--size: 100px;" label="LG">LG</craft-avatar>
+/** Size and colours are custom properties, so a set can be themed at once. */
+export const Themed: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; gap: 0.75rem; align-items: center">
+      <craft-avatar label="Brad Bell"></craft-avatar>
+      <craft-avatar label="Ryan Irelan" style="--size: 3rem"></craft-avatar>
+      <craft-avatar
+        label="Sara Fisher"
+        style="--size: 3rem; --c-avatar-color-start: #7ab55c; --c-avatar-color-end: #2e7d5b"
+      ></craft-avatar>
+    </div>
   `,
 };
diff --git a/packages/craftcms-ui/src/components/avatar/avatar.styles.ts b/packages/craftcms-ui/src/components/avatar/avatar.styles.ts
index d4731ec3b7c..64c04c9676b 100644
--- a/packages/craftcms-ui/src/components/avatar/avatar.styles.ts
+++ b/packages/craftcms-ui/src/components/avatar/avatar.styles.ts
@@ -2,9 +2,9 @@ import {css} from 'lit';
 
 export default css`
   :host {
-    --color-start: red;
-    --color-end: blue;
-    --color-text: inherit;
+    --c-avatar-color-start: red;
+    --c-avatar-color-end: blue;
+    --c-avatar-color-text: inherit;
 
     --size: calc(30rem / 16);
     display: contents;
diff --git a/packages/craftcms-ui/src/components/avatar/avatar.test.ts b/packages/craftcms-ui/src/components/avatar/avatar.test.ts
new file mode 100644
index 00000000000..80313a317f5
--- /dev/null
+++ b/packages/craftcms-ui/src/components/avatar/avatar.test.ts
@@ -0,0 +1,68 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './avatar.js';
+import type CraftAvatar from './avatar.js';
+
+async function createAvatar(
+  attrs: Record<string, string> = {},
+  innerHTML = 'BH'
+): Promise<CraftAvatar> {
+  const element = document.createElement('craft-avatar') as CraftAvatar;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function svg(element: CraftAvatar): SVGElement {
+  return element.shadowRoot!.querySelector('svg')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-avatar', () => {
+  it('renders the gradient artwork', async () => {
+    const element = await createAvatar();
+
+    expect(svg(element)).toBeTruthy();
+    expect(element.shadowRoot!.querySelector('linearGradient')).toBeTruthy();
+  });
+
+  /**
+   * An avatar that names nothing is decoration beside the name it sits next to,
+   * so it is hidden rather than announced as an unnamed image.
+   */
+  it('is hidden from assistive technology without a label', async () => {
+    const element = await createAvatar();
+
+    expect(svg(element).getAttribute('aria-hidden')).toBe('true');
+    expect(svg(element).getAttribute('role')).toBeNull();
+    expect(element.shadowRoot!.querySelector('title')).toBeNull();
+  });
+
+  it('becomes a named image once it has a label', async () => {
+    const element = await createAvatar({label: 'Brian Hanson'});
+
+    expect(svg(element).getAttribute('role')).toBe('img');
+    expect(svg(element).getAttribute('aria-hidden')).toBeNull();
+    expect(element.shadowRoot!.querySelector('title')?.textContent).toBe(
+      'Brian Hanson'
+    );
+  });
+
+  it('gives each instance its own gradient id, so they do not collide', async () => {
+    const first = await createAvatar();
+    const second = await createAvatar();
+
+    const id = (element: CraftAvatar) =>
+      element.shadowRoot!.querySelector('linearGradient')!.id;
+
+    expect(id(first)).not.toBe('');
+    expect(id(first)).not.toBe(id(second));
+  });
+});
diff --git a/packages/craftcms-ui/src/components/avatar/avatar.ts b/packages/craftcms-ui/src/components/avatar/avatar.ts
index 90fb8bc575e..2238a6bb17b 100644
--- a/packages/craftcms-ui/src/components/avatar/avatar.ts
+++ b/packages/craftcms-ui/src/components/avatar/avatar.ts
@@ -1,15 +1,23 @@
 import {property, state} from 'lit/decorators.js';
 import type {CSSResultGroup} from 'lit';
-import {html, LitElement} from 'lit';
+import {html, LitElement, nothing} from 'lit';
 import styles from './avatar.styles.js';
 
 /**
- * @summary Container to represent a user or object
+ * @summary Stands in for a user or object with their initials on a gradient
+ * disc. Draws initials rather than loading a picture, so it works where there
+ * may not be one — use `craft-thumbnail` when there is.
  *
- * @cssproperty [--color-start=red] - Start color of the gradient
- * @cssproperty [--color-end=blue] - End color of the gradient
- * @cssproperty [--color-text=currentColor] - Color of the text
- * @cssproperty [--size=calc(30rem / 16)] - Overall size of the avatar. Defaults to 30px.
+ * Without a `label` there are no initials to draw and nothing to announce, so
+ * the disc falls back to a question mark and is hidden from assistive
+ * technology rather than exposed as an unnamed image.
+ *
+ * @cssproperty [--c-avatar-color-start=red] - The gradient's start colour.
+ * @cssproperty [--c-avatar-color-end=blue] - The gradient's end colour.
+ * @cssproperty [--c-avatar-color-text=inherit] - The initials' colour.
+ * @cssproperty [--size=calc(30rem / 16)] - The avatar's overall size, 30px by
+ * default. Shared with the other square components — spinner, status, indicator —
+ * so one declaration can size a row of them together.
  */
 export default class CraftAvatar extends LitElement {
   static override styles: CSSResultGroup = [styles];
@@ -44,9 +52,10 @@ export default class CraftAvatar extends LitElement {
         <svg
           viewBox="0 0 100 100"
           xmlns="http://www.w3.org/2000/svg"
-          role="img"
+          role="${this.label ? 'img' : nothing}"
+          aria-hidden="${this.label ? nothing : 'true'}"
         >
-          ${this.label ? html`<title>${this.label}</title>` : ''}
+          ${this.label ? html`<title>${this.label}</title>` : nothing}
           <defs>
             <linearGradient
               id="${this._gradientId}"
@@ -55,8 +64,14 @@ export default class CraftAvatar extends LitElement {
               x2="1"
               y2="0"
             >
-              <stop offset="0%" style="stop-color:var(--color-start)"></stop>
-              <stop offset="100%" style="stop-color:var(--color-end)"></stop>
+              <stop
+                offset="0%"
+                style="stop-color:var(--c-avatar-color-start)"
+              ></stop>
+              <stop
+                offset="100%"
+                style="stop-color:var(--c-avatar-color-end)"
+              ></stop>
             </linearGradient>
           </defs>
           <circle
diff --git a/packages/craftcms-ui/src/components/badge-indicator/BadgeIndicator.mdx b/packages/craftcms-ui/src/components/badge-indicator/BadgeIndicator.mdx
new file mode 100644
index 00000000000..f16d72eb2dd
--- /dev/null
+++ b/packages/craftcms-ui/src/components/badge-indicator/BadgeIndicator.mdx
@@ -0,0 +1,49 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as BadgeIndicatorStories from './badge-indicator.stories';
+
+<Meta of={BadgeIndicatorStories} name="Docs" />
+
+# Badge Indicator
+
+`<craft-badge-indicator>` marks something as new or changed, with an optional count.
+
+<Canvas of={BadgeIndicatorStories.Dot} sourceState="shown" />
+
+It attaches to whatever it sits beside — a nav item, a tab, a button — and says only "there is something here".
+
+<Canvas of={BadgeIndicatorStories.Numbered} sourceState="shown" />
+
+## Not the Same as Badge
+
+[Badge](?path=/docs/components-badge--docs) is a pill with a label, naming a state in place. This is a marker that draws attention to something else.
+
+If the thing needs naming, use a badge. If it needs pointing at, use this.
+
+## Variants
+
+<Canvas of={BadgeIndicatorStories.Primary} sourceState="shown" />
+
+<Canvas of={BadgeIndicatorStories.Secondary} sourceState="shown" />
+
+<Canvas of={BadgeIndicatorStories.Inverse} sourceState="shown" />
+
+`inverse` is for placing the badge on a dark or coloured surface, where the primary treatment would disappear.
+
+## Accessibility
+
+A bare dot conveys nothing — it is a coloured shape with no text.
+
+`alt-text` is what gives it meaning, and it is worth setting whenever the badge is not immediately beside text that already explains it.
+
+For a count, `badge-count-suffix` supplies the units, because a number alone is ambiguous:
+
+```html
+<craft-badge-indicator badge-count="3" badge-count-suffix="unread messages">
+</craft-badge-indicator>
+```
+
+Announced as "3 unread messages" rather than "3", which could be anything.
+
+## Properties
+
+<ArgTypes of={BadgeIndicatorStories} />
diff --git a/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.stories.ts b/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.stories.ts
index 38ed1a1dd14..e04cf07383b 100644
--- a/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.stories.ts
+++ b/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.stories.ts
@@ -1,93 +1,57 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './badge-indicator.js';
+import type CraftBadgeIndicator from './badge-indicator.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `badge-indicator.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftBadgeIndicator>(
+  'craft-badge-indicator'
+);
+
+type BadgeIndicatorArgs = CraftBadgeIndicator & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Badge Indicator',
   component: 'craft-badge-indicator',
-  args: {
-    variant: 'primary',
-    altText: 'Has Notifications',
-    badgeCount: null,
-  },
-  argTypes: {
-    badgeCount: {
-      control: {
-        type: 'number',
-      },
-    },
-    variant: {
-      options: ['primary', 'secondary', 'inverse'],
-      control: {
-        type: 'radio',
-      },
-    },
-    altText: {
-      control: {
-        type: 'text',
-      },
-    },
-  },
-  render: (args) => html`
-    <craft-badge-indicator
-      .badgeCount="${args.badgeCount}"
-      .badgeCountSuffix="${args.badgeCountSuffix}"
-      .altText="${args.altText}"
-      .variant="${args.variant}"
-    ></craft-badge-indicator>
-  `,
-} satisfies Meta<any>;
+  args: {...args, variant: 'primary', 'alt-text': 'Has notifications'},
+  argTypes,
+  // Render from args alone so every control drives the story. Stories below
+  // vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<BadgeIndicatorArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
-
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+type Story = StoryObj<BadgeIndicatorArgs>;
 
-export const Dot: Story = {
-  name: 'Dot',
-  parameters: {
-    controls: {exclude: ['badgeCount', 'badgeCountSuffix']},
-  },
-};
+/** With no count, the indicator is a bare dot. */
+export const Dot: Story = {};
 
+/** A `badge-count` turns it into a number. */
 export const Numbered: Story = {
-  name: 'Numbered',
   args: {
-    altText: null,
-    badgeCount: 5,
-    badgeCountSuffix: 'updates',
-  },
-  parameters: {
-    controls: {exclude: ['altText']},
+    'alt-text': null,
+    'badge-count': 5,
+    'badge-count-suffix': 'updates',
   },
 };
 
+/** The default variant, for the standard surface. */
 export const Primary: Story = {
-  name: 'Primary',
-  parameters: {
-    controls: {exclude: ['badgeCount', 'badgeCountSuffix']},
-  },
+  args: {variant: 'primary', 'badge-count': 3},
 };
 
+/** A quieter variant, for a surface that already carries emphasis. */
 export const Secondary: Story = {
-  name: 'Secondary',
-  args: {
-    variant: 'secondary',
-  },
-  parameters: {
-    controls: {exclude: ['badgeCount', 'badgeCountSuffix']},
-  },
+  args: {variant: 'secondary', 'badge-count': 3},
 };
 
+/** An inverse indicator, for a dark surface. */
 export const Inverse: Story = {
-  name: 'Inverse',
-  args: {
-    variant: 'inverse',
-  },
-  parameters: {
-    controls: {exclude: ['badgeCount', 'badgeCountSuffix']},
-  },
+  args: {variant: 'inverse', 'badge-count': 12},
 };
diff --git a/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.test.ts b/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.test.ts
new file mode 100644
index 00000000000..5e802c3add6
--- /dev/null
+++ b/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.test.ts
@@ -0,0 +1,109 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './badge-indicator.js';
+import type CraftBadgeIndicator from './badge-indicator.js';
+
+async function createBadgeIndicator(
+  attrs: Record<string, string> = {}
+): Promise<CraftBadgeIndicator> {
+  const element = document.createElement(
+    'craft-badge-indicator'
+  ) as CraftBadgeIndicator;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function badge(element: CraftBadgeIndicator): HTMLElement {
+  return element.shadowRoot!.querySelector('[part="badge"]')!;
+}
+
+function number(element: CraftBadgeIndicator): string | null {
+  return (
+    element.shadowRoot!.querySelector('.number')?.textContent?.trim() ?? null
+  );
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-badge-indicator', () => {
+  it('is a bare dot with no count', async () => {
+    const element = await createBadgeIndicator();
+
+    expect(number(element)).toBeNull();
+    expect(
+      badge(element).classList.contains('badge-indicator--with-number')
+    ).toBe(false);
+  });
+
+  it('shows a count once there is one', async () => {
+    const element = await createBadgeIndicator({'badge-count': '5'});
+
+    expect(number(element)).toBe('5');
+    expect(
+      badge(element).classList.contains('badge-indicator--with-number')
+    ).toBe(true);
+  });
+
+  /** A zero count is nothing to report, so it stays a dot. */
+  it('stays a dot at zero', async () => {
+    const element = await createBadgeIndicator({'badge-count': '0'});
+
+    expect(number(element)).toBeNull();
+  });
+
+  /** Past 99 the exact number stops being useful and would not fit. */
+  it('caps the count at 99+', async () => {
+    expect(number(await createBadgeIndicator({'badge-count': '99'}))).toBe(
+      '99'
+    );
+    expect(number(await createBadgeIndicator({'badge-count': '100'}))).toBe(
+      '99+'
+    );
+  });
+
+  it('carries a modifier class for each variant', async () => {
+    for (const variant of ['secondary', 'inverse']) {
+      const element = await createBadgeIndicator({variant});
+
+      expect(
+        badge(element).classList.contains(`badge-indicator--${variant}`)
+      ).toBe(true);
+    }
+  });
+
+  /**
+   * Without alt text the indicator is decoration beside whatever it marks, so
+   * it is not announced as an unnamed image.
+   */
+  it('is not an image without alt text', async () => {
+    const element = await createBadgeIndicator({'badge-count': '5'});
+
+    expect(badge(element).getAttribute('role')).toBeNull();
+  });
+
+  it('becomes a named image once it has alt text', async () => {
+    const element = await createBadgeIndicator({'alt-text': 'Has updates'});
+
+    expect(badge(element).getAttribute('role')).toBe('img');
+    expect(badge(element).getAttribute('aria-labelledby')).toBe(
+      `${element.id}-label`
+    );
+    expect(
+      element.shadowRoot!.querySelector(`#${element.id}-label`)?.textContent
+    ).toBe('Has updates');
+  });
+
+  it('gives each instance an id, so its label can be referenced', async () => {
+    const first = await createBadgeIndicator();
+    const second = await createBadgeIndicator();
+
+    expect(first.id).not.toBe('');
+    expect(first.id).not.toBe(second.id);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.ts b/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.ts
index 58df8f0fbef..61c34515aa5 100644
--- a/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.ts
+++ b/packages/craftcms-ui/src/components/badge-indicator/badge-indicator.ts
@@ -5,9 +5,12 @@ import {classMap} from 'lit/directives/class-map.js';
 import '@shoelace-style/shoelace/dist/components/visually-hidden/visually-hidden.js';
 
 /**
- * @summary A badge indicator component. Used in various places to indicate that
- * something is new or has been updated. The indicator can have an optional
- * notification count.
+ * @summary A small marker showing that something is new or has changed, with
+ * an optional count.
+ *
+ * It attaches to whatever it sits beside — a nav item, a tab, a button — and
+ * says only "there is something here". What that something is has to come from
+ * the text around it or from `alt-text`.
  */
 
 export default class CraftBadgeIndicator extends LitElement {
@@ -26,6 +29,10 @@ export default class CraftBadgeIndicator extends LitElement {
   /** Theme variant of the badge indicator. Defaults to "primary" */
   @property() variant: 'primary' | 'secondary' | 'inverse' = 'primary';
 
+  /**
+   * Id of the badge, so the element it marks can reference it. Generated when
+   * not supplied.
+   */
   @property()
   override id: string;
 
diff --git a/packages/craftcms-ui/src/components/badge/Badge.mdx b/packages/craftcms-ui/src/components/badge/Badge.mdx
index 86d0e54e33e..d8d3b8aafd0 100644
--- a/packages/craftcms-ui/src/components/badge/Badge.mdx
+++ b/packages/craftcms-ui/src/components/badge/Badge.mdx
@@ -1,194 +1,61 @@
-import {Canvas, Meta} from '@storybook/addon-docs/blocks';
-import BadgeMeta, {
-  Default,
-  AllColors,
-  SemanticColors,
-  CustomPrefix,
-} from './badge.stories';
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as BadgeStories from './badge.stories';
 
-<Meta of={BadgeMeta} name="Docs" />
+<Meta of={BadgeStories} name="Docs" />
 
 # Badge
 
-`<craft-badge>` is a small status pill — a color `<craft-indicator>` dot followed
-by a label. Use it to surface an object's state in lists, tables, and headers
-(for example an entry's status or an order's payment state).
+`<craft-badge>` is a small status pill: a coloured [Indicator](?path=/docs/components-indicator--docs) dot followed by a label.
+Use it to surface an object's state where it is read at a glance — an entry's status in an index, an order's payment state in a header.
 
-<Canvas of={Default} />
+<Canvas of={BadgeStories.Default} sourceState="shown" />
 
-## Usage
+The label is the default slot, and `fill` sets the colour.
+The badge renders its surface, border, and text in the quiet tone of that colour, and the indicator in the loud one, so the pill stays legible against the page while the dot carries the signal.
 
-```html
-<craft-badge fill="success">Live</craft-badge>
-```
+## Colour
 
-The label is the default slot. By default the badge prepends a
-`<craft-indicator>` tinted to match `fill`; the badge's own surface, border, and
-text render in the quieter tone of the same color.
+`fill` takes a value from the shared `Color` palette:
 
-## Properties
+<Canvas of={BadgeStories.AllColors} sourceState="shown" />
 
-<table>
-  <thead>
-    <tr>
-      <th>Property</th>
-      <th>Attribute</th>
-      <th>Type</th>
-      <th>Default</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <code>fill</code>
-      </td>
-      <td>
-        <code>fill</code>
-      </td>
-      <td>
-        <code>ColorValue</code>
-      </td>
-      <td>
-        <code>gray</code>
-      </td>
-      <td>
-        The badge color — a value from the shared <code>Color</code> palette
-        (see <a href="#fill">Fill</a>). Reflected to the <code>fill</code>{' '}
-        attribute.
-      </td>
-    </tr>
-  </tbody>
-</table>
-
-## Fill
-
-`fill` accepts a color **value** from the shared `Color` constant — a palette
-swatch (`red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`,
-`cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`,
-`gray`, `white`, `black`).
-
-Unlike `<craft-indicator>`, the badge is constrained to the palette and does not
-take arbitrary CSS colors — `fill` is typed as `ColorValue`, so only known
-values type-check. Setting `fill` reflects the resolved color onto the host's
-`data-color` attribute, which scopes the `--c-color-*` tokens the badge styles
-read.
-
-<Canvas of={AllColors} />
-
-### Semantic colors
-
-The `Color` constant also exposes semantic aliases that resolve to palette
-values — `Color.Success` → `emerald`, `Color.Warning` → `orange`,
-`Color.Danger` → `red`, `Color.Info` → `blue`, `Color.Neutral` → `slate`, and
-`Color.Accent` → `red`. Prefer these when the color carries meaning so intent
-survives any future palette retune.
-
-```html
-<craft-badge fill="emerald">Success</craft-badge>
-```
+Unlike Indicator, the badge is limited to the palette and does not take arbitrary CSS colours — `fill` is typed as `ColorValue`, so an unknown colour fails to type-check rather than rendering as nothing.
 
-<Canvas of={SemanticColors} />
-
-## Slots
-
-<table>
-  <thead>
-    <tr>
-      <th>Slot</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <em>(default)</em>
-      </td>
-      <td>The label content, shown after the indicator.</td>
-    </tr>
-    <tr>
-      <td>
-        <code>prefix</code>
-      </td>
-      <td>
-        Leading content. Defaults to a <code>&lt;craft-indicator&gt;</code>{' '}
-        filled from <code>fill</code>; slot your own element to replace it.
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <code>suffix</code>
-      </td>
-      <td>Trailing content, shown after the label.</td>
-    </tr>
-  </tbody>
-</table>
-
-Slotting `prefix` overrides the default indicator — handy for an icon or a
-custom marker:
-
-<Canvas of={CustomPrefix} />
-
-## CSS parts
-
-<table>
-  <thead>
-    <tr>
-      <th>Part</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <code>badge</code>
-      </td>
-      <td>The pill wrapper.</td>
-    </tr>
-    <tr>
-      <td>
-        <code>prefix</code>
-      </td>
-      <td>The leading slot, before the label.</td>
-    </tr>
-    <tr>
-      <td>
-        <code>indicator</code>
-      </td>
-      <td>The default indicator rendered in the prefix slot.</td>
-    </tr>
-    <tr>
-      <td>
-        <code>suffix</code>
-      </td>
-      <td>The trailing slot, after the label.</td>
-    </tr>
-  </tbody>
-</table>
+Setting it reflects the resolved colour onto the host's `data-color` attribute, which is what scopes the `--c-color-*` tokens the badge's styles read.
+That is the same mechanism described on the [Colorable](?path=/docs/tokens-colorable--docs) page.
 
-## Styling
+### Semantic colours
+
+`Color` also carries aliases that resolve to palette values — `Color.Success` is `emerald`, `Color.Warning` is `orange`, `Color.Danger` is `red`, `Color.Info` is `blue`.
+Reach for these when the colour carries meaning, so intent survives a palette retune:
+
+<Canvas of={BadgeStories.SemanticColors} sourceState="shown" />
+
+## Replacing the Indicator
 
-The badge sizes itself in `em` and reads the generic colorable tokens, so it
-adapts to the surrounding text and to `fill` automatically:
+The `prefix` slot holds the indicator, so slotting your own content replaces it — an icon, or a marker of your own:
 
-- Surface — `--c-color-fill-quiet`
-- Border — `--c-color-border-quiet`
-- Text — `--c-color-on-quiet`
+<Canvas of={BadgeStories.CustomPrefix} sourceState="shown" />
 
-Because those tokens are scoped by the `data-color` attribute the component sets
-from `fill`, you normally change a badge's color through `fill` rather than by
-overriding the tokens. Set `font-size` on the host to scale the whole pill,
-including its indicator:
+## Styling
+
+The badge sizes itself in `em`, so set `font-size` on the host to scale the whole pill, indicator included:
 
 ```css
 craft-badge {
-  font-size: 0.875rem;
+  font-size: var(--c-text-sm);
 }
 ```
 
+Its colours come from the generic colorable tokens — `--c-color-fill-quiet` for the surface, `--c-color-border-quiet` for the border, `--c-color-on-quiet` for the text.
+Because `fill` scopes those tokens, change a badge's colour through `fill` rather than by overriding them.
+
 ## Accessibility
 
-The default indicator is decorative and is left unlabeled, since the badge's
-text already names the status. If you replace the `prefix` with a meaningful
-graphic, give it its own accessible name (for example a `label` on
-`<craft-indicator>` or `<craft-icon>`).
+The default indicator is decorative and deliberately unlabelled: the badge's own text already names the status, and a labelled dot beside it would be announced twice.
+
+Replace the `prefix` with something meaningful and that changes — give it its own accessible name, such as a `label` on the [Indicator](?path=/docs/components-indicator--docs) or [Icon](?path=/docs/components-icon--docs).
+
+## Properties
+
+<ArgTypes of={BadgeStories} />
diff --git a/packages/craftcms-ui/src/components/badge/badge.stories.ts b/packages/craftcms-ui/src/components/badge/badge.stories.ts
index 193bf975ce0..b1d6a9dc70e 100644
--- a/packages/craftcms-ui/src/components/badge/badge.stories.ts
+++ b/packages/craftcms-ui/src/components/badge/badge.stories.ts
@@ -2,32 +2,36 @@ import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
 import {expect} from 'storybook/test';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './badge.js';
 import type CraftBadge from './badge.js';
-import {Color, colors} from '@src/constants/colors';
+import {Color} from '@src/constants/colors';
 import {capitalize} from '@src/utilities/string';
 import '../icon/icon.js';
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `badge.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftBadge>('craft-badge');
+
+type BadgeArgs = CraftBadge & typeof args;
+
 const meta = {
   title: 'Components/Badge',
   component: 'craft-badge',
-  args: {
-    fill: 'gray',
-  },
-  argTypes: {
-    fill: {control: 'select', options: colors},
-  },
-  render: (args) => html`
-    <craft-badge fill=${args.fill}>
-      ${capitalize(String(args.fill))}
-    </craft-badge>
-  `,
-} satisfies Meta<CraftBadge>;
+  args: {...args, fill: 'gray', 'default-slot': 'Gray'},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<BadgeArgs>;
 
 export default meta;
-type Story = StoryObj<CraftBadge>;
+type Story = StoryObj<BadgeArgs>;
 
 export const Default: Story = {
   play: async ({canvasElement}) => {
@@ -48,7 +52,7 @@ export const Default: Story = {
 
 /** `fill` takes a color value from `Color` (e.g. `red`). */
 export const FromColorValue: Story = {
-  render: () => html`<craft-badge fill="red">Value: red</craft-badge>`,
+  args: {fill: 'red', 'default-slot': 'Value: red'},
   play: async ({canvasElement}) => {
     const badge = canvasElement.querySelector('craft-badge')!;
     // The badge reflects the resolved color for its own surface styling.
@@ -57,6 +61,7 @@ export const FromColorValue: Story = {
 };
 
 export const AllColors: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
     <div style="display: grid; gap: 0.5rem; justify-items: start">
       ${Object.entries(Color).map(
@@ -68,6 +73,7 @@ export const AllColors: Story = {
 };
 
 export const SemanticColors: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
     <div style="display: grid; gap: 0.5rem; justify-items: start">
       ${(
@@ -88,12 +94,11 @@ export const SemanticColors: Story = {
 };
 
 export const CustomPrefix: Story = {
-  render: () => html`
-    <craft-badge fill=${Color.Green}>
-      <craft-icon slot="prefix" name="circle-check" label="Done"></craft-icon>
-      Custom prefix
-    </craft-badge>
-  `,
+  args: {
+    fill: Color.Green,
+    'prefix-slot': '<craft-icon name="circle-check" label="Done"></craft-icon>',
+    'default-slot': 'Custom prefix',
+  },
   play: async ({canvasElement}) => {
     const host = canvasElement.querySelector('craft-badge')!;
     // A slotted prefix overrides the default indicator fallback.
diff --git a/packages/craftcms-ui/src/components/badge/badge.test.ts b/packages/craftcms-ui/src/components/badge/badge.test.ts
new file mode 100644
index 00000000000..68277cf6126
--- /dev/null
+++ b/packages/craftcms-ui/src/components/badge/badge.test.ts
@@ -0,0 +1,68 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './badge.js';
+import type CraftBadge from './badge.js';
+
+async function createBadge(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Live'
+): Promise<CraftBadge> {
+  const element = document.createElement('craft-badge') as CraftBadge;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-badge', () => {
+  it('defaults to gray', async () => {
+    const element = await createBadge();
+
+    expect(element.fill).toBe('gray');
+  });
+
+  /**
+   * The host's `data-color` is what scopes the `--c-color-*` tokens the badge's
+   * own surface, border, and text read, so it has to follow `fill`.
+   */
+  it('reflects the fill onto data-color for the token scope', async () => {
+    const element = await createBadge({fill: 'emerald'});
+
+    expect(element.dataset.color).toBe('emerald');
+  });
+
+  it('keeps data-color in step when the fill changes', async () => {
+    const element = await createBadge({fill: 'emerald'});
+
+    element.fill = 'red';
+    await element.updateComplete;
+
+    expect(element.dataset.color).toBe('red');
+  });
+
+  /** The default prefix is an indicator tinted to match. */
+  it('renders an indicator carrying the same fill', async () => {
+    const element = await createBadge({fill: 'red'});
+    const indicator = element.shadowRoot!.querySelector('craft-indicator');
+
+    expect(indicator?.getAttribute('fill')).toBe('red');
+  });
+
+  it('exposes its regions as parts', async () => {
+    const element = await createBadge();
+    const parts = [...element.shadowRoot!.querySelectorAll('[part]')].map(
+      (el) => el.getAttribute('part')
+    );
+
+    expect(parts).toEqual(
+      expect.arrayContaining(['badge', 'prefix', 'indicator', 'suffix'])
+    );
+  });
+});
diff --git a/packages/craftcms-ui/src/components/breadcrumb-item/BreadcrumbItem.mdx b/packages/craftcms-ui/src/components/breadcrumb-item/BreadcrumbItem.mdx
new file mode 100644
index 00000000000..4f1f9ecbad2
--- /dev/null
+++ b/packages/craftcms-ui/src/components/breadcrumb-item/BreadcrumbItem.mdx
@@ -0,0 +1,29 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Components/Breadcrumb Item" />
+
+# Breadcrumb Item
+
+`<craft-breadcrumb-item>` is one step in a [Breadcrumbs](?path=/docs/components-breadcrumbs--docs) trail.
+
+There are no stories here because a single crumb has no trail to sit in. See the [Breadcrumbs](?path=/docs/components-breadcrumbs--docs) page for working examples.
+
+```html
+<craft-breadcrumbs>
+  <craft-breadcrumb-item href="/admin">Control Panel</craft-breadcrumb-item>
+  <craft-breadcrumb-item href="/admin/entries">Entries</craft-breadcrumb-item>
+  <craft-breadcrumb-item>Homepage</craft-breadcrumb-item>
+</craft-breadcrumbs>
+```
+
+## Links and the Current Page
+
+A crumb with `href` renders as a link; one without renders as plain text.
+
+**Leave `href` off the last crumb.** It is the page the person is already on, so a link there goes nowhere — and announcing it as a link suggests otherwise.
+
+`target` and `rel` behave as they do on a native anchor. `rel` defaults to `noreferrer noopener`, which is what a crumb opening in a new tab should carry.
+
+## Properties
+
+<ArgTypes of="craft-breadcrumb-item" />
diff --git a/packages/craftcms-ui/src/components/breadcrumb-item/breadcrumb-item.ts b/packages/craftcms-ui/src/components/breadcrumb-item/breadcrumb-item.ts
index 06334027b43..bc3c6bd3c6d 100644
--- a/packages/craftcms-ui/src/components/breadcrumb-item/breadcrumb-item.ts
+++ b/packages/craftcms-ui/src/components/breadcrumb-item/breadcrumb-item.ts
@@ -6,14 +6,30 @@ import {property} from 'lit/decorators.js';
  * as a link when `href` is set. `craft-breadcrumbs` appends separator content
  * into the `separator` slot.
  */
+/**
+ * @summary One step in a `craft-breadcrumbs` trail. Renders as a link when
+ * `href` is set, and as plain text otherwise — which is what the current page
+ * should be.
+ *
+ * @slot - The step's label.
+ */
 export default class CraftBreadcrumbItem extends LitElement {
   /** When set, the label is rendered as a link. */
+  /**
+   * Where the step links to. Leave it off for the current page: the last
+   * crumb is where the person already is, so linking it goes nowhere.
+   */
   @property({reflect: true}) href?: string;
 
   /** The link target (only used when `href` is set). */
+  /** Browsing context for the link, as on a native anchor. */
   @property() target?: '_blank' | '_parent' | '_self' | '_top';
 
   /** The link rel (only used when `href` and `target` are set). */
+  /**
+   * Link relationship. Defaults to `noreferrer noopener`, which is what a
+   * crumb opening in a new tab should carry.
+   */
   @property() rel = 'noreferrer noopener';
 
   static override styles = css`
diff --git a/packages/craftcms-ui/src/components/breadcrumbs/Breadcrumbs.mdx b/packages/craftcms-ui/src/components/breadcrumbs/Breadcrumbs.mdx
new file mode 100644
index 00000000000..76ef2099b5f
--- /dev/null
+++ b/packages/craftcms-ui/src/components/breadcrumbs/Breadcrumbs.mdx
@@ -0,0 +1,32 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as BreadcrumbsStories from './breadcrumbs.stories';
+
+<Meta of={BreadcrumbsStories} name="Docs" />
+
+# Breadcrumbs
+
+`<craft-breadcrumbs>` shows where the current page sits and gives a route back up.
+
+<Canvas of={BreadcrumbsStories.Default} sourceState="shown" />
+
+The trail is made of [Breadcrumb Item](?path=/docs/components-breadcrumb-item--docs)s, each a link except the last.
+
+## Collapsing
+
+A deep path in a narrow window would either wrap onto two lines or push the page sideways. Instead the trail collapses:
+
+<Canvas of={BreadcrumbsStories.Resizable} sourceState="shown" />
+
+The ends matter most — where you are, and the root you can get back to — so those survive as the middle gives way.
+
+## Accessibility
+
+The trail is a navigation landmark named by `label`, defaulting to a translated "Breadcrumbs".
+
+A page with more than one set should name each of them. Two landmarks both called "Breadcrumbs" are indistinguishable in the list a screen reader offers.
+
+The current page is the last crumb and should have no `href` — it is where the person already is, so linking it goes nowhere.
+
+## Properties
+
+<ArgTypes of={BreadcrumbsStories} />
diff --git a/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.stories.ts b/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.stories.ts
index d3fac9c51fb..c16084e2f97 100644
--- a/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.stories.ts
+++ b/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.stories.ts
@@ -1,35 +1,52 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './breadcrumbs.js';
 import '../breadcrumb-item/breadcrumb-item.js';
+import type CraftBreadcrumbs from './breadcrumbs.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `breadcrumbs.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftBreadcrumbs>('craft-breadcrumbs');
+
+type BreadcrumbsArgs = CraftBreadcrumbs & typeof args;
+
+const TRAIL = `
+  <craft-breadcrumb-item href="#">Site Name</craft-breadcrumb-item>
+  <craft-breadcrumb-item href="#">Entries</craft-breadcrumb-item>
+  <craft-breadcrumb-item href="#">Entry Type</craft-breadcrumb-item>
+  <craft-breadcrumb-item href="#">Current Entry</craft-breadcrumb-item>
+`;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Breadcrumbs',
   component: 'craft-breadcrumbs',
-  argTypes: {},
-  render: (args) => html`
-    <craft-breadcrumbs>
-      <craft-breadcrumb-item href="#">Site Name</craft-breadcrumb-item>
-      <craft-breadcrumb-item href="#">Entries</craft-breadcrumb-item>
-      <craft-breadcrumb-item href="#">Entry Type</craft-breadcrumb-item>
-      <craft-breadcrumb-item href="#">Current Entry</craft-breadcrumb-item>
-    </craft-breadcrumbs>
-  `,
-} satisfies Meta<any>;
+  args: {...args, 'default-slot': TRAIL},
+  argTypes,
+  // Render from args alone so every control — attributes and slot — drives the
+  // story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<BreadcrumbsArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<BreadcrumbsArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** The trail is `craft-breadcrumb-item` children; the list draws the rest. */
+export const Default: Story = {};
 
+/**
+ * The trail collapses from the middle when it runs out of room. Drag the
+ * handle to see it.
+ */
 export const Resizable: Story = {
-  render: (args) => html`
+  parameters: {controls: {disable: true}},
+  render: () => html`
     <div class="resizable-container">
       <craft-breadcrumbs>
         <craft-breadcrumb-item href="#">Site Name</craft-breadcrumb-item>
diff --git a/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.test.ts b/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.test.ts
new file mode 100644
index 00000000000..4bf5406f56a
--- /dev/null
+++ b/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.test.ts
@@ -0,0 +1,74 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './breadcrumbs.js';
+import '../breadcrumb-item/breadcrumb-item.js';
+import type CraftBreadcrumbs from './breadcrumbs.js';
+
+async function createBreadcrumbs(
+  attrs: Record<string, string> = {},
+  innerHTML = `
+    <craft-breadcrumb-item href="#">Site</craft-breadcrumb-item>
+    <craft-breadcrumb-item href="#">Entries</craft-breadcrumb-item>
+    <craft-breadcrumb-item href="#">News</craft-breadcrumb-item>
+  `
+): Promise<CraftBreadcrumbs> {
+  const element = document.createElement(
+    'craft-breadcrumbs'
+  ) as CraftBreadcrumbs;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function nav(element: CraftBreadcrumbs): HTMLElement {
+  return element.shadowRoot!.querySelector('nav')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-breadcrumbs', () => {
+  /**
+   * A page can hold more than one navigation landmark, so the trail names
+   * itself rather than being announced as an unlabelled "navigation".
+   */
+  it('is a named navigation landmark', async () => {
+    const element = await createBreadcrumbs();
+
+    expect(nav(element)).toBeTruthy();
+    expect(nav(element).getAttribute('aria-label')).toBeTruthy();
+  });
+
+  it('takes a label of its own', async () => {
+    const element = await createBreadcrumbs({label: 'You are here'});
+
+    expect(nav(element).getAttribute('aria-label')).toBe('You are here');
+  });
+
+  it('renders its items from the default slot', async () => {
+    const element = await createBreadcrumbs();
+    const slot =
+      element.shadowRoot!.querySelector<HTMLSlotElement>('slot:not([name])')!;
+
+    expect(slot.assignedElements()).toHaveLength(3);
+  });
+
+  /**
+   * The separator is drawn between items and carries no meaning of its own, so
+   * the template it is cloned from is hidden from assistive technology.
+   */
+  it('keeps the separator out of the accessibility tree', async () => {
+    const element = await createBreadcrumbs();
+    const separator = element.shadowRoot!.querySelector(
+      'slot[name="separator"]'
+    )!.parentElement!;
+
+    expect(separator.getAttribute('aria-hidden')).toBe('true');
+    expect(separator.hasAttribute('hidden')).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.ts b/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.ts
index 2750f7019ca..7f24ee10cc7 100644
--- a/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.ts
+++ b/packages/craftcms-ui/src/components/breadcrumbs/breadcrumbs.ts
@@ -13,10 +13,19 @@ type BreadcrumbItem = {
   isVisible: boolean; // false if displayed in menu overlay
 };
 
+/**
+ * @summary A trail of `craft-breadcrumb-item`s showing where the current page
+ * sits, and giving a route back up.
+ *
+ * The trail collapses when it runs out of room rather than wrapping or
+ * overflowing, so a deep path stays on one line in a narrow window.
+ *
+ * @slot - The `craft-breadcrumb-item`s making up the trail.
+ */
 export default class CraftBreadcrumbs extends LitElement {
   static override styles = [styles];
-  @query('slot') defaultSlot: HTMLSlotElement;
-  @query('slot[name="separator"]') separatorSlot: HTMLSlotElement;
+  @query('slot') protected defaultSlot: HTMLSlotElement;
+  @query('slot[name="separator"]') protected separatorSlot: HTMLSlotElement;
 
   @queryAssignedElements({selector: 'craft-breadcrumb-item'})
   private breadcrumbsElements!: CraftBreadcrumbItem[];
@@ -25,6 +34,11 @@ export default class CraftBreadcrumbs extends LitElement {
    * The label to use for the breadcrumb control. This will not be shown on the screen, but it will be announced by
    * screen readers and other assistive devices to provide more context for users.
    */
+  /**
+   * Accessible name for the navigation landmark. A page with more than one
+   * set of breadcrumbs should name each, so they are distinguishable in a
+   * list of landmarks.
+   */
   @property() label = t('Breadcrumbs');
 
   @state()
diff --git a/packages/craftcms-ui/src/components/button-group/ButtonGroup.mdx b/packages/craftcms-ui/src/components/button-group/ButtonGroup.mdx
new file mode 100644
index 00000000000..60fee1fb6a9
--- /dev/null
+++ b/packages/craftcms-ui/src/components/button-group/ButtonGroup.mdx
@@ -0,0 +1,40 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ButtonGroupStories from './button-group.stories';
+
+<Meta of={ButtonGroupStories} name="Docs" />
+
+# Button Group
+
+`<craft-button-group>` joins related buttons into a single visual unit.
+
+<Canvas of={ButtonGroupStories.Default} sourceState="shown" />
+
+<Canvas of={ButtonGroupStories.WithActions} sourceState="shown" />
+
+## Radio Mode
+
+Given a `name`, the group becomes a single-choice control — a segmented toggle rather than a row of independent buttons:
+
+<Canvas of={ButtonGroupStories.RadioMode} sourceState="shown" />
+
+<Canvas of={ButtonGroupStories.RadioModeVariants} sourceState="shown" />
+
+<Canvas of={ButtonGroupStories.RadioModeIcons} sourceState="shown" />
+
+<Canvas of={ButtonGroupStories.FormAssociated} sourceState="shown" />
+
+In this mode the group is form-associated and posts like any other field, so a segmented control does not need a hidden input beside it.
+
+## Choosing Between Modes
+
+Without a `name` the buttons are actions; with one they are options.
+
+That is a real semantic difference, not styling: in radio mode the group is announced as a radio group and arrow keys move between the options, which is wrong for a row of independent actions and right for a choice.
+
+## Icon Buttons
+
+A segmented control of icons is compact and easy to misread. Each button still needs a name — see [Icon](?path=/docs/components-icon--docs) — because the group announces the choice, not what each option means.
+
+## Properties
+
+<ArgTypes of={ButtonGroupStories} />
diff --git a/packages/craftcms-ui/src/components/button-group/button-group.stories.ts b/packages/craftcms-ui/src/components/button-group/button-group.stories.ts
index 7c584576fe5..56e2b4625f6 100644
--- a/packages/craftcms-ui/src/components/button-group/button-group.stories.ts
+++ b/packages/craftcms-ui/src/components/button-group/button-group.stories.ts
@@ -1,13 +1,26 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 
 import './button-group.js';
+import type CraftButtonGroup from './button-group.js';
 import '../button/button.js';
 import '../icon/icon.js';
 import '../action-menu/action-menu.js';
 import '../action-item/action-item.js';
 
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `button-group.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftButtonGroup>('craft-button-group');
+
+type CraftButtonGroupArgs = CraftButtonGroup & typeof args;
+
 const meta = {
   title: 'Components/Button Group',
   component: 'craft-button-group',
@@ -25,17 +38,8 @@ The group is form-associated and submits its value with the surrounding form.
       },
     },
   },
-  argTypes: {
-    name: {
-      description: 'Form field name. When set, enables radio mode.',
-      control: {type: 'text'},
-    },
-    value: {
-      description: 'The currently selected value (radio mode only).',
-      control: {type: 'text'},
-    },
-  },
-  args: {},
+  args,
+  argTypes,
   render: () => html`
     <craft-button-group>
       <craft-button>One</craft-button>
@@ -43,10 +47,10 @@ The group is form-associated and submits its value with the surrounding form.
       <craft-button>Three</craft-button>
     </craft-button-group>
   `,
-} satisfies Meta<any>;
+} satisfies Meta<CraftButtonGroupArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftButtonGroupArgs>;
 
 /** Standard button group with no selection behavior — buttons act independently. */
 export const Default: Story = {
diff --git a/packages/craftcms-ui/src/components/button-group/button-group.test.ts b/packages/craftcms-ui/src/components/button-group/button-group.test.ts
index 8aad88d01c5..d5c671a85ca 100644
--- a/packages/craftcms-ui/src/components/button-group/button-group.test.ts
+++ b/packages/craftcms-ui/src/components/button-group/button-group.test.ts
@@ -1,59 +1,91 @@
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
 import type CraftButton from '../button/button.js';
 import '../button/button.js';
 import './button-group.js';
 
-const setFormValue = vi.fn();
-const attachInternals = Object.getOwnPropertyDescriptor(
-  HTMLElement.prototype,
-  'attachInternals'
-);
-
 beforeEach(() => {
   document.body.innerHTML = '';
-  setFormValue.mockClear();
-  Object.defineProperty(HTMLElement.prototype, 'attachInternals', {
-    configurable: true,
-    value: () => ({setFormValue}),
-  });
-});
-
-afterEach(() => {
-  if (attachInternals) {
-    Object.defineProperty(
-      HTMLElement.prototype,
-      'attachInternals',
-      attachInternals
-    );
-  } else {
-    delete (HTMLElement.prototype as Partial<HTMLElement>).attachInternals;
-  }
 });
 
+/**
+ * The group is a form-associated custom element. happy-dom has no
+ * `ElementInternals`, so these run against `element-internals-polyfill`, wired
+ * up in the components project's setup.
+ */
 describe('craft-button-group', () => {
-  it('toggles multiple selected values', async () => {
+  async function createGroup(multiple: boolean): Promise<{
+    form: HTMLFormElement;
+    group: HTMLElement;
+    buttons: CraftButton[];
+  }> {
+    const form = document.createElement('form');
     const group = document.createElement('craft-button-group');
     group.name = 'topics';
-    group.multiple = true;
+    group.multiple = multiple;
+
+    const buttons = ['news', 'events'].map((value) => {
+      const button = document.createElement('craft-button');
+      button.value = value;
+      button.textContent = value;
+      group.append(button);
+      return button;
+    });
+
+    form.append(group);
+    document.body.append(form);
+    await Promise.all([
+      group.updateComplete,
+      ...buttons.map((button) => button.updateComplete),
+    ]);
+
+    return {form, group, buttons};
+  }
 
-    const button = document.createElement('craft-button');
-    button.value = 'news';
-    button.textContent = 'News';
-    group.append(button);
-    document.body.append(group);
-    await Promise.all([group.updateComplete, button.updateComplete]);
+  const click = (button: CraftButton) =>
+    button.dispatchEvent(
+      new MouseEvent('click', {bubbles: true, composed: true})
+    );
+
+  it('toggles multiple selected values', async () => {
+    const {form, group, buttons} = await createGroup(true);
 
     let values: string[] = [];
     group.addEventListener('change', (event) => {
       values = (event as CustomEvent<{values: string[]}>).detail.values;
     });
 
-    button.dispatchEvent(
-      new MouseEvent('click', {bubbles: true, composed: true})
-    );
+    click(buttons[0]!);
 
-    expect((button as CraftButton).active).toBe(true);
+    expect(buttons[0]!.active).toBe(true);
     expect(values).toEqual(['news']);
-    expect(setFormValue).toHaveBeenCalled();
+    // Multiple mode posts a PHP-style array, behind an empty sentinel so an
+    // empty selection still reaches the server as a key.
+    expect(new FormData(form).getAll('topics')).toEqual(['']);
+    expect(new FormData(form).getAll('topics[]')).toEqual(['news']);
+
+    click(buttons[1]!);
+
+    expect(values).toEqual(['news', 'events']);
+    expect(new FormData(form).getAll('topics[]')).toEqual(['news', 'events']);
+
+    // Clicking a selected button in multiple mode turns it back off.
+    click(buttons[0]!);
+
+    expect(buttons[0]!.active).toBe(false);
+    expect(values).toEqual(['events']);
+  });
+
+  it('posts a single value in radio mode', async () => {
+    const {form, group, buttons} = await createGroup(false);
+
+    let value = '';
+    group.addEventListener('change', (event) => {
+      value = (event as CustomEvent<{value: string}>).detail.value;
+    });
+
+    click(buttons[1]!);
+
+    expect(value).toBe('events');
+    expect(new FormData(form).get('topics')).toBe('events');
   });
 });
diff --git a/packages/craftcms-ui/src/components/button-group/button-group.ts b/packages/craftcms-ui/src/components/button-group/button-group.ts
index ac1b99692e9..6b00065ea93 100644
--- a/packages/craftcms-ui/src/components/button-group/button-group.ts
+++ b/packages/craftcms-ui/src/components/button-group/button-group.ts
@@ -14,6 +14,10 @@ import styles from './button-group.styles.js';
  */
 export default class CraftButtonGroup extends LitElement {
   static override styles: CSSResultGroup = [styles];
+  /**
+   * Makes the group a form-associated custom element, so its selected value
+   * posts with the form in radio mode.
+   */
   static formAssociated = true;
 
   private _internals: ElementInternals;
diff --git a/packages/craftcms-ui/src/components/button/Docs.mdx b/packages/craftcms-ui/src/components/button/Button.mdx
similarity index 79%
rename from packages/craftcms-ui/src/components/button/Docs.mdx
rename to packages/craftcms-ui/src/components/button/Button.mdx
index 72697740939..8b860bf61e9 100644
--- a/packages/craftcms-ui/src/components/button/Docs.mdx
+++ b/packages/craftcms-ui/src/components/button/Button.mdx
@@ -1,7 +1,7 @@
-import {Canvas, Meta} from '@storybook/addon-docs/blocks';
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
 import * as ButtonStories from './button.stories';
 
-<Meta of={ButtonStories} />
+<Meta of={ButtonStories} name="Docs" />
 
 # Button
 
@@ -27,7 +27,7 @@ A button represents a clickable element that performs an action when activated.
 
 ## Inherit
 
-Add the boolean `inherit` property to a button placed inside a [Colorable](?path=/docs/concepts-colorable--docs) container (such as a `craft-callout` or any `[data-color]` element). Its neutral variants then adopt the container's color instead of the neutral palette, while still honoring the chosen appearance (`solid`, `fill`, `outline`, and so on).
+Add the boolean `inherit` property to a button placed inside a [Colorable](?path=/docs/tokens-colorable--docs) container (such as a `craft-callout` or any `[data-color]` element). Its neutral variants then adopt the container's color instead of the neutral palette, while still honoring the chosen appearance (`solid`, `fill`, `outline`, and so on).
 
 `primary` and `danger` ignore `inherit` and keep their own colors, so they remain stable inside colorable containers.
 
@@ -48,3 +48,7 @@ Add the boolean `inherit` property to a button placed inside a [Colorable](?path
 ## Links
 
 <Canvas of={ButtonStories.Links} />
+
+## Properties
+
+<ArgTypes of={ButtonStories} />
diff --git a/packages/craftcms-ui/src/components/button/button.stories.ts b/packages/craftcms-ui/src/components/button/button.stories.ts
index 143db30510b..807744ab288 100644
--- a/packages/craftcms-ui/src/components/button/button.stories.ts
+++ b/packages/craftcms-ui/src/components/button/button.stories.ts
@@ -1,8 +1,11 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 
 import './button.js';
+import type CraftButton from './button.js';
 import '../icon/icon.js';
 import '../chip/chip.js';
 import {ButtonVariant} from '@src/components/button/button';
@@ -10,30 +13,27 @@ import {ButtonVariant} from '@src/components/button/button';
 const buttonVariants = Object.values(ButtonVariant);
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `button.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftButton>('craft-button');
+
+type CraftButtonArgs = CraftButton & typeof args;
+
 const meta = {
   title: 'Components/Button',
   component: 'craft-button',
   parameters: {
     layout: 'centered',
   },
-  args: {
-    label: 'Button',
-    loading: false,
-    variant: ButtonVariant.Fill,
-  },
-  argTypes: {
-    variant: {
-      control: {type: 'select'},
-      options: buttonVariants,
-    },
-    loading: {
-      control: {type: 'boolean'},
-    },
-  },
-} satisfies Meta<any>;
+  args: {...args, label: 'Button', variant: ButtonVariant.Fill},
+  argTypes,
+} satisfies Meta<CraftButtonArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftButtonArgs>;
 
 /**
  * Every variant. `primary` and `danger` are solid and colored; the rest are the
diff --git a/packages/craftcms-ui/src/components/button/button.styles.ts b/packages/craftcms-ui/src/components/button/button.styles.ts
index 6d005f27495..f8268d383b4 100644
--- a/packages/craftcms-ui/src/components/button/button.styles.ts
+++ b/packages/craftcms-ui/src/components/button/button.styles.ts
@@ -410,25 +410,6 @@ export default css`
     justify-content: end;
   }
 
-  .a11y-error {
-    position: relative;
-    outline: 2px solid var(--c-color-danger-border-normal) !important;
-    background-color: rgba(255, 0, 0, 0.1) !important;
-
-    &:after {
-      content: '!';
-      position: absolute;
-      display: inline-flex;
-      font-size: calc(11rem / 16);
-      padding: 0.125em 0.5em 0.25em;
-      inset-block-start: -2px;
-      inset-inline-start: 0;
-      background: var(--c-color-danger-bg-emphasis);
-      color: white;
-      transform: translateX(-100%);
-    }
-  }
-
   /*
   Link mode: the inner <a> is the full interactive surface.
   Move inline padding from :host to the anchor so the whole button is clickable.
diff --git a/packages/craftcms-ui/src/components/button/button.test.ts b/packages/craftcms-ui/src/components/button/button.test.ts
index 4b1fc925ce4..4b713d5cab0 100644
--- a/packages/craftcms-ui/src/components/button/button.test.ts
+++ b/packages/craftcms-ui/src/components/button/button.test.ts
@@ -20,6 +20,11 @@ function anchor(element: CraftButton): HTMLAnchorElement | null {
   return element.shadowRoot?.querySelector('a.link') ?? null;
 }
 
+/** The inner content wrapper, which carries the nameless-button warning class. */
+function content(element: CraftButton): HTMLElement | null {
+  return element.shadowRoot?.querySelector('.button-content') ?? null;
+}
+
 beforeEach(() => {
   document.body.innerHTML = '';
 });
@@ -75,7 +80,15 @@ describe('craft-button link mode', () => {
     const element = await createButton({href: '/x'}, 'Settings');
     // Wait for firstUpdated's async accessible-name computation.
     await element.updateComplete;
-    expect(element.accessibleName).toBe('Settings');
+    expect(content(element)!.classList.contains('a11y-error')).toBe(false);
+  });
+
+  /** An icon-only button with nothing to read from is the case worth catching. */
+  it('flags an accessible-name error for a nameless button', async () => {
+    const element = await createButton({}, '');
+    await element.updateComplete;
+    await new Promise((resolve) => setTimeout(resolve));
+    expect(content(element)!.classList.contains('a11y-error')).toBe(true);
   });
 });
 
diff --git a/packages/craftcms-ui/src/components/button/button.ts b/packages/craftcms-ui/src/components/button/button.ts
index bb06657c71d..7590ae6a8f7 100644
--- a/packages/craftcms-ui/src/components/button/button.ts
+++ b/packages/craftcms-ui/src/components/button/button.ts
@@ -3,6 +3,7 @@ import {html, nothing} from 'lit';
 import {property, state, query} from 'lit/decorators.js';
 import {t} from '@src/utilities/translate';
 import styles from './button.styles.js';
+import a11yErrorStyles from '@src/styles/a11y-error.styles.js';
 import visuallyHiddenStyles from '@src/styles/visually-hidden.styles.js';
 import '../spinner/spinner.js';
 import '../icon/icon.js';
@@ -44,9 +45,16 @@ export type ButtonVariant = (typeof ButtonVariant)[keyof typeof ButtonVariant];
  */
 export default class CraftButton extends LionButtonSubmit {
   static override get styles() {
-    return [...super.styles, visuallyHiddenStyles, styles];
+    return [...super.styles, visuallyHiddenStyles, a11yErrorStyles, styles];
   }
 
+  /**
+   * Defaults to `button` rather than Lion's `submit`: a plain action button is
+   * far the more common case, and Lion gates its submit and reset wiring
+   * behind this, so the default also skips that work.
+   */
+  override type = 'button';
+
   constructor() {
     super();
     // We extend LionButtonSubmit so `type="submit"`/`"reset"` Just Work inside
@@ -159,23 +167,17 @@ export default class CraftButton extends LionButtonSubmit {
       Array.from(childComponents).map((child: any) => child.updateComplete)
     );
 
-    if (!this.accessibleName) {
-      // In link mode the host is role="presentation" (name not computable on
-      // it); the real accessible element is the inner anchor.
-      const nameTarget = this.isLink
-        ? ((this.shadowRoot?.querySelector('a.link') as HTMLElement | null) ??
-          this)
-        : this;
-      this.accessibleName = computeAccessibleName(nameTarget);
-    }
+    // In link mode the host is role="presentation" (name not computable on
+    // it); the real accessible element is the inner anchor.
+    const nameTarget = this.isLink
+      ? ((this.shadowRoot?.querySelector('a.link') as HTMLElement | null) ??
+        this)
+      : this;
+    this._accessibleName = computeAccessibleName(nameTarget);
 
-    this._hasAccessibilityError =
-      !this.accessibleName || this.accessibleName.trim() === '';
+    this._hasAccessibilityError = this._accessibleName.trim() === '';
   }
 
-  /** The computed accessible name */
-  @property({attribute: 'accessible-name'}) accessibleName: string;
-
   /**
    * The button's visual style. Defaults to "fill" (neutral fill).
    */
@@ -232,7 +234,20 @@ export default class CraftButton extends LionButtonSubmit {
   @property({attribute: 'icon-position'}) iconPosition: 'prefix' | 'suffix' =
     'prefix';
 
-  @query('[data-live-region]') liveRegion: HTMLElement;
+  @query('[data-live-region]') protected liveRegion: HTMLElement;
+
+  /**
+   * The name the button actually computes to, kept only so a button that ends
+   * up nameless can be flagged.
+   *
+   * Deliberately internal: it records a name, it does not apply one. Exposing
+   * it as an attribute invited consumers to "name" a button by setting it,
+   * which silenced the warning below while leaving nothing in the DOM for a
+   * screen reader. Name an icon-only button with `aria-label` on the host, or
+   * with a `label` on the icon it contains.
+   */
+  @state()
+  private _accessibleName: string = '';
 
   @state()
   private _hasAccessibilityError: boolean = false;
diff --git a/packages/craftcms-ui/src/components/callout/Callout.mdx b/packages/craftcms-ui/src/components/callout/Callout.mdx
new file mode 100644
index 00000000000..4aa31a7378d
--- /dev/null
+++ b/packages/craftcms-ui/src/components/callout/Callout.mdx
@@ -0,0 +1,126 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CalloutStories from './callout.stories';
+
+<Meta of={CalloutStories} name="Docs" />
+
+# Callout
+
+`<craft-callout>` is a boxed message that explains the state of the page, or the consequences of an action, in place.
+It holds an optional icon, an optional title, body content, and an optional trailing action.
+
+<Canvas of={CalloutStories.Default} sourceState="shown" />
+
+Use a callout for something the person needs to know while they are looking at the surrounding content.
+For a message about an action that has already completed, and that does not need to stay on screen, use a flash message instead.
+
+## Variant and Appearance
+
+`variant` carries the meaning, and `appearance` controls how loudly that meaning is stated.
+The two are independent, and they behave the same way here as on every other component that accepts them.
+See [Variants & Appearances](?path=/docs/tokens-variants-appearances--docs) for the underlying token mapping.
+
+Every variant except `neutral` also supplies a default icon, so a variant on its own is usually all a callout needs:
+
+<Canvas of={CalloutStories.Variants} sourceState="shown" />
+
+<Canvas of={CalloutStories.Appearances} sourceState="shown" />
+
+Reach for `solid` when the callout must be seen before anything else on the page, and `plain` when it is a footnote to the content it sits beside.
+
+## Content
+
+A callout has four regions: the icon, the title, the body, and the action.
+Each one collapses when it has nothing in it, so a callout with only body content is a plain box.
+
+The title has two forms.
+The `title` attribute is the shorthand:
+
+<Canvas of={CalloutStories.WithTitle} sourceState="shown" />
+
+Slot `title` instead when the title needs markup of its own.
+The slot takes precedence over the attribute.
+
+The `action` slot holds a trailing button or link.
+Give it `inherit` so it takes the callout's colour rather than the neutral palette:
+
+<Canvas of={CalloutStories.WithAction} sourceState="shown" />
+
+## The Icon
+
+The icon comes from the variant unless you say otherwise, and there are three ways to say otherwise.
+
+Set `icon` to a name to replace the variant's default:
+
+<Canvas of={CalloutStories.WithIcon} sourceState="shown" />
+
+Slot `icon` to supply your own artwork.
+Slotted content is honored even when no icon name resolves, so this works on a `neutral` callout that has no default of its own:
+
+<Canvas of={CalloutStories.CustomIcon} sourceState="shown" />
+
+Set `hide-icon` to suppress the region entirely, including a variant's default and anything slotted:
+
+<Canvas of={CalloutStories.HideIcon} sourceState="shown" />
+
+## Layout
+
+`rounded` selects which corners are rounded.
+Use `start` or `end` when the callout is flush against the top or bottom of another surface, and `none` when it spans a container edge to edge:
+
+<Canvas of={CalloutStories.Rounded} sourceState="shown" />
+
+`inline` renders the callout as a pill that flows with surrounding text rather than as a block-level box:
+
+<Canvas of={CalloutStories.Inline} sourceState="shown" />
+
+`size` steps the type down to `--c-text-sm` and tightens the gap between the icon and the text.
+The box padding is rem-based, so it does not scale with the type — pair `size` with `padding` when a small callout also wants a tighter box:
+
+<Canvas of={CalloutStories.Sizes} sourceState="shown" />
+
+## Padding
+
+Leaving `padding` off keeps the callout's own asymmetric pair: `--c-spacing-sm` on the block axis and `--c-spacing-md` on the inline one.
+A value that is given applies to both axes, the way a one-value CSS `padding` shorthand does.
+
+It accepts `sm`, `md`, `lg`, and `xl` (mapped to `--c-spacing-*`), or `0`/`none`:
+
+<Canvas of={CalloutStories.Padding} sourceState="shown" />
+
+The attribute is closed to that scale, so the design system stays the vocabulary for spacing.
+A value off it is ignored, and the callout's own default stands.
+
+For a value off the scale, or an asymmetric pair of your own, set the custom properties instead:
+
+<Canvas of={CalloutStories.CustomPadding} sourceState="shown" />
+
+```css
+craft-callout {
+  --c-callout-padding-block: var(--c-spacing-lg);
+  --c-callout-padding-inline: var(--c-spacing-sm);
+}
+```
+
+An `inline` callout also carries a little padding on the host itself.
+That is part of the pill treatment rather than of the box, and `padding` does not govern it.
+
+## Everything at Once
+
+<Canvas of={CalloutStories.KitchenSink} sourceState="shown" />
+
+## Accessibility
+
+A callout is a container, not a live region.
+It has no implicit role, and adding one to the page does not announce it.
+When a callout appears in response to something the person did — a failed save, a validation summary — the announcement is the responsibility of the code that inserts it.
+
+The icon is decorative.
+It repeats what the variant and the text already say, and carries no accessible name of its own, so nothing is lost when it is not announced.
+If you slot artwork that conveys something the text does not, give it its own label.
+
+Colour is not the only signal a callout carries, but it is the fastest one.
+Keep the text meaningful on its own, so a `danger` callout still reads as a problem when the colour is not perceived.
+
+## Properties
+
+<ArgTypes of={CalloutStories} />
diff --git a/packages/craftcms-ui/src/components/callout/callout.stories.ts b/packages/craftcms-ui/src/components/callout/callout.stories.ts
index 0a1eb0364b0..a05cd4b0409 100644
--- a/packages/craftcms-ui/src/components/callout/callout.stories.ts
+++ b/packages/craftcms-ui/src/components/callout/callout.stories.ts
@@ -1,164 +1,172 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html, nothing} from 'lit';
-
-import './callout.js';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {appearances} from '@src/constants/appearances.js';
 import {variants} from '@src/constants/variants.js';
+import {SPACING_STEPS} from '@src/mixins/Paddable.js';
+
+import './callout.js';
+import '../button/button.js';
+import '../icon/icon.js';
+import type CraftCallout from './callout.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `callout.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftCallout>('craft-callout');
+
+/**
+ * `padding` is supplied by the `Paddable` mixin, so the analyzer records no
+ * resolvable type for it and the helpers cannot derive a control. Build one
+ * from the same constant the mixin resolves against, rather than restating
+ * the values by hand.
+ */
+const paddingArgType = {
+  control: {type: 'select'},
+  options: [...SPACING_STEPS, 'none', '0'],
+} as const;
+
+const MESSAGE = 'Entries in this section are disabled for the current site.';
+
+const ACTION_BUTTON = `<craft-button type="button" variant="outline" inherit size="small">Action</craft-button>`;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Callout',
   component: 'craft-callout',
-  args: {
-    appearance: 'outline-fill',
-    variant: 'default',
-    flash: false,
-    message: 'This is a callout message',
-  },
-  argTypes: {
-    appearance: {
-      control: {type: 'select'},
-      options: appearances,
-    },
-    variant: {
-      control: {type: 'select'},
-      options: appearances,
-    },
-    message: {
-      control: {type: 'text'},
-    },
-    flash: {
-      control: {type: 'boolean'},
-    },
-  },
-  render: ({appearance, variant, message}) => {
-    return html`
-      <craft-callout variant="${variant}" appearance="${appearance}"
-        >${message}</craft-callout
-      >
-    `;
-  },
+  args: {...args, 'default-slot': MESSAGE},
+  argTypes: {...argTypes, padding: paddingArgType},
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
 } satisfies Meta<any>;
 
 export default meta;
 type Story = StoryObj<any>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+/**
+ * A `neutral` callout has no default icon, so the icon region collapses and
+ * the box is body content alone.
+ */
+export const Default: Story = {};
+
+/**
+ * Every variant except `neutral` supplies its own icon, so a variant alone is
+ * usually all a callout needs.
+ */
+export const Variants: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${variants.map(
+        (variant) =>
+          html`<craft-callout variant="${variant}">${variant}</craft-callout>`
+      )}
+    </div>
+  `,
+};
+
+/**
+ * `appearance` sets how loudly the variant is stated, from `solid` down to
+ * `plain`. See [Variants & Appearances](?path=/docs/tokens-variants-appearances--docs)
+ * for the underlying token mapping.
+ */
+export const Appearances: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${appearances.map(
+        (appearance) =>
+          html`<craft-callout variant="info" appearance="${appearance}"
+            >${appearance}</craft-callout
+          >`
+      )}
+    </div>
+  `,
+};
+
+/** The `title` attribute is the shorthand for the `title` slot. */
+export const WithTitle: Story = {
+  args: {variant: 'info', title: 'Site-specific content'},
 };
 
+/** Setting `icon` replaces whatever icon the variant would have supplied. */
 export const WithIcon: Story = {
-  args: {
-    variant: 'info',
-  },
-  render: ({appearance, variant, message}) => {
-    return html`
-      <craft-callout
-        variant="${variant}"
-        appearance="${appearance}"
-        icon="circle-info"
-      >
-        ${message}
-      </craft-callout>
-    `;
-  },
+  args: {variant: 'info', icon: 'circle-info'},
 };
 
-export const WithCustomIcon: Story = {
+/**
+ * Slotting `icon` replaces the icon region with your own artwork. Slotted
+ * content is honored even when no icon name resolves.
+ */
+export const CustomIcon: Story = {
   args: {
     variant: 'info',
-  },
-  render: ({appearance, variant, message}) => {
-    return html`
-      <craft-callout variant="${variant}" appearance="${appearance}">
-        <span slot="icon">
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke-width="1.5"
-            width="1lh"
-            height="1lh"
-            stroke="currentColor"
-          >
-            <path
-              stroke-linecap="round"
-              stroke-linejoin="round"
-              d="M9 12.75 11.25 15 15 9.75M21 12c0 1.268-.63 2.39-1.593 3.068a3.745 3.745 0 0 1-1.043 3.296 3.745 3.745 0 0 1-3.296 1.043A3.745 3.745 0 0 1 12 21c-1.268 0-2.39-.63-3.068-1.593a3.746 3.746 0 0 1-3.296-1.043 3.745 3.745 0 0 1-1.043-3.296A3.745 3.745 0 0 1 3 12c0-1.268.63-2.39 1.593-3.068a3.745 3.745 0 0 1 1.043-3.296 3.746 3.746 0 0 1 3.296-1.043A3.746 3.746 0 0 1 12 3c1.268 0 2.39.63 3.068 1.593a3.746 3.746 0 0 1 3.296 1.043 3.746 3.746 0 0 1 1.043 3.296A3.745 3.745 0 0 1 21 12Z"
-            />
-          </svg>
-        </span>
-
-        ${message}
-      </craft-callout>
-    `;
+    'icon-slot': `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" width="1lh" height="1lh" stroke="currentColor">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12c0 1.268-.63 2.39-1.593 3.068a3.745 3.745 0 0 1-1.043 3.296 3.745 3.745 0 0 1-3.296 1.043A3.745 3.745 0 0 1 12 21c-1.268 0-2.39-.63-3.068-1.593a3.746 3.746 0 0 1-3.296-1.043 3.745 3.745 0 0 1-1.043-3.296A3.745 3.745 0 0 1 3 12c0-1.268.63-2.39 1.593-3.068a3.745 3.745 0 0 1 1.043-3.296 3.746 3.746 0 0 1 3.296-1.043A3.746 3.746 0 0 1 12 3c1.268 0 2.39.63 3.068 1.593a3.746 3.746 0 0 1 3.296 1.043 3.746 3.746 0 0 1 1.043 3.296A3.745 3.745 0 0 1 21 12Z" />
+</svg>`,
   },
 };
 
-export const WithTitle: Story = {
-  args: {
-    variant: 'info',
-  },
-  render: ({appearance, variant, message}) => {
-    return html`
-      <craft-callout variant="${variant}" appearance="${appearance}">
-        <craft-icon slot="icon" name="circle-info"></craft-icon>
-        <span slot="title">This is a title</span>
-        ${message}
-      </craft-callout>
-    `;
-  },
+/** `hide-icon` suppresses the icon region, including a variant's default. */
+export const HideIcon: Story = {
+  args: {variant: 'warning', 'hide-icon': true},
 };
 
-export const KitchenSink: Story = {
-  args: {
-    variant: 'danger',
-  },
-  render: ({appearance, variant, message}) => {
-    return html`
-      <craft-callout variant="${variant}" appearance="${appearance}">
-        <craft-icon slot="icon" name="triangle-exclamation"></craft-icon>
-        <span slot="title">Unable to save entry.</span>
-
-        <p>Please correct the errors and try again.</p>
-        <ul class="list">
-          <li><a href="#">Title</a> is required.</li>
-          <li><a href="#">Slug</a> is required.</li>
-          <li><a href="#">Feature Image</a> must have at least one item.</li>
-        </ul>
-
-        <craft-button
-          type="button"
-          slot="action"
-          variant="outline"
-          inherit
-          size="small"
-          >Action</craft-button
-        >
-      </craft-callout>
-    `;
-  },
+/** The `action` slot holds a trailing button or link. */
+export const WithAction: Story = {
+  args: {variant: 'warning', 'action-slot': ACTION_BUTTON},
 };
 
-export const Variants: Story = {
-  args: {
-    appearance: 'outline-fill',
-  },
-  render({appearance}) {
-    return html`
-      <div class="stack">
-        ${variants.map((variant) => {
-          return html`
-            <craft-callout variant="${variant}" appearance="${appearance}"
-              >${variant}</craft-callout
-            >
-          `;
-        })}
-      </div>
-    `;
-  },
+/**
+ * `rounded` selects which corners are rounded, for callouts that sit flush
+ * against another surface.
+ */
+export const Rounded: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${(['all', 'start', 'end', 'none'] as const).map(
+        (rounded) =>
+          html`<craft-callout variant="info" rounded="${rounded}"
+            >rounded="${rounded}"</craft-callout
+          >`
+      )}
+    </div>
+  `,
+};
+
+/** `inline` renders the callout as a pill that flows with surrounding text. */
+export const Inline: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <p style="max-width: 48ch">
+      This entry has unsaved changes.
+      <craft-callout variant="warning" inline>Draft</craft-callout>
+      Publish it to make the changes live.
+    </p>
+  `,
+};
+
+/**
+ * `size` steps the type down. The box padding is rem-based, so it does not
+ * scale with the size — pair `size` with `padding` for a tighter box.
+ */
+export const Sizes: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${(['auto', 'small'] as const).map(
+        (size) =>
+          html`<craft-callout variant="info" size="${size}"
+            >size="${size}" — ${MESSAGE}</craft-callout
+          >`
+      )}
+    </div>
+  `,
 };
 
 /**
@@ -167,47 +175,52 @@ export const Variants: Story = {
  * applies to both axes, the way a one-value CSS `padding` shorthand does.
  */
 export const Padding: Story = {
-  args: {
-    variant: 'info',
-  },
-  argTypes: {
-    padding: {
-      control: {type: 'text'},
-    },
-  },
-  render: ({appearance, variant, message}) => {
-    return html`
-      <div class="stack">
-        ${[undefined, 'none', 'sm', 'md', 'lg', 'xl', '24', '2rem'].map(
-          (padding) => html`
-            <craft-callout
-              variant="${variant}"
-              appearance="${appearance}"
-              padding="${padding ?? nothing}"
-            >
-              ${padding ? `padding="${padding}"` : 'no padding attribute'} —
-              ${message}
-            </craft-callout>
-          `
-        )}
-      </div>
-    `;
-  },
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${[undefined, 'none', 'sm', 'md', 'lg', 'xl'].map(
+        (padding) => html`
+          <craft-callout variant="info" padding="${padding ?? nothing}">
+            ${padding ? `padding="${padding}"` : 'no padding attribute'} —
+            ${MESSAGE}
+          </craft-callout>
+        `
+      )}
+    </div>
+  `,
 };
 
-export const Appearances: Story = {
-  args: {},
-  render: (args) => {
-    return html`
-      <div class="stack">
-        ${appearances.map((appearance) => {
-          return html`
-            <craft-callout variant="info" appearance="${appearance}"
-              >${appearance}</craft-callout
-            >
-          `;
-        })}
-      </div>
-    `;
+/**
+ * The `padding` attribute is closed to the spacing scale. For a value off it,
+ * or an asymmetric pair of your own, set the custom properties instead.
+ */
+export const CustomPadding: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-callout
+      variant="info"
+      style="--c-callout-padding-block: 2.5rem; --c-callout-padding-inline: var(--c-spacing-xl)"
+    >
+      ${MESSAGE}
+    </craft-callout>
+  `,
+};
+
+/**
+ * Every region at once: a slotted title, a slotted icon, rich body content,
+ * and a trailing action.
+ */
+export const KitchenSink: Story = {
+  args: {
+    variant: 'danger',
+    'title-slot': 'Unable to save entry.',
+    'icon-slot': '<craft-icon name="triangle-exclamation"></craft-icon>',
+    'action-slot': ACTION_BUTTON,
+    'default-slot': `<p>Please correct the errors and try again.</p>
+<ul class="list">
+  <li><a href="#">Title</a> is required.</li>
+  <li><a href="#">Slug</a> is required.</li>
+  <li><a href="#">Feature Image</a> must have at least one item.</li>
+</ul>`,
   },
 };
diff --git a/packages/craftcms-ui/src/components/callout/callout.styles.ts b/packages/craftcms-ui/src/components/callout/callout.styles.ts
index 6789b5961e7..03c1cb6c3f7 100644
--- a/packages/craftcms-ui/src/components/callout/callout.styles.ts
+++ b/packages/craftcms-ui/src/components/callout/callout.styles.ts
@@ -8,10 +8,10 @@ export default css`
   .callout {
     --_radius: var(--c-callout-radius, var(--c-radius-md));
     /*
-      The two padding axes are declared separately because the callout's
-      default is asymmetric — a tight block edge, a roomier inline one. The
-      \`padding\` attribute writes both of these on this element when it's set,
-      so these fallbacks are what a callout with no \`padding\` renders with.
+      The two axes are declared separately so the padding attribute can write
+      either one on its own. These fallbacks are what a callout with no padding
+      renders with; the inline gap to the text is finished by the padding on
+      the icon, title, and description.
     */
     --_callout-padding-block: var(
       --c-callout-padding-block,
@@ -19,19 +19,22 @@ export default css`
     );
     --_callout-padding-inline: var(
       --c-callout-padding-inline,
-      var(--c-spacing-md)
+      var(--c-spacing-sm)
     );
     display: grid;
-    grid-template-areas: 'icon title action' 'icon description action';
+    grid-template-areas: 'icon description action';
     grid-template-columns: auto 1fr minmax(0, max-content);
-    gap: 0 var(--c-spacing-sm);
     align-items: start;
     padding: var(--_callout-padding-block) var(--_callout-padding-inline);
     border: 1px solid transparent;
   }
 
+  .callout--title {
+    grid-template-areas: 'icon title action' 'icon description action';
+  }
+
   .callout--hide-icon {
-    grid-template-areas: 'title action' 'description action';
+    grid-template-areas: 'description action';
     grid-template-columns: 1fr minmax(0, max-content);
 
     .callout__icon {
@@ -39,11 +42,20 @@ export default css`
     }
   }
 
+  .callout--hide-icon.callout--title {
+    grid-template-areas: 'title action' 'description action';
+  }
+
   .callout--small {
     font-size: var(--c-text-sm);
     gap: 0 var(--c-spacing-xs);
   }
 
+  .callout__title,
+  .callout__description {
+    padding-inline: var(--c-spacing-sm);
+  }
+
   .callout__title {
     display: flex;
     font-weight: bold;
@@ -51,12 +63,9 @@ export default css`
   }
 
   .callout__description {
-    grid-area: title;
-    align-self: center;
-  }
-
-  .callout__title + .callout__description {
     grid-area: description;
+    align-self: center;
+    padding-inline: var(--c-spacing-sm);
   }
 
   .callout__action {
@@ -72,6 +81,7 @@ export default css`
     justify-content: center;
     align-items: center;
     grid-area: icon;
+    padding-inline: var(--c-spacing-sm);
   }
 
   ::slotted(code) {
diff --git a/packages/craftcms-ui/src/components/callout/callout.test.ts b/packages/craftcms-ui/src/components/callout/callout.test.ts
index 1eb3047aa92..83d17b443d2 100644
--- a/packages/craftcms-ui/src/components/callout/callout.test.ts
+++ b/packages/craftcms-ui/src/components/callout/callout.test.ts
@@ -88,16 +88,17 @@ describe('craft-callout padding', () => {
   });
 
   /**
-   * So the shipped appearance is byte-identical to the `padding: sm md`
-   * shorthand this replaced: the pair still comes from the stylesheet, and the
-   * attribute only ever overrides it.
+   * The default pair still comes from the stylesheet, and the attribute only
+   * ever overrides it. Both axes are `sm`: the inline gap to the text is made
+   * up by the padding on the icon, title, and description themselves, so the
+   * container's own inline padding is the tighter step.
    */
-  it('keeps the asymmetric default in the stylesheet', () => {
+  it('keeps the default padding in the stylesheet', () => {
     expect(cssText).toContain(
       '--_callout-padding-block:var(--c-callout-padding-block,var(--c-spacing-sm));'
     );
     expect(cssText).toContain(
-      '--_callout-padding-inline:var(--c-callout-padding-inline,var(--c-spacing-md));'
+      '--_callout-padding-inline:var(--c-callout-padding-inline,var(--c-spacing-sm));'
     );
     expect(cssText).toContain(
       'padding:var(--_callout-padding-block)var(--_callout-padding-inline);'
@@ -119,17 +120,27 @@ describe('craft-callout padding', () => {
     expect(spacing(element, 'inline')).toBe('0');
   });
 
-  it.each([
-    ['0', '0'],
-    ['24', 'calc(24rem / 16)'],
-    ['2rem', '2rem'],
-    ['var(--my-spacing)', 'var(--my-spacing)'],
-  ])('resolves %s to %s', async (padding, expected) => {
-    const element = await createCallout({padding});
+  it('resolves 0 to zero', async () => {
+    const element = await createCallout({padding: '0'});
 
-    expect(spacing(element, 'block')).toBe(expected);
+    expect(spacing(element, 'block')).toBe('0');
   });
 
+  /**
+   * The attribute is closed to the spacing scale. An off-scale value writes
+   * nothing, so the callout's asymmetric default still applies — the custom
+   * properties are the escape hatch for arbitrary spacing.
+   */
+  it.each(['24', '2rem', 'var(--my-spacing)'])(
+    'ignores %s, which is off the spacing scale',
+    async (padding) => {
+      const element = await createCallout({padding});
+
+      expect(spacing(element, 'block')).toBe('');
+      expect(spacing(element, 'inline')).toBe('');
+    }
+  );
+
   it('re-renders when the padding property changes', async () => {
     const element = await createCallout();
 
diff --git a/packages/craftcms-ui/src/components/callout/callout.ts b/packages/craftcms-ui/src/components/callout/callout.ts
index 3312734e943..35d04c0b1b9 100644
--- a/packages/craftcms-ui/src/components/callout/callout.ts
+++ b/packages/craftcms-ui/src/components/callout/callout.ts
@@ -11,7 +11,21 @@ import {styleMap} from 'lit/directives/style-map.js';
 
 /**
  * @summary A boxed message: an optional icon, an optional title, body content,
- * and an optional trailing action.
+ * and an optional trailing action. Use a callout to explain the state of the
+ * page or the consequences of an action, in place rather than in a toast.
+ *
+ * `variant` carries the meaning and supplies a default icon. `appearance`
+ * controls how loudly that meaning is stated. Each region collapses when it
+ * has nothing in it, so a callout with only body content is a plain box.
+ *
+ * @slot - The callout's body content.
+ * @slot title - Title content, shown above the body. Takes precedence over the
+ *   `title` attribute, which is the shorthand for the same region.
+ * @slot icon - Leading artwork, replacing the icon the variant would supply.
+ *   Slotted content is honored even when no icon name resolves, and is
+ *   suppressed entirely by `hide-icon`.
+ * @slot action - Trailing content, shown after the body. Typically a button or
+ *   a link.
  *
  * @attr size - `small` steps the box down to `--c-text-sm` and tightens the gap
  *   between the icon and the text. Defaults to `auto`, which leaves the callout
@@ -19,17 +33,17 @@ import {styleMap} from 'lit/directives/style-map.js';
  *   `--c-spacing-*`, i.e. rem-based, so it does not scale with the size; set
  *   `padding` alongside it if a small callout wants a tighter box too.
  *
- * @attr padding - Spacing applied to the callout box. Accepts
- *   `sm`/`md`/`lg`/`xl` (mapped to `--c-spacing-*`), `0` or `none`, a unitless
- *   number (treated as pixels), or any CSS length.
+ * @attr {'sm'|'md'|'lg'|'xl'|'none'|'0'} padding - Spacing applied to the callout box. Accepts `sm`, `md`,
+ *   `lg`, and `xl` (mapped to `--c-spacing-*`), or `0`/`none`. Values off that
+ *   scale are ignored; set `--c-callout-padding-block` /
+ *   `--c-callout-padding-inline` for anything else.
  *
  *   The callout's own default is asymmetric — `--c-spacing-sm` on the block
  *   axis, `--c-spacing-md` on the inline one — so leaving `padding` off keeps
  *   exactly that pair. A value that *is* given applies to both axes, the way a
  *   one-value CSS `padding` shorthand does; scaling the two axes apart from a
  *   single value would make `padding="md"` mean something other than `md`.
- *   Reach for `--c-callout-padding-block` / `--c-callout-padding-inline` to
- *   keep an asymmetric pair of your own.
+ *   Reach for the custom properties to keep an asymmetric pair of your own.
  *
  *   Note that an `inline` callout also carries a little padding on the host
  *   itself, which is part of that pill treatment rather than of the box, and
@@ -47,30 +61,55 @@ export default class CraftCallout extends Paddable(LitElement, {
 }) {
   static override styles: CSSResultGroup = [variantsStyles, styles];
 
-  /** Variant style of the callout */
+  /**
+   * The semantic color group the callout draws its tokens from, and what the
+   * message means. Every variant except `neutral` also supplies a default
+   * icon.
+   */
   @property({reflect: true}) variant: VariantValue = Variant.Neutral;
 
   /**
-   * Appearance style of the callout
-   * @TODO maybe drop "outline"?
+   * How prominently the variant color is applied. `solid` is the loudest and
+   * `plain` the quietest.
    */
+  // @TODO maybe drop "outline"?
   @property({reflect: true}) appearance: AppearanceValue =
     Appearance.OutlineFill;
 
-  /** Title of the callout */
+  /**
+   * Title text, shown above the body. A shorthand for the `title` slot; slot
+   * it instead when the title needs markup.
+   */
   @property() override title: string = '';
 
-  /** Icon to display in the callout */
+  /**
+   * Name of the icon to show, replacing the one the variant would supply.
+   * Leave it unset to take the variant's default.
+   */
   @property() icon: string | null = null;
 
+  /**
+   * Suppresses the icon region entirely, including a variant's default icon
+   * and anything slotted into `icon`.
+   */
   @property({type: Boolean, attribute: 'hide-icon'}) hideIcon: boolean = false;
 
+  /**
+   * Which corners are rounded. Use `start` or `end` when the callout is
+   * flush against the top or bottom of another surface, and `none` when it
+   * spans a container edge to edge.
+   */
   @property({reflect: true})
   rounded: 'all' | 'start' | 'end' | 'none' = 'all';
 
+  /**
+   * Renders the callout as an inline pill that flows with surrounding text,
+   * rather than as a block-level box.
+   */
   @property({reflect: true, type: Boolean})
   inline: boolean = false;
 
+  /** See the `size` attribute above. */
   @property()
   size: 'small' | 'auto' = 'auto';
 
@@ -86,7 +125,7 @@ export default class CraftCallout extends Paddable(LitElement, {
     this.resolvedIcon = this.icon ?? this.getDefaultIcon();
   }
 
-  getDefaultIcon() {
+  protected getDefaultIcon() {
     switch (this.variant) {
       case Variant.Info:
         return 'lightbulb';
diff --git a/packages/craftcms-ui/src/components/card/Card.mdx b/packages/craftcms-ui/src/components/card/Card.mdx
new file mode 100644
index 00000000000..8665ea9eb8c
--- /dev/null
+++ b/packages/craftcms-ui/src/components/card/Card.mdx
@@ -0,0 +1,107 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CardStories from './card.stories';
+
+<Meta of={CardStories} name="Docs" />
+
+# Card
+
+`<craft-card>` is a bordered, rounded surface that groups related content into a standalone block.
+It holds an optional header, an optional thumbnail column, body content, and an optional footer.
+
+<Canvas of={CardStories.Default} sourceState="shown" />
+
+Use a card when the content is a block a person reads or acts on as a unit — an element in an index view, a settings group, a summary panel.
+For a compact reference to a single entity in a list, use [Chip](?path=/docs/components-chip--docs) instead.
+
+## Regions
+
+A card has four regions, and each one is only rendered when there is something to put in it.
+A card with body content alone is a plain bordered surface with no header or footer chrome.
+
+The header appears as soon as the `label` attribute is set, or the `header`, `label`, or `actions` slot is filled:
+
+<Canvas of={CardStories.WithLabel} sourceState="shown" />
+
+The `actions` slot sits at the end of the header:
+
+<Canvas of={CardStories.WithActions} sourceState="shown" />
+
+The footer appears only when the `footer` slot is filled:
+
+<Canvas of={CardStories.WithFooter} sourceState="shown" />
+
+## Replacing the Header
+
+There are two levels of override, depending on how much of the default layout you want to keep.
+
+Fill the `label` slot to replace the label text while keeping the header's layout, so slotted actions still sit at the end:
+
+<Canvas of={CardStories.CustomLabel} sourceState="shown" />
+
+Fill the `header` slot to replace the region outright.
+The default `label`/`actions` layout is not rendered at all, so anything you slot is responsible for its own arrangement:
+
+<Canvas of={CardStories.CustomHeader} sourceState="shown" />
+
+## The Thumbnail
+
+Content in the `thumbnail` slot renders in a fixed column beside the body:
+
+<Canvas of={CardStories.WithThumbnail} sourceState="shown" />
+
+Two attributes govern it.
+`show-thumb` is on by default and gates the column entirely — set it to `false` to drop the thumbnail without removing the slotted content.
+`thumb-alignment` puts the column at the `start` or the `end` of the body:
+
+<Canvas of={CardStories.ThumbnailAlignment} sourceState="shown" />
+
+## Active State
+
+`active` marks a card as selected, and is reflected to the host so it can be styled from outside the component.
+Element index views bind it to row selection:
+
+<Canvas of={CardStories.Active} sourceState="shown" />
+
+`active` is presentational.
+It does not make the card focusable or announce a selection, so a selectable list is responsible for its own control and its own semantics.
+
+## Styling
+
+`padding` sets the spacing of every padded region from the shared spacing scale, the same as [Pane](?path=/docs/components-pane--docs) and [Callout](?path=/docs/components-callout--docs):
+
+```html
+<craft-card label="Entry" padding="lg"></craft-card>
+```
+
+Leave it unset and each region keeps its own default — the header is tighter than the body — which is what a card in an index renders with.
+
+For the rest, the card exposes seven CSS parts and four `--c-card-*` custom properties, both listed in full under [Properties](#properties).
+
+<Canvas of={CardStories.CustomProperties} sourceState="shown" />
+
+```css
+craft-card {
+  --c-card-radius: 0;
+  --c-card-shadow: none;
+  --c-card-padding-inline: 2rem;
+}
+```
+
+The card draws its own chrome but leaves attributes on the host alone, so an `id`, `style` custom properties, and `data-*` metadata can all be set on it directly.
+
+## Everything at Once
+
+<Canvas of={CardStories.KitchenSink} sourceState="shown" />
+
+## Accessibility
+
+A card is a container, not a control.
+It has no implicit role and does not receive focus, so the content decides the semantics.
+
+- **Give the card a heading if it is one.** The `label` renders as plain text, not a heading element. When a card is a section of a page, slot a real heading into `label` so it lands in the document outline.
+- **Name the header actions.** An icon-only button in the `actions` slot needs an `aria-label`; the card's label does not name it.
+- **Keep a decorative thumbnail decorative.** Artwork that only repeats the label takes `alt=""` or `aria-hidden`. If it carries meaning the text does not, give it a name of its own.
+
+## Properties
+
+<ArgTypes of={CardStories} />
diff --git a/packages/craftcms-ui/src/components/card/card.stories.ts b/packages/craftcms-ui/src/components/card/card.stories.ts
index 181ace4c982..153eba9b3a4 100644
--- a/packages/craftcms-ui/src/components/card/card.stories.ts
+++ b/packages/craftcms-ui/src/components/card/card.stories.ts
@@ -2,11 +2,31 @@ import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import type CraftCard from './card.js';
 import './card.js';
 import '../button/button.js';
 import '../icon/icon.js';
 
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `card.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftCard>('craft-card');
+
+const BODY =
+  'Cards group related content into a bordered surface, with optional header, footer, and thumbnail regions.';
+
+const ACTION_BUTTON = `<craft-button icon="ellipsis" variant="plain" size="small" aria-label="Actions"></craft-button>`;
+
+const THUMB = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" role="img" aria-label="Placeholder thumbnail" style="display: block; width: 100%; height: auto; border-radius: 4px;">
+  <rect width="120" height="120" fill="#e2e8f0" />
+  <path d="M20 88l24-28 18 20 14-16 24 24v12H20z" fill="#94a3b8" />
+  <circle cx="42" cy="38" r="10" fill="#94a3b8" />
+</svg>`;
+
 const placeholderThumb = html`
   <svg
     slot="thumbnail"
@@ -23,49 +43,32 @@ const placeholderThumb = html`
 `;
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * The helpers add slot and CSS-property args alongside the element's own
+ * properties, so stories are typed against both.
+ */
+type CardArgs = CraftCard & typeof args;
+
 const meta = {
   title: 'Components/Card',
   component: 'craft-card',
-  args: {
-    label: 'Card label',
-    active: false,
-    thumbAlignment: 'start',
-  },
-  argTypes: {
-    label: {
-      control: {type: 'text'},
-      description:
-        'Header label; the header only renders when this (or a header/label/actions slot) is present',
-    },
-    active: {
-      control: {type: 'boolean'},
-    },
-    thumbAlignment: {
-      control: {type: 'select'},
-      options: ['start', 'end'],
-    },
-  },
-  render: ({label, active}) => html`
-    <craft-card label="${label}" ?active="${active}">
-      Cards group related content into a bordered surface, with optional header,
-      footer, and thumbnail regions.
-    </craft-card>
-  `,
-} satisfies Meta<CraftCard>;
+  args: {...args, label: 'Card label', 'default-slot': BODY},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<CardArgs>;
 
 export default meta;
-type Story = StoryObj<CraftCard>;
-
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+type Story = StoryObj<CardArgs>;
 
 /** Body only — with no label or header/label/actions slot, no header renders. */
 export const Default: Story = {
-  render: () => html`
-    <craft-card>
-      A bare card is just the bordered body surface — no header or footer chrome
-      until content asks for it.
-    </craft-card>
-  `,
+  args: {
+    label: '',
+    'default-slot':
+      'A bare card is just the bordered body surface — no header or footer chrome until content asks for it.',
+  },
 };
 
 /** The `label` attribute alone brings in the header region. */
@@ -73,94 +76,62 @@ export const WithLabel: Story = {};
 
 /** Buttons in the `actions` slot sit at the end of the header. */
 export const WithActions: Story = {
-  render: ({label}) => html`
-    <craft-card label="${label}">
-      <craft-button
-        slot="actions"
-        icon="pencil"
-        appearance="plain"
-        size="small"
-        aria-label="Edit"
-      ></craft-button>
-      <craft-button
-        slot="actions"
-        icon="ellipsis"
-        appearance="plain"
-        size="small"
-        aria-label="Actions"
-      ></craft-button>
-
-      Header actions are slotted content, so anything works — icon buttons, an
-      action menu, a switch.
-    </craft-card>
-  `,
+  args: {
+    'actions-slot': `<craft-button icon="pencil" variant="plain" size="small" aria-label="Edit"></craft-button>
+${ACTION_BUTTON}`,
+    'default-slot':
+      'Header actions are slotted content, so anything works — icon buttons, an action menu, a switch.',
+  },
 };
 
 /** The `label` slot replaces the label text while keeping the header layout. */
 export const CustomLabel: Story = {
-  render: () => html`
-    <craft-card>
-      <span
-        slot="label"
-        style="display: inline-flex; align-items: center; gap: 0.5em;"
-      >
-        <craft-icon name="newspaper"></craft-icon>
-        Article
-        <code>article</code>
-      </span>
-
-      A slotted label can carry richer content than plain text — icons, handles,
-      badges.
-    </craft-card>
-  `,
+  args: {
+    'label-slot': `<span style="display: inline-flex; align-items: center; gap: 0.5em;">
+  <craft-icon name="newspaper"></craft-icon>
+  Article
+  <code>article</code>
+</span>`,
+    'default-slot':
+      'A slotted label can carry richer content than plain text — icons, handles, badges.',
+  },
 };
 
 /** The `header` slot replaces the whole default label/actions header. */
 export const CustomHeader: Story = {
-  render: () => html`
-    <craft-card>
-      <div
-        slot="header"
-        style="display: flex; align-items: center; justify-content: space-between; inline-size: 100%;"
-      >
-        <strong>Custom header</strong>
-        <em>anything goes here</em>
-      </div>
-
-      When the header slot is filled, the default label/actions layout is
-      replaced entirely.
-    </craft-card>
-  `,
+  args: {
+    'header-slot': `<div style="display: flex; align-items: center; justify-content: space-between; inline-size: 100%;">
+  <strong>Custom header</strong>
+  <em>anything goes here</em>
+</div>`,
+    'default-slot':
+      'When the header slot is filled, the default label/actions layout is replaced entirely.',
+  },
 };
 
 /** The footer region only renders when the `footer` slot is filled. */
 export const WithFooter: Story = {
-  render: ({label}) => html`
-    <craft-card label="${label}">
-      Body content.
-
-      <div
-        slot="footer"
-        style="display: flex; justify-content: space-between; inline-size: 100%;"
-      >
-        <span>Updated 2 hours ago</span>
-        <span>Draft</span>
-      </div>
-    </craft-card>
-  `,
+  args: {
+    'default-slot': 'Body content.',
+    'footer-slot': `<div style="display: flex; justify-content: space-between; inline-size: 100%;">
+  <span>Updated 2 hours ago</span>
+  <span>Draft</span>
+</div>`,
+  },
 };
 
 /** Thumbnail content renders in a fixed-width column beside the body. */
 export const WithThumbnail: Story = {
-  render: ({label, thumbAlignment}) => html`
-    <craft-card label="${label}" thumb-alignment="${thumbAlignment}">
-      ${placeholderThumb} The thumbnail slot gets a 120px column;
-      <code>thumb-alignment</code> puts it at the start or end of the body.
-    </craft-card>
-  `,
+  args: {
+    'thumbnail-slot': THUMB,
+    'default-slot':
+      'The thumbnail slot gets a 120px column; thumb-alignment puts it at the start or end of the body.',
+  },
 };
 
+/** `thumb-alignment` puts the thumbnail column before or after the body. */
 export const ThumbnailAlignment: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
     <div style="display: grid; gap: 1rem;">
       <craft-card label='thumb-alignment="start"'>
@@ -175,10 +146,13 @@ export const ThumbnailAlignment: Story = {
 
 /** The reflected `active` attribute marks selection (e.g. element index rows). */
 export const Active: Story = {
-  render: ({label}) => html`
+  parameters: {controls: {disable: true}},
+  render: () => html`
     <div style="display: grid; gap: 1rem;">
-      <craft-card label="${label}">An inactive card for comparison.</craft-card>
-      <craft-card label="${label}" active>
+      <craft-card label="Card label"
+        >An inactive card for comparison.</craft-card
+      >
+      <craft-card label="Card label" active>
         An active card — loud header/footer fill and border.
       </craft-card>
     </div>
@@ -187,9 +161,10 @@ export const Active: Story = {
 
 /** Radius, shadow, and padding are themeable via custom properties. */
 export const CustomProperties: Story = {
-  render: ({label}) => html`
+  parameters: {controls: {disable: true}},
+  render: () => html`
     <craft-card
-      label="${label}"
+      label="Card label"
       style="--c-card-radius: 0; --c-card-shadow: none; --c-card-padding-inline: 2rem; --c-card-padding-block: 1rem;"
     >
       Square corners, no shadow, and roomier padding via
@@ -198,36 +173,16 @@ export const CustomProperties: Story = {
   `,
 };
 
+/** Every region at once: header label and actions, thumbnail, body, footer. */
 export const KitchenSink: Story = {
-  render: ({label, active, thumbAlignment}) => html`
-    <craft-card
-      label="${label}"
-      ?active="${active}"
-      thumb-alignment="${thumbAlignment}"
-    >
-      <craft-button
-        slot="actions"
-        icon="ellipsis"
-        appearance="plain"
-        size="small"
-        aria-label="Actions"
-      ></craft-button>
-
-      ${placeholderThumb}
-
-      <strong>Autumn on the Coast</strong>
-      <p style="margin: 0.25em 0 0">
-        Header label and actions, a leading thumbnail, body content, and a
-        metadata footer — all regions at once.
-      </p>
-
-      <div
-        slot="footer"
-        style="display: flex; justify-content: space-between; inline-size: 100%;"
-      >
-        <span>Posted Oct 14</span>
-        <span>Live</span>
-      </div>
-    </craft-card>
-  `,
+  args: {
+    label: 'Autumn on the Coast',
+    'actions-slot': ACTION_BUTTON,
+    'thumbnail-slot': THUMB,
+    'default-slot': `<p style="margin: 0">Header label and actions, a leading thumbnail, body content, and a metadata footer — all regions at once.</p>`,
+    'footer-slot': `<div style="display: flex; justify-content: space-between; inline-size: 100%;">
+  <span>Posted Oct 14</span>
+  <span>Live</span>
+</div>`,
+  },
 };
diff --git a/packages/craftcms-ui/src/components/card/card.ts b/packages/craftcms-ui/src/components/card/card.ts
index 06587130569..12abcf8cde7 100644
--- a/packages/craftcms-ui/src/components/card/card.ts
+++ b/packages/craftcms-ui/src/components/card/card.ts
@@ -1,8 +1,14 @@
-import {property, state} from 'lit/decorators.js';
+import {property} from 'lit/decorators.js';
 import type {CSSResultGroup} from 'lit';
 import {html, LitElement, nothing} from 'lit';
+import {styleMap} from 'lit/directives/style-map.js';
+import {Paddable} from '@src/mixins/Paddable.js';
 import styles from './card.styles.js';
 import {classMap} from 'lit/directives/class-map.js';
+import {
+  hasSlotted,
+  LightDomController,
+} from '@src/controllers/LightDomController';
 
 /**
  * @summary A surface that groups related content into a bordered, rounded
@@ -15,12 +21,9 @@ import {classMap} from 'lit/directives/class-map.js';
  * (with the `label` attribute as the default label content). The footer region
  * is only rendered when the `footer` slot is filled.
  *
- * Host attributes are applied directly to the element, so the server-rendered
- * wrapper attributes that accompany an element's card HTML (its `id`, `style`
- * custom properties, and `data-*` metadata) can be spread onto it with the
- * `attrs()` utility — e.g. `v-bind="attrs(element.cardAttributes)"`. `class` is
- * usually excluded from that bind (`{exclude: ['class']}`), since the component
- * renders its own card chrome rather than the server's `.card` classes.
+ * The card renders its own chrome, so attributes set on the host are left
+ * alone — an `id`, `style` custom properties, and `data-*` metadata can all be
+ * spread onto it without the component interfering.
  *
  * @slot - The card's body content.
  * @slot header - The full header region. Replaces the default
@@ -30,8 +33,18 @@ import {classMap} from 'lit/directives/class-map.js';
  * @slot actions - Action content shown at the end of the header, e.g. buttons.
  * @slot footer - Footer content. The footer is only rendered when this slot is
  *   filled.
+ * @slot thumbnail - Artwork shown in a fixed column beside the body. Rendered
+ *   only while `show-thumb` is set; `thumb-alignment` puts the column at the
+ *   start or the end of the body.
  *
+ * @csspart base - The card's outermost element, which carries the surface and
+ *   the border.
+ * @csspart header - The default header region.
  * @csspart label - The label slot within the header.
+ * @csspart actions - The wrapper around the `actions` slot.
+ * @csspart body - The region holding the thumbnail column and the content.
+ * @csspart thumbnail - The fixed column the `thumbnail` slot renders into.
+ * @csspart footer - The default footer region.
  *
  * @cssproperty --c-card-radius - Corner radius. Defaults to `--c-radius-md`.
  * @cssproperty --c-card-shadow - Box shadow. Defaults to `--c-shadow-sm`.
@@ -40,8 +53,20 @@ import {classMap} from 'lit/directives/class-map.js';
  * @cssproperty --c-card-padding-block - Block (vertical) padding of the header,
  *   body, and footer. Defaults to `--c-spacing-sm` for the header/footer and
  *   `--c-spacing-md` for the body.
+ *
+ * @property padding - Spacing for every padded region, from the shared spacing
+ *   scale. Supplied by the `Paddable` mixin, the same as `craft-pane` and
+ *   `craft-callout`. Leave it unset to keep the per-region defaults above; set
+ *   the custom properties for anything the scale cannot express.
  */
-export default class CraftCard extends LitElement {
+export default class CraftCard extends Paddable(LitElement, {
+  // The public properties, so an unset `padding` leaves the stylesheet's
+  // per-region defaults alone and only an explicit value overrides them.
+  customProperty: ['--c-card-padding-block', '--c-card-padding-inline'],
+}) {
+  // In the CP, an element's server-rendered card attributes are spread onto
+  // the host with `attrs(element.cardAttributes)`, excluding `class` — the
+  // component draws its own chrome rather than the server's `.card` classes.
   static override styles: CSSResultGroup = [styles];
 
   /** Label shown in the header when the `label` slot is not filled. */
@@ -57,85 +82,54 @@ export default class CraftCard extends LitElement {
   /** Whether the thumbnail region renders at all, even with slotted content. */
   @property({attribute: 'show-thumb', type: Boolean}) showThumb: boolean = true;
 
-  @property({attribute: 'thumb-alignment'}) thumbAlignment: 'start' | 'end' =
-    'start';
-
   /**
-   * Whether the thumbnail slot currently has assigned content. Tracked as reactive
-   * state and updated from the slot's `slotchange` event, since Lit doesn't
-   * re-render on slotted light-DOM changes on its own — without this the card's
-   * presence-derived rendering would go stale (e.g. when the CVD swaps the thumb).
+   * Which side of the body the thumbnail column sits on. Has no effect unless
+   * the `thumbnail` slot is filled and `show-thumb` is set.
    */
-  @state() private _hasThumbnail = false;
+  @property({attribute: 'thumb-alignment'}) thumbAlignment: 'start' | 'end' =
+    'start';
 
   /**
-   * Whether header/footer content is currently slotted. The header and footer
-   * slots only render when filled, so (unlike the always-rendered thumbnail
-   * slot) their presence can't be tracked via `slotchange` — a light-DOM
-   * observer keeps them fresh when a consumer swaps slotted content.
+   * The header, footer, and thumbnail regions only render when they have
+   * something in them, so their slots can't report their own changes — an
+   * unrendered slot never fires `slotchange`. The controller re-renders the
+   * card whenever its light DOM moves, which is how a thumbnail swapped in
+   * by the element index shows up.
    */
-  @state() private _hasSlottedHeader = false;
-
-  @state() private _hasSlottedFooter = false;
-
-  private _lightDomObserver = new MutationObserver(() =>
-    this._syncSlotPresence()
-  );
-
-  override connectedCallback() {
-    super.connectedCallback();
-    this._syncSlotPresence();
-    this._lightDomObserver.observe(this, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: ['slot'],
-    });
-  }
-
-  override disconnectedCallback() {
-    super.disconnectedCallback();
-    this._lightDomObserver.disconnect();
-  }
-
-  private _syncSlotPresence() {
-    this._hasSlottedHeader =
-      !!this.querySelector('[slot="header"]') ||
-      !!this.querySelector('[slot="label"]') ||
-      !!this.querySelector('[slot="actions"]');
-    this._hasSlottedFooter = !!this.querySelector('[slot="footer"]');
-    this._hasThumbnail = !!this.querySelector('[slot="thumbnail"]');
-  }
-
-  private _handleThumbnailSlotChange(event: Event) {
-    const slot = event.target as HTMLSlotElement;
-    this._hasThumbnail = slot.assignedElements({flatten: true}).length > 0;
-  }
+  private _lightDom = new LightDomController(this);
 
   override render() {
-    const hasSlottedHeader = !!this.label || this._hasSlottedHeader;
-    const hasSlottedFooter = this._hasSlottedFooter;
-    const showThumbnail = this.showThumb && this._hasThumbnail;
+    const hasSlottedHeader =
+      !!this.label || hasSlotted(this, 'header', 'label', 'actions');
+    const hasSlottedFooter = hasSlotted(this, 'footer');
+    const showThumbnail = this.showThumb && hasSlotted(this, 'thumbnail');
 
     return html`
       <div
+        part="base"
         class="${classMap({
           card: true,
           'card--has-thumbnail': showThumbnail,
         })}"
+        style="${styleMap(this.paddingStyles)}"
       >
         ${hasSlottedHeader
-          ? html`<div class="card__header">
+          ? html`<div class="card__header" part="header">
               <slot name="header">
                 <slot name="label" class="card__label" part="label"
                   >${this.label}</slot
                 >
-                <slot name="actions" class="card__actions"></slot>
+                <slot
+                  name="actions"
+                  class="card__actions"
+                  part="actions"
+                ></slot>
               </slot>
             </div>`
           : nothing}
 
         <div
+          part="body"
           class="${classMap({
             'card-body': true,
             'card-body--thumb-start':
@@ -144,11 +138,12 @@ export default class CraftCard extends LitElement {
               showThumbnail && this.thumbAlignment === 'end',
           })}"
         >
-          <div class="card-body__thumb" ?hidden="${!showThumbnail}">
-            <slot
-              name="thumbnail"
-              @slotchange="${this._handleThumbnailSlotChange}"
-            ></slot>
+          <div
+            class="card-body__thumb"
+            part="thumbnail"
+            ?hidden="${!showThumbnail}"
+          >
+            <slot name="thumbnail"></slot>
           </div>
 
           <div class="card-body__main">
@@ -157,7 +152,9 @@ export default class CraftCard extends LitElement {
         </div>
 
         ${hasSlottedFooter
-          ? html`<div class="card__footer"><slot name="footer"></slot></div>`
+          ? html`<div class="card__footer" part="footer">
+              <slot name="footer"></slot>
+            </div>`
           : nothing}
       </div>
     `;
diff --git a/packages/craftcms-ui/src/components/card/padding-parts.test.ts b/packages/craftcms-ui/src/components/card/padding-parts.test.ts
new file mode 100644
index 00000000000..62eb603f508
--- /dev/null
+++ b/packages/craftcms-ui/src/components/card/padding-parts.test.ts
@@ -0,0 +1,73 @@
+import {expect, test} from 'vite-plus/test';
+import {html, render} from 'lit';
+
+import './card.js';
+import type CraftCard from './card.js';
+
+async function mount(template: unknown): Promise<CraftCard> {
+  const host = document.createElement('div');
+  document.body.append(host);
+  render(template as never, host);
+  const card = host.firstElementChild as CraftCard;
+  await card.updateComplete;
+  return card;
+}
+
+function parts(card: CraftCard): string[] {
+  return [...(card.shadowRoot?.querySelectorAll('[part]') ?? [])].map((el) =>
+    el.getAttribute('part')!
+  );
+}
+
+test('exposes the same regions craft-pane does', async () => {
+  const card = await mount(
+    html`<craft-card label="Entry">
+      <p>Body</p>
+      <div slot="actions">Actions</div>
+      <div slot="footer">Footer</div>
+    </craft-card>`
+  );
+
+  expect(parts(card)).toEqual(
+    expect.arrayContaining([
+      'base',
+      'header',
+      'label',
+      'actions',
+      'body',
+      'footer',
+    ])
+  );
+});
+
+test('writes nothing when no padding is set, so the per-region defaults stand', async () => {
+  const card = await mount(html`<craft-card label="Entry"></craft-card>`);
+  const base = card.shadowRoot!.querySelector<HTMLElement>('[part="base"]')!;
+
+  expect(card.padding).toBeUndefined();
+  expect(base.style.getPropertyValue('--c-card-padding-block')).toBe('');
+  expect(base.style.getPropertyValue('--c-card-padding-inline')).toBe('');
+});
+
+test('an explicit padding overrides both axes', async () => {
+  const card = await mount(
+    html`<craft-card label="Entry" padding="lg"></craft-card>`
+  );
+  const base = card.shadowRoot!.querySelector<HTMLElement>('[part="base"]')!;
+
+  expect(base.style.getPropertyValue('--c-card-padding-block')).toBe(
+    'var(--c-spacing-lg)'
+  );
+  expect(base.style.getPropertyValue('--c-card-padding-inline')).toBe(
+    'var(--c-spacing-lg)'
+  );
+});
+
+test('ignores a value off the spacing scale', async () => {
+  const card = await mount(
+    html`<craft-card label="Entry" padding="3.5rem"></craft-card>`
+  );
+  const base = card.shadowRoot!.querySelector<HTMLElement>('[part="base"]')!;
+
+  expect(base.style.getPropertyValue('--c-card-padding-block')).toBe('');
+});
diff --git a/packages/craftcms-ui/src/components/checkbox-group/CheckboxGroup.mdx b/packages/craftcms-ui/src/components/checkbox-group/CheckboxGroup.mdx
new file mode 100644
index 00000000000..a404a8c673b
--- /dev/null
+++ b/packages/craftcms-ui/src/components/checkbox-group/CheckboxGroup.mdx
@@ -0,0 +1,30 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CheckboxGroupStories from './checkbox-group.stories';
+
+<Meta of={CheckboxGroupStories} name="Docs" />
+
+# Checkbox Group
+
+`<craft-checkbox-group>` collects [Checkbox](?path=/docs/form-controls-choice-controls-checkbox--docs)es that share a name, for a choice where any number of options can be selected.
+
+<Canvas of={CheckboxGroupStories.Default} sourceState="shown" />
+
+The group owns the name and the value: its `modelValue` is the array of what is checked, rather than each checkbox carrying its own.
+
+Use a [Radio Group](?path=/docs/form-controls-choice-controls-radio-group--docs) when exactly one option may be chosen.
+
+## Labelling the Group
+
+The group takes its own `label`, `help-text`, and `feedback` — and it should. The individual checkboxes name the options; only the group can name the question they answer.
+
+Validation belongs at the group level too, since a rule like "choose at least one" is about the set rather than any single box.
+
+## Server-Rendered Markup
+
+A group rendered by the server adopts the name already present on its inputs.
+
+That is load-bearing rather than a convenience: Lion syncs every registered child's name to the group's, so a group that upgraded without a name would strip the server's names off the inputs and break native posting.
+
+## Properties
+
+<ArgTypes of={CheckboxGroupStories} />
diff --git a/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.stories.ts b/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.stories.ts
index 89be9a5f808..5e979f67ccb 100644
--- a/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.stories.ts
+++ b/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.stories.ts
@@ -1,45 +1,68 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './checkbox-group.js';
 import '../checkbox/checkbox.js';
+import type CraftCheckboxGroup from './checkbox-group.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `checkbox-group.ts` surfaces it here without touching this file.
+ *
+ * Lion's own `label` and `help-text` are slots here, so they are set through
+ * the `label-slot` and `help-text-slot` args rather than as attributes.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftCheckboxGroup>(
+  'craft-checkbox-group'
+);
+
+type CheckboxGroupArgs = CraftCheckboxGroup & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Checkbox Group',
+  title: 'Form Controls/Choice Controls/Checkbox Group',
   component: 'craft-checkbox-group',
-  args: {},
-  render: function () {
-    return html`<craft-checkbox-group name="scientists[]" label="Scientists">
-      <craft-checkbox
-        label="Marie Curie"
-        .choiceValue=${'curie'}
-      ></craft-checkbox>
-      <craft-checkbox
-        label="Ada Lovelace"
-        .choiceValue=${'lovelace'}
-        .checked=${true}
-      ></craft-checkbox>
-      <craft-checkbox
-        label="Grace Hopper"
-        .choiceValue=${'hopper'}
-      ></craft-checkbox>
-    </craft-checkbox-group>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, name: 'scientists[]', 'label-slot': 'Scientists'},
+  argTypes,
+  // The options are written out rather than generated: each one carries a
+  // `choiceValue`, which is a property rather than an attribute, so it cannot
+  // be expressed in a slot's markup string.
+  render: (args) => html`
+    <craft-checkbox-group
+      name="${args.name ?? ''}"
+      ?disabled="${args.disabled}"
+    >
+      <label slot="label">${args['label-slot']}</label>
+      <craft-checkbox .choiceValue="${'curie'}">
+        <label slot="label">Marie Curie</label>
+      </craft-checkbox>
+      <craft-checkbox .choiceValue="${'lovelace'}" checked>
+        <label slot="label">Ada Lovelace</label>
+      </craft-checkbox>
+      <craft-checkbox .choiceValue="${'hopper'}">
+        <label slot="label">Grace Hopper</label>
+      </craft-checkbox>
+    </craft-checkbox-group>
+  `,
+} satisfies Meta<CheckboxGroupArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CheckboxGroupArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** The group owns the name; its value is the array of what is checked. */
+export const Default: Story = {};
 
+/**
+ * A group rendered by the server adopts the name already on its inputs, so the
+ * markup keeps posting the way it did before the component upgraded.
+ */
 export const ServerRendered: Story = {
+  parameters: {controls: {disable: true}},
   render: () =>
-    html`<craft-checkbox-group label="Allowed kinds">
+    html`<craft-checkbox-group>
+      <label slot="label">Allowed kinds</label>
       <div>
         <craft-checkbox>
           <input
diff --git a/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.ts b/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.ts
index 120df748180..b28a9fce792 100644
--- a/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.ts
+++ b/packages/craftcms-ui/src/components/checkbox-group/checkbox-group.ts
@@ -1,47 +1,28 @@
 import {LionCheckboxGroup} from '@lion/ui/checkbox-group.js';
-import {css, type PropertyValues} from 'lit';
+import {css} from 'lit';
 import {baseFieldStyles} from '@src/styles/form.styles';
-
-export default class CraftCheckboxGroup extends LionCheckboxGroup {
-  private __ssrNameAdopted = false;
-
-  /**
-   * Adopts the group name from server-rendered checkbox inputs. Lion syncs
-   * each registered child's name to the group's (`name || ''`), so a
-   * nameless group would strip the SSR'd names and break native posting.
-   * Runs before `super.connectedCallback()` so the name is set before any
-   * child registers; `willUpdate` is the fallback for streaming parsing,
-   * where the element can connect before its children exist.
-   */
-  override connectedCallback() {
-    this.__adoptSlottedName();
-    super.connectedCallback();
-  }
-
-  protected override willUpdate(changedProperties: PropertyValues) {
-    this.__adoptSlottedName();
-    super.willUpdate(changedProperties);
-  }
-
-  private __adoptSlottedName() {
-    if (this.__ssrNameAdopted || this.name) {
-      return;
-    }
-
-    const input = this.querySelector<HTMLInputElement>(
-      'input[type="checkbox"][name]'
-    );
-
-    if (!input) {
-      // Leave the flag unset so a later pass can still adopt once children
-      // have been parsed.
-      return;
-    }
-
-    this.__ssrNameAdopted = true;
-    this.name = input.name;
-  }
-
+import {SsrChoiceGroupMixin} from '@src/mixins/SsrChoiceGroupMixin';
+
+/**
+ * @summary A group of checkboxes sharing one name, for a choice where any
+ * number of options can be selected.
+ *
+ * The group owns the name and the collected value, so its `modelValue` is the
+ * array of what is checked. Use `craft-radio-group` when exactly one option
+ * may be chosen.
+ *
+ * A group rendered by the server adopts the name already on its inputs, so the
+ * markup keeps posting the way it did before the component upgraded.
+ *
+ * @slot - The `craft-checkbox`es in the group.
+ * @slot label - The group's label.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages for the group as a whole.
+ */
+export default class CraftCheckboxGroup extends SsrChoiceGroupMixin(
+  LionCheckboxGroup,
+  'checkbox'
+) {
   static override get styles() {
     return [
       ...LionCheckboxGroup.styles,
@@ -68,3 +49,9 @@ export default class CraftCheckboxGroup extends LionCheckboxGroup {
 if (!customElements.get('craft-checkbox-group')) {
   customElements.define('craft-checkbox-group', CraftCheckboxGroup);
 }
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'craft-checkbox-group': CraftCheckboxGroup;
+  }
+}
diff --git a/packages/craftcms-ui/src/components/checkbox-indeterminate/CheckboxIndeterminate.mdx b/packages/craftcms-ui/src/components/checkbox-indeterminate/CheckboxIndeterminate.mdx
new file mode 100644
index 00000000000..0195a53fe92
--- /dev/null
+++ b/packages/craftcms-ui/src/components/checkbox-indeterminate/CheckboxIndeterminate.mdx
@@ -0,0 +1,28 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CheckboxIndeterminateStories from './checkbox-indeterminate.stories';
+
+<Meta of={CheckboxIndeterminateStories} name="Docs" />
+
+# Checkbox Indeterminate
+
+`<craft-checkbox-indeterminate>` is a parent checkbox that summarises the ones nested under it.
+
+<Canvas of={CheckboxIndeterminateStories.Default} sourceState="shown" />
+
+It is checked when every child is, unchecked when none are, and indeterminate when only some are. Toggling it sets every child to match — which is what makes it a "select all".
+
+## The Third State
+
+Indeterminate is a summary, not a value. The parent never posts an indeterminate value; only the children it summarises post anything at all.
+
+That is why this is a different component from a [Checkbox](?path=/docs/form-controls-choice-controls-checkbox--docs) with `indeterminate` set. The plain checkbox exposes the state so you can drive it yourself; this one derives it, so the parent cannot fall out of step with its children.
+
+## Accessibility
+
+The mixed state is exposed as `aria-checked="mixed"`, which is announced as such — so a person hears that some of the set is selected rather than being told it is simply off.
+
+Label the parent with what the set contains rather than with "Select all". "All entry types" says what is being selected; "Select all" says only what the control does, which the checkbox shape already conveys.
+
+## Properties
+
+<ArgTypes of={CheckboxIndeterminateStories} />
diff --git a/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.stories.ts b/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.stories.ts
index aaf4c71aaff..92c22aed910 100644
--- a/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.stories.ts
+++ b/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.stories.ts
@@ -1,99 +1,113 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './checkbox-indeterminate.js';
 import '../checkbox/checkbox.js';
 import '../checkbox-group/checkbox-group.js';
+import type CraftCheckboxIndeterminate from './checkbox-indeterminate.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `checkbox-indeterminate.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftCheckboxIndeterminate>(
+  'craft-checkbox-indeterminate'
+);
+
+type CheckboxIndeterminateArgs = CraftCheckboxIndeterminate & typeof args;
+
+/** A group with a select-all at its head, which is the only way to use this. */
+const group = (groupLabel: string, allLabel: string, children: unknown) => html`
+  <craft-checkbox-group>
+    <label slot="label">${groupLabel}</label>
+    <craft-checkbox-indeterminate>
+      <label slot="label">${allLabel}</label>
+      ${children}
+    </craft-checkbox-indeterminate>
+  </craft-checkbox-group>
+`;
 
 const meta = {
-  title: 'Controls/Checkbox Indeterminate',
+  title: 'Form Controls/Choice Controls/Checkbox Indeterminate',
   component: 'craft-checkbox-indeterminate',
-  args: {
-    label: 'Select All',
-  },
-  argTypes: {
-    label: {
-      control: 'text',
-      description: 'Label for the indeterminate checkbox',
-    },
-  },
-} satisfies Meta<any>;
+  args: {...args, 'label-slot': 'All'},
+  argTypes,
+  parameters: {controls: {disable: true}},
+  render: (args) =>
+    group(
+      'Notifications',
+      String(args['label-slot'] ?? 'All'),
+      html`
+        <craft-checkbox
+          ><label slot="label">Email notifications</label></craft-checkbox
+        >
+        <craft-checkbox
+          ><label slot="label">Push notifications</label></craft-checkbox
+        >
+        <craft-checkbox
+          ><label slot="label">SMS notifications</label></craft-checkbox
+        >
+      `
+    ),
+} satisfies Meta<CheckboxIndeterminateArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CheckboxIndeterminateArgs>;
 
 /**
- * The indeterminate checkbox provides a "select all" control for a group of checkboxes.
- * It shows three states: unchecked (none selected), indeterminate (some selected), and checked (all selected).
+ * A select-all for a group of checkboxes, with three states: unchecked,
+ * indeterminate when some are selected, and checked when all are.
  */
-export const Default: Story = {
-  render: () => html`
-    <craft-checkbox-group label="Notifications">
-      <craft-checkbox-indeterminate label="All">
-        <craft-checkbox>
-          <label slot="label">Email notifications</label>
-        </craft-checkbox>
-        <craft-checkbox>
-          <label slot="label">Push notifications</label>
-        </craft-checkbox>
-        <craft-checkbox>
-          <label slot="label">SMS notifications</label>
-        </craft-checkbox>
-      </craft-checkbox-indeterminate>
-    </craft-checkbox-group>
-  `,
-};
+export const Default: Story = {};
 
-/**
- * When some child checkboxes are checked, the parent shows an indeterminate state.
- */
+/** Some children checked, so the parent shows the indeterminate state. */
 export const IndeterminateState: Story = {
-  render: () => html`
-    <craft-checkbox-group label="Features">
-      <craft-checkbox-indeterminate label="All Features">
-        <craft-checkbox checked>
-          <label slot="label">Feature A (checked)</label>
-        </craft-checkbox>
-        <craft-checkbox>
-          <label slot="label">Feature B (unchecked)</label>
-        </craft-checkbox>
-        <craft-checkbox checked>
-          <label slot="label">Feature C (checked)</label>
-        </craft-checkbox>
-      </craft-checkbox-indeterminate>
-    </craft-checkbox-group>
-  `,
+  render: () =>
+    group(
+      'Features',
+      'All features',
+      html`
+        <craft-checkbox checked
+          ><label slot="label">Feature A</label></craft-checkbox
+        >
+        <craft-checkbox><label slot="label">Feature B</label></craft-checkbox>
+        <craft-checkbox checked
+          ><label slot="label">Feature C</label></craft-checkbox
+        >
+      `
+    ),
 };
 
-/**
- * When all child checkboxes are checked, the parent shows a checked state.
- */
+/** All children checked, so the parent is checked too. */
 export const AllSelected: Story = {
-  render: () => html`
-    <craft-checkbox-group label="Permissions">
-      <craft-checkbox-indeterminate label="All Permissions">
-        <craft-checkbox checked>
-          <label slot="label">Read</label>
-        </craft-checkbox>
-        <craft-checkbox checked>
-          <label slot="label">Write</label>
-        </craft-checkbox>
-        <craft-checkbox checked>
-          <label slot="label">Delete</label>
-        </craft-checkbox>
-      </craft-checkbox-indeterminate>
-    </craft-checkbox-group>
-  `,
+  render: () =>
+    group(
+      'Permissions',
+      'All permissions',
+      html`
+        <craft-checkbox checked
+          ><label slot="label">Read</label></craft-checkbox
+        >
+        <craft-checkbox checked
+          ><label slot="label">Write</label></craft-checkbox
+        >
+        <craft-checkbox checked
+          ><label slot="label">Delete</label></craft-checkbox
+        >
+      `
+    ),
 };
 
-/**
- * Checkboxes can include help text for additional context.
- */
+/** Children can carry help text of their own. */
 export const WithHelpText: Story = {
-  render: () => html`
-    <craft-checkbox-group label="Cache Options">
-      <craft-checkbox-indeterminate label="All Caches">
+  render: () =>
+    group(
+      'Cache options',
+      'All caches',
+      html`
         <craft-checkbox>
           <label slot="label">Data caches</label>
           <div slot="help-text">Clears all cached data</div>
@@ -102,42 +116,38 @@ export const WithHelpText: Story = {
           <label slot="label">Template caches</label>
           <div slot="help-text">Clears compiled templates</div>
         </craft-checkbox>
-        <craft-checkbox>
-          <label slot="label">Asset caches</label>
-          <div slot="help-text">Clears generated thumbnails</div>
-        </craft-checkbox>
-      </craft-checkbox-indeterminate>
-    </craft-checkbox-group>
-  `,
+      `
+    ),
 };
 
-/**
- * Multiple indeterminate groups can be used within the same form.
- */
+/** More than one group can sit in the same form. */
 export const MultipleGroups: Story = {
   render: () => html`
-    <div style="display: flex; flex-direction: column; gap: 2rem;">
-      <craft-checkbox-group label="Email Settings">
-        <craft-checkbox-indeterminate label="All Email Types">
-          <craft-checkbox>
-            <label slot="label">Marketing emails</label>
-          </craft-checkbox>
-          <craft-checkbox>
-            <label slot="label">Transactional emails</label>
-          </craft-checkbox>
-        </craft-checkbox-indeterminate>
-      </craft-checkbox-group>
-
-      <craft-checkbox-group label="Privacy Settings">
-        <craft-checkbox-indeterminate label="All Privacy Options">
-          <craft-checkbox>
-            <label slot="label">Analytics tracking</label>
-          </craft-checkbox>
-          <craft-checkbox>
-            <label slot="label">Personalization</label>
-          </craft-checkbox>
-        </craft-checkbox-indeterminate>
-      </craft-checkbox-group>
+    <div style="display: flex; flex-direction: column; gap: 2rem">
+      ${group(
+        'Email settings',
+        'All email types',
+        html`
+          <craft-checkbox
+            ><label slot="label">Marketing emails</label></craft-checkbox
+          >
+          <craft-checkbox
+            ><label slot="label">Transactional emails</label></craft-checkbox
+          >
+        `
+      )}
+      ${group(
+        'Privacy settings',
+        'All privacy options',
+        html`
+          <craft-checkbox
+            ><label slot="label">Analytics tracking</label></craft-checkbox
+          >
+          <craft-checkbox
+            ><label slot="label">Personalization</label></craft-checkbox
+          >
+        `
+      )}
     </div>
   `,
 };
diff --git a/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.test.ts b/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.test.ts
new file mode 100644
index 00000000000..e169b569bfa
--- /dev/null
+++ b/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.test.ts
@@ -0,0 +1,87 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './checkbox-indeterminate.js';
+import '../checkbox/checkbox.js';
+import '../checkbox-group/checkbox-group.js';
+import type CraftCheckboxIndeterminate from './checkbox-indeterminate.js';
+
+/**
+ * The component only means anything inside a group — that is what registers
+ * the children it stands for, so every story and every real usage wraps it.
+ */
+async function createGroup(count = 3): Promise<CraftCheckboxIndeterminate> {
+  const group = document.createElement('craft-checkbox-group');
+  group.innerHTML = `
+    <label slot="label">Notifications</label>
+    <craft-checkbox-indeterminate>
+      <label slot="label">All</label>
+      ${Array.from(
+        {length: count},
+        (_, index) =>
+          `<craft-checkbox><label slot="label">Option ${index + 1}</label></craft-checkbox>`
+      ).join('')}
+    </craft-checkbox-indeterminate>
+  `;
+  document.body.append(group);
+
+  const element = group.querySelector(
+    'craft-checkbox-indeterminate'
+  ) as CraftCheckboxIndeterminate;
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+/**
+ * The tri-state itself is Lion's, and its sync runs off registration and
+ * `model-value-changed` events that need a real browser to settle — the
+ * Storybook stories cover it there. What is checked here is this package's own
+ * contribution: that the element composes correctly inside a group, and that
+ * the three states it can hold are addressable.
+ */
+describe('craft-checkbox-indeterminate', () => {
+  it('stands for the checkboxes nested inside it', async () => {
+    const element = await createGroup();
+
+    expect(element.querySelectorAll('craft-checkbox')).toHaveLength(3);
+  });
+
+  it('starts unchecked and determinate', async () => {
+    const element = await createGroup();
+
+    expect(element.checked).toBe(false);
+    expect(element.indeterminate).toBe(false);
+  });
+
+  /** The middle state is the one an ordinary checkbox cannot express. */
+  it('can be put into the indeterminate state', async () => {
+    const element = await createGroup();
+
+    element.indeterminate = true;
+    await element.updateComplete;
+
+    expect(element.indeterminate).toBe(true);
+  });
+
+  it('can be checked', async () => {
+    const element = await createGroup();
+
+    element.checked = true;
+    await element.updateComplete;
+
+    expect(element.checked).toBe(true);
+  });
+
+  it('takes its own label from the label slot', async () => {
+    const element = await createGroup();
+
+    expect(
+      element.querySelector(':scope > label[slot="label"]')?.textContent
+    ).toBe('All');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.ts b/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.ts
index 7009930c2e2..4d231bf4d38 100644
--- a/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.ts
+++ b/packages/craftcms-ui/src/components/checkbox-indeterminate/checkbox-indeterminate.ts
@@ -1,6 +1,18 @@
 import {LionCheckboxIndeterminate} from '@lion/ui/checkbox-group.js';
 import {css} from 'lit';
 
+/**
+ * @summary A parent checkbox that reflects the state of the checkboxes nested
+ * under it — checked when all are, indeterminate when only some are, and
+ * unchecked when none are.
+ *
+ * Toggling it sets every child to match, which is what makes it a "select
+ * all". The indeterminate state is presentational: it is never a value the
+ * form posts, only a summary of the children that do.
+ *
+ * @slot - The child `craft-checkbox`es this one summarises.
+ * @slot label - The checkbox's label.
+ */
 export default class CraftCheckboxIndeterminate extends LionCheckboxIndeterminate {
   static override get styles() {
     return [
diff --git a/packages/craftcms-ui/src/components/checkbox/Checkbox.mdx b/packages/craftcms-ui/src/components/checkbox/Checkbox.mdx
new file mode 100644
index 00000000000..8eae6e6b394
--- /dev/null
+++ b/packages/craftcms-ui/src/components/checkbox/Checkbox.mdx
@@ -0,0 +1,36 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CheckboxStories from './checkbox.stories';
+
+<Meta of={CheckboxStories} name="Docs" />
+
+# Checkbox
+
+`<craft-checkbox>` is a single checkbox — a choice that is on or off.
+
+<Canvas of={CheckboxStories.Default} sourceState="shown" />
+
+Use one on its own for a standalone setting, or several inside a [Checkbox Group](?path=/docs/form-controls-choice-controls-checkbox-group--docs) when they share a name and post together.
+
+For a choice where exactly one of several options may be picked, use a [Radio Group](?path=/docs/form-controls-choice-controls-radio-group--docs) instead. The shape of the control tells a person how many answers are allowed, so picking the right one matters before styling it.
+
+## Indeterminate
+
+`indeterminate` renders the third state — neither checked nor unchecked — for a "select all" that reflects a partial selection.
+
+It is presentational: an indeterminate checkbox still posts as unchecked. When you want that state managed for you across a set of children, use [Checkbox Indeterminate](?path=/docs/form-controls-choice-controls-checkbox-indeterminate--docs) rather than driving this property by hand.
+
+## Server-Rendered Markup
+
+A checkbox that arrives from the server with its `<input>` already in place keeps that input's `checked`, `disabled`, and `name` when the component upgrades.
+
+Without that, upgrading would reset the control to the component's own defaults and quietly discard state the server had set — so a page rendered checked would arrive unchecked.
+
+## Accessibility
+
+Lion wires the label and any validation feedback to the input, so a labelled checkbox is announced with its state and its name.
+
+Label every checkbox. An unlabelled one is announced only as "checkbox", which tells a person the shape of the control and nothing about what ticking it does.
+
+## Properties
+
+<ArgTypes of={CheckboxStories} />
diff --git a/packages/craftcms-ui/src/components/checkbox/checkbox.stories.ts b/packages/craftcms-ui/src/components/checkbox/checkbox.stories.ts
index 7a334d2cb65..5083eaaa0f1 100644
--- a/packages/craftcms-ui/src/components/checkbox/checkbox.stories.ts
+++ b/packages/craftcms-ui/src/components/checkbox/checkbox.stories.ts
@@ -1,36 +1,67 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './checkbox.js';
+import type CraftCheckbox from './checkbox.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `checkbox.ts` surfaces it here without touching this file.
+ *
+ * Lion's own `label` and `help-text` are slots here, so they are set through
+ * the `label-slot` and `help-text-slot` args rather than as attributes.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftCheckbox>('craft-checkbox');
+
+type CheckboxArgs = CraftCheckbox & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Checkbox',
+  title: 'Form Controls/Choice Controls/Checkbox',
   component: 'craft-checkbox',
-  args: {},
-  render: function () {
-    return html`<craft-checkbox
-      label="Craft Input"
-      help-text="This is some instructions text"
-    ></craft-checkbox>`;
+  args: {
+    ...args,
+    'label-slot': 'Enable indexing',
+    'help-text-slot': 'Search engines will be allowed to index this page.',
   },
-} satisfies Meta<any>;
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<CheckboxArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CheckboxArgs>;
+
+/** A label, help text, and the box itself. */
+export const Default: Story = {};
+
+export const Checked: Story = {
+  args: {checked: true},
+};
+
+/** `indeterminate` is the third state, for a box standing in for a group. */
+export const Indeterminate: Story = {
+  args: {indeterminate: true},
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+export const Disabled: Story = {
+  args: {disabled: true},
 };
 
-export const NoLabel: Story = {
-  render: function () {
-    return html`<craft-checkbox
-      label="Craft Input"
-      help-text="This is some instructions text"
-      label-sr-only
-    ></craft-checkbox>`;
+/** `label-sr-only` keeps the name for assistive technology and hides it. */
+export const NoVisibleLabel: Story = {
+  args: {'label-sr-only': true, 'help-text-slot': ''},
+  parameters: {
+    a11y: {
+      config: {
+        // The label is still there and still wired up with `aria-labelledby`;
+        // hiding it visually is the point of the story, and that is exactly
+        // what this rule reports.
+        rules: [{id: 'label-title-only', enabled: false}],
+      },
+    },
   },
 };
diff --git a/packages/craftcms-ui/src/components/checkbox/checkbox.ts b/packages/craftcms-ui/src/components/checkbox/checkbox.ts
index cb3d361fd95..ba02bce61ca 100644
--- a/packages/craftcms-ui/src/components/checkbox/checkbox.ts
+++ b/packages/craftcms-ui/src/components/checkbox/checkbox.ts
@@ -3,6 +3,21 @@ import {css, type PropertyValues} from 'lit';
 import {property} from 'lit/decorators.js';
 import {SsrChoiceInputMixin} from '../../mixins/SsrChoiceInputMixin.js';
 
+/**
+ * @summary A single checkbox, for a choice that stands on its own or one of
+ * several in a `craft-checkbox-group`.
+ *
+ * Built on Lion's checkbox, so it carries a label, validation, and a
+ * `modelValue` alongside the native input. It also understands
+ * server-rendered markup: a checkbox that arrives from the server with its
+ * input already in place keeps that input's `checked`, `disabled`, and `name`
+ * rather than having them reset on upgrade.
+ *
+ * @slot label - The checkbox's label, as an alternative to the `label`
+ *   attribute.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages.
+ */
 export default class CraftCheckbox extends SsrChoiceInputMixin(LionCheckbox) {
   private __inputPatched = false;
 
diff --git a/packages/craftcms-ui/src/components/chip/Chip.mdx b/packages/craftcms-ui/src/components/chip/Chip.mdx
new file mode 100644
index 00000000000..c2f3df580c9
--- /dev/null
+++ b/packages/craftcms-ui/src/components/chip/Chip.mdx
@@ -0,0 +1,108 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ChipStories from './chip.stories';
+
+<Meta of={ChipStories} name="Docs" />
+
+# Chip
+
+`<craft-chip>` is a container that represents a single entity. That could be an entry, an asset, a user, a category, etc.
+It pairs a label with an optional leading prefix and an optional trailing suffix.
+
+<Canvas of={ChipStories.Default} sourceState="shown" />
+
+Use a chip to represent an entity that can be acted on.
+To represent a piece of state instead — a status, a count, or a label — use [Badge](?path=/docs/components-badge--docs).
+
+## Composition
+
+A chip has three regions: an optional prefix, the label, and an optional suffix.
+The prefix and suffix are only rendered when there is content for them, so a chip with nothing but a label renders neither.
+
+<Canvas of={ChipStories.PrefixAndSuffix} sourceState="shown" />
+
+The label is the chip's default slot.
+The suffix is rendered as soon as the `suffix` slot is filled, and is where per-chip actions belong:
+
+<Canvas of={ChipStories.SuffixOnly} sourceState="shown" />
+
+Chips are frequently populated after they have been added to the page, such as when an action menu is attached once the entity's available actions are known.
+A chip watches its own light DOM for changes, so content added to a slot after the initial render is picked up automatically.
+
+<Canvas of={ChipStories.DeferredActions} sourceState="shown" />
+
+## The Prefix
+
+There are two ways to fill the prefix, and they are mutually exclusive.
+
+Fill the `prefix` slot to supply your own leading content.
+This replaces the entire prefix region, and the built-in slots described below are ignored:
+
+<Canvas of={ChipStories.CustomPrefix} sourceState="shown" />
+
+Otherwise, use one of the built-in prefix slots:
+
+- `thumbnail` – Requires `show-thumb`. Without it the slot is not rendered, and its content does not appear.
+- `icon` – Rendered when the `icon` attribute is set.
+- `status` – Rendered whenever the slot is filled, or when `show-status` is set.
+
+<Canvas of={ChipStories.Thumbnail} sourceState="shown" />
+
+The `icon` attribute is a shorthand for the `icon` slot, and does not require a slot of its own:
+
+<Canvas of={ChipStories.Icon} sourceState="shown" />
+
+## Variant and Appearance
+
+`variant` sets the semantic color group the chip draws its tokens from, and `appearance` determines how those tokens are applied.
+The two are independent, and they behave the same way here as on every other component that accepts them.
+See [Variants & Appearances](?path=/docs/tokens-variants-appearances--docs) for the underlying token mapping.
+
+<Canvas of={ChipStories.Appearances} />
+
+`plain` removes the chip's border, background, padding, and shadow, leaving the label and prefix inline with the surrounding content.
+Use it when a chip appears within running text or a dense table, rather than as a standalone object.
+
+A chip stamps `data-color="white"` on itself when it connects, so it reads as a raised surface by default.
+Set `data-color` on the chip to override that. Because the attribute lands on the chip itself, an ancestor's `data-color` does not reach it — colour each chip directly:
+
+<Canvas of={ChipStories.Colors} />
+
+## Sizing
+
+`size` sets how much room the chip gives its contents — the padding around the label, and the thumbnail in the prefix:
+
+<Canvas of={ChipStories.Sizes} sourceState="shown" />
+
+The step shows most clearly with a prefix and a suffix in place, since the thumbnail grows with it:
+
+<Canvas of={ChipStories.SizesWithContent} sourceState="shown" />
+
+## Styling
+
+The chip exposes three CSS parts — `chip`, `prefix`, and `suffix` — and a set of `--c-chip-*` custom properties for its height, radius, padding, shadow, and border.
+Both are listed in full under [Properties](#properties).
+
+Prefer the custom properties over styling the parts directly.
+A chip is sized by its padding and content, so scaling one is usually a single declaration:
+
+```css
+craft-chip {
+  --c-chip-height: var(--c-size-control-md);
+}
+```
+
+## Accessibility
+
+A chip is a container, not a control.
+It has no implicit role and does not receive focus.
+The content you place in it carries its own semantics, which makes two things your responsibility:
+
+- **Interactive content must provide its own accessible name.** An action button in the `suffix` slot requires a label, and an icon-only button requires one on the icon. The chip's label does not name it.
+- **Decorative prefixes must remain decorative.** A thumbnail that only repeats the label takes `alt=""`. A status indicator that conveys meaning the label does not should be given a `label` of its own.
+
+Setting `selectable` renders a checkbox before the prefix, for chips within a multi-select list.
+Name it with `select-label` so a list of chips does not read as a run of identically labelled checkboxes; it falls back to a generic "Select".
+
+## Properties
+
+<ArgTypes of={ChipStories} />
diff --git a/packages/craftcms-ui/src/components/chip/chip.stories.ts b/packages/craftcms-ui/src/components/chip/chip.stories.ts
index 3a93695b529..1ed0692329c 100644
--- a/packages/craftcms-ui/src/components/chip/chip.stories.ts
+++ b/packages/craftcms-ui/src/components/chip/chip.stories.ts
@@ -1,92 +1,342 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {html, nothing} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {Color} from '../../constants/colors';
 
 import './chip.js';
 import '../status/status.js';
 import '../button/button.js';
+import '../icon/icon.js';
+import '../action-menu/action-menu.js';
+import '../avatar/avatar.js';
+import '../badge/badge.js';
+import type CraftChip from './chip.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `chip.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftChip>('craft-chip');
+
+const ACTION_BUTTON = `<craft-button icon size="small" variant="plain">
+  <craft-icon name="ellipsis" label="Actions"></craft-icon>
+</craft-button>`;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Chip',
   component: 'craft-chip',
-  argTypes: {},
-  render: (args) => html` <craft-chip> This is a chip </craft-chip> `,
+  args: {...args, 'default-slot': 'Homepage'},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
 } satisfies Meta<any>;
 
 export default meta;
 type Story = StoryObj<any>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** Every `size` value, including unset, for the size stories below. */
+const chipSizes = [
+  {size: 'small', label: 'Small'},
+  {size: 'medium', label: 'Medium'},
+  {size: 'large', label: 'Large'},
+] as const;
 
+/**
+ * A chip with nothing but a label renders neither the prefix nor the suffix
+ * region.
+ */
+export const Default: Story = {};
+
+/**
+ * The two regions are independent. Fill `suffix` for a per-chip action, and
+ * `prefix` to supply your own leading content.
+ */
 export const PrefixAndSuffix: Story = {
-  args: {},
-  render: (args) => html`
-    <craft-chip>
-      <craft-status slot="prefix" status="live"></craft-status>
-      This is a chip
-      <craft-button icon size="small" variant="plain" slot="suffix">
-        <craft-icon name="ellipsis" label="Actions"></craft-icon>
-      </craft-button>
-    </craft-chip>
-  `,
+  args: {
+    'status-slot': '<craft-status status="live"></craft-status>',
+    'suffix-slot': ACTION_BUTTON,
+  },
+};
+
+export const CustomPrefix: Story = {
+  args: {
+    'prefix-slot': `<div style="padding: var(--_chip-spacing);">
+  <craft-button size="small" inherit variant="primary" type="button">Btn</craft-button>
+</div>`,
+  },
+};
+
+export const SuffixOnly: Story = {
+  args: {'suffix-slot': ACTION_BUTTON},
+};
+
+/**
+ * Attaching an action menu after the chip has rendered, then adding items to
+ * it. "Attach action menu" appends a `craft-action-menu` to the chip's
+ * `suffix` slot, and the chip renders the suffix region without being told to
+ * re-render. "Add action" appends an item to the menu that is already there.
+ */
+export const DeferredActions: Story = {
+  parameters: {
+    controls: {disable: true},
+    docs: {
+      // The feature here is imperative, so the rendered markup does not show
+      // it. Keep this in sync with the handlers below.
+      source: {
+        code: `const chip = document.querySelector('craft-chip');
+
+// Attach the menu once the entity's available actions are known.
+const menu = document.createElement('craft-action-menu');
+menu.slot = 'suffix';
+menu.label = 'Actions';
+menu.icon = 'ellipsis';
+menu.actions = [
+  {label: 'View', icon: 'eye', onClick: () => {}},
+  {label: 'Edit', icon: 'pen', onClick: () => {}},
+  {label: 'Delete', icon: 'trash', variant: 'danger', onClick: () => {}},
+];
+
+// The chip observes its own light DOM, so the suffix region appears on its own.
+chip.append(menu);
+
+// \`actions\` is a reactive property. Add an item by reassigning the array —
+// pushing onto it in place does not trigger a re-render.
+menu.actions = [
+  ...menu.actions,
+  {label: 'Custom action 1', icon: 'lightbulb', onClick: () => {}},
+];`,
+        language: 'js',
+      },
+    },
+  },
+  render: () => {
+    let added = 0;
+
+    const menuFor = (trigger: HTMLElement) =>
+      trigger.parentElement?.querySelector('craft-action-menu') ?? null;
+
+    const attachMenu = (event: Event) => {
+      const trigger = event.currentTarget as HTMLElement;
+      const chip = trigger.parentElement?.querySelector('craft-chip');
+      if (!chip || chip.querySelector('[slot="suffix"]')) {
+        return;
+      }
+
+      const menu = document.createElement('craft-action-menu');
+      menu.slot = 'suffix';
+      menu.label = 'Actions';
+      menu.icon = 'ellipsis';
+      menu.actions = [
+        {label: 'View', icon: 'eye', onClick: () => {}},
+        {label: 'Edit', icon: 'pen', onClick: () => {}},
+        {label: 'Delete', icon: 'trash', variant: 'danger', onClick: () => {}},
+      ];
+
+      chip.append(menu);
+    };
+
+    const addAction = (event: Event) => {
+      const menu = menuFor(event.currentTarget as HTMLElement);
+      if (!menu) {
+        return;
+      }
+
+      const current = Array.isArray(menu.actions) ? menu.actions : [];
+      added++;
+
+      // Reassign rather than push: `actions` is a reactive property, and Lit
+      // compares by reference.
+      menu.actions = [
+        ...current,
+        {
+          label: `Custom action ${added}`,
+          icon: 'lightbulb',
+          onClick: () => {},
+        },
+      ];
+    };
+
+    return html`
+      <div style="display: flex; gap: 1rem; align-items: center">
+        <craft-chip>Homepage</craft-chip>
+        <craft-button size="small" @click="${attachMenu}">
+          Attach action menu
+        </craft-button>
+        <craft-button size="small" @click="${addAction}">
+          Add action
+        </craft-button>
+      </div>
+    `;
+  },
 };
 
+/**
+ * `show-thumb` is required. Without it, the `thumbnail` slot is not rendered,
+ * and its content does not appear.
+ */
 export const Thumbnail: Story = {
-  args: {},
-  render: (args) => html`
-    <craft-chip>
-      <img slot="thumbnail" src="https://picsum.photos/300/300" alt="" />
-      This is a chip
-      <craft-button icon size="small" variant="plain" slot="suffix">
-        <craft-icon name="ellipsis" label="Actions"></craft-icon>
-      </craft-button>
-    </craft-chip>
+  args: {
+    'show-thumb': true,
+    'thumbnail-slot': '<img src="https://picsum.photos/120/120" alt="" />',
+    'suffix-slot': ACTION_BUTTON,
+  },
+};
+
+/**
+ * The `icon` attribute is a shorthand for the `icon` slot, and setting it is
+ * what causes that slot to be rendered.
+ */
+export const Icon: Story = {
+  args: {icon: 'star'},
+};
+
+/**
+ * The four `size` values on a bare chip. Each step is taller than the last:
+ * `small` adds block padding, and `medium` applies a minimum height. `large`
+ * has no styles of its own, so it renders the same as an unset `size`.
+ */
+export const Sizes: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div
+      style="display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: start"
+    >
+      ${chipSizes.map(
+        ({size, label}) =>
+          html`<craft-chip size="${size || nothing}">${label}</craft-chip>`
+      )}
+    </div>
   `,
 };
 
-export const PrefixOnly: Story = {
-  args: {},
-  render: (args) => html`
-    <craft-chip>
-      <craft-status slot="prefix" status="live"></craft-status>
-      This is a chip
-    </craft-chip>
+/**
+ * The same sizes with a thumbnail and a suffix. `medium` sets a minimum height
+ * on the chip's regions, so the difference is clearest once there is content
+ * that does not already fill them.
+ */
+export const SizesWithContent: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div
+      style="display: flex; flex-direction: column; gap: 0.75rem; align-items: start"
+    >
+      ${chipSizes.map(
+        ({size, label}) => html`
+          <craft-chip size="${size || nothing}" show-thumb>
+            <img slot="thumbnail" src="https://picsum.photos/120/120" alt="" />
+            ${label}
+            <craft-button icon size="small" variant="plain" slot="suffix">
+              <craft-icon name="ellipsis" label="Actions"></craft-icon>
+            </craft-button>
+          </craft-chip>
+        `
+      )}
+    </div>
   `,
 };
 
-export const SuffixOnly: Story = {
-  args: {},
-  render: (args) => html`
-    <craft-chip>
-      <craft-button icon size="small" variant="plain" slot="suffix">
-        <craft-icon name="ellipsis" label="Actions"></craft-icon>
-      </craft-button>
-      This is a chip
-    </craft-chip>
+/**
+ * `variant` sets the color group and `appearance` determines how those tokens
+ * are applied. See [Variants & Appearances](?path=/docs/tokens-variants-appearances--docs)
+ * for the underlying token mapping.
+ */
+export const Appearances: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div
+      style="display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: center"
+    >
+      ${['solid', 'fill', 'outline-fill', 'outline', 'plain'].map(
+        (appearance) =>
+          html`<craft-chip variant="info" appearance="${appearance}">
+            ${appearance}
+          </craft-chip>`
+      )}
+    </div>
   `,
 };
 
+/**
+ * A chip inherits the palette of any `data-color` ancestor, so chips can be
+ * tinted per row without overriding tokens.
+ */
 export const Colors: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div
+      style="display: grid; grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)); gap: 1rem"
+    >
+      ${Object.entries(Color).map(
+        ([name, value]) =>
+          html`<craft-chip data-color="${value}">
+            ${name}
+            <craft-button size="small" slot="suffix" inherit variant="plain"
+              >Button</craft-button
+            >
+          </craft-chip>`
+      )}
+    </div>
+  `,
+};
+
+/**
+ * Every slot at once. The first chip fills the built-in prefix slots —
+ * `thumbnail`, `icon`, and `status` — each of which needs its own attribute
+ * before it renders. The second fills `prefix` instead, which replaces that
+ * whole region, so the built-in slots are ignored. Both fill the default slot
+ * and `suffix`.
+ */
+export const KitchenSink: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
-    <div class="stage">
-      <div
-        style="display: grid; grid-template-columns: repeat(auto-fill, minmax(120px, 1fr)); gap: 1rem"
+    <div style="display: flex; flex-wrap: wrap; gap: 1rem; align-items: center">
+      <craft-chip
+        selectable
+        select-label="Select Homepage"
+        show-thumb
+        show-status
+        icon="file"
       >
-        ${Object.entries(Color).map(
-          ([name, value]) =>
-            html`<craft-chip data-color="${value}">
-              ${name}
-              <craft-button size="small" slot="suffix" inherit variant="plain"
-                >Button</craft-button
-              >
-            </craft-chip>`
-        )}
-      </div>
+        <img slot="thumbnail" src="https://picsum.photos/120/120" alt="" />
+        <craft-icon slot="icon" name="lightbulb"></craft-icon>
+        <craft-status slot="status" status="live"></craft-status>
+        Built-in prefix slots
+        <craft-action-menu slot="suffix">
+          <craft-button
+            slot="invoker"
+            label="Actions"
+            size="small"
+            variant="plain"
+          >
+            <craft-icon name="ellipsis" label="Actions"></craft-icon>
+          </craft-button>
+          <craft-action-item>Action Item</craft-action-item>
+        </craft-action-menu>
+      </craft-chip>
+
+      <craft-chip>
+        <craft-badge
+          fill="info"
+          slot="prefix"
+          style="margin-inline: var(--_chip-spacing)"
+          >Badge</craft-badge
+        >
+        Custom prefix
+        <craft-action-menu slot="suffix">
+          <craft-button
+            slot="invoker"
+            label="Actions"
+            size="small"
+            variant="plain"
+          >
+            <craft-icon name="ellipsis" label="Actions"></craft-icon>
+          </craft-button>
+          <craft-action-item>Action Item</craft-action-item>
+        </craft-action-menu>
+      </craft-chip>
     </div>
   `,
 };
diff --git a/packages/craftcms-ui/src/components/chip/chip.styles.ts b/packages/craftcms-ui/src/components/chip/chip.styles.ts
index 6e25cc3733b..6eaefc741b3 100644
--- a/packages/craftcms-ui/src/components/chip/chip.styles.ts
+++ b/packages/craftcms-ui/src/components/chip/chip.styles.ts
@@ -10,26 +10,18 @@ export default css`
   }
 
   .cp-chip {
-    --_min-height: var(--c-chip-height, none);
-    --_thumb-size: calc(24rem / 16);
-    --_radius: var(--c-chip-radius, var(--c-radius-md));
-    --_fill: var(--c-color-fill-quiet, var(--c-surface-raised));
+    --_chip-spacing: 0.25em;
+    --_thumb-size: calc(30rem / 16);
+    --_radius: var(--c-radius-md);
     padding: 0;
     display: inline-flex;
-    min-width: auto;
     border-radius: var(--_radius);
     align-items: center;
     box-shadow: var(--c-chip-shadow, var(--c-shadow-sm));
+    background-color: var(--c-chip-fill, var(--c-surface-raised));
 
-    /* colorable styles */
-    color: var(--c-color-on-quiet, var(--c-color-neutral-on-quiet));
     border-width: var(--c-chip-border-width, 1px);
     border-style: var(--c-chip-border-style, solid);
-    border-color: var(
-      --c-color-border-quiet,
-      var(--c-color-neutral-border-quiet)
-    );
-    background-color: var(--c-color-fill-quiet, var(--c-surface-raised));
     overflow: clip;
   }
 
@@ -39,25 +31,79 @@ export default css`
     display: flex;
   }
 
-  .cp-chip[appearance='plain'],
+  /*
+   * Appearance tiers, mirroring craft-callout so the two read at the same
+   * intensity for a given variant. The variant remaps the generic
+   * --c-color-* tokens; each tier below picks which loudness of them to use.
+   */
+  :host([appearance~='solid']) .cp-chip {
+    background-color: var(--c-color-fill-loud);
+    border-color: var(--c-color-border-loud);
+    color: var(--c-color-on-loud);
+  }
+
+  :host([appearance~='fill']) .cp-chip {
+    background-color: var(--c-color-fill-normal);
+    border-color: transparent;
+    color: var(--c-color-on-normal);
+  }
+
+  :host([appearance~='outline-fill']) .cp-chip {
+    background-color: var(--c-color-fill-normal);
+    border-color: var(--c-color-border-normal);
+    color: var(--c-color-on-normal);
+  }
+
+  :host([appearance~='outline']) .cp-chip {
+    background-color: transparent;
+    border-color: var(--c-color-border-quiet);
+    color: var(--c-color-on-quiet);
+  }
+
+  :host([appearance~='plain']) .cp-chip {
+    background-color: transparent;
+    border-color: transparent;
+    color: var(--c-color-on-quiet);
+  }
+
+  /*
+   * Without an author-chosen colour the chip stamps data-color="white", whose
+   * fill, border, and text are all static colours — they stay light in dark
+   * mode. A default chip takes the theme-aware surface instead, paired with
+   * the same text and border tokens craft-pane uses on that surface, so the
+   * three move together. Scoped to the two filled tiers so outline and plain
+   * stay transparent, and to the stamped colour so a variant still fills with
+   * its own.
+   */
+  :host([data-color='white'][appearance~='fill']) .cp-chip,
+  :host([data-color='white'][appearance~='outline-fill']) .cp-chip {
+    background-color: var(--c-chip-fill, var(--c-surface-raised));
+    border-color: var(
+      --c-chip-border-color,
+      var(--c-color-neutral-border-quiet)
+    );
+    color: var(--c-chip-text, var(--c-text-default));
+  }
+
+  /* Layout side of plain: no chrome, so no padding or shadow either. */
   .cp-chip--plain {
-    --_min-height: none;
     padding-block: 0;
     padding-inline: 0;
-    border-color: transparent;
-    background-color: transparent;
     box-shadow: none;
   }
 
-  .cp-chip[size='small'],
   .cp-chip--small {
-    padding-block: calc(var(--c-spacing-xs) / 2);
+    --_chip-spacing: 0.25em;
   }
 
-  .cp-chip[size='medium'],
   .cp-chip--medium {
-    padding-block: 0;
-    min-height: var(--c-size-control-md);
+    --_chip-spacing: 0.5em;
+    --_thumb-size: calc(34rem / 16);
+  }
+
+  .cp-chip--large {
+    --_chip-spacing: 1em;
+    --_thumb-size: calc(40rem / 16);
   }
 
   .cp-chip__prefix,
@@ -65,10 +111,10 @@ export default css`
   .cp-chip__suffix {
     display: inline-flex;
     flex-direction: column;
-    min-height: var(--_min-height);
   }
 
   .cp-chip__body {
+    padding: calc(var(--_chip-spacing) / 2) var(--_chip-spacing);
     display: flex;
     gap: var(--c-spacing-sm);
     align-items: center;
@@ -80,9 +126,9 @@ export default css`
     text-overflow: ellipsis;
   }
 
+  /* Prefix gets no padding on its own because each prefix item has different spacing needs */
   .cp-chip__prefix {
     position: relative;
-    padding-inline-end: var(--c-spacing-sm);
     display: flex;
     align-items: center;
     flex-direction: row;
@@ -90,18 +136,22 @@ export default css`
   }
 
   .cp-chip__suffix {
+    padding: calc(var(--_chip-spacing) / 2);
+    padding-inline-start: var(--_chip-spacing);
     display: flex;
-    padding-inline-start: var(--c-spacing-md);
   }
 
-  .cp-chip__status {
+  .cp-chip__status,
+  .cp-chip__icon {
     display: inline-flex;
-    padding-inline: var(--c-spacing-xs);
+    padding-inline: var(--_chip-spacing);
   }
 
   .cp-chip__thumbnail {
+    display: flex;
     position: relative;
-    padding: var(--c-spacing-sm);
-    /*border-radius: calc(var(--_radius) - var(--c-spacing-xs));*/
+    width: var(--_thumb-size);
+    aspect-ratio: 1;
+    padding-inline-end: var(--_chip-spacing);
   }
 `;
diff --git a/packages/craftcms-ui/src/components/chip/chip.ts b/packages/craftcms-ui/src/components/chip/chip.ts
index 8d645913034..9e69fd32bb2 100644
--- a/packages/craftcms-ui/src/components/chip/chip.ts
+++ b/packages/craftcms-ui/src/components/chip/chip.ts
@@ -1,4 +1,4 @@
-import {property, state} from 'lit/decorators.js';
+import {property} from 'lit/decorators.js';
 import type {CSSResultGroup, PropertyValues} from 'lit';
 import {html, LitElement, nothing} from 'lit';
 import styles from './chip.styles.js';
@@ -7,93 +7,141 @@ import {Appearance, type AppearanceValue} from '@src/constants/appearances';
 import {Variant, type VariantValue} from '@src/constants/variants';
 import type {SizeValue} from '@src/constants/size';
 import {ThumbnailLoader} from '@src/utilities/thumbnail-loader';
+import {t} from '@src/utilities/translate';
+import variantsStyles from '@src/styles/variants.styles.js';
+import {
+  hasSlotted,
+  LightDomController,
+} from '@src/controllers/LightDomController';
 
 /**
- * @summary A compact, inline element that pairs a label with an optional
- * prefix (icon, status indicator, thumbnail, …) and suffix (e.g. an action
- * button). Used for element chips, status chips, and similar UI.
+ * @summary A container that pairs a label with an optional
+ * leading prefix — a thumbnail, an icon, or a status dot — and a trailing
+ * suffix, usually an action button. Chips represent a single entity in a
+ * list: an entry, an asset, a user, a category, etc.
  *
- * The prefix is only rendered when the `prefix` or `icon` slot is filled or the
- * `icon` attribute is set; the suffix is only rendered when the `suffix` slot is
- * filled.
+ * The prefix and suffix regions are only rendered when there is content for
+ * them, so a chip with nothing but a label renders neither. The suffix is
+ * rendered when the `suffix` slot is filled. The prefix is rendered when the
+ * `prefix`, `icon`, `thumbnail`, or `status` slot is filled, or when the
+ * `icon` attribute or `show-status` is set.
  *
- * @slot - The chip's body/label content.
- * @slot prefix - Content shown before the body, e.g. a status indicator or
- *   thumbnail. Takes precedence over the `icon` slot/attribute.
- * @slot icon - Custom icon content shown in the prefix, as an alternative to the
- *   `icon` attribute.
- * @slot suffix - Content shown after the body, e.g. an action button.
+ * Filling the `prefix` slot replaces the entire prefix region. Use it to
+ * supply your own leading content; the built-in `thumbnail`, `icon`, and
+ * `status` slots are ignored when it is present.
+ *
+ * On connect the chip stamps `data-color="white"` on itself so it reads as a
+ * raised surface by default, filled with `--c-surface-raised` so it follows
+ * the theme. Set `data-color` yourself to override it. Because the attribute
+ * lands on the chip, an ancestor's `data-color` no longer reaches it — colour
+ * the chip directly instead.
+ *
+ * @slot - The chip's label.
+ * @slot prefix - Leading content. Replaces the built-in prefix region, so the
+ *   `thumbnail`, `icon`, and `status` slots are ignored when this is filled.
+ * @slot thumbnail - A thumbnail image for the prefix. Requires `show-thumb`.
+ *   Without it, the slot is not rendered and its content does not appear.
+ * @slot icon - Icon content for the prefix, as an alternative to the `icon`
+ *   attribute. Only rendered when `icon` is set.
+ * @slot status - A status indicator for the prefix. Rendered whenever this
+ *   slot is filled, or when `show-status` is set.
+ * @slot suffix - Trailing content, shown after the label. Typically an action
+ *   button or menu.
  *
  * @csspart chip - The outer chip wrapper.
  * @csspart prefix - The prefix container.
  * @csspart suffix - The suffix container.
  *
- * @cssproperty --c-chip-height - Minimum height of the chip. Defaults to `--c-size-control-sm`.
+ * @cssproperty --c-chip-height - Minimum height of the chip's regions. Unset
+ *   by default, so the chip is sized by its padding and content.
  * @cssproperty --c-chip-radius - Corner radius. Defaults to `--c-radius-md`.
  * @cssproperty --c-chip-spacing-inline - Inline (horizontal) padding. Defaults to `0`.
  * @cssproperty --c-chip-spacing-block - Block (vertical) padding. Defaults to `--c-spacing-sm`.
+ * @cssproperty --c-chip-fill - Background colour. Defaults to
+ *   `--c-surface-raised`. A `variant` fills with its own colour instead.
+ * @cssproperty --c-chip-text - Label colour. Defaults to `--c-text-default`.
+ * @cssproperty --c-chip-border-color - Border colour. Defaults to
+ *   `--c-color-neutral-border-quiet`.
  * @cssproperty --c-chip-shadow - Box shadow. Defaults to `--c-shadow-sm`.
  * @cssproperty --c-chip-border-width - Border width. Defaults to `1px`.
  * @cssproperty --c-chip-border-style - Border style. Defaults to `solid`.
  */
 export default class CraftChip extends LitElement {
-  static override styles: CSSResultGroup = [styles];
+  static override styles: CSSResultGroup = [variantsStyles, styles];
 
-  /** Size of the chip. */
-  @property() size: SizeValue | '' = '';
+  /**
+   * How much room the chip gives its contents. Each step sets the padding
+   * around the label and the size of the thumbnail in the prefix — `small`
+   * is tight enough for a chip in a table cell, `large` suits one standing on
+   * its own.
+   */
+  @property() size: SizeValue = 'small';
 
-  /** Variant of the chip. `plain` will render with no border or padding */
-  @property({reflect: true}) variant: VariantValue = Variant.Neutral;
+  /**
+   * The semantic color group the chip draws its tokens from. It is combined
+   * with `appearance`, which determines how those tokens are applied.
+   */
+  @property({reflect: true}) variant: VariantValue | null = null;
 
-  /** Appearance of the chip. Defaults to `outline-fill`. */
+  /**
+   * How prominently the variant color is applied. `plain` removes the chip's
+   * border, background, padding, and shadow, leaving the label and prefix
+   * inline with the surrounding content.
+   */
   @property({reflect: true}) appearance: AppearanceValue =
     Appearance.OutlineFill;
 
-  /** Shortcut for adding an icon as the prefix */
+  /**
+   * The name of an icon to render in the prefix. This is a shorthand for
+   * filling the `icon` slot, and setting it is what causes that slot to be
+   * rendered.
+   */
   @property() icon: string | null = null;
 
-  @property({attribute: 'show-indicators', type: Boolean})
-  showIndicators: boolean = false;
+  /** Renders the `status` slot within the prefix. */
   @property({attribute: 'show-status', type: Boolean})
   showStatus: boolean = false;
+
+  /** Renders the `thumbnail` slot within the prefix. */
   @property({attribute: 'show-thumb', type: Boolean}) showThumb: boolean =
     false;
+
+  /**
+   * Renders a checkbox before the prefix, for chips within a multi-select
+   * list. The checkbox is named by `select-label`, falling back to a generic
+   * "Select".
+   */
   @property({type: Boolean}) selectable: boolean = false;
 
+  /**
+   * Accessible name for the `selectable` checkbox. Set it to name the entity
+   * the chip stands for, so a list of chips does not read as a run of
+   * identically labelled checkboxes.
+   */
+  @property({attribute: 'select-label'}) selectLabel: string | null = null;
+
   #thumbLoader = new ThumbnailLoader();
 
   /**
-   * Bumped whenever the light DOM changes, so the slot checks in `render()`
-   * run again.
-   *
-   * Those checks are plain `querySelector()` calls rather than `slotchange`
-   * listeners: a `<slot>` that isn't rendered can't report a change, so the
-   * first thing slotted into an empty prefix or suffix would never appear.
-   * Chips are commonly filled in after their first render — `addActionsToChip()`
-   * injects an action menu into `[slot="suffix"]` long after the chip mounts.
+   * Re-renders the chip when its light DOM changes, so the slot checks in
+   * `render()` run again. A `<slot>` that isn't rendered can't report a change
+   * of its own, and chips are commonly filled in after their first render —
+   * `addActionsToChip()` injects an action menu into `[slot="suffix"]` long
+   * after the chip mounts.
    */
-  @state() private lightDom = 0;
-
-  #observer = new MutationObserver(() => this.lightDom++);
+  #lightDom = new LightDomController(this);
 
   override connectedCallback(): void {
     super.connectedCallback();
-    // Attributes included: content moves between slots by having its `slot`
-    // attribute set, not only by being added or removed.
-    this.#observer.observe(this, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: ['slot'],
-    });
-  }
 
-  override disconnectedCallback(): void {
-    this.#observer.disconnect();
-    super.disconnectedCallback();
+    if (!this.getAttribute('data-color')) {
+      this.setAttribute('data-color', 'white');
+    }
   }
 
-  renderPrefix() {
+  protected renderPrefix() {
+    const showStatus = this.showStatus || hasSlotted(this, 'status');
+
     return html`<div class="cp-chip__prefix" part="prefix">
       <slot name="prefix">
         ${this.showThumb
@@ -104,7 +152,7 @@ export default class CraftChip extends LitElement {
               ><craft-icon name="${this.icon}"></craft-icon
             ></slot>`
           : nothing}
-        ${this.showStatus
+        ${showStatus
           ? html`<slot class="cp-chip__status" name="status"></slot>`
           : nothing}
       </slot>
@@ -117,17 +165,11 @@ export default class CraftChip extends LitElement {
   }
 
   override render() {
-    // Read so Lit re-renders when the light DOM changes; see `lightDom`.
-    void this.lightDom;
-
-    // query the element Light DOM children for slotted elements
     const renderPrefix =
-      !!this.querySelector('[slot="prefix"]') ||
-      !!this.querySelector('[slot="icon"]') ||
-      !!this.querySelector('[slot="thumbnail"]') ||
-      !!this.querySelector('[slot="indicator"]') ||
+      hasSlotted(this, 'prefix', 'icon', 'status', 'thumbnail') ||
+      this.showStatus ||
       this.icon;
-    const renderSuffix = !!this.querySelector('[slot="suffix"]');
+    const renderSuffix = hasSlotted(this, 'suffix');
 
     return html`
       <div
@@ -140,11 +182,15 @@ export default class CraftChip extends LitElement {
           'cp-chip--plain': this.appearance === Appearance.Plain,
           'cp-chip--selectable': this.selectable,
           'cp-chip--show-thumb': this.showThumb,
-          'cp-chip--show-indicators': this.showIndicators,
           'cp-chip--show-status': this.showStatus,
         })}"
       >
-        ${this.selectable ? html` <input type="checkbox" />` : nothing}
+        ${this.selectable
+          ? html` <input
+              type="checkbox"
+              aria-label="${this.selectLabel ?? t('Select')}"
+            />`
+          : nothing}
         ${renderPrefix ? this.renderPrefix() : nothing}
         <slot class="cp-chip__body"></slot>
         ${renderSuffix
diff --git a/packages/craftcms-ui/src/components/combobox/Combobox.mdx b/packages/craftcms-ui/src/components/combobox/Combobox.mdx
new file mode 100644
index 00000000000..a3f17b7c02f
--- /dev/null
+++ b/packages/craftcms-ui/src/components/combobox/Combobox.mdx
@@ -0,0 +1,67 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ComboboxStories from './combobox.stories';
+
+<Meta of={ComboboxStories} name="Docs" />
+
+# Combobox
+
+`<craft-combobox>` is a single-select dropdown with type-ahead filtering.
+
+<Canvas of={ComboboxStories.Default} sourceState="shown" />
+
+Reach for it when a list is long enough that scanning it is work — sections, fields, users, anything running to dozens of entries. For a short list, [Select](?path=/docs/form-controls-select-controls-select--docs) is less machinery and gets the native picker on touch devices.
+
+## Options as Data
+
+Unlike Lion's combobox, which expects every option authored as a slotted child, this takes an `options` array and renders only the matching subset as [Option](?path=/docs/form-controls-select-controls-option--docs) children.
+
+<Canvas of={ComboboxStories.LargeList} sourceState="shown" />
+
+That is what makes a long list workable: the DOM holds the matches, not the source. `limit` caps how many are rendered at once, so a search matching hundreds of entries still produces a bounded list.
+
+Selection, keyboard navigation, and the ARIA wiring are still Lion's, over whatever subset is currently rendered.
+
+## Rich Options
+
+Options can carry markup rather than only text:
+
+<Canvas of={ComboboxStories.RichOptions} sourceState="shown" />
+
+And they can be grouped:
+
+<Canvas of={ComboboxStories.Grouped} sourceState="shown" />
+
+## Clearing
+
+`clearable` adds a control to empty the field:
+
+<Canvas of={ComboboxStories.Clearable} sourceState="shown" />
+
+Offer it whenever no selection is a valid answer. Without it, a person who picks something by accident has no way back to nothing.
+
+`show-selected-hint` keeps the selected option's hint visible in the closed field, for when the hint is what distinguishes two similarly named entries.
+
+## Events
+
+Bind the native events, the same two a text input gives you:
+
+```js
+combobox.addEventListener('input', () => preview(combobox.modelValue));
+combobox.addEventListener('change', () => save(combobox.modelValue));
+```
+
+`input` fires on every alteration, typed or selected. `change` fires when the value is committed — an option is chosen, or the field is left after typing. Both are dispatched from the component, so `event.target` is the combobox rather than the textbox inside it.
+
+The control also emits `model-value-changed`. That is Lion's internal protocol name, carried because Lion's form system depends on it; prefer the native events.
+
+## Accessibility
+
+Lion supplies the combobox pattern — the ARIA roles, the active-descendant handling, and the keyboard model.
+
+The filtering is the part worth thinking about. A list that renders only matches means the number of options changes as a person types, which is announced. Keep `limit` high enough that a search feels complete and low enough that the announcement is not overwhelming.
+
+## Properties
+
+The `options` array is a property rather than an attribute, so bind it with `.options`.
+
+<ArgTypes of={ComboboxStories} />
diff --git a/packages/craftcms-ui/src/components/combobox/combobox.stories.ts b/packages/craftcms-ui/src/components/combobox/combobox.stories.ts
index bac1bd7ce63..5126fe78ec0 100644
--- a/packages/craftcms-ui/src/components/combobox/combobox.stories.ts
+++ b/packages/craftcms-ui/src/components/combobox/combobox.stories.ts
@@ -1,7 +1,10 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {html} from 'lit';
 import type {ComboboxItem} from './combobox.js';
 import './combobox.js';
+import type CraftCombobox from './combobox.js';
 
 const countries: ComboboxItem[] = [
   {label: 'United States', value: 'us'},
@@ -45,13 +48,24 @@ const manyOptions: ComboboxItem[] = Array.from({length: 400}, (_, i) => ({
   data: {keywords: `item number ${i}`},
 }));
 
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `combobox.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftCombobox>('craft-combobox');
+
+type CraftComboboxArgs = CraftCombobox & typeof args;
+
 const meta = {
-  title: 'Controls/Combobox',
+  title: 'Form Controls/Select Controls/Combobox',
   component: 'craft-combobox',
-} satisfies Meta;
+  args,
+  argTypes,
+} satisfies Meta<CraftComboboxArgs>;
 
 export default meta;
-type Story = StoryObj;
+type Story = StoryObj<CraftComboboxArgs>;
 
 export const Default: Story = {
   render: () =>
diff --git a/packages/craftcms-ui/src/components/combobox/combobox.test.ts b/packages/craftcms-ui/src/components/combobox/combobox.test.ts
index f42c191f14d..5cb388781a9 100644
--- a/packages/craftcms-ui/src/components/combobox/combobox.test.ts
+++ b/packages/craftcms-ui/src/components/combobox/combobox.test.ts
@@ -262,6 +262,43 @@ describe('craft-combobox', () => {
     expect(fired).toContain('$MY_ENV');
   });
 
+  it('emits native input while typing and change when the field is left', async () => {
+    const combobox = await createFixture((c) => {
+      c.requireOptionMatch = false;
+      c.options = [{label: 'Online', value: '1'}];
+    });
+    const order: string[] = [];
+    combobox.addEventListener('input', (event) => {
+      // The textbox lives in the light DOM, so its own event would otherwise
+      // reach consumers with the textbox as target rather than the component.
+      expect(event.target).toBe(combobox);
+      order.push('input');
+    });
+    combobox.addEventListener('change', () => order.push('change'));
+
+    // Cast rather than reaching through `_inputNode` directly, which is
+    // protected — the older tests in this file predate that being checked.
+    const input = (combobox as unknown as {_inputNode: HTMLInputElement})
+      ._inputNode;
+    for (const value of ['h', 'ht']) {
+      input.focus();
+      input.value = value;
+      input.dispatchEvent(new Event('input', {bubbles: true}));
+      await combobox.updateComplete;
+      await new Promise((resolve) => setTimeout(resolve));
+    }
+
+    // Typing alters but does not commit.
+    expect(order).toEqual(['input', 'input']);
+
+    combobox.dispatchEvent(new Event('blur'));
+    expect(order).toEqual(['input', 'input', 'change']);
+
+    // Leaving again without an edit commits nothing.
+    combobox.dispatchEvent(new Event('blur'));
+    expect(order).toEqual(['input', 'input', 'change']);
+  });
+
   it('keeps updating the model past the first keystroke, even with a v-model write-back', async () => {
     // Regression: list-mode autocomplete stopped syncing typed text into the
     // model after the first character, and a bound v-model writing .modelValue
diff --git a/packages/craftcms-ui/src/components/combobox/combobox.ts b/packages/craftcms-ui/src/components/combobox/combobox.ts
index 762b1c9ddc7..9b74148c6a7 100644
--- a/packages/craftcms-ui/src/components/combobox/combobox.ts
+++ b/packages/craftcms-ui/src/components/combobox/combobox.ts
@@ -3,6 +3,7 @@ import {html, nothing, render} from 'lit';
 import {property} from 'lit/decorators.js';
 import styles from './combobox.styles.js';
 import type CraftOption from '../option/option.js';
+import {emitChange, emitInput} from '@src/utilities/form-events';
 import {t} from '@src/utilities/translate';
 import '../option/option.js';
 import '../icon/icon.js';
@@ -58,6 +59,17 @@ interface VisibleEntry {
  * @slot label - Field label.
  * @slot after - Supplementary content rendered below the field.
  * @slot feedback - Validation feedback.
+ *
+ * @fires input - Emitted on every alteration to the value, typed or selected.
+ * @fires change - Emitted when the value is committed: an option is selected,
+ *   or the field is left after typing.
+ * @fires model-value-changed - The selection changed. Bubbles, so a form can
+ *   listen for it once on an ancestor rather than per field.
+ *
+ * `model-value-changed` is Lion's own protocol name, not one this package
+ * chose, and it is kept because Lion's form system dispatches and listens for
+ * it. Prefer the native events above: they are the contract this package
+ * supports, and they carry the component as `event.target`.
  */
 export default class CraftCombobox extends LionCombobox {
   static override get styles() {
@@ -103,21 +115,52 @@ export default class CraftCombobox extends LionCombobox {
   /** Last model value we've announced via `model-value-changed`. */
   #lastNotifiedValue: unknown = undefined;
 
+  /** Last model value announced as committed, via native `change`. */
+  #committedValue: unknown = undefined;
+
   #filtering = false;
 
   override firstUpdated(changed: Map<PropertyKey, unknown>) {
     super.firstUpdated(changed);
     this._inputNode?.addEventListener('input', this.#onInput);
+    // Same reason as `#onInput`: the textbox lives in the light DOM, so its own
+    // `change` on blur would reach consumers with the textbox as `target`.
+    // `#commit()` is what announces a commit from the host.
+    this._inputNode?.addEventListener('change', (event) =>
+      event.stopPropagation()
+    );
     // Keep our notion of the last-announced value in sync with every
     // model-value-changed the component emits — Lion's (on selection) and ours
     // (on free-text, below) — so we never double-announce the same value.
     this.addEventListener('model-value-changed', () => {
       this.#lastNotifiedValue = this.modelValue;
+
+      // Typing announces its own `input` from `#onInput` and commits on blur;
+      // anything else reaching here is a selection, which is both at once.
+      if (!this.#typing) {
+        emitInput(this);
+        this.#commit();
+      }
     });
+
+    // A typed value commits when the field is left, as a text input's does.
+    this.addEventListener('blur', () => this.#commit());
+
     this.#lastNotifiedValue = this.modelValue;
+    this.#committedValue = this.modelValue;
     this.#renderOptions();
   }
 
+  /** Emits native `change` when the value has moved since the last commit. */
+  #commit(): void {
+    if (this.modelValue === this.#committedValue) {
+      return;
+    }
+
+    this.#committedValue = this.modelValue;
+    emitChange(this);
+  }
+
   override updated(changed: Map<PropertyKey, unknown>) {
     super.updated(changed);
     if (changed.has('opened') && !this.opened) {
@@ -137,6 +180,9 @@ export default class CraftCombobox extends LionCombobox {
     }
   }
 
+  /**
+   * Registers an option with the combobox. Called by Lion as options render.
+   */
   override addFormElement(option: CraftOption, indexToInsertAt: number) {
     super.addFormElement(option, indexToInsertAt);
     option.updateComplete.then(() => {
@@ -149,10 +195,25 @@ export default class CraftCombobox extends LionCombobox {
     });
   }
 
-  #onInput = () => {
-    this.#filtering = true;
-    this.#renderOptions();
-    this.#syncModelFromInput();
+  #typing = false;
+
+  #onInput = (event: Event) => {
+    // Lion keeps its textbox in the light DOM, so the input's own event would
+    // reach consumers with the textbox as `target` rather than this component.
+    // Claim it here and re-emit from the host; listeners bound to the textbox
+    // itself (Lion's own) still run.
+    event.stopPropagation();
+
+    this.#typing = true;
+    try {
+      this.#filtering = true;
+      this.#renderOptions();
+      this.#syncModelFromInput();
+    } finally {
+      this.#typing = false;
+    }
+
+    emitInput(this);
   };
 
   /**
diff --git a/packages/craftcms-ui/src/components/copy-attribute/CopyAttribute.mdx b/packages/craftcms-ui/src/components/copy-attribute/CopyAttribute.mdx
new file mode 100644
index 00000000000..a56934c64c7
--- /dev/null
+++ b/packages/craftcms-ui/src/components/copy-attribute/CopyAttribute.mdx
@@ -0,0 +1,26 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CopyAttributeStories from './copy-attribute.stories';
+
+<Meta of={CopyAttributeStories} name="Docs" />
+
+# Copy Attribute
+
+`<craft-copy-attribute>` copies a value read from an element's attribute.
+
+<Canvas of={CopyAttributeStories.Default} sourceState="shown" />
+
+It exists for server-rendered markup, where the value to copy is already on an element in the page and passing it through a property would mean serialising it twice.
+
+For a value you have in script, [Copy Button](?path=/docs/components-copy-button--docs) takes it directly and is simpler.
+
+## Events
+
+Like the copy button, it emits `craft-copy` on success and `craft-error` on failure — clipboard writes can be refused, and the interface should say so rather than appear to have worked.
+
+## Accessibility
+
+The same rule as the copy button: name the control with what it copies, and announce the result if the surrounding page does not already.
+
+## Properties
+
+<ArgTypes of={CopyAttributeStories} />
diff --git a/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.stories.ts b/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.stories.ts
index e2da551fc3c..6c31b83fa48 100644
--- a/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.stories.ts
+++ b/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.stories.ts
@@ -1,26 +1,43 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './copy-attribute.js';
+import type CraftCopyAttribute from './copy-attribute.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `copy-attribute.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftCopyAttribute>(
+  'craft-copy-attribute'
+);
+
+type CopyAttributeArgs = CraftCopyAttribute & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Copy Attribute',
   component: 'craft-copy-attribute',
-  argTypes: {},
-  parameters: {
-    layout: 'centered',
-  },
-  render: (args) => html`
-    <craft-copy-attribute value="fieldHandle">fieldHandle</craft-copy-attribute>
-  `,
-} satisfies Meta<any>;
+  args: {...args, value: 'fieldHandle', 'default-slot': 'fieldHandle'},
+  argTypes,
+  parameters: {layout: 'centered'},
+  // Render from args alone so every control — attributes and slot — drives the
+  // story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<CopyAttributeArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CopyAttributeArgs>;
+
+/** The value reads as text and copies on click. */
+export const Default: Story = {};
+
+/** The visible text and the copied value do not have to match. */
+export const DifferentCopiedValue: Story = {
+  args: {value: 'craft\\elements\\Entry', 'default-slot': 'Entry'},
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+export const Disabled: Story = {
+  args: {disabled: true},
 };
diff --git a/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.test.ts b/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.test.ts
new file mode 100644
index 00000000000..0482c4c5292
--- /dev/null
+++ b/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.test.ts
@@ -0,0 +1,53 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './copy-attribute.js';
+import type CraftCopyAttribute from './copy-attribute.js';
+
+async function createCopyAttribute(
+  attrs: Record<string, string> = {}
+): Promise<CraftCopyAttribute> {
+  const element = document.createElement(
+    'craft-copy-attribute'
+  ) as CraftCopyAttribute;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function inner(element: CraftCopyAttribute): HTMLElement {
+  return element.shadowRoot!.querySelector('craft-copy-button')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-copy-attribute', () => {
+  /** It is a copy button that shows the value it copies. */
+  it('shows the value and hands it to the copy button', async () => {
+    const element = await createCopyAttribute({value: 'fieldHandle'});
+
+    expect(inner(element).getAttribute('value')).toBe('fieldHandle');
+    expect(inner(element).textContent?.trim()).toBe('fieldHandle');
+  });
+
+  it('follows a changed value', async () => {
+    const element = await createCopyAttribute({value: 'one'});
+
+    element.value = 'two';
+    await element.updateComplete;
+
+    expect(inner(element).getAttribute('value')).toBe('two');
+  });
+
+  it('gives each instance an id, so its tooltip can be referenced', async () => {
+    const first = await createCopyAttribute({value: 'a'});
+    const second = await createCopyAttribute({value: 'b'});
+
+    expect(inner(first).id).not.toBe('');
+    expect(inner(first).id).not.toBe(inner(second).id);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.ts b/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.ts
index 229bbe6f008..bdf7b96272a 100644
--- a/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.ts
+++ b/packages/craftcms-ui/src/components/copy-attribute/copy-attribute.ts
@@ -20,7 +20,7 @@ import CraftCopyButton from '../copy-button/copy-button.js';
 export default class CraftCopyAttribute extends LitElement {
   static override styles: CSSResultGroup = [hostStyles, styles];
 
-  @query('craft-copy-button') copyButtonEl!: CraftCopyButton;
+  @query('craft-copy-button') protected copyButtonEl!: CraftCopyButton;
 
   /** The text value to copy */
   @property({type: String})
@@ -30,7 +30,7 @@ export default class CraftCopyAttribute extends LitElement {
   @property({type: Boolean, reflect: true})
   disabled: boolean = false;
 
-  getId(): string {
+  protected getId(): string {
     return `attribute-${this.value
       .replace(/([a-z])([A-Z])/g, '$1-$2')
       .replace(/[\s_]+/g, '-')
diff --git a/packages/craftcms-ui/src/components/copy-button/CopyButton.mdx b/packages/craftcms-ui/src/components/copy-button/CopyButton.mdx
new file mode 100644
index 00000000000..e0b75c591ce
--- /dev/null
+++ b/packages/craftcms-ui/src/components/copy-button/CopyButton.mdx
@@ -0,0 +1,31 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as CopyButtonStories from './copy-button.stories';
+
+<Meta of={CopyButtonStories} name="Docs" />
+
+# Copy Button
+
+`<craft-copy-button>` copies a value to the clipboard.
+
+<Canvas of={CopyButtonStories.Default} sourceState="shown" />
+
+Use it beside a value worth taking away — a token, a URL, an ID. For a value shown in a field, [Input Copy](?path=/docs/form-controls-text-controls-input-copy--docs) pairs the two together and is usually the better fit.
+
+## Events
+
+The outcome is reported rather than assumed:
+
+- `craft-copy` — the value reached the clipboard
+- `craft-error` — it did not
+
+Clipboard writes fail for reasons outside your control: permissions, an insecure context, a browser that declines. Listening for the failure is what lets the interface say so rather than appearing to have worked.
+
+## Accessibility
+
+`tooltip-label` names what will be copied, which is what makes an icon-only copy button announce as something other than "button".
+
+A copy that succeeds silently is a copy a screen reader user cannot confirm. The button reports success through `craft-copy`; whether that becomes an announcement is up to the surrounding page, and it should.
+
+## Properties
+
+<ArgTypes of={CopyButtonStories} />
diff --git a/packages/craftcms-ui/src/components/copy-button/copy-button.stories.ts b/packages/craftcms-ui/src/components/copy-button/copy-button.stories.ts
index 6c1ac3b1c86..d9ab01ec95b 100644
--- a/packages/craftcms-ui/src/components/copy-button/copy-button.stories.ts
+++ b/packages/craftcms-ui/src/components/copy-button/copy-button.stories.ts
@@ -1,40 +1,64 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './copy-button.js';
+import type CraftCopyButton from './copy-button.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `copy-button.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftCopyButton>('craft-copy-button');
+
+type CopyButtonArgs = CraftCopyButton & typeof args;
+
+/** A field to paste into, so the copy can actually be checked. */
+const withPasteTarget = (button: unknown) => html`
+  <div style="display: grid; gap: 1em">
+    <div>${button}</div>
+    <input
+      type="text"
+      placeholder="Test your paste here"
+      aria-label="Paste here"
+    />
+  </div>
+`;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Functional/Copy Button',
+  title: 'Components/Copy Button',
   component: 'craft-copy-button',
-  parameters: {
-    layout: 'centered',
+  args: {
+    ...args,
+    value: 'You copied me!',
+    'default-slot': 'Copy to clipboard',
   },
-  argTypes: {},
-  render: (args) => html`
-    <div style="display: grid; gap: 1em;">
-      <div>
-        <craft-copy-button value="You copied me!" data-testId="button"
-          >Clicking will copy "You copied me!" to the clipboard.
-        </craft-copy-button>
-      </div>
-      <div>
-        <input
-          type="text"
-          value=""
-          placeholder="Test your paste here"
-          data-testId="pastezone"
-        />
-      </div>
-    </div>
-  `,
-} satisfies Meta<any>;
+  argTypes,
+  parameters: {layout: 'centered'},
+  // Render from args alone so every control — attributes and slot — drives the
+  // story. Stories below vary the args, not the template.
+  render: (args) => withPasteTarget(template(args)),
+} satisfies Meta<CopyButtonArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CopyButtonArgs>;
+
+/** Clicking copies `value` and shows the outcome for a moment. */
+export const Default: Story = {};
+
+/** `tooltip-label` names the button when its content is an icon. */
+export const WithTooltipLabel: Story = {
+  args: {'tooltip-label': 'Copy the handle', 'default-slot': 'Copy'},
+};
+
+/** `feedback-duration` sets how long the outcome stays up, in milliseconds. */
+export const SlowFeedback: Story = {
+  args: {'feedback-duration': 4000},
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+export const Disabled: Story = {
+  args: {disabled: true},
 };
diff --git a/packages/craftcms-ui/src/components/copy-button/copy-button.test.ts b/packages/craftcms-ui/src/components/copy-button/copy-button.test.ts
new file mode 100644
index 00000000000..c664667ddf6
--- /dev/null
+++ b/packages/craftcms-ui/src/components/copy-button/copy-button.test.ts
@@ -0,0 +1,95 @@
+import {beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+
+import './copy-button.js';
+import type CraftCopyButton from './copy-button.js';
+
+async function createCopyButton(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Copy'
+): Promise<CraftCopyButton> {
+  const element = document.createElement(
+    'craft-copy-button'
+  ) as CraftCopyButton;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function button(element: CraftCopyButton): HTMLButtonElement {
+  return element.shadowRoot!.querySelector('button')!;
+}
+
+/** happy-dom has no clipboard, so it is stubbed for what the component awaits. */
+function stubClipboard(writeText = vi.fn().mockResolvedValue(undefined)) {
+  Object.defineProperty(navigator, 'clipboard', {
+    value: {writeText},
+    configurable: true,
+    writable: true,
+  });
+  return writeText;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-copy-button', () => {
+  it('writes its value to the clipboard when pressed', async () => {
+    const writeText = stubClipboard();
+    const element = await createCopyButton({value: 'https://craftcms.com'});
+
+    await element.copyValue();
+
+    expect(writeText).toHaveBeenCalledWith('https://craftcms.com');
+  });
+
+  it('announces the copy so a page can react to it', async () => {
+    stubClipboard();
+    const element = await createCopyButton({value: 'handle'});
+    const copied = vi.fn();
+    element.addEventListener('craft-copy', copied);
+
+    await element.copyValue();
+
+    expect(copied).toHaveBeenCalled();
+    const [event] = copied.mock.calls[0] as [CustomEvent<{value: string}>];
+    expect(event.detail.value).toBe('handle');
+  });
+
+  it('announces a failure rather than swallowing it', async () => {
+    stubClipboard(vi.fn().mockRejectedValue(new Error('denied')));
+    const element = await createCopyButton({value: 'handle'});
+    const failed = vi.fn();
+    element.addEventListener('craft-error', failed);
+
+    await element.copyValue();
+
+    expect(failed).toHaveBeenCalled();
+  });
+
+  it('does nothing while disabled', async () => {
+    const writeText = stubClipboard();
+    const element = await createCopyButton({value: 'handle', disabled: ''});
+
+    await element.copyValue();
+
+    expect(writeText).not.toHaveBeenCalled();
+    expect(button(element).disabled).toBe(true);
+  });
+
+  /** A second press mid-copy would double-fire the event and the feedback. */
+  it('ignores a press while a copy is already running', async () => {
+    const writeText = stubClipboard();
+    const element = await createCopyButton({value: 'handle'});
+
+    const first = element.copyValue();
+    await element.copyValue();
+    await first;
+
+    expect(writeText).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/copy-button/copy-button.ts b/packages/craftcms-ui/src/components/copy-button/copy-button.ts
index 97514ba2b5c..fbe2dc84bb4 100644
--- a/packages/craftcms-ui/src/components/copy-button/copy-button.ts
+++ b/packages/craftcms-ui/src/components/copy-button/copy-button.ts
@@ -37,27 +37,38 @@ const animations = {
 export default class CraftCopyButton extends LitElement {
   static override styles: CSSResultGroup = [styles];
 
-  @state() isCopying = false;
+  @state() protected isCopying = false;
 
-  @state() status: 'rest' | 'copying' | 'success' | 'error' = 'rest';
+  @state() protected status: 'rest' | 'copying' | 'success' | 'error' = 'rest';
 
-  @query('slot[name="copy-icon"]') copyIconEl!: HTMLSlotElement;
-  @query('slot[name="success-icon"]') successIconEl!: HTMLSlotElement;
-  @query('slot[name="error-icon"]') errorIconEl!: HTMLSlotElement;
-  @query('craft-tooltip') tooltipEl!: CraftTooltip;
+  @query('slot[name="copy-icon"]') protected copyIconEl!: HTMLSlotElement;
+  @query('slot[name="success-icon"]') protected successIconEl!: HTMLSlotElement;
+  @query('slot[name="error-icon"]') protected errorIconEl!: HTMLSlotElement;
+  @query('craft-tooltip') protected tooltipEl!: CraftTooltip;
 
   /** Value to copy on click */
   @property({type: String}) value = '';
 
+  /** Prevents copying, and dims the button. */
   @property({type: Boolean}) disabled = false;
 
   /** The length of time to show feedback before restoring the default trigger. */
   @property({attribute: 'feedback-duration', type: Number}) feedbackDuration =
     1000;
 
+  /**
+   * Text shown in the button's tooltip, naming what will be copied.
+   */
   @property({attribute: 'tooltip-label'})
   tooltipLabel: string | null = null;
 
+  /**
+
+   * Copies `value` to the clipboard and shows the outcome. Resolves once the
+   * status has been shown.
+
+   */
+
   async copyValue() {
     if (this.status === 'copying' || this.disabled) {
       return;
@@ -90,6 +101,12 @@ export default class CraftCopyButton extends LitElement {
     }
   }
 
+  /**
+
+   * Shows the copy outcome for a moment, then returns the button to rest.
+
+   */
+
   async showStatus(status: 'success' | 'error') {
     const statusIcon =
       status === 'success' ? this.successIconEl : this.errorIconEl;
diff --git a/packages/craftcms-ui/src/components/dialog/Dialog.mdx b/packages/craftcms-ui/src/components/dialog/Dialog.mdx
new file mode 100644
index 00000000000..83261297a3e
--- /dev/null
+++ b/packages/craftcms-ui/src/components/dialog/Dialog.mdx
@@ -0,0 +1,44 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as DialogStories from './dialog.stories';
+
+<Meta of={DialogStories} name="Docs" />
+
+# Dialog
+
+`<craft-dialog>` is a modal dialog.
+
+<Canvas of={DialogStories.Default} sourceState="shown" />
+
+Being modal, it takes focus and blocks the page behind it. That is a strong thing to do to someone, so reach for it only when they genuinely have to deal with something before continuing — a destructive confirmation, a required choice.
+
+For anything less, a [Popover](?path=/docs/components-popover--docs) or an inline [Callout](?path=/docs/components-callout--docs) interrupts less.
+
+## Opening and Closing
+
+Set the `open` attribute to show it.
+
+There is **no `open` boolean property**: Lion's overlay system already defines `open()` as a _method_, so the property would collide. Use the attribute, or the `opened` property.
+
+```js
+dialog.setAttribute('open', ''); // shows it
+dialog.opened = false; // hides it
+```
+
+Any descendant carrying `data-dialog="close"` closes the dialog when clicked, so a close button needs no wiring.
+
+## Content
+
+Default-slot children are the body; `slot="footer"` children are right-aligned below it, which is where actions go.
+
+## Accessibility
+
+The dialog renders inside a native `<dialog>`, so the browser supplies the modal behaviour — the focus trap, the inert background, and Escape to dismiss.
+
+Two things stay with you:
+
+- **Name it.** A dialog with no accessible name is announced only as "dialog".
+- **Give it a way out that is not Escape.** Escape works, but a visible close or cancel control is what makes that discoverable.
+
+## Properties
+
+<ArgTypes of={DialogStories} />
diff --git a/packages/craftcms-ui/src/components/dialog/dialog.stories.ts b/packages/craftcms-ui/src/components/dialog/dialog.stories.ts
index 7815dce34e6..5c61a518ece 100644
--- a/packages/craftcms-ui/src/components/dialog/dialog.stories.ts
+++ b/packages/craftcms-ui/src/components/dialog/dialog.stories.ts
@@ -1,15 +1,27 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 
 import './dialog.js';
 import type CraftDialog from './dialog.js';
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `dialog.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftDialog>('craft-dialog');
+
+type CraftDialogArgs = CraftDialog & typeof args;
+
 const meta = {
   title: 'Components/Dialog',
   component: 'craft-dialog',
-  args: {},
+  args: {...args, label: 'Dialog'},
+  argTypes,
   parameters: {
     layout: 'centered',
   },
@@ -29,10 +41,10 @@ const meta = {
       <craft-button @click="${openDialog}">Open Dialog</craft-button>
     `;
   },
-} satisfies Meta<any>;
+} satisfies Meta<CraftDialogArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftDialogArgs>;
 
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
 export const Default: Story = {
diff --git a/packages/craftcms-ui/src/components/dialog/dialog.ts b/packages/craftcms-ui/src/components/dialog/dialog.ts
index 5e0f1fd6ef7..b70bcacec16 100644
--- a/packages/craftcms-ui/src/components/dialog/dialog.ts
+++ b/packages/craftcms-ui/src/components/dialog/dialog.ts
@@ -61,11 +61,18 @@ contentStyles?.replaceSync(`
 `);
 
 /**
- * craft-dialog is a modal dialog. Set the `open` attribute to show it;
+ * @summary A modal dialog. Set the `open` attribute to show it;
  * default-slot children render as the body, `slot="footer"` children render
  * in a footer, and any descendant with `data-dialog="close"` closes the
  * dialog when clicked.
  *
+ * Being modal, it takes focus and blocks the page behind it — so reach for it
+ * when a person genuinely has to deal with something before continuing, and
+ * for anything less use a `craft-popover` or an inline `craft-callout`.
+ *
+ * @slot - The dialog's body content.
+ * @slot footer - Actions, rendered right-aligned below the body.
+ *
  * Note: Lion's overlay system already defines an `open()` *method*, so there
  * is no `open` boolean property — use the `open` attribute or the `opened`
  * property.
@@ -75,6 +82,11 @@ contentStyles?.replaceSync(`
  * dialog.setAttribute('open', '');
  * dialog.append(message);
  * document.body.appendChild(dialog);
+ *
+ * @fires craft-show - The overlay is opening. Fires as the state flips.
+ * @fires craft-after-show - The overlay has opened and its update has settled.
+ * @fires craft-hide - The overlay is closing. Fires as the state flips.
+ * @fires craft-after-hide - The overlay has closed and its update has settled.
  */
 export default class CraftDialog extends LionDialog {
   /**
diff --git a/packages/craftcms-ui/src/components/disclosure/Disclosure.mdx b/packages/craftcms-ui/src/components/disclosure/Disclosure.mdx
new file mode 100644
index 00000000000..7d7deb5567a
--- /dev/null
+++ b/packages/craftcms-ui/src/components/disclosure/Disclosure.mdx
@@ -0,0 +1,42 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as DisclosureStories from './disclosure.stories';
+
+<Meta of={DisclosureStories} name="Docs" />
+
+# Disclosure
+
+`<craft-disclosure>` shows and hides a section of content.
+
+<Canvas of={DisclosureStories.Collapsed} sourceState="shown" />
+
+<Canvas of={DisclosureStories.Expanded} sourceState="shown" />
+
+## Two Modes
+
+**Slotted mode** is the usual one: a `slot="invoker"` trigger and `slot="content"` content, following Lion's collapsible convention. Without a slotted invoker it renders a default one from `label`:
+
+<Canvas of={DisclosureStories.DefaultInvoker} sourceState="shown" />
+
+**External-target mode** wraps a bare `button` whose `aria-controls` names an element elsewhere in the document. Toggling flips that target's `data-state` between `expanded` and `collapsed`, and the consumer supplies the CSS.
+
+That second mode exists for server-rendered markup, where the trigger and the thing it reveals are rendered in different places and cannot be nested. It can also persist the state to a cookie via `cookie-name`, so a section stays as a person left it.
+
+## Accordions
+
+<Canvas of={DisclosureStories.Accordion} sourceState="shown" />
+
+Several disclosures side by side make an accordion. Nothing enforces one-open-at-a-time — if you want that, close the others yourself.
+
+Consider whether you want it at all. Collapsing a section a person just opened, because they opened another, is a common source of frustration.
+
+## Accessibility
+
+The invoker carries `aria-expanded` and `aria-controls`, so the state and the relationship are both announced.
+
+In external-target mode the component mirrors `aria-expanded` onto the button it wraps — which is why that mode expects a real `button`, not a div dressed as one.
+
+Label the invoker with what it reveals rather than with the action. "Advanced settings" says what is behind it; "Show more" says only that there is more.
+
+## Properties
+
+<ArgTypes of={DisclosureStories} />
diff --git a/packages/craftcms-ui/src/components/disclosure/disclosure.stories.ts b/packages/craftcms-ui/src/components/disclosure/disclosure.stories.ts
index d8acc6180e6..f6003e432d7 100644
--- a/packages/craftcms-ui/src/components/disclosure/disclosure.stories.ts
+++ b/packages/craftcms-ui/src/components/disclosure/disclosure.stories.ts
@@ -1,18 +1,27 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {expect} from 'storybook/test';
 import {html} from 'lit';
 
 import './disclosure.js';
+import type CraftDisclosure from './disclosure.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `disclosure.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftDisclosure>('craft-disclosure');
+
+type CraftDisclosureArgs = CraftDisclosure & typeof args;
 
 const meta = {
-  title: 'Functional/Disclosure',
+  title: 'Components/Disclosure',
   component: 'craft-disclosure',
-  argTypes: {
-    state: {
-      control: {type: 'select'},
-      options: ['collapsed', 'expanded'],
-    },
-  },
+  args,
+  argTypes,
   render: (args) => html`
     <craft-disclosure state="${args.state || 'collapsed'}">
       <button type="button" aria-controls="disclosure-target">
@@ -39,10 +48,10 @@ const meta = {
       }
     </style>
   `,
-} satisfies Meta<any>;
+} satisfies Meta<CraftDisclosureArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftDisclosureArgs>;
 
 export const Collapsed: Story = {
   args: {
diff --git a/packages/craftcms-ui/src/components/disclosure/disclosure.test.ts b/packages/craftcms-ui/src/components/disclosure/disclosure.test.ts
new file mode 100644
index 00000000000..40e8b4a2071
--- /dev/null
+++ b/packages/craftcms-ui/src/components/disclosure/disclosure.test.ts
@@ -0,0 +1,101 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './disclosure.js';
+import type CraftDisclosure from './disclosure.js';
+
+/**
+ * External-target mode: a bare `button[aria-controls]` inside the disclosure,
+ * pointing at an element elsewhere in the document. This is the contract of the
+ * legacy `CraftDisclosure` element.
+ */
+async function createExternal(
+  attrs: Record<string, string> = {}
+): Promise<{element: CraftDisclosure; target: HTMLElement}> {
+  const target = document.createElement('div');
+  target.id = 'target';
+  target.dataset.state = 'collapsed';
+
+  const element = document.createElement('craft-disclosure') as CraftDisclosure;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML =
+    '<button type="button" aria-controls="target">Toggle</button>';
+
+  // The target has to be in the document before the disclosure connects: the
+  // component looks it up by id while setting external mode up.
+  document.body.append(target);
+  document.body.append(element);
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return {element, target};
+}
+
+function trigger(element: CraftDisclosure): HTMLButtonElement {
+  return element.querySelector('button')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-disclosure', () => {
+  /**
+   * With no `state` in the markup the disclosure opens, whatever the target's
+   * own `data-state` said — the component owns the state rather than adopting
+   * what it finds.
+   */
+  it('defaults to expanded', async () => {
+    const {element, target} = await createExternal();
+
+    expect(element.state).toBe('expanded');
+    expect(target.dataset.state).toBe('expanded');
+    expect(trigger(element).getAttribute('aria-expanded')).toBe('true');
+  });
+
+  /** `state` is reflected, so a consumer can start it closed from markup. */
+  it('honours a collapsed state set on the host', async () => {
+    const {element, target} = await createExternal({state: 'collapsed'});
+
+    expect(target.dataset.state).toBe('collapsed');
+    expect(trigger(element).getAttribute('aria-expanded')).toBe('false');
+  });
+
+  /** The consumer supplies the CSS; the component only flips `data-state`. */
+  it('collapses the target it controls', async () => {
+    const {element, target} = await createExternal();
+
+    trigger(element).click();
+    await element.updateComplete;
+
+    expect(target.dataset.state).toBe('collapsed');
+    expect(trigger(element).getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('expands again', async () => {
+    const {element, target} = await createExternal();
+
+    trigger(element).click();
+    await element.updateComplete;
+    trigger(element).click();
+    await element.updateComplete;
+
+    expect(target.dataset.state).toBe('expanded');
+    expect(trigger(element).getAttribute('aria-expanded')).toBe('true');
+  });
+
+  it('fires close and open as it toggles', async () => {
+    const {element} = await createExternal();
+    const seen: string[] = [];
+    element.addEventListener('craft-show', () => seen.push('open'));
+    element.addEventListener('craft-hide', () => seen.push('close'));
+
+    trigger(element).click();
+    await element.updateComplete;
+    trigger(element).click();
+    await element.updateComplete;
+
+    expect(seen).toEqual(['close', 'open']);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/disclosure/disclosure.ts b/packages/craftcms-ui/src/components/disclosure/disclosure.ts
index 2e2aa95af73..52fe4c6a312 100644
--- a/packages/craftcms-ui/src/components/disclosure/disclosure.ts
+++ b/packages/craftcms-ui/src/components/disclosure/disclosure.ts
@@ -5,7 +5,7 @@ import type {WindowWithCraft} from '@src/types/globals';
 import '../button/button.js';
 
 /**
- * A disclosure trigger supporting two modes:
+ * @summary A trigger that shows and hides content, in either of two modes:
  *
  * **Slotted (collapsible) mode** — Lion's collapsible convention: a
  * `slot="invoker"` trigger and `slot="content"` collapsible content. Without a
@@ -20,6 +20,9 @@ import '../button/button.js';
  * persists the state to a cookie (`cookie-name`). This is the contract of the
  * legacy `CraftDisclosure` element and `_includes/disclosure-toggle.twig`.
  * The mode is chosen automatically when such a button is present.
+ *
+ * @fires craft-show - The content was expanded.
+ * @fires craft-hide - The content was collapsed.
  */
 export default class CraftDisclosure extends LionCollapsible {
   static override get styles() {
@@ -157,7 +160,7 @@ export default class CraftDisclosure extends LionCollapsible {
   private __handleExternalOpen() {
     this.__externalExpanded = true;
     this.__externalTrigger?.setAttribute('aria-expanded', 'true');
-    this.dispatchEvent(new CustomEvent('open'));
+    this.dispatchEvent(new CustomEvent('craft-show'));
 
     const target = this.__externalTarget;
     if (target) {
@@ -170,7 +173,7 @@ export default class CraftDisclosure extends LionCollapsible {
   private __handleExternalClose() {
     this.__externalExpanded = false;
     this.__externalTrigger?.setAttribute('aria-expanded', 'false');
-    this.dispatchEvent(new CustomEvent('close'));
+    this.dispatchEvent(new CustomEvent('craft-hide'));
 
     const target = this.__externalTarget;
     if (target) {
diff --git a/packages/craftcms-ui/src/components/docs-references.test.ts b/packages/craftcms-ui/src/components/docs-references.test.ts
new file mode 100644
index 00000000000..9e28b1c6e58
--- /dev/null
+++ b/packages/craftcms-ui/src/components/docs-references.test.ts
@@ -0,0 +1,152 @@
+import {existsSync, globSync, readFileSync, readdirSync} from 'node:fs';
+import {join} from 'node:path';
+import {describe, expect, it} from 'vite-plus/test';
+
+/**
+ * A docs page references its stories by name — `<Canvas of={ChipStories.Icon}>`.
+ * Rename or drop the story and MDX resolves `of` to `undefined`, which does not
+ * fail the build: Storybook renders the whole page as an error instead, so the
+ * component silently loses its documentation until someone opens it.
+ *
+ * Cross-check every reference against the story file's actual exports.
+ */
+
+const COMPONENTS = join(import.meta.dirname, '.');
+const SRC = join(import.meta.dirname, '..');
+
+/** `?path=/docs/<id>--docs` — how the pages link to each other. */
+const CROSS_LINK = /\?path=\/docs\/([a-z0-9-]+)--docs/g;
+
+/** `<name>Stories.Foo` — how the MDX pages address their stories. */
+const REFERENCE = /\b[A-Za-z]+Stories\.([A-Za-z][A-Za-z0-9]*)/g;
+const EXPORT = /^export const ([A-Za-z][A-Za-z0-9]*)\s*:/gm;
+
+function matchAll(source: string, pattern: RegExp): string[] {
+  return [...source.matchAll(pattern)].map((match) => match[1]!);
+}
+
+/** Every `[mdx, stories]` pair sitting in a component directory. */
+function docPages(): Array<{component: string; mdx: string; stories: string}> {
+  const pages: Array<{component: string; mdx: string; stories: string}> = [];
+
+  for (const component of readdirSync(COMPONENTS, {withFileTypes: true})) {
+    if (!component.isDirectory()) {
+      continue;
+    }
+
+    const dir = join(COMPONENTS, component.name);
+    const files = readdirSync(dir);
+    const mdx = files.find((file) => file.endsWith('.mdx'));
+    const stories = files.find((file) => file.endsWith('.stories.ts'));
+
+    if (mdx && stories) {
+      pages.push({
+        component: component.name,
+        mdx: join(dir, mdx),
+        stories: join(dir, stories),
+      });
+    }
+  }
+
+  return pages;
+}
+
+const pages = docPages();
+
+/**
+ * Storybook's own id derivation: lowercase, non-alphanumerics collapsed to
+ * dashes. Renaming a story group changes every id under it, so a cross-link
+ * written before the move silently points at nothing.
+ */
+function docsId(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Every docs id the package declares — from story titles anywhere under `src`,
+ * plus MDX pages that stand alone with their own `<Meta title>`.
+ */
+const knownIds = new Set(
+  [
+    ...globSync(join(SRC, '**/*.stories.ts')).flatMap((file) => {
+      const title = /title:\s*'([^']+)'/.exec(readFileSync(file, 'utf8'))?.[1];
+      return title ? [docsId(title)] : [];
+    }),
+    ...globSync(join(SRC, '**/*.mdx')).flatMap((file) => {
+      const title = /<Meta\s+title="([^"]+)"/.exec(
+        readFileSync(file, 'utf8')
+      )?.[1];
+      return title ? [docsId(title)] : [];
+    }),
+  ].filter(Boolean)
+);
+
+describe('docs pages reference stories that exist', () => {
+  /** A guard that silently matches nothing would be worse than none at all. */
+  it('finds the documented components', () => {
+    expect(pages.length).toBeGreaterThan(0);
+  });
+
+  it.each(pages)('$component', ({mdx, stories}) => {
+    const referenced = new Set(matchAll(readFileSync(mdx, 'utf8'), REFERENCE));
+    const exported = new Set(matchAll(readFileSync(stories, 'utf8'), EXPORT));
+
+    const missing = [...referenced].filter((name) => !exported.has(name));
+
+    expect(missing).toEqual([]);
+  });
+});
+
+describe('docs pages import stories that exist', () => {
+  /**
+   * An MDX page importing a stories file that is not there fails the Storybook
+   * build rather than degrading — but the build takes a minute and this takes
+   * milliseconds.
+   */
+  it.each(
+    globSync(join(COMPONENTS, '*', '*.mdx')).map((mdx) => ({
+      component: mdx.split('/').at(-2)!,
+      mdx,
+    }))
+  )('$component', ({mdx}) => {
+    const imported = /from '\.\/([a-z-]+\.stories)'/.exec(
+      readFileSync(mdx, 'utf8')
+    )?.[1];
+
+    if (!imported) {
+      return;
+    }
+
+    expect(
+      existsSync(join(mdx, '..', `${imported}.ts`)),
+      `${mdx} imports ${imported}, which does not exist`
+    ).toBe(true);
+  });
+});
+
+/**
+ * Every MDX page in the package, not just the ones sitting beside a story
+ * file — the Getting Started and Tokens pages carry cross-links too, and a
+ * dead one there is the first thing a new reader would hit.
+ */
+const allPages = globSync(join(SRC, '**/*.mdx')).map((mdx) => ({
+  page: mdx.slice(SRC.length + 1),
+  mdx,
+}));
+
+describe('docs pages link to pages that exist', () => {
+  it('finds every page in the package', () => {
+    expect(allPages.length).toBeGreaterThan(pages.length);
+  });
+
+  it.each(allPages)('$page', ({mdx}) => {
+    const linked = matchAll(readFileSync(mdx, 'utf8'), CROSS_LINK);
+    const dead = linked.filter((id) => !knownIds.has(id));
+
+    expect(dead).toEqual([]);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/empty/Empty.mdx b/packages/craftcms-ui/src/components/empty/Empty.mdx
new file mode 100644
index 00000000000..26ab3de1151
--- /dev/null
+++ b/packages/craftcms-ui/src/components/empty/Empty.mdx
@@ -0,0 +1,52 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as EmptyStories from './empty.stories';
+
+<Meta of={EmptyStories} name="Docs" />
+
+# Empty
+
+`<craft-empty>` fills a space that has nothing in it yet.
+
+<Canvas of={EmptyStories.Default} sourceState="shown" />
+
+Use it wherever a list, index, or panel can come up with no results — a place that would otherwise be blank, which reads as broken rather than as empty.
+
+## Writing the Message
+
+An empty state has one job: tell a person what is missing and what to do about it.
+
+<Canvas of={EmptyStories.LabelOnly} sourceState="shown" />
+
+Say what is absent rather than that something is. "No entries yet" is a fact about the section; "Nothing to show" is a fact about the screen, and a person cannot act on it.
+
+Then give them the action:
+
+<Canvas of={EmptyStories.WithAction} sourceState="shown" />
+
+The default slot sits below the message and is where that action goes.
+
+## Distinguishing Empty From Filtered
+
+The two look the same and mean opposite things. A section with no entries needs "Create one"; a search with no matches needs "Clear the filters".
+
+Getting this wrong sends someone to create something they already have.
+
+## Graphics and Custom Content
+
+`icon` puts artwork above the message, and the `graphic` slot replaces it with your own:
+
+<Canvas of={EmptyStories.CustomGraphic} sourceState="shown" />
+
+The `content` slot replaces the message region entirely, for a state needing more than a line:
+
+<Canvas of={EmptyStories.CustomContent} sourceState="shown" />
+
+## Accessibility
+
+The graphic is decoration — the message carries the meaning, so artwork that repeats it should not be announced twice.
+
+When an empty state appears in response to something a person did, such as a filter returning nothing, the change needs announcing. The component does not do that: it renders in place and says nothing about arriving, so the code that swaps it in is responsible.
+
+## Properties
+
+<ArgTypes of={EmptyStories} />
diff --git a/packages/craftcms-ui/src/components/empty/empty.stories.ts b/packages/craftcms-ui/src/components/empty/empty.stories.ts
index d3b4e234b6a..648b2d6d718 100644
--- a/packages/craftcms-ui/src/components/empty/empty.stories.ts
+++ b/packages/craftcms-ui/src/components/empty/empty.stories.ts
@@ -1,96 +1,75 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html, nothing} from 'lit';
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
-import type CraftEmpty from './empty.js';
 import './empty.js';
+import type CraftEmpty from './empty.js';
 import '../button/button.js';
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `empty.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftEmpty>('craft-empty');
+
+type EmptyArgs = CraftEmpty & typeof args;
+
 const meta = {
   title: 'Components/Empty',
   component: 'craft-empty',
-  args: {
-    label: 'Nothing yet.',
-    icon: 'magnifying-glass',
-  },
-  argTypes: {
-    label: {
-      control: {type: 'text'},
-    },
-    icon: {
-      control: {type: 'text'},
-      description: 'Icon name rendered above the label',
-    },
-  },
-  render: ({label, icon}) => {
-    return html`
-      <craft-empty label="${label}" icon="${icon || nothing}"></craft-empty>
-    `;
-  },
-} satisfies Meta<CraftEmpty>;
+  args: {...args, label: 'Nothing yet.', icon: 'magnifying-glass'},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<EmptyArgs>;
 
 export default meta;
-type Story = StoryObj<CraftEmpty>;
+type Story = StoryObj<EmptyArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** An icon above a label, which is the whole component. */
+export const Default: Story = {};
 
+/** Drop the `icon` for a quieter state. */
 export const LabelOnly: Story = {
-  args: {
-    icon: '',
-  },
+  args: {icon: ''},
 };
 
+/** The default slot holds whatever gets the reader out of the empty state. */
 export const WithAction: Story = {
-  render: ({label, icon}) => {
-    return html`
-      <craft-empty label="${label}" icon="${icon || nothing}">
-        <craft-button icon="plus">New entry</craft-button>
-      </craft-empty>
-    `;
+  args: {
+    'default-slot': '<craft-button icon="plus">New entry</craft-button>',
   },
 };
 
+/** The `content` slot replaces the label when it needs more than one line. */
 export const CustomContent: Story = {
-  render: ({icon}) => {
-    return html`
-      <craft-empty icon="${icon || nothing}">
-        <div slot="content">
-          <p style="font-size: 1.25em; margin-block-end: 0">
-            No entries match your search.
-          </p>
-          <p>Try a different keyword, or clear the filters.</p>
-        </div>
-        <craft-button appearance="outline">Clear filters</craft-button>
-      </craft-empty>
-    `;
+  args: {
+    label: '',
+    'content-slot': `
+      <p style="font-size: 1.25em; margin-block-end: 0">
+        No entries match your search.
+      </p>
+      <p>Try a different keyword, or clear the filters.</p>
+    `,
+    'default-slot':
+      '<craft-button appearance="outline">Clear filters</craft-button>',
   },
 };
 
+/** The `graphic` slot replaces the icon with artwork of your own. */
 export const CustomGraphic: Story = {
-  render: ({label}) => {
-    return html`
-      <craft-empty label="${label}">
-        <svg
-          slot="graphic"
-          xmlns="http://www.w3.org/2000/svg"
-          fill="none"
-          viewBox="0 0 24 24"
-          stroke-width="1.5"
-          width="48"
-          height="48"
-          stroke="currentColor"
-        >
-          <path
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            d="M20.25 7.5l-.625 10.632a2.25 2.25 0 0 1-2.247 2.118H6.622a2.25 2.25 0 0 1-2.247-2.118L3.75 7.5m8.25 3v6.75m0 0-3-3m3 3 3-3M3.375 7.5h17.25c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125Z"
-          />
-        </svg>
-      </craft-empty>
-    `;
+  args: {
+    icon: '',
+    'graphic-slot': `
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
+        stroke-width="1.5" width="48" height="48" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round"
+          d="M20.25 7.5l-.625 10.632a2.25 2.25 0 0 1-2.247 2.118H6.622a2.25 2.25 0 0 1-2.247-2.118L3.75 7.5m8.25 3v6.75m0 0-3-3m3 3 3-3M3.375 7.5h17.25c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125Z" />
+      </svg>
+    `,
   },
 };
diff --git a/packages/craftcms-ui/src/components/empty/empty.test.ts b/packages/craftcms-ui/src/components/empty/empty.test.ts
new file mode 100644
index 00000000000..68715947267
--- /dev/null
+++ b/packages/craftcms-ui/src/components/empty/empty.test.ts
@@ -0,0 +1,59 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './empty.js';
+import type CraftEmpty from './empty.js';
+
+async function createEmpty(
+  attrs: Record<string, string> = {},
+  innerHTML = ''
+): Promise<CraftEmpty> {
+  const element = document.createElement('craft-empty') as CraftEmpty;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-empty', () => {
+  it('renders the label', async () => {
+    const element = await createEmpty({label: 'Nothing yet.'});
+
+    expect(
+      element.shadowRoot!.querySelector('.label')?.textContent?.trim()
+    ).toBe('Nothing yet.');
+  });
+
+  it('renders an icon when one is named', async () => {
+    const element = await createEmpty({
+      label: 'None',
+      icon: 'magnifying-glass',
+    });
+
+    expect(
+      element.shadowRoot!.querySelector('craft-icon')?.getAttribute('name')
+    ).toBe('magnifying-glass');
+  });
+
+  it('renders no icon when none is named', async () => {
+    const element = await createEmpty({label: 'None'});
+
+    expect(element.shadowRoot!.querySelector('craft-icon')).toBeNull();
+  });
+
+  /** Each slot is a fallback point, so slotting replaces what it defaults to. */
+  it('offers graphic, content, and default slots', async () => {
+    const element = await createEmpty({label: 'None'});
+    const names = [...element.shadowRoot!.querySelectorAll('slot')].map(
+      (slot) => slot.getAttribute('name')
+    );
+
+    expect(names).toEqual(expect.arrayContaining(['graphic', 'content', null]));
+  });
+});
diff --git a/packages/craftcms-ui/src/components/empty/empty.ts b/packages/craftcms-ui/src/components/empty/empty.ts
index 352ec9eb578..0653adba15b 100644
--- a/packages/craftcms-ui/src/components/empty/empty.ts
+++ b/packages/craftcms-ui/src/components/empty/empty.ts
@@ -3,6 +3,17 @@ import {property} from 'lit/decorators.js';
 
 import '../icon/icon';
 
+/**
+ * @summary An empty state: a centred message, an optional graphic, and room
+ * for whatever the person should do next.
+ *
+ * Shown where a list, an index, or a panel has nothing in it — a place that
+ * would otherwise be blank, which reads as broken rather than as empty.
+ *
+ * @slot - Content shown after the message, usually the action to take.
+ * @slot graphic - Artwork shown above the message, replacing the `icon`.
+ * @slot content - The message region, replacing the `label`.
+ */
 export default class CraftEmpty extends LitElement {
   static override styles = [
     css`
@@ -31,7 +42,10 @@ export default class CraftEmpty extends LitElement {
     `,
   ];
 
+  /** The message. Say what is missing, not that something is missing. */
   @property() label: string = '';
+
+  /** Name of an icon shown above the message. */
   @property() icon: string = '';
 
   protected override render() {
diff --git a/packages/craftcms-ui/src/components/field-group/FieldGroup.mdx b/packages/craftcms-ui/src/components/field-group/FieldGroup.mdx
new file mode 100644
index 00000000000..4aadbb88dcd
--- /dev/null
+++ b/packages/craftcms-ui/src/components/field-group/FieldGroup.mdx
@@ -0,0 +1,36 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as FieldGroupStories from './field-group.stories';
+
+<Meta of={FieldGroupStories} name="Docs" />
+
+# Field Group
+
+`<craft-field-group>` lays [Field](?path=/docs/form-controls-field--docs)s out on a twelve-column grid.
+
+<Canvas of={FieldGroupStories.Default} sourceState="shown" />
+
+Children take a full row by default, which is the right default for a form: full-width fields are the easiest to scan down.
+
+## Widths
+
+A `width-*` class on a child gives it a fraction of the row:
+
+<Canvas of={FieldGroupStories.Widths} sourceState="shown" />
+
+The available fractions are `width-25`, `width-33`, `width-50`, `width-66`, and `width-75` — quarters, thirds, and halves of the twelve columns.
+
+## Container Queries, Not Media Queries
+
+The breakpoints respond to the width of the group itself, not the viewport.
+
+That means a group inside a narrow pane stacks even on a wide screen:
+
+<Canvas of={FieldGroupStories.NarrowContainer} sourceState="shown" />
+
+This is what you want for a component that has no idea where it will be placed — a form in a slideout, a modal, or a narrow sidebar gets a sensible layout without anyone configuring it.
+
+Between roughly 25rem and 50rem, `width-25` widens to a half rather than collapsing straight to full, so a row of four short fields becomes two rows of two.
+
+## Properties
+
+<ArgTypes of={FieldGroupStories} />
diff --git a/packages/craftcms-ui/src/components/field-group/field-group.stories.ts b/packages/craftcms-ui/src/components/field-group/field-group.stories.ts
new file mode 100644
index 00000000000..2c287f97a85
--- /dev/null
+++ b/packages/craftcms-ui/src/components/field-group/field-group.stories.ts
@@ -0,0 +1,69 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import {html} from 'lit';
+
+import './field-group.js';
+import type CraftFieldGroup from './field-group.js';
+import '../field/field.js';
+import '../input/input.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `field-group.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftFieldGroup>('craft-field-group');
+
+type CraftFieldGroupArgs = CraftFieldGroup & typeof args;
+
+const meta = {
+  title: 'Form Controls/Field Group',
+  component: 'craft-field-group',
+  args,
+  argTypes,
+} satisfies Meta<CraftFieldGroupArgs>;
+
+export default meta;
+type Story = StoryObj<CraftFieldGroupArgs>;
+
+const field = (label: string, widthClass = '') => html`
+  <craft-field class="${widthClass}">
+    <label slot="label">${label}</label>
+    <craft-input slot="input"></craft-input>
+  </craft-field>
+`;
+
+/** Fields take a full row unless told otherwise. */
+export const Default: Story = {
+  render: () => html`
+    <craft-field-group> ${field('Title')} ${field('Slug')} </craft-field-group>
+  `,
+};
+
+/** A `width-*` class gives a field a fraction of the row. */
+export const Widths: Story = {
+  render: () => html`
+    <craft-field-group>
+      ${field('Title', 'width-50')} ${field('Slug', 'width-50')}
+      ${field('Author', 'width-33')} ${field('Post Date', 'width-33')}
+      ${field('Expiry Date', 'width-33')}
+    </craft-field-group>
+  `,
+};
+
+/**
+ * The breakpoints are container queries, so the same group stacks inside a
+ * narrow container even on a wide screen.
+ */
+export const NarrowContainer: Story = {
+  render: () => html`
+    <div style="width: 22rem; outline: 1px dashed var(--c-color-border-quiet)">
+      <craft-field-group>
+        ${field('Title', 'width-50')} ${field('Slug', 'width-50')}
+      </craft-field-group>
+    </div>
+  `,
+};
diff --git a/packages/craftcms-ui/src/components/field-group/field-group.ts b/packages/craftcms-ui/src/components/field-group/field-group.ts
index ac6480aa885..9a6ea04d9c0 100644
--- a/packages/craftcms-ui/src/components/field-group/field-group.ts
+++ b/packages/craftcms-ui/src/components/field-group/field-group.ts
@@ -1,5 +1,17 @@
 import {html, LitElement} from 'lit';
 
+/**
+ * @summary Lays fields out on a twelve-column grid that collapses as its
+ * container narrows. Children take a full row by default, and a `width-*`
+ * class gives them a fraction of one.
+ *
+ * The breakpoints are container queries rather than media queries, so a group
+ * inside a narrow pane stacks even on a wide screen — the layout follows the
+ * space the fields actually have.
+ *
+ * @slot - The fields to lay out. Add `width-25`, `width-33`, `width-50`,
+ *   `width-66`, or `width-75` to a child to give it a fraction of the row.
+ */
 export default class CraftFieldGroup extends LitElement {
   protected override render() {
     return html`
diff --git a/packages/craftcms-ui/src/components/field/Field.mdx b/packages/craftcms-ui/src/components/field/Field.mdx
new file mode 100644
index 00000000000..0710acfed21
--- /dev/null
+++ b/packages/craftcms-ui/src/components/field/Field.mdx
@@ -0,0 +1,80 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as FieldStories from './field.stories';
+
+<Meta of={FieldStories} name="Docs" />
+
+# Field
+
+`<craft-field>` is the shell that puts Craft's standard field chrome around a control.
+
+<Canvas of={FieldStories.Default} sourceState="shown" />
+
+Label, instructions, tips, warnings, errors, and the status badge all come from the field. The control it wraps supplies only itself.
+
+## What It Does Not Do
+
+The shell never touches the slotted control's value, validation, or events. It provides the chrome and the label/description ARIA wiring, and nothing else.
+
+That is what makes it general: any control can go in the `input` slot — a Craft component, a Lion control, or a plain `<input>` — and get the same field treatment without the field knowing anything about it.
+
+<Canvas of={FieldStories.WithCraftInput} sourceState="shown" />
+
+## Instructions, Tips, and Warnings
+
+Three different things, rendered differently on purpose:
+
+- **`help-text`** — how to fill the field in. Always visible, below the label.
+- **`tip`** — supplementary advice, in an info callout.
+- **`warning`** — a consequence worth knowing before changing the value, in a warning callout.
+
+<Canvas of={FieldStories.RequiredWithInstructions} sourceState="shown" />
+
+<Canvas of={FieldStories.TipAndWarning} sourceState="shown" />
+
+Reach for the plainest one that fits. A page where every field carries a warning has no warnings.
+
+## Errors
+
+<Canvas of={FieldStories.Errors} sourceState="shown" />
+
+Errors render in the `feedback` slot and are wired to the control with `aria-describedby`, so they are announced when the control takes focus rather than only being visible beside it.
+
+## Status and Translation
+
+<Canvas of={FieldStories.StatusBadge} sourceState="shown" />
+
+<Canvas of={FieldStories.Translatable} sourceState="shown" />
+
+The status badge marks a field whose value is outdated or overridden. The translation indicator marks a field whose value is per-site, with `translation-description` explaining the scope.
+
+## Fieldsets
+
+<Canvas of={FieldStories.FieldsetMode} sourceState="shown" />
+
+`fieldset` renders the shell as a `<fieldset>` with a `<legend>` instead of a label bound to one control.
+
+Use it when the field holds several controls that share one question — a group of checkboxes, a date and time pair. A `<label>` can only point at one control, so a group needs a legend.
+
+## Actions
+
+<Canvas of={FieldStories.Actions} sourceState="shown" />
+
+The `actions` slot holds field-level controls: a hide-label toggle, a copy-value button, a settings menu.
+
+`label-extra` does something similar and is **deprecated** — use `actions`.
+
+## Accessibility
+
+The field is where a control's accessible name and description come from, which makes it the single most load-bearing component in a form.
+
+- **Every control in a form belongs in one.** A bare input has no name; wrapping it is the cheapest way to fix that.
+- **Use `fieldset` for groups.** A label pointing at the first of five checkboxes names that checkbox, not the group.
+- **`required` is announced,** not just marked with a symbol — so a person hears the requirement rather than needing to see the asterisk.
+
+<Canvas of={FieldStories.ReadOnly} sourceState="shown" />
+
+<Canvas of={FieldStories.Rtl} sourceState="shown" />
+
+## Properties
+
+<ArgTypes of={FieldStories} />
diff --git a/packages/craftcms-ui/src/components/field/field.stories.ts b/packages/craftcms-ui/src/components/field/field.stories.ts
index 2fe16a11159..a040b694d13 100644
--- a/packages/craftcms-ui/src/components/field/field.stories.ts
+++ b/packages/craftcms-ui/src/components/field/field.stories.ts
@@ -1,36 +1,28 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 import {ifDefined} from 'lit/directives/if-defined.js';
 
 import './field.js';
+import type CraftField from './field.js';
 import '../input/input.js';
 
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `field.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftField>('craft-field');
+
+type CraftFieldArgs = CraftField & typeof args;
+
 const meta = {
-  title: 'Controls/Field',
+  title: 'Form Controls/Field',
   component: 'craft-field',
-  args: {
-    label: 'Field label',
-    helpText: '',
-    required: false,
-    translatable: false,
-    fieldset: false,
-    readOnly: false,
-    disabled: false,
-    status: undefined,
-    statusLabel: undefined,
-    orientation: undefined,
-  },
-  argTypes: {
-    orientation: {
-      control: 'select',
-      options: ['ltr', 'rtl'],
-    },
-    status: {
-      control: 'select',
-      options: ['modified', 'outdated'],
-    },
-  },
+  args: {...args, label: 'Field label', helpText: ''},
+  argTypes,
   render: ({
     label,
     helpText,
@@ -58,10 +50,10 @@ const meta = {
       <input slot="input" type="text" />
     </craft-field>`;
   },
-} satisfies Meta<any>;
+} satisfies Meta<CraftFieldArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftFieldArgs>;
 
 export const Default: Story = {
   args: {},
diff --git a/packages/craftcms-ui/src/components/field/field.ts b/packages/craftcms-ui/src/components/field/field.ts
index 930f881d2ee..6e9c2c835ec 100644
--- a/packages/craftcms-ui/src/components/field/field.ts
+++ b/packages/craftcms-ui/src/components/field/field.ts
@@ -22,7 +22,7 @@ type FormControlTarget = HTMLElement & {
 };
 
 /**
- * A generic form-field shell that renders the standard CP field chrome
+ * @summary A generic form-field shell that renders the standard CP field chrome
  * (label, instructions, tip/warning notices, errors and status badge) around
  * any slotted control, mirroring the server-side field wrapper
  * (`FormFields::fieldHtml()` / `forms/field.blade.php`).
@@ -236,6 +236,10 @@ export default class CraftField extends FormControlMixin(LitElement) {
     super.addToAriaLabelledBy(element, {...customConfig, reorder: false});
   }
 
+  /**
+   * Adds an element to the field's `aria-describedby`, so a control outside
+   * the field can still be described by it.
+   */
   override addToAriaDescribedBy(
     element: HTMLElement,
     customConfig: {idPrefix?: string; reorder?: boolean} = {}
diff --git a/packages/craftcms-ui/src/components/icon/Icon.mdx b/packages/craftcms-ui/src/components/icon/Icon.mdx
new file mode 100644
index 00000000000..c9941ca1ae0
--- /dev/null
+++ b/packages/craftcms-ui/src/components/icon/Icon.mdx
@@ -0,0 +1,60 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as IconStories from './icon.stories';
+
+<Meta of={IconStories} name="Docs" />
+
+# Icon
+
+`<craft-icon>` renders an SVG icon, fetched by name from the control panel's published icon assets.
+
+<Canvas of={IconStories.Default} sourceState="shown" />
+
+It is the icon primitive the rest of the library builds on — buttons, action items, callouts, and chips all render one internally when given an icon name.
+
+## Sizing and Colour
+
+Icons inherit `currentColor` and are sized in `em`, so they take the colour and size of the text around them.
+That is deliberate: an icon beside a label should match that label without either being set explicitly.
+
+<Canvas of={IconStories.InheritsText} sourceState="shown" />
+
+To change an icon's size, change the font size of what contains it.
+
+## Naming an Icon
+
+`name` resolves against a `family` and a `variant`, defaulting to `classic` and `solid` — the set the control panel's own icons come from.
+
+A name that does not resolve leaves the icon empty rather than rendering a placeholder, and logs the failure. Check the name against the icon set if one goes missing.
+
+## Your Own Artwork
+
+Slot an `<svg>` to render something the icon set does not cover:
+
+<Canvas of={IconStories.SlottedSvg} sourceState="shown" />
+
+Slotted content wins: while the slot has content, no named icon is fetched. Give the SVG `fill="none"` and `stroke="currentColor"` if you want it to inherit colour the way a named icon does.
+
+## Badges
+
+`appearance="badge"` draws the icon on a coloured disc, for a marker that has to read as a status rather than as decoration:
+
+<Canvas of={IconStories.Badge} sourceState="shown" />
+
+It defaults the disc to the warning colour. Set `data-color` for any other.
+
+## Accessibility
+
+**An icon is decorative unless you say otherwise.** Without a `label` it is `aria-hidden`, so it adds nothing to what a screen reader announces:
+
+<Canvas of={IconStories.Labelled} sourceState="shown" />
+
+Setting `label` makes it `role="img"` with that accessible name.
+
+The rule of thumb is what the icon sits beside:
+
+- **Beside text that already says it** — leave the label off. A trash icon next to the word "Delete" announced as "Delete Delete" is worse than one that is silent.
+- **On its own** — it needs a label, because nothing else names it. This is the usual case inside an icon-only button.
+
+## Properties
+
+<ArgTypes of={IconStories} />
diff --git a/packages/craftcms-ui/src/components/icon/icon.stories.ts b/packages/craftcms-ui/src/components/icon/icon.stories.ts
index 7956f66d88e..95481d71e41 100644
--- a/packages/craftcms-ui/src/components/icon/icon.stories.ts
+++ b/packages/craftcms-ui/src/components/icon/icon.stories.ts
@@ -1,32 +1,94 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './icon.js';
+import type CraftIcon from './icon.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `icon.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftIcon>('craft-icon');
+
+type IconArgs = CraftIcon & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Icon',
   component: 'craft-icon',
-  args: {
-    iconId: 'chevron-down',
-  },
-  render: function ({iconId}) {
-    return html`<craft-icon name="${iconId}"></craft-icon>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, name: 'chevron-down'},
+  argTypes,
+  // Render from args alone so every control drives the story.
+  render: (args) => template(args),
+} satisfies Meta<IconArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<IconArgs>;
+
+/** An icon named from the CP's published icon set. */
+export const Default: Story = {};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+/**
+ * Icons inherit `currentColor` and are sized in `em`, so they take the colour
+ * and size of the text around them rather than needing either set.
+ */
+export const InheritsText: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      <p style="margin: 0">
+        Default size <craft-icon name="star"></craft-icon>
+      </p>
+      <p style="margin: 0; font-size: 1.5rem">
+        Larger text <craft-icon name="star"></craft-icon>
+      </p>
+      <p style="margin: 0; color: var(--c-color-danger-on-normal)">
+        Coloured text <craft-icon name="star"></craft-icon>
+      </p>
+    </div>
+  `,
+};
+
+/**
+ * `label` gives the icon an accessible name and makes it `role="img"`. Without
+ * one it is `aria-hidden`, which is what you want beside text that already
+ * says the same thing.
+ */
+export const Labelled: Story = {
+  args: {name: 'circle-exclamation', label: 'Warning'},
+};
+
+/**
+ * `appearance="badge"` draws the icon on a coloured disc, for a marker that
+ * has to read as a status. `data-color` picks the colour.
+ */
+export const Badge: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; gap: 0.75rem; align-items: center">
+      <craft-icon name="circle-exclamation" appearance="badge"></craft-icon>
+      <craft-icon
+        name="circle-check"
+        appearance="badge"
+        data-color="success"
+      ></craft-icon>
+      <craft-icon
+        name="triangle-exclamation"
+        appearance="badge"
+        data-color="danger"
+      ></craft-icon>
+    </div>
+  `,
 };
 
-// Render a custom inline SVG via the default slot. When the slot has content,
-// the slotted SVG is shown instead of the name-based icon.
+/**
+ * Slot your own `<svg>` when the icon set does not cover what you need. The
+ * named icon is not fetched while the slot has content.
+ */
 export const SlottedSvg: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
     <craft-icon>
       <svg
diff --git a/packages/craftcms-ui/src/components/icon/icon.ts b/packages/craftcms-ui/src/components/icon/icon.ts
index db892548fa1..7695234e180 100644
--- a/packages/craftcms-ui/src/components/icon/icon.ts
+++ b/packages/craftcms-ui/src/components/icon/icon.ts
@@ -10,20 +10,31 @@ import {property, state} from 'lit/decorators.js';
 import {resolveIcon} from '../../utilities/icons.js';
 
 /**
- * craft-icon renders an SVG icon fetched from the CP's published icon assets
- * (see `getIconUrl` for the URL contract).
+ * @summary An SVG icon, fetched by name from the CP's published icon assets.
+ * Icons inherit `currentColor` and size with the surrounding text, so they sit
+ * in a label or a button without being sized by hand.
  *
- * In addition to name-based rendering, you may pass an inline `<svg>` (or
- * other element) into the default slot to render your own icon. When the slot
- * has assigned content, the slotted markup is rendered and the fetched
- * (name-based) icon is suppressed.
+ * Slot your own `<svg>` instead of naming one when the icon set does not cover
+ * what you need — slotted content takes over and the named icon is not
+ * fetched.
+ *
+ * An icon is decorative unless you say otherwise: without a `label` it is
+ * `aria-hidden`, and with one it becomes `role="img"` with that name. Icon-only
+ * buttons need the label; an icon beside text does not.
+ *
+ * @slot - Your own icon markup, used in place of the named one.
  */
 export default class CraftIcon extends LitElement {
   /** Icon name, optionally prefixed with a variant (e.g. `custom-icons/foo`). */
   @property({reflect: true}) name?: string;
 
+  /**
+   * Icon family to resolve the name against. Defaults to `classic`, which is
+   * what the CP's own icons use.
+   */
   @property({reflect: true}) family?: string;
 
+  /** Weight within the family. Defaults to `solid`. */
   @property({reflect: true}) variant?: string;
 
   /**
@@ -32,6 +43,11 @@ export default class CraftIcon extends LitElement {
    */
   @property() label?: string;
 
+  /**
+   * `badge` draws the icon on a coloured disc, for a marker that has to read
+   * as a status rather than as decoration. It defaults the disc to the warning
+   * colour; set `data-color` for another.
+   */
   @property({reflect: true}) appearance?: 'plain' | 'badge' = 'plain';
 
   @state() private _svg: TemplateResult | typeof nothing = nothing;
diff --git a/packages/craftcms-ui/src/components/indicator/Indicator.mdx b/packages/craftcms-ui/src/components/indicator/Indicator.mdx
index 0e3c6f1e3b3..5be6c39bb39 100644
--- a/packages/craftcms-ui/src/components/indicator/Indicator.mdx
+++ b/packages/craftcms-ui/src/components/indicator/Indicator.mdx
@@ -1,11 +1,7 @@
-import {Canvas, Meta} from '@storybook/addon-docs/blocks';
-import IndicatorMeta, {
-  ArbitraryColor,
-  ArbitrarySize,
-  Default,
-} from './indicator.stories';
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as IndicatorStories from './indicator.stories';
 
-<Meta of={IndicatorMeta} name="Docs" />
+<Meta of={IndicatorStories} name="Docs" />
 
 # Indicator
 
@@ -13,7 +9,7 @@ import IndicatorMeta, {
 object — for example, the live/draft state of an entry or a "has updates" marker
 in a list.
 
-<Canvas of={Default} />
+<Canvas of={IndicatorStories.Default} />
 
 ## Usage
 
@@ -24,92 +20,6 @@ in a list.
 The element renders a single `role="img"` dot. It has no slot — all of its
 appearance is driven by attributes.
 
-## Properties
-
-<table>
-  <thead>
-    <tr>
-      <th>Property</th>
-      <th>Attribute</th>
-      <th>Type</th>
-      <th>Default</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <code>fill</code>
-      </td>
-      <td>
-        <code>fill</code>
-      </td>
-      <td>
-        <code>string</code>
-      </td>
-      <td>
-        <code>var(--c-color-fill-loud)</code>
-      </td>
-      <td>
-        The dot color. Accepts a semantic keyword (see below) or any CSS color.
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <code>appearance</code>
-      </td>
-      <td>
-        <code>appearance</code>
-      </td>
-      <td>
-        <code>'solid' | 'outline' | 'outline-fill'</code>
-      </td>
-      <td>
-        <code>'outline-fill'</code>
-      </td>
-      <td>
-        How the dot is drawn — see <a href="#appearance">Appearance</a>.
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <code>size</code>
-      </td>
-      <td>
-        <code>size</code>
-      </td>
-      <td>
-        <code>'md' | 'lg'</code>
-      </td>
-      <td>
-        <code>'md'</code>
-      </td>
-      <td>
-        <code>md</code> ≈ 0.6em, <code>lg</code> ≈ 1em. Scales with the
-        surrounding font size.
-      </td>
-    </tr>
-    <tr>
-      <td>
-        <code>label</code>
-      </td>
-      <td>
-        <code>label</code>
-      </td>
-      <td>
-        <code>string | null</code>
-      </td>
-      <td>
-        <code>null</code>
-      </td>
-      <td>
-        Accessible name, exposed as <code>aria-label</code>. Provide it for
-        non-decorative dots.
-      </td>
-    </tr>
-  </tbody>
-</table>
-
 ## Fill
 
 `fill` sets the dot's color. A recognized **status variant** (`default`,
@@ -123,42 +33,15 @@ verbatim.
 Prefer the variant and swatch names so indicators stay consistent with the rest
 of the palette; reach for an arbitrary value only when a color falls outside it.
 
-<Canvas of={ArbitraryColor} />
+<Canvas of={IndicatorStories.ArbitraryColor} />
 
 ## Appearance
 
 `appearance` controls how the dot is drawn:
 
-<table>
-  <thead>
-    <tr>
-      <th>Value</th>
-      <th>Renders</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <code>outline-fill</code> (default)
-      </td>
-      <td>Filled dot with a subtle dark outline.</td>
-    </tr>
-    <tr>
-      <td>
-        <code>solid</code>
-      </td>
-      <td>Filled dot with no outline.</td>
-    </tr>
-    <tr>
-      <td>
-        <code>outline</code>
-      </td>
-      <td>
-        Hollow dot — a 2px ring in the fill color over a transparent center.
-      </td>
-    </tr>
-  </tbody>
-</table>
+- `outline-fill` (default) — filled dot with a subtle dark outline.
+- `solid` — filled dot with no outline.
+- `outline` — hollow dot: a 2px ring in the fill colour over a transparent centre.
 
 ## Sizing
 
@@ -166,7 +49,7 @@ of the palette; reach for an arbitrary value only when a color falls outside it.
 `em`, the dot scales with the font size of its container — set `font-size` on a
 wrapper to fine-tune it.
 
-<Canvas of={ArbitrarySize} />
+<Canvas of={IndicatorStories.ArbitrarySize} />
 
 ## Accessibility
 
@@ -188,3 +71,7 @@ craft-indicator {
   font-size: 1.25rem;
 }
 ```
+
+## Properties
+
+<ArgTypes of={IndicatorStories} />
diff --git a/packages/craftcms-ui/src/components/indicator/indicator.stories.ts b/packages/craftcms-ui/src/components/indicator/indicator.stories.ts
index a8e30dce3e3..7dcef97f0ca 100644
--- a/packages/craftcms-ui/src/components/indicator/indicator.stories.ts
+++ b/packages/craftcms-ui/src/components/indicator/indicator.stories.ts
@@ -1,300 +1,120 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html, nothing} from 'lit';
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './indicator.js';
 import type CraftIndicator from './indicator.js';
 import {Variant} from '@src/constants/variants';
-
-const appearances = ['outline-fill', 'solid', 'outline'];
+import {colors} from '@src/constants/colors';
 
 /**
- * Renders the indicator in each appearance, with a label, so every story shares
- * the same markup.
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `indicator.ts` surfaces it here without touching this file.
  */
-const renderIndicators = (
-  label: string,
-  attrs: {fill?: string; size?: CraftIndicator['size']} = {}
-) => html`
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftIndicator>('craft-indicator');
+
+type IndicatorArgs = CraftIndicator & typeof args;
+
+const APPEARANCES = ['solid', 'outline-fill', 'outline'] as const;
+
+/** One row of the appearance matrix, so every grid story shares its markup. */
+const row = (label: string, attrs: {fill?: string; size?: string}) => html`
   <tr>
-    <td>${label}</td>
-    ${appearances.map(
+    <td style="padding-inline-end: 1rem; font-size: 0.8rem">${label}</td>
+    ${APPEARANCES.map(
       (appearance) => html`
-        <td>
+        <td style="padding: 0.25rem 0.75rem">
           <craft-indicator
-            fill="${attrs.fill ?? nothing}"
-            size="${attrs.size ?? nothing}"
+            fill="${attrs.fill ?? 'var(--c-color-fill-loud)'}"
+            size="${attrs.size ?? 'md'}"
             appearance="${appearance}"
+            label="${label} ${appearance}"
           ></craft-indicator>
         </td>
       `
     )}
   </tr>
 `;
-type ColorGroup = string;
-type Volume = string;
-
-const SWATCH_COLORS: ColorGroup[] = [
-  'red',
-  'orange',
-  'amber',
-  'yellow',
-  'lime',
-  'green',
-  'emerald',
-  'teal',
-  'cyan',
-  'sky',
-  'blue',
-  'indigo',
-  'violet',
-  'purple',
-  'fuchsia',
-  'pink',
-  'rose',
-  'gray',
-];
 
-const VOLUMES: Volume[] = ['quiet', 'normal', 'loud'];
+const matrix = (rows: unknown) => html`
+  <table>
+    <thead>
+      <tr>
+        <td></td>
+        ${APPEARANCES.map(
+          (appearance) =>
+            html`<th style="font-size: 0.75rem; font-weight: 500">
+              ${appearance}
+            </th>`
+        )}
+      </tr>
+    </thead>
+    <tbody>
+      ${rows}
+    </tbody>
+  </table>
+`;
 
 const meta = {
   title: 'Components/Indicator',
   component: 'craft-indicator',
-  args: {},
-  render: () => html`
-    <table>
-      <thead>
-        <td></td>
-        ${appearances.map((appearance) => html`<th>${appearance}</th>`)}
-      </thead>
-      <tbody>
-        ${Object.values(Variant).map((variant) =>
-          renderIndicators(variant, {fill: variant})
-        )}
-      </tbody>
-    </table>
-  `,
-} satisfies Meta<CraftIndicator>;
+  args: {...args, label: 'Live'},
+  argTypes,
+  // Render from args alone so every control drives the story. The grid stories
+  // below vary the markup instead, and disable the controls that no longer
+  // reach them.
+  render: (args) => template(args),
+} satisfies Meta<IndicatorArgs>;
 
 export default meta;
-type Story = StoryObj<CraftIndicator>;
+type Story = StoryObj<IndicatorArgs>;
 
-/** All semantic variants side by side at their default (`normal`) volume. */
-export const Default: Story = {
-  name: 'Semantic variants',
-  render: () => html`
-    <div style="display:flex;gap:0.5rem;align-items:center">
-      ${Object.values(Variant).map(
-        (variant) =>
-          html`<craft-indicator
-            variant="${variant}"
-            label="${variant}"
-          ></craft-indicator>`
-      )}
-      <craft-indicator variant="empty" label="empty"></craft-indicator>
-    </div>
-  `,
-};
+/** A single dot, driven by the controls. */
+export const Default: Story = {};
 
 /**
- * The `volume` property controls color intensity. `quiet` renders a subtle tint,
- * `normal` a mid-tone fill, and `loud` a fully saturated fill with high contrast text.
+ * `fill` takes a status variant, which resolves to that variant's fill token.
  */
-export const VolumeVariants: Story = {
-  name: 'Volume',
-  render: () => html`
-    <div style="display:flex;flex-direction:column;gap:0.75rem">
-      ${VOLUMES.map(
-        (volume) => html`
-          <div style="display:flex;gap:0.5rem;align-items:center">
-            <span
-              style="width:3.5rem;font-size:0.75rem;color:var(--c-text-muted)"
-              >${volume}</span
-            >
-            ${Object.values(Variant).map(
-              (variant) => html`
-                <craft-indicator
-                  variant="${variant}"
-                  volume="${volume}"
-                  label="${variant} ${volume}"
-                ></craft-indicator>
-              `
-            )}
-          </div>
-        `
-      )}
-    </div>
-  `,
+export const Variants: Story = {
+  parameters: {controls: {disable: true}},
+  render: () =>
+    matrix(
+      Object.values(Variant).map((variant) => row(variant, {fill: variant}))
+    ),
 };
 
-/**
- * Use `variant="swatch"` with the `swatch` attribute to pick any named color from the
- * design system's colorable palette. The `volume` property controls the intensity.
- */
-export const SwatchVariant: Story = {
-  name: 'Swatch',
-  render: () => html`
-    <div style="display:flex;flex-direction:column;gap:0.5rem">
-      <div style="display:flex;gap:0.5rem;margin-bottom:0.25rem">
-        <span style="width:5rem"></span>
-        ${VOLUMES.map(
-          (v) =>
-            html`<span
-              style="width:1.5rem;font-size:0.7rem;color:var(--c-text-muted);text-align:center"
-              >${v}</span
-            >`
-        )}
-      </div>
-      ${SWATCH_COLORS.map(
-        (color) => html`
-          <div style="display:flex;gap:0.5rem;align-items:center">
-            <span style="width:5rem;font-size:0.75rem;color:var(--c-text-muted)"
-              >${color}</span
-            >
-            ${VOLUMES.map(
-              (volume) => html`
-                <craft-indicator
-                  variant="swatch"
-                  swatch="${color}"
-                  volume="${volume}"
-                  label="${color} ${volume}"
-                  style="width:1.5rem"
-                ></craft-indicator>
-              `
-            )}
-          </div>
-        `
-      )}
-    </div>
-  `,
+/** `fill` also takes any palette swatch by name. */
+export const Swatches: Story = {
+  parameters: {controls: {disable: true}},
+  render: () =>
+    matrix(colors.slice(0, 8).map((color) => row(color, {fill: color}))),
 };
 
 /**
- * Use `variant="custom"` with the `color` attribute to set the indicator to any CSS
- * `background` value. This accepts hex, rgb, hsl, named colors, and gradients —
- * useful for user-defined or data-driven colors.
+ * Anything the browser accepts as a colour works too — a hex value, an `rgba()`,
+ * even a gradient. Prefer the variant and swatch names, which stay in step with
+ * the rest of the palette.
  */
-export const CustomVariant: Story = {
-  name: 'Custom color',
-  render: () => html`
-    <div style="display:flex;flex-direction:column;gap:0.75rem">
-      <div>
-        <p
-          style="font-size:0.75rem;color:var(--c-text-muted);margin-bottom:0.5rem"
-        >
-          Hex colors
-        </p>
-        <div style="display:flex;gap:0.5rem;align-items:center">
-          <craft-indicator
-            variant="custom"
-            color="#e74c3c"
-            label="red"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="#e67e22"
-            label="orange"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="#f1c40f"
-            label="yellow"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="#2ecc71"
-            label="green"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="#3498db"
-            label="blue"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="#9b59b6"
-            label="purple"
-          ></craft-indicator>
-        </div>
-      </div>
-      <div>
-        <p
-          style="font-size:0.75rem;color:var(--c-text-muted);margin-bottom:0.5rem"
-        >
-          Gradients
-        </p>
-        <div style="display:flex;gap:0.5rem;align-items:center">
-          <craft-indicator
-            variant="custom"
-            color="linear-gradient(135deg, #e74c3c, #9b59b6)"
-            label="red to purple"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="linear-gradient(135deg, #3498db, #2ecc71)"
-            label="blue to green"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="linear-gradient(135deg, red, orange, yellow, green, blue, indigo, violet)"
-            label="rainbow"
-          ></craft-indicator>
-          <craft-indicator
-            variant="custom"
-            color="conic-gradient(red, orange, yellow, green, blue, indigo, violet, red)"
-            label="conic rainbow"
-          ></craft-indicator>
-        </div>
-      </div>
-    </div>
-  `,
-};
-
-/** Interactive story with Storybook controls for exploring all properties. */
-export const Playground: Story = {
-  name: 'Playground',
-  args: {
-    fill: 'violet',
-    size: 'md',
-  },
-};
-
-const arbitraryValues = [
-  '#2c61de',
-  'rgba(30, 40, 40, 0.2)',
-  'linear-gradient(red, blue)',
-];
-
 export const ArbitraryColor: Story = {
-  render: () => html`
-    <table>
-      <thead>
-        <td></td>
-        ${appearances.map((appearance) => html`<th>${appearance}</th>`)}
-      </thead>
-      <tbody>
-        ${arbitraryValues.map((value) =>
-          renderIndicators(value, {fill: value})
-        )}
-      </tbody>
-    </table>
-  `,
+  parameters: {controls: {disable: true}},
+  render: () =>
+    matrix(
+      ['#2c61de', 'rgba(30, 40, 40, 0.2)', 'linear-gradient(red, blue)'].map(
+        (value) => row(value, {fill: value})
+      )
+    ),
 };
 
-const sizes: Array<CraftIndicator['size']> = ['md', 'lg'];
-
+/** `size` steps the dot between the two sizes it ships with. */
 export const ArbitrarySize: Story = {
-  render: () => html`
-    <table>
-      <thead>
-        <td></td>
-        ${appearances.map((appearance) => html`<th>${appearance}</th>`)}
-      </thead>
-      <tbody>
-        ${sizes.map((size) =>
-          renderIndicators(size === 'md' ? 'md (default)' : size, {size})
-        )}
-      </tbody>
-    </table>
-  `,
+  parameters: {controls: {disable: true}},
+  render: () =>
+    matrix(
+      (['md', 'lg'] as const).map((size) =>
+        row(size === 'md' ? 'md (default)' : size, {size})
+      )
+    ),
 };
diff --git a/packages/craftcms-ui/src/components/indicator/indicator.test.ts b/packages/craftcms-ui/src/components/indicator/indicator.test.ts
new file mode 100644
index 00000000000..46dd40921a3
--- /dev/null
+++ b/packages/craftcms-ui/src/components/indicator/indicator.test.ts
@@ -0,0 +1,78 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './indicator.js';
+import type CraftIndicator from './indicator.js';
+
+async function createIndicator(
+  attrs: Record<string, string> = {}
+): Promise<CraftIndicator> {
+  const element = document.createElement('craft-indicator') as CraftIndicator;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function dot(element: CraftIndicator): HTMLElement {
+  return element.shadowRoot!.querySelector('.indicator')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-indicator', () => {
+  it('renders a dot', async () => {
+    expect(dot(await createIndicator())).toBeTruthy();
+  });
+
+  /** A recognised variant resolves to that variant's fill token. */
+  it('resolves a status variant to its token', async () => {
+    const element = await createIndicator({fill: 'success'});
+
+    expect(dot(element).getAttribute('style')).toContain(
+      'var(--c-color-success-fill-loud)'
+    );
+  });
+
+  /** So does a palette swatch, which is the same lookup. */
+  it('resolves a palette swatch to its token', async () => {
+    const element = await createIndicator({fill: 'red'});
+
+    expect(dot(element).getAttribute('style')).toContain(
+      'var(--c-color-red-fill-loud)'
+    );
+  });
+
+  /** Anything else is passed through as a CSS colour. */
+  it('passes an arbitrary colour straight through', async () => {
+    const element = await createIndicator({fill: '#2c61de'});
+
+    expect(dot(element).getAttribute('style')).toContain('#2c61de');
+  });
+
+  it('marks the outline appearance with a modifier class', async () => {
+    const element = await createIndicator({appearance: 'outline'});
+
+    expect(dot(element).classList.contains('indicator--outline')).toBe(true);
+  });
+
+  /**
+   * An unlabelled dot is decoration beside the thing it marks, so it is not
+   * announced as an unnamed image.
+   */
+  it('is not an image without a label', async () => {
+    const element = await createIndicator();
+
+    expect(dot(element).getAttribute('role')).toBeNull();
+  });
+
+  it('becomes a named image once it has a label', async () => {
+    const element = await createIndicator({label: 'Online'});
+
+    expect(dot(element).getAttribute('role')).toBe('img');
+    expect(dot(element).getAttribute('aria-label')).toBe('Online');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/indicator/indicator.ts b/packages/craftcms-ui/src/components/indicator/indicator.ts
index 6e9fc4ac3ea..e80b4500147 100644
--- a/packages/craftcms-ui/src/components/indicator/indicator.ts
+++ b/packages/craftcms-ui/src/components/indicator/indicator.ts
@@ -7,9 +7,11 @@ import {variants} from '@src/constants/variants';
 import {Appearance} from '@src/constants/appearances';
 
 /**
- * @summary Indicators are used to visually represent the status of an object.
- * Most of the time, you won't want to use the component directly but instead
- * should use one of the status components.
+ * @summary A small dot representing the status of an object.
+ *
+ * Most of the time you want `craft-status`, which covers the fixed vocabulary
+ * of object states. Reach for this when the dot means something that
+ * vocabulary does not cover, since it takes any palette colour or CSS colour.
  *
  * @since 1.0
  */
@@ -50,20 +52,41 @@ export default class CraftIndicator extends LitElement {
     `,
   ];
 
+  /**
+   * Dot size. Both are defined in `em`, so either scales with the surrounding
+   * font size — set `font-size` on the host to fine-tune.
+   */
   @property()
   size: 'md' | 'lg' = 'md';
 
-  /** @phpType {Color|string} */
+  /**
+   * The dot's colour. A status variant (`success`, `warning`, `danger`,
+   * `info`) or a palette swatch resolves to the matching `--c-color-*` token;
+   * any other value — a hex code, `rgb()`, a custom property — is used
+   * verbatim.
+   *
+   * @phpType {Color|string}
+   */
   @property({reflect: true})
   fill: string = 'var(--c-color-fill-loud)';
 
+  /**
+   * Accessible name, exposed as `aria-label`. Set it whenever the dot is not
+   * purely decorative — a status conveyed by colour alone is conveyed to
+   * nobody who cannot see it.
+   */
   @property()
   label: string | null = null;
 
+  /**
+   * How the dot is drawn: `outline-fill` is filled with a subtle outline,
+   * `solid` is filled with none, and `outline` is a hollow ring over a
+   * transparent centre.
+   */
   @property({reflect: true})
   appearance: 'solid' | 'outline-fill' | 'outline' = Appearance.OutlineFill;
 
-  getFill() {
+  protected getFill() {
     // If the fill is known swatch
     if ((colors as string[]).includes(this.fill)) {
       return `var(--c-color-${this.fill}-fill-loud)`;
@@ -77,7 +100,7 @@ export default class CraftIndicator extends LitElement {
     return this.fill;
   }
 
-  getSize() {
+  protected getSize() {
     switch (this.size) {
       case 'md':
         return '0.6em';
diff --git a/packages/craftcms-ui/src/components/info-icon/InfoIcon.mdx b/packages/craftcms-ui/src/components/info-icon/InfoIcon.mdx
new file mode 100644
index 00000000000..67d5ac2eebf
--- /dev/null
+++ b/packages/craftcms-ui/src/components/info-icon/InfoIcon.mdx
@@ -0,0 +1,45 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InfoIconStories from './info-icon.stories';
+
+<Meta of={InfoIconStories} name="Docs" />
+
+# Info Icon
+
+`<craft-info-icon>` is a small button that reveals explanatory text in a tooltip.
+
+<Canvas of={InfoIconStories.Default} sourceState="shown" />
+
+Reach for it when a detail helps but should not take up room beside the thing it explains — the definition of a setting, the consequence of an option, the format a field expects.
+
+<Canvas of={InfoIconStories.InContext} sourceState="shown" />
+
+If the explanation is something a person needs _before_ acting rather than on demand, put it in the field's help text instead. An info icon is for the second question, not the first.
+
+## Behaviour
+
+The tooltip opens on **click**, not hover.
+That is deliberate: hover text cannot be reached without a pointer, and it disappears the moment attention moves, which is the wrong trade for text meant to be read.
+
+Only one info icon is open at a time — opening one closes any other:
+
+<Canvas of={InfoIconStories.OnlyOneOpen} sourceState="shown" />
+
+## Appearance
+
+`icon` changes the marker when the default circle is not right — a lightbulb for a tip rather than a definition, say:
+
+<Canvas of={InfoIconStories.CustomIcon} sourceState="shown" />
+
+<Canvas of={InfoIconStories.Disabled} sourceState="shown" />
+
+## Accessibility
+
+The trigger is a real button with an accessible name from `label`, defaulting to a translated "More Info".
+
+Give it a more specific name when the page has several, so they are distinguishable in a list of controls: "More info about propagation" tells a screen reader user which one they have landed on, where three identical "More Info" buttons do not.
+
+The `id` ties the tooltip to its button, and is generated when you do not supply one — so a page can hold many info icons without collisions.
+
+## Properties
+
+<ArgTypes of={InfoIconStories} />
diff --git a/packages/craftcms-ui/src/components/info-icon/info-icon.stories.ts b/packages/craftcms-ui/src/components/info-icon/info-icon.stories.ts
index ddafb966981..74742f7066e 100644
--- a/packages/craftcms-ui/src/components/info-icon/info-icon.stories.ts
+++ b/packages/craftcms-ui/src/components/info-icon/info-icon.stories.ts
@@ -1,35 +1,71 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
-import './info-icon';
+
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import './info-icon.js';
+import type CraftInfoIcon from './info-icon.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftInfoIcon>('craft-info-icon');
+
+type InfoIconArgs = CraftInfoIcon & typeof args;
 
-const meta: Meta = {
+const meta = {
   title: 'Components/Info Icon',
-  tags: ['autodocs'],
-  args: {},
-  render: (args) => {
-    return html`<craft-info-icon>
-      This is the content for the tooltip
-    </craft-info-icon>`;
+  component: 'craft-info-icon',
+  args: {
+    ...args,
+    'default-slot':
+      'Entries in this section are only available on the sites you select.',
   },
-};
+  argTypes,
+  parameters: {layout: 'centered'},
+  render: (args) => template(args),
+} satisfies Meta<InfoIconArgs>;
 
 export default meta;
+type Story = StoryObj<InfoIconArgs>;
 
-type Story = StoryObj<any>;
+/** Click the icon to reveal the explanation. */
+export const Default: Story = {};
 
-export const Default: Story = {
-  args: {
-    label: 'More Info',
-    icon: 'circle-info',
-  },
+/** `icon` picks a different marker when the default is not the right one. */
+export const CustomIcon: Story = {
+  args: {icon: 'lightbulb', 'default-slot': 'A tip rather than a definition.'},
 };
 
-export const Multiple: Story = {
-  render: () => {
-    return html`<div style="display: flex; gap: 2rem; align-items: center;">
-      <craft-info-icon>Tooltip content for icon 1</craft-info-icon>
-      <craft-info-icon>Tooltip content for icon 2</craft-info-icon>
-      <craft-info-icon>Tooltip content for icon 3</craft-info-icon>
-    </div>`;
-  },
+/** `disabled` stops the tooltip being opened. */
+export const Disabled: Story = {
+  args: {disabled: true},
+};
+
+/** Opening one info icon closes any other, so tooltips never accumulate. */
+export const OnlyOneOpen: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; gap: 1.5rem">
+      <craft-info-icon>The first explanation.</craft-info-icon>
+      <craft-info-icon>The second explanation.</craft-info-icon>
+      <craft-info-icon>The third explanation.</craft-info-icon>
+    </div>
+  `,
+};
+
+/** Beside the thing it explains, which is where it usually sits. */
+export const InContext: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <span style="display: inline-flex; align-items: center; gap: 0.25rem">
+      Propagation Method
+      <craft-info-icon>
+        How content is carried across the sites in this group when an entry is
+        saved.
+      </craft-info-icon>
+    </span>
+  `,
 };
diff --git a/packages/craftcms-ui/src/components/info-icon/info-icon.test.ts b/packages/craftcms-ui/src/components/info-icon/info-icon.test.ts
new file mode 100644
index 00000000000..d9985cb94dd
--- /dev/null
+++ b/packages/craftcms-ui/src/components/info-icon/info-icon.test.ts
@@ -0,0 +1,78 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './info-icon.js';
+import type CraftInfoIcon from './info-icon.js';
+
+async function createInfoIcon(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Shown in the entry index.'
+): Promise<CraftInfoIcon> {
+  const element = document.createElement('craft-info-icon') as CraftInfoIcon;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function icon(element: CraftInfoIcon): Element {
+  return element.shadowRoot!.querySelector('craft-icon')!;
+}
+
+function tooltip(element: CraftInfoIcon): Element {
+  return element.shadowRoot!.querySelector('craft-tooltip')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-info-icon', () => {
+  it('renders a button carrying the icon', async () => {
+    const element = await createInfoIcon();
+
+    expect(element.shadowRoot!.querySelector('craft-button')).toBeTruthy();
+    expect(icon(element).getAttribute('name')).toBe('circle-info');
+  });
+
+  it('takes an icon of its own', async () => {
+    const element = await createInfoIcon({icon: 'triangle-exclamation'});
+
+    expect(icon(element).getAttribute('name')).toBe('triangle-exclamation');
+  });
+
+  /**
+   * The button holds only an icon, so the name has to come from the icon's
+   * label — without it the control is announced as an unnamed button.
+   */
+  it('names the icon-only button', async () => {
+    const element = await createInfoIcon();
+
+    expect(icon(element).getAttribute('label')).toBeTruthy();
+  });
+
+  it('takes a label of its own', async () => {
+    const element = await createInfoIcon({label: 'What is this?'});
+
+    expect(icon(element).getAttribute('label')).toBe('What is this?');
+  });
+
+  /** The tooltip has to point at the button that opens it. */
+  it('wires the tooltip to the button', async () => {
+    const element = await createInfoIcon();
+    const button = element.shadowRoot!.querySelector('craft-button')!;
+
+    expect(element.id).not.toBe('');
+    expect(button.id).toBe(element.id);
+    expect(tooltip(element).getAttribute('for')).toBe(element.id);
+  });
+
+  it('holds its content in the tooltip', async () => {
+    const element = await createInfoIcon();
+
+    expect(tooltip(element).querySelector('slot')).toBeTruthy();
+    expect(element.textContent).toBe('Shown in the entry index.');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/info-icon/info-icon.ts b/packages/craftcms-ui/src/components/info-icon/info-icon.ts
index 1619fc0e4d8..f859b59ec48 100644
--- a/packages/craftcms-ui/src/components/info-icon/info-icon.ts
+++ b/packages/craftcms-ui/src/components/info-icon/info-icon.ts
@@ -1,13 +1,25 @@
 import {t} from '@src/utilities/translate';
 import {css, html, LitElement} from 'lit';
-import {property, query, queryAssignedElements, state} from 'lit/decorators.js';
+import {property, query} from 'lit/decorators.js';
 
 import '../button/button';
 import '../icon/icon';
 import '../tooltip/tooltip';
 import type CraftTooltip from '../tooltip/tooltip';
-import '../visually-hidden/visually-hidden';
 
+/**
+ * @summary A small "more info" button that reveals explanatory text in a
+ * tooltip. Use it for a detail that helps but should not take up room beside
+ * the thing it explains.
+ *
+ * Only one info icon is open at a time — opening one closes any other, so the
+ * page never accumulates tooltips.
+ *
+ * The tooltip opens on click rather than hover, so the text is reachable
+ * without a pointer and stays put long enough to read.
+ *
+ * @slot - The explanatory text shown in the tooltip.
+ */
 export default class CraftInfoIcon extends LitElement {
   static override styles = css`
     :host {
@@ -17,17 +29,22 @@ export default class CraftInfoIcon extends LitElement {
 
   static #openInstance: CraftInfoIcon | null = null;
 
+  /** Accessible name for the button that opens the tooltip. */
   @property() label = t('More Info');
 
+  /** Name of the icon shown on the button. */
   @property() icon = 'circle-info';
 
+  /** Prevents the tooltip from being opened. */
   @property({type: Boolean, reflect: true}) disabled = false;
 
+  /**
+   * Id of the host, used to tie the tooltip to its button. Generated when not
+   * supplied, so a page can hold many info icons without collisions.
+   */
   @property() override id: string;
 
-  @state() status = '';
-
-  @query('craft-tooltip') tooltip!: HTMLElement;
+  @query('craft-tooltip') protected tooltip!: HTMLElement;
 
   #eventController = new AbortController();
 
@@ -63,24 +80,12 @@ export default class CraftInfoIcon extends LitElement {
       {signal}
     );
 
-    this.addEventListener(
-      'craft-after-show',
-      () => {
-        this.status = '';
-        setTimeout(() => {
-          this.status = 'Some new status';
-        }, 200);
-      },
-      {signal}
-    );
-
     this.addEventListener(
       'craft-after-hide',
       () => {
         if (CraftInfoIcon.#openInstance === this) {
           CraftInfoIcon.#openInstance = null;
         }
-        this.status = '';
       },
       {signal}
     );
@@ -97,10 +102,6 @@ export default class CraftInfoIcon extends LitElement {
   override render() {
     return html`
       <div class="cp-info-icon">
-        <craft-visually-hidden role="status">
-          ${this.status}
-        </craft-visually-hidden>
-
         <craft-button
           type="button"
           icon
diff --git a/packages/craftcms-ui/src/components/input-color/InputColor.mdx b/packages/craftcms-ui/src/components/input-color/InputColor.mdx
new file mode 100644
index 00000000000..723f9a45268
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-color/InputColor.mdx
@@ -0,0 +1,50 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputColorStories from './input-color.stories';
+
+<Meta of={InputColorStories} name="Docs" />
+
+# Input Color
+
+`<craft-input-color>` pairs a hex text field with the browser's own colour swatch.
+
+<Canvas of={InputColorStories.Default} sourceState="shown" />
+
+Two ways of choosing a colour suit two different tasks: the picker for browsing to something that looks right, the text field for entering a value you already have.
+Either one updates the other.
+
+## Values
+
+Values are bare hex — the leading `#` is stripped, and three-digit shorthand is expanded to six for the picker.
+The field shows a `#` prefix so the format is obvious without it being part of the value.
+
+<Canvas of={InputColorStories.Shorthand} sourceState="shown" />
+
+Anything that is not a valid hex colour leaves the swatch alone rather than snapping it to an arbitrary colour:
+
+<Canvas of={InputColorStories.Invalid} sourceState="shown" />
+
+## Presets
+
+`presets` takes a JSON array of hex values, offered through a native datalist:
+
+<Canvas of={InputColorStories.WithPresets} sourceState="shown" />
+
+The list is a shortcut, not a constraint — any value can still be typed.
+
+## States
+
+<Canvas of={InputColorStories.WithError} sourceState="shown" />
+
+<Canvas of={InputColorStories.Disabled} sourceState="shown" />
+
+## Accessibility
+
+Colour is the one thing this control cannot convey on its own.
+The text field is what makes the value readable and typable without seeing the swatch, which is why it is the primary control rather than a secondary one.
+
+Presets are offered by value, not by name.
+If a preset means something — a brand colour, a status — say so in the help text, because the swatch alone does not.
+
+## Properties
+
+<ArgTypes of={InputColorStories} />
diff --git a/packages/craftcms-ui/src/components/input-color/input-color.stories.ts b/packages/craftcms-ui/src/components/input-color/input-color.stories.ts
index bfc59db1e56..6cc95829b71 100644
--- a/packages/craftcms-ui/src/components/input-color/input-color.stories.ts
+++ b/packages/craftcms-ui/src/components/input-color/input-color.stories.ts
@@ -1,74 +1,85 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './input-color.js';
+import type CraftInputColor from './input-color.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-color.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: the value is Lion's
+ * `modelValue`, a property rather than an attribute, and the label is a slot.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftInputColor>('craft-input-color');
+
+type CraftInputColorArgs = CraftInputColor & typeof args;
+
+/** The shell every story shares, so each one only supplies its args. */
+const field = (args: Record<string, unknown>, extra: unknown = '') => html`
+  <craft-input-color
+    ?disabled="${args.disabled}"
+    .modelValue="${args.value ?? ''}"
+    .presets="${(args.presets as string[]) ?? []}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${args['help-text-slot']
+      ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+      : ''}
+    ${extra}
+  </craft-input-color>
+`;
 
 const meta = {
-  title: 'Controls/Input Color',
+  title: 'Form Controls/Text Controls/Input Color',
   component: 'craft-input-color',
-  args: {
-    label: 'Fill Color',
-    value: '7ab55c',
-  },
-  render: function ({label, value}) {
-    return html`<craft-input-color
-      label="${label}"
-      .modelValue="${value}"
-    ></craft-input-color>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, 'label-slot': 'Fill Color', value: '7ab55c'},
+  argTypes,
+  render: (args) => field(args),
+} satisfies Meta<CraftInputColorArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftInputColorArgs>;
 
-export const Default: Story = {
-  args: {},
-};
+/** A hex value beside a swatch that opens the browser's colour picker. */
+export const Default: Story = {};
 
+/** Three-digit shorthand is accepted and expanded. */
 export const Shorthand: Story = {
-  args: {
-    value: 'abc',
-  },
+  args: {value: 'abc'},
 };
 
+/** A value that is not a colour leaves the swatch empty. */
 export const Invalid: Story = {
-  args: {
-    value: 'not-a-color',
-  },
+  args: {value: 'not-a-color'},
 };
 
 export const Disabled: Story = {
-  render: () =>
-    html`<craft-input-color
-      label="Fill Color"
-      .modelValue="${'7ab55c'}"
-      disabled
-    ></craft-input-color>`,
+  args: {disabled: true},
 };
 
+/** `presets` offers a fixed set beneath the picker. */
 export const WithPresets: Story = {
-  render: () => html`
-    <craft-input-color
-      label="Fill Color"
-      .modelValue="${'7ab55c'}"
-      .presets="${['#ffffff', '000000', '#7ab55c', 'e5422b']}"
-    ></craft-input-color>
-  `,
+  args: {presets: ['#ffffff', '000000', '#7ab55c', 'e5422b']},
 };
 
+/** Validation feedback goes in the `feedback` slot, as on any Lion field. */
 export const WithError: Story = {
-  render: () => html`
-    <craft-input-color
-      label="Fill Color"
-      .modelValue="${'not-a-color'}"
+  args: {value: 'not-a-color'},
+  render: (args) =>
+    html`<craft-input-color
+      .modelValue="${args.value ?? ''}"
       has-feedback-for="error"
     >
+      <label slot="label">${args['label-slot']}</label>
       <div slot="feedback">
         <ul class="error-list">
           <li>Enter a valid hex color.</li>
         </ul>
       </div>
-    </craft-input-color>
-  `,
+    </craft-input-color>`,
 };
diff --git a/packages/craftcms-ui/src/components/input-color/input-color.ts b/packages/craftcms-ui/src/components/input-color/input-color.ts
index d888546dc34..dfed67e303e 100644
--- a/packages/craftcms-ui/src/components/input-color/input-color.ts
+++ b/packages/craftcms-ui/src/components/input-color/input-color.ts
@@ -1,7 +1,6 @@
-import {LionInput} from '@lion/ui/input.js';
 import {html, nothing} from 'lit';
 import {property} from 'lit/decorators.js';
-import {inputStyles} from '@src/styles/form.styles';
+import CraftInput from '../input/input.js';
 import {t} from '@src/utilities/translate';
 import styles from './input-color.styles.js';
 
@@ -52,7 +51,7 @@ function expandedHexValue(value: unknown): string | null {
 }
 
 /**
- * @summary A color input built on top of Lion's text input. Pairs a free
+ * @summary A color input built on top of `craft-input`. Pairs a free
  * text field (prefixed with `#`) with a native `<input type="color">` swatch and
  * an optional datalist of preset colors.
  *
@@ -69,9 +68,9 @@ function expandedHexValue(value: unknown): string | null {
  *
  * @since 1.0
  */
-export default class CraftInputColor extends LionInput {
+export default class CraftInputColor extends CraftInput {
   static override get styles() {
-    return [...super.styles, inputStyles, styles];
+    return [...super.styles, styles];
   }
 
   /**
@@ -90,9 +89,14 @@ export default class CraftInputColor extends LionInput {
 
   protected _pickerListId = `${this._inputId}-presets`;
 
+  /**
+   * Fixed to `text`. The swatch beside the field is a separate native colour
+   * input, so the text field keeps the hex value editable.
+   */
+  override type = 'text';
+
   constructor() {
     super();
-    this.type = 'text';
   }
 
   /**
@@ -111,6 +115,9 @@ export default class CraftInputColor extends LionInput {
     return CraftInputColor._browserSupportsColorInputs;
   }
 
+  /**
+   * Adds the colour swatch alongside the native input.
+   */
   override get slots() {
     return {
       ...super.slots,
@@ -133,22 +140,38 @@ export default class CraftInputColor extends LionInput {
     };
   }
 
+  /**
+   * Parses the typed hex string into the model value.
+   */
   override parser(value: string) {
     return normalizeColorValue(value);
   }
 
+  /**
+   * Formats the model value for display in the field.
+   */
   override formatter(value: unknown) {
     return normalizeColorValue(value);
   }
 
+  /**
+   * Serialises the model value for form submission.
+   */
   override serializer(value: unknown) {
     return normalizeColorValue(value);
   }
 
+  /**
+   * Restores a model value from its serialised form.
+   */
   override deserializer(value: string) {
     return normalizeColorValue(value);
   }
 
+  /**
+   * Normalises what is typed before it is parsed, so a value pasted with or
+   * without a leading `#` lands the same way.
+   */
   override preprocessor(value: string) {
     const normalizedValue = normalizeColorValue(value);
 
diff --git a/packages/craftcms-ui/src/components/input-copy/InputCopy.mdx b/packages/craftcms-ui/src/components/input-copy/InputCopy.mdx
new file mode 100644
index 00000000000..6cd66b4a7ba
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-copy/InputCopy.mdx
@@ -0,0 +1,48 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputCopyStories from './input-copy.stories';
+
+<Meta of={InputCopyStories} name="Docs" />
+
+# Input Copy
+
+`<craft-input-copy>` shows a value and gives it a copy-to-clipboard button.
+
+<Canvas of={InputCopyStories.Default} sourceState="shown" />
+
+It is [Input](?path=/docs/form-controls-text-controls-input--docs) held permanently read-only, with a `craft-copy-button` in its suffix.
+
+## Read-Only by Design
+
+The control forces `readOnly` on every update, not just at startup, so removing the attribute at runtime does not make the field editable.
+That is deliberate: the value is something to take away, not something to change, and a field that looks editable but is not would be worse than one that plainly is not.
+
+## Copying Something Else
+
+`copy-value` sets what reaches the clipboard, independently of what is displayed.
+Reach for it when the readable form and the useful form differ — showing a truncated token while copying the whole one, say:
+
+<Canvas of={InputCopyStories.WithSeparateCopyValue} sourceState="shown" />
+
+With `copy-value` unset, the displayed value is copied.
+
+## Events
+
+The control re-emits the copy button's outcome, so a page can react to it:
+
+- `craft-copy` — the value reached the clipboard.
+- `craft-error` — it did not.
+
+## States
+
+<Canvas of={InputCopyStories.Disabled} sourceState="shown" />
+
+## Accessibility
+
+The copy button carries its own tooltip and label, so it is announced as a button rather than as unnamed chrome.
+
+A copy that succeeds silently is a copy a screen reader user cannot confirm.
+If the surrounding page does not already announce the result, listen for `craft-copy` and say so.
+
+## Properties
+
+<ArgTypes of={InputCopyStories} />
diff --git a/packages/craftcms-ui/src/components/input-copy/input-copy.stories.ts b/packages/craftcms-ui/src/components/input-copy/input-copy.stories.ts
index 2997c723b0d..5c249a4b27b 100644
--- a/packages/craftcms-ui/src/components/input-copy/input-copy.stories.ts
+++ b/packages/craftcms-ui/src/components/input-copy/input-copy.stories.ts
@@ -1,49 +1,70 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './input-copy.js';
+import type CraftInputCopy from './input-copy.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-copy.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: the value is Lion's
+ * `modelValue`, a property rather than an attribute, and the label is a slot.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftInputCopy>('craft-input-copy');
+
+type CraftInputCopyArgs = CraftInputCopy & typeof args;
+
+/** The shell every story shares, so each one only supplies its args. */
+const field = (args: Record<string, unknown>) => html`
+  <craft-input-copy
+    copy-value="${(args['copy-value'] as string) ?? ''}"
+    ?disabled="${args.disabled}"
+    .modelValue="${args.value ?? ''}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${args['help-text-slot']
+      ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+      : ''}
+  </craft-input-copy>
+`;
 
 const meta = {
-  title: 'Controls/Input Copy',
+  title: 'Form Controls/Text Controls/Input Copy',
   component: 'craft-input-copy',
-  render: () => html`
-    <craft-input-copy
-      label="Site URL"
-      help-text="Click the copy button to copy this value."
-      value="https://craftcms.com"
-    ></craft-input-copy>
-  `,
-} satisfies Meta<any>;
+  args: {
+    ...args,
+    'label-slot': 'Site URL',
+    'help-text-slot': 'Click the copy button to copy this value.',
+    value: 'https://craftcms.com',
+  },
+  argTypes,
+  render: (args) => field(args),
+} satisfies Meta<CraftInputCopyArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftInputCopyArgs>;
 
-export const Default: Story = {
-  args: {},
-};
+/** A read-only value with a copy button in the suffix. */
+export const Default: Story = {};
 
 /**
- * Use \`copy-value\` when the value sent to the clipboard should differ from
- * what is displayed in the textbox — for example, showing a truncated token
- * while copying the full one.
+ * `copy-value` sends something other than what is shown — a full token behind
+ * a masked one, say.
  */
 export const WithSeparateCopyValue: Story = {
-  render: () => html`
-    <craft-input-copy
-      label="API Token"
-      value="sk-••••••••••••••••••••••••1234"
-      copy-value="sk-abcdefghijklmnopqrstuvwxyz1234"
-    ></craft-input-copy>
-  `,
+  args: {
+    'label-slot': 'API Token',
+    'help-text-slot': '',
+    value: 'sk-••••••••••••••••••••••••1234',
+    'copy-value': 'sk-abcdefghijklmnopqrstuvwxyz1234',
+  },
 };
 
 export const Disabled: Story = {
-  render: () => html`
-    <craft-input-copy
-      label="Site URL"
-      value="https://craftcms.com"
-      disabled
-    ></craft-input-copy>
-  `,
+  args: {disabled: true, 'help-text-slot': ''},
 };
diff --git a/packages/craftcms-ui/src/components/input-copy/input-copy.ts b/packages/craftcms-ui/src/components/input-copy/input-copy.ts
index 6fd0c58ba44..9cc6ab2f9bf 100644
--- a/packages/craftcms-ui/src/components/input-copy/input-copy.ts
+++ b/packages/craftcms-ui/src/components/input-copy/input-copy.ts
@@ -36,6 +36,9 @@ export default class CraftInputCopy extends CraftInput {
     ></craft-copy-button>`;
   }
 
+  /**
+   * Adds the copy button to the field, in the suffix slot.
+   */
   override get slots() {
     return {
       ...super.slots,
diff --git a/packages/craftcms-ui/src/components/input-date-time/InputDateTime.mdx b/packages/craftcms-ui/src/components/input-date-time/InputDateTime.mdx
new file mode 100644
index 00000000000..063ce155e35
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-date-time/InputDateTime.mdx
@@ -0,0 +1,107 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputDateTimeStories from './input-date-time.stories';
+
+<Meta of={InputDateTimeStories} name="Docs" />
+
+# Input Date Time
+
+`<craft-input-date-time>` is a paired date and time field.
+It owns a [Input Date](?path=/docs/form-controls-text-controls-input-date--docs) and a [Input Time](?path=/docs/form-controls-text-controls-input-time--docs), creating them as its own children and keeping their values in step.
+
+<Canvas of={InputDateTimeStories.Default} sourceState="shown" />
+
+Reach for it whenever a single moment in time is being edited — a post date, an expiry, a scheduled action — so the two halves submit and validate together rather than as unrelated fields.
+
+The component has no label or field chrome of its own, so every example on this page is wrapped in a `craft-field`.
+
+## Submitting
+
+Give the component a `name` and it posts each part under it:
+
+| Field            | Value                                |
+| ---------------- | ------------------------------------ |
+| `name[date]`     | the date, as `YYYY-MM-DD`            |
+| `name[time]`     | the time, as `HH:MM`                 |
+| `name[timezone]` | the timezone the value belongs to    |
+| `name[locale]`   | the locale the parts were entered in |
+
+The server therefore receives one coherent value rather than two loose inputs.
+The locale always travels with it, and the timezone is carried by a hidden input whenever it is not shown as a control.
+
+Without a `name`, nothing is submitted — the component is then a pair of inputs you read from `date-value` and `time-value` yourself.
+
+<Canvas of={InputDateTimeStories.WithValues} sourceState="shown" />
+
+## Showing One Half
+
+`show-date` and `show-time` are both on by default, and each drops its input when set to the string `"false"`:
+
+<Canvas of={InputDateTimeStories.DateOnly} sourceState="shown" />
+
+<Canvas of={InputDateTimeStories.TimeOnly} sourceState="shown" />
+
+These two are deliberately default-on, so **only the exact value `"false"` turns them off**.
+Any other value — including `"0"` — leaves the input in place, and so does removing the attribute.
+
+That makes them string flags rather than boolean attributes, which matters when you are not writing the markup by hand.
+A boolean binding cannot express them: `?show-time="${false}"` in a Lit template removes the attribute, and an absent attribute reads as on.
+Write the literal string instead.
+
+```html
+<craft-input-date-time show-time="false"></craft-input-date-time>
+```
+
+`show-timezone` is the opposite: an ordinary boolean attribute that is absent by default, and on when present.
+
+<Canvas of={InputDateTimeStories.WithTimezone} sourceState="shown" />
+
+Hiding the timezone does not discard it.
+It keeps travelling in a hidden input, so a value entered in one zone is not silently reinterpreted in another.
+
+## Constraining the Value
+
+`min` and `max` bound the date; `min-time` and `max-time` bound the time:
+
+<Canvas of={InputDateTimeStories.Bounded} sourceState="shown" />
+
+`minute-increment` sets the spacing between the time input's suggestions, and `force-round-time` snaps a typed time onto the nearest step:
+
+<Canvas of={InputDateTimeStories.MinuteIncrement} sourceState="shown" />
+
+`disabled-time-ranges` takes a JSON array of `[start, end]` pairs of `HH:MM` times that cannot be chosen.
+It is forwarded straight to the time input — see [Input Time](?path=/docs/form-controls-text-controls-input-time--docs) for how the ranges are enforced.
+
+## States
+
+<Canvas of={InputDateTimeStories.Disabled} sourceState="shown" />
+
+<Canvas of={InputDateTimeStories.Readonly} sourceState="shown" />
+
+`required` marks the date and time inputs as required.
+All three apply to every input the component owns, including the timezone.
+
+## Adding Your Own Content
+
+The default slot takes content placed after the inputs — a button that clears them, say.
+The component's own inputs always lead, so slotted controls stay after the inputs they act on in both reading and tab order:
+
+<Canvas of={InputDateTimeStories.WithSlottedContent} sourceState="shown" />
+
+## In a Field
+
+Wrapping in `craft-field` is what supplies the label, help text, and error handling:
+
+<Canvas of={InputDateTimeStories.InAField} sourceState="shown" />
+
+`craft-field` sets `described-by` for you, which the component applies to each input it owns.
+
+## Accessibility
+
+Each input the component owns carries its own accessible name — "Date", "Time", "Time zone" — because a wrapping `craft-field` names the pair rather than the parts.
+Without them a screen reader reached two controls announced only as edit fields inside a labelled group, with nothing to say which half was which.
+
+The names are translated, so keep the field's own label describing what the value _is_ ("Post Date") rather than repeating what the parts are.
+
+## Properties
+
+<ArgTypes of={InputDateTimeStories} />
diff --git a/packages/craftcms-ui/src/components/input-date-time/input-date-time.stories.ts b/packages/craftcms-ui/src/components/input-date-time/input-date-time.stories.ts
new file mode 100644
index 00000000000..6d605fee511
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-date-time/input-date-time.stories.ts
@@ -0,0 +1,188 @@
+import type {Decorator, Meta, StoryObj} from '@storybook/web-components';
+
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import './input-date-time.js';
+import '../button/button.js';
+import '../field/field.js';
+import type CraftInputDateTime from './input-date-time.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-date-time.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftInputDateTime>(
+  'craft-input-date-time'
+);
+
+type InputDateTimeArgs = CraftInputDateTime & typeof args;
+
+/**
+ * The component carries no label of its own, so every example sits in a
+ * `craft-field` — which is how it is always used, and what gives the pair a
+ * name.
+ *
+ * A story that renders its own field sets `parameters.ownField` to opt out.
+ * Story-level decorators are additive rather than overriding, so opting out
+ * has to be a parameter the shared decorator checks; returning `story()` from
+ * a story's own decorator would still leave this one wrapping it.
+ */
+const inField: Decorator = (story, context) => html`
+  <craft-field>
+    <label slot="label">Post Date</label>
+    ${story()}
+  </craft-field>
+`;
+
+/**
+ * `show-date` and `show-time` cannot be driven from args.
+ *
+ * They are default-on string flags — only the literal `"false"` turns them
+ * off, which is what the PHP builder emits. The manifest types them as
+ * booleans, and the helpers map a `"false"` arg onto boolean `false`, which
+ * *removes* the attribute; an absent attribute reads as on. So the stories
+ * that turn them off write the attribute themselves, and the controls are
+ * disabled rather than offering a knob that cannot work.
+ */
+const showFlagArgType = {control: {disable: true}} as const;
+
+const meta = {
+  title: 'Form Controls/Text Controls/Input Date Time',
+  component: 'craft-input-date-time',
+  args: {
+    ...args,
+    name: 'postDate',
+    'date-value': '2026-08-28',
+    slot: 'input',
+  },
+  argTypes: {
+    ...argTypes,
+    'show-date': showFlagArgType,
+    'show-time': showFlagArgType,
+  },
+  decorators: [inField],
+  parameters: {
+    // The date and time inputs have no accessible name of their own: each is a
+    // Lion field whose label slot is empty, and a wrapping `craft-field` names
+    // the pair rather than the parts. Surfaced rather than gated until the
+    // component gives them sub-labels — see the docs page.
+    a11y: {test: 'todo'},
+  },
+  // Render from args alone so every control drives the story. Stories below
+  // vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<InputDateTimeArgs>;
+
+export default meta;
+type Story = StoryObj<InputDateTimeArgs>;
+
+/** A date input and a time input, kept in step and submitted together. */
+export const Default: Story = {};
+
+/** Both parts can carry a value. */
+export const WithValues: Story = {
+  args: {'date-value': '2026-08-28', 'time-value': '09:30'},
+};
+
+/** `show-time="false"` drops the time input, leaving a date-only field. */
+export const DateOnly: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-input-date-time
+      slot="input"
+      name="postDate"
+      date-value="2026-08-28"
+      show-time="false"
+    ></craft-input-date-time>
+  `,
+};
+
+/** `show-date="false"` drops the date input, leaving a time-only field. */
+export const TimeOnly: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-input-date-time
+      slot="input"
+      name="postDate"
+      time-value="09:30"
+      show-date="false"
+    ></craft-input-date-time>
+  `,
+};
+
+/**
+ * `show-timezone` makes the timezone editable. Without it the timezone still
+ * travels with the value, in a hidden input.
+ */
+export const WithTimezone: Story = {
+  args: {'show-timezone': true, timezone: 'America/Los_Angeles'},
+};
+
+/** `min` and `max` bound the date; `min-time` and `max-time` bound the time. */
+export const Bounded: Story = {
+  args: {
+    min: '2026-08-01',
+    max: '2026-08-31',
+    'min-time': '09:00',
+    'max-time': '17:00',
+  },
+};
+
+/** `minute-increment` sets the spacing between the time input's suggestions. */
+export const MinuteIncrement: Story = {
+  args: {'minute-increment': 15, 'time-value': '09:15'},
+};
+
+export const Disabled: Story = {
+  args: {disabled: true, 'time-value': '09:30'},
+};
+
+export const Readonly: Story = {
+  args: {readonly: true, 'time-value': '09:30'},
+};
+
+/**
+ * The component's own inputs always lead, so slotted content — a clear button,
+ * say — stays after the inputs it acts on in reading and tab order.
+ */
+export const WithSlottedContent: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-input-date-time slot="input" name="postDate" date-value="2026-08-28">
+      <craft-button
+        size="small"
+        variant="plain"
+        @click="${(event: Event) => {
+          const field = (event.currentTarget as HTMLElement)
+            .parentElement as CraftInputDateTime;
+          field.dateValue = '';
+          field.timeValue = '';
+        }}"
+      >
+        Clear
+      </craft-button>
+    </craft-input-date-time>
+  `,
+};
+
+/**
+ * Wrapping in `craft-field` is what supplies the label, help text, and error
+ * handling. Every example on this page is wrapped the same way.
+ */
+export const InAField: Story = {
+  parameters: {controls: {disable: true}, ownField: true},
+  render: () => html`
+    <craft-field>
+      <label slot="label">Post Date</label>
+      <span slot="help-text">When the entry should go live.</span>
+      <craft-input-date-time
+        slot="input"
+        name="postDate"
+        date-value="2026-08-28"
+        time-value="09:30"
+      ></craft-input-date-time>
+    </craft-field>
+  `,
+};
diff --git a/packages/craftcms-ui/src/components/input-date-time/input-date-time.ts b/packages/craftcms-ui/src/components/input-date-time/input-date-time.ts
index 924658bd076..193c3ed3556 100644
--- a/packages/craftcms-ui/src/components/input-date-time/input-date-time.ts
+++ b/packages/craftcms-ui/src/components/input-date-time/input-date-time.ts
@@ -5,60 +5,127 @@ import CraftInputDate from '../input-date/input-date.js';
 import CraftInputTime, {
   type DisabledTimeRange,
 } from '../input-time/input-time.js';
-
-const booleanAttribute = {
-  fromAttribute: (value: string | null) => value !== 'false',
-  toAttribute: (value: boolean) => String(value),
+import {defaultTrueBoolean, jsonAttribute} from '@src/utilities/converters';
+import {t} from '@src/utilities/translate';
+
+/**
+ * Accessible names for the inputs the component owns. Functions rather than
+ * strings so they translate against the locale in play when they are read,
+ * not the one loaded when the module was first imported.
+ */
+const PART_LABELS: Record<string, () => string> = {
+  date: () => t('Date'),
+  time: () => t('Time'),
+  timezone: () => t('Time zone'),
 };
 
+/**
+ * @summary A paired date and time field. It owns a `craft-input-date`, a
+ * `craft-input-time`, and optionally a timezone input, creating them as its
+ * own light-DOM children and keeping their values in step.
+ *
+ * Give it a `name` and it submits the parts under that name — `name[date]`,
+ * `name[time]`, `name[timezone]`, and `name[locale]` — so the server receives
+ * one coherent value. The locale always goes along, and the timezone is
+ * carried by a hidden input whenever it is not shown as a control.
+ *
+ * The component has no label or field chrome of its own. Wrap it in
+ * `craft-field` for a label, instructions, and error handling.
+ *
+ * @slot - Content placed after the date and time inputs, such as a button
+ *   that clears them. The component's own inputs always lead, so slotted
+ *   controls stay after the inputs they act on in reading and tab order.
+ */
 export default class CraftInputDateTime extends LitElement {
+  /**
+   * Base name for the submitted values. Each part is posted under it as
+   * `name[date]`, `name[time]`, `name[timezone]`, and `name[locale]`. Without
+   * a name nothing is submitted.
+   */
   @property() name?: string;
 
+  /** Value of the date input, as `YYYY-MM-DD`. */
   @property({attribute: 'date-value'}) dateValue = '';
 
+  /** Value of the time input, as `HH:MM`. */
   @property({attribute: 'time-value'}) timeValue = '';
 
+  /**
+   * Locale the inputs format against. Always submitted as `name[locale]`, so
+   * the server can read the parts back the way they were entered.
+   */
   @property() locale?: string;
 
+  /**
+   * The timezone the value belongs to. Shown as an editable input when
+   * `show-timezone` is set, and submitted as a hidden input otherwise.
+   */
   @property() timezone?: string;
 
-  @property({attribute: 'show-date', converter: booleanAttribute})
+  /**
+   * Whether the date input is shown. On by default — set `show-date="false"`
+   * to drop it and leave a time-only field. Any other value counts as on.
+   */
+  @property({attribute: 'show-date', converter: defaultTrueBoolean})
   showDate = true;
 
-  @property({attribute: 'show-time', converter: booleanAttribute})
+  /**
+   * Whether the time input is shown. On by default — set `show-time="false"`
+   * to drop it and leave a date-only field. Any other value counts as on.
+   */
+  @property({attribute: 'show-time', converter: defaultTrueBoolean})
   showTime = true;
 
+  /**
+   * Whether the timezone is editable. Unlike `show-date` and `show-time` this
+   * is an ordinary boolean attribute: absent means off, present means on.
+   */
   @property({type: Boolean, attribute: 'show-timezone'})
   showTimezone = false;
 
+  /** Earliest selectable date, as `YYYY-MM-DD`. */
   @property() min?: string;
 
+  /** Latest selectable date, as `YYYY-MM-DD`. */
   @property() max?: string;
 
+  /** Earliest selectable time, as `HH:MM`. */
   @property({attribute: 'min-time'}) minTime?: string;
 
+  /** Latest selectable time, as `HH:MM`. */
   @property({attribute: 'max-time'}) maxTime?: string;
 
+  /** Spacing between the time input's suggestions, in minutes. */
   @property({type: Number, attribute: 'minute-increment'}) minuteIncrement = 30;
 
+  /**
+   * Time ranges that cannot be chosen, as a JSON array of `[start, end]`
+   * pairs of `HH:MM` times. Passed through to the time input, which enforces
+   * them with validation.
+   */
   @property({
     attribute: 'disabled-time-ranges',
-    converter: {
-      fromAttribute: (value) => JSON.parse(value ?? '[]'),
-      toAttribute: (value) => JSON.stringify(value),
-    },
+    converter: jsonAttribute<DisabledTimeRange[]>(() => []),
   })
   disabledTimeRanges: DisabledTimeRange[] = [];
 
+  /** Snaps a typed time onto the nearest `minute-increment` step. */
   @property({type: Boolean, attribute: 'force-round-time'})
   forceRoundTime = false;
 
+  /** Disables every input the component owns. */
   @property({type: Boolean}) disabled = false;
 
+  /** Makes every input the component owns read-only. */
   @property({type: Boolean}) readonly = false;
 
+  /** Marks the date and time inputs as required. */
   @property({type: Boolean}) required = false;
 
+  /**
+   * Id of the element describing this field, applied as `aria-describedby` to
+   * each input the component owns. `craft-field` supplies this for you.
+   */
   @property({attribute: 'described-by'}) describedBy?: string;
 
   static override styles = css`
@@ -186,6 +253,7 @@ export default class CraftInputDateTime extends LitElement {
     required: boolean
   ) {
     input.name = this.name ? `${this.name}[${part}]` : '';
+
     input.disabled = this.disabled;
     input.readOnly = this.readonly;
     input.required = required;
@@ -199,6 +267,12 @@ export default class CraftInputDateTime extends LitElement {
     } else {
       input.removeAttribute('aria-describedby');
     }
+
+    // A wrapping `craft-field` names the pair, not the parts. Without a name
+    // of its own each input is announced only as an edit field, so a person
+    // tabbing between them is told twice that they are somewhere they can
+    // type and never which half they are in.
+    input.setAttribute('aria-label', PART_LABELS[part]?.() ?? part);
   }
 
   #onModelValueChanged = (event: Event) => {
diff --git a/packages/craftcms-ui/src/components/input-date-time/labels.test.ts b/packages/craftcms-ui/src/components/input-date-time/labels.test.ts
new file mode 100644
index 00000000000..02f49d476af
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-date-time/labels.test.ts
@@ -0,0 +1,56 @@
+import {expect, test} from 'vite-plus/test';
+import {html, render} from 'lit';
+
+import './input-date-time.js';
+
+async function mount(template: unknown) {
+  const host = document.createElement('div');
+  document.body.append(host);
+  render(template as never, host);
+  const element = host.firstElementChild as HTMLElement & {
+    updateComplete: Promise<unknown>;
+  };
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+function labels(element: HTMLElement): Record<string, string | null> {
+  return Object.fromEntries(
+    [...element.querySelectorAll('[data-date-time-part]')].map((part) => [
+      (part as HTMLElement).dataset.dateTimePart!,
+      part.getAttribute('aria-label'),
+    ])
+  );
+}
+
+test('names the date and time inputs separately', async () => {
+  const element = await mount(
+    html`<craft-input-date-time name="postDate"></craft-input-date-time>`
+  );
+
+  expect(labels(element)).toEqual({date: 'Date', time: 'Time'});
+});
+
+test('names the timezone input when it is shown', async () => {
+  const element = await mount(
+    html`<craft-input-date-time
+      name="postDate"
+      show-timezone
+    ></craft-input-date-time>`
+  );
+
+  expect(labels(element).timezone).toBe('Time zone');
+});
+
+test('a date-only field still names its one input', async () => {
+  const element = await mount(
+    html`<craft-input-date-time
+      name="postDate"
+      show-time="false"
+    ></craft-input-date-time>`
+  );
+
+  expect(labels(element)).toEqual({date: 'Date'});
+});
diff --git a/packages/craftcms-ui/src/components/input-date/InputDate.mdx b/packages/craftcms-ui/src/components/input-date/InputDate.mdx
new file mode 100644
index 00000000000..1a803c1e770
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-date/InputDate.mdx
@@ -0,0 +1,52 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputDateStories from './input-date.stories';
+
+<Meta of={InputDateStories} name="Docs" />
+
+# Input Date
+
+`<craft-input-date>` is a date input.
+It is [Input](?path=/docs/form-controls-text-controls-input--docs) with its `type` fixed to `date`, so it carries the same label, help text, validation, and slots, and renders the browser's own date picker.
+
+<Canvas of={InputDateStories.Default} sourceState="shown" />
+
+Everything on the Input page applies here — labelling, width, sizing, and the slot surface.
+This page covers only what is specific to dates.
+
+## Values
+
+Values are `YYYY-MM-DD`, which is what the native date input exchanges regardless of how the browser displays them.
+A person in a `dd/mm/yyyy` locale sees their own format; the value you read is still ISO.
+
+<Canvas of={InputDateStories.WithHelpText} sourceState="shown" />
+
+## Bounding the Range
+
+`min` and `max` take the same `YYYY-MM-DD` form and bound what the picker offers.
+
+Both are **properties rather than attributes** — they are declared with `attribute: false` and pushed onto the native input — so bind them with `.min` / `.max` rather than writing them as markup:
+
+<Canvas of={InputDateStories.Bounded} sourceState="shown" />
+
+## States
+
+<Canvas of={InputDateStories.Disabled} sourceState="shown" />
+
+<Canvas of={InputDateStories.Readonly} sourceState="shown" />
+
+<Canvas of={InputDateStories.Sizes} sourceState="shown" />
+
+## Pairing With a Time
+
+To edit a date and a time as a single value, use [Input Date Time](?path=/docs/form-controls-text-controls-input-date-time--docs).
+It owns one of these and one [Input Time](?path=/docs/form-controls-text-controls-input-time--docs), keeps them in step, and submits them together under one name — which is what you want whenever the two halves describe the same moment.
+
+## Accessibility
+
+The native date input brings its own keyboard support and its own picker, both of which are better understood by assistive technology than anything a custom widget would replace them with.
+
+As with any [Input](?path=/docs/form-controls-text-controls-input--docs), the one thing to get right is the label: set `label`, slot one, or wrap the control in `craft-field`.
+
+## Properties
+
+<ArgTypes of={InputDateStories} />
diff --git a/packages/craftcms-ui/src/components/input-date/input-date.stories.ts b/packages/craftcms-ui/src/components/input-date/input-date.stories.ts
new file mode 100644
index 00000000000..bf2200da911
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-date/input-date.stories.ts
@@ -0,0 +1,82 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import './input-date.js';
+import type CraftInputDate from './input-date.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-date.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftInputDate>('craft-input-date');
+
+type InputDateArgs = CraftInputDate & typeof args;
+
+const meta = {
+  title: 'Form Controls/Text Controls/Input Date',
+  component: 'craft-input-date',
+  args: {...args, 'label-slot': 'Post Date'},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<InputDateArgs>;
+
+export default meta;
+type Story = StoryObj<InputDateArgs>;
+
+/** The browser's own date picker, with Craft's label and help text around it. */
+export const Default: Story = {};
+
+export const WithHelpText: Story = {
+  args: {'help-text-slot': 'When the entry should go live.'},
+};
+
+/**
+ * `min` and `max` bound the selectable range. Both are `YYYY-MM-DD`, and both
+ * are properties rather than attributes — bind them with `.min` / `.max`.
+ */
+export const Bounded: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-input-date
+      label="Post Date"
+      help-text="August 2026 only."
+      .min="${'2026-08-01'}"
+      .max="${'2026-08-31'}"
+    ></craft-input-date>
+  `,
+};
+
+export const Disabled: Story = {
+  args: {disabled: true},
+};
+
+export const Readonly: Story = {
+  args: {readonly: true},
+};
+
+/**
+ * To edit a date and a time as one value, use
+ * [Input Date Time](?path=/docs/form-controls-text-controls-input-date-time--docs), which pairs
+ * this with an [Input Time](?path=/docs/form-controls-text-controls-input-time--docs) and submits
+ * them together.
+ */
+export const Sizes: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${(['small', 'medium', 'large'] as const).map(
+        (size) =>
+          html`<craft-input-date
+            label='size="${size}"'
+            size="${size}"
+          ></craft-input-date>`
+      )}
+    </div>
+  `,
+};
diff --git a/packages/craftcms-ui/src/components/input-date/input-date.ts b/packages/craftcms-ui/src/components/input-date/input-date.ts
index bd72dbec9c9..5992000ebac 100644
--- a/packages/craftcms-ui/src/components/input-date/input-date.ts
+++ b/packages/craftcms-ui/src/components/input-date/input-date.ts
@@ -1,9 +1,23 @@
 import CraftInput from '../input/input.js';
 
+/**
+ * @summary A date input. `craft-input` with its `type` fixed to `date`, so it
+ * carries the same label, help text, validation, and slots, and renders the
+ * browser's own date picker.
+ *
+ * Values are `YYYY-MM-DD`, and `min` and `max` take the same form. To edit a
+ * date and a time together, use `craft-input-date-time`, which pairs this with
+ * `craft-input-time` and submits them as one value.
+ */
 export default class CraftInputDate extends CraftInput {
+  /**
+   * Fixed to `date`, which is the point of the component — it renders the
+   * browser's date picker rather than a text field.
+   */
+  override type = 'date';
+
   constructor() {
     super();
-    this.type = 'date';
   }
 }
 
diff --git a/packages/craftcms-ui/src/components/input-file/InputFile.mdx b/packages/craftcms-ui/src/components/input-file/InputFile.mdx
new file mode 100644
index 00000000000..48ba89bb502
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-file/InputFile.mdx
@@ -0,0 +1,43 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputFileStories from './input-file.stories';
+
+<Meta of={InputFileStories} name="Docs" />
+
+# Input File
+
+`<craft-input-file>` is a file field: a button that opens the file dialog, and a list of what has been chosen.
+
+<Canvas of={InputFileStories.Default} sourceState="shown" />
+
+It is built on Lion's file input rather than [Input](?path=/docs/form-controls-text-controls-input--docs), because it manages a list of files rather than a text value — so the base control's `maxlength`, `size`, `width`, and friends do not apply here.
+
+## Choosing Files
+
+`multiple` allows more than one file, and the list grows as they are added:
+
+<Canvas of={InputFileStories.Multiple} sourceState="shown" />
+
+`accept` limits what the dialog offers, using the same syntax as the native attribute:
+
+<Canvas of={InputFileStories.WithAccept} sourceState="shown" />
+
+`accept` filters the dialog; it is not a guarantee. A file can still arrive by other routes, so validate on the server too.
+
+## Validation
+
+Lion supplies file-type and file-size validators, and their messages render in the `feedback` slot alongside any of your own.
+
+## Slots
+
+The dialog button comes from the component, as a `craft-button` in the `file-select-button` slot.
+Slotting your own replaces it — useful when the button needs different wording or a different variant, though the default already carries the label Lion computes.
+
+## Accessibility
+
+The button is a real button and the file list is real content, so both are reachable and announced without help.
+
+The selection is the part worth attention: after choosing files, what changed is the list, not the button. If a page needs that announced, it should say so itself.
+
+## Properties
+
+<ArgTypes of={InputFileStories} />
diff --git a/packages/craftcms-ui/src/components/input-file/input-file.stories.ts b/packages/craftcms-ui/src/components/input-file/input-file.stories.ts
index 5881e720212..5e63103556b 100644
--- a/packages/craftcms-ui/src/components/input-file/input-file.stories.ts
+++ b/packages/craftcms-ui/src/components/input-file/input-file.stories.ts
@@ -1,46 +1,74 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './input-file.js';
+import type CraftInputFile from './input-file.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-file.ts` surfaces it here without touching this file.
+ *
+ * `accept` and `multiple` come from Lion's file input rather than from this
+ * component, so they are written into the template rather than generated.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftInputFile>('craft-input-file');
+
+type InputFileArgs = CraftInputFile & typeof args;
+
+/** The shell every story shares, so each one only supplies its args. */
+const field = (args: Record<string, unknown>) => html`
+  <craft-input-file
+    accept="${(args.accept as string) ?? ''}"
+    ?multiple="${args.multiple}"
+    ?disabled="${args.disabled}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${args['help-text-slot']
+      ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+      : ''}
+  </craft-input-file>
+`;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/InputFile',
+  title: 'Form Controls/Input File',
   component: 'craft-input-file',
-  args: {},
-  render: function () {
-    return html`<craft-input-file
-      label="Upload File"
-      help-text="Select a file to upload"
-    ></craft-input-file>`;
+  args: {
+    ...args,
+    'label-slot': 'Upload file',
+    'help-text-slot': 'Select a file to upload.',
   },
-} satisfies Meta<any>;
+  argTypes,
+  render: (args) => field(args),
+} satisfies Meta<InputFileArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<InputFileArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** A button that opens the file dialog, and the list of what was chosen. */
+export const Default: Story = {};
 
+/** `multiple` lets the dialog return more than one file. */
 export const Multiple: Story = {
-  render: function () {
-    return html`<craft-input-file
-      label="Upload Files"
-      help-text="Select multiple files to upload"
-      multiple
-    ></craft-input-file>`;
+  args: {
+    multiple: true,
+    'label-slot': 'Upload files',
+    'help-text-slot': 'Select one or more files.',
   },
 };
 
+/** `accept` filters what the dialog offers, as on a native file input. */
 export const WithAccept: Story = {
-  render: function () {
-    return html`<craft-input-file
-      label="Upload Image"
-      help-text="Select an image file"
-      accept="image/*"
-    ></craft-input-file>`;
+  args: {
+    accept: 'image/*',
+    'label-slot': 'Upload image',
+    'help-text-slot': 'Images only.',
   },
 };
+
+export const Disabled: Story = {
+  args: {disabled: true},
+};
diff --git a/packages/craftcms-ui/src/components/input-file/input-file.test.ts b/packages/craftcms-ui/src/components/input-file/input-file.test.ts
new file mode 100644
index 00000000000..29c32f49ce4
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-file/input-file.test.ts
@@ -0,0 +1,75 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './input-file.js';
+import type CraftInputFile from './input-file.js';
+
+async function createInputFile(
+  attrs: Record<string, string> = {},
+  innerHTML = '<label slot="label">Upload file</label>'
+): Promise<CraftInputFile> {
+  const element = document.createElement('craft-input-file') as CraftInputFile;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+function native(element: CraftInputFile): HTMLInputElement {
+  return element.querySelector('input[type="file"]')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-input-file', () => {
+  it('renders a native file input', async () => {
+    const element = await createInputFile();
+
+    expect(native(element)).toBeTruthy();
+  });
+
+  /**
+   * The dialog is opened by a `craft-button` the component supplies, rather
+   * than by the native input's own control, so the CP's button styling
+   * applies.
+   */
+  it('supplies its own button for the file dialog', async () => {
+    const element = await createInputFile();
+    const button = element.querySelector('craft-button');
+
+    expect(button).toBeTruthy();
+    expect(button!.getAttribute('type')).toBe('button');
+  });
+
+  it('wires the label to the control', async () => {
+    const element = await createInputFile();
+
+    expect(element.querySelector('label')!.getAttribute('for')).toBe(
+      native(element).id
+    );
+  });
+
+  it('passes accept through to the native input', async () => {
+    const element = await createInputFile({accept: 'image/*'});
+
+    expect(native(element).getAttribute('accept')).toBe('image/*');
+  });
+
+  it('passes multiple through to the native input', async () => {
+    const element = await createInputFile({multiple: ''});
+
+    expect(native(element).multiple).toBe(true);
+  });
+
+  it('disables the native input', async () => {
+    const element = await createInputFile({disabled: ''});
+
+    expect(native(element).disabled).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/input-file/input-file.ts b/packages/craftcms-ui/src/components/input-file/input-file.ts
index 92cf726f559..57540eed7f5 100644
--- a/packages/craftcms-ui/src/components/input-file/input-file.ts
+++ b/packages/craftcms-ui/src/components/input-file/input-file.ts
@@ -4,11 +4,32 @@ import styles from './input-file.styles.js';
 import CraftSelectedFileList from './selected-file-list.js';
 import {html} from 'lit';
 
+/**
+ * @summary A file input: a button that opens the file dialog, and a list of
+ * the files chosen so far.
+ *
+ * Built on Lion's file input rather than `craft-input`, since it manages a
+ * file list rather than a text value — so the base control's `maxlength`,
+ * `size`, `width`, and friends do not apply. It supplies its own
+ * `craft-button` for the dialog and renders the selection through
+ * `craft-selected-file-list`.
+ *
+ * @slot label - The control's label, as an alternative to the `label`
+ *   attribute.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages, including Lion's own file-type and
+ *   file-size errors.
+ * @slot file-select-button - The button that opens the file dialog. Supplied
+ *   by the component; slotting your own replaces it.
+ */
 export default class CraftInputFile extends LionInputFile {
   static override get styles() {
     return [...super.styles, inputStyles, styles];
   }
 
+  /**
+   * Adds the file input and its chrome to the field.
+   */
   override get slots() {
     return {
       ...super.slots,
@@ -23,6 +44,9 @@ export default class CraftInputFile extends LionInputFile {
     };
   }
 
+  /**
+   * Registers the elements the file input renders into its own shadow root.
+   */
   static override get scopedElements() {
     return {
       ...super.scopedElements,
diff --git a/packages/craftcms-ui/src/components/input-handle/InputHandle.mdx b/packages/craftcms-ui/src/components/input-handle/InputHandle.mdx
new file mode 100644
index 00000000000..3c495a97fab
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-handle/InputHandle.mdx
@@ -0,0 +1,48 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputHandleStories from './input-handle.stories';
+
+<Meta of={InputHandleStories} name="Docs" />
+
+# Input Handle
+
+`<craft-input-handle>` is a field for handles — the short machine-readable names that identify entry types, fields, sections, and volumes.
+
+<Canvas of={InputHandleStories.Default} sourceState="shown" />
+
+It is [Input](?path=/docs/form-controls-text-controls-input--docs) with two changes: the value renders in a monospace face, and the browser's text conveniences are turned off.
+
+## Why It Differs
+
+A handle is typed exactly and read character by character, so the two things a browser does to help with prose actively get in the way.
+Autocorrection rewrites a deliberate spelling, and auto-capitalisation puts a capital where the handle needs none.
+
+The monospace face is the other half: it makes `l`, `1`, and `I` — and `0` against `O` — distinguishable at a glance.
+
+<Canvas of={InputHandleStories.ComparedToInput} sourceState="shown" />
+
+## Autocorrection
+
+`autocorrect` and `autocapitalize` are off here, where [Input](?path=/docs/form-controls-text-controls-input--docs) leaves them on.
+Both can be turned back on if a field wants them:
+
+<Canvas of={InputHandleStories.AutocorrectOn} sourceState="shown" />
+
+They serialise as `on`/`off` rather than as bare boolean attributes, matching the native attributes they drive — so `autocorrect="off"` is the way to disable it, not removing the attribute.
+
+## Everything Else
+
+The rest comes from [Input](?path=/docs/form-controls-text-controls-input--docs) unchanged, including the width inference around `maxlength`:
+
+<Canvas of={InputHandleStories.WithMaxLength} sourceState="shown" />
+
+<Canvas of={InputHandleStories.Disabled} sourceState="shown" />
+
+## Accessibility
+
+Nothing here changes how the control is announced; see [Input](?path=/docs/form-controls-text-controls-input--docs).
+
+Because the field is monospace and the value is machine-readable, it is worth saying in the help text what a valid handle looks like rather than leaving someone to discover the rules through validation.
+
+## Properties
+
+<ArgTypes of={InputHandleStories} />
diff --git a/packages/craftcms-ui/src/components/input-handle/input-handle.stories.ts b/packages/craftcms-ui/src/components/input-handle/input-handle.stories.ts
new file mode 100644
index 00000000000..8cab025b99a
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-handle/input-handle.stories.ts
@@ -0,0 +1,93 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import './input-handle.js';
+import '../input/input.js';
+import type CraftInputHandle from './input-handle.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-handle.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: the value is Lion's
+ * `modelValue`, a property rather than an attribute, and the label is a slot.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftInputHandle>('craft-input-handle');
+
+type CraftInputHandleArgs = CraftInputHandle & typeof args;
+
+/** The shell every story shares, so each one only supplies its args. */
+const field = (args: Record<string, unknown>) => html`
+  <craft-input-handle
+    autocorrect="${args.autocorrect ? 'on' : 'off'}"
+    autocapitalize="${(args.autocapitalize as string) ?? 'off'}"
+    maxlength="${(args.maxlength as number) ?? ''}"
+    ?disabled="${args.disabled}"
+    .modelValue="${args.value ?? ''}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${args['help-text-slot']
+      ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+      : ''}
+  </craft-input-handle>
+`;
+
+const meta = {
+  title: 'Form Controls/Text Controls/Input Handle',
+  component: 'craft-input-handle',
+  args: {
+    ...args,
+    'label-slot': 'Handle',
+    'help-text-slot': 'Used in templates.',
+    value: 'entryType',
+  },
+  argTypes,
+  render: (args) => field(args),
+} satisfies Meta<CraftInputHandleArgs>;
+
+export default meta;
+type Story = StoryObj<CraftInputHandleArgs>;
+
+/** A monospace field with the browser's text conveniences turned off. */
+export const Default: Story = {};
+
+/** Handles are read character by character, so the value is monospaced. */
+export const ComparedToInput: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      <craft-input .modelValue="${'entryType'}">
+        <label slot="label">craft-input</label>
+      </craft-input>
+      <craft-input-handle .modelValue="${'entryType'}">
+        <label slot="label">craft-input-handle</label>
+      </craft-input-handle>
+    </div>
+  `,
+};
+
+/**
+ * `autocorrect` is a boolean here, but it serialises as `on`/`off` rather than
+ * as a bare boolean attribute, which is how the native attribute spells it.
+ */
+export const AutocorrectOn: Story = {
+  args: {
+    autocorrect: true,
+    autocapitalize: 'sentences',
+    'help-text-slot':
+      'autocorrect="on" — the browser may correct what is typed.',
+  },
+};
+
+/** Everything from `craft-input` still applies, including the width rules. */
+export const WithMaxLength: Story = {
+  args: {maxlength: 12, 'help-text-slot': ''},
+};
+
+export const Disabled: Story = {
+  args: {disabled: true, 'help-text-slot': ''},
+};
diff --git a/packages/craftcms-ui/src/components/input-handle/input-handle.ts b/packages/craftcms-ui/src/components/input-handle/input-handle.ts
index 803fe1d01f5..67dd6006d68 100644
--- a/packages/craftcms-ui/src/components/input-handle/input-handle.ts
+++ b/packages/craftcms-ui/src/components/input-handle/input-handle.ts
@@ -2,6 +2,14 @@ import {css} from 'lit';
 import {property} from 'lit/decorators.js';
 import CraftInput from '@src/components/input/input.js';
 
+/**
+ * @summary A handle input — `craft-input` in a monospace face, with the
+ * browser's autocorrection and auto-capitalisation turned off.
+ *
+ * Handles are typed exactly and read character by character, so the two
+ * conveniences a browser applies to prose actively get in the way. Everything
+ * else comes from `craft-input`.
+ */
 export default class CraftInputHandle extends CraftInput {
   static override get styles() {
     return [
@@ -15,6 +23,11 @@ export default class CraftInputHandle extends CraftInput {
     ];
   }
 
+  /**
+   * Whether the browser may autocorrect the value. Off here, unlike on
+   * `craft-input`. Serialised as `on`/`off` rather than as a bare boolean
+   * attribute, matching the native attribute it drives.
+   */
   @property({
     reflect: true,
     converter: {
@@ -24,6 +37,9 @@ export default class CraftInputHandle extends CraftInput {
   })
   override autocorrect = false;
 
+  /**
+   * The native `autocapitalize` mode. `off` here, unlike on `craft-input`.
+   */
   @property({reflect: true, type: String})
   override autocapitalize = 'off';
 
diff --git a/packages/craftcms-ui/src/components/input-money/InputMoney.mdx b/packages/craftcms-ui/src/components/input-money/InputMoney.mdx
new file mode 100644
index 00000000000..26c3027c6c3
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-money/InputMoney.mdx
@@ -0,0 +1,55 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputMoneyStories from './input-money.stories';
+
+<Meta of={InputMoneyStories} name="Docs" />
+
+# Input Money
+
+`<craft-input-money>` is a field for an amount of money, formatted for a currency and a locale.
+
+<Canvas of={InputMoneyStories.Default} sourceState="shown" />
+
+It is [Input](?path=/docs/form-controls-text-controls-input--docs) with a mask over the top, so it carries the same label, help text, validation, and slots.
+
+## Why Not `type="number"`
+
+A native number field has no notion of thousands separators, shows spinner arrows that make no sense for money, and formats nothing.
+
+This is a masked text field instead.
+The mask is derived from `locale` and `currency` through `Intl.NumberFormat`, so the grouping character, the decimal character, and the number of decimal places are the ones that combination actually uses — rather than a guess baked into the component.
+
+<Canvas of={InputMoneyStories.LocalizedEuro} sourceState="shown" />
+
+That also means the decimal places follow the currency, not a fixed two:
+
+<Canvas of={InputMoneyStories.JapaneseYen} sourceState="shown" />
+
+Set `decimals`, `decimal-separator`, or `group-separator` to depart from the locale's own conventions.
+
+## Affordances
+
+Two pieces of chrome are on by default: the currency symbol beside the field, and a button that clears the amount once there is one.
+
+<Canvas of={InputMoneyStories.WithoutAffordances} sourceState="shown" />
+
+Both are **default-on string flags**: only the exact value `"false"` turns them off.
+A boolean binding cannot express that — `?show-currency="${false}"` removes the attribute, and an absent attribute reads as on.
+
+```html
+<craft-input-money show-currency="false" clearable="false"></craft-input-money>
+```
+
+## States
+
+<Canvas of={InputMoneyStories.Disabled} sourceState="shown" />
+
+## Accessibility
+
+The mask changes what a person sees as they type.
+Keep the help text explicit about the expected form when the locale's conventions are not the ones a reader would assume — a field that silently reformats input is harder to trust than one that says what it will do.
+
+The clear button is a real button with its own label. Everything else is announced as on [Input](?path=/docs/form-controls-text-controls-input--docs).
+
+## Properties
+
+<ArgTypes of={InputMoneyStories} />
diff --git a/packages/craftcms-ui/src/components/input-money/input-money.stories.ts b/packages/craftcms-ui/src/components/input-money/input-money.stories.ts
index 3dcc1351454..abd636c53f2 100644
--- a/packages/craftcms-ui/src/components/input-money/input-money.stories.ts
+++ b/packages/craftcms-ui/src/components/input-money/input-money.stories.ts
@@ -1,72 +1,79 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './input-money.js';
+import type CraftInputMoney from './input-money.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-money.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: the value is Lion's
+ * `modelValue`, a property rather than an attribute, and the label is a slot.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftInputMoney>('craft-input-money');
+
+type CraftInputMoneyArgs = CraftInputMoney & typeof args;
+
+/** The shell every story shares, so each one only supplies its args. */
+const field = (args: Record<string, unknown>) => html`
+  <craft-input-money
+    currency="${(args.currency as string) ?? 'USD'}"
+    locale="${(args.locale as string) ?? 'en-US'}"
+    show-currency="${String(args['show-currency'] ?? true)}"
+    clearable="${String(args.clearable ?? true)}"
+    ?disabled="${args.disabled}"
+    .modelValue="${args.value ?? ''}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${args['help-text-slot']
+      ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+      : ''}
+  </craft-input-money>
+`;
 
 const meta = {
-  title: 'Controls/Input Money',
+  title: 'Form Controls/Text Controls/Input Money',
   component: 'craft-input-money',
   args: {
-    label: 'Price',
+    ...args,
+    'label-slot': 'Price',
     value: '1,234.56',
     currency: 'USD',
     locale: 'en-US',
-    showCurrency: true,
-    clearable: true,
-    disabled: false,
   },
-  render: function ({
-    label,
-    value,
-    currency,
-    locale,
-    showCurrency,
-    clearable,
-    disabled,
-  }) {
-    return html`<craft-input-money
-      label=${label}
-      .modelValue=${value}
-      currency=${currency}
-      locale=${locale}
-      .showCurrency=${showCurrency}
-      .clearable=${clearable}
-      ?disabled=${disabled}
-    ></craft-input-money>`;
-  },
-} satisfies Meta<any>;
+  argTypes,
+  render: (args) => field(args),
+} satisfies Meta<CraftInputMoneyArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftInputMoneyArgs>;
 
+/** The mask is built from `locale` and `currency`. */
 export const Default: Story = {};
 
+/** A different locale changes the separators as well as the symbol. */
 export const LocalizedEuro: Story = {
-  args: {
-    value: '1.234,56',
-    currency: 'EUR',
-    locale: 'de-DE',
-  },
+  args: {value: '1.234,56', currency: 'EUR', locale: 'de-DE'},
 };
 
+/** A currency with no minor units drops the decimals. */
 export const JapaneseYen: Story = {
-  args: {
-    value: '123,456',
-    currency: 'JPY',
-    locale: 'ja-JP',
-  },
+  args: {value: '123,456', currency: 'JPY', locale: 'ja-JP'},
 };
 
+/**
+ * `show-currency` and `clearable` are on unless explicitly turned off, so they
+ * take the literal string `"false"` rather than a bare boolean attribute.
+ */
 export const WithoutAffordances: Story = {
-  args: {
-    showCurrency: false,
-    clearable: false,
-  },
+  args: {'show-currency': false, clearable: false},
 };
 
 export const Disabled: Story = {
-  args: {
-    disabled: true,
-  },
+  args: {disabled: true},
 };
diff --git a/packages/craftcms-ui/src/components/input-money/input-money.ts b/packages/craftcms-ui/src/components/input-money/input-money.ts
index 38972708e9d..3ad68f4f148 100644
--- a/packages/craftcms-ui/src/components/input-money/input-money.ts
+++ b/packages/craftcms-ui/src/components/input-money/input-money.ts
@@ -3,6 +3,7 @@ import {css, html, nothing, type PropertyValues} from 'lit';
 import {property} from 'lit/decorators.js';
 import {t} from '@src/utilities/translate';
 import CraftInput from '../input/input.js';
+import {defaultTrueBoolean} from '@src/utilities/converters';
 import '../button/button.js';
 import '../icon/icon.js';
 
@@ -14,17 +15,15 @@ type MaskedInput = HTMLInputElement & {
   };
 };
 
-const defaultTrueBooleanConverter = {
-  fromAttribute(value: string | null): boolean {
-    return value !== 'false';
-  },
-  toAttribute(value: boolean): string {
-    return String(value);
-  },
-};
-
 /**
  * @summary A locale-aware money input with a currency label and clear button.
+ * Extends `craft-input`, so it carries the same label, help text, validation,
+ * and slots.
+ *
+ * The field is a masked text input rather than `type="number"`: the mask is
+ * built from `locale` and `currency` via `Intl.NumberFormat`, so the grouping
+ * and decimal characters are the ones that locale actually uses. Override
+ * either separator to depart from that.
  *
  * @dependency craft-button
  * @dependency craft-icon
@@ -55,27 +54,49 @@ export default class CraftInputMoney extends CraftInput {
     ];
   }
 
+  /** ISO 4217 currency code, which sets the symbol and the decimal places. */
   @property() currency = 'USD';
 
+  /** Locale the amount is formatted for. Accepts `en-US` or `en_US`. */
   @property() locale = 'en-US';
 
+  /**
+   * Number of decimal places. Defaults to whatever the currency uses in this
+   * locale — two for most, none for yen.
+   */
   @property({type: Number}) decimals?: number;
 
+  /** Character separating the decimals. Defaults to the locale's own. */
   @property({attribute: 'decimal-separator'}) decimalSeparator?: string;
 
+  /** Character grouping the thousands. Defaults to the locale's own. */
   @property({attribute: 'group-separator'}) groupSeparator?: string;
 
+  /**
+   * Whether the currency symbol is shown beside the field. On by default —
+   * set `show-currency="false"` to hide it.
+   */
   @property({
-    converter: defaultTrueBooleanConverter,
+    converter: defaultTrueBoolean,
     attribute: 'show-currency',
   })
   showCurrency = true;
 
-  @property({converter: defaultTrueBooleanConverter}) clearable = true;
+  /**
+   * Whether a button to clear the amount is shown once there is one. On by
+   * default — set `clearable="false"` to remove it.
+   */
+  @property({converter: defaultTrueBoolean}) clearable = true;
+
+  /**
+   * Fixed to `text` rather than `number`: the value is a formatted, masked
+   * amount, and a number input would fight the grouping and currency symbols.
+   */
+  override type = 'text';
 
   constructor() {
     super();
-    this.type = 'text';
+
     this.inputMode = 'decimal';
   }
 
diff --git a/packages/craftcms-ui/src/components/input-password/InputPassword.mdx b/packages/craftcms-ui/src/components/input-password/InputPassword.mdx
new file mode 100644
index 00000000000..c617ed3c126
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-password/InputPassword.mdx
@@ -0,0 +1,27 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputPasswordStories from './input-password.stories';
+
+<Meta of={InputPasswordStories} name="Docs" />
+
+# Input Password
+
+`<craft-input-password>` is a password field with a button to reveal what has been typed.
+
+<Canvas of={InputPasswordStories.Default} sourceState="shown" />
+
+The button toggles the field between `password` and `text`, and renames itself "Show" or "Hide" as it goes, so the button always says what it is about to do.
+
+## Everything Else
+
+It is [Input](?path=/docs/form-controls-text-controls-input--docs) underneath, so the whole base surface applies — labelling, the width inference around `maxlength`, `size`, and the slots.
+
+## Accessibility
+
+The reveal button carries a real label that changes with the state, so it is announced as "Show" or "Hide" rather than as an unnamed button.
+
+Revealing a password puts it on screen in plain text.
+That is the point of the control, but it means the button should stay where the person expects it and should not be triggered by anything other than a deliberate press.
+
+## Properties
+
+<ArgTypes of={InputPasswordStories} />
diff --git a/packages/craftcms-ui/src/components/input-password/input-password.stories.ts b/packages/craftcms-ui/src/components/input-password/input-password.stories.ts
index 6c431d87a83..cf3b1b0751c 100644
--- a/packages/craftcms-ui/src/components/input-password/input-password.stories.ts
+++ b/packages/craftcms-ui/src/components/input-password/input-password.stories.ts
@@ -1,26 +1,62 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './input-password.js';
+import type CraftInputPassword from './input-password.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-password.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: the value is Lion's
+ * `modelValue`, a property rather than an attribute, and the label is a slot.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftInputPassword>(
+  'craft-input-password'
+);
+
+type CraftInputPasswordArgs = CraftInputPassword & typeof args;
+
+/** The shell every story shares, so each one only supplies its args. */
+const field = (args: Record<string, unknown>) => html`
+  <craft-input-password
+    ?disabled="${args.disabled}"
+    .modelValue="${args.value ?? ''}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${args['help-text-slot']
+      ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+      : ''}
+  </craft-input-password>
+`;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Input Password',
+  title: 'Form Controls/Text Controls/Input Password',
   component: 'craft-input-password',
-  args: {},
-  render: function () {
-    return html`<craft-input-password
-      label="Password"
-      help-text="Click the eye icon to show or hide the input"
-      value="SuperSecurePassword123"
-    ></craft-input-password>`;
+  args: {
+    ...args,
+    'label-slot': 'Password',
+    'help-text-slot': 'Use the eye button to show or hide what you typed.',
+    value: 'SuperSecurePassword123',
   },
-} satisfies Meta<any>;
+  argTypes,
+  render: (args) => field(args),
+} satisfies Meta<CraftInputPasswordArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftInputPasswordArgs>;
+
+/** The value is masked until the reveal button in the suffix is pressed. */
+export const Default: Story = {};
+
+/** An empty field, as it arrives on a sign-in form. */
+export const Empty: Story = {
+  args: {value: '', 'help-text-slot': ''},
+};
 
-export const Default: Story = {
-  args: {},
+export const Disabled: Story = {
+  args: {disabled: true, 'help-text-slot': ''},
 };
diff --git a/packages/craftcms-ui/src/components/input-password/input-password.ts b/packages/craftcms-ui/src/components/input-password/input-password.ts
index 635d257233a..bd8e723ead9 100644
--- a/packages/craftcms-ui/src/components/input-password/input-password.ts
+++ b/packages/craftcms-ui/src/components/input-password/input-password.ts
@@ -1,19 +1,31 @@
 import {css, html} from 'lit';
 import {state} from 'lit/decorators.js';
-import {LionInput} from '@lion/ui/input.js';
-import {inputStyles} from '@src/styles/form.styles';
+import CraftInput from '../input/input.js';
 import {t} from '@src/utilities/translate';
 import '../icon/icon.js';
 import '../button/button.js';
 
-export default class CraftInputPassword extends LionInput {
+/**
+ * @summary A password input with a button to reveal the value. The button
+ * toggles the field between `password` and `text`, and names itself "Show" or
+ * "Hide" as it goes.
+ *
+ * It extends `craft-input`, so everything on that control applies here too.
+ *
+ * @slot label - The control's label, as an alternative to the `label`
+ *   attribute.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages.
+ * @slot suffix - Supplied by the component: the reveal button. Slotting your
+ *   own replaces it.
+ */
+export default class CraftInputPassword extends CraftInput {
   @state()
   protected _visible = false;
 
   static override get styles() {
     return [
       ...super.styles,
-      inputStyles,
       css`
         .input-group__container {
           position: relative;
@@ -29,12 +41,18 @@ export default class CraftInputPassword extends LionInput {
     ];
   }
 
+  /**
+   * Starts at `password` and flips to `text` while the value is revealed, which
+   * is how the reveal button works.
+   */
+  override type = 'password';
+
   constructor() {
     super();
     this.type = 'password';
   }
 
-  reveal = () => {
+  protected reveal = () => {
     this._visible = !this._visible;
     this.type = this._visible ? 'text' : 'password';
   };
@@ -42,7 +60,7 @@ export default class CraftInputPassword extends LionInput {
   // Note: no leading/trailing whitespace inside the template — with
   // `renderAsDirectHostChild` every root node is appended to the host, and
   // text nodes don't get a slot attribute.
-  renderSuffix = () => {
+  protected renderSuffix = () => {
     return html`<craft-button
       type="button"
       icon
@@ -61,6 +79,9 @@ export default class CraftInputPassword extends LionInput {
     </craft-button>`;
   };
 
+  /**
+   * Adds the reveal button to the field, in the suffix slot.
+   */
   override get slots() {
     return {
       ...super.slots,
diff --git a/packages/craftcms-ui/src/components/input-time/InputTime.mdx b/packages/craftcms-ui/src/components/input-time/InputTime.mdx
new file mode 100644
index 00000000000..1d8fa8551ff
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-time/InputTime.mdx
@@ -0,0 +1,78 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputTimeStories from './input-time.stories';
+
+<Meta of={InputTimeStories} name="Docs" />
+
+# Input Time
+
+`<craft-input-time>` is a time input.
+It is [Input](?path=/docs/form-controls-text-controls-input--docs) with its `type` fixed to `time`, so it carries the same label, help text, validation, and slots, and renders the browser's own time picker.
+
+<Canvas of={InputTimeStories.Default} sourceState="shown" />
+
+Everything on the Input page applies here.
+On top of the native field this adds a stepping interval, a set of unselectable ranges, and optional rounding.
+
+## Values
+
+Values are `HH:MM` on a 24-hour clock, which is what the native time input exchanges regardless of whether the browser shows a 12-hour picker.
+
+## Stepping
+
+`minute-increment` sets the spacing between the picker's suggestions, in minutes.
+It is applied to the native input as `step`, so the browser's own stepping honours it:
+
+<Canvas of={InputTimeStories.MinuteIncrement} sourceState="shown" />
+
+A step does not stop someone typing a time between two of them.
+`force-round-time` closes that gap by snapping the value onto the nearest step when the field changes:
+
+<Canvas of={InputTimeStories.ForceRoundTime} sourceState="shown" />
+
+## Unavailable Times
+
+`disabled-time-ranges` takes an array of `[start, end]` pairs of `HH:MM` times.
+The start is inclusive and the end exclusive, so `["12:00", "13:00"]` blocks noon up to but not including one o'clock.
+
+```js
+input.disabledTimeRanges = [
+  ['12:00', '13:00'],
+  ['17:30', '18:00'],
+];
+```
+
+The name is worth reading carefully: the ranges are enforced by **validation**, not by the picker.
+A time inside a range is still selectable, and then fails with "This time is unavailable." rather than being absent from the list:
+
+<Canvas of={InputTimeStories.DisabledRanges} sourceState="shown" />
+
+## Bounding the Range
+
+`min` and `max` bound the range outright, in `HH:MM`.
+Like the date input's, both are **properties rather than attributes**, so bind them with `.min` / `.max`:
+
+<Canvas of={InputTimeStories.Bounded} sourceState="shown" />
+
+Use these when the whole field has a floor and a ceiling, and `disabled-time-ranges` when the gaps are in the middle.
+
+## States
+
+<Canvas of={InputTimeStories.Disabled} sourceState="shown" />
+
+<Canvas of={InputTimeStories.Readonly} sourceState="shown" />
+
+## Pairing With a Date
+
+To edit a date and a time as a single value, use [Input Date Time](?path=/docs/form-controls-text-controls-input-date-time--docs), which owns one of these and one [Input Date](?path=/docs/form-controls-text-controls-input-date--docs) and submits them together.
+It forwards `minute-increment`, `disabled-time-ranges`, and `force-round-time` straight through to this control.
+
+## Accessibility
+
+The native time input brings its own keyboard support and picker.
+
+The custom validity message is set on the native input, so it is announced the way any constraint-validation message is.
+Because an unavailable time is only rejected after it is chosen, say so in the help text as well — a person should not have to discover the rule by failing it.
+
+## Properties
+
+<ArgTypes of={InputTimeStories} />
diff --git a/packages/craftcms-ui/src/components/input-time/input-time.stories.ts b/packages/craftcms-ui/src/components/input-time/input-time.stories.ts
new file mode 100644
index 00000000000..cbeb9236dc7
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input-time/input-time.stories.ts
@@ -0,0 +1,95 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import './input-time.js';
+import type CraftInputTime from './input-time.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input-time.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftInputTime>('craft-input-time');
+
+type InputTimeArgs = CraftInputTime & typeof args;
+
+const meta = {
+  title: 'Form Controls/Text Controls/Input Time',
+  component: 'craft-input-time',
+  args: {...args, 'label-slot': 'Start Time'},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<InputTimeArgs>;
+
+export default meta;
+type Story = StoryObj<InputTimeArgs>;
+
+/** The browser's own time picker, with Craft's label and help text around it. */
+export const Default: Story = {};
+
+/**
+ * `minute-increment` sets the spacing between the picker's suggestions, in
+ * minutes. It is applied to the native input as `step`.
+ */
+export const MinuteIncrement: Story = {
+  args: {'minute-increment': 15, 'help-text-slot': 'Quarter-hour steps.'},
+};
+
+/**
+ * `force-round-time` snaps a typed time onto the nearest step when the field
+ * changes, rather than leaving an off-step value in place.
+ */
+export const ForceRoundTime: Story = {
+  args: {
+    'minute-increment': 15,
+    'force-round-time': true,
+    'help-text-slot': 'Type 09:07 and leave the field — it rounds to 09:00.',
+  },
+};
+
+/**
+ * `disabled-time-ranges` takes `[start, end]` pairs of `HH:MM` times. The start
+ * is inclusive and the end exclusive.
+ *
+ * The ranges are enforced by validation rather than by the picker: a time
+ * inside one is still selectable, and fails with "This time is unavailable."
+ */
+export const DisabledRanges: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-input-time
+      label="Start Time"
+      help-text="Noon to 1pm is unavailable — pick 12:30 to see it fail."
+      .disabledTimeRanges="${[['12:00', '13:00']]}"
+    ></craft-input-time>
+  `,
+};
+
+/**
+ * `min` and `max` bound the selectable range. Both are `HH:MM`, and both are
+ * properties rather than attributes — bind them with `.min` / `.max`.
+ */
+export const Bounded: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-input-time
+      label="Start Time"
+      help-text="Office hours only."
+      .min="${'09:00'}"
+      .max="${'17:00'}"
+    ></craft-input-time>
+  `,
+};
+
+export const Disabled: Story = {
+  args: {disabled: true},
+};
+
+export const Readonly: Story = {
+  args: {readonly: true},
+};
diff --git a/packages/craftcms-ui/src/components/input-time/input-time.ts b/packages/craftcms-ui/src/components/input-time/input-time.ts
index b62697abcbd..76535d16b79 100644
--- a/packages/craftcms-ui/src/components/input-time/input-time.ts
+++ b/packages/craftcms-ui/src/components/input-time/input-time.ts
@@ -1,28 +1,55 @@
 import {property} from 'lit/decorators.js';
 import type {PropertyValues} from 'lit';
 import CraftInput from '../input/input.js';
+import {jsonAttribute} from '@src/utilities/converters';
 
+/** A `[start, end]` pair of `HH:MM` times that cannot be selected. */
 export type DisabledTimeRange = [string, string];
 
+/**
+ * @summary A time input. `craft-input` with its `type` fixed to `time`, so it
+ * carries the same label, help text, validation, and slots, and renders the
+ * browser's own time picker.
+ *
+ * Values are `HH:MM`, and `min` and `max` take the same form. On top of the
+ * native field it adds a stepping interval, a set of unselectable ranges, and
+ * optional rounding. To edit a date and a time together, use
+ * `craft-input-date-time`.
+ */
 export default class CraftInputTime extends CraftInput {
+  /**
+   * Spacing between the picker's suggestions, in minutes. Applied to the
+   * native input as `step`.
+   */
   @property({type: Number, attribute: 'minute-increment'})
   minuteIncrement = 30;
 
+  /**
+   * Ranges that cannot be selected, as a JSON array of `[start, end]` pairs of
+   * `HH:MM` times — `[["12:00", "13:00"]]` blocks the lunch hour. The start
+   * is inclusive and the end exclusive. A time inside a range fails
+   * validation rather than being unselectable in the picker.
+   */
   @property({
     attribute: 'disabled-time-ranges',
-    converter: {
-      fromAttribute: (value) => JSON.parse(value ?? '[]'),
-      toAttribute: (value) => JSON.stringify(value),
-    },
+    converter: jsonAttribute<DisabledTimeRange[]>(() => []),
   })
   disabledTimeRanges: DisabledTimeRange[] = [];
 
+  /**
+   * Snaps a typed or picked time onto the nearest `minute-increment` step when
+   * the field changes.
+   */
   @property({type: Boolean, attribute: 'force-round-time'})
   forceRoundTime = false;
 
+  /**
+   * Fixed to `time`, so the browser renders its own time picker.
+   */
+  override type = 'time';
+
   constructor() {
     super();
-    this.type = 'time';
   }
 
   override connectedCallback() {
diff --git a/packages/craftcms-ui/src/components/input/Input.mdx b/packages/craftcms-ui/src/components/input/Input.mdx
new file mode 100644
index 00000000000..c6c698dd5e9
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input/Input.mdx
@@ -0,0 +1,93 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as InputStories from './input.stories';
+
+<Meta of={InputStories} name="Docs" />
+
+# Input
+
+`<craft-input>` is a single-line text input, and the base every other `craft-input-*` control extends.
+It is built on [Lion's input](https://lion.js.org/components/input/overview/), so it brings a label, help text, validation, and a `modelValue` alongside the native field.
+
+<Canvas of={InputStories.Default} sourceState="shown" />
+
+Everything on this page applies to the controls that extend it — [Input Date](?path=/docs/form-controls-text-controls-input-date--docs), [Input Time](?path=/docs/form-controls-text-controls-input-time--docs), Input Money, Input Copy, and the rest — which add behaviour on top rather than replacing any of it.
+
+## Labelling
+
+A bare input is unlabelled.
+Give it a label one of two ways: the `label` attribute for plain text, or the `label` slot when it needs markup.
+The same pairing applies to `help-text`.
+
+```html
+<craft-input label="Handle" help-text="Used in templates."></craft-input>
+
+<craft-input>
+  <span slot="label">Handle <code>handle</code></span>
+</craft-input>
+```
+
+Inside a form, wrapping in `craft-field` is usually better than labelling the input directly — the field owns the label, instructions, and error presentation for the whole row.
+
+## Width
+
+By default the control spans its column.
+Setting `maxlength` caps the value _and_ shrinks the control to the expected character width, so a four-character field does not stretch across the page:
+
+<Canvas of={InputStories.WithMaxLength} sourceState="shown" />
+
+`width` overrides that inference in either direction.
+`full` spans the column despite a `maxlength`:
+
+<Canvas of={InputStories.FullWidthOverride} sourceState="shown" />
+
+`auto` shrinks to the input's intrinsic width without needing one:
+
+<Canvas of={InputStories.AutoWidth} sourceState="shown" />
+
+## Presentation
+
+`size` steps the control's height:
+
+<Canvas of={InputStories.Sizes} sourceState="shown" />
+
+`monospace` renders the value in a monospace font, which suits handles, keys, and anything else read character by character:
+
+<Canvas of={InputStories.Monospace} sourceState="shown" />
+
+`center` centre-aligns the value, for short numeric fields where a left-aligned value looks stranded:
+
+<Canvas of={InputStories.Centered} sourceState="shown" />
+
+`hidden-input` visually hides the control while keeping it in the DOM and form-bound, so its value still submits.
+Reach for it when a field is populated programmatically but has to round-trip with the form.
+
+## Slots
+
+The control has eight slots, four of which are Lion's own plumbing.
+`prefix` and `suffix` sit _inside_ the control, alongside the input:
+
+<Canvas of={InputStories.WithPrefix} sourceState="shown" />
+
+<Canvas of={InputStories.WithSuffix} sourceState="shown" />
+
+`before` and `after` sit outside it.
+All eight are listed under [Properties](#properties).
+
+## Types
+
+`type` takes any native input type, and the control renders whatever the browser provides for it:
+
+<Canvas of={InputStories.Types} sourceState="shown" />
+
+Two types have components of their own, because they need more than the native field: [Input Date](?path=/docs/form-controls-text-controls-input-date--docs) and [Input Time](?path=/docs/form-controls-text-controls-input-time--docs).
+
+## Accessibility
+
+Lion wires the label, help text, and validation feedback to the input with `aria-labelledby` and `aria-describedby`, so a labelled input is announced correctly without further work.
+
+The thing to watch is an input with no label at all.
+Nothing stops you rendering one, and it is not announced as anything — so either set `label`, slot one, or wrap the control in `craft-field`.
+
+## Properties
+
+<ArgTypes of={InputStories} />
diff --git a/packages/craftcms-ui/src/components/input/input.stories.ts b/packages/craftcms-ui/src/components/input/input.stories.ts
index 9ff97f6a0e3..8db7e339e80 100644
--- a/packages/craftcms-ui/src/components/input/input.stories.ts
+++ b/packages/craftcms-ui/src/components/input/input.stories.ts
@@ -1,69 +1,122 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './input.js';
+import '../icon/icon.js';
+import type CraftInput from './input.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `input.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftInput>('craft-input');
+
+type InputArgs = CraftInput & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Input',
+  title: 'Form Controls/Text Controls/Input',
   component: 'craft-input',
   args: {
-    size: undefined,
-  },
-  argTypes: {
-    size: {
-      control: {type: 'number'},
-    },
-  },
-  render: function ({maxlength}) {
-    return html`<craft-input
-      label="Craft Input"
-      help-text="This is some instructions text"
-      placeholder="Placeholder value"
-      .maxlength="${maxlength}"
-    ></craft-input>`;
+    ...args,
+    // Lion's `label` and `help-text` are not in the manifest, so the helpers
+    // would drop them from `template()`. They are slots too, and slot args do
+    // reach the element.
+    'label-slot': 'Craft Input',
+    'help-text-slot': 'This is some instructions text',
   },
-} satisfies Meta<any>;
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<InputArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<InputArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** `label` and `help-text` come from Lion, as attributes or slots. */
+export const Default: Story = {};
 
+/**
+ * A `maxlength` both caps the value and shrinks the control to the expected
+ * character width.
+ */
 export const WithMaxLength: Story = {
-  args: {
-    maxlength: 5,
-  },
+  args: {maxlength: 5, 'label-slot': 'Port'},
 };
 
+/** `width="full"` spans the column even when a `maxlength` is set. */
+export const FullWidthOverride: Story = {
+  args: {maxlength: 6, width: 'full', 'label-slot': 'Port'},
+};
+
+/** `width="auto"` shrinks the control without requiring a `maxlength`. */
+export const AutoWidth: Story = {
+  args: {width: 'auto', 'label-slot': 'Handle'},
+};
+
+/** The `prefix` slot sits inside the control, before the input. */
 export const WithPrefix: Story = {
-  render: () => html`
-    <craft-input label="Search">
-      <craft-icon name="search" slot="prefix"></craft-icon>
-    </craft-input>
-  `,
+  args: {
+    'label-slot': 'Search',
+    'prefix-slot': '<craft-icon name="magnifying-glass"></craft-icon>',
+  },
 };
 
+/** The `suffix` slot sits inside the control, after the input. */
 export const WithSuffix: Story = {
-  render: () => html`
-    <craft-input label="Search">
-      <craft-icon name="search" slot="suffix"></craft-icon>
-    </craft-input>
-  `,
+  args: {
+    'label-slot': 'Search',
+    'suffix-slot': '<craft-icon name="magnifying-glass"></craft-icon>',
+  },
 };
 
-/** \`width="full"\` spans the column even when a \`maxlength\` is set. */
-export const FullWidthOverride: Story = {
+/** `monospace` renders the value in a monospace font. */
+export const Monospace: Story = {
+  args: {monospace: true, 'label-slot': 'Handle'},
+};
+
+/** `center` centre-aligns the value. */
+export const Centered: Story = {
+  args: {center: true, maxlength: 4, 'label-slot': 'Year'},
+};
+
+/** `size` steps the control's height. */
+export const Sizes: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
-    <craft-input label="Port" maxlength="6" width="full"></craft-input>
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${(['small', 'medium', 'large'] as const).map(
+        (size) =>
+          html`<craft-input
+            label='size="${size}"'
+            size="${size}"
+          ></craft-input>`
+      )}
+    </div>
   `,
 };
 
-/** \`width="auto"\` shrinks the control without requiring a \`maxlength\`. */
-export const AutoWidth: Story = {
-  render: () => html`<craft-input label="Handle" width="auto"></craft-input>`,
+/**
+ * `type` accepts any native input type. The date and time types have their own
+ * components — [Input Date](?path=/docs/form-controls-text-controls-input-date--docs) and
+ * [Input Time](?path=/docs/form-controls-text-controls-input-time--docs) — which add behaviour on
+ * top.
+ */
+export const Types: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.75rem">
+      ${(['text', 'email', 'url', 'number', 'password'] as const).map(
+        (type) =>
+          html`<craft-input
+            label='type="${type}"'
+            type="${type}"
+          ></craft-input>`
+      )}
+    </div>
+  `,
 };
diff --git a/packages/craftcms-ui/src/components/input/input.test.ts b/packages/craftcms-ui/src/components/input/input.test.ts
new file mode 100644
index 00000000000..5f89f2fed23
--- /dev/null
+++ b/packages/craftcms-ui/src/components/input/input.test.ts
@@ -0,0 +1,119 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './input.js';
+import type CraftInput from './input.js';
+
+async function createInput(
+  attrs: Record<string, string> = {},
+  innerHTML = '<label slot="label">Handle</label>'
+): Promise<CraftInput> {
+  const element = document.createElement('craft-input') as CraftInput;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  // Lion wires the label and feedback relations after its own first update,
+  // so give it a turn before reading them.
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+/** Lion's native input, which is the element the component drives. */
+function native(element: CraftInput): HTMLInputElement {
+  return element.querySelector('input')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-input', () => {
+  it('renders a native input with the label wired to it', async () => {
+    const element = await createInput();
+    const label = element.querySelector('label')!;
+
+    expect(native(element)).toBeTruthy();
+    // Lion rewrites the label's `for` to the id it generated for the input,
+    // which is what makes clicking the label focus the field.
+    expect(label.getAttribute('for')).toBe(native(element).id);
+    expect(native(element).id).not.toBe('');
+  });
+
+  it('defaults to a medium control', async () => {
+    expect((await createInput()).size).toBe('medium');
+  });
+
+  it('carries the value as Lion s modelValue', async () => {
+    const element = await createInput();
+
+    element.modelValue = 'entryType';
+    await element.updateComplete;
+
+    expect(native(element).value).toBe('entryType');
+  });
+
+  /**
+   * `maxlength` caps the value and is also the width hint: a four-character
+   * field should not stretch across the page.
+   */
+  it('applies maxlength to the native input', async () => {
+    const element = await createInput({maxlength: '12'});
+    await element.updateComplete;
+
+    expect(native(element).maxLength).toBe(12);
+  });
+
+  it('reflects the width override so the stylesheet can act on it', async () => {
+    const element = await createInput({maxlength: '4', width: 'full'});
+
+    expect(element.getAttribute('width')).toBe('full');
+  });
+
+  /** These are presentation flags the stylesheet keys off, so they reflect. */
+  it('reflects its presentation flags', async () => {
+    const element = await createInput({
+      monospace: '',
+      center: '',
+      small: '',
+    });
+
+    expect(element.monospace).toBe(true);
+    expect(element.center).toBe(true);
+    expect(element.hasAttribute('monospace')).toBe(true);
+    expect(element.hasAttribute('center')).toBe(true);
+  });
+
+  it('passes a type through to the native input', async () => {
+    const element = await createInput({type: 'email'});
+    await element.updateComplete;
+
+    expect(native(element).type).toBe('email');
+  });
+
+  it('disables the native input', async () => {
+    const element = await createInput({disabled: ''});
+    await element.updateComplete;
+
+    expect(native(element).disabled).toBe(true);
+  });
+
+  /**
+   * `inputSize`, `min`, `max`, and `step` are properties rather than
+   * attributes, and are synced onto the native input after render.
+   */
+  it('syncs the native-only properties onto the input', async () => {
+    const element = await createInput({type: 'number'});
+
+    element.min = 1;
+    element.max = 10;
+    element.step = 2;
+    await element.updateComplete;
+
+    expect(native(element).getAttribute('min')).toBe('1');
+    expect(native(element).getAttribute('max')).toBe('10');
+    expect(native(element).getAttribute('step')).toBe('2');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/input/input.ts b/packages/craftcms-ui/src/components/input/input.ts
index 2c98366817c..d3b048ea2ab 100644
--- a/packages/craftcms-ui/src/components/input/input.ts
+++ b/packages/craftcms-ui/src/components/input/input.ts
@@ -4,6 +4,32 @@ import styles from './input.styles.js';
 import type {PropertyValues} from 'lit';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary A single-line text input, and the base every other `craft-input-*`
+ * control extends. Built on Lion's input, so it brings a label, help text,
+ * validation, and a `modelValue` alongside the native field.
+ *
+ * Set `label` and `help-text` as attributes for plain text, or slot them when
+ * they need markup. Change `type` to get any of the native input types —
+ * `craft-input-date` and `craft-input-time` are exactly that, with the type
+ * fixed and a little behaviour added.
+ *
+ * A bare input is unlabelled; either give it a `label`, or wrap it in
+ * `craft-field`, which supplies the label and error handling for you.
+ *
+ * @slot input - The native input. Supplied by the component; you rarely touch
+ *   this.
+ * @slot label - The control's label, as an alternative to the `label`
+ *   attribute.
+ * @slot help-text - Guidance shown below the label, as an alternative to the
+ *   `help-text` attribute.
+ * @slot feedback - Validation messages. Lion fills this from the control's
+ *   validators.
+ * @slot prefix - Content inside the control, before the input.
+ * @slot suffix - Content inside the control, after the input.
+ * @slot before - Content outside the control, before it.
+ * @slot after - Content outside the control, after it.
+ */
 export default class CraftInput extends LionInput {
   static override get styles() {
     return [...super.styles, inputStyles, styles];
diff --git a/packages/craftcms-ui/src/components/manifest-coverage.test.ts b/packages/craftcms-ui/src/components/manifest-coverage.test.ts
new file mode 100644
index 00000000000..9807eac0e52
--- /dev/null
+++ b/packages/craftcms-ui/src/components/manifest-coverage.test.ts
@@ -0,0 +1,199 @@
+import {existsSync, globSync, readFileSync, statSync} from 'node:fs';
+import {join} from 'node:path';
+import {describe, expect, it} from 'vite-plus/test';
+
+/**
+ * The custom elements manifest is the canonical description of this package:
+ * Storybook's controls and API tables are generated from it, editors read it
+ * for IntelliSense, and consumers read it to find out what an element takes.
+ * Everything in it comes from JSDoc in the source, which means a new property
+ * lands undocumented by default and nothing complains.
+ *
+ * These checks hold the line at fully described. They read the built manifest,
+ * so run `npm run build:manifest` first — the `pretest` and `prestorybook`
+ * hooks already do.
+ */
+
+const MANIFEST = join(import.meta.dirname, '../../dist/custom-elements.json');
+
+interface Described {
+  name?: string;
+  description?: string;
+}
+
+interface Member extends Described {
+  privacy?: string;
+  kind?: string;
+}
+
+interface Declaration extends Described {
+  tagName?: string;
+  customElement?: boolean;
+  summary?: string;
+  attributes?: Described[];
+  slots?: Described[];
+  events?: Described[];
+  cssParts?: Described[];
+  cssProperties?: Described[];
+  members?: Member[];
+}
+
+const manifest = existsSync(MANIFEST)
+  ? (JSON.parse(readFileSync(MANIFEST, 'utf8')) as {
+      modules: {declarations?: Declaration[]}[];
+    })
+  : null;
+
+const elements = (manifest?.modules ?? [])
+  .flatMap((module) => module.declarations ?? [])
+  .filter((declaration) => declaration.customElement)
+  .sort((a, b) => (a.tagName ?? '').localeCompare(b.tagName ?? ''));
+
+const cases = elements.map((element) => ({
+  tag: element.tagName ?? element.name ?? 'unknown',
+  element,
+}));
+
+/**
+ * Placeholder API from the component scaffold. `craft-status` shipped with all
+ * of it — a slot, a part, a CSS property, and an event that never existed —
+ * described in the manifest as though it were real, which is worse than being
+ * undocumented.
+ */
+const SCAFFOLD_NAMES = new Set(['example', 'craft-event-name', '--example']);
+const SCAFFOLD_TEXT = /\b(lorem ipsum|some new status|tbd|todo|fixme)\b/i;
+
+describe('the manifest is built', () => {
+  it('exists', () => {
+    expect(
+      manifest,
+      `${MANIFEST} is missing — run \`npm run build:manifest\``
+    ).not.toBeNull();
+  });
+
+  /**
+   * Every check below reads the built manifest, so a stale one fails all of
+   * them at once and blames the components rather than the build. `npm test`
+   * rebuilds it first; running vitest directly does not, which is exactly when
+   * this happens.
+   */
+  it('is newer than the components it describes', () => {
+    const newest = globSync(join(import.meta.dirname, '*', '*.ts'))
+      .filter((file) => !/\.(test|stories|styles)\.ts$/.test(file))
+      .reduce((latest, file) => Math.max(latest, statSync(file).mtimeMs), 0);
+
+    expect(
+      statSync(MANIFEST).mtimeMs,
+      'the manifest is older than a component — run `npm run build:manifest`'
+    ).toBeGreaterThan(newest);
+  });
+
+  /** A guard that silently matches nothing would be worse than none at all. */
+  it('describes every custom element in the package', () => {
+    expect(elements.length).toBeGreaterThan(60);
+  });
+});
+
+describe('every element says what it is', () => {
+  it.each(cases)('$tag', ({element}) => {
+    expect(
+      element.summary ?? element.description ?? '',
+      `${element.tagName} has no @summary, so it is blank in the docs and in IntelliSense`
+    ).not.toBe('');
+  });
+});
+
+describe('every part of an element API is described', () => {
+  it.each(cases)('$tag', ({element}) => {
+    const undescribed: string[] = [];
+
+    for (const [kind, entries] of [
+      ['attribute', element.attributes],
+      ['slot', element.slots],
+      ['event', element.events],
+      ['CSS part', element.cssParts],
+      ['CSS property', element.cssProperties],
+    ] as const) {
+      for (const entry of entries ?? []) {
+        if (!entry.description) {
+          undescribed.push(`${kind} ${entry.name ?? '(unnamed)'}`);
+        }
+      }
+    }
+
+    expect(undescribed).toEqual([]);
+  });
+});
+
+describe('no scaffold placeholders survive into the manifest', () => {
+  it.each(cases)('$tag', ({element}) => {
+    const entries = [
+      ...(element.attributes ?? []),
+      ...(element.slots ?? []),
+      ...(element.events ?? []),
+      ...(element.cssParts ?? []),
+      ...(element.cssProperties ?? []),
+    ];
+
+    const placeholders = entries
+      .filter(
+        (entry) =>
+          SCAFFOLD_NAMES.has(entry.name ?? '') ||
+          SCAFFOLD_TEXT.test(entry.description ?? '')
+      )
+      .map((entry) => entry.name);
+
+    expect(placeholders).toEqual([]);
+    expect(SCAFFOLD_TEXT.test(element.summary ?? '')).toBe(false);
+  });
+});
+
+/**
+ * Lion assigns these in a constructor rather than declaring them, so the
+ * analyzer records the assignment as a member with nowhere to hang a comment.
+ * Redeclaring them to document them fails to type-check against Lion's own
+ * declarations, so they are named here instead of being silently tolerated.
+ */
+const UNDOCUMENTABLE = new Set([
+  'craft-combobox.modelValue',
+  'craft-combobox.defaultValidators',
+  'craft-combobox.autocomplete',
+]);
+
+describe('no internals are published as API', () => {
+  /**
+   * The analyzer records every class member it finds, so without filtering the
+   * property tables list things no consumer can call — `craft-permission-tree`
+   * advertised a `#treeId`. The manifest config drops anything `private`,
+   * `protected`, `#`-prefixed, or `_`-prefixed; this is the check that it did.
+   *
+   * A member that should be public must lose the prefix, not gain an exemption.
+   */
+  it.each(cases)('$tag', ({element}) => {
+    const internal = (element.members ?? [])
+      .filter(
+        (member) =>
+          member.privacy === 'private' ||
+          member.privacy === 'protected' ||
+          member.name?.startsWith('#') ||
+          member.name?.startsWith('_')
+      )
+      .map((member) => member.name);
+
+    expect(internal).toEqual([]);
+  });
+});
+
+describe('every public member is described', () => {
+  it.each(cases)('$tag', ({element}) => {
+    const undescribed = (element.members ?? [])
+      .filter(
+        (member) =>
+          !member.description &&
+          !UNDOCUMENTABLE.has(`${element.tagName}.${member.name}`)
+      )
+      .map((member) => member.name);
+
+    expect(undescribed).toEqual([]);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/missing-component/MissingComponent.mdx b/packages/craftcms-ui/src/components/missing-component/MissingComponent.mdx
new file mode 100644
index 00000000000..ef534401e8f
--- /dev/null
+++ b/packages/craftcms-ui/src/components/missing-component/MissingComponent.mdx
@@ -0,0 +1,32 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Components/Missing Component" />
+
+# Missing Component
+
+`<craft-missing-component>` renders in place of a component that could not be loaded.
+
+There are no stories here because the component only appears when something has gone wrong — a field type whose plugin is missing, disabled, or failed to load.
+
+```html
+<craft-missing-component
+  error="Unable to load the field type."
+  plugin-name="Super Table"
+></craft-missing-component>
+```
+
+## Why It Exists
+
+Without it, a page containing a broken component would either fail to render or show a gap where something used to be — and a gap tells a person nothing about what happened or how to fix it.
+
+Naming the plugin is the useful part. "Unable to load the field type" is a dead end; naming _which_ plugin is missing points at the action: install it, enable it, or remove the field.
+
+## Accessibility
+
+The message is text, so it is announced like any other content.
+
+The important property is that it is _in the flow_ rather than hidden behind an icon or a tooltip. A person who cannot see the broken layout still learns that something is missing and what it was.
+
+## Properties
+
+<ArgTypes of="craft-missing-component" />
diff --git a/packages/craftcms-ui/src/components/missing-component/missing-component.ts b/packages/craftcms-ui/src/components/missing-component/missing-component.ts
index 05a8b5d97d3..ba071cd18d6 100644
--- a/packages/craftcms-ui/src/components/missing-component/missing-component.ts
+++ b/packages/craftcms-ui/src/components/missing-component/missing-component.ts
@@ -1,6 +1,13 @@
 import {css, html, LitElement, nothing} from 'lit';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary Renders in place of a component that could not be loaded — a field
+ * type whose plugin is missing or disabled.
+ *
+ * It exists so a page with a broken component still renders, and says which
+ * component and which plugin rather than leaving a gap.
+ */
 export default class CraftMissingComponent extends LitElement {
   static override styles = css`
     :host {
@@ -59,8 +66,10 @@ export default class CraftMissingComponent extends LitElement {
     }
   `;
 
+  /** The message explaining why the component could not be loaded. */
   @property() error = '';
 
+  /** Name of the plugin the missing component belonged to. */
   @property({attribute: 'plugin-name'}) pluginName = '';
 
   protected override render() {
diff --git a/packages/craftcms-ui/src/components/nav-item/NavItem.mdx b/packages/craftcms-ui/src/components/nav-item/NavItem.mdx
new file mode 100644
index 00000000000..11ab92c91e0
--- /dev/null
+++ b/packages/craftcms-ui/src/components/nav-item/NavItem.mdx
@@ -0,0 +1,55 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as NavItemStories from './nav-item.stories';
+
+<Meta of={NavItemStories} name="Docs" />
+
+# Nav Item
+
+`<craft-nav-item>` is one entry in the control panel's navigation.
+
+<Canvas of={NavItemStories.Default} sourceState="shown" />
+
+Items belong inside a [Nav List](?path=/docs/components-nav-list--docs), which supplies the list semantics that make the group announce as a list with a count rather than as a run of loose links.
+
+## States and Markers
+
+`active` marks the entry for the current section:
+
+<Canvas of={NavItemStories.Active} sourceState="shown" />
+
+`indicator` adds a marker for something needing attention:
+
+<Canvas of={NavItemStories.WithIndicator} sourceState="shown" />
+
+`external` opens the link in a new tab and shows the external-link icon, so the behaviour is visible before the click rather than surprising after it.
+
+## Nested Navigation
+
+The `subnav` slot holds child items:
+
+<Canvas of={NavItemStories.WithChildren} sourceState="shown" />
+
+<Canvas of={NavItemStories.Group} sourceState="shown" />
+
+<Canvas of={NavItemStories.TogglePositionPrefix} sourceState="shown" />
+
+A subnav can belong to an item that is not itself a link:
+
+<Canvas of={NavItemStories.SubnavWithoutLabel} sourceState="shown" />
+
+## Collapsed Navigation
+
+`icon-only` collapses the item to its icon. The label is still announced, so the item keeps its name — and a subnav moves into a flyout rather than disappearing, which is what keeps the children reachable at any width.
+
+## Accessibility
+
+The item is a link, so it is focusable and activates on Enter without help.
+
+Two things are worth attention:
+
+- **`icon-only` hides the label visually, not from assistive technology.** A collapsed navigation is still fully named. Do not "help" by removing the label.
+- **`active` is presentational.** Marking the current page for a screen reader is `aria-current`, which the surrounding navigation should set — the colour alone does not announce anything.
+
+## Properties
+
+<ArgTypes of={NavItemStories} />
diff --git a/packages/craftcms-ui/src/components/nav-item/nav-item.stories.ts b/packages/craftcms-ui/src/components/nav-item/nav-item.stories.ts
index 8dca2a6d080..4cb5675373d 100644
--- a/packages/craftcms-ui/src/components/nav-item/nav-item.stories.ts
+++ b/packages/craftcms-ui/src/components/nav-item/nav-item.stories.ts
@@ -1,17 +1,30 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 
 import '../icon/icon.js';
 import '../nav-list/nav-list.js';
 import '../button/button.js';
 import './nav-item.js';
+import type CraftNavItem from './nav-item.js';
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `nav-item.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftNavItem>('craft-nav-item');
+
+type CraftNavItemArgs = CraftNavItem & typeof args;
+
 const meta = {
   title: 'Components/Nav Item',
   component: 'craft-nav-item',
-  argTypes: {},
+  args,
+  argTypes,
   parameters: {
     a11y: {
       config: {
@@ -40,10 +53,10 @@ const meta = {
       </craft-nav-list>
     `;
   },
-} satisfies Meta<any>;
+} satisfies Meta<CraftNavItemArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftNavItemArgs>;
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
 export const Default: Story = {
   args: {},
diff --git a/packages/craftcms-ui/src/components/nav-item/nav-item.ts b/packages/craftcms-ui/src/components/nav-item/nav-item.ts
index 135ebe1d260..804e1d7409e 100644
--- a/packages/craftcms-ui/src/components/nav-item/nav-item.ts
+++ b/packages/craftcms-ui/src/components/nav-item/nav-item.ts
@@ -11,7 +11,18 @@ import {classMap} from 'lit/directives/class-map.js';
 import {Appearance} from '@src/constants/appearances';
 
 /**
+ * @summary One entry in the control panel's navigation — a link with an
+ * optional icon, an indicator, and a nested subnav.
  *
+ * Items live inside a `craft-nav-list`, which supplies the list semantics that
+ * make the group announce as a list rather than as loose links.
+ *
+ * When the navigation is collapsed to icons, an item with a subnav shows it in
+ * a flyout instead of inline, so the children stay reachable at any width.
+ *
+ * @slot - The item's label.
+ * @slot subnav - Nested `craft-nav-item`s, shown beneath the item or in a
+ *   flyout when collapsed.
  */
 export default class CraftNavItem extends LitElement {
   static override styles = styles;
@@ -36,9 +47,17 @@ export default class CraftNavItem extends LitElement {
   @property({type: Boolean})
   indicator: boolean = false;
 
+  /**
+   * Id of the item, used to tie a subnav to the item that owns it. Generated
+   * when not supplied.
+   */
   @property()
   override id: string;
 
+  /**
+   * Collapses the item to its icon, hiding the label. The label is still
+   * announced, and a subnav moves into a flyout rather than disappearing.
+   */
   @property({reflect: true, type: Boolean, attribute: 'icon-only'})
   iconOnly: boolean = false;
 
@@ -64,7 +83,7 @@ export default class CraftNavItem extends LitElement {
   togglePosition: 'prefix' | 'suffix' = 'suffix';
 
   @state()
-  subnavState: string = 'closed';
+  protected subnavState: string = 'closed';
 
   /**
    * Whether the icon-only flyout is showing. Collapsed to an icon, an item has
@@ -142,13 +161,19 @@ export default class CraftNavItem extends LitElement {
     this.flyoutOpen = (event.target as {opened?: boolean}).opened === true;
   };
 
+  /**
+
+   * Expands or collapses the subnav.
+
+   */
+
   toggleSubnav(event: Event) {
     event.preventDefault();
     event.stopPropagation();
     this.subnavState = this.subnavState === 'open' ? 'closed' : 'open';
   }
 
-  renderIconItem(hasSubnav: boolean) {
+  protected renderIconItem(hasSubnav: boolean) {
     const itemId = `item-${this.id}`;
     // Without an href there's nothing to link to, so render a plain span.
     const tag = this.href ? literal`a` : literal`span`;
@@ -189,7 +214,7 @@ export default class CraftNavItem extends LitElement {
     `;
   }
 
-  renderSubnavToggle() {
+  protected renderSubnavToggle() {
     return html`
       <craft-button
         @click="${this.toggleSubnav}"
@@ -212,7 +237,7 @@ export default class CraftNavItem extends LitElement {
     `;
   }
 
-  renderPrefix(showToggle: boolean = false) {
+  protected renderPrefix(showToggle: boolean = false) {
     if (showToggle && this.togglePosition === 'prefix') {
       return html`
         <span class="nav-item__prefix">${this.renderSubnavToggle()}</span>
@@ -240,7 +265,7 @@ export default class CraftNavItem extends LitElement {
     `;
   }
 
-  renderSuffix(showToggle: boolean = false) {
+  protected renderSuffix(showToggle: boolean = false) {
     return html`
       <div class="nav-item__suffix">
         <slot name="suffix">
@@ -252,7 +277,7 @@ export default class CraftNavItem extends LitElement {
     `;
   }
 
-  renderItem(showToggle: boolean, hasPrefix: boolean = false) {
+  protected renderItem(showToggle: boolean, hasPrefix: boolean = false) {
     // Without an href there's nothing to link to, so render a plain span.
     const tag = this.href ? literal`a` : literal`span`;
 
diff --git a/packages/craftcms-ui/src/components/nav-list/NavList.mdx b/packages/craftcms-ui/src/components/nav-list/NavList.mdx
new file mode 100644
index 00000000000..7851552b9c4
--- /dev/null
+++ b/packages/craftcms-ui/src/components/nav-list/NavList.mdx
@@ -0,0 +1,22 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as NavListStories from './nav-list.stories';
+
+<Meta of={NavListStories} name="Docs" />
+
+# Nav List
+
+`<craft-nav-list>` wraps a set of [Nav Item](?path=/docs/components-nav-item--docs)s in a real list.
+
+<Canvas of={NavListStories.Default} sourceState="shown" />
+
+It contributes two things and nothing else: the `<ul>` semantics, and the spacing between items. The items carry their own appearance.
+
+## Why the List Matters
+
+A run of links in a `<div>` is announced one at a time, with no sense of how many there are or where you are among them. Inside a list, a screen reader says "list, 5 items" and numbers them as you move.
+
+That is the whole reason this component exists rather than a wrapper `<div>` — and it is why nav items belong inside one even when the visual result looks identical.
+
+## Properties
+
+<ArgTypes of={NavListStories} />
diff --git a/packages/craftcms-ui/src/components/nav-list/nav-list.stories.ts b/packages/craftcms-ui/src/components/nav-list/nav-list.stories.ts
index d04e0a9cee6..58073c88b07 100644
--- a/packages/craftcms-ui/src/components/nav-list/nav-list.stories.ts
+++ b/packages/craftcms-ui/src/components/nav-list/nav-list.stories.ts
@@ -1,16 +1,36 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import '../icon/icon.js';
 import '../nav-item/nav-item.js';
 import './nav-list.js';
+import type CraftNavList from './nav-list.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `nav-list.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftNavList>('craft-nav-list');
+
+type NavListArgs = CraftNavList & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Nav List',
   component: 'craft-nav-list',
-  argTypes: {},
+  args: {
+    ...args,
+    'default-slot': `
+      <craft-nav-item icon="gauge" active>Dashboard</craft-nav-item>
+      <craft-nav-item icon="pencil">Entries</craft-nav-item>
+      <craft-nav-item icon="image">Assets</craft-nav-item>
+      <craft-nav-item icon="users">Users</craft-nav-item>
+    `,
+  },
+  argTypes,
   parameters: {
     a11y: {
       config: {
@@ -27,29 +47,21 @@ const meta = {
       },
     },
   },
-  render: () => {
-    return html`
-      <craft-nav-list style="max-width: 300px">
-        <craft-nav-item icon="gauge" active>Dashboard</craft-nav-item>
-        <craft-nav-item icon="pencil">Entries</craft-nav-item>
-        <craft-nav-item icon="image">Assets</craft-nav-item>
-        <craft-nav-item icon="users">Users</craft-nav-item>
-      </craft-nav-list>
-    `;
-  },
-} satisfies Meta<any>;
+  // Render from args alone so the slot control drives the story. The
+  // composition stories below supply their own markup instead, and disable the
+  // controls that no longer reach them.
+  render: (args) => template(args),
+} satisfies Meta<NavListArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<NavListArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** A flat list of items. */
+export const Default: Story = {};
 
 /** Nested in a nav item's `subnav` slot for a collapsible hierarchy. */
 export const Nested: Story = {
-  args: {},
+  parameters: {controls: {disable: true}},
   render() {
     return html`
       <craft-nav-list style="max-width: 300px">
@@ -82,7 +94,7 @@ export const Nested: Story = {
  * - Grouped children carry a `data-group` attribute naming their heading.
  */
 export const ContentSources: Story = {
-  args: {},
+  parameters: {controls: {disable: true}},
   render() {
     return html`
       <craft-nav-list style="max-width: 300px">
@@ -129,7 +141,7 @@ export const ContentSources: Story = {
  * no toggle, subnav always open.
  */
 export const SecondaryNav: Story = {
-  args: {},
+  parameters: {controls: {disable: true}},
   render() {
     return html`
       <craft-nav-list style="max-width: 300px">
@@ -168,7 +180,7 @@ export const SecondaryNav: Story = {
  * an `icon` and slotted label text.
  */
 export const IconOnly: Story = {
-  args: {},
+  parameters: {controls: {disable: true}},
   render() {
     return html`
       <craft-nav-list>
diff --git a/packages/craftcms-ui/src/components/nav-list/nav-list.test.ts b/packages/craftcms-ui/src/components/nav-list/nav-list.test.ts
new file mode 100644
index 00000000000..347dfaf5c8b
--- /dev/null
+++ b/packages/craftcms-ui/src/components/nav-list/nav-list.test.ts
@@ -0,0 +1,52 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './nav-list.js';
+import '../nav-item/nav-item.js';
+import type CraftNavList from './nav-list.js';
+
+async function createNavList(innerHTML = ''): Promise<CraftNavList> {
+  const element = document.createElement('craft-nav-list') as CraftNavList;
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-nav-list', () => {
+  /**
+   * The list element is what makes a run of nav items a list to a screen
+   * reader, which is how it announces how many there are and where you are in
+   * them.
+   */
+  it('renders a list around its items', async () => {
+    const element = await createNavList(
+      '<craft-nav-item>Entries</craft-nav-item>'
+    );
+
+    expect(element.shadowRoot!.querySelector('ul')).toBeTruthy();
+    expect(element.shadowRoot!.querySelector('slot')).toBeTruthy();
+  });
+
+  it('takes its items from the default slot', async () => {
+    const element = await createNavList(`
+      <craft-nav-item>Entries</craft-nav-item>
+      <craft-nav-item>Assets</craft-nav-item>
+    `);
+
+    const slot = element.shadowRoot!.querySelector('slot')!;
+
+    expect(
+      slot.assignedElements().map((item) => item.tagName.toLowerCase())
+    ).toEqual(['craft-nav-item', 'craft-nav-item']);
+  });
+
+  it('renders an empty list rather than nothing', async () => {
+    const element = await createNavList();
+
+    expect(element.shadowRoot!.querySelector('ul')).toBeTruthy();
+  });
+});
diff --git a/packages/craftcms-ui/src/components/nav-list/nav-list.ts b/packages/craftcms-ui/src/components/nav-list/nav-list.ts
index e31be9b468e..d459a4d422a 100644
--- a/packages/craftcms-ui/src/components/nav-list/nav-list.ts
+++ b/packages/craftcms-ui/src/components/nav-list/nav-list.ts
@@ -1,5 +1,15 @@
 import {css, html, LitElement} from 'lit';
 
+/**
+ * @summary A list wrapper for `craft-nav-item`s. Renders a real `<ul>` around
+ * them, so the group is announced as a list with a count rather than as a run
+ * of loose links.
+ *
+ * It supplies the list semantics and the spacing between items, and nothing
+ * else — the items carry their own appearance.
+ *
+ * @slot - The `craft-nav-item`s making up the list.
+ */
 export default class CraftNavList extends LitElement {
   static override styles = css`
     :host {
diff --git a/packages/craftcms-ui/src/components/option/Option.mdx b/packages/craftcms-ui/src/components/option/Option.mdx
new file mode 100644
index 00000000000..a408f578ce1
--- /dev/null
+++ b/packages/craftcms-ui/src/components/option/Option.mdx
@@ -0,0 +1,41 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Form Controls/Select Controls/Option" />
+
+# Option
+
+`<craft-option>` is one entry inside a [Select Rich](?path=/docs/form-controls-select-controls-select-rich--docs) or a [Combobox](?path=/docs/form-controls-select-controls-combobox--docs).
+
+There are no stories on this page because an option outside a listbox has nothing to belong to. See either parent's page for working examples.
+
+```html
+<craft-select-rich label="Entry type">
+  <craft-option .choiceValue="${'article'}" hint="article">
+    <craft-icon name="newspaper"></craft-icon>
+    Article
+  </craft-option>
+</craft-select-rich>
+```
+
+## What It Adds
+
+Over a native `<option>`, two things:
+
+- **Arbitrary markup.** An icon, a status, a thumbnail — anything that helps a person recognise the entry.
+- **A hint.** Secondary text after the label, rendered quieter: a handle, a count, a short qualifier.
+
+## Responsive Layout
+
+Options widen their layout once they have room, measured against the option itself rather than the viewport.
+
+That means the same list reads sensibly in a narrow slideout and on a wide page without the parent configuring anything. The threshold is `--c-option-wide-threshold`, defaulting to 640 pixels.
+
+## Accessibility
+
+Lion supplies the option semantics and selection state.
+
+Remember that everything inside the option is announced. A decorative icon should be hidden, or every entry in the list will be read with the same prefix before the part that distinguishes it.
+
+## Properties
+
+<ArgTypes of="craft-option" />
diff --git a/packages/craftcms-ui/src/components/option/option.test.ts b/packages/craftcms-ui/src/components/option/option.test.ts
new file mode 100644
index 00000000000..daa7dbd1e5c
--- /dev/null
+++ b/packages/craftcms-ui/src/components/option/option.test.ts
@@ -0,0 +1,66 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './option.js';
+import type CraftOption from './option.js';
+
+async function createOption(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Blog'
+): Promise<CraftOption> {
+  const element = document.createElement('craft-option') as CraftOption;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-option', () => {
+  /** The label is slotted, which is what lets an option hold markup. */
+  it('renders its label from the default slot', async () => {
+    const element = await createOption();
+
+    expect(element.shadowRoot!.querySelector('slot:not([name])')).toBeTruthy();
+    expect(element.textContent).toBe('Blog');
+  });
+
+  it('renders no hint unless one is set', async () => {
+    const element = await createOption();
+
+    expect(element.shadowRoot!.querySelector('.hint')).toBeNull();
+  });
+
+  it('renders a hint after the label', async () => {
+    const element = await createOption({hint: '12 entries'});
+
+    expect(
+      element.shadowRoot!.querySelector('.hint')?.textContent?.trim()
+    ).toBe('12 entries');
+  });
+
+  it('offers a suffix slot for trailing content', async () => {
+    const element = await createOption();
+
+    expect(
+      element.shadowRoot!.querySelector('slot[name="suffix"]')
+    ).toBeTruthy();
+  });
+
+  /**
+   * The value is Lion's `choiceValue`, a property rather than an attribute, so
+   * an option can carry a value that is not a string.
+   */
+  it('carries its value as choiceValue', async () => {
+    const element = await createOption();
+
+    element.choiceValue = 'blog';
+
+    expect(element.choiceValue).toBe('blog');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/option/option.ts b/packages/craftcms-ui/src/components/option/option.ts
index 70fb20eb0b4..ba3e504fd77 100644
--- a/packages/craftcms-ui/src/components/option/option.ts
+++ b/packages/craftcms-ui/src/components/option/option.ts
@@ -3,6 +3,21 @@ import {LionOption} from '@lion/ui/listbox.js';
 import {html, nothing} from 'lit';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary One option inside `craft-select-rich` or `craft-combobox`. Unlike a
+ * native `<option>` it can hold arbitrary markup — an icon, a status, a
+ * thumbnail — alongside its label.
+ *
+ * Options widen their layout once they have room for it, measured against the
+ * option rather than the viewport, so the same list reads sensibly in a narrow
+ * slideout and a wide page.
+ *
+ * @slot - The option's label and any markup that goes with it.
+ * @slot suffix - Trailing content, shown after the label and hint.
+ *
+ * @cssproperty --c-option-wide-threshold - Width, in pixels, past which the
+ *   option switches to its wide layout. Defaults to `640`.
+ */
 export default class CraftOption extends LionOption {
   static override get styles() {
     return [...LionOption.styles, styles];
@@ -23,6 +38,10 @@ export default class CraftOption extends LionOption {
     }
   });
 
+  /**
+   * Secondary text shown after the label — a handle, a count, a short
+   * qualifier. Rendered quieter than the label rather than as part of it.
+   */
   @property()
   hint?: string | null = null;
 
diff --git a/packages/craftcms-ui/src/components/pane/Pane.mdx b/packages/craftcms-ui/src/components/pane/Pane.mdx
new file mode 100644
index 00000000000..de59563e311
--- /dev/null
+++ b/packages/craftcms-ui/src/components/pane/Pane.mdx
@@ -0,0 +1,92 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as PaneStories from './pane.stories';
+
+<Meta of={PaneStories} name="Docs" />
+
+# Pane
+
+`<craft-pane>` is the control panel's primary content surface — a padded, rounded container with optional header and footer regions.
+
+<Canvas of={PaneStories.Default} sourceState="shown" />
+
+Panes wrap page sections, forms, tables, and modal bodies. It is the most-used component in the library, and the one that gives a page its structure.
+
+For a block that represents a _thing_ rather than a section of a page — an entry, an asset, a user — use [Card](?path=/docs/components-card--docs).
+
+## Appearance and Variant
+
+The two are orthogonal and combine freely. `appearance` picks the surface treatment:
+
+<Canvas of={PaneStories.Appearance} sourceState="shown" />
+
+`variant` layers a semantic treatment on top:
+
+<Canvas of={PaneStories.Variant} sourceState="shown" />
+
+## Regions
+
+Header and footer each render only when there is something in them, so a pane holding only body content is a plain padded surface.
+
+<Canvas of={PaneStories.WithHeader} sourceState="shown" />
+
+<Canvas of={PaneStories.WithHeaderActions} sourceState="shown" />
+
+<Canvas of={PaneStories.WithFooter} sourceState="shown" />
+
+The footer is built for form actions, with dedicated slots for a primary action, a secondary action, and feedback:
+
+<Canvas of={PaneStories.WithFooterActions} sourceState="shown" />
+
+<Canvas of={PaneStories.FullComposition} sourceState="shown" />
+
+Slotting `header` or `footer` replaces that whole region, padding included — for when the default layout is not what you want:
+
+<Canvas of={PaneStories.CustomRegions} sourceState="shown" />
+
+<Canvas of={PaneStories.CustomTitle} sourceState="shown" />
+
+## Scrolling
+
+A pane that clamps its height scrolls its content — either through `variant="code"` or by setting `--c-pane-max-block-size`:
+
+<Canvas of={PaneStories.ScrollableCode} sourceState="shown" />
+
+**A scrolling region has to be reachable by keyboard.** Someone using a keyboard or a switch with no pointer otherwise cannot read past the clamp, which fails WCAG 2.1.1.
+
+So when — and only when — the content actually overflows, the pane makes its own scroll container a labelled tab stop. It is conditional because a tab stop that cannot scroll anywhere is a focus trap with nothing to do.
+
+Do not put `tabindex` on the host yourself. The host is not the scroller, and browsers only scroll the focused element or a scrollable _ancestor_ of it — never a descendant.
+
+## Padding
+
+`padding` takes the shared spacing scale, defaulting to `lg`:
+
+<Canvas of={PaneStories.Padding} sourceState="shown" />
+
+Values off that scale are ignored; set `--c-pane-padding` for anything else. This is the same `Paddable` behaviour [Callout](?path=/docs/components-callout--docs) uses.
+
+## Styling
+
+<Canvas of={PaneStories.CustomProperties} sourceState="shown" />
+
+The pane exposes seven CSS parts — `base`, `header`, `title`, `header-actions`, `body`, `footer`, and `footer-actions` — and thirteen custom properties. Both are listed under [Properties](#properties).
+
+`base` is the outermost element and the scroll container, so it is the one carrying the surface treatment and, when content overflows, the focus ring.
+
+## Accessibility
+
+The `label` renders as a heading in the header, which puts the pane in the document outline.
+
+It renders at `heading-level`, which defaults to `2`. A CP page has its own `<h1>`, and pages routinely stack two or three panes, so a pane that claimed `<h1>` would flatten the heading list a screen reader navigates by.
+
+Set `heading-level="1"` for a pane that really is the page's main heading, or a deeper level for a nested one:
+
+```html
+<craft-pane label="Settings" heading-level="3"></craft-pane>
+```
+
+Slotting your own heading into `title` still overrides all of this.
+
+## Properties
+
+<ArgTypes of={PaneStories} />
diff --git a/packages/craftcms-ui/src/components/pane/heading-level.test.ts b/packages/craftcms-ui/src/components/pane/heading-level.test.ts
new file mode 100644
index 00000000000..c85819ff1da
--- /dev/null
+++ b/packages/craftcms-ui/src/components/pane/heading-level.test.ts
@@ -0,0 +1,53 @@
+import {expect, test} from 'vite-plus/test';
+import {html, render} from 'lit';
+
+import './pane.js';
+import type CraftPane from './pane.js';
+
+async function mount(template: unknown): Promise<CraftPane> {
+  const host = document.createElement('div');
+  document.body.append(host);
+  render(template as never, host);
+  const pane = host.firstElementChild as CraftPane;
+  await pane.updateComplete;
+  return pane;
+}
+
+function heading(pane: CraftPane): string | undefined {
+  return pane.shadowRoot
+    ?.querySelector('.cp-pane__title')
+    ?.tagName.toLowerCase();
+}
+
+test('defaults to h2, below the page its own h1', async () => {
+  const pane = await mount(html`<craft-pane label="Settings"></craft-pane>`);
+  expect(heading(pane)).toBe('h2');
+});
+
+test('honours an explicit level', async () => {
+  const pane = await mount(
+    html`<craft-pane label="Settings" heading-level="3"></craft-pane>`
+  );
+  expect(heading(pane)).toBe('h3');
+});
+
+test('a pane that is the page heading can ask for h1', async () => {
+  const pane = await mount(
+    html`<craft-pane label="Settings" heading-level="1"></craft-pane>`
+  );
+  expect(heading(pane)).toBe('h1');
+});
+
+test('clamps a level outside the six real headings', async () => {
+  const pane = await mount(
+    html`<craft-pane label="Settings" heading-level="9"></craft-pane>`
+  );
+  expect(heading(pane)).toBe('h6');
+});
+
+test('renders the label as the heading text', async () => {
+  const pane = await mount(html`<craft-pane label="Settings"></craft-pane>`);
+  expect(
+    pane.shadowRoot?.querySelector('.cp-pane__title')?.textContent?.trim()
+  ).toBe('Settings');
+});
diff --git a/packages/craftcms-ui/src/components/pane/pane.stories.ts b/packages/craftcms-ui/src/components/pane/pane.stories.ts
index 5e712c350c2..401dfadf03e 100644
--- a/packages/craftcms-ui/src/components/pane/pane.stories.ts
+++ b/packages/craftcms-ui/src/components/pane/pane.stories.ts
@@ -7,6 +7,18 @@ const {events, args, argTypes, template} = getStorybookHelpers('craft-pane');
 import './pane.js';
 import '../button/button.js';
 import '../icon/icon.js';
+import {SPACING_STEPS} from '@src/mixins/Paddable.js';
+
+/**
+ * `padding` is supplied by the `Paddable` mixin, so the analyzer records no
+ * resolvable type for it and the helpers cannot derive a control. Build one
+ * from the same constant the mixin resolves against, rather than restating
+ * the values by hand.
+ */
+const paddingArgType = {
+  control: {type: 'select'},
+  options: [...SPACING_STEPS, 'none', '0'],
+} as const;
 
 const bodyCopy = html`
   Panes are the primary CP content surface — a padded, rounded container with
@@ -27,7 +39,7 @@ const meta: Meta<CraftPane> = {
     ...args,
     label: '',
   },
-  argTypes,
+  argTypes: {...argTypes, padding: paddingArgType},
   render: (args) => template(args, bodyCopy),
   parameters: {
     actions: {
@@ -140,8 +152,8 @@ export const ScrollableCode: Story = {
 };
 
 /**
- * `padding` takes the `sm`/`md`/`lg`/`xl` steps, `0`, a unitless number
- * (pixels), or any CSS length.
+ * `padding` takes the `sm`/`md`/`lg`/`xl` steps, or `0`/`none`. For a value
+ * off that scale, set `--c-pane-padding` instead.
  */
 export const Padding: Story = {
   render: () => html`
@@ -150,7 +162,6 @@ export const Padding: Story = {
       <craft-pane padding="md">padding="md"</craft-pane>
       <craft-pane padding="lg">padding="lg" (default)</craft-pane>
       <craft-pane padding="xl">padding="xl"</craft-pane>
-      <craft-pane padding="24">padding="24" (24px)</craft-pane>
       <craft-pane padding="0">
         <div
           style="padding: 0.5rem; background: var(--c-color-neutral-fill-quiet);"
@@ -158,6 +169,9 @@ export const Padding: Story = {
           padding="0" — edge-to-edge content, e.g. a table
         </div>
       </craft-pane>
+      <craft-pane style="--c-pane-padding: 2.5rem"
+        >--c-pane-padding: 2.5rem — a value off the scale</craft-pane
+      >
     </div>
   `,
 };
diff --git a/packages/craftcms-ui/src/components/pane/pane.test.ts b/packages/craftcms-ui/src/components/pane/pane.test.ts
index 074546051ad..6d8b4ebf756 100644
--- a/packages/craftcms-ui/src/components/pane/pane.test.ts
+++ b/packages/craftcms-ui/src/components/pane/pane.test.ts
@@ -241,17 +241,19 @@ describe('craft-pane padding', () => {
     expect(spacing(element)).toBe('0');
   });
 
-  it('treats numeric values as pixels', async () => {
-    const element = await createPane({padding: '24'});
-
-    expect(spacing(element)).toBe('calc(24rem / 16)');
-  });
-
-  it('passes any other value through verbatim', async () => {
-    const element = await createPane({padding: 'var(--my-spacing)'});
+  /**
+   * The attribute is closed to the spacing scale. An off-scale value writes
+   * nothing, so `--c-pane-padding` and the stylesheet default still apply —
+   * which is the escape hatch for arbitrary spacing.
+   */
+  it.each(['24', '2rem', 'var(--my-spacing)'])(
+    'ignores %s, which is off the spacing scale',
+    async (padding) => {
+      const element = await createPane({padding});
 
-    expect(spacing(element)).toBe('var(--my-spacing)');
-  });
+      expect(spacing(element)).toBe('');
+    }
+  );
 
   it('re-renders when the padding property changes', async () => {
     const element = await createPane();
diff --git a/packages/craftcms-ui/src/components/pane/pane.ts b/packages/craftcms-ui/src/components/pane/pane.ts
index 1b3e8bae6dc..094666f2750 100644
--- a/packages/craftcms-ui/src/components/pane/pane.ts
+++ b/packages/craftcms-ui/src/components/pane/pane.ts
@@ -1,10 +1,15 @@
 import type {CSSResultGroup, PropertyValues} from 'lit';
 import {html, LitElement, nothing} from 'lit';
+import {html as staticHtml, unsafeStatic} from 'lit/static-html.js';
 import {property, state} from 'lit/decorators.js';
 import {styleMap} from 'lit/directives/style-map.js';
 import {Paddable} from '@src/mixins/Paddable.js';
 import hostStyles from '@src/styles/host.styles.js';
 import {t} from '@src/utilities/translate.js';
+import {
+  hasSlotted,
+  LightDomController,
+} from '@src/controllers/LightDomController';
 import styles from './pane.styles.js';
 
 export const PaneAppearance = {
@@ -87,10 +92,11 @@ const OVERFLOW_TOLERANCE = 1;
  * @slot secondary-action - The footer's secondary action, e.g. a cancel button.
  * @slot primary-action - The footer's primary action, e.g. a submit button.
  *
- * @attr padding - Spacing applied to the header, body, and footer regions.
- *   Accepts `sm`/`md`/`lg`/`xl` (mapped to `--c-spacing-*`), `0` or `none`, a
- *   unitless number (treated as pixels), or any CSS length. Defaults to `lg`.
- *   Supplied by the `Paddable` mixin, which writes it to `--_pane-spacing`.
+ * @attr {'sm'|'md'|'lg'|'xl'|'none'|'0'} padding - Spacing applied to the header, body, and footer regions.
+ *   Accepts `sm`, `md`, `lg`, and `xl` (mapped to `--c-spacing-*`), or
+ *   `0`/`none`. Defaults to `lg`. Values off that scale are ignored; set
+ *   `--c-pane-padding` for anything else. Supplied by the `Paddable` mixin,
+ *   which writes it to `--_pane-spacing`.
  *
  * @csspart base - The pane's outermost element, which carries the surface
  *   treatment. Style it to override border/shadow/fill for a single pane. It's
@@ -124,7 +130,7 @@ const OVERFLOW_TOLERANCE = 1;
  *   Defaults to `--c-color-neutral-border-quiet`.
  * @cssproperty --c-pane-padding - Fallback spacing used when the `padding`
  *   attribute is absent. Defaults to `--c-spacing-lg`.
- * @cssproperty --c-pane-title-font-size - Font size of the default `<h1>`
+ * @cssproperty --c-pane-title-font-size - Font size of the default heading
  *   title. Defaults to `1.125rem`.
  * @cssproperty --c-pane-title-line-height - Line height of the default title.
  * @cssproperty --c-pane-title-font-weight - Font weight of the default title.
@@ -168,10 +174,25 @@ export default class CraftPane extends Paddable(LitElement, {
    */
   @property() label = '';
 
+  /**
+   * The heading level `label` renders at. A pane sits inside a page that has
+   * its own `<h1>`, and pages routinely stack two or three panes, so the
+   * default is `2` — a run of `<h1>`s would leave a screen reader's heading
+   * list flat and unnavigable. Set it to `1` for a pane that really is the
+   * page's main heading, or deeper for a nested one.
+   */
+  @property({type: Number, attribute: 'heading-level'}) headingLevel:
+    | 1
+    | 2
+    | 3
+    | 4
+    | 5
+    | 6 = 2;
+
   /**
    * Whether header content is currently slotted. The header and footer slots
    * only render when filled, so their presence can't be tracked with
-   * `slotchange` — an unrendered slot never fires one. A light-DOM observer
+   * `slotchange` — an unrendered slot never fires one. `LightDomController`
    * keeps this fresh when a consumer adds, removes, or re-slots content.
    */
   @state() private _hasSlottedHeader = false;
@@ -188,7 +209,11 @@ export default class CraftPane extends Paddable(LitElement, {
   /** The host's `aria-label`, mirrored into state so it re-renders the region. */
   @state() private _hostLabel = '';
 
-  private _lightDomObserver = new MutationObserver(() => this._syncLightDom());
+  private _lightDom = new LightDomController(this, {
+    attributeFilter: ['aria-label'],
+    characterData: true,
+    onChange: () => this._syncLightDom(),
+  });
 
   private _resizeObserver?: ResizeObserver;
 
@@ -201,21 +226,8 @@ export default class CraftPane extends Paddable(LitElement, {
    */
   private _observedBoxes = new Set<Element>();
 
-  override connectedCallback() {
-    super.connectedCallback();
-    this._syncLightDom();
-    this._lightDomObserver.observe(this, {
-      childList: true,
-      subtree: true,
-      characterData: true,
-      attributes: true,
-      attributeFilter: ['slot', 'aria-label'],
-    });
-  }
-
   override disconnectedCallback() {
     super.disconnectedCallback();
-    this._lightDomObserver.disconnect();
     this._resizeObserver?.disconnect();
     this._observedBoxes.clear();
   }
@@ -225,20 +237,15 @@ export default class CraftPane extends Paddable(LitElement, {
     return this.renderRoot?.querySelector('.cp-pane') ?? null;
   }
 
-  /**
-   * Only direct children can be assigned to this pane's slots, so presence is
-   * checked against them rather than the whole subtree — a nested component
-   * with its own `footer`/`actions` slot must not light up the pane's chrome.
-   */
-  private _hasSlot(...names: string[]): boolean {
-    return Array.from(this.children).some((child) =>
-      names.includes(child.slot)
-    );
-  }
-
   private _syncSlotPresence() {
-    this._hasSlottedHeader = this._hasSlot('header', 'title', 'header-actions');
-    this._hasSlottedFooter = this._hasSlot(
+    this._hasSlottedHeader = hasSlotted(
+      this,
+      'header',
+      'title',
+      'header-actions'
+    );
+    this._hasSlottedFooter = hasSlotted(
+      this,
       'footer',
       'footer-content',
       'feedback',
@@ -364,6 +371,18 @@ export default class CraftPane extends Paddable(LitElement, {
     this._observeScrollable();
   }
 
+  /**
+   * `staticHtml` because the tag name is part of the template, not a value —
+   * an interpolated tag would be escaped as text. The level is clamped to the
+   * six real heading elements so a bad attribute cannot emit an `<h0>`.
+   */
+  private _renderTitle() {
+    const level = Math.min(6, Math.max(1, Number(this.headingLevel) || 2));
+    const tag = unsafeStatic(`h${level}`);
+
+    return staticHtml`<${tag} class="cp-pane__title">${this.label}</${tag}>`;
+  }
+
   protected override render() {
     const showHeader = !!this.label || this._hasSlottedHeader;
 
@@ -380,9 +399,7 @@ export default class CraftPane extends Paddable(LitElement, {
           ? html`<slot name="header">
               <div class="cp-pane__header" part="header">
                 <slot name="title" part="title">
-                  ${this.label
-                    ? html`<h1 class="cp-pane__title">${this.label}</h1>`
-                    : nothing}
+                  ${this.label ? this._renderTitle() : nothing}
                 </slot>
                 <div class="cp-pane__header-actions" part="header-actions">
                   <slot name="header-actions"></slot>
diff --git a/packages/craftcms-ui/src/components/permission-tree/PermissionTree.mdx b/packages/craftcms-ui/src/components/permission-tree/PermissionTree.mdx
new file mode 100644
index 00000000000..215be2fe8aa
--- /dev/null
+++ b/packages/craftcms-ui/src/components/permission-tree/PermissionTree.mdx
@@ -0,0 +1,50 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Components/Permission Tree" />
+
+# Permission Tree
+
+`<craft-permission-tree>` renders Craft's nested permission checkboxes.
+
+There are no stories on this page: the component takes a full permission structure as data, and a representative one is large enough that an example would obscure rather than explain. It is used in one place — the user and group permission screens.
+
+```html
+<craft-permission-tree name="permissions"></craft-permission-tree>
+```
+
+```js
+tree.groups = [...];              // the permission structure
+tree.modelValue = [...];          // the permissions currently granted
+tree.lockedPermissions = [...];   // permissions that cannot be changed
+```
+
+`groups`, `modelValue`, and `locked-permissions` carry the data. All three are properties as well as attributes, so bind them rather than serialising.
+
+## Nesting
+
+Permissions nest: granting a child implies its parents, and revoking a parent revokes what it contains. The tree enforces that, which is why it exists rather than being a flat list of checkboxes.
+
+Locked permissions render as fixed — granted by something other than this screen, such as an admin flag — so the interface shows them without pretending they can be changed here.
+
+## Accessibility
+
+The nesting is structural, so the relationship between a permission and the ones it contains is available rather than being conveyed by indentation alone.
+
+A tree this size is hard to navigate by ear regardless. Where a screen offers one, it is worth also providing a way to search or filter it.
+
+## Events
+
+Each toggle is a commit, so the tree emits `input` and `change` together:
+
+```js
+tree.addEventListener('change', () => save(tree.modelValue));
+```
+
+It also emits `model-value-changed`, Lion's internal protocol name. Prefer the native events.
+
+## Properties
+
+Five attributes cover the data and the field wiring: `groups`, `model-value`,
+`locked-permissions`, `name`, and `disabled`.
+
+<ArgTypes of="craft-permission-tree" />
diff --git a/packages/craftcms-ui/src/components/permission-tree/permission-tree.test.ts b/packages/craftcms-ui/src/components/permission-tree/permission-tree.test.ts
index 19135ccd4d9..5c1e5a91cc0 100644
--- a/packages/craftcms-ui/src/components/permission-tree/permission-tree.test.ts
+++ b/packages/craftcms-ui/src/components/permission-tree/permission-tree.test.ts
@@ -81,4 +81,40 @@ describe('craft-permission-tree', () => {
       )
     ).toEqual(['']);
   });
+
+  it('emits native input and change when a permission is toggled', async () => {
+    const element = document.createElement(
+      'craft-permission-tree'
+    ) as CraftPermissionTree;
+    element.name = 'permissions';
+    element.modelValue = ['viewEntries'];
+    element.groups = [
+      {
+        handle: 'content',
+        heading: 'Content',
+        keys: ['viewEntries'],
+        permissions: {
+          viewEntries: {key: 'viewEntries', label: 'View entries'},
+        },
+      },
+    ];
+    document.body.append(element);
+    await element.updateComplete;
+
+    const order: string[] = [];
+    element.addEventListener('input', () => order.push('input'));
+    element.addEventListener('change', () => order.push('change'));
+
+    const checkbox =
+      element.shadowRoot!.querySelector<CraftCheckbox>('craft-checkbox')!;
+    checkbox.checked = false;
+    checkbox.dispatchEvent(
+      new CustomEvent('model-value-changed', {bubbles: true, composed: true})
+    );
+    await element.updateComplete;
+
+    // Each toggle is a commit, so the pair fires together.
+    expect(order).toEqual(['input', 'change']);
+    expect(element.modelValue).toEqual([]);
+  });
 });
diff --git a/packages/craftcms-ui/src/components/permission-tree/permission-tree.ts b/packages/craftcms-ui/src/components/permission-tree/permission-tree.ts
index 587f098c8bc..49d72548e3a 100644
--- a/packages/craftcms-ui/src/components/permission-tree/permission-tree.ts
+++ b/packages/craftcms-ui/src/components/permission-tree/permission-tree.ts
@@ -1,6 +1,7 @@
 import {css, html, LitElement, nothing, type PropertyValues} from 'lit';
 import {property} from 'lit/decorators.js';
 import {repeat} from 'lit/directives/repeat.js';
+import {emitChange, emitInput} from '@src/utilities/form-events.js';
 import {t} from '@src/utilities/translate.js';
 import type CraftCheckbox from '../checkbox/checkbox.js';
 import '../button/button.js';
@@ -30,7 +31,15 @@ let nextTreeId = 0;
 
 /**
  * @summary A grouped tree of selectable permissions.
+ * @fires input - Emitted when a permission is toggled.
+ * @fires change - Emitted when a permission is toggled. Each toggle is a
+ *   commit, so it follows each `input`.
  * @fires model-value-changed - Fired when the selected permissions change.
+ *
+ * `model-value-changed` is Lion's own protocol name, not one this package
+ * chose, and it is kept because Lion's form system dispatches and listens for
+ * it. Prefer the native events above: they are the contract this package
+ * supports, and they carry the component as `event.target`.
  */
 export default class CraftPermissionTree extends LitElement {
   static override styles = css`
@@ -305,6 +314,11 @@ export default class CraftPermissionTree extends LitElement {
         detail: {isTriggeredByUser: true},
       })
     );
+
+    // The public contract. Toggling a permission is a commit, so the pair
+    // fires together, the way a checkbox group's does.
+    emitInput(this);
+    emitChange(this);
   }
 
   #syncHiddenInputs() {
diff --git a/packages/craftcms-ui/src/components/popover/Popover.mdx b/packages/craftcms-ui/src/components/popover/Popover.mdx
new file mode 100644
index 00000000000..1855abfd0c0
--- /dev/null
+++ b/packages/craftcms-ui/src/components/popover/Popover.mdx
@@ -0,0 +1,46 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as PopoverStories from './popover.stories';
+
+<Meta of={PopoverStories} name="Docs" />
+
+# Popover
+
+`<craft-popover>` overlays content on top of the page without affecting layout.
+
+<Canvas of={PopoverStories.Basic} sourceState="shown" />
+
+It is non-modal: the page behind stays live, and the popover dismisses on Escape or an outside click. That makes it the right choice for something supplementary — where a [Dialog](?path=/docs/components-dialog--docs) would be an interruption.
+
+## Three Ways to Trigger It
+
+- **A slotted `invoker`** — the usual case, where the trigger sits inside the popover.
+- **`for`** — names an element elsewhere by id, for a trigger the popover cannot contain.
+- **`anchor`** — the element passed directly, for triggers built in script.
+
+The last two exist because a popover often has to be positioned by something it does not own — a toolbar button, a table cell, a server-rendered control.
+
+## Placement
+
+<Canvas of={PopoverStories.BottomEnd} sourceState="shown" />
+
+Placement follows Popper's vocabulary, so `bottom-end`, `right-start`, and the rest behave as they do elsewhere.
+
+<Canvas of={PopoverStories.MatchInvokerWidth} sourceState="shown" />
+
+Matching the invoker's width is what makes a popover read as an extension of its trigger rather than as a floating panel — which is why select-style menus use it.
+
+## Events
+
+Four events cover the transitions: `craft-show` and `craft-hide` fire as the change begins, `craft-after-show` and `craft-after-hide` once it has finished.
+
+Use the `after` pair when you need the popover to have actually settled — moving focus into it, or measuring it.
+
+## Accessibility
+
+Lion supplies the overlay behaviour, including dismissal and the wiring between invoker and content.
+
+Because it is non-modal, focus is not trapped. That is the point, but it means a popover holding interactive content should place focus deliberately when it opens and return it to the invoker when it closes — otherwise a keyboard user is left where they were, with the popover open somewhere else.
+
+## Properties
+
+<ArgTypes of={PopoverStories} />
diff --git a/packages/craftcms-ui/src/components/popover/popover.stories.ts b/packages/craftcms-ui/src/components/popover/popover.stories.ts
index 3d3043d41b4..143ffadbf88 100644
--- a/packages/craftcms-ui/src/components/popover/popover.stories.ts
+++ b/packages/craftcms-ui/src/components/popover/popover.stories.ts
@@ -1,40 +1,32 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {html} from 'lit';
 
 import './popover.js';
+import type CraftPopover from './popover.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `popover.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftPopover>('craft-popover');
+
+type CraftPopoverArgs = CraftPopover & typeof args;
 
 const meta = {
-  title: 'Functional/Popover',
+  title: 'Components/Popover',
   component: 'craft-popover',
   parameters: {
     layout: 'centered',
   },
-  argTypes: {
-    placement: {
-      control: {type: 'select'},
-      options: [
-        'top',
-        'top-start',
-        'top-end',
-        'bottom',
-        'bottom-start',
-        'bottom-end',
-        'left',
-        'left-start',
-        'left-end',
-        'right',
-        'right-start',
-        'right-end',
-      ],
-    },
-    matchInvokerWidth: {
-      control: {type: 'boolean'},
-    },
-  },
+  args: {...args, placement: 'bottom-start'},
+  argTypes,
   render: (args) => html`
     <craft-popover
       placement="${args.placement || 'bottom-start'}"
-      ?match-invoker-width="${args.matchInvokerWidth}"
+      ?match-invoker-width="${args['match-invoker-width']}"
     >
       <button slot="invoker" type="button">Toggle Popover</button>
       <div slot="content">
@@ -43,10 +35,10 @@ const meta = {
       </div>
     </craft-popover>
   `,
-} satisfies Meta<any>;
+} satisfies Meta<CraftPopoverArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftPopoverArgs>;
 
 export const Basic: Story = {
   args: {
diff --git a/packages/craftcms-ui/src/components/popover/popover.ts b/packages/craftcms-ui/src/components/popover/popover.ts
index 22958422809..34c84fbd496 100644
--- a/packages/craftcms-ui/src/components/popover/popover.ts
+++ b/packages/craftcms-ui/src/components/popover/popover.ts
@@ -7,7 +7,7 @@ import {viewportEscapingModifiers} from '@src/utilities/overlay-position.js';
 import styles from './popover.styles.js';
 
 /**
- * A non-modal popover component built on Lion's overlay system.
+ * @summary A non-modal popover built on Lion's overlay system.
  *
  * Overlays content on top of the page without affecting document flow.
  * The trigger can be a slotted `invoker` child, an external element
@@ -27,6 +27,11 @@ import styles from './popover.styles.js';
  *   <div slot="content">Popover content here</div>
  * </craft-popover>
  * ```
+ *
+ * @fires craft-show - The overlay is opening. Fires as the state flips.
+ * @fires craft-after-show - The overlay has opened and its update has settled.
+ * @fires craft-hide - The overlay is closing. Fires as the state flips.
+ * @fires craft-after-hide - The overlay has closed and its update has settled.
  */
 export default class CraftPopover extends OverlayMixin(LitElement) {
   static override styles = [styles];
@@ -192,12 +197,24 @@ export default class CraftPopover extends OverlayMixin(LitElement) {
     }
   }
 
+  /**
+
+   * Opens the popover. Resolves once the overlay has finished opening.
+
+   */
+
   async show(): Promise<void> {
     this.opened = true;
     await this.updateComplete;
     await this.open();
   }
 
+  /**
+
+   * Closes the popover. Resolves once the overlay has finished closing.
+
+   */
+
   async hide(): Promise<void> {
     this.opened = false;
     await this.updateComplete;
diff --git a/packages/craftcms-ui/src/components/progress-bar/ProgressBar.mdx b/packages/craftcms-ui/src/components/progress-bar/ProgressBar.mdx
new file mode 100644
index 00000000000..a6241f3ef32
--- /dev/null
+++ b/packages/craftcms-ui/src/components/progress-bar/ProgressBar.mdx
@@ -0,0 +1,60 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ProgressBarStories from './progress-bar.stories';
+
+<Meta of={ProgressBarStories} name="Docs" />
+
+# Progress Bar
+
+`<craft-progress-bar>` shows progress as a horizontal bar, with an optional status line.
+
+<Canvas of={ProgressBarStories.ProgressStates} sourceState="shown" />
+
+Use it where there is room to spread out and progress is worth watching — an upload, a queue job, a long save. For a small fixed space, use [Progress](?path=/docs/components-progress--docs); where progress cannot be measured, use [Spinner](?path=/docs/components-spinner--docs).
+
+## Two Ways to Set It
+
+Either a percentage:
+
+```html
+<craft-progress-bar progress="50"></craft-progress-bar>
+```
+
+Or a count of items, which the bar turns into a percentage itself:
+
+<Canvas of={ProgressBarStories.ItemCountMode} sourceState="shown" />
+
+Prefer the count when you have one. It is what the status line can report, and "25 of 100" tells a person more than "25%" — including how much work a single item represents.
+
+## Status
+
+<Canvas of={ProgressBarStories.WithStatus} sourceState="shown" />
+
+`show-status` renders the progress as text alongside the bar. This is the part that makes the component readable without seeing it, so turn it on whenever there is room.
+
+## Pending and Completion
+
+<Canvas of={ProgressBarStories.Pending} sourceState="shown" />
+
+<Canvas of={ProgressBarStories.CompleteEvent} sourceState="shown" />
+
+<Canvas of={ProgressBarStories.ResetMethod} sourceState="shown" />
+
+`reset()` returns the bar to zero, for reusing one across several runs rather than replacing the element.
+
+## Styling
+
+<Canvas of={ProgressBarStories.CustomStyles} sourceState="shown" />
+
+Three CSS parts and five custom properties cover the track, the fill, and the status text. Both are listed under [Properties](#properties).
+
+<Canvas of={ProgressBarStories.Playground} sourceState="shown" />
+
+## Accessibility
+
+The bar itself is a visual fill. **`show-status` is what makes it perceivable as text**, which is why it is worth turning on rather than treating as decoration.
+
+Where the status is hidden, the surrounding interface has to say the same thing another way — a caption, a count, a live region. A bar with no text is a progress indicator only for people who can see it.
+
+## Properties
+
+<ArgTypes of={ProgressBarStories} />
diff --git a/packages/craftcms-ui/src/components/progress-bar/progress-bar.stories.ts b/packages/craftcms-ui/src/components/progress-bar/progress-bar.stories.ts
index f3f5475d6f4..8548dde1f2a 100644
--- a/packages/craftcms-ui/src/components/progress-bar/progress-bar.stories.ts
+++ b/packages/craftcms-ui/src/components/progress-bar/progress-bar.stories.ts
@@ -251,7 +251,7 @@ export const CompleteEvent: Story = {
           processed="0"
           show-status
           smooth
-          @complete=${() => {
+          @craft-complete=${() => {
             const output = document.querySelector('#complete-output');
             if (output) {
               output.textContent = 'Complete event fired!';
diff --git a/packages/craftcms-ui/src/components/progress-bar/progress-bar.test.ts b/packages/craftcms-ui/src/components/progress-bar/progress-bar.test.ts
new file mode 100644
index 00000000000..1a23db639ad
--- /dev/null
+++ b/packages/craftcms-ui/src/components/progress-bar/progress-bar.test.ts
@@ -0,0 +1,74 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './progress-bar.js';
+import type CraftProgressBar from './progress-bar.js';
+
+async function createProgressBar(
+  attrs: Record<string, string> = {}
+): Promise<CraftProgressBar> {
+  const element = document.createElement(
+    'craft-progress-bar'
+  ) as CraftProgressBar;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function track(element: CraftProgressBar): HTMLElement {
+  return element.shadowRoot!.querySelector('[part="track"]')!;
+}
+
+function fill(element: CraftProgressBar): HTMLElement {
+  return element.shadowRoot!.querySelector('[part="fill"]')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-progress-bar', () => {
+  it('is a progressbar with the full range declared', async () => {
+    const element = await createProgressBar({progress: '40'});
+
+    expect(track(element).getAttribute('role')).toBe('progressbar');
+    expect(track(element).getAttribute('aria-valuemin')).toBe('0');
+    expect(track(element).getAttribute('aria-valuemax')).toBe('100');
+    expect(track(element).getAttribute('aria-valuenow')).toBe('40');
+  });
+
+  it('names itself, so a bar on its own is not anonymous', async () => {
+    const element = await createProgressBar({label: 'Uploading assets'});
+
+    expect(track(element).getAttribute('aria-label')).toBe('Uploading assets');
+  });
+
+  it('fills to the progress value', async () => {
+    const element = await createProgressBar({progress: '40'});
+
+    expect(fill(element).style.width).toBe('40%');
+  });
+
+  /** A total and a processed count are the other way to express the same thing. */
+  it('derives progress from processed and total', async () => {
+    const element = await createProgressBar({total: '50', processed: '25'});
+
+    expect(fill(element).style.width).toBe('50%');
+  });
+
+  /**
+   * A pending bar has no value to report, so it fills the track and drops
+   * `aria-valuenow` rather than claiming a number it does not have.
+   */
+  it('reports no value while pending', async () => {
+    const element = await createProgressBar({pending: ''});
+
+    expect(track(element).getAttribute('aria-valuenow')).toBeNull();
+    expect(fill(element).style.width).toBe('100%');
+    expect(track(element).classList.contains('progress-bar--pending')).toBe(
+      true
+    );
+  });
+});
diff --git a/packages/craftcms-ui/src/components/progress-bar/progress-bar.ts b/packages/craftcms-ui/src/components/progress-bar/progress-bar.ts
index f6db9c1c6f2..9143010341f 100644
--- a/packages/craftcms-ui/src/components/progress-bar/progress-bar.ts
+++ b/packages/craftcms-ui/src/components/progress-bar/progress-bar.ts
@@ -40,7 +40,7 @@ import styles from './progress-bar.styles';
  * <craft-progress-bar progress="75" smooth></craft-progress-bar>
  * ```
  *
- * @event complete - Fired when progress reaches 100% (only when using item count mode)
+ * @event craft-complete - Fired when progress reaches 100% (only when using item count mode)
  *
  * @csspart track - The background track of the progress bar
  * @csspart fill - The filled portion indicating progress
@@ -94,7 +94,7 @@ export default class CraftProgressBar extends LitElement {
         // Check if we just reached 100%
         if (newProgress >= 100 && this.#lastProgress < 100) {
           this.dispatchEvent(
-            new CustomEvent('complete', {bubbles: true, composed: true})
+            new CustomEvent('craft-complete', {bubbles: true, composed: true})
           );
         }
 
diff --git a/packages/craftcms-ui/src/components/progress/Progress.mdx b/packages/craftcms-ui/src/components/progress/Progress.mdx
new file mode 100644
index 00000000000..4e366e41589
--- /dev/null
+++ b/packages/craftcms-ui/src/components/progress/Progress.mdx
@@ -0,0 +1,50 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ProgressStories from './progress.stories';
+
+<Meta of={ProgressStories} name="Docs" />
+
+# Progress
+
+`<craft-progress>` shows progress as a radial arc.
+
+<Canvas of={ProgressStories.ProgressStates} sourceState="shown" />
+
+Use it where progress has to sit in a small, fixed space — beside a row, inside a button, in a toolbar. For progress with room to spread out, or that needs a status line, use [Progress Bar](?path=/docs/components-progress-bar--docs).
+
+When you cannot measure progress at all, use [Spinner](?path=/docs/components-spinner--docs).
+
+## Determinate and Indeterminate
+
+<Canvas of={ProgressStories.AnimatedProgress} sourceState="shown" />
+
+<Canvas of={ProgressStories.Indeterminate} sourceState="shown" />
+
+Reach for indeterminate only when the total genuinely is not known. A spinning arc tells a person nothing about whether to wait, so a real percentage is always the better answer where one exists.
+
+## Completion
+
+<Canvas of={ProgressStories.CompleteAnimation} sourceState="shown" />
+
+<Canvas of={ProgressStories.AutoComplete} sourceState="shown" />
+
+The `complete` event fires when the completion animation finishes, rather than when the value reaches 100 — so anything that should happen after the indicator has visibly settled can wait for it.
+
+## Sizing and Colour
+
+<Canvas of={ProgressStories.CustomSize} sourceState="shown" />
+
+<Canvas of={ProgressStories.IndeterminateSizes} sourceState="shown" />
+
+<Canvas of={ProgressStories.CustomColors} sourceState="shown" />
+
+Size and stroke width are custom properties, so the arc scales without redrawing.
+
+## Accessibility
+
+The arc is drawn on a canvas, which means it has no text and nothing a screen reader can read from the drawing itself.
+
+Whatever it accompanies has to carry the state in text — "Uploading 3 of 8" beside the arc, not the arc alone. A percentage that exists only as an angle is a percentage some people cannot read.
+
+## Properties
+
+<ArgTypes of={ProgressStories} />
diff --git a/packages/craftcms-ui/src/components/progress/progress.stories.ts b/packages/craftcms-ui/src/components/progress/progress.stories.ts
index d0b8e2c2db9..76e126d3286 100644
--- a/packages/craftcms-ui/src/components/progress/progress.stories.ts
+++ b/packages/craftcms-ui/src/components/progress/progress.stories.ts
@@ -189,7 +189,7 @@ export const CompleteAnimation: Story = {
         <craft-progress
           id="complete-demo"
           progress="75"
-          @complete=${() => console.log('Complete event received!')}
+          @craft-complete=${() => console.log('Complete event received!')}
         ></craft-progress>
         <button @click=${handleClick}>Trigger Complete Animation</button>
       </div>
@@ -239,7 +239,7 @@ export const AutoComplete: Story = {
           id="auto-complete-demo"
           progress="0"
           auto-complete
-          @complete=${() => console.log('Auto-complete triggered!')}
+          @craft-complete=${() => console.log('Auto-complete triggered!')}
         ></craft-progress>
         <div>
           <button type="button" @click="${replay}">Replay</button>
diff --git a/packages/craftcms-ui/src/components/progress/progress.test.ts b/packages/craftcms-ui/src/components/progress/progress.test.ts
new file mode 100644
index 00000000000..b1dd110db3a
--- /dev/null
+++ b/packages/craftcms-ui/src/components/progress/progress.test.ts
@@ -0,0 +1,72 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './progress.js';
+import type CraftProgress from './progress.js';
+
+async function createProgress(
+  attrs: Record<string, string> = {}
+): Promise<CraftProgress> {
+  const element = document.createElement('craft-progress') as CraftProgress;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function canvas(element: CraftProgress): HTMLElement {
+  return element.shadowRoot!.querySelector('[part="canvas"]')!;
+}
+
+/** The visually hidden text, which is what a screen reader actually gets. */
+function announced(element: CraftProgress): string {
+  return element
+    .shadowRoot!.querySelector('.visually-hidden')!
+    .textContent!.trim();
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-progress', () => {
+  it('is a progressbar with the full range declared', async () => {
+    const element = await createProgress({progress: '60'});
+
+    expect(canvas(element).getAttribute('role')).toBe('progressbar');
+    expect(canvas(element).getAttribute('aria-valuemin')).toBe('0');
+    expect(canvas(element).getAttribute('aria-valuemax')).toBe('100');
+    expect(canvas(element).getAttribute('aria-valuenow')).toBe('60');
+  });
+
+  it('names itself', async () => {
+    const element = await createProgress({label: 'Generating transforms'});
+
+    expect(canvas(element).getAttribute('aria-label')).toBe(
+      'Generating transforms'
+    );
+  });
+
+  /**
+   * The canvas draws the ring, so the state has to be announced in text
+   * alongside it — a canvas has nothing a screen reader can read.
+   */
+  it('announces the percentage in text', async () => {
+    expect(announced(await createProgress({progress: '60'}))).toBe('60%');
+  });
+
+  /** A negative value means indeterminate rather than a number to report. */
+  it('announces loading when there is no value yet', async () => {
+    const element = await createProgress({progress: '-1'});
+
+    expect(announced(element)).toBe('Loading');
+    expect(canvas(element).getAttribute('aria-valuenow')).toBe('');
+  });
+
+  it('announces a failure', async () => {
+    expect(announced(await createProgress({progress: '60', failed: ''}))).toBe(
+      'Failed'
+    );
+  });
+});
diff --git a/packages/craftcms-ui/src/components/progress/progress.ts b/packages/craftcms-ui/src/components/progress/progress.ts
index 853e5b6f1a5..5322e78f989 100644
--- a/packages/craftcms-ui/src/components/progress/progress.ts
+++ b/packages/craftcms-ui/src/components/progress/progress.ts
@@ -7,7 +7,7 @@ import {property} from 'lit/decorators.js';
  *
  * @summary Displays progress in radial form
  *
- * @event complete - Fired when the completion animation finishes
+ * @event craft-complete - Fired when the completion animation finishes
  *
  * @csspart canvas - The canvas element
  *
@@ -310,7 +310,7 @@ export default class CraftProgress extends LitElement {
   async complete(): Promise<void> {
     await this.runCompleteAnimation();
     this.dispatchEvent(
-      new CustomEvent('complete', {bubbles: true, composed: true})
+      new CustomEvent('craft-complete', {bubbles: true, composed: true})
     );
   }
 
diff --git a/packages/craftcms-ui/src/components/radio-group/RadioGroup.mdx b/packages/craftcms-ui/src/components/radio-group/RadioGroup.mdx
new file mode 100644
index 00000000000..abfda6c603c
--- /dev/null
+++ b/packages/craftcms-ui/src/components/radio-group/RadioGroup.mdx
@@ -0,0 +1,32 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as RadioGroupStories from './radio-group.stories';
+
+<Meta of={RadioGroupStories} name="Docs" />
+
+# Radio Group
+
+`<craft-radio-group>` collects [Radio](?path=/docs/form-controls-choice-controls-radio--docs)s that share a name, for a choice where exactly one option may be selected.
+
+<Canvas of={RadioGroupStories.Default} sourceState="shown" />
+
+The group owns the name and the value: its `modelValue` is the value of whichever radio is checked.
+
+Use a [Checkbox Group](?path=/docs/form-controls-choice-controls-checkbox-group--docs) when more than one option may be chosen.
+
+## Choosing Between Them
+
+The control tells a person how many answers are allowed before they read a word of the labels — radios mean one, checkboxes mean any number. Picking the wrong one is a usability problem no amount of help text fixes.
+
+A radio group also cannot be cleared once an option is chosen. When "none of these" is a valid answer, either offer it as an explicit option or use checkboxes.
+
+## Labelling the Group
+
+The group takes its own `label`, `help-text`, and `feedback`. The radios name the options; only the group can name the question.
+
+## Server-Rendered Markup
+
+A group rendered by the server adopts the name already present on its inputs, for the same reason as the checkbox group: Lion syncs each child's name to the group's, so upgrading a nameless group would strip the server's names and break native posting.
+
+## Properties
+
+<ArgTypes of={RadioGroupStories} />
diff --git a/packages/craftcms-ui/src/components/radio-group/radio-group.stories.ts b/packages/craftcms-ui/src/components/radio-group/radio-group.stories.ts
index 810ac2a676d..3acfc21ef94 100644
--- a/packages/craftcms-ui/src/components/radio-group/radio-group.stories.ts
+++ b/packages/craftcms-ui/src/components/radio-group/radio-group.stories.ts
@@ -1,39 +1,64 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './radio-group.js';
 import '../radio/radio.js';
+import type CraftRadioGroup from './radio-group.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `radio-group.ts` surfaces it here without touching this file.
+ *
+ * Lion's own `label` and `help-text` are slots here, so they are set through
+ * the `label-slot` and `help-text-slot` args rather than as attributes.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftRadioGroup>('craft-radio-group');
+
+type RadioGroupArgs = CraftRadioGroup & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Radio Group',
+  title: 'Form Controls/Choice Controls/Radio Group',
   component: 'craft-radio-group',
-  args: {},
-  render: function () {
-    return html`<craft-radio-group name="scientist" label="Scientists">
-      <craft-radio label="Marie Curie" .choiceValue=${'curie'}></craft-radio>
-      <craft-radio
-        label="Ada Lovelace"
-        .choiceValue=${'lovelace'}
-        .checked=${true}
-      ></craft-radio>
-      <craft-radio label="Grace Hopper" .choiceValue=${'hopper'}></craft-radio>
-    </craft-radio-group>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, name: 'scientist', 'label-slot': 'Scientists'},
+  argTypes,
+  // The options are written out rather than generated: each one carries a
+  // `choiceValue`, which is a property rather than an attribute, so it cannot
+  // be expressed in a slot's markup string.
+  render: (args) => html`
+    <craft-radio-group name="${args.name ?? ''}" ?disabled="${args.disabled}">
+      <label slot="label">${args['label-slot']}</label>
+      <craft-radio .choiceValue="${'curie'}">
+        <label slot="label">Marie Curie</label>
+      </craft-radio>
+      <craft-radio .choiceValue="${'lovelace'}" checked>
+        <label slot="label">Ada Lovelace</label>
+      </craft-radio>
+      <craft-radio .choiceValue="${'hopper'}">
+        <label slot="label">Grace Hopper</label>
+      </craft-radio>
+    </craft-radio-group>
+  `,
+} satisfies Meta<RadioGroupArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<RadioGroupArgs>;
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
+/** Exactly one option may be selected, and the group owns the value. */
+export const Default: Story = {};
 
+/**
+ * A group rendered by the server adopts the name already on its inputs, so the
+ * markup keeps posting the way it did before the component upgraded.
+ */
 export const ServerRendered: Story = {
+  parameters: {controls: {disable: true}},
   render: () =>
-    html`<craft-radio-group label="Color">
+    html`<craft-radio-group>
+      <label slot="label">Color</label>
       <div>
         <craft-radio>
           <input
diff --git a/packages/craftcms-ui/src/components/radio-group/radio-group.ts b/packages/craftcms-ui/src/components/radio-group/radio-group.ts
index a522afb8318..4160a746ca7 100644
--- a/packages/craftcms-ui/src/components/radio-group/radio-group.ts
+++ b/packages/craftcms-ui/src/components/radio-group/radio-group.ts
@@ -1,47 +1,28 @@
 import {LionRadioGroup} from '@lion/ui/radio-group.js';
 import {inputStyles} from '@src/styles/form.styles';
-import {css, type PropertyValues} from 'lit';
-
-export default class CraftRadioGroup extends LionRadioGroup {
-  private __ssrNameAdopted = false;
-
-  /**
-   * Adopts the group name from server-rendered radio inputs. Lion syncs
-   * each registered child's name to the group's (`name || ''`), so a
-   * nameless group would strip the SSR'd names and break native posting.
-   * Runs before `super.connectedCallback()` so the name is set before any
-   * child registers; `willUpdate` is the fallback for streaming parsing,
-   * where the element can connect before its children exist.
-   */
-  override connectedCallback() {
-    this.__adoptSlottedName();
-    super.connectedCallback();
-  }
-
-  protected override willUpdate(changedProperties: PropertyValues) {
-    this.__adoptSlottedName();
-    super.willUpdate(changedProperties);
-  }
-
-  private __adoptSlottedName() {
-    if (this.__ssrNameAdopted || this.name) {
-      return;
-    }
-
-    const input = this.querySelector<HTMLInputElement>(
-      'input[type="radio"][name]'
-    );
-
-    if (!input) {
-      // Leave the flag unset so a later pass can still adopt once children
-      // have been parsed.
-      return;
-    }
-
-    this.__ssrNameAdopted = true;
-    this.name = input.name;
-  }
-
+import {SsrChoiceGroupMixin} from '@src/mixins/SsrChoiceGroupMixin';
+import {css} from 'lit';
+
+/**
+ * @summary A group of radios sharing one name, for a choice where exactly one
+ * option may be selected.
+ *
+ * The group owns the name and the value, so its `modelValue` is the value of
+ * whichever radio is checked. Use `craft-checkbox-group` when more than one
+ * option may be chosen.
+ *
+ * A group rendered by the server adopts the name already on its inputs, so the
+ * markup keeps posting the way it did before the component upgraded.
+ *
+ * @slot - The `craft-radio`s in the group.
+ * @slot label - The group's label.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages for the group as a whole.
+ */
+export default class CraftRadioGroup extends SsrChoiceGroupMixin(
+  LionRadioGroup,
+  'radio'
+) {
   static override get styles() {
     return [
       ...super.styles,
diff --git a/packages/craftcms-ui/src/components/radio/Radio.mdx b/packages/craftcms-ui/src/components/radio/Radio.mdx
new file mode 100644
index 00000000000..067fee5bed4
--- /dev/null
+++ b/packages/craftcms-ui/src/components/radio/Radio.mdx
@@ -0,0 +1,35 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Form Controls/Choice Controls/Radio" />
+
+# Radio
+
+`<craft-radio>` is one option within a [Radio Group](?path=/docs/form-controls-choice-controls-radio-group--docs).
+
+There are no stories on this page because a radio on its own has nothing to be exclusive against — its whole behaviour is defined by the group it belongs to. See the [Radio Group](?path=/docs/form-controls-choice-controls-radio-group--docs) page for working examples.
+
+```html
+<craft-radio-group label="Propagation method">
+  <craft-radio
+    label="Only save to the site it was edited in"
+    value="none"
+  ></craft-radio>
+  <craft-radio label="Save to all sites in the group" value="all"></craft-radio>
+</craft-radio-group>
+```
+
+## What It Contributes
+
+The radio carries the option's `label` and `value`. The group carries the name, the current value, and any validation.
+
+Like [Checkbox](?path=/docs/form-controls-choice-controls-checkbox--docs), it keeps the `checked`, `disabled`, and `name` of a server-rendered input rather than resetting them when the component upgrades.
+
+## Accessibility
+
+Lion wires the label to the input, and the group provides the radio-group semantics that make arrow-key navigation between options work.
+
+That is one more reason not to use a radio outside a group: alone, it is a control a person can select but never deselect, with no siblings to move between.
+
+## Properties
+
+<ArgTypes of="craft-radio" />
diff --git a/packages/craftcms-ui/src/components/radio/radio.ts b/packages/craftcms-ui/src/components/radio/radio.ts
index d8c444b3eff..8d907c4cf5a 100644
--- a/packages/craftcms-ui/src/components/radio/radio.ts
+++ b/packages/craftcms-ui/src/components/radio/radio.ts
@@ -2,6 +2,18 @@ import {LionRadio} from '@lion/ui/radio-group.js';
 import {css} from 'lit';
 import {SsrChoiceInputMixin} from '@src/mixins/SsrChoiceInputMixin';
 
+/**
+ * @summary One option within a `craft-radio-group`. A radio outside a group
+ * has nothing to be exclusive against, so it is always used in one.
+ *
+ * Built on Lion's radio, and like `craft-checkbox` it keeps the `checked`,
+ * `disabled`, and `name` of a server-rendered input rather than resetting them
+ * on upgrade.
+ *
+ * @slot label - The option's label, as an alternative to the `label`
+ *   attribute.
+ * @slot help-text - Guidance shown below the label.
+ */
 export default class CraftRadio extends SsrChoiceInputMixin(LionRadio) {
   static override get styles() {
     return [
diff --git a/packages/craftcms-ui/src/components/reorder-button/ReorderButton.mdx b/packages/craftcms-ui/src/components/reorder-button/ReorderButton.mdx
new file mode 100644
index 00000000000..efcac2444d2
--- /dev/null
+++ b/packages/craftcms-ui/src/components/reorder-button/ReorderButton.mdx
@@ -0,0 +1,36 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ReorderButtonStories from './reorder-button.stories';
+
+<Meta of={ReorderButtonStories} name="Docs" />
+
+# Reorder Button
+
+`<craft-reorder-button>` moves an item up or down a list from the keyboard.
+
+<Canvas of={ReorderButtonStories.Default} sourceState="shown" />
+
+It is the accessible counterpart to a drag handle. Dragging is a pointer gesture with no keyboard equivalent, so a list that can only be reordered by dragging cannot be reordered by everyone.
+
+## Position
+
+<Canvas of={ReorderButtonStories.First} sourceState="shown" />
+
+<Canvas of={ReorderButtonStories.Last} sourceState="shown" />
+
+`position` tells the button where its item sits, so the direction that would go nowhere is disabled rather than silently doing nothing.
+
+<Canvas of={ReorderButtonStories.Horizontal} sourceState="shown" />
+
+<Canvas of={ReorderButtonStories.Disabled} sourceState="shown" />
+
+## Accessibility
+
+This component exists for accessibility, so the thing to get right is the announcement.
+
+Moving an item changes the list, and that change is invisible to a screen reader unless something says so. The button reports the move; the list is responsible for making the new order perceivable — usually a live region naming the item and its new position.
+
+Without that, a person can reorder a list and have no way of knowing whether it worked.
+
+## Properties
+
+<ArgTypes of={ReorderButtonStories} />
diff --git a/packages/craftcms-ui/src/components/reorder-button/reorder-button.stories.ts b/packages/craftcms-ui/src/components/reorder-button/reorder-button.stories.ts
index 211f0672427..e1cefb516ff 100644
--- a/packages/craftcms-ui/src/components/reorder-button/reorder-button.stories.ts
+++ b/packages/craftcms-ui/src/components/reorder-button/reorder-button.stories.ts
@@ -1,51 +1,43 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './reorder-button.js';
+import type CraftReorderButton from './reorder-button.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `reorder-button.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} = getStorybookHelpers<CraftReorderButton>(
+  'craft-reorder-button'
+);
+
+type ReorderButtonArgs = CraftReorderButton & typeof args;
 
 const meta = {
   title: 'Components/Reorder Button',
   component: 'craft-reorder-button',
-  parameters: {
-    layout: 'centered',
-  },
   args: {
+    ...args,
     label: 'Reorder',
     position: 'middle',
     variant: 'neutral',
     orientation: 'vertical',
-    disabled: false,
   },
-  argTypes: {
-    position: {
-      control: {type: 'select'},
-      options: ['first', 'middle', 'last'],
-    },
-    orientation: {
-      control: {type: 'select'},
-      options: ['vertical', 'horizontal'],
-    },
-  },
-  render: (args) => html`
-    <craft-reorder-button
-      label="${args.label}"
-      position="${args.position}"
-      variant="${args.variant}"
-      orientation="${args.orientation}"
-      ?disabled="${args.disabled}"
-      @reorder="${(e: CustomEvent<{direction: 'up' | 'down'}>) =>
-        console.log('reorder', e.detail.direction)}"
-    ></craft-reorder-button>
-  `,
-} satisfies Meta<any>;
+  argTypes,
+  parameters: {layout: 'centered'},
+  // Render from args alone so every control drives the story. Stories below
+  // vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<ReorderButtonArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<ReorderButtonArgs>;
 
-export const Default: Story = {
-  args: {},
-};
+/** Both directions available, for an item in the middle of a list. */
+export const Default: Story = {};
 
 export const First: Story = {
   name: 'First (move-up disabled)',
diff --git a/packages/craftcms-ui/src/components/reorder-button/reorder-button.test.ts b/packages/craftcms-ui/src/components/reorder-button/reorder-button.test.ts
index 47d0f2dc38b..3c147a31d8e 100644
--- a/packages/craftcms-ui/src/components/reorder-button/reorder-button.test.ts
+++ b/packages/craftcms-ui/src/components/reorder-button/reorder-button.test.ts
@@ -8,7 +8,7 @@ it('emits composed reorder events to list owners', async () => {
     'craft-reorder-button'
   ) as CraftReorderButton;
   const reordered = vi.fn();
-  list.addEventListener('reorder', reordered);
+  list.addEventListener('craft-reorder', reordered);
   list.append(button);
   document.body.append(list);
   await button.updateComplete;
diff --git a/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts b/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts
index b65e48f8117..de9de6da96a 100644
--- a/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts
+++ b/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts
@@ -22,7 +22,7 @@ export type ReorderOrientation = 'vertical' | 'horizontal';
  * @dependency craft-button
  * @dependency craft-icon
  *
- * @fires {CustomEvent<{direction: ReorderDirection}>} reorder - Emitted when the
+ * @fires {CustomEvent<{direction: ReorderDirection}>} craft-reorder - Emitted when the
  *   user chooses a move action. `event.detail.direction` is `'up'` or `'down'`
  *   regardless of orientation: `'up'` always means toward the start of the list
  *   ("Move forward" when horizontal) and `'down'` toward the end.
@@ -83,7 +83,7 @@ export default class CraftReorderButton extends LitElement {
     }
 
     this.dispatchEvent(
-      new CustomEvent<{direction: ReorderDirection}>('reorder', {
+      new CustomEvent<{direction: ReorderDirection}>('craft-reorder', {
         detail: {direction},
         bubbles: true,
         composed: true,
diff --git a/packages/craftcms-ui/src/components/select-color/SelectColor.mdx b/packages/craftcms-ui/src/components/select-color/SelectColor.mdx
new file mode 100644
index 00000000000..372399a49ec
--- /dev/null
+++ b/packages/craftcms-ui/src/components/select-color/SelectColor.mdx
@@ -0,0 +1,42 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SelectColorStories from './select-color.stories';
+
+<Meta of={SelectColorStories} name="Docs" />
+
+# Select Color
+
+`<craft-select-color>` offers the Craft palette as a dropdown, each option showing its swatch.
+
+<Canvas of={SelectColorStories.Default} sourceState="shown" />
+
+It is built on [Select Rich](?path=/docs/form-controls-select-controls-select-rich--docs), which is what lets each option carry a swatch beside its name.
+
+## Palette, Not Arbitrary Colour
+
+Use this where the colour has to come from the design system — a label colour, a status colour, anything that will sit alongside other Craft UI and needs to match it.
+
+For an arbitrary colour, use [Input Color](?path=/docs/form-controls-text-controls-input-color--docs), which takes any hex value. The two are not interchangeable: this one guarantees the result is a palette colour, and that guarantee is the reason to choose it.
+
+## The Transparent Option
+
+An optional "transparent" entry sits alongside the colours, for a value meaning _no colour_ rather than a colour that happens to be pale.
+
+## Events
+
+Picking a colour is a commit, so the control emits `input` and `change` together:
+
+```js
+select.addEventListener('change', () => save(select.modelValue));
+```
+
+It also emits `model-value-changed`, Lion's internal protocol name. Prefer the native events — they carry the component as `event.target`.
+
+## Accessibility
+
+Each option is named by its colour, so the list is usable without seeing the swatches.
+
+Colour names are not meanings, though. If a colour carries significance in your interface — red for a problem, green for a healthy state — say so in the label or help text, because "Red" alone does not tell a person what choosing red will do.
+
+## Properties
+
+<ArgTypes of={SelectColorStories} />
diff --git a/packages/craftcms-ui/src/components/select-color/select-color.stories.ts b/packages/craftcms-ui/src/components/select-color/select-color.stories.ts
index e3041f7f27b..a2f548d2286 100644
--- a/packages/craftcms-ui/src/components/select-color/select-color.stories.ts
+++ b/packages/craftcms-ui/src/components/select-color/select-color.stories.ts
@@ -1,76 +1,129 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {expect} from 'storybook/test';
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import './select-color.js';
+import type CraftSelectColor from './select-color.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `select-color.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: the value is bound as the
+ * `modelValue` property so an empty selection can be `null`, which an attribute
+ * cannot express.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftSelectColor>('craft-select-color');
+
+type SelectColorArgs = CraftSelectColor & typeof args;
 
 const meta = {
-  title: 'Controls/Select Color',
+  title: 'Form Controls/Select Controls/Select Color',
   component: 'craft-select-color',
-  args: {
-    label: 'Color',
-    modelValue: 'red',
-  },
-  render: function ({label, modelValue}) {
-    return html`<craft-select-color
-      label="${label}"
-      name="color"
-      .modelValue="${modelValue}"
-    ></craft-select-color>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, label: 'Color', name: 'color', 'model-value': 'red'},
+  argTypes,
+  render: (args) => html`
+    <craft-select-color
+      label="${args.label ?? ''}"
+      name="${args.name ?? 'color'}"
+      ?allow-transparent="${args['allow-transparent']}"
+      .modelValue="${args['model-value'] ?? null}"
+    ></craft-select-color>
+  `,
+} satisfies Meta<SelectColorArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<SelectColorArgs>;
 
 /**
- * A color is selected on load, so the invoker shows its swatch.
+ * A colour is selected on load, so the invoker shows its swatch.
+ *
+ * The assertions live here rather than in a unit test: the component renders a
+ * `craft-select-rich`, whose Lion internals need layout that happy-dom does not
+ * provide, so this is the only place the rendered control can be checked.
  */
 export const Default: Story = {
-  args: {},
+  play: async ({canvasElement}) => {
+    const host = canvasElement.querySelector('craft-select-color')!;
+
+    // It forwards its label and name onto the select it wraps.
+    const select = host.shadowRoot!.querySelector('craft-select-rich')!;
+    await expect(select).toBeTruthy();
+    await expect(select.getAttribute('label')).toBe('Color');
+    await expect(select.getAttribute('name')).toBe('color');
+
+    // And the selection reaches it as a model value.
+    await expect((host as {modelValue?: unknown}).modelValue).toBe('red');
+  },
 };
 
 /**
- * No color selected — the invoker shows the placeholder with no swatch.
+ * Picking a colour is a commit, so the control emits native `input` and
+ * `change` together — the events a consumer should bind, rather than Lion's
+ * internal `model-value-changed`.
+ *
+ * Asserted here rather than in a unit test for the same reason as the rest of
+ * this file: the inner `craft-select-rich` needs layout that happy-dom does
+ * not provide.
  */
+export const NativeEvents: Story = {
+  play: async ({canvasElement}) => {
+    const host = canvasElement.querySelector('craft-select-color')!;
+    const order: string[] = [];
+    host.addEventListener('input', (event) => {
+      // Dispatched from the host, so `event.target` is the component.
+      if (event.target === host) order.push('input');
+    });
+    host.addEventListener('change', (event) => {
+      if (event.target === host) order.push('change');
+    });
+
+    const inner = host.shadowRoot!.querySelector('craft-select-rich')!;
+    inner.dispatchEvent(
+      new CustomEvent('model-value-changed', {bubbles: true})
+    );
+
+    await expect(order).toEqual(['input', 'change']);
+  },
+};
+
+/** Nothing selected — the invoker shows the placeholder with no swatch. */
 export const Empty: Story = {
-  args: {
-    modelValue: null,
+  args: {'model-value': null},
+  play: async ({canvasElement}) => {
+    const host = canvasElement.querySelector('craft-select-color')!;
+
+    await expect((host as {modelValue?: unknown}).modelValue).toBeNull();
   },
 };
 
-/**
- * Preselected blue — the blue swatch appears in the invoker.
- */
+/** Preselected blue, so the blue swatch appears in the invoker. */
 export const Preselected: Story = {
-  args: {
-    modelValue: 'blue',
-  },
+  args: {'model-value': 'blue'},
 };
 
 /**
- * With the transparent option enabled and preselected, the checkerboard swatch
- * appears in the invoker.
+ * `allow-transparent` adds a "transparent" option, whose swatch is the
+ * chequerboard.
  */
 export const AllowTransparent: Story = {
-  render: () => html`
-    <craft-select-color
-      label="Color"
-      name="color"
-      allow-transparent
-      .modelValue="${'__blank__'}"
-    ></craft-select-color>
-  `,
+  args: {'allow-transparent': true, 'model-value': '__blank__'},
+  play: async ({canvasElement}) => {
+    const host = canvasElement.querySelector('craft-select-color')!;
+
+    // The transparent option is opt-in, and carries its own sentinel value.
+    await expect((host as {allowTransparent?: boolean}).allowTransparent).toBe(
+      true
+    );
+    await expect((host as {modelValue?: unknown}).modelValue).toBe('__blank__');
+  },
 };
 
-/**
- * The transparent option enabled but nothing selected, so the full list is
- * available from the invoker.
- */
+/** The same option offered but nothing selected yet. */
 export const AllowTransparentEmpty: Story = {
-  render: () => html`
-    <craft-select-color
-      label="Color"
-      name="color"
-      allow-transparent
-    ></craft-select-color>
-  `,
+  args: {'allow-transparent': true, 'model-value': null},
 };
diff --git a/packages/craftcms-ui/src/components/select-color/select-color.ts b/packages/craftcms-ui/src/components/select-color/select-color.ts
index 6f761915719..9b51855cb26 100644
--- a/packages/craftcms-ui/src/components/select-color/select-color.ts
+++ b/packages/craftcms-ui/src/components/select-color/select-color.ts
@@ -1,6 +1,7 @@
 import {html, LitElement} from 'lit';
 import {property} from 'lit/decorators.js';
 import {colors} from '@src/constants/colors';
+import {emitChange, emitInput} from '@src/utilities/form-events';
 import {t} from '@src/utilities/translate';
 import styles from './select-color.styles.js';
 import '../select-rich/select-rich.js';
@@ -14,10 +15,26 @@ function titleCase(value: string): string {
 }
 
 /**
- * @summary A color picker built on top of the rich select. Renders one option
- * per color from `constants/colors`, with an optional "transparent" option.
+ * @summary A colour picker offering the Craft palette, built on the rich
+ * select. Renders one option per colour from `constants/colors`, each with its
+ * swatch, plus an optional "transparent" option.
+ *
+ * Use it where a colour has to come from the design system — a label colour, a
+ * status colour — so the choice stays inside the palette. For an arbitrary
+ * colour, use `craft-input-color`, which takes any hex value.
  *
  * @since 1.0
+ *
+ * @fires input - Emitted when a colour is picked.
+ * @fires change - Emitted when a colour is picked. Picking is a commit, so it
+ *   follows each `input`.
+ * @fires model-value-changed - The selected colour changed. Re-dispatched from
+ *   the host as a composed event so it crosses the shadow boundary.
+ *
+ * `model-value-changed` is Lion's own protocol name, not one this package
+ * chose, and it is kept because Lion's form system dispatches and listens for
+ * it. Prefer the native events above: they are the contract this package
+ * supports, and they carry the component as `event.target`.
  */
 export default class CraftSelectColor extends LitElement {
   static override styles = [styles];
@@ -129,6 +146,11 @@ export default class CraftSelectColor extends LitElement {
     this.dispatchEvent(
       new CustomEvent('model-value-changed', {bubbles: true, composed: true})
     );
+
+    // The public contract. Picking a colour is a commit, so the pair fires
+    // together, the way a radio group's does.
+    emitInput(this);
+    emitChange(this);
   }
 
   protected override render() {
diff --git a/packages/craftcms-ui/src/components/select-rich/SelectRich.mdx b/packages/craftcms-ui/src/components/select-rich/SelectRich.mdx
new file mode 100644
index 00000000000..480fba7763c
--- /dev/null
+++ b/packages/craftcms-ui/src/components/select-rich/SelectRich.mdx
@@ -0,0 +1,34 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SelectRichStories from './select-rich.stories';
+
+<Meta of={SelectRichStories} name="Docs" />
+
+# Select Rich
+
+`<craft-select-rich>` is a dropdown whose options can hold arbitrary markup.
+
+<Canvas of={SelectRichStories.Default} sourceState="shown" />
+
+Options are [Option](?path=/docs/form-controls-select-controls-option--docs) elements rather than native `<option>`s, so each one can carry an icon, a status dot, a hint, or a thumbnail. The selected option is cloned into the invoker, so whatever an option looks like in the list is what the closed control shows.
+
+## What It Costs
+
+Replacing the native dropdown means replacing everything the platform gave you with it — the mobile picker, the built-in type-ahead, the keyboard model. Lion reimplements the keyboard and ARIA behaviour, but a person on a phone gets a custom list where they expected the system one.
+
+So use [Select](?path=/docs/form-controls-select-controls-select--docs) unless an option genuinely needs to be more than text. "It looks nicer" is not that reason.
+
+## Sizing
+
+The invoker sizes itself to its content rather than to a fixed width, so a control holding short values does not stretch across the row.
+
+`small` renders it at the smaller size.
+
+## Accessibility
+
+Lion supplies the listbox semantics, roving focus, and the wiring between label, invoker, and options.
+
+The thing to watch is what an option _announces_. Rich markup is read out too, so an option carrying an icon, a label, and a hint is announced as all three. Keep the visible label first and the decoration after it, and mark purely decorative artwork as such — otherwise every option in the list starts with the same noise.
+
+## Properties
+
+<ArgTypes of={SelectRichStories} />
diff --git a/packages/craftcms-ui/src/components/select-rich/select-rich.stories.ts b/packages/craftcms-ui/src/components/select-rich/select-rich.stories.ts
index 5224a9800db..b0d46f4ffe9 100644
--- a/packages/craftcms-ui/src/components/select-rich/select-rich.stories.ts
+++ b/packages/craftcms-ui/src/components/select-rich/select-rich.stories.ts
@@ -1,89 +1,122 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import './select-rich.js';
 import '../option/option.js';
 import '../indicator/indicator.js';
+import type CraftSelectRich from './select-rich.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `select-rich.ts` surfaces it here without touching this file.
+ *
+ * The options are written out rather than generated: Lion registers each
+ * `craft-option` as a real child, and a generated slot would wrap them in a
+ * `<span>` that Lion adopts as the control instead.
+ */
+const {args, argTypes} =
+  getStorybookHelpers<CraftSelectRich>('craft-select-rich');
+
+type SelectRichArgs = CraftSelectRich & typeof args;
+
+/** The shell every story shares, so each one only supplies its options. */
+const select = (args: Record<string, unknown>, options: unknown) => html`
+  <craft-select-rich
+    name="${(args.name as string) ?? ''}"
+    ?small="${args.small}"
+    ?disabled="${args.disabled}"
+  >
+    <label slot="label">${args['label-slot']}</label>
+    ${options}
+  </craft-select-rich>
+`;
 
 const meta = {
-  title: 'Controls/Select Rich',
+  title: 'Form Controls/Select Controls/Select Rich',
   component: 'craft-select-rich',
-  args: {},
-  render: function () {
-    return html`
-      <craft-select-rich label="Favorite Fruit" name="fruit">
-        <craft-option .choiceValue=${'apple'}>Apple</craft-option>
-        <craft-option .choiceValue=${'banana'}>Banana</craft-option>
-        <craft-option .choiceValue=${'cherry'}>Cherry</craft-option>
-        <craft-option .choiceValue=${'grape'}>Grape</craft-option>
-        <craft-option .choiceValue=${'mango'}>Mango</craft-option>
-      </craft-select-rich>
-    `;
-  },
-} satisfies Meta<any>;
+  args: {...args, name: 'fruit', 'label-slot': 'Favorite Fruit'},
+  argTypes,
+  render: (args) =>
+    select(
+      args,
+      html`
+        <craft-option .choiceValue="${'apple'}">Apple</craft-option>
+        <craft-option .choiceValue="${'banana'}">Banana</craft-option>
+        <craft-option .choiceValue="${'cherry'}">Cherry</craft-option>
+        <craft-option .choiceValue="${'grape'}">Grape</craft-option>
+        <craft-option .choiceValue="${'mango'}">Mango</craft-option>
+      `
+    ),
+} satisfies Meta<SelectRichArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<SelectRichArgs>;
 
-export const Default: Story = {
-  args: {},
-};
+/** Options are `craft-option` children rather than native `<option>`s. */
+export const Default: Story = {};
 
+/** Which is what lets an option hold markup rather than only text. */
 export const RichOptions: Story = {
-  args: {},
-  render: function () {
-    return html`
-      <craft-select-rich label="System Status" name="status">
-        <craft-option .choiceValue=${'online'}>
+  args: {name: 'status', 'label-slot': 'System Status'},
+  render: (args) =>
+    select(
+      args,
+      html`
+        <craft-option .choiceValue="${'online'}">
           <div class="flex items-center gap-1">
-            <craft-indicator variant="success"></craft-indicator>
-            <span>Online</span>
+            <craft-indicator fill="success"></craft-indicator
+            ><span>Online</span>
           </div>
         </craft-option>
-        <craft-option .choiceValue=${'maintenance'}>
+        <craft-option .choiceValue="${'maintenance'}">
           <div class="flex items-center gap-1">
-            <craft-indicator variant="warning"></craft-indicator>
-            <span>Maintenance</span>
+            <craft-indicator fill="warning"></craft-indicator
+            ><span>Maintenance</span>
           </div>
         </craft-option>
-        <craft-option .choiceValue=${'offline'}>
+        <craft-option .choiceValue="${'offline'}">
           <div class="flex items-center gap-1">
-            <craft-indicator variant="danger"></craft-indicator>
-            <span>Offline</span>
+            <craft-indicator fill="danger"></craft-indicator
+            ><span>Offline</span>
           </div>
         </craft-option>
-      </craft-select-rich>
-    `;
-  },
+      `
+    ),
 };
 
+/** `small` steps the control down for a dense row. */
 export const Small: Story = {
-  args: {},
-  render: function () {
-    return html`
-      <craft-select-rich label="Size" name="size" small>
-        <craft-option .choiceValue=${'sm'}>Small</craft-option>
-        <craft-option .choiceValue=${'md'}>Medium</craft-option>
-        <craft-option .choiceValue=${'lg'}>Large</craft-option>
-      </craft-select-rich>
-    `;
-  },
+  args: {small: true, name: 'size', 'label-slot': 'Size'},
+  render: (args) =>
+    select(
+      args,
+      html`
+        <craft-option .choiceValue="${'sm'}">Small</craft-option>
+        <craft-option .choiceValue="${'md'}">Medium</craft-option>
+        <craft-option .choiceValue="${'lg'}">Large</craft-option>
+      `
+    ),
 };
 
+/** An option's `hint` sits after its label, for a count or a note. */
 export const WithHints: Story = {
-  args: {},
-  render: function () {
-    return html`
-      <craft-select-rich label="Section" name="section">
-        <craft-option .choiceValue=${'blog'} hint="12 entries"
+  args: {name: 'section', 'label-slot': 'Section'},
+  render: (args) =>
+    select(
+      args,
+      html`
+        <craft-option .choiceValue="${'blog'}" hint="12 entries"
           >Blog</craft-option
         >
-        <craft-option .choiceValue=${'news'} hint="4 entries"
+        <craft-option .choiceValue="${'news'}" hint="4 entries"
           >News</craft-option
         >
-        <craft-option .choiceValue=${'docs'} hint="89 entries"
+        <craft-option .choiceValue="${'docs'}" hint="89 entries"
           >Documentation</craft-option
         >
-      </craft-select-rich>
-    `;
-  },
+      `
+    ),
 };
diff --git a/packages/craftcms-ui/src/components/select-rich/select-rich.test.ts b/packages/craftcms-ui/src/components/select-rich/select-rich.test.ts
new file mode 100644
index 00000000000..e67c62278cb
--- /dev/null
+++ b/packages/craftcms-ui/src/components/select-rich/select-rich.test.ts
@@ -0,0 +1,66 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './select-rich.js';
+import type CraftSelectRich from './select-rich.js';
+
+async function createSelectRich(
+  attrs: Record<string, string> = {}
+): Promise<CraftSelectRich> {
+  const element = document.createElement(
+    'craft-select-rich'
+  ) as CraftSelectRich;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = '<label slot="label">Favorite Fruit</label>';
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+/**
+ * Slotted `craft-option`s are not exercised here: registering one runs Lion's
+ * listbox wiring, which needs layout happy-dom does not provide and throws
+ * before the option lands. The options, the keyboard navigation, and the
+ * selection are covered by the Storybook stories, which run in a real browser.
+ */
+describe('craft-select-rich', () => {
+  it('upgrades and renders its field chrome', async () => {
+    const element = await createSelectRich();
+
+    expect(element.shadowRoot).toBeTruthy();
+    expect(element.querySelector('label[slot="label"]')).toBeTruthy();
+  });
+
+  it('takes a name for posting', async () => {
+    const element = await createSelectRich({name: 'fruit'});
+
+    expect(element.name).toBe('fruit');
+  });
+
+  it('reflects small so the stylesheet can act on it', async () => {
+    const element = await createSelectRich({small: ''});
+
+    expect(element.hasAttribute('small')).toBe(true);
+  });
+
+  /**
+   * The component registers its own elements into the shadow root rather than
+   * relying on globally defined tags, which is how a rich option renders.
+   */
+  it('scopes the elements it renders', async () => {
+    const scoped = (
+      CraftSelectRichConstructor as unknown as {
+        scopedElements: Record<string, unknown>;
+      }
+    ).scopedElements;
+
+    expect(Object.keys(scoped).length).toBeGreaterThan(0);
+  });
+});
+
+const CraftSelectRichConstructor = customElements.get('craft-select-rich')!;
diff --git a/packages/craftcms-ui/src/components/select-rich/select-rich.ts b/packages/craftcms-ui/src/components/select-rich/select-rich.ts
index 94256263707..75f7ec7bfc5 100644
--- a/packages/craftcms-ui/src/components/select-rich/select-rich.ts
+++ b/packages/craftcms-ui/src/components/select-rich/select-rich.ts
@@ -28,6 +28,9 @@ export default class CraftSelectRich extends LionSelectRich {
     return [...super.styles, styles];
   }
 
+  /**
+   * Registers the elements the select renders into its own shadow root.
+   */
   static override get scopedElements() {
     return {
       ...super.scopedElements,
diff --git a/packages/craftcms-ui/src/components/select/Select.mdx b/packages/craftcms-ui/src/components/select/Select.mdx
new file mode 100644
index 00000000000..49ff7e3bd3d
--- /dev/null
+++ b/packages/craftcms-ui/src/components/select/Select.mdx
@@ -0,0 +1,36 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SelectStories from './select.stories';
+
+<Meta of={SelectStories} name="Docs" />
+
+# Select
+
+`<craft-select>` is a dropdown built on the native `<select>`.
+
+<Canvas of={SelectStories.Default} sourceState="shown" />
+
+The options are real `<option>` elements, so the browser draws the dropdown itself.
+
+## Why the Native Control
+
+On a phone or tablet, the native picker is a full-screen wheel or list the person already knows how to use — better than anything a component can draw, and it comes with keyboard support, type-ahead, and screen reader behaviour for free.
+
+That is the trade this component makes: you get the platform's dropdown, and in exchange the options can only be text.
+
+## Choosing Between the Three
+
+- **Select** — plain text options. The default choice.
+- **[Select Rich](?path=/docs/form-controls-select-controls-select-rich--docs)** — an option needs more than text: an icon, a status, a hint.
+- **[Combobox](?path=/docs/form-controls-select-controls-combobox--docs)** — the list is long enough that a person needs to filter it.
+
+Reach for the plainest one that fits. Each step up trades platform behaviour for presentation.
+
+## Accessibility
+
+The native select brings its own semantics, keyboard handling, and mobile affordances, and Lion wires the label and validation feedback around it.
+
+Label it with the thing being chosen. A select is announced with its current value, so an unlabelled one reads as a value with no question attached.
+
+## Properties
+
+<ArgTypes of={SelectStories} />
diff --git a/packages/craftcms-ui/src/components/select/select.stories.ts b/packages/craftcms-ui/src/components/select/select.stories.ts
index 8769ab2a8ec..2d0c336c4b7 100644
--- a/packages/craftcms-ui/src/components/select/select.stories.ts
+++ b/packages/craftcms-ui/src/components/select/select.stories.ts
@@ -1,37 +1,64 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './select.js';
+import type CraftSelect from './select.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `select.ts` surfaces it here without touching this file.
+ *
+ * The template is written out rather than generated: Lion expects the real
+ * `<select>` in its `input` slot, and a generated slot wraps its content in a
+ * `<span>`, which Lion then adopts as the control.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftSelect>('craft-select');
+
+type SelectArgs = CraftSelect & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Select',
+  title: 'Form Controls/Select Controls/Select',
   component: 'craft-select',
-  args: {},
-  render: function () {
-    return html`
-      <craft-select
-        label="Language"
-        id="site-language"
-        name="language"
-        .modelValue="en-US"
-      >
-        <select slot="input">
-          <option value="">Select a language</option>
-          <option value="fr-FR">French</option>
-          <option value="en-US">English</option>
-          <option value="de-DE">German</option>
-        </select>
-      </craft-select>
-    `;
-  },
-} satisfies Meta<any>;
+  args: {...args, name: 'language', 'label-slot': 'Language'},
+  argTypes,
+  render: (args) => html`
+    <craft-select
+      name="${args.name ?? ''}"
+      ?small="${args.small}"
+      ?disabled="${args.disabled}"
+    >
+      <label slot="label">${args['label-slot']}</label>
+      ${args['help-text-slot']
+        ? html`<span slot="help-text">${args['help-text-slot']}</span>`
+        : ''}
+      <select slot="input">
+        <option value="">Select a language</option>
+        <option value="fr-FR">French</option>
+        <option value="en-US" selected>English</option>
+        <option value="de-DE">German</option>
+      </select>
+    </craft-select>
+  `,
+} satisfies Meta<SelectArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<SelectArgs>;
+
+/** The native `<select>` goes in the `input` slot; the component draws the rest. */
+export const Default: Story = {};
+
+/** `small` steps the control down for a dense row. */
+export const Small: Story = {
+  args: {small: true},
+};
+
+export const WithHelpText: Story = {
+  args: {'help-text-slot': 'Used for date and number formatting.'},
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+export const Disabled: Story = {
+  args: {disabled: true},
 };
diff --git a/packages/craftcms-ui/src/components/select/select.test.ts b/packages/craftcms-ui/src/components/select/select.test.ts
new file mode 100644
index 00000000000..a6bfe4a67bf
--- /dev/null
+++ b/packages/craftcms-ui/src/components/select/select.test.ts
@@ -0,0 +1,81 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './select.js';
+import type CraftSelect from './select.js';
+
+const OPTIONS = `
+  <label slot="label">Language</label>
+  <select slot="input">
+    <option value="">Select a language</option>
+    <option value="fr-FR">French</option>
+    <option value="en-US">English</option>
+  </select>
+`;
+
+async function createSelect(
+  attrs: Record<string, string> = {},
+  innerHTML = OPTIONS
+): Promise<CraftSelect> {
+  const element = document.createElement('craft-select') as CraftSelect;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+function native(element: CraftSelect): HTMLSelectElement {
+  return element.querySelector('select')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-select', () => {
+  /**
+   * The native `<select>` is slotted rather than rendered, so the component
+   * adds the field chrome around whatever the server or the page already put
+   * there.
+   */
+  it('adopts the slotted select', async () => {
+    const element = await createSelect();
+
+    expect(native(element)).toBeTruthy();
+    expect(native(element).options).toHaveLength(3);
+  });
+
+  it('wires the label to the control', async () => {
+    const element = await createSelect();
+
+    expect(element.querySelector('label')!.getAttribute('for')).toBe(
+      native(element).id
+    );
+  });
+
+  it('reads the selection as its model value', async () => {
+    const element = await createSelect();
+
+    native(element).value = 'en-US';
+    native(element).dispatchEvent(new Event('change', {bubbles: true}));
+    await element.updateComplete;
+
+    expect(element.modelValue).toBe('en-US');
+  });
+
+  it('reflects small so the stylesheet can act on it', async () => {
+    const element = await createSelect({small: ''});
+
+    expect(element.hasAttribute('small')).toBe(true);
+  });
+
+  it('disables the native control', async () => {
+    const element = await createSelect({disabled: ''});
+
+    expect(native(element).disabled).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/select/select.ts b/packages/craftcms-ui/src/components/select/select.ts
index 79908eff6cc..53da2baba63 100644
--- a/packages/craftcms-ui/src/components/select/select.ts
+++ b/packages/craftcms-ui/src/components/select/select.ts
@@ -5,11 +5,29 @@ import '../option/option.js';
 import '../icon/icon.js';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary A dropdown built on the native `<select>`, with Craft's field
+ * chrome and a chevron indicator around it.
+ *
+ * The options are real `<option>` elements, so the browser supplies the
+ * dropdown — which is what you want on touch devices, where the native picker
+ * is far better than anything a component can draw.
+ *
+ * Reach for `craft-select-rich` when an option needs more than text: an icon,
+ * a status, a hint. Reach for `craft-combobox` when the list is long enough to
+ * need filtering.
+ *
+ * @slot input - The native `<select>` and its options.
+ * @slot label - The field's label, as an alternative to the `label` attribute.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages.
+ */
 export default class CraftSelect extends LionSelect {
   static override get styles() {
     return [...super.styles, styles];
   }
 
+  /** Renders the control at a smaller size. */
   @property({reflect: true, type: Boolean}) small = false;
 
   // oxlint-disable-next-line class-methods-use-this
diff --git a/packages/craftcms-ui/src/components/shortcut/Shortcut.mdx b/packages/craftcms-ui/src/components/shortcut/Shortcut.mdx
new file mode 100644
index 00000000000..fe8aa151318
--- /dev/null
+++ b/packages/craftcms-ui/src/components/shortcut/Shortcut.mdx
@@ -0,0 +1,26 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ShortcutStories from './shortcut.stories';
+
+<Meta of={ShortcutStories} name="Docs" />
+
+# Shortcut
+
+`<craft-shortcut>` renders a keyboard shortcut.
+
+<Canvas of={ShortcutStories.Default} sourceState="shown" />
+
+It shows the platform's own symbols — ⌘ on a Mac, Ctrl on Windows — detected from the browser, so the same markup reads correctly everywhere. `os` overrides the detection when you need to show a specific platform.
+
+## Display Only
+
+The component renders a shortcut; it does not bind one. Whatever handles the key press is separate, which means the two can disagree — a rendered shortcut that nothing listens for is a promise the interface does not keep.
+
+## Accessibility
+
+Symbols like ⌘ and ⇧ are announced inconsistently, and sometimes not at all.
+
+Where a shortcut is the only way to reach something, it needs a text equivalent nearby rather than living solely in the symbols. Inside an [Action Item](?path=/docs/components-action-item--docs), the item's label carries the meaning and the shortcut is supplementary, which is the arrangement that works.
+
+## Properties
+
+<ArgTypes of={ShortcutStories} />
diff --git a/packages/craftcms-ui/src/components/shortcut/shortcut.test.ts b/packages/craftcms-ui/src/components/shortcut/shortcut.test.ts
new file mode 100644
index 00000000000..261c584ef93
--- /dev/null
+++ b/packages/craftcms-ui/src/components/shortcut/shortcut.test.ts
@@ -0,0 +1,61 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './shortcut.js';
+import type CraftShortcut from './shortcut.js';
+
+async function createShortcut(
+  attrs: Record<string, string> = {},
+  innerHTML = 'S'
+): Promise<CraftShortcut> {
+  const element = document.createElement('craft-shortcut') as CraftShortcut;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+/** The prefix the component renders, without the slotted key. */
+function prefix(element: CraftShortcut): string {
+  return element.shadowRoot!.querySelector('.shortcut')!.textContent!.trim();
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-shortcut', () => {
+  it('uses the platform symbols on a Mac', async () => {
+    expect(prefix(await createShortcut({os: 'Mac'}))).toBe('⌘');
+    expect(prefix(await createShortcut({os: 'Mac', alt: ''}))).toBe('⌥⌘');
+    expect(prefix(await createShortcut({os: 'Mac', shift: ''}))).toBe('⇧⌘');
+    expect(prefix(await createShortcut({os: 'Mac', alt: '', shift: ''}))).toBe(
+      '⌥⇧⌘'
+    );
+  });
+
+  it('spells the modifiers out elsewhere', async () => {
+    expect(prefix(await createShortcut({os: 'Windows'}))).toBe('Ctrl+');
+    expect(prefix(await createShortcut({os: 'Windows', alt: ''}))).toBe(
+      'Ctrl+Alt+'
+    );
+    expect(prefix(await createShortcut({os: 'Linux'}))).toBe('Super+');
+    expect(prefix(await createShortcut({os: 'Linux', shift: ''}))).toBe(
+      'Super+Shift+'
+    );
+  });
+
+  /** An unknown platform falls back to the Ctrl spelling rather than nothing. */
+  it('falls back to Ctrl for an unknown platform', async () => {
+    expect(prefix(await createShortcut({os: 'Unknown'}))).toBe('Ctrl+');
+  });
+
+  it('renders the key from the default slot', async () => {
+    const element = await createShortcut({os: 'Mac'}, 'K');
+
+    expect(element.textContent).toBe('K');
+    expect(element.shadowRoot!.querySelector('slot')).toBeTruthy();
+  });
+});
diff --git a/packages/craftcms-ui/src/components/shortcut/shortcut.ts b/packages/craftcms-ui/src/components/shortcut/shortcut.ts
index 6aa18f6d1b8..6d2650534db 100644
--- a/packages/craftcms-ui/src/components/shortcut/shortcut.ts
+++ b/packages/craftcms-ui/src/components/shortcut/shortcut.ts
@@ -33,6 +33,10 @@ export default class CraftShortcut extends LitElement {
   @property({type: Boolean})
   shift: boolean = false;
 
+  /**
+   * Which platform's modifier symbols to render. Detected from the browser
+   * when not set, so a Mac shows ⌘ and Windows shows Ctrl.
+   */
   @property()
   os: 'Mac' | 'Windows' | 'Linux' | 'Unknown' = 'Unknown';
 
diff --git a/packages/craftcms-ui/src/components/slide-picker/SlidePicker.mdx b/packages/craftcms-ui/src/components/slide-picker/SlidePicker.mdx
new file mode 100644
index 00000000000..2ef5119a969
--- /dev/null
+++ b/packages/craftcms-ui/src/components/slide-picker/SlidePicker.mdx
@@ -0,0 +1,54 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SlidePickerStories from './slide-picker.stories';
+
+<Meta of={SlidePickerStories} name="Docs" />
+
+# Slide Picker
+
+`<craft-slide-picker>` picks a number from a small set of steps.
+
+<Canvas of={SlidePickerStories.Default} sourceState="shown" />
+
+Use it where the range is short and every step is meaningful — a column count, a level, a size. For a continuous range use [Slide Rule](?path=/docs/form-controls-slide-rule--docs); for an exact number a person already knows, a number input is faster than dragging.
+
+<Canvas of={SlidePickerStories.FiveSteps} sourceState="shown" />
+
+<Canvas of={SlidePickerStories.ReadOnly} sourceState="shown" />
+
+## Posting a Value
+
+The control is form-associated. Give it a `name` and it posts with the form the way a native input does — `new FormData(form)` reads it, `form.reset()` puts back the value the markup started with, and there is no hidden input to keep in sync.
+
+<Canvas of={SlidePickerStories.InAForm} sourceState="shown" />
+
+`readonly` and `disabled` differ in what they post: a read-only control still submits its value, a disabled one is left out of submission entirely.
+
+It emits the same events a radio group does. Every step is a commit, so `change` follows each `input`:
+
+```js
+picker.addEventListener('change', () => {
+  console.log(picker.value);
+});
+```
+
+## Announcing the Value
+
+A slider's value is a number, and a number on its own rarely means anything.
+
+`value-unit` supplies the units, so the control announces "3 columns" rather than "3":
+
+```html
+<craft-slide-picker value-unit="columns"></craft-slide-picker>
+```
+
+When a unit is not enough, `valueLabel` formats the announced value however you like. It is a property rather than an attribute, so bind it with `.valueLabel`.
+
+## Accessibility
+
+The control is a slider with a name from `label` and a described-by from `described-by`, which [Field](?path=/docs/form-controls-field--docs) supplies when it wraps one.
+
+Sliders are hard to operate precisely with a pointer and easy with a keyboard, so the arrow-key behaviour is not a fallback — it is how many people will use it. Keep the step count low enough that arrowing to a value is quick.
+
+## Properties
+
+<ArgTypes of={SlidePickerStories} />
diff --git a/packages/craftcms-ui/src/components/slide-picker/slide-picker.stories.ts b/packages/craftcms-ui/src/components/slide-picker/slide-picker.stories.ts
index bae5bb76e76..024768a6465 100644
--- a/packages/craftcms-ui/src/components/slide-picker/slide-picker.stories.ts
+++ b/packages/craftcms-ui/src/components/slide-picker/slide-picker.stories.ts
@@ -1,5 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 import type CraftSlidePicker from './slide-picker.js';
+import {expect} from 'storybook/test';
+import {html} from 'lit';
 import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import './slide-picker.js';
 
@@ -7,7 +9,7 @@ const {events, args, argTypes, template} =
   getStorybookHelpers('craft-slide-picker');
 
 const meta: Meta<CraftSlidePicker> = {
-  title: 'Controls/Slide Picker',
+  title: 'Form Controls/Slide Picker',
   component: 'craft-slide-picker',
   args,
   argTypes,
@@ -28,7 +30,7 @@ export const Default: Story = {
 
 export const ReadOnly: Story = {
   args: {
-    readOnly: true,
+    readonly: true,
   },
 };
 
@@ -41,3 +43,54 @@ export const FiveSteps: Story = {
     label: 'Completion',
   },
 };
+
+/**
+ * The control is form-associated, so `name` is all it takes to post a value —
+ * there is no hidden input behind it.
+ *
+ * The assertions run here rather than in a unit test because they exercise the
+ * user agent's own side of form association: excluding a disabled control from
+ * submission, and calling back on reset. happy-dom has no `ElementInternals` at
+ * all, and the polyfill the unit tests use does not carry either behaviour.
+ */
+export const InAForm: Story = {
+  render: () => html`
+    <form>
+      <craft-slide-picker
+        name="columns"
+        label="Number of columns"
+        value-unit=" columns"
+        min="1"
+        max="6"
+        step="1"
+        value="3"
+      ></craft-slide-picker>
+    </form>
+  `,
+  play: async ({canvasElement}) => {
+    const form = canvasElement.querySelector('form')!;
+    const picker = form.querySelector('craft-slide-picker')!;
+
+    // It belongs to the form, and posts under its name.
+    await expect(picker.form).toBe(form);
+    await expect(new FormData(form).get('columns')).toBe('3');
+
+    // A disabled control is left out of submission entirely.
+    picker.disabled = true;
+    await picker.updateComplete;
+    await expect(new FormData(form).get('columns')).toBeNull();
+
+    picker.disabled = false;
+    await picker.updateComplete;
+
+    // And a reset puts back the value the markup started with.
+    picker.value = 6;
+    await picker.updateComplete;
+    await expect(new FormData(form).get('columns')).toBe('6');
+
+    form.reset();
+    await picker.updateComplete;
+    await expect(picker.value).toBe(3);
+    await expect(new FormData(form).get('columns')).toBe('3');
+  },
+};
diff --git a/packages/craftcms-ui/src/components/slide-picker/slide-picker.styles.ts b/packages/craftcms-ui/src/components/slide-picker/slide-picker.styles.ts
index 9e3b34ae0ff..577fcb482df 100644
--- a/packages/craftcms-ui/src/components/slide-picker/slide-picker.styles.ts
+++ b/packages/craftcms-ui/src/components/slide-picker/slide-picker.styles.ts
@@ -57,7 +57,7 @@ export default css`
     z-index: 1;
   }
 
-  :host([read-only]) .slide-picker__segment {
+  :host([readonly]) .slide-picker__segment {
     cursor: default;
     opacity: 0.7;
   }
diff --git a/packages/craftcms-ui/src/components/slide-picker/slide-picker.test.ts b/packages/craftcms-ui/src/components/slide-picker/slide-picker.test.ts
index 35b04ce12c1..ca7232f0c41 100644
--- a/packages/craftcms-ui/src/components/slide-picker/slide-picker.test.ts
+++ b/packages/craftcms-ui/src/components/slide-picker/slide-picker.test.ts
@@ -56,24 +56,35 @@ describe('craft-slide-picker', () => {
     expect(lastActive[0]!.getAttribute('title')).toBe('50');
   });
 
-  it('emits value-change with the selected value on segment click', async () => {
+  it('emits input then change on segment click', async () => {
     const element = await createSlidePicker({
       min: 0,
       max: 100,
       step: 10,
       value: 0,
     });
-    const handler = vi.fn();
-    element.addEventListener('value-change', handler as EventListener);
+    const order: string[] = [];
+    element.addEventListener('input', () => order.push('input'));
+    element.addEventListener('change', () => order.push('change'));
 
     segments(element)[3]!.click(); // 0, 10, 20, 30 -> 30
     await element.updateComplete;
 
     expect(element.value).toBe(30);
-    expect(handler).toHaveBeenCalledTimes(1);
-    expect((handler.mock.calls[0]![0] as CustomEvent).detail).toEqual({
-      value: 30,
-    });
+    // Every step is a commit, so the pair fires together.
+    expect(order).toEqual(['input', 'change']);
+  });
+
+  it('does not emit when the value is set programmatically', async () => {
+    const element = await createSlidePicker({value: 0});
+    const handler = vi.fn();
+    element.addEventListener('input', handler as EventListener);
+    element.addEventListener('change', handler as EventListener);
+
+    element.value = 40;
+    await element.updateComplete;
+
+    expect(handler).not.toHaveBeenCalled();
   });
 
   it('clamps out-of-range values and snaps off-step values', async () => {
@@ -102,7 +113,7 @@ describe('craft-slide-picker', () => {
       value: 50,
     });
     const handler = vi.fn();
-    element.addEventListener('value-change', handler as EventListener);
+    element.addEventListener('change', handler as EventListener);
 
     const press = (key: string) =>
       slider(element).dispatchEvent(
@@ -131,11 +142,11 @@ describe('craft-slide-picker', () => {
       step: 10,
       value: 50,
     });
-    element.readOnly = true;
+    element.readonly = true;
     await element.updateComplete;
 
     const handler = vi.fn();
-    element.addEventListener('value-change', handler as EventListener);
+    element.addEventListener('change', handler as EventListener);
 
     segments(element)[0]!.click();
     slider(element).dispatchEvent(
@@ -165,6 +176,23 @@ describe('craft-slide-picker', () => {
     expect(s.getAttribute('aria-valuetext')).toBe('50');
   });
 
+  it('ignores input while disabled', async () => {
+    const element = await createSlidePicker({value: 50});
+    element.disabled = true;
+    await element.updateComplete;
+
+    const handler = vi.fn();
+    element.addEventListener('change', handler as EventListener);
+
+    segments(element)[0]!.click();
+    await element.updateComplete;
+
+    expect(element.value).toBe(50);
+    expect(handler).not.toHaveBeenCalled();
+    expect(slider(element).getAttribute('tabindex')).toBe('-1');
+    expect(slider(element).getAttribute('aria-disabled')).toBe('true');
+  });
+
   it('formats the value text with valueUnit and valueLabel', async () => {
     const withUnit = await createSlidePicker({
       min: 0,
@@ -187,3 +215,61 @@ describe('craft-slide-picker', () => {
     expect(slider(withLabel).getAttribute('aria-valuetext')).toBe('50 columns');
   });
 });
+
+/**
+ * happy-dom has no `ElementInternals`, so these run against
+ * `element-internals-polyfill` (wired up in the components project's setup).
+ * The polyfill carries `setFormValue` and `FormData`, but not the parts the
+ * user agent itself performs — leaving a disabled control out of submission,
+ * and calling `formResetCallback` on reset. Those are covered in the browser,
+ * in `slide-picker.stories.ts`.
+ */
+describe('craft-slide-picker form association', () => {
+  async function createInForm(
+    props: Partial<Pick<CraftSlidePicker, 'name' | 'value'>> = {}
+  ): Promise<{form: HTMLFormElement; element: CraftSlidePicker}> {
+    const form = document.createElement('form');
+    const element = document.createElement('craft-slide-picker');
+    Object.assign(element, {min: 0, max: 100, step: 10, value: 0, ...props});
+    form.append(element);
+    document.body.append(form);
+    await element.updateComplete;
+
+    return {form, element};
+  }
+
+  it('posts its value under its name', async () => {
+    const {form} = await createInForm({name: 'columns', value: 30});
+
+    expect(new FormData(form).get('columns')).toBe('30');
+  });
+
+  it('posts the updated value after user input', async () => {
+    const {form, element} = await createInForm({name: 'columns', value: 0});
+
+    segments(element)[5]!.click(); // -> 50
+    await element.updateComplete;
+
+    expect(new FormData(form).get('columns')).toBe('50');
+  });
+
+  it('posts nothing without a name', async () => {
+    const {form} = await createInForm({value: 30});
+
+    expect([...new FormData(form).keys()]).toEqual([]);
+  });
+
+  it('restores the value it was given back', async () => {
+    const {element} = await createInForm({name: 'columns', value: 30});
+
+    segments(element)[8]!.click(); // -> 80
+    await element.updateComplete;
+    expect(element.value).toBe(80);
+
+    // What the user agent hands back on `form.reset()`.
+    element._restoreFormValue('30');
+    await element.updateComplete;
+
+    expect(element.value).toBe(30);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/slide-picker/slide-picker.ts b/packages/craftcms-ui/src/components/slide-picker/slide-picker.ts
index 3e3f09aac7d..02d106fd820 100644
--- a/packages/craftcms-ui/src/components/slide-picker/slide-picker.ts
+++ b/packages/craftcms-ui/src/components/slide-picker/slide-picker.ts
@@ -2,6 +2,7 @@ import {html, LitElement, nothing, type PropertyValues} from 'lit';
 import {property} from 'lit/decorators.js';
 import {classMap} from 'lit/directives/class-map.js';
 import {ifDefined} from 'lit/directives/if-defined.js';
+import {FormAssociated} from '@src/mixins/FormAssociated';
 import {t} from '@src/utilities/translate';
 import styles from './slide-picker.styles.js';
 
@@ -9,22 +10,63 @@ import styles from './slide-picker.styles.js';
  * @summary Segmented slider control for selecting numeric values in fixed steps.
  * @since 1.0
  *
- * @fires {CustomEvent<{value:number}>} value-change - Emitted when user input
- * changes the current value.
+ * @attr {string} name - Field name. The control posts under this, like any
+ * other input. Supplied by the `FormAssociated` mixin.
+ * @attr {boolean} disabled - Whether the control responds to input. A disabled
+ * control is left out of form submission. Supplied by the `FormAssociated`
+ * mixin.
+ *
+ * @fires input - Emitted on every alteration to the value.
+ * @fires change - Emitted when an alteration to the value is committed by the
+ * user. Every alteration is a commit here, so it follows each `input`.
  */
-export default class CraftSlidePicker extends LitElement {
+export default class CraftSlidePicker extends FormAssociated(LitElement) {
   static override styles = [styles];
 
+  /** Lowest selectable value. */
   @property({type: Number}) min = 0;
+  /** Highest selectable value. */
   @property({type: Number}) max = 100;
+  /** Spacing between selectable values. */
   @property({type: Number}) step = 10;
+  /** The currently selected value. */
   @property({type: Number}) value = 0;
+  /** Accessible name for the slider. */
   @property() label = t('Number of columns');
+  /**
+   * Id of the element describing the control, applied as `aria-describedby`.
+   * `craft-field` supplies this for you.
+   */
   @property({attribute: 'described-by'}) describedBy?: string;
+  /**
+   * Unit appended to the announced value — `columns`, `px`. Without one a
+   * bare number is all a screen reader gets.
+   */
   @property({attribute: 'value-unit'}) valueUnit = '';
+  /**
+   * Formats the announced value, for when a number and a unit are not enough.
+   * A property rather than an attribute, so bind it with `.valueLabel`.
+   */
   @property({attribute: false}) valueLabel?: (value: number) => string;
-  @property({type: Boolean, reflect: true, attribute: 'read-only'})
-  readOnly = false;
+  /**
+   * Renders the current value without allowing it to be changed. Spelled the
+   * way HTML spells it, and the way the other controls do. A read-only control
+   * still posts its value; a `disabled` one does not.
+   */
+  @property({type: Boolean, reflect: true}) readonly = false;
+
+  /** Whether the control responds to input. */
+  get #editable(): boolean {
+    return !this.readonly && !this.disabled;
+  }
+
+  override _formValue(): string | null {
+    return this.name ? String(this.value) : null;
+  }
+
+  override _restoreFormValue(value: string | null): void {
+    this.value = this.#normalize(Number(value ?? this.min));
+  }
 
   protected override willUpdate(changed: PropertyValues<this>) {
     super.willUpdate(changed);
@@ -92,25 +134,22 @@ export default class CraftSlidePicker extends LitElement {
     this.value = normalized;
 
     if (emit) {
-      this.dispatchEvent(
-        new CustomEvent<{value: number}>('value-change', {
-          detail: {value: normalized},
-          bubbles: true,
-          composed: true,
-        })
-      );
+      // Every step is a commit, so `change` follows `input` immediately —
+      // what a radio group does, not what a range slider does.
+      this.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
+      this.dispatchEvent(new Event('change', {bubbles: true, composed: true}));
     }
   }
 
   #handleSegmentClick(value: number) {
-    if (this.readOnly) {
+    if (!this.#editable) {
       return;
     }
     this.#setValue(value, true);
   }
 
   #handleKeyDown(event: KeyboardEvent) {
-    if (this.readOnly) {
+    if (!this.#editable) {
       return;
     }
 
@@ -151,13 +190,14 @@ export default class CraftSlidePicker extends LitElement {
       <div
         class="slide-picker"
         role="slider"
-        tabindex=${this.readOnly ? -1 : 0}
+        tabindex=${this.#editable ? 0 : -1}
         aria-label=${this.label}
         aria-valuemin=${this.min}
         aria-valuemax=${this.max}
         aria-valuenow=${this.value}
         aria-valuetext=${this.#valueText(this.value)}
-        aria-readonly=${this.readOnly ? 'true' : 'false'}
+        aria-readonly=${this.readonly ? 'true' : 'false'}
+        aria-disabled=${this.disabled ? 'true' : 'false'}
         aria-describedby=${ifDefined(this.describedBy)}
         @keydown=${this.#handleKeyDown}
       >
diff --git a/packages/craftcms-ui/src/components/slide-rule/SlideRule.mdx b/packages/craftcms-ui/src/components/slide-rule/SlideRule.mdx
new file mode 100644
index 00000000000..2782d47e785
--- /dev/null
+++ b/packages/craftcms-ui/src/components/slide-rule/SlideRule.mdx
@@ -0,0 +1,45 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SlideRuleStories from './slide-rule.stories';
+
+<Meta of={SlideRuleStories} name="Docs" />
+
+# Slide Rule
+
+`<craft-slide-rule>` picks an angle from a scrolling ruler.
+
+<Canvas of={SlideRuleStories.Default} sourceState="shown" />
+
+It is built for rotation — image cropping, focal points — where a person adjusts by feel and watches the result rather than reading a number.
+
+<Canvas of={SlideRuleStories.StartingAngle} sourceState="shown" />
+
+For a short set of discrete steps, use [Slide Picker](?path=/docs/form-controls-slide-picker--docs).
+
+## Posting a Value
+
+The control is form-associated: give it a `name` and the angle posts with the form, and comes back on `form.reset()`.
+
+<Canvas of={SlideRuleStories.InAForm} sourceState="shown" />
+
+## Events
+
+It behaves like a range input, so the two native events mean different things. `input` fires on every alteration — continuously through a drag, and once per keyboard step. `change` fires only when the value is committed: the end of a drag, or each keyboard step. A drag that ends where it started emits no `change` at all.
+
+Follow the value live with `input`, and react to a settled value with `change`:
+
+```js
+rule.addEventListener('input', () => preview(rule.value));
+rule.addEventListener('change', () => save(rule.value));
+```
+
+`craft-drag-start` and `craft-drag-end` bracket a pointer drag, for anything that should only be visible while the person is dragging — the image editor shows its alignment grid between the two.
+
+## Accessibility
+
+A drag-to-rotate ruler is a pointer-first control, which makes the keyboard path the one to check rather than assume.
+
+Whatever it adjusts should also be settable another way — a numeric field beside it, or a set of preset angles — so the interface does not depend on a gesture. Fine rotation by keyboard alone is slow at best.
+
+## Properties
+
+<ArgTypes of={SlideRuleStories} />
diff --git a/packages/craftcms-ui/src/components/slide-rule/slide-rule.stories.ts b/packages/craftcms-ui/src/components/slide-rule/slide-rule.stories.ts
index 8ac024dd600..918d312bb40 100644
--- a/packages/craftcms-ui/src/components/slide-rule/slide-rule.stories.ts
+++ b/packages/craftcms-ui/src/components/slide-rule/slide-rule.stories.ts
@@ -1,5 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 import type CraftSlideRule from './slide-rule.js';
+import {expect} from 'storybook/test';
+import {html} from 'lit';
 import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import './slide-rule.js';
 
@@ -7,7 +9,7 @@ const {events, args, argTypes, template} =
   getStorybookHelpers('craft-slide-rule');
 
 const meta: Meta<CraftSlideRule> = {
-  title: 'Controls/Slide Rule',
+  title: 'Form Controls/Slide Rule',
   component: 'craft-slide-rule',
   args,
   argTypes,
@@ -31,3 +33,40 @@ export const StartingAngle: Story = {
     value: 15,
   },
 };
+
+/**
+ * Give it a `name` and the angle posts with the form, like any other input.
+ *
+ * As with the slide picker, the assertions run in the browser because they
+ * exercise the user agent's own side of form association, which neither
+ * happy-dom nor the polyfill provides.
+ */
+export const InAForm: Story = {
+  render: () => html`
+    <form>
+      <craft-slide-rule name="angle" value="15"></craft-slide-rule>
+    </form>
+  `,
+  play: async ({canvasElement}) => {
+    const form = canvasElement.querySelector('form')!;
+    const rule = form.querySelector('craft-slide-rule')!;
+
+    await expect(rule.form).toBe(form);
+    await expect(new FormData(form).get('angle')).toBe('15');
+
+    rule.disabled = true;
+    await rule.updateComplete;
+    await expect(new FormData(form).get('angle')).toBeNull();
+
+    rule.disabled = false;
+    await rule.updateComplete;
+
+    rule.value = -30;
+    await rule.updateComplete;
+    await expect(new FormData(form).get('angle')).toBe('-30');
+
+    form.reset();
+    await rule.updateComplete;
+    await expect(rule.value).toBe(15);
+  },
+};
diff --git a/packages/craftcms-ui/src/components/slide-rule/slide-rule.test.ts b/packages/craftcms-ui/src/components/slide-rule/slide-rule.test.ts
index dae98b43d2d..384cf9d8528 100644
--- a/packages/craftcms-ui/src/components/slide-rule/slide-rule.test.ts
+++ b/packages/craftcms-ui/src/components/slide-rule/slide-rule.test.ts
@@ -58,10 +58,11 @@ describe('craft-slide-rule', () => {
     expect(selected).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
   });
 
-  it('moves the value with the keyboard and emits change', async () => {
+  it('moves the value with the keyboard, emitting input and change per step', async () => {
     const element = await createSlideRule({value: 0});
-    const handler = vi.fn();
-    element.addEventListener('change', handler as EventListener);
+    const order: string[] = [];
+    element.addEventListener('input', () => order.push('input'));
+    element.addEventListener('change', () => order.push('change'));
 
     pressKey(element, 'ArrowRight');
     await element.updateComplete;
@@ -79,10 +80,37 @@ describe('craft-slide-rule', () => {
     await element.updateComplete;
     expect(element.value).toBe(45);
 
-    expect(handler).toHaveBeenCalledTimes(4);
-    expect((handler.mock.calls.at(-1)![0] as CustomEvent).detail).toEqual({
-      value: 45,
-    });
+    // A keyboard step commits as it moves, the way a native range input does.
+    expect(order).toEqual(Array(4).fill(['input', 'change']).flat());
+  });
+
+  it('emits nothing when a key press cannot move the value', async () => {
+    const element = await createSlideRule({value: 45});
+    const handler = vi.fn();
+    element.addEventListener('input', handler as EventListener);
+    element.addEventListener('change', handler as EventListener);
+
+    pressKey(element, 'End'); // already at max
+    await element.updateComplete;
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('ignores the keyboard while disabled', async () => {
+    const element = await createSlideRule({value: 0});
+    element.disabled = true;
+    await element.updateComplete;
+
+    const handler = vi.fn();
+    element.addEventListener('change', handler as EventListener);
+
+    pressKey(element, 'ArrowRight');
+    await element.updateComplete;
+
+    expect(element.value).toBe(0);
+    expect(handler).not.toHaveBeenCalled();
+    expect(root(element).getAttribute('tabindex')).toBe('-1');
+    expect(root(element).getAttribute('aria-disabled')).toBe('true');
   });
 
   it('clamps to the slide range even when pushed past it', async () => {
@@ -105,3 +133,58 @@ describe('craft-slide-rule', () => {
     expect(r.getAttribute('aria-valuetext')).toContain('12');
   });
 });
+
+/**
+ * As with the slide picker, these run against `element-internals-polyfill`;
+ * the user-agent side of form association is covered in the browser, in
+ * `slide-rule.stories.ts`.
+ */
+describe('craft-slide-rule form association', () => {
+  async function createInForm(): Promise<{
+    form: HTMLFormElement;
+    element: CraftSlideRule;
+  }> {
+    const form = document.createElement('form');
+    const element = document.createElement('craft-slide-rule');
+    element.name = 'angle';
+    element.value = 12;
+    form.append(element);
+    document.body.append(form);
+    await element.updateComplete;
+
+    return {form, element};
+  }
+
+  it('posts its value under its name', async () => {
+    const {form, element} = await createInForm();
+
+    expect(new FormData(form).get('angle')).toBe('12');
+
+    pressKey(element, 'ArrowRight');
+    await element.updateComplete;
+
+    expect(new FormData(form).get('angle')).toBe('13');
+  });
+
+  it('posts nothing without a name', async () => {
+    const {form, element} = await createInForm();
+    element.name = '';
+    await element.updateComplete;
+
+    expect([...new FormData(form).keys()]).toEqual([]);
+  });
+
+  it('restores the value it was given back', async () => {
+    const {element} = await createInForm();
+
+    pressKey(element, 'PageUp');
+    await element.updateComplete;
+    expect(element.value).toBe(22);
+
+    // What the user agent hands back on `form.reset()`.
+    element._restoreFormValue('12');
+    await element.updateComplete;
+
+    expect(element.value).toBe(12);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/slide-rule/slide-rule.ts b/packages/craftcms-ui/src/components/slide-rule/slide-rule.ts
index 8e5718423a1..9d66f600961 100644
--- a/packages/craftcms-ui/src/components/slide-rule/slide-rule.ts
+++ b/packages/craftcms-ui/src/components/slide-rule/slide-rule.ts
@@ -1,6 +1,7 @@
 import {html, LitElement, type PropertyValues} from 'lit';
 import {property, query} from 'lit/decorators.js';
 import {classMap} from 'lit/directives/class-map.js';
+import {FormAssociated} from '@src/mixins/FormAssociated';
 import {t} from '@src/utilities/translate';
 import styles from './slide-rule.styles.js';
 
@@ -15,11 +16,21 @@ const SENSITIVITY = 3;
  *
  * @since 1.0
  *
- * @fires {CustomEvent<{value:number}>} start - A drag/interaction began.
- * @fires {CustomEvent<{value:number}>} change - The value changed.
- * @fires {CustomEvent<{value:number}>} end - A drag/interaction ended.
+ * @attr {string} name - Field name. The control posts under this, like any
+ * other input. Supplied by the `FormAssociated` mixin.
+ * @attr {boolean} disabled - Whether the control responds to input. A disabled
+ * control is left out of form submission. Supplied by the `FormAssociated`
+ * mixin.
+ *
+ * @fires input - Emitted on every alteration to the value — continuously
+ * through a drag, and once per keyboard step.
+ * @fires change - Emitted when an alteration is committed: the end of a drag,
+ * or each keyboard step. Not emitted when a gesture leaves the value where it
+ * started.
+ * @fires {CustomEvent<{value:number}>} craft-drag-start - A drag began.
+ * @fires {CustomEvent<{value:number}>} craft-drag-end - A drag ended.
  */
-export default class CraftSlideRule extends LitElement {
+export default class CraftSlideRule extends FormAssociated(LitElement) {
   static override styles = [styles];
 
   /** Minimum selectable value (the slide range floor). */
@@ -40,6 +51,19 @@ export default class CraftSlideRule extends LitElement {
   /** Accessible name for the slider. */
   @property() label = t('Rotate');
 
+  /** Whether the control responds to input. */
+  get #editable(): boolean {
+    return !this.disabled;
+  }
+
+  override _formValue(): string | null {
+    return this.name ? String(this.value) : null;
+  }
+
+  override _restoreFormValue(value: string | null): void {
+    this.value = Math.min(Math.max(Number(value ?? 0), this.min), this.max);
+  }
+
   @query('.slide-rule') private _root!: HTMLElement;
   @query('.graduations') private _graduations!: HTMLElement;
   @query('.graduations ul') private _list!: HTMLElement;
@@ -47,6 +71,8 @@ export default class CraftSlideRule extends LitElement {
 
   #dragging = false;
   #rotateIntent = false;
+  /** Value when the current drag began, so `change` only fires on a real move. */
+  #valueAtDragStart = 0;
   #startPositionX = 0;
   #startLeft = 0;
   #calculatedWidth = 0;
@@ -79,6 +105,9 @@ export default class CraftSlideRule extends LitElement {
   }
 
   override updated(changed: PropertyValues<this>): void {
+    // The mixin re-posts the form value from here, so this must chain.
+    super.updated(changed);
+
     if (
       changed.has('value') ||
       changed.has('min') ||
@@ -128,17 +157,25 @@ export default class CraftSlideRule extends LitElement {
     );
   }
 
-  #setValue(rawValue: number, emitChange = true): void {
+  /** Sets the value and emits `input`. Returns whether the value moved. */
+  #setValue(rawValue: number): boolean {
     const value = Math.min(Math.max(rawValue, this.min), this.max);
 
+    if (value === this.value) {
+      return false;
+    }
+
     this.value = value;
+    this.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
 
-    if (emitChange) {
-      this.#emit('change');
-    }
+    return true;
+  }
+
+  #emitChange(): void {
+    this.dispatchEvent(new Event('change', {bubbles: true, composed: true}));
   }
 
-  #emit(type: 'start' | 'change' | 'end'): void {
+  #emitDrag(type: 'craft-drag-start' | 'craft-drag-end'): void {
     this.dispatchEvent(
       new CustomEvent<{value: number}>(type, {
         detail: {value: this.value},
@@ -154,6 +191,7 @@ export default class CraftSlideRule extends LitElement {
     // Only rotate when the press lands inside the graduations, matching the
     // legacy `.graduations *` intent check.
     this.#rotateIntent =
+      this.#editable &&
       this._graduations.contains(event.target as Node) &&
       event.target !== this._graduations;
 
@@ -164,8 +202,9 @@ export default class CraftSlideRule extends LitElement {
     event.preventDefault();
     this.#startPositionX = event.clientX;
     this.#startLeft = this._list.offsetLeft;
+    this.#valueAtDragStart = this.value;
     this._root.setPointerCapture(event.pointerId);
-    this.#emit('start');
+    this.#emitDrag('craft-drag-start');
   }
 
   #handlePointerMove(event: PointerEvent) {
@@ -195,7 +234,11 @@ export default class CraftSlideRule extends LitElement {
       this.#setValueFromPointer(event);
     }
 
-    this.#emit('end');
+    if (this.value !== this.#valueAtDragStart) {
+      this.#emitChange();
+    }
+
+    this.#emitDrag('craft-drag-end');
     this._root.releasePointerCapture(event.pointerId);
     this.#startPositionX = 0;
     this.#rotateIntent = false;
@@ -216,33 +259,43 @@ export default class CraftSlideRule extends LitElement {
   }
 
   #handleKeyDown(event: KeyboardEvent) {
+    if (!this.#editable) {
+      return;
+    }
+
     const current = this.value;
+    let moved: boolean;
 
     switch (event.key) {
       case 'ArrowUp':
       case 'ArrowRight':
-        this.#setValue(current + 1);
+        moved = this.#setValue(current + 1);
         break;
       case 'ArrowDown':
       case 'ArrowLeft':
-        this.#setValue(current - 1);
+        moved = this.#setValue(current - 1);
         break;
       case 'PageUp':
-        this.#setValue(current + 10);
+        moved = this.#setValue(current + 10);
         break;
       case 'PageDown':
-        this.#setValue(current - 10);
+        moved = this.#setValue(current - 10);
         break;
       case 'Home':
-        this.#setValue(this.min);
+        moved = this.#setValue(this.min);
         break;
       case 'End':
-        this.#setValue(this.max);
+        moved = this.#setValue(this.max);
         break;
       default:
         return;
     }
 
+    // A keyboard step commits as it moves, the way a native range input does.
+    if (moved) {
+      this.#emitChange();
+    }
+
     event.preventDefault();
   }
 
@@ -258,12 +311,13 @@ export default class CraftSlideRule extends LitElement {
       <div
         class="slide-rule"
         role="slider"
-        tabindex="0"
+        tabindex=${this.#editable ? 0 : -1}
         aria-label=${this.label}
         aria-valuemin=${this.min}
         aria-valuemax=${this.max}
         aria-valuenow=${this.value}
         aria-valuetext=${this.#valueText(this.value)}
+        aria-disabled=${this.disabled ? 'true' : 'false'}
         @keydown=${this.#handleKeyDown}
         @pointerdown=${this.#handlePointerDown}
         @pointermove=${this.#handlePointerMove}
diff --git a/packages/craftcms-ui/src/components/spinner/Spinner.mdx b/packages/craftcms-ui/src/components/spinner/Spinner.mdx
new file mode 100644
index 00000000000..be37f586f53
--- /dev/null
+++ b/packages/craftcms-ui/src/components/spinner/Spinner.mdx
@@ -0,0 +1,48 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SpinnerStories from './spinner.stories';
+
+<Meta of={SpinnerStories} name="Docs" />
+
+# Spinner
+
+`<craft-spinner>` is an indeterminate loading indicator, for work whose progress cannot be measured.
+
+<Canvas of={SpinnerStories.Default} sourceState="shown" />
+
+When progress _can_ be measured, use [Progress](?path=/docs/components-progress--docs) or [Progress Bar](?path=/docs/components-progress-bar--docs) instead — a spinner that runs for thirty seconds tells a person nothing about whether to wait.
+
+## Showing and Hiding
+
+`visible` toggles the spinner, and `show()` / `hide()` do the same from script, each firing a matching event.
+
+Hiding keeps the spinner in the layout rather than removing it:
+
+<Canvas of={SpinnerStories.Hidden} sourceState="shown" />
+
+That is the point — content around it does not jump as work starts and stops:
+
+<Canvas of={SpinnerStories.HoldsItsSpace} sourceState="shown" />
+
+If you want the space back, remove the element rather than hiding it.
+
+## Sizing
+
+The spinner is sized in `em`, so it takes the font size of what contains it:
+
+<Canvas of={SpinnerStories.Sizes} sourceState="shown" />
+
+## Accessibility
+
+The spinner itself is presentational — an animated shape carries no meaning to a screen reader.
+
+**Slot text saying what is loading.** It is visually hidden and announced, which is the only thing making the wait perceivable to someone who cannot see the animation:
+
+```html
+<craft-spinner>Loading entries</craft-spinner>
+```
+
+A spinner with an empty slot is silent. That is occasionally right — inside a button that already says "Saving…" — but it is a decision to make rather than a default to accept.
+
+## Properties
+
+<ArgTypes of={SpinnerStories} />
diff --git a/packages/craftcms-ui/src/components/spinner/spinner.stories.ts b/packages/craftcms-ui/src/components/spinner/spinner.stories.ts
index cecfdd3cc38..99759dbaa07 100644
--- a/packages/craftcms-ui/src/components/spinner/spinner.stories.ts
+++ b/packages/craftcms-ui/src/components/spinner/spinner.stories.ts
@@ -1,53 +1,68 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './spinner.js';
+import '../button/button.js';
+import type CraftSpinner from './spinner.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftSpinner>('craft-spinner');
+
+type SpinnerArgs = CraftSpinner & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Spinner',
   component: 'craft-spinner',
-  argTypes: {
-    width: {},
-    size: {
-      control: {
-        type: 'text',
-      },
-      defaultValue: null,
-    },
-  },
-  render: function ({size, width, message}) {
-    let style = '';
-    if (size) {
-      style = `--size: ${size};`;
-    }
-
-    if (width) {
-      style += `--width: ${width};`;
-    }
-
-    return html`<craft-spinner style="${style}">${message}</craft-spinner>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, 'default-slot': 'Loading entries'},
+  argTypes,
+  parameters: {layout: 'centered'},
+  render: (args) => template(args),
+} satisfies Meta<SpinnerArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<SpinnerArgs>;
+
+/** The slotted text is announced but not shown. */
+export const Default: Story = {};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Basic: Story = {
-  args: {},
+/** `visible` hides the spinner without removing it from the layout. */
+export const Hidden: Story = {
+  args: {visible: false},
 };
 
-export const Size: Story = {
-  args: {
-    size: '100px',
-    width: '4px',
-  },
+/**
+ * Because a hidden spinner still occupies its space, content around it does
+ * not jump as work starts and stops.
+ */
+export const HoldsItsSpace: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; align-items: center; gap: 0.5rem">
+      Saving
+      <craft-spinner visible="${false}">Saving</craft-spinner>
+      — the spinner is hidden, but the gap it leaves is not.
+    </div>
+  `,
 };
 
-export const Message: Story = {
-  args: {
-    message: 'This is a message',
-  },
+/** Spinners inherit the surrounding font size. */
+export const Sizes: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; gap: 1.5rem; align-items: center">
+      <craft-spinner>Loading</craft-spinner>
+      <span style="font-size: 1.5rem"
+        ><craft-spinner>Loading</craft-spinner></span
+      >
+      <span style="font-size: 2.5rem"
+        ><craft-spinner>Loading</craft-spinner></span
+      >
+    </div>
+  `,
 };
diff --git a/packages/craftcms-ui/src/components/spinner/spinner.test.ts b/packages/craftcms-ui/src/components/spinner/spinner.test.ts
new file mode 100644
index 00000000000..8c79423d2b4
--- /dev/null
+++ b/packages/craftcms-ui/src/components/spinner/spinner.test.ts
@@ -0,0 +1,78 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './spinner.js';
+import type CraftSpinner from './spinner.js';
+
+async function createSpinner(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Loading'
+): Promise<CraftSpinner> {
+  const element = document.createElement('craft-spinner') as CraftSpinner;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function wrapper(element: CraftSpinner): HTMLElement {
+  return element.shadowRoot!.querySelector('.wrapper')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-spinner', () => {
+  it('is visible by default', async () => {
+    const element = await createSpinner();
+
+    expect(element.visible).toBe(true);
+    expect(wrapper(element).classList.contains('hidden')).toBe(false);
+  });
+
+  /** Hiding keeps it in the layout rather than collapsing the space. */
+  it('hides without leaving the layout', async () => {
+    const element = await createSpinner();
+
+    element.hide();
+    await element.updateComplete;
+
+    expect(element.visible).toBe(false);
+    expect(wrapper(element).classList.contains('hidden')).toBe(true);
+    expect(wrapper(element).isConnected).toBe(true);
+  });
+
+  it('shows again', async () => {
+    const element = await createSpinner({visible: 'false'});
+
+    element.show();
+    await element.updateComplete;
+
+    expect(element.visible).toBe(true);
+  });
+
+  it('fires show and hide', async () => {
+    const element = await createSpinner();
+    const seen: string[] = [];
+    element.addEventListener('craft-show', () => seen.push('show'));
+    element.addEventListener('craft-hide', () => seen.push('hide'));
+
+    element.hide();
+    element.show();
+
+    expect(seen).toEqual(['hide', 'show']);
+  });
+
+  /** The slotted text is the accessible name, and is visually hidden. */
+  it('keeps its slotted label for assistive technology', async () => {
+    const element = await createSpinner({}, 'Saving entry');
+
+    expect(
+      element.shadowRoot!.querySelector('.cp-visually-hidden')
+    ).toBeTruthy();
+    expect(element.textContent).toBe('Saving entry');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/spinner/spinner.ts b/packages/craftcms-ui/src/components/spinner/spinner.ts
index b24b627b17e..8e48aa075e8 100644
--- a/packages/craftcms-ui/src/components/spinner/spinner.ts
+++ b/packages/craftcms-ui/src/components/spinner/spinner.ts
@@ -6,25 +6,63 @@ import visuallyHiddenStyles from '@src/styles/visually-hidden.styles';
 
 import '../visually-hidden/visually-hidden';
 
+/**
+ * @summary An indeterminate loading indicator, for work whose progress cannot
+ * be measured. Use `craft-progress` or `craft-progress-bar` when it can.
+ *
+ * The spinner is presentational on its own. Slot text to say what is loading,
+ * which is announced but not shown.
+ *
+ * @slot - A description of what is loading, visually hidden.
+ *
+ * @fires craft-show - Emitted when the spinner is shown via `show()`.
+ * @fires craft-hide - Emitted when the spinner is hidden via `hide()`.
+ * @cssproperty [--size=24px] - The spinner's diameter. Shared with avatar,
+ * status, and indicator, so one declaration sizes a row of them together.
+ *
+ */
 export default class CraftSpinner extends LitElement {
   static override styles = [visuallyHiddenStyles, componentStyles];
 
+  /**
+   * Whether the spinner is shown. Hiding keeps it in the layout rather than
+   * removing it, so surrounding content does not jump as work starts and
+   * stops.
+   */
   @property({reflect: true, type: Boolean})
   visible: boolean = true;
 
   @query('.wrapper')
-  wrapper!: HTMLElement | null;
+  protected wrapper!: HTMLElement | null;
+
+  /**
+
+   * Shows the spinner and announces it, firing `show`.
+
+   */
 
   show() {
     this.visible = true;
-    this.dispatchEvent(new CustomEvent('show'));
+    this.dispatchEvent(new CustomEvent('craft-show'));
   }
 
+  /**
+
+   * Hides the spinner, firing `hide`. It keeps its place in the layout.
+
+   */
+
   hide() {
     this.visible = false;
-    this.dispatchEvent(new CustomEvent('hide'));
+    this.dispatchEvent(new CustomEvent('craft-hide'));
   }
 
+  /**
+
+   * Moves focus to the spinner, so a screen reader reaches the busy state.
+
+   */
+
   override focus() {
     this.wrapper?.focus();
   }
diff --git a/packages/craftcms-ui/src/components/status/Status.mdx b/packages/craftcms-ui/src/components/status/Status.mdx
new file mode 100644
index 00000000000..c8c10db58c2
--- /dev/null
+++ b/packages/craftcms-ui/src/components/status/Status.mdx
@@ -0,0 +1,48 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as StatusStories from './status.stories';
+
+<Meta of={StatusStories} name="Docs" />
+
+# Status
+
+`<craft-status>` is a coloured dot standing for an object's state.
+
+<Canvas of={StatusStories.Default} sourceState="shown" />
+
+It carries no text of its own and is meant to sit beside the thing it describes — an index row, a [Chip](?path=/docs/components-chip--docs), a page header — where the name is already present.
+
+<Canvas of={StatusStories.InContext} sourceState="shown" />
+
+## States
+
+`status` takes a fixed vocabulary, each with its own colour:
+
+<Canvas of={StatusStories.AllStatuses} sourceState="shown" />
+
+Leaving it unset renders the neutral dot:
+
+<Canvas of={StatusStories.NoStatus} sourceState="shown" />
+
+## Status, Indicator, or Badge?
+
+Three components draw a small coloured mark, and they are not interchangeable:
+
+- **Status** — a fixed set of object states (`live`, `pending`, `expired`, `disabled`, `enabled`). Reach for it when the meaning is one of those.
+- **[Indicator](?path=/docs/components-indicator--docs)** — any palette colour, and appearance options. Reach for it when the dot means something the status vocabulary does not cover.
+- **[Badge](?path=/docs/components-badge--docs)** — a dot _and_ a label in a pill. Reach for it when the state needs naming in place rather than in the row beside it.
+
+## Accessibility
+
+The dot is a coloured shape, so on its own it conveys nothing to a screen reader. It is exposed as `role="img"` with an accessible name, which is what makes the state perceivable.
+
+Without a `label`, the name is a translated "Status: live" derived from the state. Set `label` when that is not what a person needs to hear:
+
+<Canvas of={StatusStories.CustomLabel} sourceState="shown" />
+
+Where the state is already spelled out in adjacent text, the dot is decoration and repeating it is noise. A status with neither `status` nor `label` has no name and is not exposed as an image at all, which is the correct handling of a purely decorative dot.
+
+**Colour is the only visual signal here.** In a dense list, that puts the whole meaning on hue — so the surrounding row should carry the state in text too, rather than relying on the dot alone.
+
+## Properties
+
+<ArgTypes of={StatusStories} />
diff --git a/packages/craftcms-ui/src/components/status/status.stories.ts b/packages/craftcms-ui/src/components/status/status.stories.ts
index bff8b3a2eda..d176c1f80e2 100644
--- a/packages/craftcms-ui/src/components/status/status.stories.ts
+++ b/packages/craftcms-ui/src/components/status/status.stories.ts
@@ -1,29 +1,72 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './status.js';
+import type CraftStatus from './status.js';
 
-const statuses = ['live', 'pending', 'expired', 'disabled'];
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftStatus>('craft-status');
+
+type StatusArgs = CraftStatus & typeof args;
+
+const STATUSES = ['live', 'pending', 'expired', 'disabled', 'enabled'] as const;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Status',
   component: 'craft-status',
-  argTypes: {},
-  render: (args) => html`
-    <div class="flex gap-2">
-      ${statuses.map(
-        (status) => html` <craft-status status="${status}"></craft-status>`
+  args: {...args, status: 'live'},
+  argTypes,
+  parameters: {layout: 'centered'},
+  render: (args) => template(args),
+} satisfies Meta<StatusArgs>;
+
+export default meta;
+type Story = StoryObj<StatusArgs>;
+
+/** A dot standing for one state. */
+export const Default: Story = {};
+
+/** Each state renders in its own colour. */
+export const AllStatuses: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 0.5rem">
+      ${STATUSES.map(
+        (status) => html`
+          <span style="display: flex; align-items: center; gap: 0.5rem">
+            <craft-status status="${status}"></craft-status> ${status}
+          </span>
+        `
       )}
     </div>
   `,
-} satisfies Meta<any>;
+};
 
-export default meta;
-type Story = StoryObj<any>;
+/** With no status, the dot is neutral. */
+export const NoStatus: Story = {
+  args: {status: null},
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+/**
+ * `label` replaces the announced name. Without one, the status supplies a
+ * translated "Status: live".
+ */
+export const CustomLabel: Story = {
+  args: {status: 'pending', label: 'Awaiting review'},
+};
+
+/** Where it usually sits — beside the thing it describes. */
+export const InContext: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <span style="display: inline-flex; align-items: center; gap: 0.5rem">
+      <craft-status status="live"></craft-status> Homepage
+    </span>
+  `,
 };
diff --git a/packages/craftcms-ui/src/components/status/status.test.ts b/packages/craftcms-ui/src/components/status/status.test.ts
new file mode 100644
index 00000000000..886225e7861
--- /dev/null
+++ b/packages/craftcms-ui/src/components/status/status.test.ts
@@ -0,0 +1,71 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './status.js';
+import type CraftStatus from './status.js';
+
+async function createStatus(
+  attrs: Record<string, string> = {}
+): Promise<CraftStatus> {
+  const element = document.createElement('craft-status') as CraftStatus;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function dot(element: CraftStatus): HTMLElement {
+  return element.shadowRoot!.querySelector('.status')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-status', () => {
+  it('renders a dot', async () => {
+    const element = await createStatus();
+
+    expect(dot(element)).toBeTruthy();
+  });
+
+  it('carries a modifier class for each status', async () => {
+    for (const status of [
+      'live',
+      'pending',
+      'expired',
+      'disabled',
+      'enabled',
+    ]) {
+      const element = await createStatus({status});
+
+      expect(dot(element).classList.contains(`status--${status}`)).toBe(true);
+    }
+  });
+
+  /**
+   * A dot with nothing to say is decoration beside the label it sits next to.
+   * An unnamed `role="img"` would be announced as an image and tell a screen
+   * reader user nothing.
+   */
+  it('is not an image when it has no status and no label', async () => {
+    const element = await createStatus();
+
+    expect(dot(element).getAttribute('role')).toBeNull();
+    expect(dot(element).getAttribute('aria-label')).toBeNull();
+  });
+
+  it('announces the status when one is set', async () => {
+    const element = await createStatus({status: 'live'});
+
+    expect(dot(element).getAttribute('role')).toBe('img');
+    expect(dot(element).getAttribute('aria-label')).toBe('Status: live');
+  });
+
+  it('prefers an explicit label over the status name', async () => {
+    const element = await createStatus({status: 'live', label: 'Published'});
+
+    expect(dot(element).getAttribute('aria-label')).toBe('Published');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/status/status.ts b/packages/craftcms-ui/src/components/status/status.ts
index bf68d9380e2..a95890b163c 100644
--- a/packages/craftcms-ui/src/components/status/status.ts
+++ b/packages/craftcms-ui/src/components/status/status.ts
@@ -3,18 +3,21 @@ import {html, LitElement, nothing} from 'lit';
 import styles from './status.styles.js';
 import type {CSSResultGroup} from 'lit';
 import {classMap} from 'lit/directives/class-map.js';
+import {t} from '@src/utilities/translate';
 
 /**
- * @summary Short summary of the component's intended use.
+ * @summary A coloured dot standing for an object's state — an entry that is
+ * live, a user that is disabled, a draft that is pending.
  *
- * @event craft-event-name - Emitted as an example.
+ * The dot carries no text. It is meant to sit beside the thing it describes,
+ * in an index row or a chip, where the name is already present.
  *
- * @slot - The default slot.
- * @slot example - An example slot.
+ * Reach for `craft-indicator` instead when the dot means something the status
+ * vocabulary does not cover: indicator takes any palette colour, where this
+ * takes a fixed set of states.
+ * @cssproperty [--size=var(--c-size-icon-xs)] - The dot's diameter. Shared
+ * with avatar, spinner, and indicator.
  *
- * @csspart base - The component's base wrapper.
- *
- * @cssproperty --example - An example CSS custom property.
  */
 export default class CraftStatus extends LitElement {
   static override styles: CSSResultGroup = [styles];
@@ -22,7 +25,10 @@ export default class CraftStatus extends LitElement {
   /** Accessible label for the status. */
   @property() label: string | null = null;
 
-  /** The status of the indicator. */
+  /**
+   * The state the dot stands for. Each renders in its own colour; leaving it
+   * unset renders the neutral dot.
+   */
   @property() status:
     | 'live'
     | 'pending'
@@ -31,9 +37,9 @@ export default class CraftStatus extends LitElement {
     | 'enabled'
     | null = null;
 
-  getLabel() {
+  protected getLabel() {
     if (!this.label && this.status) {
-      return `Status: ${this.status}`;
+      return t('Status: {status}', {status: this.status});
     }
 
     return this.label;
@@ -50,8 +56,8 @@ export default class CraftStatus extends LitElement {
           'status--expired': this.status === 'expired',
           'status--disabled': this.status === 'disabled',
         })}"
-        role="img"
-        aria-label="${this.getLabel()}"
+        role="${this.getLabel() ? 'img' : nothing}"
+        aria-label="${this.getLabel() ?? nothing}"
       ></span>
     `;
   }
diff --git a/packages/craftcms-ui/src/components/switch-button/SwitchButton.mdx b/packages/craftcms-ui/src/components/switch-button/SwitchButton.mdx
new file mode 100644
index 00000000000..6066a08ecce
--- /dev/null
+++ b/packages/craftcms-ui/src/components/switch-button/SwitchButton.mdx
@@ -0,0 +1,21 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Form Controls/Choice Controls/Switch Button" />
+
+# Switch Button
+
+`<craft-switch-button>` is the track and thumb that [Switch](?path=/docs/form-controls-choice-controls-switch--docs) renders inside itself.
+
+It is documented here because it is a registered custom element you will see in the DOM — not because it is one to reach for. On its own it has no label, no hidden input, and nothing it posts.
+
+**Use [Switch](?path=/docs/form-controls-choice-controls-switch--docs) instead.** It supplies the label, the hidden input, the state labels, and the value handling, and drives this control to match.
+
+## What It Contributes
+
+The visual toggle, and the `aria-checked` state that goes with it — `true`, `false`, or `mixed`.
+
+The mixed state here is display-only: transitions between the three states are managed by the switch, which owns the rule that indeterminate is cleared as soon as the switch is turned on.
+
+## Properties
+
+<ArgTypes of="craft-switch-button" />
diff --git a/packages/craftcms-ui/src/components/switch-button/switch-button.test.ts b/packages/craftcms-ui/src/components/switch-button/switch-button.test.ts
new file mode 100644
index 00000000000..747a935c545
--- /dev/null
+++ b/packages/craftcms-ui/src/components/switch-button/switch-button.test.ts
@@ -0,0 +1,67 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './switch-button.js';
+import type CraftSwitchButton from './switch-button.js';
+
+async function createSwitchButton(
+  attrs: Record<string, string> = {}
+): Promise<CraftSwitchButton> {
+  const element = document.createElement(
+    'craft-switch-button'
+  ) as CraftSwitchButton;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-switch-button', () => {
+  /**
+   * The button is the toggle a `craft-switch` renders, and it reports its own
+   * state — the three values `aria-checked` can take are the whole contract.
+   */
+  it('reports the off state', async () => {
+    const element = await createSwitchButton();
+
+    expect(element.getAttribute('aria-checked')).toBe('false');
+  });
+
+  it('reports the on state', async () => {
+    const element = await createSwitchButton();
+
+    element.checked = true;
+    await element.updateComplete;
+
+    expect(element.getAttribute('aria-checked')).toBe('true');
+  });
+
+  /** Mixed is display-only here; `craft-switch` owns the transitions. */
+  it('reports the mixed state', async () => {
+    const element = await createSwitchButton({indeterminate: ''});
+
+    expect(element.getAttribute('aria-checked')).toBe('mixed');
+  });
+
+  /** Checked wins, so a switch cannot claim to be both on and mixed. */
+  it('prefers checked over mixed', async () => {
+    const element = await createSwitchButton({indeterminate: ''});
+
+    element.checked = true;
+    await element.updateComplete;
+
+    expect(element.getAttribute('aria-checked')).toBe('true');
+  });
+
+  it('reflects indeterminate so the stylesheet can centre the thumb', async () => {
+    const element = await createSwitchButton({indeterminate: ''});
+
+    expect(element.indeterminate).toBe(true);
+    expect(element.hasAttribute('indeterminate')).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/switch-button/switch-button.ts b/packages/craftcms-ui/src/components/switch-button/switch-button.ts
index 02a32dcd948..4542686b42c 100644
--- a/packages/craftcms-ui/src/components/switch-button/switch-button.ts
+++ b/packages/craftcms-ui/src/components/switch-button/switch-button.ts
@@ -2,6 +2,13 @@ import {LionSwitchButton} from '@lion/ui/switch.js';
 import {css, type PropertyValues} from 'lit';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary The toggle itself — the track and thumb a `craft-switch` renders.
+ *
+ * It is the switch's internal control rather than something to use directly:
+ * on its own it has no label, no hidden input, and nothing posts. Reach for
+ * `craft-switch`, which supplies all three and drives this.
+ */
 export default class CraftSwitchButton extends LionSwitchButton {
   /**
    * Display-only mixed state (thumb centered, `aria-checked="mixed"`).
diff --git a/packages/craftcms-ui/src/components/switch/Switch.mdx b/packages/craftcms-ui/src/components/switch/Switch.mdx
new file mode 100644
index 00000000000..bdb7c6438e3
--- /dev/null
+++ b/packages/craftcms-ui/src/components/switch/Switch.mdx
@@ -0,0 +1,47 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as SwitchStories from './switch.stories';
+
+<Meta of={SwitchStories} name="Docs" />
+
+# Switch
+
+`<craft-switch>` toggles a setting that takes effect immediately.
+
+<Canvas of={SwitchStories.Default} sourceState="shown" />
+
+It is the modern replacement for the legacy lightswitch, and posts through a hidden input so it behaves like any other form field.
+
+## Switch or Checkbox?
+
+The two look different because they mean different things:
+
+- **Switch** — the change happens now. Turning it on _is_ the action.
+- **[Checkbox](?path=/docs/form-controls-choice-controls-checkbox--docs)** — the value is part of a form, and nothing happens until it is submitted.
+
+A switch that only takes effect after a Save button is a switch that lied about what it does.
+
+## State Labels
+
+`on-label` and `off-label` render text either side of the control describing the two states, matching the legacy lightswitch. Clicking either label sets that state.
+
+They are announced as a single description rather than as two loose strings — the visible labels are hidden from assistive technology and replaced with one linked description, so a screen reader hears what the switch does rather than the words "on" and "off" floating beside it.
+
+## The Mixed State
+
+`indeterminate` renders the third state, again matching the legacy lightswitch, and posts `indeterminate-value` rather than the on value.
+
+It is only meaningful while the switch is off, and is cleared as soon as the switch is turned on — a switch cannot be both on and undecided.
+
+## Values
+
+`value` is what the hidden input posts when the switch is on, defaulting to `1`. It is named `checkedValue` on the element itself, because Lion already defines a `value` accessor that proxies the input node.
+
+## Accessibility
+
+The control is exposed as a switch with its checked state, and the mixed state as `aria-checked="mixed"`.
+
+Label it with the thing being switched, not with the states. "Enable comments" tells a person what the control governs; "On/Off" tells them only what a switch already looks like.
+
+## Properties
+
+<ArgTypes of={SwitchStories} />
diff --git a/packages/craftcms-ui/src/components/switch/switch.stories.ts b/packages/craftcms-ui/src/components/switch/switch.stories.ts
index 325e42772ac..8acdff91100 100644
--- a/packages/craftcms-ui/src/components/switch/switch.stories.ts
+++ b/packages/craftcms-ui/src/components/switch/switch.stories.ts
@@ -1,114 +1,77 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
-import {ifDefined} from 'lit/directives/if-defined.js';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './switch.js';
+import type CraftSwitch from './switch.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `switch.ts` surfaces it here without touching this file.
+ *
+ * Lion's own `label` and `help-text` are slots here, so they are set through
+ * the `label-slot` and `help-text-slot` args rather than as attributes.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftSwitch>('craft-switch');
+
+type SwitchArgs = CraftSwitch & typeof args;
 
 const meta = {
-  title: 'Controls/Switch',
+  title: 'Form Controls/Choice Controls/Switch',
   component: 'craft-switch',
-  args: {
-    label: 'Enable feature',
-    helpText: '',
-    size: 'medium',
-    disabled: false,
-    checked: false,
-    labelSrOnly: false,
-    onLabel: undefined,
-    offLabel: undefined,
-  },
-  argTypes: {
-    size: {
-      control: 'select',
-      options: ['small', 'medium'],
-    },
-    onLabel: {
-      control: 'text',
-    },
-    offLabel: {
-      control: 'text',
-    },
-  },
-  render: ({
-    label,
-    helpText,
-    size,
-    disabled,
-    checked,
-    labelSrOnly,
-    onLabel,
-    offLabel,
-  }) => {
-    return html`<craft-switch
-      label=${label}
-      help-text=${helpText}
-      size=${size}
-      ?disabled=${disabled}
-      ?checked=${checked}
-      ?label-sr-only=${labelSrOnly}
-      on-label=${ifDefined(onLabel || undefined)}
-      off-label=${ifDefined(offLabel || undefined)}
-    ></craft-switch>`;
-  },
-} satisfies Meta<any>;
+  args: {...args, size: 'medium', 'label-slot': 'Enable feature'},
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<SwitchArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<SwitchArgs>;
 
-export const Default: Story = {
-  args: {},
-};
+/** Off by default; clicking or pressing Space toggles it. */
+export const Default: Story = {};
 
 export const Checked: Story = {
-  args: {
-    checked: true,
-  },
+  args: {checked: true},
 };
 
 export const WithHelpText: Story = {
-  args: {
-    helpText: 'This toggles the feature on or off',
-  },
+  args: {'help-text-slot': 'This toggles the feature on or off.'},
 };
 
+/** The two sizes, side by side. */
 export const Sizes: Story = {
+  parameters: {controls: {disable: true}},
   render: () => html`
-    <div style="display: flex; align-items: center; gap: 24px;">
-      <craft-switch label="Small" size="small"></craft-switch>
-      <craft-switch label="Medium" size="medium"></craft-switch>
+    <div style="display: flex; align-items: center; gap: 24px">
+      <craft-switch size="small"
+        ><label slot="label">Small</label></craft-switch
+      >
+      <craft-switch size="medium"
+        ><label slot="label">Medium</label></craft-switch
+      >
     </div>
   `,
 };
 
 export const Disabled: Story = {
-  args: {
-    disabled: true,
-  },
+  args: {disabled: true},
 };
 
 export const DisabledChecked: Story = {
-  args: {
-    disabled: true,
-    checked: true,
-  },
-};
-
-export const LabelSrOnly: Story = {
-  args: {
-    labelSrOnly: true,
-  },
+  args: {disabled: true, checked: true},
 };
 
+/** `on-label` and `off-label` put the state in words beside the control. */
 export const MultipleLabels: Story = {
-  args: {
-    onLabel: 'On',
-    offLabel: 'Off',
-  },
+  args: {'on-label': 'On', 'off-label': 'Off'},
 };
 
+/** The third state, for a switch standing in for a mixed group. */
 export const Indeterminate: Story = {
-  render: () => html`
-    <craft-switch label="Mixed state" indeterminate></craft-switch>
-  `,
+  args: {indeterminate: true, 'label-slot': 'Mixed state'},
 };
diff --git a/packages/craftcms-ui/src/components/switch/switch.ts b/packages/craftcms-ui/src/components/switch/switch.ts
index 039e38f4db3..b56c570bbe3 100644
--- a/packages/craftcms-ui/src/components/switch/switch.ts
+++ b/packages/craftcms-ui/src/components/switch/switch.ts
@@ -20,11 +20,27 @@ const SYNTHETIC_CHANGE = Symbol.for('craft-switch-synthetic-change');
 
 type SyntheticChangeEvent = Event & {[SYNTHETIC_CHANGE]?: boolean};
 
+/**
+ * @summary A switch, for a setting that takes effect as soon as it is
+ * toggled — the modern replacement for the legacy lightswitch.
+ *
+ * Use a switch when the change is immediate and needs no confirmation, and a
+ * `craft-checkbox` when the value is part of a form that has to be submitted.
+ * The control tells a person which they are dealing with.
+ *
+ * A hidden input carries the value, so a switch posts like any other field.
+ *
+ * @slot label - The switch's label, as an alternative to the `label`
+ *   attribute.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages.
+ */
 export default class CraftSwitch extends LionSwitch {
   static override get styles() {
     return [...super.styles, baseFieldStyles, styles];
   }
 
+  /** Size of the control. */
   @property({type: String, reflect: true}) size: 'small' | 'medium' = 'medium';
 
   /**
@@ -70,6 +86,10 @@ export default class CraftSwitch extends LionSwitch {
   // backing the `muteEvent` argument of turnOn()/turnOff()/turnIndeterminate().
   #suppressNativeChange = false;
 
+  /**
+   * Adds the switch's own input to Lion's slot map, so the component owns the
+   * native control rather than expecting one to be slotted in.
+   */
   override get slots() {
     return {
       ...super.slots,
@@ -103,6 +123,9 @@ export default class CraftSwitch extends LionSwitch {
     };
   }
 
+  /**
+   * Registers the elements the switch renders into its own shadow root.
+   */
   static override get scopedElements() {
     return {
       ...super.scopedElements,
@@ -296,14 +319,26 @@ export default class CraftSwitch extends LionSwitch {
     return this._postedValue;
   }
 
+  /**
+   * Turns the switch on. Pass `true` to suppress the `change` event, mirroring
+   * the legacy `Craft.LightSwitch` API that code migrating off
+   * `$el.data('lightswitch')` still calls.
+   */
   turnOn(muteEvent = false): void {
     this.#applyState(() => this._setCheckedState(true), muteEvent);
   }
 
+  /**
+   * Turns the switch off. Pass `true` to suppress the `change` event.
+   */
   turnOff(muteEvent = false): void {
     this.#applyState(() => this._setCheckedState(false), muteEvent);
   }
 
+  /**
+   * Puts the switch in the indeterminate state — neither on nor off. Pass
+   * `true` to suppress the `change` event.
+   */
   turnIndeterminate(muteEvent = false): void {
     this.#applyState(() => {
       if (this.indeterminate && !this.checked) {
diff --git a/packages/craftcms-ui/src/components/tab/Tab.mdx b/packages/craftcms-ui/src/components/tab/Tab.mdx
new file mode 100644
index 00000000000..03b672f5556
--- /dev/null
+++ b/packages/craftcms-ui/src/components/tab/Tab.mdx
@@ -0,0 +1,40 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Components/Tab" />
+
+# Tab
+
+`<craft-tab>` is a single trigger within a [Tabs](?path=/docs/components-tabs--docs) strip.
+
+There are no stories here because a tab outside a strip controls nothing. See the [Tabs](?path=/docs/components-tabs--docs) page for working examples.
+
+```html
+<craft-tabs>
+  <craft-tab slot="tab">Content</craft-tab>
+  <div slot="panel">…</div>
+</craft-tabs>
+```
+
+## Deliberately Thin
+
+The tab owns almost nothing. [Tabs](?path=/docs/components-tabs--docs), via Lion, assigns it an `id`, `role="tab"`, `aria-controls`, `aria-selected`, and `tabindex`, and toggles `selected` as the selection moves.
+
+The only state the tab owns is `disabled` — and even that is honoured by the strip, which skips disabled tabs during arrow-key navigation.
+
+This is why `selected` is not something to set yourself: the strip will overwrite it. Set `selectedIndex` on the strip instead.
+
+## External Panels
+
+`controls` names a panel elsewhere in the document by id, for strips whose panels cannot be slotted alongside their tabs.
+
+That is the escape hatch for a server-rendered field layout, where the tab bar sits in the page header and the sections sit inside a pane. Without it, tabs and panels have to be siblings.
+
+## Styling
+
+The tab is padded in `em`, so it scales with whatever font size it inherits — which is how the strip's `size` resizes every tab without touching any of them.
+
+The selected indicator's geometry comes from custom properties the strip sets according to its `placement`. Override them to reposition the indicator; see the API table for the full set.
+
+## Properties
+
+<ArgTypes of="craft-tab" />
diff --git a/packages/craftcms-ui/src/components/tab/tab.test.ts b/packages/craftcms-ui/src/components/tab/tab.test.ts
new file mode 100644
index 00000000000..1ec9ac1ef87
--- /dev/null
+++ b/packages/craftcms-ui/src/components/tab/tab.test.ts
@@ -0,0 +1,62 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './tab.js';
+import type CraftTab from './tab.js';
+
+async function createTab(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Content'
+): Promise<CraftTab> {
+  const element = document.createElement('craft-tab') as CraftTab;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-tab', () => {
+  it('renders its label from the default slot', async () => {
+    const element = await createTab();
+
+    expect(element.shadowRoot!.querySelector('slot')).toBeTruthy();
+    expect(element.textContent).toBe('Content');
+  });
+
+  /**
+   * The strip reads these off the host, and the stylesheet keys off them, so
+   * all three have to reflect rather than stay properties.
+   */
+  it('reflects disabled', async () => {
+    const element = await createTab({disabled: ''});
+
+    expect(element.disabled).toBe(true);
+    expect(element.hasAttribute('disabled')).toBe(true);
+  });
+
+  it('reflects the panel it controls', async () => {
+    const element = await createTab({controls: 'panel-seo'});
+
+    expect(element.controls).toBe('panel-seo');
+    expect(element.getAttribute('controls')).toBe('panel-seo');
+  });
+
+  it('has no panel to control by default', async () => {
+    expect((await createTab()).controls).toBeNull();
+  });
+
+  it('follows a controls value set as a property', async () => {
+    const element = await createTab();
+
+    element.controls = 'panel-content';
+    await element.updateComplete;
+
+    expect(element.getAttribute('controls')).toBe('panel-content');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/tabs/Tabs.mdx b/packages/craftcms-ui/src/components/tabs/Tabs.mdx
new file mode 100644
index 00000000000..6dbec7a0791
--- /dev/null
+++ b/packages/craftcms-ui/src/components/tabs/Tabs.mdx
@@ -0,0 +1,84 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as TabsStories from './tabs.stories';
+
+<Meta of={TabsStories} name="Docs" />
+
+# Tabs
+
+`<craft-tabs>` is a strip of triggers over a set of panels, one visible at a time.
+
+<Canvas of={TabsStories.Default} sourceState="shown" />
+
+Use tabs for alternative views of the same subject — an entry's content, its settings, its metadata. Not for steps in a sequence, which is a wizard, and not for content a person needs to compare, which they cannot do when only one panel is visible.
+
+## Pairing
+
+Tabs and panels are slotted as **siblings**, paired by document order: the first `slot="tab"` owns the first `slot="panel"`.
+
+```html
+<craft-tabs>
+  <craft-tab slot="tab">Content</craft-tab>
+  <div slot="panel">…</div>
+  <craft-tab slot="tab">Settings</craft-tab>
+  <div slot="panel">…</div>
+</craft-tabs>
+```
+
+That looks unusual next to a nested API, and it is deliberate: because a panel is not wrapped in anything this component defines, it can be a `<div>`, a [Pane](?path=/docs/components-pane--docs), or a form section, with no wrapper in the way.
+
+A mismatched count logs a warning and leaves the extras inert.
+
+## Selection
+
+Selection is a **property**, not slotted state. Read or set `selectedIndex` (`selected-index`):
+
+<Canvas of={TabsStories.SelectedIndex} sourceState="shown" />
+
+Do not toggle `selected` on a tab — Lion owns that attribute and will overwrite it.
+
+## Layout
+
+<Canvas of={TabsStories.Placements} sourceState="shown" />
+
+<Canvas of={TabsStories.Sizes} sourceState="shown" />
+
+`size` works by font size, and the tabs are padded in `em`, so the whole strip scales without the tabs being touched individually.
+
+<Canvas of={TabsStories.RightToLeft} sourceState="shown" />
+
+## Overflow
+
+A strip too narrow for its tabs collapses the excess into a menu rather than wrapping or scrolling silently:
+
+<Canvas of={TabsStories.Overflow} sourceState="shown" />
+
+<Canvas of={TabsStories.NoOverflow} sourceState="shown" />
+
+## External Panels
+
+Some strips cannot slot their panels — a server-rendered field layout puts the tab bar in the page header and the sections inside a pane, so the two halves live in different parts of the document.
+
+<Canvas of={TabsStories.ExternalPanels} sourceState="shown" />
+
+For that case, a [Tab](?path=/docs/components-tab--docs) names its panel by id with `controls`, and the strip wires the two together across the document instead of by position.
+
+## States
+
+<Canvas of={TabsStories.Disabled} sourceState="shown" />
+
+Disabled tabs are skipped by arrow-key navigation, rather than being focusable and inert.
+
+<Canvas of={TabsStories.IconToolbar} sourceState="shown" />
+
+## Accessibility
+
+Lion supplies the whole tab contract: the `role`, `aria-controls`, and `aria-labelledby` wiring, the roving tabindex, and arrow/Home/End navigation.
+
+Two things stay with you:
+
+- **Keep labels short.** They sit in a strip, and a long label is what pushes a tab into the overflow menu.
+- **Do not use tabs to hide required form fields.** A validation error in a panel nobody has opened is an error nobody can find.
+
+## Properties
+
+<ArgTypes of={TabsStories} />
diff --git a/packages/craftcms-ui/src/components/tabs/tabs.stories.ts b/packages/craftcms-ui/src/components/tabs/tabs.stories.ts
index f5ac37729ac..2287ec51c86 100644
--- a/packages/craftcms-ui/src/components/tabs/tabs.stories.ts
+++ b/packages/craftcms-ui/src/components/tabs/tabs.stories.ts
@@ -1,5 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
-import {expect} from 'storybook/test';
+
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+import {expect, waitFor} from 'storybook/test';
 
 import {html} from 'lit';
 
@@ -7,39 +9,38 @@ import {sizes} from '@src/constants/size';
 
 import '../tab/tab.js';
 import './tabs.js';
+import type CraftTabs from './tabs.js';
 import {tabsPlacements} from './tabs.js';
 
 import '../icon/icon.js';
 
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `tabs.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftTabs>('craft-tabs');
+
+type CraftTabsArgs = CraftTabs & typeof args;
+
 const meta = {
   title: 'Components/Tabs',
   component: 'craft-tabs',
+  // `selected-index` is Lion's, so it is not in the manifest and is declared
+  // alongside the generated set.
   argTypes: {
-    placement: {
-      control: {type: 'inline-radio'},
-      options: tabsPlacements,
-      description: 'Where the strip sits relative to the panels.',
-    },
-    size: {
-      control: {type: 'inline-radio'},
-      options: sizes,
-      description: 'How large the strip is.',
-    },
+    ...argTypes,
     selectedIndex: {
       name: 'selected-index',
       control: {type: 'number'},
       description: 'Index of the selected tab. -1 selects nothing.',
     },
-    collapsible: {
-      control: {type: 'boolean'},
-      description: 'Whether clicking the selected tab deselects it.',
-    },
   },
   args: {
+    ...args,
     placement: 'block-start',
     size: 'medium',
     selectedIndex: 0,
-    collapsible: false,
   },
   render: (args) => html`
     <craft-tabs
@@ -62,10 +63,10 @@ const meta = {
       </div>
     </craft-tabs>
   `,
-} satisfies Meta<any>;
+} satisfies Meta<CraftTabsArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftTabsArgs>;
 
 /*
  * These play functions are the real test bed for the Lion-driven behavior:
@@ -347,13 +348,26 @@ export const ExternalPanels: Story = {
   },
 };
 
-/** Waits out the animation frames the overflow measurement schedules. */
+/**
+ * Waits out the animation frames the overflow measurement schedules.
+ *
+ * A fixed number of frames is not enough on its own: `requestAnimationFrame`
+ * is starved when several browser tests run at once, so the measurement had
+ * not always finished by the time the assertions ran. Pair this with
+ * `settleUntil()` wherever the result of a measurement is being read.
+ */
 async function settle() {
   for (let frame = 0; frame < 3; frame++) {
     await new Promise((resolve) => requestAnimationFrame(resolve));
   }
 }
 
+/** Settles, then waits for the measurement to actually land. */
+async function settleUntil(condition: () => boolean) {
+  await settle();
+  await waitFor(() => expect(condition()).toBe(true));
+}
+
 const OVERFLOW_LABELS = [
   'Content',
   'Metadata',
@@ -369,6 +383,18 @@ const OVERFLOW_LABELS = [
  * Storybook viewport to watch tabs move in and out of the menu.
  */
 export const Overflow: Story = {
+  parameters: {
+    a11y: {
+      config: {
+        // This story opens the overflow menu and leaves it open, so the scan
+        // reaches Lion's overlay wrapper — a `<dialog role="none">` it creates
+        // to position the content without adding a second dialog around it.
+        // The role is deliberate on Lion's side and the element is not ours to
+        // change; the menu inside it carries the real semantics.
+        rules: [{id: 'aria-allowed-role', enabled: false}],
+      },
+    },
+  },
   render: () => html`
     <div style="max-inline-size: 26rem; resize: horizontal; overflow: auto;">
       <craft-tabs>
@@ -390,8 +416,9 @@ export const Overflow: Story = {
 
     const collapsed = () => tabs.filter((tab) => tab.hasAttribute('hidden'));
 
-    // The strip measures off a rAF, so settle before reading it.
-    await settle();
+    // The strip measures off a rAF, so wait for the measurement to land
+    // rather than for a fixed number of frames.
+    await settleUntil(() => collapsed().length > 0);
 
     // Some tabs don't fit, so the menu is showing and holds exactly them.
     await expect(collapsed().length).toBeGreaterThan(0);
@@ -408,7 +435,9 @@ export const Overflow: Story = {
     const label = target.textContent!.trim();
 
     await userEvent.click(menu.querySelector('[slot="invoker"]')!);
-    await settle();
+    await settleUntil(
+      () => menu.querySelectorAll('craft-action-item').length > 0
+    );
 
     // The items are the menu's own light DOM, which lives inside the strip's
     // shadow root — a document-level query wouldn't reach them.
@@ -417,7 +446,7 @@ export const Overflow: Story = {
     );
     await expect(item).toBeTruthy();
     await userEvent.click(item as HTMLElement);
-    await settle();
+    await settleUntil(() => !target.hasAttribute('hidden'));
 
     // It swapped into the strip, selected, and something else took its place
     // in the menu.
diff --git a/packages/craftcms-ui/src/components/tabs/tabs.test.ts b/packages/craftcms-ui/src/components/tabs/tabs.test.ts
index 5de542f8856..0ecc0aee1f4 100644
--- a/packages/craftcms-ui/src/components/tabs/tabs.test.ts
+++ b/packages/craftcms-ui/src/components/tabs/tabs.test.ts
@@ -403,10 +403,23 @@ describe('external-panel mode', () => {
     ]);
   });
 
-  it('switches panels on click and fires selected-changed', async () => {
+  it('stays quiet on the initial render', async () => {
+    let fired = 0;
+    const element = document.createElement('craft-tabs');
+    element.addEventListener('craft-tab-show', () => {
+      fired++;
+    });
+    document.body.append(element);
+    await element.updateComplete;
+
+    // Selecting the first tab on load is not a change anyone asked for.
+    expect(fired).toBe(0);
+  });
+
+  it('switches panels on click and fires craft-tab-show', async () => {
     const {element, tabs, sections} = await createExternalTabs();
     let fired = 0;
-    element.addEventListener('selected-changed', () => {
+    element.addEventListener('craft-tab-show', () => {
       fired++;
     });
 
@@ -628,7 +641,7 @@ describe('collapsible', () => {
     });
 
     let reported: number | undefined;
-    element.addEventListener('selected-changed', (event) => {
+    element.addEventListener('craft-tab-show', (event) => {
       reported = (event.target as CraftTabs).selectedIndex;
     });
 
@@ -737,7 +750,7 @@ describe('collapsible', () => {
   it('leaves a strip that isn’t collapsible alone', async () => {
     const {element, tabs, sections} = await createExternalTabs();
     let fired = 0;
-    element.addEventListener('selected-changed', () => {
+    element.addEventListener('craft-tab-show', () => {
       fired++;
     });
 
diff --git a/packages/craftcms-ui/src/components/tabs/tabs.ts b/packages/craftcms-ui/src/components/tabs/tabs.ts
index 5d03f15670f..6df35eecbf3 100644
--- a/packages/craftcms-ui/src/components/tabs/tabs.ts
+++ b/packages/craftcms-ui/src/components/tabs/tabs.ts
@@ -113,7 +113,7 @@ const FIT_TOLERANCE = 1;
  * panel count, and it is fixed at first render — a strip is all-`controls` or
  * all-slotted, never a mix. Lion's own pairing is bypassed entirely here (it
  * indexes into a panel list that doesn't exist), so this component owns the
- * keyboard navigation in this mode; `selectedIndex` and `selected-changed`
+ * keyboard navigation in this mode; `selectedIndex` and `craft-tab-show`
  * behave identically either way.
  *
  * Replacing the external panels' markup (re-rendering the fragment they live
@@ -152,7 +152,7 @@ const FIT_TOLERANCE = 1;
  * @slot panel - The panels, one per tab, in the same order. Omitted entirely
  *   in external-panel mode.
  *
- * @event selected-changed - Fired when the selected tab changes, by click or
+ * @event craft-tab-show - Fired when the selected tab changes, by click or
  *   keyboard, including when a collapsible strip closes. Read `selectedIndex`
  *   off the target for the new index — `-1` when nothing is selected. Note it
  *   does not bubble, so listen on the element itself.
@@ -160,7 +160,7 @@ const FIT_TOLERANCE = 1;
  * @attr collapsed - Present while nothing is selected and the panel region is
  *   taking no space. Reflected and read-only — set `selectedIndex` (or let a
  *   `collapsible` strip be toggled) to change it. Exists so a surrounding
- *   layout can respond in CSS alone, without listening for `selected-changed`:
+ *   layout can respond in CSS alone, without listening for `craft-tab-show`:
  *
  *       .body:has(craft-tabs[collapsed]) { grid-template-columns: 1fr auto; }
  *
@@ -360,6 +360,14 @@ export default class CraftTabs extends LionTabs {
       } else {
         this.#syncSlotted();
       }
+
+      // Lion announces the selection as `selected-changed`. That is its
+      // protocol, not this component's API, so the public event is emitted
+      // here under our own name. The guard keeps the initial render quiet:
+      // there is no previous index to have changed from.
+      if (changedProperties.get('selectedIndex') !== undefined) {
+        this.dispatchEvent(new CustomEvent('craft-tab-show'));
+      }
     }
 
     if (
@@ -388,7 +396,7 @@ export default class CraftTabs extends LionTabs {
    *
    * The click it claims is stopped where it is, so a listener bound to the
    * host (or above it) won't see the one that closes the strip. Listen for
-   * `selected-changed` instead, which fires either way.
+   * `craft-tab-show` instead, which fires either way.
    */
   #handleClick = (event: Event) => {
     if (!this.collapsible || this.#collapsed) {
@@ -891,10 +899,10 @@ export default class CraftTabs extends LionTabs {
               size="small"
             >
               <!--
-                The name has to come from the icon: craft-button's
-                \`accessible-name\` only records the name it computed, it doesn't
-                put one in the DOM, so an icon-only button with nothing else to
-                read is nameless.
+                The name has to come from the icon: craft-button does not
+                name itself, so an icon-only button with nothing else to read
+                is nameless. A label on the icon (or aria-label on the host)
+                is what supplies one.
               -->
               <craft-icon
                 name="ellipsis"
diff --git a/packages/craftcms-ui/src/components/text-expander/TextExpander.mdx b/packages/craftcms-ui/src/components/text-expander/TextExpander.mdx
new file mode 100644
index 00000000000..46e15a09da3
--- /dev/null
+++ b/packages/craftcms-ui/src/components/text-expander/TextExpander.mdx
@@ -0,0 +1,41 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as TextExpanderStories from './text-expander.stories';
+
+<Meta of={TextExpanderStories} name="Docs" />
+
+# Text Expander
+
+`<craft-text-expander>` offers suggestions as a person types a trigger character.
+
+<Canvas of={TextExpanderStories.TextInput} sourceState="shown" />
+
+It wraps an input or textarea and watches for triggers — `@` for a user, `#` for an entry — then offers matches inline, without the person leaving the field.
+
+## Multiple Triggers
+
+<Canvas
+  of={TextExpanderStories.TextareaWithMultipleTriggers}
+  sourceState="shown"
+/>
+
+Each trigger can have its own source, so one field can reference several kinds of thing.
+
+<Canvas of={TextExpanderStories.MarkdownInput} sourceState="shown" />
+
+## Rich Suggestions
+
+<Canvas of={TextExpanderStories.RichOptions} sourceState="shown" />
+
+Suggestions can carry markup — an avatar, a status, a hint — which is what makes two similarly named entries distinguishable at a glance.
+
+## Accessibility
+
+This is a combobox pattern layered onto a free-text field, and the announcement is the part that carries it.
+
+The suggestion list is wired to the input, so arrowing through options announces each one, and the field reports how many matched. That is what makes the feature usable without seeing the list appear.
+
+Because suggestions arrive as a person types, keep the option text short and put the distinguishing part first. A list where every entry starts with the same words is a list nobody can navigate by ear.
+
+## Properties
+
+<ArgTypes of={TextExpanderStories} />
diff --git a/packages/craftcms-ui/src/components/text-expander/text-expander.stories.ts b/packages/craftcms-ui/src/components/text-expander/text-expander.stories.ts
index f2839dcdba7..6bd587e8c52 100644
--- a/packages/craftcms-ui/src/components/text-expander/text-expander.stories.ts
+++ b/packages/craftcms-ui/src/components/text-expander/text-expander.stories.ts
@@ -1,4 +1,6 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {expect, waitFor} from 'storybook/test';
 import {html} from 'lit';
 import {ref} from 'lit/directives/ref.js';
@@ -9,6 +11,7 @@ import type {
   TextExpanderTriggers,
 } from './text-expander.js';
 import './text-expander.js';
+import type CraftTextExpander from './text-expander.js';
 
 const people = [
   {label: 'Ada Lovelace', value: '@ada', keywords: ['lovelace']},
@@ -32,14 +35,27 @@ const triggers: TextExpanderTriggers = [
   },
 ];
 
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `text-expander.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftTextExpander>(
+  'craft-text-expander'
+);
+
+type CraftTextExpanderArgs = CraftTextExpander & typeof args;
+
 const meta = {
-  title: 'Functional/Text Expander',
+  title: 'Components/Text Expander',
   component: 'craft-text-expander',
+  args,
+  argTypes,
   parameters: {layout: 'centered'},
-} satisfies Meta<any>;
+} satisfies Meta<CraftTextExpanderArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftTextExpanderArgs>;
 
 export const TextInput: Story = {
   render: () => html`
diff --git a/packages/craftcms-ui/src/components/text-expander/text-expander.test.ts b/packages/craftcms-ui/src/components/text-expander/text-expander.test.ts
index 77770f715d8..2c69bde195f 100644
--- a/packages/craftcms-ui/src/components/text-expander/text-expander.test.ts
+++ b/packages/craftcms-ui/src/components/text-expander/text-expander.test.ts
@@ -379,7 +379,7 @@ describe('craft-text-expander', () => {
     const events: string[] = [];
     let detail: TextExpanderSelectDetail | null = null;
     target.addEventListener('input', () => events.push('input'));
-    expander.addEventListener('craft-text-expander-select', (event) => {
+    expander.addEventListener('craft-select', (event) => {
       events.push('select');
       detail = event.detail;
     });
@@ -745,7 +745,7 @@ describe('craft-text-expander', () => {
       '@': {source: 'text-expander/options'},
     });
     let detail: TextExpanderErrorDetail | null = null;
-    expander.addEventListener('craft-text-expander-error', (event) => {
+    expander.addEventListener('craft-error', (event) => {
       detail = event.detail;
     });
 
@@ -766,7 +766,7 @@ describe('craft-text-expander', () => {
       '#': {source: 'text-expander/options'},
     });
     let detail: TextExpanderErrorDetail | null = null;
-    expander.addEventListener('craft-text-expander-error', (event) => {
+    expander.addEventListener('craft-error', (event) => {
       detail = event.detail;
     });
 
diff --git a/packages/craftcms-ui/src/components/text-expander/text-expander.ts b/packages/craftcms-ui/src/components/text-expander/text-expander.ts
index 10b500db1fa..35a9e74b7a1 100644
--- a/packages/craftcms-ui/src/components/text-expander/text-expander.ts
+++ b/packages/craftcms-ui/src/components/text-expander/text-expander.ts
@@ -94,8 +94,8 @@ let nextId = 0;
  * @csspart listbox - The suggestion listbox.
  * @csspart option - A generated suggestion option.
  * @csspart loading - The loading row.
- * @fires craft-text-expander-select - Fired after a suggestion is inserted.
- * @fires craft-text-expander-error - Fired when a suggestion source fails.
+ * @fires craft-select - Fired after a suggestion is inserted.
+ * @fires craft-error - Fired when a suggestion source fails.
  */
 export default class CraftTextExpander extends LitElement {
   static override styles = [visuallyHiddenStyles, styles];
@@ -508,7 +508,7 @@ export default class CraftTextExpander extends LitElement {
 
       this.#close();
       this.dispatchEvent(
-        new CustomEvent<TextExpanderErrorDetail>('craft-text-expander-error', {
+        new CustomEvent<TextExpanderErrorDetail>('craft-error', {
           bubbles: true,
           composed: true,
           detail: {character: match.character, query: match.query, error},
@@ -644,7 +644,7 @@ export default class CraftTextExpander extends LitElement {
     };
     this.#close();
     this.dispatchEvent(
-      new CustomEvent<TextExpanderSelectDetail>('craft-text-expander-select', {
+      new CustomEvent<TextExpanderSelectDetail>('craft-select', {
         bubbles: true,
         composed: true,
         detail,
@@ -863,7 +863,7 @@ declare global {
   }
 
   interface HTMLElementEventMap {
-    'craft-text-expander-select': CustomEvent<TextExpanderSelectDetail>;
-    'craft-text-expander-error': CustomEvent<TextExpanderErrorDetail>;
+    'craft-select': CustomEvent<TextExpanderSelectDetail>;
+    'craft-error': CustomEvent<TextExpanderErrorDetail>;
   }
 }
diff --git a/packages/craftcms-ui/src/components/textarea/Textarea.mdx b/packages/craftcms-ui/src/components/textarea/Textarea.mdx
new file mode 100644
index 00000000000..f17c17a91b7
--- /dev/null
+++ b/packages/craftcms-ui/src/components/textarea/Textarea.mdx
@@ -0,0 +1,30 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as TextareaStories from './textarea.stories';
+
+<Meta of={TextareaStories} name="Docs" />
+
+# Textarea
+
+`<craft-textarea>` is a multi-line text input.
+
+<Canvas of={TextareaStories.Default} sourceState="shown" />
+
+It carries the same label, help text, validation, and slots as [Input](?path=/docs/form-controls-text-controls-input--docs) — everything on that page applies here.
+
+## When to Use It
+
+Where the value is genuinely prose: a description, a note, a summary.
+
+The size of a field is a promise about the length of the answer. A textarea for something short trains people to write more than the value needs, and a single-line input for something long makes them fight the field.
+
+`monospace` renders the value in a monospace font, for code or structured text where character alignment matters.
+
+## Accessibility
+
+As with any control, the label is what matters — set it, slot it, or wrap the textarea in a [Field](?path=/docs/form-controls-field--docs).
+
+Do not remove the resize handle. It is one of the few pieces of interface a person can adjust to suit themselves, and taking it away helps nobody.
+
+## Properties
+
+<ArgTypes of={TextareaStories} />
diff --git a/packages/craftcms-ui/src/components/textarea/textarea.stories.ts b/packages/craftcms-ui/src/components/textarea/textarea.stories.ts
index c1b0fac07e9..462fa95501d 100644
--- a/packages/craftcms-ui/src/components/textarea/textarea.stories.ts
+++ b/packages/craftcms-ui/src/components/textarea/textarea.stories.ts
@@ -1,23 +1,52 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './textarea.js';
+import type CraftTextarea from './textarea.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `textarea.ts` surfaces it here without touching this file.
+ *
+ * Lion's own `label` and `help-text` are slots here, so they are set through
+ * the `label-slot` and `help-text-slot` args rather than as attributes.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftTextarea>('craft-textarea');
+
+type TextareaArgs = CraftTextarea & typeof args;
 
-// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
-  title: 'Controls/Textarea',
+  title: 'Form Controls/Text Controls/Textarea',
   component: 'craft-textarea',
-  args: {},
-  render: function () {
-    return html`<craft-textarea label="Craft Textarea" help-text="This is some instructions text"></craft-uinput>`;
+  args: {
+    ...args,
+    'label-slot': 'Description',
+    'help-text-slot': 'Shown beneath the entry title in listings.',
   },
-} satisfies Meta<any>;
+  argTypes,
+  // Render from args alone so every control — attributes and slots — drives
+  // the story. Stories below vary the args, not the template.
+  render: (args) => template(args),
+} satisfies Meta<TextareaArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<TextareaArgs>;
+
+/** A multi-line field with the same label and help text as the other controls. */
+export const Default: Story = {};
+
+/** `monospace` suits anything read character by character. */
+export const Monospace: Story = {
+  args: {monospace: true, 'label-slot': 'Redirect rules'},
+};
+
+export const Disabled: Story = {
+  args: {disabled: true},
+};
 
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
+export const Readonly: Story = {
+  args: {readonly: true},
 };
diff --git a/packages/craftcms-ui/src/components/textarea/textarea.test.ts b/packages/craftcms-ui/src/components/textarea/textarea.test.ts
new file mode 100644
index 00000000000..d3806266e53
--- /dev/null
+++ b/packages/craftcms-ui/src/components/textarea/textarea.test.ts
@@ -0,0 +1,68 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './textarea.js';
+import type CraftTextarea from './textarea.js';
+
+async function createTextarea(
+  attrs: Record<string, string> = {},
+  innerHTML = '<label slot="label">Description</label>'
+): Promise<CraftTextarea> {
+  const element = document.createElement('craft-textarea') as CraftTextarea;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await element.updateComplete;
+  return element;
+}
+
+function native(element: CraftTextarea): HTMLTextAreaElement {
+  return element.querySelector('textarea')!;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-textarea', () => {
+  /** A textarea rather than an input is the whole point of the component. */
+  it('renders a native textarea, not an input', async () => {
+    const element = await createTextarea();
+
+    expect(native(element)).toBeTruthy();
+    expect(element.querySelector('input')).toBeNull();
+  });
+
+  it('wires the label to the control', async () => {
+    const element = await createTextarea();
+
+    expect(element.querySelector('label')!.getAttribute('for')).toBe(
+      native(element).id
+    );
+  });
+
+  it('carries the value as Lion s modelValue', async () => {
+    const element = await createTextarea();
+
+    element.modelValue = 'Some description';
+    await element.updateComplete;
+
+    expect(native(element).value).toBe('Some description');
+  });
+
+  it('reflects monospace so the stylesheet can act on it', async () => {
+    const element = await createTextarea({monospace: ''});
+
+    expect(element.monospace).toBe(true);
+    expect(element.hasAttribute('monospace')).toBe(true);
+  });
+
+  it('disables the native control', async () => {
+    const element = await createTextarea({disabled: ''});
+
+    expect(native(element).disabled).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/textarea/textarea.ts b/packages/craftcms-ui/src/components/textarea/textarea.ts
index ff779dd9ab8..2b5fbd74ffc 100644
--- a/packages/craftcms-ui/src/components/textarea/textarea.ts
+++ b/packages/craftcms-ui/src/components/textarea/textarea.ts
@@ -3,11 +3,24 @@ import {inputStyles} from '../../styles/form.styles.js';
 import {LionTextarea} from '@lion/ui/textarea.js';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary A multi-line text input, with the same label, help text, and
+ * validation as `craft-input`.
+ *
+ * Use it where the value is genuinely prose — a description, a note. A
+ * textarea for something short trains people to expect more room than the
+ * value needs.
+ *
+ * @slot label - The field's label, as an alternative to the `label` attribute.
+ * @slot help-text - Guidance shown below the label.
+ * @slot feedback - Validation messages.
+ */
 export default class CraftTextarea extends LionTextarea {
   static override get styles() {
     return [...super.styles, inputStyles, styles];
   }
 
+  /** Renders the value in a monospace font, for code or structured text. */
   @property({type: Boolean, reflect: true})
   monospace: boolean = false;
 }
diff --git a/packages/craftcms-ui/src/components/thumbnail-loader/ThumbnailLoader.mdx b/packages/craftcms-ui/src/components/thumbnail-loader/ThumbnailLoader.mdx
new file mode 100644
index 00000000000..61545bb7312
--- /dev/null
+++ b/packages/craftcms-ui/src/components/thumbnail-loader/ThumbnailLoader.mdx
@@ -0,0 +1,39 @@
+import {ArgTypes, Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Components/Thumbnail Loader" />
+
+# Thumbnail Loader
+
+`<craft-thumbnail-loader>` lazy-loads the server-rendered thumbnail placeholders inside it.
+
+It is a controller element rather than a visual one: it has no shadow root and renders nothing of its own. Wrap markup containing `[data-sizes]` thumb placeholders in it, and each one is loaded as it becomes visible.
+
+```html
+<craft-thumbnail-loader>
+  <div class="thumb" data-sizes="…" data-srcset="…" data-src="…"></div>
+</craft-thumbnail-loader>
+```
+
+There are no stories on this page because there is nothing to look at — the element's whole behaviour is loading images into markup it did not render.
+
+## Why It Exists
+
+Craft's element markup is generated on the server, and its thumbnails are placeholders until something fills them in.
+
+Historically that was an imperative call — `Craft.cp.elementThumbLoader.load(…)` — which meant every code path that injected element markup had to remember to make it. Wrapping the markup instead makes it declarative: a fragment that arrives over XHR loads its own thumbnails because the wrapper came with it.
+
+## Behaviour
+
+Booting waits for the wrapped markup to parse, retrying an animation frame at a time, because the element can upgrade before its children exist — during the initial HTML parse, or when an injected fragment is still being built.
+
+Loading runs through a small worker pool and defers anything off screen until it scrolls into view. Disconnecting destroys the loader, its workers, and its visibility listeners.
+
+## When to Use It
+
+Only with server-rendered thumb placeholders. For a single image in a component you control, use [Thumbnail](?path=/docs/components-thumbnail--docs) — it renders a real `<img>` with native lazy loading and needs no wrapper.
+
+The underlying `ThumbnailLoader` class is also exported from `@craftcms/ui` for imperative use, and `craft-chip` instantiates one directly.
+
+## Properties
+
+<ArgTypes of="craft-thumbnail-loader" />
diff --git a/packages/craftcms-ui/src/components/thumbnail-loader/thumbnail-loader.test.ts b/packages/craftcms-ui/src/components/thumbnail-loader/thumbnail-loader.test.ts
new file mode 100644
index 00000000000..08a2ec61496
--- /dev/null
+++ b/packages/craftcms-ui/src/components/thumbnail-loader/thumbnail-loader.test.ts
@@ -0,0 +1,72 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './thumbnail-loader.js';
+
+function create(innerHTML = ''): HTMLElement {
+  const element = document.createElement('craft-thumbnail-loader');
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  return element;
+}
+
+/** The element boots a frame at a time, so give it a few. */
+async function frames(count = 3) {
+  for (let frame = 0; frame < count; frame++) {
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+  }
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-thumbnail-loader', () => {
+  /**
+   * A light-DOM controller: the loader scans and mutates the markup it wraps,
+   * so a shadow root would put that markup out of its reach.
+   */
+  it('has no shadow root', async () => {
+    const element = create('<div data-sizes="1x" data-src="a.png"></div>');
+    await frames();
+
+    expect(element.shadowRoot).toBeNull();
+  });
+
+  it('leaves the markup it wraps in place', async () => {
+    const element = create('<div class="thumb" data-sizes="1x"></div>');
+    await frames();
+
+    expect(element.querySelector('.thumb')).toBeTruthy();
+  });
+
+  /**
+   * The element can upgrade before its children have parsed — during the
+   * initial HTML parse, or when a fragment is injected — so it waits rather
+   * than giving up on an empty subtree.
+   */
+  it('waits for thumb markup that arrives after it connects', async () => {
+    const element = create();
+    await frames(1);
+
+    const thumb = document.createElement('div');
+    thumb.dataset.sizes = '1x';
+    thumb.dataset.src = 'a.png';
+    element.append(thumb);
+    await frames();
+
+    expect(element.querySelector('[data-sizes]')).toBe(thumb);
+  });
+
+  /** Disconnecting has to destroy the loader's workers and listeners. */
+  it('survives being removed and re-added', async () => {
+    const element = create('<div data-sizes="1x" data-src="a.png"></div>');
+    await frames();
+
+    element.remove();
+    await frames(1);
+    document.body.append(element);
+    await frames();
+
+    expect(element.isConnected).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/thumbnail/Thumbnail.mdx b/packages/craftcms-ui/src/components/thumbnail/Thumbnail.mdx
new file mode 100644
index 00000000000..217c03e2c1b
--- /dev/null
+++ b/packages/craftcms-ui/src/components/thumbnail/Thumbnail.mdx
@@ -0,0 +1,56 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as ThumbnailStories from './thumbnail.stories';
+
+<Meta of={ThumbnailStories} name="Docs" />
+
+# Thumbnail
+
+`<craft-thumbnail>` shows a small preview image in a fixed box, with optional rounding and a checkered backing.
+
+<Canvas of={ThumbnailStories.Default} sourceState="shown" />
+
+It is the image counterpart to [Avatar](?path=/docs/components-avatar--docs): a thumbnail where there is a picture to show, an avatar where there is not.
+
+## The Image
+
+`src`, `srcset`, `sizes`, `alt`, `width`, and `height` are passed through to a real `<img>`, so responsive images and intrinsic sizing work exactly as they do natively.
+
+`loading` defaults to lazy, which is what you want in an index view where most thumbnails start off screen:
+
+<Canvas of={ThumbnailStories.Lazy} sourceState="shown" />
+
+## Transparency
+
+`checkered` draws a chequerboard behind the image, so a transparent PNG reads as transparent rather than as whatever the surface behind it happens to be:
+
+<Canvas of={ThumbnailStories.Checkered} sourceState="shown" />
+
+`rounded` applies the corner radius:
+
+<Canvas of={ThumbnailStories.Rounded} sourceState="shown" />
+
+Both are ordinary boolean attributes: absent means off, present means on. On the server they follow the element — `Asset` sets `checkered` for images that can be transparent, and leaves it off for everything else.
+
+## Sizing
+
+The box is sized by `--c-thumbnail-size` rather than by the image, so a column of thumbnails lines up regardless of what each picture's dimensions are:
+
+<Canvas of={ThumbnailStories.CustomSize} sourceState="shown" />
+
+## Your Own Content
+
+With no `src`, the default slot renders instead — and still gets the box, the rounding, and the checkered backing:
+
+<Canvas of={ThumbnailStories.SlottedContent} sourceState="shown" />
+
+That is the route for an inline `<svg>`, or for a placeholder that is not an image at all.
+
+## Accessibility
+
+`alt` is passed straight to the `<img>`, and the usual rule applies: describe the image when it carries meaning, and use `alt=""` when it repeats a label beside it.
+
+A thumbnail in a [Chip](?path=/docs/components-chip--docs) or [Card](?path=/docs/components-card--docs) is nearly always the second kind — the entity's name is already there in text.
+
+## Properties
+
+<ArgTypes of={ThumbnailStories} />
diff --git a/packages/craftcms-ui/src/components/thumbnail/thumbnail.stories.ts b/packages/craftcms-ui/src/components/thumbnail/thumbnail.stories.ts
index 46a40ae165f..215816d5ffc 100644
--- a/packages/craftcms-ui/src/components/thumbnail/thumbnail.stories.ts
+++ b/packages/craftcms-ui/src/components/thumbnail/thumbnail.stories.ts
@@ -38,21 +38,16 @@ const meta: Meta<CraftThumbnail> = {
 export default meta;
 type Story = StoryObj<CraftThumbnail & typeof args>;
 
-// Checkered is enabled by default and is visible behind the transparent image.
 export const Default: Story = {
   args: {},
 };
 
-// Disable the checkered backing for an opaque image.
+// Side by side, so the chequerboard reads as a property of the left thumbnail
+// rather than as part of the image itself.
 export const Checkered: Story = {
   render: () => html`
-    <craft-thumbnail src="${transparentImage}" alt="Checkered (default)">
-    </craft-thumbnail>
-    <craft-thumbnail
-      src="${transparentImage}"
-      alt="No checkered"
-      .checkered="${false}"
-    >
+    <craft-thumbnail src="${transparentImage}" alt="Default"></craft-thumbnail>
+    <craft-thumbnail src="${transparentImage}" alt="Checkered" checkered>
     </craft-thumbnail>
   `,
 };
diff --git a/packages/craftcms-ui/src/components/thumbnail/thumbnail.test.ts b/packages/craftcms-ui/src/components/thumbnail/thumbnail.test.ts
new file mode 100644
index 00000000000..e8fe45853aa
--- /dev/null
+++ b/packages/craftcms-ui/src/components/thumbnail/thumbnail.test.ts
@@ -0,0 +1,100 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './thumbnail.js';
+import type CraftThumbnail from './thumbnail.js';
+
+async function createThumbnail(
+  attrs: Record<string, string> = {},
+  innerHTML = ''
+): Promise<CraftThumbnail> {
+  const element = document.createElement('craft-thumbnail') as CraftThumbnail;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+function box(element: CraftThumbnail): HTMLElement {
+  return element.shadowRoot!.querySelector('.thumbnail')!;
+}
+
+function image(element: CraftThumbnail): HTMLImageElement | null {
+  return element.shadowRoot!.querySelector('img');
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-thumbnail', () => {
+  it('renders an image from src', async () => {
+    const element = await createThumbnail({src: 'a.png', alt: 'An asset'});
+
+    expect(image(element)?.getAttribute('src')).toBe('a.png');
+    expect(image(element)?.getAttribute('alt')).toBe('An asset');
+  });
+
+  it('lazy-loads by default, and defers decoding', async () => {
+    const element = await createThumbnail({src: 'a.png'});
+
+    expect(image(element)?.getAttribute('loading')).toBe('lazy');
+    expect(image(element)?.getAttribute('decoding')).toBe('async');
+  });
+
+  it('takes an eager loading strategy when asked', async () => {
+    const element = await createThumbnail({src: 'a.png', loading: 'eager'});
+
+    expect(image(element)?.getAttribute('loading')).toBe('eager');
+  });
+
+  it('falls back to the default slot with no src', async () => {
+    const element = await createThumbnail({}, '<svg></svg>');
+
+    expect(image(element)).toBeNull();
+    expect(element.shadowRoot!.querySelector('slot')).toBeTruthy();
+  });
+
+  /**
+   * `checkered` is an ordinary boolean attribute: absent means off. The server
+   * renders it only for images that can be transparent, and omits it
+   * otherwise, so a defaulted-on property would checker every other thumbnail.
+   */
+  it('is not checkered unless asked', async () => {
+    const element = await createThumbnail({src: 'a.png'});
+
+    expect(element.checkered).toBe(false);
+    expect(box(element).classList.contains('thumbnail--checkered')).toBe(false);
+  });
+
+  it('checkers when the attribute is present', async () => {
+    const element = await createThumbnail({src: 'a.png', checkered: ''});
+
+    expect(element.checkered).toBe(true);
+    expect(box(element).classList.contains('thumbnail--checkered')).toBe(true);
+  });
+
+  it('rounds when the attribute is present', async () => {
+    const element = await createThumbnail({src: 'a.png', rounded: ''});
+
+    expect(box(element).classList.contains('thumbnail--rounded')).toBe(true);
+  });
+
+  it('passes the responsive image attributes through', async () => {
+    const element = await createThumbnail({
+      src: 'a.png',
+      srcset: 'a.png 1x, a@2x.png 2x',
+      sizes: '2rem',
+      width: '32',
+      height: '32',
+    });
+
+    expect(image(element)?.getAttribute('srcset')).toBe(
+      'a.png 1x, a@2x.png 2x'
+    );
+    expect(image(element)?.getAttribute('sizes')).toBe('2rem');
+    expect(image(element)?.getAttribute('width')).toBe('32');
+  });
+});
diff --git a/packages/craftcms-ui/src/components/thumbnail/thumbnail.ts b/packages/craftcms-ui/src/components/thumbnail/thumbnail.ts
index 3fa0538acb2..04d4a34f7b6 100644
--- a/packages/craftcms-ui/src/components/thumbnail/thumbnail.ts
+++ b/packages/craftcms-ui/src/components/thumbnail/thumbnail.ts
@@ -5,18 +5,6 @@ import {classMap} from 'lit/directives/class-map.js';
 import {ifDefined} from 'lit/directives/if-defined.js';
 import styles from './thumbnail.styles.js';
 
-/**
- * Boolean attribute converter that treats the string `"false"` as `false`.
- * Lit's built-in boolean converter is presence-based, so `checkered="false"`
- * would otherwise be truthy — this lets server-rendered markup disable the
- * attribute with `checkered="false"`.
- */
-const defaultTrueBoolean = {
-  fromAttribute: (value: string | null): boolean =>
-    value !== null && value !== 'false',
-  toAttribute: (value: boolean): string | null => (value ? '' : null),
-};
-
 /**
  * @summary Displays an image thumbnail with an optional checkered backing and
  * rounded corners. Images are lazy-loaded natively via the browser.
@@ -60,9 +48,12 @@ export default class CraftThumbnail extends LitElement {
   /** Native browser loading strategy for the image. Defaults to `lazy`. */
   @property() loading: 'lazy' | 'eager' = 'lazy';
 
-  /** Whether to render a checkered pattern behind the image. Enabled by default. */
-  @property({reflect: true, converter: defaultTrueBoolean})
-  checkered = true;
+  /**
+   * Whether to render a checkered pattern behind the image, to show where a
+   * transparent image ends. Off by default, and set only for the images that
+   * warrant it — `Asset::hasCheckeredThumb()` decides on the server.
+   */
+  @property({type: Boolean, reflect: true}) checkered = false;
 
   /** Whether to round the corners of the image. */
   @property({type: Boolean, reflect: true}) rounded = false;
diff --git a/packages/craftcms-ui/src/components/tooltip/Tooltip.mdx b/packages/craftcms-ui/src/components/tooltip/Tooltip.mdx
index 5c9d7881249..2d5ba8e80e1 100644
--- a/packages/craftcms-ui/src/components/tooltip/Tooltip.mdx
+++ b/packages/craftcms-ui/src/components/tooltip/Tooltip.mdx
@@ -1,10 +1,14 @@
-import {Canvas, Meta} from '@storybook/addon-docs/blocks';
-import TooltipMeta, {Playground} from './tooltip.stories';
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as TooltipStories from './tooltip.stories';
 
-<Meta of={TooltipMeta} />
+<Meta of={TooltipStories} name="Docs" />
 
 # Tooltip
 
 `<craft-tooltip>` shows contextual text for an external trigger element referenced by id via the `for` attribute. It is built on [Lion's tooltip/overlay system](https://lion.js.org/components/tooltip/overview/) and supports `placement` (Popper placement strings) and `trigger` (`hover focus`, `click`, or `manual`). It emits `craft-show`, `craft-after-show`, `craft-hide`, and `craft-after-hide` events.
 
-<Canvas of={Playground} />
+<Canvas of={TooltipStories.Playground} sourceState="shown" />
+
+## Properties
+
+<ArgTypes of={TooltipStories} />
diff --git a/packages/craftcms-ui/src/components/tooltip/tooltip.stories.ts b/packages/craftcms-ui/src/components/tooltip/tooltip.stories.ts
index 7fbec3585f7..ce10365aa63 100644
--- a/packages/craftcms-ui/src/components/tooltip/tooltip.stories.ts
+++ b/packages/craftcms-ui/src/components/tooltip/tooltip.stories.ts
@@ -1,18 +1,32 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
 import {html} from 'lit';
 
 import './tooltip.js';
+import type CraftTooltip from './tooltip.js';
 import '../button/button.js';
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `tooltip.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes} = getStorybookHelpers<CraftTooltip>('craft-tooltip');
+
+type CraftTooltipArgs = CraftTooltip & typeof args;
+
 const meta = {
   title: 'Components/Tooltip',
   component: 'craft-tooltip',
   args: {
+    ...args,
     placement: 'top',
     content: 'This is some content within a tooltip',
   },
+  argTypes,
   parameters: {
     layout: 'centered',
   },
@@ -32,10 +46,10 @@ const meta = {
       <craft-button id="my-button">Hover me</craft-button>
     `;
   },
-} satisfies Meta<any>;
+} satisfies Meta<CraftTooltipArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftTooltipArgs>;
 
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
 export const Playground: Story = {
diff --git a/packages/craftcms-ui/src/components/tooltip/tooltip.ts b/packages/craftcms-ui/src/components/tooltip/tooltip.ts
index 6ce447ac593..d022ffe5b3c 100644
--- a/packages/craftcms-ui/src/components/tooltip/tooltip.ts
+++ b/packages/craftcms-ui/src/components/tooltip/tooltip.ts
@@ -11,7 +11,10 @@ import {viewportEscapingModifiers} from '../../utilities/overlay-position.js';
  *
  * @example <craft-tooltip for="my-button" placement="right-start">Help text</craft-tooltip>
  *
- * Emits `craft-show`/`craft-after-show`/`craft-hide`/`craft-after-hide`.
+ * @fires craft-show - The overlay is opening. Fires as the state flips.
+ * @fires craft-after-show - The overlay has opened and its update has settled.
+ * @fires craft-hide - The overlay is closing. Fires as the state flips.
+ * @fires craft-after-hide - The overlay has closed and its update has settled.
  */
 export default class CraftTooltip extends LionTooltip {
   /** Id of the trigger element within the same document/shadow root. */
@@ -176,11 +179,23 @@ export default class CraftTooltip extends LionTooltip {
     }
   }
 
+  /**
+
+   * Shows the tooltip, regardless of `trigger`. Resolves once it is open.
+
+   */
+
   async show(): Promise<void> {
     this.opened = true;
     await this.updateComplete;
   }
 
+  /**
+
+   * Hides the tooltip. Resolves once it is closed.
+
+   */
+
   async hide(): Promise<void> {
     this.opened = false;
     await this.updateComplete;
diff --git a/packages/craftcms-ui/src/components/truncate/Truncate.mdx b/packages/craftcms-ui/src/components/truncate/Truncate.mdx
new file mode 100644
index 00000000000..7d10bbbd37b
--- /dev/null
+++ b/packages/craftcms-ui/src/components/truncate/Truncate.mdx
@@ -0,0 +1,32 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as TruncateStories from './truncate.stories';
+
+<Meta of={TruncateStories} name="Docs" />
+
+# Truncate
+
+`<craft-truncate>` shortens text that does not fit, and shows the whole of it in a tooltip.
+
+<Canvas of={TruncateStories.Default} sourceState="shown" />
+
+The tooltip only appears when the text is actually clipped:
+
+<Canvas of={TruncateStories.FitsWithoutTooltip} sourceState="shown" />
+
+That conditional behaviour is the point. A tooltip repeating text already fully visible is noise, and one that never appears leaves clipped text unreadable.
+
+## When to Reach for It
+
+Where a value's length is outside your control and the space is not — a filename in a column, an entry title in a narrow sidebar.
+
+Where you control the text, write it shorter. Truncation is a fallback for unpredictable content, not a substitute for editing.
+
+## Accessibility
+
+The full text remains available to assistive technology, so a screen reader announces the whole value rather than the clipped version.
+
+The tooltip is reachable by keyboard as well as pointer — which matters, because clipped text a person cannot expand is text they cannot read.
+
+## Properties
+
+<ArgTypes of={TruncateStories} />
diff --git a/packages/craftcms-ui/src/components/truncate/truncate.stories.ts b/packages/craftcms-ui/src/components/truncate/truncate.stories.ts
index 2eabdf6d4ea..cc48867dab7 100644
--- a/packages/craftcms-ui/src/components/truncate/truncate.stories.ts
+++ b/packages/craftcms-ui/src/components/truncate/truncate.stories.ts
@@ -1,61 +1,65 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
 import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 
 import './truncate.js';
+import type CraftTruncate from './truncate.js';
+
+/**
+ * `args` and `argTypes` are derived from the custom elements manifest, so the
+ * controls and the API tables follow the component's JSDoc. Adding a property
+ * to `truncate.ts` surfaces it here without touching this file.
+ */
+const {args, argTypes, template} =
+  getStorybookHelpers<CraftTruncate>('craft-truncate');
+
+type TruncateArgs = CraftTruncate & typeof args;
+
+const LONG_TEXT =
+  'This is a fairly long piece of text that will be truncated when it does not fit';
+
+/**
+ * The component truncates against its container, so every story needs one with
+ * a width. The box is story scaffolding, not part of the component.
+ */
+const inABox = (content: unknown, width = '200px') => html`
+  <div
+    style="width: ${width}; border: 1px dashed var(--c-color-border-quiet, #ccc)"
+  >
+    ${content}
+  </div>
+`;
 
 const meta = {
   title: 'Components/Truncate',
   component: 'craft-truncate',
-  args: {
-    width: '200px',
-    content:
-      'This is a fairly long piece of text that will be truncated when it does not fit',
-    placement: 'top',
-  },
-  argTypes: {
-    width: {control: {type: 'text'}},
-    content: {control: {type: 'text'}},
-    placement: {
-      control: {type: 'select'},
-      options: [
-        'top-start',
-        'top',
-        'top-end',
-        'right-start',
-        'right',
-        'right-end',
-        'bottom-end',
-        'bottom',
-        'bottom-start',
-        'left-end',
-        'left',
-        'left-start',
-      ],
-    },
-  },
-  parameters: {
-    layout: 'centered',
-  },
-  render: (args) => html`
-    <div
-      style="width: ${args.width}; border: 1px dashed var(--c-color-border-quiet, #ccc);"
-    >
-      <craft-truncate placement="${args.placement}"
-        >${args.content}</craft-truncate
-      >
-    </div>
-  `,
-} satisfies Meta<any>;
+  args: {...args, 'default-slot': LONG_TEXT},
+  argTypes,
+  parameters: {layout: 'centered'},
+  // Render from args alone so every control — attributes and slot — drives the
+  // story, inside the constrained box the component needs to truncate at all.
+  render: (args) => inABox(template(args)),
+} satisfies Meta<TruncateArgs>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<TruncateArgs>;
 
-export const Playground: Story = {};
+/** Text too long for its container truncates, and gains a tooltip. */
+export const Default: Story = {};
 
+/** Text that fits is left alone, and gets no tooltip. */
 export const FitsWithoutTooltip: Story = {
-  args: {
-    width: '400px',
-    content: 'Short label',
-  },
+  args: {'default-slot': 'Short label'},
+  render: (args) => inABox(template(args), '400px'),
+};
+
+/** `placement` moves the tooltip, the same values the overlay takes. */
+export const Placement: Story = {
+  args: {placement: 'bottom'},
+};
+
+/** `disabled` keeps the visual truncation but drops the tooltip. */
+export const Disabled: Story = {
+  args: {disabled: true},
 };
diff --git a/packages/craftcms-ui/src/components/truncate/truncate.styles.ts b/packages/craftcms-ui/src/components/truncate/truncate.styles.ts
index ab475d3ea47..74187abd170 100644
--- a/packages/craftcms-ui/src/components/truncate/truncate.styles.ts
+++ b/packages/craftcms-ui/src/components/truncate/truncate.styles.ts
@@ -6,6 +6,7 @@ export default css`
     /* Allow the element to shrink below its content size in flex/grid layouts
        so the text actually truncates instead of forcing the container wider. */
     min-width: 0;
+    max-width: 100%;
   }
 
   .truncate {
diff --git a/packages/craftcms-ui/src/components/truncate/truncate.ts b/packages/craftcms-ui/src/components/truncate/truncate.ts
index 7b8b3d998b1..ded8c9ba545 100644
--- a/packages/craftcms-ui/src/components/truncate/truncate.ts
+++ b/packages/craftcms-ui/src/components/truncate/truncate.ts
@@ -52,7 +52,13 @@ export default class CraftTruncate extends LitElement {
   }
 
   protected override firstUpdated() {
-    this.#measure();
+    // `observe()` delivers an initial callback once the element is laid out,
+    // which is the first measurement. Measuring here as well would set state
+    // straight after an update completed — the double render Lit warns about.
+    // Without a ResizeObserver there is nothing else to seed it.
+    if (!this.#resizeObserver) {
+      this.#measure();
+    }
   }
 
   #measure() {
diff --git a/packages/craftcms-ui/src/components/visually-hidden/VisuallyHidden.mdx b/packages/craftcms-ui/src/components/visually-hidden/VisuallyHidden.mdx
new file mode 100644
index 00000000000..55fac7e0e36
--- /dev/null
+++ b/packages/craftcms-ui/src/components/visually-hidden/VisuallyHidden.mdx
@@ -0,0 +1,40 @@
+import {ArgTypes, Canvas, Meta} from '@storybook/addon-docs/blocks';
+import * as VisuallyHiddenStories from './visually-hidden.stories';
+
+<Meta of={VisuallyHiddenStories} name="Docs" />
+
+# Visually Hidden
+
+`<craft-visually-hidden>` hides its content visually while leaving it available to screen readers.
+
+<Canvas of={VisuallyHiddenStories.Default} sourceState="shown" />
+
+There is text in that example. It is in the document, in the accessibility tree, and in the tab order — it just is not painted.
+
+## When to Use It
+
+For text that names something the design conveys another way:
+
+- an icon-only control, where the icon carries the meaning visually
+- a table column whose header is implied by position
+- a live region reporting progress that is already visible as a spinner
+
+<Canvas of={VisuallyHiddenStories.InContext} sourceState="shown" />
+
+**Hidden is not removed.** `display: none` and `hidden` take content out of the accessibility tree entirely; this keeps it in. That difference is the whole point, and it is why `display: none` is not a substitute.
+
+## Checking It
+
+`debug` reveals the content, which is a faster way to see what a screen reader would announce than reaching for one:
+
+<Canvas of={VisuallyHiddenStories.Debug} sourceState="shown" />
+
+## A Caution
+
+Hidden text is text nobody proofreads. It goes stale, it gets missed in translation passes, and it is invisible in a design review.
+
+Prefer a visible label where one fits. Reach for this when the design genuinely cannot carry one — not as a way to satisfy an accessibility check while leaving the interface unlabelled.
+
+## Properties
+
+<ArgTypes of={VisuallyHiddenStories} />
diff --git a/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.stories.ts b/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.stories.ts
new file mode 100644
index 00000000000..59b2086ae38
--- /dev/null
+++ b/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.stories.ts
@@ -0,0 +1,45 @@
+import type {Meta, StoryObj} from '@storybook/web-components-vite';
+
+import {html} from 'lit';
+import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
+
+import './visually-hidden.js';
+import '../button/button.js';
+import '../icon/icon.js';
+import type CraftVisuallyHidden from './visually-hidden.js';
+
+const {args, argTypes, template} = getStorybookHelpers<CraftVisuallyHidden>(
+  'craft-visually-hidden'
+);
+
+type VisuallyHiddenArgs = CraftVisuallyHidden & typeof args;
+
+const meta = {
+  title: 'Components/Visually Hidden',
+  component: 'craft-visually-hidden',
+  args: {...args, 'default-slot': 'Announced but not shown'},
+  argTypes,
+  render: (args) => template(args),
+} satisfies Meta<VisuallyHiddenArgs>;
+
+export default meta;
+type Story = StoryObj<VisuallyHiddenArgs>;
+
+/** There is text here — it is just not visible. */
+export const Default: Story = {};
+
+/** `debug` reveals the content, for checking what would be announced. */
+export const Debug: Story = {
+  args: {debug: true},
+};
+
+/** Naming an icon-only control without showing the label twice. */
+export const InContext: Story = {
+  parameters: {controls: {disable: true}},
+  render: () => html`
+    <craft-button>
+      <craft-icon name="trash"></craft-icon>
+      <craft-visually-hidden>Delete entry</craft-visually-hidden>
+    </craft-button>
+  `,
+};
diff --git a/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.test.ts b/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.test.ts
new file mode 100644
index 00000000000..792da9bdccc
--- /dev/null
+++ b/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.test.ts
@@ -0,0 +1,55 @@
+import {beforeEach, describe, expect, it} from 'vite-plus/test';
+
+import './visually-hidden.js';
+import type CraftVisuallyHidden from './visually-hidden.js';
+
+async function createVisuallyHidden(
+  attrs: Record<string, string> = {},
+  innerHTML = 'Skip to content'
+): Promise<CraftVisuallyHidden> {
+  const element = document.createElement(
+    'craft-visually-hidden'
+  ) as CraftVisuallyHidden;
+  for (const [name, value] of Object.entries(attrs)) {
+    element.setAttribute(name, value);
+  }
+  element.innerHTML = innerHTML;
+  document.body.append(element);
+  await element.updateComplete;
+  return element;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('craft-visually-hidden', () => {
+  /**
+   * The content has to stay in the accessibility tree — hiding it with
+   * `display: none` or `hidden` would take it out, which is the opposite of
+   * what this component is for.
+   */
+  it('keeps its content in the DOM', async () => {
+    const element = await createVisuallyHidden();
+
+    expect(element.textContent).toBe('Skip to content');
+    expect(element.shadowRoot!.querySelector('slot')).toBeTruthy();
+    expect(element.hasAttribute('hidden')).toBe(false);
+  });
+
+  it('is not in debug mode by default', async () => {
+    const element = await createVisuallyHidden();
+
+    expect(element.debug).toBe(false);
+  });
+
+  /** `debug` reveals the content, for checking what a screen reader gets. */
+  it('reflects debug so the stylesheet can reveal it', async () => {
+    const element = await createVisuallyHidden();
+
+    element.debug = true;
+    await element.updateComplete;
+
+    expect(element.hasAttribute('debug')).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.ts b/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.ts
index 3aca980a7bb..42279b9b22d 100644
--- a/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.ts
+++ b/packages/craftcms-ui/src/components/visually-hidden/visually-hidden.ts
@@ -1,7 +1,17 @@
 import {css, html, LitElement} from 'lit';
-import CraftInfoIcon from '@src/components/info-icon/info-icon';
 import {property} from 'lit/decorators.js';
 
+/**
+ * @summary Hides its content visually while leaving it available to screen
+ * readers. Use it for text that names something the design conveys another
+ * way — an icon-only control, a table column whose header is implied by
+ * position, a live region reporting progress.
+ *
+ * Hidden is not the same as removed: the content stays in the accessibility
+ * tree and in the document order, which is the whole point.
+ *
+ * @slot - The content to hide visually.
+ */
 export default class CraftVisuallyHidden extends LitElement {
   static override styles = css`
     :host(:not([debug])) {
@@ -15,6 +25,10 @@ export default class CraftVisuallyHidden extends LitElement {
     }
   `;
 
+  /**
+   * Reveals the content, for checking what a screen reader would announce
+   * without reaching for one.
+   */
   @property({type: Boolean, reflect: true}) debug = false;
 
   protected override render(): unknown {
diff --git a/packages/craftcms-ui/src/controllers/LightDomController.test.ts b/packages/craftcms-ui/src/controllers/LightDomController.test.ts
new file mode 100644
index 00000000000..088bc1b0d39
--- /dev/null
+++ b/packages/craftcms-ui/src/controllers/LightDomController.test.ts
@@ -0,0 +1,113 @@
+import {beforeEach, describe, expect, test} from 'vite-plus/test';
+import {html, LitElement} from 'lit';
+import {customElement} from 'lit/decorators.js';
+
+import {hasSlotted, LightDomController} from './LightDomController';
+
+@customElement('light-dom-host')
+class LightDomHost extends LitElement {
+  renders = 0;
+
+  // Assigned for its side effect: the controller registers itself on the host.
+  private _lightDom = new LightDomController(this, {
+    onChange: () => this.changes++,
+  });
+
+  changes = 0;
+
+  override render() {
+    this.renders++;
+    return html`<slot name="footer"></slot>`;
+  }
+}
+
+function mount(markup: string): LightDomHost {
+  document.body.innerHTML = markup;
+  return document.body.firstElementChild as LightDomHost;
+}
+
+describe('hasSlotted', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  test('finds a direct child in the named slot', () => {
+    const host = mount(
+      '<light-dom-host><p slot="footer"></p></light-dom-host>'
+    );
+    expect(hasSlotted(host, 'footer')).toBe(true);
+  });
+
+  test('matches any of the names given', () => {
+    const host = mount(
+      '<light-dom-host><p slot="actions"></p></light-dom-host>'
+    );
+    expect(hasSlotted(host, 'footer', 'actions')).toBe(true);
+  });
+
+  test('ignores a matching slot nested deeper in the subtree', () => {
+    const host = mount(
+      '<light-dom-host><div><p slot="footer"></p></div></light-dom-host>'
+    );
+    expect(hasSlotted(host, 'footer')).toBe(false);
+  });
+
+  test('matches the default slot as the empty string', () => {
+    const host = mount('<light-dom-host><p></p></light-dom-host>');
+    expect(hasSlotted(host, '')).toBe(true);
+  });
+});
+
+describe('LightDomController', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  test('syncs once on connect', async () => {
+    const host = mount('<light-dom-host></light-dom-host>');
+    await host.updateComplete;
+    expect(host.changes).toBe(1);
+  });
+
+  test('re-renders when a child is added', async () => {
+    const host = mount('<light-dom-host></light-dom-host>');
+    await host.updateComplete;
+    const before = host.renders;
+
+    const child = document.createElement('p');
+    child.slot = 'footer';
+    host.append(child);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await host.updateComplete;
+
+    expect(host.renders).toBeGreaterThan(before);
+    expect(hasSlotted(host, 'footer')).toBe(true);
+  });
+
+  test('re-renders when content moves between slots', async () => {
+    const host = mount(
+      '<light-dom-host><p slot="footer"></p></light-dom-host>'
+    );
+    await host.updateComplete;
+    const before = host.renders;
+
+    host.querySelector('p')!.slot = 'header';
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await host.updateComplete;
+
+    expect(host.renders).toBeGreaterThan(before);
+    expect(hasSlotted(host, 'footer')).toBe(false);
+  });
+
+  test('stops observing once disconnected', async () => {
+    const host = mount('<light-dom-host></light-dom-host>');
+    await host.updateComplete;
+    host.remove();
+    const after = host.changes;
+
+    host.append(document.createElement('p'));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(host.changes).toBe(after);
+  });
+});
diff --git a/packages/craftcms-ui/src/controllers/LightDomController.ts b/packages/craftcms-ui/src/controllers/LightDomController.ts
new file mode 100644
index 00000000000..bffb14e0488
--- /dev/null
+++ b/packages/craftcms-ui/src/controllers/LightDomController.ts
@@ -0,0 +1,79 @@
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+
+interface LightDomControllerOptions {
+  /**
+   * Extra host attributes to watch alongside `slot`. Pass the ones the host
+   * reads during render, such as `aria-label`.
+   */
+  attributeFilter?: string[];
+  /** Whether text changes in the light DOM should count as a mutation. */
+  characterData?: boolean;
+  /**
+   * Run on connect and on every mutation batch, before the host re-renders.
+   * Use it to refresh derived state; the host is asked to update either way.
+   */
+  onChange?: () => void;
+}
+
+/**
+ * Re-renders its host when the light DOM changes.
+ *
+ * Components that render a slot only when something is in it can't use
+ * `slotchange` to find out: a slot that was never rendered has nothing to fire
+ * the event. Lit doesn't re-render on light-DOM changes on its own either, so
+ * the host would show whatever was there on first paint — a chip whose action
+ * menu is injected after mount would never show it.
+ *
+ * The observer watches the `slot` attribute as well as child lists, because
+ * content moves between slots by having its `slot` attribute rewritten rather
+ * than by being added or removed.
+ *
+ * Pair it with `hasSlotted()` to read presence during render.
+ */
+export class LightDomController implements ReactiveController {
+  private readonly host: ReactiveControllerHost & Element;
+
+  private readonly options: LightDomControllerOptions;
+
+  private readonly observer: MutationObserver;
+
+  constructor(
+    host: ReactiveControllerHost & Element,
+    options: LightDomControllerOptions = {}
+  ) {
+    this.host = host;
+    this.options = options;
+    this.observer = new MutationObserver(() => {
+      this.options.onChange?.();
+      this.host.requestUpdate();
+    });
+    host.addController(this);
+  }
+
+  hostConnected() {
+    this.options.onChange?.();
+    this.observer.observe(this.host, {
+      childList: true,
+      subtree: true,
+      characterData: this.options.characterData ?? false,
+      attributes: true,
+      attributeFilter: ['slot', ...(this.options.attributeFilter ?? [])],
+    });
+  }
+
+  hostDisconnected() {
+    this.observer.disconnect();
+  }
+}
+
+/**
+ * Whether any of the named slots has content.
+ *
+ * Only direct children can fill an element's slots, so presence is checked
+ * against them rather than the whole subtree — a nested component with its own
+ * `footer` slot must not light up its ancestor's chrome. The default slot is
+ * matched by the empty string, the same way `HTMLElement.slot` reports it.
+ */
+export function hasSlotted(host: Element, ...names: string[]): boolean {
+  return Array.from(host.children).some((child) => names.includes(child.slot));
+}
diff --git a/packages/craftcms-ui/src/factory/create-slide-picker.ts b/packages/craftcms-ui/src/factory/create-slide-picker.ts
index 16fc9f303e3..44c8f435280 100644
--- a/packages/craftcms-ui/src/factory/create-slide-picker.ts
+++ b/packages/craftcms-ui/src/factory/create-slide-picker.ts
@@ -19,8 +19,9 @@ export interface SlidePickerConfig {
 }
 
 /**
- * Creates a `<craft-slide-picker>` (segmented slider). A hidden input carries the
- * value for form posting; `onChange` fires on the element's `value-change` event.
+ * Creates a `<craft-slide-picker>` (segmented slider). The element is
+ * form-associated, so `name` is all it takes to post the value; `onChange`
+ * fires on the element's `change` event.
  */
 export function createSlidePicker(
   config: SlidePickerConfig = {}
@@ -44,7 +45,13 @@ export function createSlidePicker(
     el.setAttribute('described-by', config.describedBy);
   }
   if (readOnly) {
-    el.setAttribute('read-only', '');
+    el.readonly = true;
+  }
+  if (config.disabled) {
+    el.disabled = true;
+  }
+  if (config.name) {
+    el.name = config.name;
   }
   if (config.id) {
     el.id = config.id;
@@ -53,25 +60,8 @@ export function createSlidePicker(
     el.classList.add(...config.class.split(/\s+/).filter(Boolean));
   }
 
-  let hidden: HTMLInputElement | null = null;
-  if (config.name) {
-    hidden = document.createElement('input');
-    hidden.type = 'hidden';
-    hidden.name = config.name;
-    hidden.setAttribute('value', String(el.value));
-    hidden.disabled = !!config.disabled;
-    el.append(hidden);
-  }
-
-  el.addEventListener('value-change', (event) => {
-    const next = (event as CustomEvent<{value: number}>).detail?.value;
-    if (typeof next !== 'number') {
-      return;
-    }
-    if (hidden) {
-      hidden.value = String(next);
-    }
-    config.onChange?.(next);
+  el.addEventListener('change', () => {
+    config.onChange?.(el.value);
   });
 
   return el;
diff --git a/packages/craftcms-ui/src/factory/factory.test.ts b/packages/craftcms-ui/src/factory/factory.test.ts
index bf76a2354c6..c4c8cc21e17 100644
--- a/packages/craftcms-ui/src/factory/factory.test.ts
+++ b/packages/craftcms-ui/src/factory/factory.test.ts
@@ -148,7 +148,7 @@ describe('createSwitch', () => {
 });
 
 describe('createSlidePicker', () => {
-  it('sets the numeric props and a form-posting hidden input', () => {
+  it('sets the numeric props and posts under its name', () => {
     const el = createSlidePicker({
       min: 0,
       max: 100,
@@ -163,8 +163,10 @@ describe('createSlidePicker', () => {
     expect(el.step).toBe(25);
     expect(el.value).toBe(50);
 
-    const hidden = el.querySelector<HTMLInputElement>('input[type="hidden"]');
-    expect(hidden?.name).toBe('cols');
+    // The element is form-associated, so the name goes on it — there is no
+    // hidden input standing in for the value.
+    expect(el.name).toBe('cols');
+    expect(el.querySelector('input[type="hidden"]')).toBeNull();
   });
 
   it('resolves function min/max', () => {
diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index 3229b000048..2f55f7f2814 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -113,6 +113,7 @@ export * from './utilities/dom.js';
 export * from './utilities/attrs.js';
 export * from './utilities/thumbnail-loader.js';
 export * from './utilities/create.js';
+export * from './utilities/converters.js';
 
 // Services
 export {ConfigService} from './services/Config.js';
diff --git a/packages/craftcms-ui/src/mixins/Actionable.ts b/packages/craftcms-ui/src/mixins/Actionable.ts
index d3347de3c23..d21043316ff 100644
--- a/packages/craftcms-ui/src/mixins/Actionable.ts
+++ b/packages/craftcms-ui/src/mixins/Actionable.ts
@@ -21,7 +21,7 @@ export interface ActionableHost {
   actionState: AsyncState;
   /** Transient message surfaced during feedback (e.g. an error). */
   feedbackMessage: string | null;
-  /** Run {@link action} now, driving state + emitting `action:change-state`. */
+  /** Run {@link action} now, driving state + emitting `craft-state-change`. */
   triggerAction(): Promise<void>;
   setActionState(state: AsyncState, detail?: FeedbackData): void;
 }
@@ -29,7 +29,7 @@ export interface ActionableHost {
 /**
  * Adds a declarative `action` to any Lit element: clicking the host runs the
  * action through {@link runAction}, tracking idle/loading/success/error state,
- * surfacing feedback, and emitting a bubbling `action:change-state` event so an
+ * surfacing feedback, and emitting a bubbling `craft-state-change` event so an
  * ancestor (menu, toolbar) can react. This is the shared implementation behind
  * `craft-action-item` and `craft-button` — components read `actionState` /
  * `feedbackMessage` to render their own spinners/checks.
@@ -81,7 +81,7 @@ export const Actionable = <T extends Constructor<LitElement>>(Base: T) => {
       this.feedbackMessage = detail.message ?? null;
 
       this.dispatchEvent(
-        new CustomEvent('action:change-state', {
+        new CustomEvent('craft-state-change', {
           bubbles: true,
           composed: true,
           detail: {
diff --git a/packages/craftcms-ui/src/mixins/FormAssociated.ts b/packages/craftcms-ui/src/mixins/FormAssociated.ts
new file mode 100644
index 00000000000..8fc45ac38fc
--- /dev/null
+++ b/packages/craftcms-ui/src/mixins/FormAssociated.ts
@@ -0,0 +1,167 @@
+import type {LitElement, PropertyValues} from 'lit';
+import {property} from 'lit/decorators.js';
+
+// oxlint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = object> = new (...args: any[]) => T;
+
+/** The form-control surface the mixin adds. */
+export declare class FormAssociatedHost {
+  /**
+   * The value to submit, or `null` to submit nothing. Hosts override this;
+   * the default posts nothing.
+   *
+   * Underscore-prefixed because it is the contract between a component and
+   * this mixin rather than public API, so the manifest drops it.
+   */
+  _formValue(): string | null;
+
+  /**
+   * Applies a value the browser handed back — on `form.reset()`, or when it
+   * restores a session. Receives exactly what `_formValue()` produced. Hosts
+   * override this; the default does nothing.
+   */
+  _restoreFormValue(value: string | null): void;
+
+  /** Field name. The control posts under this, like any other input. */
+  name: string;
+
+  /**
+   * Whether the control is disabled. A disabled control does not respond to
+   * input and is left out of form submission.
+   */
+  disabled: boolean;
+
+  /** The form this control belongs to, or `null` when it is outside one. */
+  readonly form: HTMLFormElement | null;
+
+  /** The control's current validity state. */
+  readonly validity: ValidityState;
+
+  /** The message shown when the control is invalid. Empty when it is valid. */
+  readonly validationMessage: string;
+
+  /** Whether the control takes part in constraint validation. */
+  readonly willValidate: boolean;
+
+  /** Reports whether the control is valid, without showing anything. */
+  checkValidity(): boolean;
+
+  /** Reports whether the control is valid, showing the message if it is not. */
+  reportValidity(): boolean;
+}
+
+/**
+ * Makes a Lit element a form-associated custom element: it posts with
+ * `<form>`, `new FormData(form)` reads it, `form.reset()` resets it, and
+ * `form.checkValidity()` includes it — the same deal a native input gets, with
+ * no hidden input standing in for the value.
+ *
+ * The host says what its value is and how to put one back; everything else —
+ * `name`, `disabled`, the validity surface, and the four lifecycle callbacks —
+ * comes from here:
+ *
+ * ```ts
+ * class CraftThing extends FormAssociated(LitElement) {
+ *   @property({type: Number}) value = 0;
+ *
+ *   _formValue() {
+ *     return String(this.value);
+ *   }
+ *
+ *   _restoreFormValue(value: string | null) {
+ *     this.value = Number(value ?? 0);
+ *   }
+ * }
+ * ```
+ *
+ * The value is re-posted after every render, so a host has nothing to call
+ * when its value changes — but a host that overrides `updated()` must chain to
+ * `super.updated()`, or the value stops being posted. What a host must still
+ * do is fire the events: native `input` on every alteration and native
+ * `change` on commit, matching the control it behaves like.
+ *
+ * The analyzer does not follow members through a mixin, so a host documents
+ * the two it gains with `@attr name` and `@attr disabled` on its own class
+ * docblock, the way `craft-pane` documents `Paddable`'s `padding`.
+ */
+export const FormAssociated = <T extends Constructor<LitElement>>(Base: T) => {
+  class FormAssociatedElement extends Base {
+    static formAssociated = true;
+
+    #internals = this.attachInternals();
+
+    /** The value to restore on `form.reset()`, read once on first connect. */
+    #defaultValue: string | null = null;
+    #defaultValueRead = false;
+
+    @property({reflect: true}) name = '';
+    @property({type: Boolean, reflect: true}) disabled = false;
+
+    _formValue(): string | null {
+      return null;
+    }
+
+    // oxlint-disable-next-line no-unused-vars
+    _restoreFormValue(value: string | null): void {}
+
+    get form(): HTMLFormElement | null {
+      return this.#internals.form;
+    }
+
+    get validity(): ValidityState {
+      return this.#internals.validity;
+    }
+
+    get validationMessage(): string {
+      return this.#internals.validationMessage;
+    }
+
+    get willValidate(): boolean {
+      return this.#internals.willValidate;
+    }
+
+    checkValidity(): boolean {
+      return this.#internals.checkValidity();
+    }
+
+    reportValidity(): boolean {
+      return this.#internals.reportValidity();
+    }
+
+    override connectedCallback() {
+      super.connectedCallback();
+
+      // First connect only: a reconnect must not adopt the current value as
+      // the one a reset goes back to.
+      if (!this.#defaultValueRead) {
+        this.#defaultValueRead = true;
+        this.#defaultValue = this._formValue();
+      }
+
+      this.#internals.setFormValue(this._formValue());
+    }
+
+    protected override updated(changed: PropertyValues) {
+      super.updated(changed);
+      this.#internals.setFormValue(this._formValue());
+    }
+
+    /** Called when an ancestor `<fieldset disabled>` is toggled. */
+    formDisabledCallback(disabled: boolean) {
+      this.disabled = disabled;
+    }
+
+    formResetCallback() {
+      this._restoreFormValue(this.#defaultValue);
+    }
+
+    formStateRestoreCallback(state: string) {
+      this._restoreFormValue(state);
+    }
+  }
+
+  // Cast through named types only, so Lit's protected members stay out of
+  // consumers' declaration emit (TS4094) — same reason as `Paddable`.
+  return FormAssociatedElement as unknown as Constructor<FormAssociatedHost> &
+    T;
+};
diff --git a/packages/craftcms-ui/src/mixins/Paddable.test.ts b/packages/craftcms-ui/src/mixins/Paddable.test.ts
index 248fac7048b..9c10651806f 100644
--- a/packages/craftcms-ui/src/mixins/Paddable.test.ts
+++ b/packages/craftcms-ui/src/mixins/Paddable.test.ts
@@ -75,14 +75,16 @@ describe('resolvePadding', () => {
     expect(resolvePadding(value)).toBe('0');
   });
 
-  it.each([24, '24', '0.5'] as const)('reads %s as pixels', (value) => {
-    expect(resolvePadding(value)).toBe(`calc(${value}rem / 16)`);
-  });
-
-  it.each(['2rem', 'var(--my-spacing)', 'calc(1rem + 2px)'])(
-    'passes %s through verbatim',
+  /**
+   * The attribute is closed to arbitrary lengths. Ignoring them leaves the
+   * stylesheet's own default in place, rather than writing a value the design
+   * system does not define — consumers who need one set the component's
+   * padding custom properties instead.
+   */
+  it.each([24, '24', '0.5', '2rem', 'var(--my-spacing)', 'calc(1rem + 2px)'])(
+    'ignores %s, which is off the spacing scale',
     (value) => {
-      expect(resolvePadding(value)).toBe(value);
+      expect(resolvePadding(value)).toBeUndefined();
     }
   );
 
@@ -118,10 +120,10 @@ describe('Paddable with a default', () => {
   it('re-renders when the property changes', async () => {
     const element = await create<SinglePropertyHost>('test-single-padding');
 
-    element.padding = 24;
+    element.padding = 'xl';
     await element.updateComplete;
 
-    expect(written(element, '--_test-spacing')).toBe('calc(24rem / 16)');
+    expect(written(element, '--_test-spacing')).toBe('var(--c-spacing-xl)');
   });
 
   /** Removing the attribute has to clear the value, not strand the last one. */
diff --git a/packages/craftcms-ui/src/mixins/Paddable.ts b/packages/craftcms-ui/src/mixins/Paddable.ts
index bf1f8a6e33b..025d4a59202 100644
--- a/packages/craftcms-ui/src/mixins/Paddable.ts
+++ b/packages/craftcms-ui/src/mixins/Paddable.ts
@@ -17,13 +17,12 @@ export const SPACING_STEPS = ['sm', 'md', 'lg', 'xl'] as const;
 
 export type SpacingStep = (typeof SPACING_STEPS)[number];
 
-/** Everything the `padding` property accepts. */
-export type PaddingValue = SpacingStep | 'none' | string | number;
-
-/** Whether a value is a plain number (or a numeric string like `"12"`). */
-function isNumeric(value: PaddingValue): boolean {
-  return !isNaN(parseFloat(String(value))) && isFinite(Number(value));
-}
+/**
+ * Everything the `padding` property accepts: a step on the spacing scale, or
+ * zero. The attribute is deliberately closed to arbitrary lengths — reach for
+ * the component's own custom properties when you need a value off the scale.
+ */
+export type PaddingValue = SpacingStep | 'none' | '0' | 0;
 
 /**
  * Resolves a padding value to a CSS length.
@@ -33,15 +32,20 @@ function isNumeric(value: PaddingValue): boolean {
  *   bare `none` is not a valid length, so passing it through would drop the
  *   declaration and silently leave the default padding in place.
  * - `sm`/`md`/`lg`/`xl` map onto `--c-spacing-*`.
- * - A unitless number (or numeric string) is read as pixels.
- * - Anything else is passed through verbatim, so a consumer can hand over a
- *   token, a `calc()`, or any other CSS length.
  * - Nothing at all (`undefined`, `null`, or an empty attribute) resolves to
  *   `undefined`, which callers should treat as "write nothing and let the
  *   stylesheet's own fallback stand".
+ * - Anything else resolves to `undefined` as well. An arbitrary length is not
+ *   a spelling this attribute supports, and ignoring it leaves the
+ *   stylesheet's default in place rather than writing a value the design
+ *   system does not define. Set the component's padding custom properties
+ *   instead.
  */
 export function resolvePadding(
-  value: PaddingValue | null | undefined
+  // Wider than `PaddingValue` on purpose: this is the runtime boundary, and an
+  // attribute can carry any string at all. Rejecting what is off the scale is
+  // the function's job.
+  value: PaddingValue | string | number | null | undefined
 ): string | undefined {
   if (value === null || value === undefined || value === '') {
     return undefined;
@@ -51,15 +55,11 @@ export function resolvePadding(
     return '0';
   }
 
-  if (isNumeric(value)) {
-    return `calc(${value}rem / 16)`;
-  }
-
   if (SPACING_STEPS.includes(value as SpacingStep)) {
     return `var(--c-spacing-${value})`;
   }
 
-  return String(value);
+  return undefined;
 }
 
 /** How a host wires the shared `padding` behavior onto its own CSS. */
@@ -102,9 +102,10 @@ export interface PaddableHost {
 
 /**
  * Adds a declarative `padding` attribute to any Lit element: the consumer
- * writes `padding="md"` (or `0`, `none`, `24`, `2rem`, …) and the mixin
- * resolves it to a CSS length and hands it back keyed by the custom
- * properties the component nominated.
+ * writes `padding="md"` (or `0`/`none`) and the mixin resolves it to a CSS
+ * length and hands it back keyed by the custom properties the component
+ * nominated. Values off the spacing scale are ignored; a consumer who needs
+ * one sets the component's custom properties directly.
  *
  * The mixin deliberately carries only the behavior — the reactive property
  * and the value resolution. The custom property name, its fallback chain, and
diff --git a/packages/craftcms-ui/src/mixins/SsrChoiceGroupMixin.ts b/packages/craftcms-ui/src/mixins/SsrChoiceGroupMixin.ts
new file mode 100644
index 00000000000..ac7908fefb5
--- /dev/null
+++ b/packages/craftcms-ui/src/mixins/SsrChoiceGroupMixin.ts
@@ -0,0 +1,65 @@
+import type {LitElement, PropertyValues} from 'lit';
+
+// oxlint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = object> = new (...args: any[]) => T;
+
+/** The public Lion choice-group surface the mixin drives. */
+interface ChoiceGroupHost {
+  name: string;
+}
+
+/**
+ * Makes a Lion choice group (checkbox group, radio group) adopt its name from
+ * the server-rendered inputs it wraps. Lion syncs each registered child's name
+ * to the group's (`name || ''`), so a nameless group would strip the names the
+ * server wrote and break native posting.
+ *
+ * Adoption runs before `super.connectedCallback()` so the name is in place
+ * before any child registers, and again in `willUpdate` as a fallback for
+ * streaming parsing, where the element can connect before its children exist.
+ *
+ * Returns `Base`'s own type so the subclass keeps Lion's statics and member
+ * visibility; the mixin only adds lifecycle behavior. Pair it with
+ * `SsrChoiceInputMixin`, which does the equivalent job for the inputs.
+ */
+export const SsrChoiceGroupMixin = <
+  T extends Constructor<LitElement & ChoiceGroupHost>,
+>(
+  Base: T,
+  inputType: 'checkbox' | 'radio'
+): T => {
+  class SsrChoiceGroup extends Base {
+    private __ssrNameAdopted = false;
+
+    override connectedCallback() {
+      this.__adoptSlottedName();
+      super.connectedCallback();
+    }
+
+    protected override willUpdate(changedProperties: PropertyValues) {
+      this.__adoptSlottedName();
+      super.willUpdate(changedProperties);
+    }
+
+    private __adoptSlottedName() {
+      if (this.__ssrNameAdopted || this.name) {
+        return;
+      }
+
+      const input = this.querySelector<HTMLInputElement>(
+        `input[type="${inputType}"][name]`
+      );
+
+      if (!input) {
+        // Leave the flag unset so a later pass can still adopt once children
+        // have been parsed.
+        return;
+      }
+
+      this.__ssrNameAdopted = true;
+      this.name = input.name;
+    }
+  }
+
+  return SsrChoiceGroup as T;
+};
diff --git a/packages/craftcms-ui/src/stories/api/Factory.mdx b/packages/craftcms-ui/src/stories/api/Factory.mdx
new file mode 100644
index 00000000000..6e47ebeff0c
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/api/Factory.mdx
@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="JavaScript API/Factory" />
+
+# Factory
+
+The factory builds a component in JavaScript and hands back the element, with no markup and no jQuery.
+
+```js
+import {createSwitch} from '@craftcms/ui/factory';
+
+const toggle = createSwitch({
+  name: 'enabled',
+  label: 'Enabled',
+  on: true,
+  onChange: (on) => console.log(on),
+});
+
+container.append(toggle);
+```
+
+Every builder takes a single config object and returns the element. Nothing is inserted for you — append the result where it belongs. The one exception is `createCopyTextPrompt`, which is a dialog: it appends itself to `<body>` and opens.
+
+Each function is the client-side twin of a PHP component in `src/Cp/Components/`, so a control built here and one rendered by Twig produce the same element.
+
+## What is available
+
+| Function               | Returns                        | Config                 |
+| ---------------------- | ------------------------------ | ---------------------- |
+| `createSwitch`         | `<craft-switch>`               | `SwitchConfig`         |
+| `createTextInput`      | `<input class="text">`         | `TextInputConfig`      |
+| `createInputColor`     | `<craft-input-color>`          | `InputColorConfig`     |
+| `createInputPassword`  | `<craft-input-password>`       | `InputPasswordConfig`  |
+| `createSlidePicker`    | `<craft-slide-picker>`         | `SlidePickerConfig`    |
+| `createCopyTextPrompt` | `<craft-dialog>`, already open | `CopyTextPromptConfig` |
+
+Import them from `@craftcms/ui/factory`, or one at a time from `@craftcms/ui/factory/create-switch` and so on. Each config interface is exported alongside its function.
+
+## Form values
+
+The controls that carry a value are form-associated, so a `name` is all it takes to post one:
+
+```js
+const picker = createSlidePicker({name: 'columns', min: 1, max: 6, value: 3});
+form.append(picker);
+
+new FormData(form).get('columns'); // "3"
+```
+
+There is no hidden input behind them, and `form.reset()` puts back the value the control started with.
+
+## Not the whole legacy surface
+
+`createTextInput` returns a native `<input>` rather than a custom element, because that is what the rest of the CP's text inputs are built from. It renders markup only. The behaviour the legacy `Craft.ui.createTextInput` layered on top — the placeholder animation and characters-left counter from `Garnish.NiceText`, the password wrapper, the mobile autofocus suppression — stays in the legacy shim that wraps this function's result.
+
+Reach for [Utilities](?path=/docs/javascript-api-utilities--docs) for the smaller pieces the factory itself is built from, including `createButton`.
diff --git a/packages/craftcms-ui/src/stories/api/ReactiveControllers.mdx b/packages/craftcms-ui/src/stories/api/ReactiveControllers.mdx
new file mode 100644
index 00000000000..753fa813759
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/api/ReactiveControllers.mdx
@@ -0,0 +1,39 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="JavaScript API/Reactive Controllers" />
+
+# Reactive Controllers
+
+Lit [reactive controllers](https://lit.dev/docs/composition/controllers/) that components share. A controller attaches to a host in its constructor and rides the host's lifecycle from there.
+
+## LightDomController
+
+Re-renders the host when its light-DOM children change.
+
+A component that renders differently depending on what is slotted into it has a problem Lit does not solve on its own: slot content is not reactive state, so adding a child after the first render changes nothing. This controller watches the host's children and requests an update when they change.
+
+```js
+import {
+  LightDomController,
+  hasSlotted,
+} from '@craftcms/ui/controllers/LightDomController';
+
+class CraftThing extends LitElement {
+  #lightDom = new LightDomController(this);
+
+  render() {
+    return html`
+      ${hasSlotted(this, 'header') ? html`<div class="header"><slot name="header"></slot></div>` : nothing}
+      <slot></slot>
+    `;
+  }
+}
+```
+
+`hasSlotted(host, ...names)` reports whether any of the named slots have content. It checks **direct children only** — a `footer` nested deeper inside the subtree does not count, which is what keeps a card from lighting up its own chrome because something further down happened to use the same slot name.
+
+The default slot is matched by the empty string, the same way `HTMLElement.slot` reports it — `hasSlotted(this, '')`.
+
+The controller takes options for the cases the default does not cover: `onChange` to run something besides a re-render, `characterData` to also watch text changes, and `attributeFilter` to widen the attributes it watches. It always watches `slot`, because content moves between slots by having that attribute rewritten rather than by being added or removed.
+
+[Card](?path=/docs/components-card--docs), [Pane](?path=/docs/components-pane--docs), [Chip](?path=/docs/components-chip--docs), and [Action Item](?path=/docs/components-action-item--docs) all use it.
diff --git a/packages/craftcms-ui/src/stories/api/Services.mdx b/packages/craftcms-ui/src/stories/api/Services.mdx
new file mode 100644
index 00000000000..60d492ed6fe
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/api/Services.mdx
@@ -0,0 +1,62 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="JavaScript API/Services" />
+
+# Services
+
+Three stateful classes that sit behind the components rather than inside them. Each is plain data and logic with no rendering.
+
+## ConfigService
+
+A singleton holding the CP config payload, and the source of the URLs everything else builds on.
+
+```js
+import {ConfigService} from '@craftcms/ui';
+
+const config = ConfigService.getInstance();
+
+config.getCpUrl('entries');
+config.getActionUrl('users/session-info');
+config.get('someSetting', 'a fallback');
+```
+
+The page bootstrap calls `initialize()` with the payload; `getInstance()` never does it for you. Calling a URL helper before that throws a named error rather than letting an `undefined` base reach `new URL()` and surface as an opaque `TypeError` somewhere else.
+
+`all()`, `get()`, and `set()` reach the underlying values. `resetInstance()` exists for tests.
+
+## AssetIndexer
+
+Drives an asset indexing session: concurrent connections, a task queue, and state updates delivered as events.
+
+```js
+import {AssetIndexer} from '@craftcms/ui';
+
+const indexer = new AssetIndexer();
+
+indexer.on('change', ({sessions, currentSessionId, reviewSessionId}) => {
+  render(sessions);
+});
+indexer.on('error', ({message}) => console.error(message));
+indexer.on('complete', () => indexer.destroy());
+
+await indexer.startIndexing(params);
+```
+
+The methods are fire-and-forget — call one, then react to `change`, `error`, or `complete`. `startIndexing()` is the exception and returns a promise, so an immediate failure is catchable at the call site.
+
+`getSessions()`, `getCurrentSessionId()`, and `isProcessing()` read the current state. `stopSession()`, `getSessionOverview()`, and `finishSession()` drive a session through the rest of its life, and `destroy()` tears the whole thing down. `IndexingActions` holds the action paths it posts to.
+
+## Csrf
+
+Fetches and caches the CSRF token from the session-info endpoint.
+
+```js
+import {Csrf} from '@craftcms/ui/services/Csrf';
+
+const csrf = new Csrf();
+const token = await csrf.getToken();
+```
+
+`getToken()` refreshes on first use and returns the cached value after that. `refreshToken()` forces a fetch, and collapses concurrent calls into one request. `clearToken()` drops the cache so the next `getToken()` refetches — which is what to call after a response says the token expired.
+
+Unlike the other two, `Csrf` is not exported from the package root; import it from `@craftcms/ui/services/Csrf`.
diff --git a/packages/craftcms-ui/src/stories/api/Utilities.mdx b/packages/craftcms-ui/src/stories/api/Utilities.mdx
new file mode 100644
index 00000000000..1850aa1aa78
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/api/Utilities.mdx
@@ -0,0 +1,100 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="JavaScript API/Utilities" />
+
+# Utilities
+
+The helpers the components are built from. Most are exported from the package root:
+
+```js
+import {t, toHandle, escapeHtml} from '@craftcms/ui';
+```
+
+Anything not exported from the root is still reachable by its own path:
+
+```js
+import {emitInput, emitChange} from '@craftcms/ui/utilities/form-events';
+```
+
+## Translation
+
+`t()` looks a message up in the loaded translations and interpolates it. `setTranslations()` installs the store, which the CP bootstrap does for you.
+
+```js
+import {t} from '@craftcms/ui';
+
+t('Delete');
+t('{num, number} {num, plural, =1{entry} other{entries}}', {num: 3});
+```
+
+The pattern syntax is ICU-style, and `formatMessage()` exposes the formatter on its own if you need it without the lookup.
+
+## Strings
+
+`toHandle()` converts a label into a Craft handle, `toEnvVar()` into an environment-variable name, and `toUriFormat()` into a URI-friendly slug. `asciiString()` transliterates using the same character map the PHP side uses, so a handle generated in the browser matches one generated on the server.
+
+```js
+import {toHandle, toUriFormat} from '@craftcms/ui';
+
+toHandle('Blog Posts'); // blogPosts
+toUriFormat('Blog Posts'); // blog-posts
+```
+
+`capitalize()`, `rand()`, and the `asciiCharMap` the transliteration reads are exported too.
+
+## DOM
+
+`appendHeadHtml()` and `appendBodyHtml()` inject a string of HTML and return a disposer that removes exactly what they added, which is what makes them safe to call from a component that can be torn down.
+
+```js
+import {appendBodyHtml} from '@craftcms/ui';
+
+const dispose = appendBodyHtml(response.bodyHtml);
+// later
+dispose();
+```
+
+`serializeFormInputs()` mirrors jQuery's `.serialize()` — same treatment of unchecked checkboxes and disabled controls — and `serializeFormInputsAsObject()` returns an object instead, keeping PHP-style bracket names verbatim. `isVisible()` and `appendElementHtml()` round the module out.
+
+## Attributes and converters
+
+`attrs()` flattens a Yii/Craft server attributes object into something `v-bind` accepts, which is how server-rendered attributes reach a Vue-wrapped component.
+
+`converters.ts` holds the two Lit attribute converters the components share. `defaultTrueBoolean` is a boolean that is on unless it is explicitly `"false"` — Lit's built-in converter is presence-based and cannot express that. `jsonAttribute` parses a JSON attribute and falls back rather than throwing on the absent and empty cases.
+
+```js
+import {defaultTrueBoolean, jsonAttribute} from '@craftcms/ui';
+
+@property({converter: defaultTrueBoolean}) dismissible = true;
+@property({converter: jsonAttribute(() => [])}) presets = [];
+```
+
+## Form events
+
+The two native events a form control owes its consumers, dispatched from the host so `event.target` is the component rather than whatever input it wraps.
+
+```js
+import {emitInput, emitChange} from '@craftcms/ui/utilities/form-events';
+
+emitInput(this); // the value was altered
+emitChange(this); // the value was committed
+```
+
+## Icons
+
+`getIconUrl()` resolves an icon name against the CP's published icon assets. `setIconResolver()` replaces the resolution strategy wholesale, and `createUrlIconResolver()` builds one that maps names onto a base URL — the hook to reach for when icons are served from somewhere other than the CP.
+
+## The rest
+
+| Module             | What it is                                                                                                              |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `cookies`          | A cookie manager. `new Cookies(defaults)`, then `get`/`set`/`remove`.                                                   |
+| `create`           | `createButton`, `createSubmitButton`, `createPasteButton` — the button builders the factory and the legacy shims share. |
+| `format`           | `formatNumber()`, plus `cpHumanizer` for durations.                                                                     |
+| `escapeHtml`       | Escapes HTML special characters in a string.                                                                            |
+| `thumbnail-loader` | `ThumbnailLoader` and `ThumbnailWorker`, which fetch and swap element thumbnails.                                       |
+| `overlay-events`   | `wireOverlayLifecycleEvents()` — see below.                                                                             |
+| `overlay-position` | `viewportEscapingModifiers` — Popper modifiers that let a fixed-strategy overlay escape a clipping ancestor.            |
+| `api`              | `actionClient` and `apiClient`, the configured Axios instances for CP action requests and the Craft API.                |
+
+`wireOverlayLifecycleEvents(host)` is what gives [Dialog](?path=/docs/components-dialog--docs), [Popover](?path=/docs/components-popover--docs), and [Tooltip](?path=/docs/components-tooltip--docs) their four lifecycle events. It bridges Lion's `opened-changed` to `craft-show` and `craft-hide` as the state flips, then `craft-after-show` and `craft-after-hide` once the update settles. Call it once from a constructor to give an overlay component the same contract.
diff --git a/packages/craftcms-ui/src/stories/api/VueWrappers.mdx b/packages/craftcms-ui/src/stories/api/VueWrappers.mdx
new file mode 100644
index 00000000000..9a39fd6e71c
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/api/VueWrappers.mdx
@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="JavaScript API/Vue Wrappers" />
+
+# Vue Wrappers
+
+The components are web components, so they work in a Vue template as they are. The wrappers exist for the one thing that does not carry over: `v-model` on a Lion-based form control.
+
+```js
+import CraftInput from '@craftcms/ui/vue/CraftInput.vue';
+```
+
+```html
+<CraftInput v-model="title" :error="errors.title" />
+```
+
+## Why they are needed
+
+Lion holds a form control's value in a `modelValue` **property** and announces changes with a `model-value-changed` event. Vue's `v-model` on a custom element binds an attribute and listens for `update:modelValue`, so the two do not meet: the value never reaches the element, and a change never comes back.
+
+Each wrapper is a thin single-file component that does the bridging — binds `.modelValue` as a property, listens for `model-value-changed`, and writes the result back through `defineModel()`. It also forwards an `error` prop into the control's `feedback` slot, so validation messages render the way the design system expects.
+
+One subtlety they handle for you: Lion emits a `model-value-changed` on mount carrying the element's own default, before Vue's binding has settled. The wrappers ignore that one — `detail.initialize` marks it — because acting on it would clobber the bound value with an empty default the moment the component appeared.
+
+## What is wrapped
+
+Only the controls that need the bridge, seventeen in all:
+
+| Kind    | Components                                                                                                                                                                                             |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Value   | `CraftInput`, `CraftInputColor`, `CraftInputHandle`, `CraftInputMoney`, `CraftInputPassword`, `CraftTextarea`, `CraftSelect`, `CraftSelectRich`, `CraftCombobox`, `CraftInputFile`, `CraftSelectColor` |
+| Checked | `CraftSwitch`, `CraftCheckbox`                                                                                                                                                                         |
+| Group   | `CraftCheckboxGroup`, `CraftPermissionTree`, `CraftRadioGroup`                                                                                                                                         |
+| Chrome  | `CraftField`                                                                                                                                                                                           |
+
+Everything else — buttons, chips, cards, menus, overlays — has no value to bind, so there is no wrapper and none is needed. Use the custom element directly.
+
+## Types for the rest
+
+Alongside the wrappers, `craft-elements.d.ts` declares every `craft-*` element to Vue, so templates get type-checking and autocomplete on elements used directly:
+
+```html
+<craft-button variant="accent" @click="save">Save</craft-button>
+```
+
+Without it, Vue treats an unknown custom element as untyped and a misspelled attribute passes silently.
+
+## Generated, not written
+
+Both the wrappers and the type declarations come out of `scripts/generate-vue-wrappers.js`, which reads a list of components and their slots and writes `dist/vue/`. Adding a control to that list is how a new wrapper appears; editing a generated file by hand does not survive the next run.
+
+```sh
+node scripts/generate-vue-wrappers.js
+```
+
+The wrappers bridge `model-value-changed` because that is what Lion's form system speaks internally. Outside Vue, prefer the native `input` and `change` events the controls emit — see [Combobox](?path=/docs/form-controls-select-controls-combobox--docs) for the distinction.
diff --git a/packages/craftcms-ui/src/stories/getting-started/Installation.mdx b/packages/craftcms-ui/src/stories/getting-started/Installation.mdx
new file mode 100644
index 00000000000..62813764027
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/getting-started/Installation.mdx
@@ -0,0 +1,105 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Installation" />
+
+# Installation
+
+## In the control panel
+
+Nothing to install.
+The CP already loads the whole library, so a Twig template or a Vue page in a plugin can use any element on this site directly:
+
+```twig
+<craft-callout variant="warning">
+  This section has no entry types.
+</craft-callout>
+```
+
+From PHP, prefer the component classes in `src/Cp/Components/` over writing the tag by hand — they carry typed setters and handle slot content:
+
+```php
+use CraftCms\Cms\Cp\Components\Button;
+
+echo Button::make()
+    ->variant('primary')
+    ->icon('plus')
+    ->label(Craft::t('app', 'New entry'));
+```
+
+## Outside the control panel
+
+Install the package and its two peers:
+
+```sh
+npm install @craftcms/ui lit @lion/ui
+```
+
+Import a component for its side effect — importing registers the custom element, so the tag works from that point on:
+
+```js
+import '@craftcms/ui/components/button/button.js';
+```
+
+```html
+<craft-button variant="primary">Save</craft-button>
+```
+
+Import the whole library when you would rather not track individual paths. It registers every element:
+
+```js
+import '@craftcms/ui';
+```
+
+The named exports are the classes, for when you need the type or want to extend one:
+
+```js
+import {CraftButton} from '@craftcms/ui';
+```
+
+## Styles
+
+The components carry their own styles in shadow DOM, so they look right without a stylesheet.
+What they do not carry is the token layer that gives them their colours, spacing, and type — those are custom properties inherited from the page, so they have to be defined once at the root:
+
+```js
+import '@craftcms/ui/styles/cp.css';
+```
+
+Skip it and every component still renders, using whatever the fallbacks in its own stylesheet say. That is a working page, not a Craft-looking one.
+
+## Vue
+
+Custom elements pass straight through Vue's compiler as long as it knows not to resolve them as Vue components. Any tag with a hyphen is treated that way, so `<craft-button>` works with no configuration.
+
+Bind rich values as properties with `.prop`, and listen for events with `@`:
+
+```vue
+<craft-select-rich
+  :label="label"
+  .options="options"
+  @model-value-changed="onChange"
+/>
+```
+
+Typed wrappers are generated for the whole library if you would rather have Vue's own prop and event checking:
+
+```js
+import CraftButton from '@craftcms/ui/vue/button.js';
+```
+
+## TypeScript
+
+Every component augments `HTMLElementTagNameMap`, so `document.querySelector` is typed once the component is imported:
+
+```ts
+// CraftButton, not HTMLElement
+const button = document.querySelector('craft-button');
+```
+
+The package also ships its [custom elements manifest](https://github.com/webcomponents/custom-elements-manifest), which editors read for completion and hover documentation inside markup:
+
+```json
+{
+  "html.customData": ["./node_modules/@craftcms/ui/dist/custom-elements.json"]
+}
+```
diff --git a/packages/craftcms-ui/src/stories/getting-started/Introduction.mdx b/packages/craftcms-ui/src/stories/getting-started/Introduction.mdx
new file mode 100644
index 00000000000..2a39b708d8c
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/getting-started/Introduction.mdx
@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Introduction" />
+
+# Craft UI
+
+`@craftcms/ui` is the component library behind the Craft CMS control panel.
+Every element in it is a standard custom element built on [Lit](https://lit.dev), so it works in any page that can run JavaScript — a Craft plugin, a module's own CP section, or an application that has nothing to do with Craft.
+
+```html
+<craft-button variant="primary" icon="plus">New entry</craft-button>
+```
+
+## What is in here
+
+The sidebar has four groups:
+
+- **Components** — everything that is not a form control: buttons, cards, panes, menus, overlays, and the smaller pieces they are built from.
+- **Form Controls** — anything that collects a value, split into choice controls, select controls, and text controls.
+- **Tokens** — the design tokens the components are styled from: [Color Palette](?path=/docs/tokens-color-palette--docs), [Variants & Appearances](?path=/docs/tokens-variants-appearances--docs), and the [Colorable](?path=/docs/tokens-colorable--docs) contract that ties a colour to a component.
+- **Getting Started** — this page, [Installation](?path=/docs/getting-started-installation--docs), and [Theming](?path=/docs/getting-started-theming--docs).
+
+Every component page is generated from the component itself.
+The properties, attributes, slots, events, CSS parts, and CSS custom properties in each "Properties" table come from the [custom elements manifest](https://github.com/webcomponents/custom-elements-manifest), which is built from the source, so a table can never drift from the element it documents.
+
+## Why custom elements
+
+The control panel renders from two directions: Twig and PHP on the server, Vue and Inertia in the browser.
+A custom element is the one component model both can use.
+The server writes `<craft-button>` into a template and the browser upgrades it in place; Vue renders the same tag and treats it as a native element.
+
+That has two consequences worth knowing before you start:
+
+**Attributes are the API.** Anything the server needs to set is an attribute, so it can be written as markup. Rich values — arrays, objects, functions — are properties instead, and the pages say so where it matters.
+
+**Server-rendered markup is adopted, not replaced.** A control that arrives with its `<input>` already in place keeps that input's `name`, `value`, and `checked` when the component upgrades. A page rendered checked stays checked.
+
+## Conventions
+
+A few things hold across every component, so they are stated once here rather than on each page:
+
+- **Sizes** are `small`, `medium`, and `large`, and mean the same thing everywhere.
+- **Booleans** are ordinary HTML boolean attributes: absent is false, present is true. The handful that default to _on_ are documented as such and read `="false"` to turn off.
+- **Nothing is focusable unless it is a control.** Containers like [Card](?path=/docs/components-card--docs) and [Chip](?path=/docs/components-chip--docs) take no focus of their own; the content you put in them carries its own semantics.
+- **Labels are your responsibility.** Components will not invent an accessible name from context, and several of them warn in the console when they cannot find one.
+
+## Where to start
+
+If you are adding a component to a page, go to [Installation](?path=/docs/getting-started-installation--docs).
+If you are making one match a site's palette, go to [Theming](?path=/docs/getting-started-theming--docs).
+If you are looking for the right component, the sidebar is grouped by what things do rather than what they are called.
+If you are building a control in JavaScript rather than markup, go to [Factory](?path=/docs/javascript-api-factory--docs).
diff --git a/packages/craftcms-ui/src/stories/getting-started/Theming.mdx b/packages/craftcms-ui/src/stories/getting-started/Theming.mdx
new file mode 100644
index 00000000000..19bf621eaa9
--- /dev/null
+++ b/packages/craftcms-ui/src/stories/getting-started/Theming.mdx
@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Theming" />
+
+# Theming
+
+Components style themselves from CSS custom properties, and custom properties cross the shadow boundary.
+That is the whole mechanism: you never write a selector that reaches inside a component, you change the value it reads.
+
+There are three levels to reach for, in order.
+
+## 1. The palette
+
+Under everything is a palette of raw colours — `--color-red-500`, `--color-slate-200`, and so on across the ramp.
+These are the only place literal colours are written.
+
+Redefining one retunes every component that ends up reading it, which makes it the right lever for a brand colour and the wrong one for a one-off:
+
+```css
+:root {
+  --color-blue-500: #0b5fff;
+}
+```
+
+## 2. The tokens
+
+Above the palette sit the `--c-*` tokens, which name a _role_ rather than a colour: `--c-surface-raised`, `--c-text-quiet`, `--c-color-focus-outline`, `--c-spacing-md`, `--c-text-sm`.
+Components are authored against these, never against the palette directly.
+
+Change a token to move every component that plays that role:
+
+```css
+:root {
+  --c-surface-raised: var(--color-slate-50);
+  --c-color-focus-outline: var(--color-blue-500);
+}
+```
+
+## 3. A component's own properties
+
+Each component exposes its own `--c-<component>-*` properties for the things only it has — `--c-card-radius`, `--c-chip-height`, `--c-pane-background`.
+They are listed in the "Properties" table on each component's page.
+
+Set them on the element, or on any ancestor, since they inherit:
+
+```css
+craft-card {
+  --c-card-radius: 0;
+  --c-card-padding-block: var(--c-spacing-lg);
+}
+```
+
+Reach for these last. If two components need the same change, the token above them is the better place to make it.
+
+## Dark mode
+
+The dark palette is applied by `data-theme="dark"` on an ancestor — usually `<html>`:
+
+```html
+<html data-theme="dark"></html>
+```
+
+That redefines the palette, and because tokens are defined in terms of the palette, everything above updates with it.
+This is why authoring against tokens matters: a component that hard-codes `#fff` stays white in the dark theme, while one that reads `--c-surface-raised` follows.
+
+## Colouring one component
+
+Colour is a separate axis from theme, and it works through `data-color`:
+
+```html
+<craft-badge fill="emerald">Live</craft-badge>
+<craft-chip data-color="violet">Draft</craft-chip>
+```
+
+Setting it rescopes the generic `--c-color-*` tokens to that colour's group, so the component's surface, border, and text all move together and stay legible against each other.
+[Colorable](?path=/docs/tokens-colorable--docs) covers the contract, and [Color Palette](?path=/docs/tokens-color-palette--docs) shows the palette.
+
+For a semantic state rather than a specific colour, use `variant` — `neutral`, `success`, `warning`, `danger`, `info` — paired with an `appearance` for how loudly it should read.
+[Variants & Appearances](?path=/docs/tokens-variants-appearances--docs) covers both.
+
+## What not to do
+
+**Do not style into a component with `::part` when a custom property exists.** Parts are a much narrower contract: a property is a value the component agreed to read, while a part is an element it happens to render. Properties are listed first on every page for that reason.
+
+**Do not set `!important` on a token.** Components layer their own fallbacks with `var(--c-thing, <default>)`, and `!important` on the outer value defeats the per-component overrides above.
+
+**Do not rely on a component's internal class names.** They are inside shadow DOM, they are not API, and they change.
diff --git a/packages/craftcms-ui/src/styles/a11y-error.styles.ts b/packages/craftcms-ui/src/styles/a11y-error.styles.ts
new file mode 100644
index 00000000000..2cf161229a0
--- /dev/null
+++ b/packages/craftcms-ui/src/styles/a11y-error.styles.ts
@@ -0,0 +1,31 @@
+import {css} from 'lit';
+
+/**
+ * Marks a component that has been used in a way assistive technology cannot
+ * present — a button with no accessible name, a control nested inside another
+ * control.
+ *
+ * Deliberately loud. These are mistakes to fix rather than states to handle,
+ * and the ones that matter are invisible to a sighted developer testing with a
+ * mouse, so the component says so where it went wrong.
+ */
+export default css`
+  .a11y-error {
+    position: relative;
+    outline: 2px solid var(--c-color-danger-border-normal) !important;
+    background-color: rgba(255, 0, 0, 0.1) !important;
+
+    &:after {
+      content: '!';
+      position: absolute;
+      display: inline-flex;
+      font-size: calc(11rem / 16);
+      padding: 0.125em 0.5em 0.25em;
+      inset-block-start: -2px;
+      inset-inline-start: 0;
+      background: var(--c-color-danger-bg-emphasis);
+      color: white;
+      transform: translateX(-100%);
+    }
+  }
+`;
diff --git a/packages/craftcms-ui/src/styles/shared/tokens.css b/packages/craftcms-ui/src/styles/shared/tokens.css
index 405069ad04d..1c9373a56c8 100644
--- a/packages/craftcms-ui/src/styles/shared/tokens.css
+++ b/packages/craftcms-ui/src/styles/shared/tokens.css
@@ -114,6 +114,15 @@
   --c-status-disabled-text: var(--color-slate-600);
   --c-status-disabled-border: var(--color-slate-600);
 
+  /*
+    Lion reads this for the label, help text, and value of a disabled field,
+    and falls back to its own #767676 — which is 4.09:1 on our default surface,
+    under the 4.5:1 a disabled field's help text still has to meet to be read.
+    Pointing it at the token above puts it at 5.05:1, the same as the enabled
+    help text.
+  */
+  --disabled-text-color: var(--c-status-disabled-text);
+
   /**
  Static colors
   */
diff --git a/packages/craftcms-ui/src/utilities/converters.test.ts b/packages/craftcms-ui/src/utilities/converters.test.ts
new file mode 100644
index 00000000000..bd86b0d6ed1
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/converters.test.ts
@@ -0,0 +1,56 @@
+import {describe, expect, test} from 'vite-plus/test';
+
+import {defaultTrueBoolean, jsonAttribute} from './converters';
+
+describe('defaultTrueBoolean', () => {
+  test('is on when the attribute is absent', () => {
+    expect(defaultTrueBoolean.fromAttribute!(null, Boolean)).toBe(true);
+  });
+
+  test('is on when the attribute is present but empty', () => {
+    expect(defaultTrueBoolean.fromAttribute!('', Boolean)).toBe(true);
+  });
+
+  test('is off only for the literal string "false"', () => {
+    expect(defaultTrueBoolean.fromAttribute!('false', Boolean)).toBe(false);
+    expect(defaultTrueBoolean.fromAttribute!('0', Boolean)).toBe(true);
+    expect(defaultTrueBoolean.fromAttribute!('no', Boolean)).toBe(true);
+  });
+
+  test('serialises as a string both ways, so it survives a round trip', () => {
+    expect(defaultTrueBoolean.toAttribute!(false, Boolean)).toBe('false');
+    expect(
+      defaultTrueBoolean.fromAttribute!(
+        defaultTrueBoolean.toAttribute!(false, Boolean) as string,
+        Boolean
+      )
+    ).toBe(false);
+  });
+});
+
+describe('jsonAttribute', () => {
+  const converter = jsonAttribute<string[]>(() => []);
+
+  test('parses a JSON attribute', () => {
+    expect(converter.fromAttribute!('["a","b"]', Array)).toEqual(['a', 'b']);
+  });
+
+  test('falls back for an absent attribute', () => {
+    expect(converter.fromAttribute!(null, Array)).toEqual([]);
+  });
+
+  test('falls back for an empty attribute rather than throwing', () => {
+    expect(() => converter.fromAttribute!('', Array)).not.toThrow();
+    expect(converter.fromAttribute!('', Array)).toEqual([]);
+  });
+
+  test('gives each host its own fallback instance', () => {
+    const first = converter.fromAttribute!(null, Array) as string[];
+    first.push('mutated');
+    expect(converter.fromAttribute!(null, Array)).toEqual([]);
+  });
+
+  test('serialises back to JSON', () => {
+    expect(converter.toAttribute!(['a'], Array)).toBe('["a"]');
+  });
+});
diff --git a/packages/craftcms-ui/src/utilities/converters.ts b/packages/craftcms-ui/src/utilities/converters.ts
new file mode 100644
index 00000000000..8a0a2487ee0
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/converters.ts
@@ -0,0 +1,39 @@
+import type {ComplexAttributeConverter} from 'lit';
+
+/**
+ * A boolean attribute that is on unless it is explicitly turned off.
+ *
+ * Lit's built-in boolean converter is presence-based: the attribute means
+ * true when present and false when absent, so an option that should default
+ * to on can never be switched off from markup. This converter inverts that —
+ * only the literal string `"false"` is off, and every other value (including
+ * an empty attribute) is on.
+ *
+ * Reach for it when the server renders the attribute as a config flag rather
+ * than an HTML boolean, as `show-date="false"` does. A property that is off by
+ * default wants Lit's `{type: Boolean}` instead, which keeps the ordinary HTML
+ * semantics consumers expect.
+ *
+ * It serialises back as `"true"`/`"false"` rather than as a bare attribute, so
+ * a reflected value survives a round trip through the DOM.
+ */
+export const defaultTrueBoolean: ComplexAttributeConverter<boolean> = {
+  fromAttribute: (value: string | null): boolean => value !== 'false',
+  toAttribute: (value: boolean): string => String(value),
+};
+
+/**
+ * A JSON-valued attribute that falls back rather than throwing.
+ *
+ * An absent attribute arrives as `null` and an empty one as `''`. Neither is
+ * valid JSON, so both have to be caught before they reach `JSON.parse` —
+ * `disabled-time-ranges=""` would otherwise throw during the element's first
+ * update, before it ever renders.
+ */
+export const jsonAttribute = <T>(
+  fallback: () => T
+): ComplexAttributeConverter<T> => ({
+  fromAttribute: (value: string | null): T =>
+    value ? (JSON.parse(value) as T) : fallback(),
+  toAttribute: (value: T): string => JSON.stringify(value),
+});
diff --git a/packages/craftcms-ui/src/utilities/form-events.test.ts b/packages/craftcms-ui/src/utilities/form-events.test.ts
new file mode 100644
index 00000000000..e9594851078
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/form-events.test.ts
@@ -0,0 +1,28 @@
+import {beforeEach, describe, expect, it, vi} from 'vite-plus/test';
+import {emitChange, emitInput} from './form-events.js';
+
+let host: HTMLElement;
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  host = document.createElement('div');
+  document.body.append(host);
+});
+
+describe('form events', () => {
+  it.each([
+    ['input', emitInput],
+    ['change', emitChange],
+  ])('emits a composed, bubbling %s from the host', (type, emit) => {
+    const seen = vi.fn();
+    document.body.addEventListener(type, seen);
+
+    emit(host);
+
+    expect(seen).toHaveBeenCalledTimes(1);
+    const event = seen.mock.calls[0]![0] as Event;
+    expect(event.target).toBe(host);
+    expect(event.bubbles).toBe(true);
+    expect(event.composed).toBe(true);
+  });
+});
diff --git a/packages/craftcms-ui/src/utilities/form-events.ts b/packages/craftcms-ui/src/utilities/form-events.ts
new file mode 100644
index 00000000000..cf484ceffb0
--- /dev/null
+++ b/packages/craftcms-ui/src/utilities/form-events.ts
@@ -0,0 +1,20 @@
+/**
+ * The two native events a form control owes its consumers, dispatched from the
+ * host so `event.target` is the component rather than whatever input it wraps.
+ *
+ * Both are composed, so they cross a shadow boundary the way the platform's own
+ * `input` does, and a form-level listener sees them from anywhere in the tree.
+ */
+
+/** Emitted on every alteration to the value, while it is still being made. */
+export const emitInput = (host: HTMLElement): void => {
+  host.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
+};
+
+/**
+ * Emitted when an alteration is committed — a selection, a blur after typing.
+ * For a control whose every step is a commit, it follows each `emitInput`.
+ */
+export const emitChange = (host: HTMLElement): void => {
+  host.dispatchEvent(new Event('change', {bubbles: true, composed: true}));
+};
diff --git a/packages/craftcms-ui/test/element-internals.setup.ts b/packages/craftcms-ui/test/element-internals.setup.ts
new file mode 100644
index 00000000000..2fb359e1bc3
--- /dev/null
+++ b/packages/craftcms-ui/test/element-internals.setup.ts
@@ -0,0 +1,5 @@
+// happy-dom ships no `ElementInternals` — not in any release — so a
+// form-associated custom element cannot even be constructed there. This
+// polyfill supplies the platform feature so the form-control components can be
+// unit-tested; browsers have shipped the real thing since March 2023.
+import 'element-internals-polyfill';
diff --git a/packages/craftcms-ui/vitest.config.ts b/packages/craftcms-ui/vitest.config.ts
index 95d158a9ed6..68066b46630 100644
--- a/packages/craftcms-ui/vitest.config.ts
+++ b/packages/craftcms-ui/vitest.config.ts
@@ -43,6 +43,7 @@ export default defineConfig({
           name: 'components',
           root: './src/components',
           environment: 'happy-dom',
+          setupFiles: ['../../test/element-internals.setup.ts'],
         },
       },
       {
@@ -53,6 +54,17 @@ export default defineConfig({
           name: 'mixins',
           root: './src/mixins',
           environment: 'happy-dom',
+          setupFiles: ['../../test/element-internals.setup.ts'],
+        },
+      },
+      {
+        resolve: {
+          tsconfigPaths: true,
+        },
+        test: {
+          name: 'controllers',
+          root: './src/controllers',
+          environment: 'happy-dom',
         },
       },
       {
diff --git a/resources/js/common/form/CheckboxGroupItem.vue b/resources/js/common/form/CheckboxGroupItem.vue
index c9ffefc9082..5b5aab34e09 100644
--- a/resources/js/common/form/CheckboxGroupItem.vue
+++ b/resources/js/common/form/CheckboxGroupItem.vue
@@ -61,7 +61,7 @@
     >
       <craft-reorder-button
         :position="position"
-        @reorder="
+        @craft-reorder="
           (e: CustomEvent<{direction: 'up' | 'down'}>) =>
             emit(
               'reorder',
diff --git a/resources/js/modules/component-select/component-select.ts b/resources/js/modules/component-select/component-select.ts
index 22febb7a83a..ed0d373b37f 100644
--- a/resources/js/modules/component-select/component-select.ts
+++ b/resources/js/modules/component-select/component-select.ts
@@ -912,7 +912,7 @@ export class ComponentSelect extends Base<ComponentSelectSettings> {
     if (this.#list?.classList.contains('inline-chips')) {
       btn.setAttribute('orientation', 'horizontal');
     }
-    btn.addEventListener('reorder', (event: Event) => {
+    btn.addEventListener('craft-reorder', (event: Event) => {
       if (!(event instanceof CustomEvent)) {
         return;
       }
diff --git a/resources/js/modules/editable-table/editable-table.ts b/resources/js/modules/editable-table/editable-table.ts
index 6ab63b770eb..8cb5915b858 100644
--- a/resources/js/modules/editable-table/editable-table.ts
+++ b/resources/js/modules/editable-table/editable-table.ts
@@ -920,7 +920,7 @@ export class Row extends Base {
         this.addListener($input, 'mousedown', 'ignoreNextTextareaFocus');
         this.addListener(
           this.$tr.find('craft-reorder-button'),
-          'reorder',
+          'craft-reorder',
           'onReorder'
         );
 
diff --git a/resources/js/modules/elements/components/BulkActionsBar.vue b/resources/js/modules/elements/components/BulkActionsBar.vue
index 0014695b71a..27412688663 100644
--- a/resources/js/modules/elements/components/BulkActionsBar.vue
+++ b/resources/js/modules/elements/components/BulkActionsBar.vue
@@ -157,7 +157,7 @@
   );
 
   /**
-   * `craft-action-item` bubbles `action:change-state` through its lifecycle. A
+   * `craft-action-item` bubbles `craft-state-change` through its lifecycle. A
    * successful `http` action means the selection was acted on, so refresh the
    * table + clear selection. (Other states drive the item's own spinner/feedback.)
    */
@@ -199,7 +199,7 @@
   <div
     class="bulk-actions-bar"
     v-if="selectedCount > 0"
-    @action:change-state="onChangeState"
+    @craft-state-change="onChangeState"
   >
     <div class="bulk-actions-bar__selection">
       <Text
diff --git a/resources/js/modules/elements/components/DataTable.vue b/resources/js/modules/elements/components/DataTable.vue
index e34727947e8..e8f3175b3f2 100644
--- a/resources/js/modules/elements/components/DataTable.vue
+++ b/resources/js/modules/elements/components/DataTable.vue
@@ -349,7 +349,7 @@
             <td>
               <div>
                 <craft-reorder-button
-                  @reorder="
+                  @craft-reorder="
                     (e: CustomEvent<{direction: 'up' | 'down'}>) =>
                       emit(
                         'reorder',
diff --git a/resources/js/modules/entry-types/components/EntryTypeSelect.vue b/resources/js/modules/entry-types/components/EntryTypeSelect.vue
index c54c498d8fa..2452a39a3d1 100644
--- a/resources/js/modules/entry-types/components/EntryTypeSelect.vue
+++ b/resources/js/modules/entry-types/components/EntryTypeSelect.vue
@@ -308,7 +308,7 @@
               v-if="!readOnly"
               variant="inherit"
               :position="getRowPosition(index)"
-              @reorder="
+              @craft-reorder="
                 (e: CustomEvent<{direction: 'up' | 'down'}>) =>
                   reorder(
                     index,
diff --git a/resources/js/modules/field-layout-designer/element.ts b/resources/js/modules/field-layout-designer/element.ts
index c7805e3b370..5f31df8be50 100644
--- a/resources/js/modules/field-layout-designer/element.ts
+++ b/resources/js/modules/field-layout-designer/element.ts
@@ -107,14 +107,11 @@ export class Element extends Base {
       widthSlider.setAttribute('value', `${this.config.width || 100}`);
 
       if (this.tab.designer.settings!.readOnly) {
-        widthSlider.setAttribute('read-only', '');
+        widthSlider.setAttribute('readonly', '');
       }
 
-      widthSlider.addEventListener('value-change', (event: Event) => {
-        if (!(event instanceof CustomEvent)) {
-          return;
-        }
-        const width = Number(event.detail?.value);
+      widthSlider.addEventListener('change', () => {
+        const width = widthSlider.value;
         this.updateConfig((config: any) => {
           config.width = width;
           return config;
diff --git a/resources/js/modules/forms/FormNodeList.vue b/resources/js/modules/forms/FormNodeList.vue
index 252621f6a0c..33e21ddff75 100644
--- a/resources/js/modules/forms/FormNodeList.vue
+++ b/resources/js/modules/forms/FormNodeList.vue
@@ -78,7 +78,7 @@
 </script>
 
 <template>
-  <craft-tabs v-if="tabs.length > 1" @selected-changed="onSelectionChanged">
+  <craft-tabs v-if="tabs.length > 1" @craft-tab-show="onSelectionChanged">
     <craft-tab
       v-for="tab in tabs"
       slot="tab"
diff --git a/resources/js/modules/forms/FormRenderer.test.ts b/resources/js/modules/forms/FormRenderer.test.ts
index 453752e8f4f..39202805aba 100644
--- a/resources/js/modules/forms/FormRenderer.test.ts
+++ b/resources/js/modules/forms/FormRenderer.test.ts
@@ -2874,7 +2874,7 @@ describe('FormRenderer', () => {
       'Expected the second Matrix reorder button.'
     );
     reorder.dispatchEvent(
-      new CustomEvent('reorder', {
+      new CustomEvent('craft-reorder', {
         bubbles: true,
         composed: true,
         detail: {direction: 'up'},
diff --git a/resources/js/modules/forms/MatrixControl.vue b/resources/js/modules/forms/MatrixControl.vue
index 9d026b0bd63..6d48a0e8c1c 100644
--- a/resources/js/modules/forms/MatrixControl.vue
+++ b/resources/js/modules/forms/MatrixControl.vue
@@ -186,7 +186,7 @@
                 value.sortOrder.length <= (control.props.minEntries ?? 0)
               "
               data-form-matrix-remove
-              :accessible-name="
+              :aria-label="
                 t('Remove {type}', {type: entryType(uid)?.label ?? uid})
               "
             />
diff --git a/resources/js/modules/grouped-entry-type-manager/grouped-entry-type-manager.ts b/resources/js/modules/grouped-entry-type-manager/grouped-entry-type-manager.ts
index f8f35e970b5..55807883e39 100644
--- a/resources/js/modules/grouped-entry-type-manager/grouped-entry-type-manager.ts
+++ b/resources/js/modules/grouped-entry-type-manager/grouped-entry-type-manager.ts
@@ -835,7 +835,7 @@ export class Group extends Base {
     ) as CraftReorderButton;
     const container = this.container;
     btn.setAttribute('orientation', 'horizontal');
-    btn.addEventListener('reorder', (event: Event) => {
+    btn.addEventListener('craft-reorder', (event: Event) => {
       // SAFETY: craft-reorder-button emits this registered detail contract.
       const {direction} = (event as CustomEvent<{direction: ReorderDirection}>)
         .detail;
diff --git a/resources/js/modules/matrix/matrix-input.ce.ts b/resources/js/modules/matrix/matrix-input.ce.ts
index ef1950961e1..f0d218cdac6 100644
--- a/resources/js/modules/matrix/matrix-input.ce.ts
+++ b/resources/js/modules/matrix/matrix-input.ce.ts
@@ -28,7 +28,7 @@ export default class CraftMatrixInput extends ControllerElement<MatrixInput> {
     this.listener = new AbortController();
     const {signal} = this.listener;
     this.addEventListener('click', this.onClick, {signal});
-    this.addEventListener('reorder', this.onReorder, {signal});
+    this.addEventListener('craft-reorder', this.onReorder, {signal});
     this.addEventListener('entrySortDragStop', this.changed, {signal});
   }
 
@@ -165,7 +165,7 @@ export default class CraftMatrixInput extends ControllerElement<MatrixInput> {
     const remove = document.createElement('craft-button');
     remove.dataset.formMatrixRemove = '';
     remove.setAttribute('icon', 'trash');
-    remove.setAttribute('accessible-name', t('Remove {type}', {type: label}));
+    remove.setAttribute('aria-label', t('Remove {type}', {type: label}));
     actions.append(reorder, remove);
 
     return actions;
diff --git a/resources/js/modules/navigation/components/cp-global-sidebar.ts b/resources/js/modules/navigation/components/cp-global-sidebar.ts
index 29d004ac562..e68f6f21ae2 100644
--- a/resources/js/modules/navigation/components/cp-global-sidebar.ts
+++ b/resources/js/modules/navigation/components/cp-global-sidebar.ts
@@ -18,8 +18,8 @@ class CpGlobalSidebar extends LitElement {
     super.connectedCallback();
 
     if (this.trigger) {
-      this.trigger.addEventListener('open', this.expand.bind(this));
-      this.trigger.addEventListener('close', this.collapse.bind(this));
+      this.trigger.addEventListener('craft-show', this.expand.bind(this));
+      this.trigger.addEventListener('craft-hide', this.collapse.bind(this));
     }
 
     if (this.state === 'expanded') {
@@ -33,8 +33,8 @@ class CpGlobalSidebar extends LitElement {
     super.disconnectedCallback();
 
     if (this.trigger) {
-      this.trigger.removeEventListener('open', this.expand.bind(this));
-      this.trigger.removeEventListener('close', this.collapse.bind(this));
+      this.trigger.removeEventListener('craft-show', this.expand.bind(this));
+      this.trigger.removeEventListener('craft-hide', this.collapse.bind(this));
     }
 
     this.state = 'expanded';
diff --git a/resources/js/modules/plugin-manager/components/PluginsList.vue b/resources/js/modules/plugin-manager/components/PluginsList.vue
index 553334c496c..a80a0b2240f 100644
--- a/resources/js/modules/plugin-manager/components/PluginsList.vue
+++ b/resources/js/modules/plugin-manager/components/PluginsList.vue
@@ -89,7 +89,7 @@
 
 <template>
   <craft-pane appearance="raised" padding="0">
-    <AdminTable :table="table" @action:change-state="handleStateChange">
+    <AdminTable :table="table" @craft-state-change="handleStateChange">
       <template #empty-row>
         <Empty
           icon="plugin"
diff --git a/resources/js/modules/sortable-checkbox-select/sortable-checkbox-select.ts b/resources/js/modules/sortable-checkbox-select/sortable-checkbox-select.ts
index f3e16297104..47a7cc68fe2 100644
--- a/resources/js/modules/sortable-checkbox-select/sortable-checkbox-select.ts
+++ b/resources/js/modules/sortable-checkbox-select/sortable-checkbox-select.ts
@@ -296,7 +296,7 @@ export class Item extends Base {
 
     // Always-present drag handle + Move up/down menu, before the checkbox.
     this.reorderBtn = document.createElement('craft-reorder-button');
-    this.reorderBtn.addEventListener('reorder', (event: Event) => {
+    this.reorderBtn.addEventListener('craft-reorder', (event: Event) => {
       if (!(event instanceof CustomEvent)) {
         return;
       }
diff --git a/resources/js/pages/users/Addresses.vue b/resources/js/pages/users/Addresses.vue
index 2134eef715a..bee104495fb 100644
--- a/resources/js/pages/users/Addresses.vue
+++ b/resources/js/pages/users/Addresses.vue
@@ -133,9 +133,9 @@
 
   // The cards' server-provided action items (e.g. Delete) run their HTTP
   // request themselves via the action system and announce progress through
-  // bubbling `action:change-state` events — refresh the cards once one
+  // bubbling `craft-state-change` events — refresh the cards once one
   // succeeds.
-  useEventListener(cardsContainer, 'action:change-state', (event: Event) => {
+  useEventListener(cardsContainer, 'craft-state-change', (event: Event) => {
     if (!(event instanceof CustomEvent)) {
       return;
     }
diff --git a/src/Cp/Components/Button.php b/src/Cp/Components/Button.php
index 00281fc874f..00be6920969 100644
--- a/src/Cp/Components/Button.php
+++ b/src/Cp/Components/Button.php
@@ -153,7 +153,7 @@ public function active(bool $active = true): static
         return $this;
     }
 
-    /** Accessible name override, for icon-only buttons. */
+    /** Accessible name for an icon-only button. Rendered as `aria-label`. */
     public function accessibleName(?string $accessibleName): static
     {
         $this->accessibleName = $accessibleName;
@@ -245,7 +245,7 @@ protected function hostAttributes(): array
             'active' => $this->active ? 'true' : null,
             'value' => $this->value,
             'disabled' => $this->isDisabled(),
-            'accessible-name' => $this->accessibleName,
+            'aria-label' => $this->accessibleName,
             'align' => $this->align,
             'href' => $this->href,
             'target' => $this->target,
diff --git a/src/Cp/Components/InputColor.php b/src/Cp/Components/InputColor.php
index 75ce63e7422..28ebf81e61c 100644
--- a/src/Cp/Components/InputColor.php
+++ b/src/Cp/Components/InputColor.php
@@ -51,13 +51,9 @@ protected function hostAttributes(): array
     {
         $attributes = parent::hostAttributes();
 
-        // craft-input-color extends LionInput directly (see InputPassword for the
-        // same rationale): keep only the Lion-pushed control props on the host,
-        // drop `type` and the craft-input-only styling attributes. The slotted
-        // native input still carries the functional ones via Input::inputHtml().
-        foreach (['type', 'maxlength', 'size', 'small', 'width', 'center', 'monospace', 'hidden-input'] as $key) {
-            unset($attributes[$key]);
-        }
+        // Drop `type`: the component pairs its own text field with a native
+        // colour swatch. The slotted native input still carries it via
+        // Input::inputHtml().
 
         $presets = array_values(array_filter($this->presets));
         $attributes['presets'] = $presets !== [] ? Json::encode($presets) : null;
diff --git a/src/Cp/Components/InputPassword.php b/src/Cp/Components/InputPassword.php
index ab140174ee6..4df18947455 100644
--- a/src/Cp/Components/InputPassword.php
+++ b/src/Cp/Components/InputPassword.php
@@ -35,16 +35,10 @@ protected function hostAttributes(): array
     {
         $attributes = parent::hostAttributes();
 
-        // craft-input-password extends LionInput directly, so it only honors the
-        // control properties Lion pushes onto the slotted input on upgrade
-        // (placeholder/name/disabled/readonly). Drop `type` — the component owns
-        // it (password ⇄ text via the reveal toggle) — and the craft-input-only
-        // styling host attributes it doesn't implement. The slotted native input
-        // still carries the functional ones (type, maxlength) via
-        // Input::inputHtml().
-        foreach (['type', 'maxlength', 'size', 'small', 'width', 'center', 'monospace', 'hidden-input'] as $key) {
-            unset($attributes[$key]);
-        }
+        // Drop `type`: the component owns it, toggling password ⇄ text via the
+        // reveal button. The slotted native input still carries it via
+        // Input::inputHtml() for pre-upgrade masking and form posting.
+        unset($attributes['type']);
 
         return $attributes;
     }
diff --git a/src/Cp/Html/ElementHtml.php b/src/Cp/Html/ElementHtml.php
index 4a2d087a28e..a9660ccfd7c 100644
--- a/src/Cp/Html/ElementHtml.php
+++ b/src/Cp/Html/ElementHtml.php
@@ -96,7 +96,6 @@ public function chipHtml(Chippable $component, array $config = []): string
                 $config['size'],
                 ...Html::explodeClass($config['class']),
             ],
-            'show-indicators' => $config['showIndicators'],
             'show-thumb' => $config['showThumb'],
             'show-status' => $config['showStatus'],
             'selectable' => $config['selectable'],
diff --git a/tests/Unit/Cp/Components/ButtonTest.php b/tests/Unit/Cp/Components/ButtonTest.php
index 6d3068f43c6..822a0dbd28e 100644
--- a/tests/Unit/Cp/Components/ButtonTest.php
+++ b/tests/Unit/Cp/Components/ButtonTest.php
@@ -54,7 +54,7 @@
 
     it('renders the accessible name for icon-only buttons', function () {
         expect(Button::make()->icon('plus')->accessibleName('Add row')->toHtml())
-            ->toContain('accessible-name="Add row"');
+            ->toContain('aria-label="Add row"');
     });
 });
 
diff --git a/tests/Unit/Cp/Components/ComponentManifestDriftTest.php b/tests/Unit/Cp/Components/ComponentManifestDriftTest.php
index 45be2235580..359028a9df5 100644
--- a/tests/Unit/Cp/Components/ComponentManifestDriftTest.php
+++ b/tests/Unit/Cp/Components/ComponentManifestDriftTest.php
@@ -202,8 +202,10 @@ function cpDriftWcOnlyAllowlist(): array
 function cpDriftExpectedPhpOnly(): array
 {
     return [
-        // Global / structural HTML attributes the WC does not declare in the manifest.
-        '*' => ['id', 'class', 'style', 'role', 'aria', 'data', 'slot'],
+        // Global / structural HTML attributes the WC does not declare in the
+        // manifest. `aria-label` is here because naming an element is the
+        // consumer's job — no component declares an attribute for it.
+        '*' => ['id', 'class', 'style', 'role', 'aria', 'aria-label', 'data', 'slot'],
 
         // craft-button: `type`/`disabled` are native/global; `active` and `command`
         // are PHP conveniences (pressed state, Invoker Commands API).