diff --git a/packages/craftcms-cp/custom-elements-manifest.config.mjs b/packages/craftcms-cp/custom-elements-manifest.config.mjs
index 69988926c76..e9788f785b3 100644
--- a/packages/craftcms-cp/custom-elements-manifest.config.mjs
+++ b/packages/craftcms-cp/custom-elements-manifest.config.mjs
@@ -4,6 +4,62 @@ export default {
   exclude: ['**/*.stories.ts', '**/*.styles.ts', '**/*.test.ts'],
   outdir: 'dist',
   plugins: [
+    // Capture custom JSDoc tags used to drive PHP component generation.
+    // Unknown tags are dropped by the analyzer otherwise, so we read them off
+    // the AST here and attach them to the manifest:
+    //   @phpComponent          (class)    opt this element into PHP generation
+    //   @phpType {Type}        (property) override the generated PHP type
+    {
+      name: 'php-codegen-tags',
+      analyzePhase({ts, node, moduleDoc}) {
+        if (!ts.isClassDeclaration(node) || !node.name) {
+          return;
+        }
+
+        const decl = moduleDoc.declarations?.find(
+          (d) => d.name === node.name.getText()
+        );
+        if (!decl) {
+          return;
+        }
+
+        const findTag = (n, name) =>
+          (ts.getJSDocTags(n) || []).find(
+            (t) => t.tagName?.getText() === name
+          );
+
+        if (findTag(node, 'phpComponent')) {
+          decl.phpComponent = true;
+        }
+
+        for (const member of node.members || []) {
+          const tag = findTag(member, 'phpType');
+          if (!tag) {
+            continue;
+          }
+
+          const phpType = String(tag.comment ?? '')
+            .trim()
+            .replace(/^\{|\}$/g, '')
+            .trim();
+          if (!phpType) {
+            continue;
+          }
+
+          const fieldName = member.name?.getText();
+          const field = decl.members?.find(
+            (m) => m.kind === 'field' && m.name === fieldName
+          );
+          if (field) {
+            field.phpType = phpType;
+          }
+          const attr = decl.attributes?.find((a) => a.fieldName === fieldName);
+          if (attr) {
+            attr.phpType = phpType;
+          }
+        }
+      },
+    },
     // Add a plugin to prevent inheritance tree analysis errors
     {
       name: 'skip-external-inheritance',
diff --git a/packages/craftcms-cp/package.json b/packages/craftcms-cp/package.json
index 0b2e49d24aa..ef5e3d654ed 100644
--- a/packages/craftcms-cp/package.json
+++ b/packages/craftcms-cp/package.json
@@ -29,7 +29,8 @@
     "build:storybook": "storybook build",
     "build:manifest": "custom-elements-manifest analyze --litelement --outdir dist",
     "generate:vue-wrappers": "node ./scripts/generate-vue-wrappers.js",
-    "generate:colors": "node ./scripts/generate-colors.js && node scripts/generate-color-palette.js"
+    "generate:colors": "node ./scripts/generate-colors.js && node scripts/generate-color-palette.js",
+    "generate:php": "npm run build:manifest && node ./scripts/generate-php-components.js"
   },
   "exports": {
     "./package.json": "./package.json",
diff --git a/packages/craftcms-cp/scripts/generate-php-components.js b/packages/craftcms-cp/scripts/generate-php-components.js
new file mode 100644
index 00000000000..91bee1dae60
--- /dev/null
+++ b/packages/craftcms-cp/scripts/generate-php-components.js
@@ -0,0 +1,300 @@
+/**
+ * Proof of concept: generate PHP component base classes from the Custom
+ * Elements Manifest.
+ *
+ * For every custom element tagged `@phpComponent`, this emits an abstract PHP
+ * base class mirroring its attributes (fluent setters + `toHtml()`), into:
+ *   src/Cp/Components/Generated/<Name>Component.php
+ *
+ * The generated base is meant to be extended by a hand-written concrete class
+ * (e.g. `Indicator extends IndicatorComponent`) that adds behavior. Regenerating
+ * never touches the hand-written subclass.
+ *
+ * Usage (from packages/craftcms-cp/):
+ *   npm run build:manifest && node scripts/generate-php-components.js
+ */
+
+import {mkdirSync, readFileSync, writeFileSync} from 'fs';
+import {dirname, resolve} from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const MANIFEST = resolve(ROOT, 'dist/custom-elements.json');
+const OUT_DIR = resolve(ROOT, '../../src/Cp/Components/Generated');
+const PHP_NAMESPACE = 'CraftCms\\Cms\\Cp\\Components\\Generated';
+
+// Short PHP type name -> fully-qualified class to `use`. Drives both imports
+// and `->value` resolution for backed enums. A `@phpType {Color|string}` tag in
+// the web component routes through here.
+const ENUM_IMPORTS = {
+  Color: 'CraftCms\\Cms\\Shared\\Enums\\Color',
+};
+
+// TS type aliases that resolve to a plain PHP type. e.g. `VariantKey` is a
+// string union, so it maps to `string`. A `@phpType` tag can always override.
+const TYPE_ALIASES = {
+  VariantKey: 'string',
+};
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function pascalFromTag(tagName) {
+  return tagName
+    .split('-')
+    .filter((part, i) => !(i === 0 && (part === 'craft' || part === 'c')))
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+const isStringLiteralUnion = (text) =>
+  /^'[^']*'(\s*\|\s*'[^']*')*$/.test(text.trim());
+
+/**
+ * Maps a manifest attribute to PHP type info.
+ * Returns {type, paramDoc, enum} where `enum` is the backed-enum short name (or null).
+ */
+function mapType(attr) {
+  // An explicit @phpType override wins.
+  if (attr.phpType) {
+    const tokens = attr.phpType.split('|').map((t) => t.trim());
+    const enumName = tokens.find((t) => ENUM_IMPORTS[t]) ?? null;
+    return {type: attr.phpType, paramDoc: null, enum: enumName};
+  }
+
+  const text = (attr.type?.text ?? 'string').trim();
+  const nullable = /(^|\|)\s*null\s*($|\|)/.test(text);
+  const base = text
+    .split('|')
+    .map((t) => t.trim())
+    .filter((t) => t !== 'null')
+    .join(' | ');
+
+  let type;
+  let paramDoc = null;
+
+  if (TYPE_ALIASES[base]) {
+    type = TYPE_ALIASES[base];
+  } else if (isStringLiteralUnion(base)) {
+    type = 'string';
+    paramDoc = base; // e.g. 'md' | 'lg'
+  } else if (base === 'string') {
+    type = 'string';
+  } else if (base === 'number') {
+    type = 'int|float';
+  } else if (base === 'boolean') {
+    type = 'bool';
+  } else {
+    type = 'mixed';
+  }
+
+  if (nullable && type !== 'mixed') {
+    type = type.includes('|') ? `${type}|null` : `?${type}`;
+  }
+
+  return {type, paramDoc, enum: null};
+}
+
+// Widens a PHP type to also accept null (used when an attribute has no default,
+// so the generated property can be initialized to null rather than left unset).
+function makeNullable(type) {
+  if (type === 'mixed' || type.startsWith('?') || /(^|\|)null(\||$)/.test(type)) {
+    return type;
+  }
+
+  return type.includes('|') ? `${type}|null` : `?${type}`;
+}
+
+const indent = (lines, pad = '    ') =>
+  lines.map((l) => (l ? pad + l : l)).join('\n');
+
+// ─── Code generation ────────────────────────────────────────────────────────
+
+function generateSetter(attr, field, mapped) {
+  const doc = mapped.paramDoc
+    ? `    /**\n     * @param  ${mapped.paramDoc}  $${field}\n     */\n`
+    : '';
+
+  return (
+    doc +
+    `    public function ${field}(${mapped.type} $${field}): static\n` +
+    `    {\n` +
+    `        $this->${field} = $${field};\n\n` +
+    `        return $this;\n` +
+    `    }`
+  );
+}
+
+function generateRenderLine(attr, field, mapped, effectiveDefault) {
+  const resolved = mapped.enum
+    ? `$this->${field} instanceof ${mapped.enum} ? $this->${field}->value : $this->${field}`
+    : `$this->${field}`;
+
+  // Omit the attribute when it still holds its default, keeping the markup
+  // clean (the web component applies the same defaults itself). `Html::tag`
+  // renders bool `true` as a bare attribute and omits `false`/`null`.
+  if (effectiveDefault === 'null') {
+    return `'${attr.name}' => ${resolved},`;
+  }
+
+  return `'${attr.name}' => $this->${field} === ${effectiveDefault} ? null : ${mapped.enum ? `(${resolved})` : resolved},`;
+}
+
+function camelCase(name) {
+  return name
+    .split(/[-_]/)
+    .map((part, i) =>
+      i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
+    )
+    .join('');
+}
+
+// Method names already provided by the ViewComponent base.
+const RESERVED_METHODS = [
+  'make',
+  'attributes',
+  'slot',
+  'toHtml',
+  '__toString',
+  '__construct',
+];
+
+function generateSlotSetter(methodName, slotKey) {
+  const key = slotKey === '' ? "''" : `'${slotKey}'`;
+
+  return (
+    `    public function ${methodName}(Closure|Htmlable|Stringable|string $content): static\n` +
+    `    {\n` +
+    `        $this->slots[${key}] = $content;\n\n` +
+    `        return $this;\n` +
+    `    }`
+  );
+}
+
+function generateClass(decl) {
+  const tagName = decl.tagName;
+  const baseName = `${pascalFromTag(tagName)}Component`;
+  const attributes = decl.attributes ?? [];
+
+  const enums = new Set();
+  const fields = [];
+  const setters = [];
+  const renderLines = [];
+  const usedNames = new Set(RESERVED_METHODS);
+
+  for (const attr of attributes) {
+    const field = attr.fieldName ?? attr.name;
+    const mapped = mapType(attr);
+    if (mapped.enum) {
+      enums.add(mapped.enum);
+    }
+    usedNames.add(field);
+
+    // CEM only captures literal defaults; non-literal/absent ones come through
+    // as `undefined`. In that case make the property nullable and default null
+    // so it's always initialized (and omitted from the rendered markup).
+    const hasDefault =
+      attr.default !== undefined && attr.default !== 'undefined';
+    const type = hasDefault ? mapped.type : makeNullable(mapped.type);
+    const effectiveDefault = hasDefault ? attr.default : 'null';
+
+    fields.push(`    protected ${type} $${field} = ${effectiveDefault};`);
+    setters.push(generateSetter(attr, field, {...mapped, type}));
+    renderLines.push(generateRenderLine(attr, field, mapped, effectiveDefault));
+  }
+
+  // Each manifest slot becomes a fluent callback setter. The default (unnamed)
+  // slot maps to `content()`; names that would clash with an attribute setter
+  // (or a base method) get a `Slot` suffix.
+  const slotSetters = [];
+  for (const slot of decl.slots ?? []) {
+    const slotKey = slot.name ?? '';
+    let methodName = slotKey === '' ? 'content' : camelCase(slotKey);
+    while (usedNames.has(methodName)) {
+      methodName += 'Slot';
+    }
+    usedNames.add(methodName);
+    slotSetters.push(generateSlotSetter(methodName, slotKey));
+  }
+
+  const hasSlots = slotSetters.length > 0;
+
+  const importClasses = ['CraftCms\\Cms\\Cp\\Components\\ViewComponent'];
+  for (const e of enums) {
+    importClasses.push(ENUM_IMPORTS[e]);
+  }
+  if (hasSlots) {
+    importClasses.push(
+      'Closure',
+      'Illuminate\\Contracts\\Support\\Htmlable',
+      'Stringable'
+    );
+  }
+  importClasses.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const imports = importClasses.map((c) => `use ${c};`).join('\n');
+
+  const summary = (decl.summary ?? decl.description ?? '')
+    .split('\n')
+    .map((l) => ` * ${l}`.trimEnd())
+    .join('\n');
+
+  const members = [
+    fields.join('\n\n'),
+    setters.join('\n\n'),
+    slotSetters.join('\n\n'),
+    `    protected function tagName(): string\n    {\n        return '${tagName}';\n    }`,
+    `    protected function hostAttributes(): array\n    {\n        return [\n${indent(renderLines, '            ')}\n        ];\n    }`,
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+
+  return {
+    baseName,
+    code: `<?php
+
+declare(strict_types=1);
+
+namespace ${PHP_NAMESPACE};
+
+${imports}
+
+/**
+${summary ? summary + '\n *\n' : ''} * @generated from the \`${tagName}\` custom element. Do not edit by hand.
+ *           Run \`npm run generate:php\` in packages/craftcms-cp to regenerate.
+ *           Add behavior in the concrete subclass, not here.
+ */
+abstract class ${baseName} extends ViewComponent
+{
+${members}
+}
+`,
+  };
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+export default function main() {
+  const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
+
+  const declarations = (manifest.modules ?? [])
+    .flatMap((mod) => mod.declarations ?? [])
+    .filter((decl) => decl.phpComponent === true);
+
+  if (declarations.length === 0) {
+    console.log('No @phpComponent custom elements found in the manifest.');
+    return;
+  }
+
+  mkdirSync(OUT_DIR, {recursive: true});
+
+  for (const decl of declarations) {
+    const {baseName, code} = generateClass(decl);
+    const filePath = resolve(OUT_DIR, `${baseName}.php`);
+    writeFileSync(filePath, code);
+    console.log(`  Generated: src/Cp/Components/Generated/${baseName}.php`);
+  }
+
+  console.log(`\n  ${declarations.length} PHP component base class(es) generated.`);
+}
+
+main();
diff --git a/packages/craftcms-cp/src/components/action-item/action-item.ts b/packages/craftcms-cp/src/components/action-item/action-item.ts
index f381c386510..5bdce361667 100644
--- a/packages/craftcms-cp/src/components/action-item/action-item.ts
+++ b/packages/craftcms-cp/src/components/action-item/action-item.ts
@@ -19,25 +19,67 @@ import {
 } from '@src/actions';
 
 /**
- * @summary Either a link or button typically used in a menu.
+ * @summary A menu entry that renders as a link or a button and can run an
+ * action, showing inline loading/success/error feedback.
+ * @since 1.0
+ *
+ * @dependency craft-icon
+ * @dependency craft-spinner
+ * @dependency craft-shortcut
+ *
+ * @slot - The item's label.
+ * @slot icon - Icon displayed in the prefix (falls back to the `icon` attribute).
+ * @slot checkmark - Custom checkmark content, shown when `type="checkbox"`.
+ * @slot suffix - Content displayed after the label.
+ *
+ * @event action:change-state - Emitted when the item's async action changes state (idle, loading, success, or error).
+ *
+ * @phpComponent
  */
 export default class CraftActionItem extends LitElement {
   static override styles = [variantsStyles, styles];
+
+  /** Icon name shown in the prefix when no `icon` slot is provided. */
   @property() icon: string | null = null;
+
+  /** When set, the item renders as a link (`<a>`) instead of a `<button>`. */
   @property() href: string | null = null;
+
+  /** Disables the item and prevents its action from running. */
   @property({type: Boolean}) disabled: boolean = false;
+
+  /** Theme variant used for the item's coloring. */
   @property({reflect: true}) variant: VariantKey = Variant.Default;
+
+  /** For `type="checkbox"`, whether the item is checked. */
   @property({type: Boolean}) checked: boolean = false;
+
+  /** Displays the item in an active state. */
   @property({type: Boolean}) active: boolean = false;
+
+  /** Whether the item behaves as a `button` or a `checkbox`. */
   @property() type: 'button' | 'checkbox' = 'button';
+
+  /** The action to run when the item is activated. */
   @property({type: Object}) action: BaseAction | null = null;
+
+  /** Success/error feedback shown after the action runs. */
   @property({type: Object}) feedback: ActionFeedback | null = null;
+
+  /** How long, in milliseconds, feedback is shown before returning to idle. */
   @property({type: Number}) feedbackDuration: number = 1000;
+
+  /** Optional confirmation message shown before the action runs. */
   @property() confirm: string | null = null;
 
   @state() private state: AsyncState = AsyncStates.Idle;
   @state() private feedbackMessage: string | null = null;
 
+  /**
+   * Keyboard shortcut hint shown in the suffix. Accepts a plain string (e.g.
+   * `"ctrl+k"`) or an object describing the key and modifiers; the attribute
+   * form is parsed from JSON or a plain string.
+   */
   @property({
     converter: {
       fromAttribute(value: string | null) {
diff --git a/packages/craftcms-cp/src/components/badge-indicator/badge-indicator.ts b/packages/craftcms-cp/src/components/badge-indicator/badge-indicator.ts
index 61d475dd2c4..8760cb0d37b 100644
--- a/packages/craftcms-cp/src/components/badge-indicator/badge-indicator.ts
+++ b/packages/craftcms-cp/src/components/badge-indicator/badge-indicator.ts
@@ -8,8 +8,17 @@ import '@shoelace-style/shoelace/dist/components/visually-hidden/visually-hidden
  * @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.
+ *
+ * @since 1.0
+ *
+ * @dependency sl-visually-hidden
+ *
+ * @csspart badge - The badge container.
+ *
+ * @cssproperty [--badge-color=var(--c-color-accent-fill-loud)] - Background color of the badge.
+ * @cssproperty [--text-color=white] - Color of the count text.
+ * @cssproperty [--badge-size=calc(8rem / 16)] - Minimum size of the badge. Defaults to 8px.
  */
-
 export default class CraftBadgeIndicator extends LitElement {
   static override styles = [styles];
 
diff --git a/packages/craftcms-cp/src/components/indicator/Indicator.mdx b/packages/craftcms-cp/src/components/indicator/Indicator.mdx
new file mode 100644
index 00000000000..331b060fb3f
--- /dev/null
+++ b/packages/craftcms-cp/src/components/indicator/Indicator.mdx
@@ -0,0 +1,146 @@
+import {Canvas, Meta} from '@storybook/addon-docs/blocks';
+import IndicatorMeta, {
+  Default,
+  ArbitraryColor,
+  ArbitrarySize,
+} from './indicator.stories';
+
+<Meta of={IndicatorMeta} name="Docs" />
+
+# Indicator
+
+`<craft-indicator>` is a small dot used to visually represent the status of an
+object — for example, the live/draft state of an entry or a "has updates" marker
+in a list.
+
+> **Reach for a status component first.** Most features should use a
+> higher-level status component (which sets the right `fill` and `label` for a
+> known state) rather than placing `<craft-indicator>` directly. Use the
+> indicator on its own when you need a one-off dot that an existing status
+> component doesn't cover.
+
+<Canvas of={Default} />
+
+## Usage
+
+```html
+<craft-indicator fill="success" label="Live"></craft-indicator>
+```
+
+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' | 'empty'</code></td>
+      <td><code>'solid'</code></td>
+      <td><code>solid</code> fills the dot; <code>empty</code> draws only the colored ring (hollow).</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.5em, <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 keywords
+
+`fill` accepts a set of semantic keywords that map to design tokens. Anything
+that isn't a recognized keyword is passed through verbatim, so raw CSS values
+(hex, `rgb()`, `var(...)`, gradients) work too.
+
+<table>
+  <thead>
+    <tr>
+      <th>Keyword</th>
+      <th>Token</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>success</code> / <code>live</code></td>
+      <td><code>--c-color-success-fill-loud</code></td>
+    </tr>
+    <tr>
+      <td><code>warning</code></td>
+      <td><code>--c-color-warning-fill-loud</code></td>
+    </tr>
+    <tr>
+      <td><code>danger</code></td>
+      <td><code>--c-color-danger-fill-loud</code></td>
+    </tr>
+    <tr>
+      <td><code>info</code></td>
+      <td><code>--c-color-info-fill-loud</code></td>
+    </tr>
+    <tr>
+      <td><code>default</code> / <code>draft</code></td>
+      <td><code>--c-color-neutral-fill-loud</code></td>
+    </tr>
+  </tbody>
+</table>
+
+Prefer the semantic keywords so indicators stay consistent with the rest of the
+palette. Use an arbitrary value only when a status genuinely falls outside the
+token set.
+
+<Canvas of={ArbitraryColor} />
+
+## Sizing
+
+`size` switches between two preset sizes. Because the dimensions are defined in
+`em`, the dot scales with the font size of its container — set `font-size` on a
+wrapper to fine-tune it.
+
+<Canvas of={ArbitrarySize} />
+
+## Accessibility
+
+- The dot is exposed as `role="img"`, and `label` becomes its `aria-label`.
+- A status dot conveys meaning through color alone, so set `label` whenever the
+  indicator isn't purely decorative. If it only repeats adjacent visible text,
+  it's fine to leave `label` unset.
+
+## Styling
+
+The visible color is resolved from `fill` and applied through the private
+`--fill` custom property at render time, so target the host element to adjust
+layout:
+
+```css
+craft-indicator {
+  /* the dot is sized in em — change the font size to scale it */
+  font-size: 1.25rem;
+}
+```
diff --git a/packages/craftcms-cp/src/components/indicator/indicator.stories.ts b/packages/craftcms-cp/src/components/indicator/indicator.stories.ts
index d6f105950ec..56aa7dd8c3c 100644
--- a/packages/craftcms-cp/src/components/indicator/indicator.stories.ts
+++ b/packages/craftcms-cp/src/components/indicator/indicator.stories.ts
@@ -1,32 +1,104 @@
 import type {Meta, StoryObj} from '@storybook/web-components-vite';
 
-import {html} from 'lit';
+import {html, nothing} from 'lit';
 
 import './indicator.js';
+import type CraftIndicator from './indicator.js';
 import {Variant} from '@src/types';
 
+/**
+ * Renders a `solid` and an `empty` indicator side by side, with a label,
+ * so every story shares the same markup.
+ */
+const renderIndicators = (
+  label: string,
+  attrs: {fill?: string; size?: CraftIndicator['size']} = {}
+) => html`
+  <tr>
+    <td>${label}</td>
+    <td>
+      <craft-indicator
+        fill="${attrs.fill ?? nothing}"
+        size="${attrs.size ?? nothing}"
+      ></craft-indicator>
+    </td>
+    <td>
+      <craft-indicator
+        appearance="empty"
+        fill="${attrs.fill ?? nothing}"
+        size="${attrs.size ?? nothing}"
+      ></craft-indicator>
+    </td>
+  </tr>
+`;
+
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
   title: 'Components/Indicator',
   component: 'craft-indicator',
   args: {},
-  render: function () {
-    return html`
-      <div class="stack">
-        ${Object.values(Variant).map(
-          (variant) =>
-            html`<craft-indicator variant="${variant}"></craft-indicator>`
+  render: () => html`
+    <table>
+      <thead>
+        <th></th>
+        <th>Solid</th>
+        <th>Empty</th>
+      </thead>
+      <tbody>
+        ${Object.values(Variant).map((variant) =>
+          renderIndicators(variant, {fill: variant})
         )}
-        <craft-indicator variant="empty"></craft-indicator>
-      </div>
-    `;
-  },
-} satisfies Meta<any>;
+      </tbody>
+    </table>
+  `,
+} satisfies Meta<CraftIndicator>;
 
 export default meta;
-type Story = StoryObj<any>;
+type Story = StoryObj<CraftIndicator>;
 
 // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
 export const Default: Story = {
   args: {},
 };
+
+const arbitraryValues = [
+  '#2c61de',
+  'rgba(30, 40, 40, 0.2)',
+  'linear-gradient(red, blue)',
+];
+
+export const ArbitraryColor: Story = {
+  render: () => html`
+    <table>
+      <thead>
+        <th></th>
+        <th>Solid</th>
+        <th>Empty</th>
+      </thead>
+      <tbody>
+        ${arbitraryValues.map((value) =>
+          renderIndicators(value, {fill: value})
+        )}
+      </tbody>
+    </table>
+  `,
+};
+
+const sizes: Array<CraftIndicator['size']> = ['md', 'lg'];
+
+export const ArbitrarySize: Story = {
+  render: () => html`
+    <table>
+      <thead>
+        <th></th>
+        <th>Solid</th>
+        <th>Empty</th>
+      </thead>
+      <tbody>
+        ${sizes.map((size) =>
+          renderIndicators(size === 'md' ? 'md (default)' : size, {size})
+        )}
+      </tbody>
+    </table>
+  `,
+};
diff --git a/packages/craftcms-cp/src/components/indicator/indicator.ts b/packages/craftcms-cp/src/components/indicator/indicator.ts
index 944806e22cf..5a49eb5f151 100644
--- a/packages/craftcms-cp/src/components/indicator/indicator.ts
+++ b/packages/craftcms-cp/src/components/indicator/indicator.ts
@@ -4,46 +4,98 @@ import {Variant, type VariantKey} from '@src/types';
 import {classMap} from 'lit/directives/class-map.js';
 import variantsStyles from '@src/styles/variants.styles';
 
+/**
+ * @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.
+ *
+ * @since 1.0
+ *
+ * @phpComponent
+ */
 export default class CraftIndicator extends LitElement {
   static override styles = [
     variantsStyles,
     css`
       .indicator {
+        --_fill: var(--fill, var(--c-color-fill-loud));
+        --_size: var(--size, 0.5em);
         display: inline-flex;
         aspect-ratio: 1;
-        width: var(--c-indicator-size, 0.5em);
+        width: var(--_size);
         border-radius: var(--c-radius-full);
-        color: var(--c-color-on-loud);
-        background-color: var(--c-color-fill-loud);
-        border: 1px solid var(--c-color-border-loud);
+        background: var(--_fill);
+        border: 1px solid var(--_fill);
       }
 
       .indicator--empty {
-        background-color: var(--c-color-neutral-fill-quiet);
-        border: 1px solid var(--c-color-neutral-border-normal);
+        background: transparent;
       }
     `,
   ];
 
-  @property({reflect: true})
-  variant: VariantKey | 'empty' = Variant.Default;
+  /** Size of the indicator dot. */
+  @property()
+  size: 'md' | 'lg' = 'md';
+
+  /**
+   * Fill color of the dot — a status keyword (e.g. `success`, `draft`), any CSS
+   * color value, or a {@link Color} when set from PHP.
+   *
+   * @phpType {Color|string}
+   */
+  @property()
+  fill: string = 'var(--c-color-fill-loud)';
 
+  /** Accessible label for the indicator, exposed as `aria-label`. */
   @property()
   label: string | null = null;
 
+  /** `solid` fills the dot; `empty` renders it hollow. */
+  @property()
+  appearance: 'solid' | 'empty' = 'solid';
+
+  getFill() {
+    switch (this.fill) {
+      case 'live':
+      case Variant.Success:
+        return 'var(--c-color-success-fill-loud)';
+      case Variant.Warning:
+        return 'var(--c-color-warning-fill-loud)';
+      case Variant.Danger:
+        return 'var(--c-color-danger-fill-loud)';
+      case Variant.Info:
+        return 'var(--c-color-info-fill-loud)';
+      case 'draft':
+      case 'default':
+        return 'var(--c-color-neutral-fill-loud)';
+
+      default:
+        return this.fill;
+    }
+  }
+
+  getSize() {
+    switch (this.size) {
+      case 'md':
+        return '0.6em';
+      case 'lg':
+        return '1em';
+      default:
+        return this.size;
+    }
+  }
+
   protected override render(): unknown {
     return html`<span
+      style="--fill: ${this.getFill()}; --size: ${this.getSize()}"
+      aria-label="${this.label}"
+      role="img"
       class="${classMap({
         indicator: true,
-        'indicator--success': this.variant === Variant.Success,
-        'indicator--danger': this.variant === Variant.Danger,
-        'indicator--warning': this.variant === Variant.Warning,
-        'indicator--info': this.variant === Variant.Info,
-        'indicator--empty': this.variant === 'empty',
+        'indicator--empty': this.appearance === 'empty',
       })}"
-    >
-      <slot></slot>
-    </span>`;
+    ></span>`;
   }
 }
 
diff --git a/packages/craftcms-cp/src/components/nav-item/nav-item.ts b/packages/craftcms-cp/src/components/nav-item/nav-item.ts
index fee63bc351c..fe6b5187221 100644
--- a/packages/craftcms-cp/src/components/nav-item/nav-item.ts
+++ b/packages/craftcms-cp/src/components/nav-item/nav-item.ts
@@ -7,7 +7,22 @@ import {t} from '@src/utilities/translate.js';
 import {classMap} from 'lit/directives/class-map.js';
 
 /**
+ * @summary A navigation item, rendered as a link within a nav list, optionally
+ * with a collapsible subnav, a prefix icon/indicator, and an icon-only mode.
+ * @since 1.0
  *
+ * @dependency craft-icon
+ * @dependency craft-button
+ * @dependency craft-badge-indicator
+ * @dependency c-tooltip
+ *
+ * @slot - The item's label.
+ * @slot prefix - Content displayed before the label.
+ * @slot icon - Icon displayed in the prefix (falls back to the `icon` attribute).
+ * @slot suffix - Content displayed after the label.
+ * @slot subnav - Nested `craft-nav-item`s shown in a collapsible subnav.
+ *
+ * @phpComponent
  */
 export default class CraftNavItem extends LitElement {
   static override styles = styles;
@@ -32,9 +47,11 @@ export default class CraftNavItem extends LitElement {
   @property({type: Boolean})
   indicator: boolean = false;
 
+  /** Unique identifier for the item. Generated automatically when omitted. */
   @property()
   override id: string;
 
+  /** Renders the item as an icon-only button, with the label shown in a tooltip. */
   @property({reflect: true, type: Boolean, attribute: 'icon-only'})
   iconOnly: boolean = false;
 
diff --git a/packages/craftcms-cp/src/components/status-badge/status-badge.ts b/packages/craftcms-cp/src/components/status-badge/status-badge.ts
new file mode 100644
index 00000000000..3249d43fc7c
--- /dev/null
+++ b/packages/craftcms-cp/src/components/status-badge/status-badge.ts
@@ -0,0 +1,48 @@
+import {html, css, LitElement} from 'lit';
+import {Color, type ColorKey} from '@src/constants/colors';
+import {property} from 'lit/decorators.js';
+
+export default class CraftStatusBadge extends LitElement {
+  static override styles = [
+    css`
+      .status-badge {
+        display: inline-flex;
+        border-radius: var(--c-radius-full);
+        padding: 0 0.25em;
+        font-size: 0.9em;
+        align-items: center;
+        font-weight: 500;
+
+        background-color: var(--c-color-fill-quiet);
+        color: var(--c-color-on-quiet);
+        border: 1px solid var(--c-color-border-quiet);
+      }
+
+      .status-badge__body {
+        display: inline-flex;
+        padding-inline: 0.25em;
+      }
+    `,
+  ];
+  @property() color: ColorKey = Color.Gray;
+
+  protected override render(): unknown {
+    return html`
+      <span class="status-badge" data-color="${this.color}">
+        <slot name="prefix"></slot>
+        <span class="status-badge__body"><slot></slot></span>
+        <slot name="suffix"></slot>
+      </span>
+    `;
+  }
+}
+
+if (!customElements.get('craft-status-badge')) {
+  customElements.define('craft-status-badge', CraftStatusBadge);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'craft-status-badge': CraftStatusBadge;
+  }
+}
diff --git a/packages/craftcms-cp/src/components/tooltip/Tooltip.mdx b/packages/craftcms-cp/src/components/tooltip/Tooltip.mdx
index d223cff065e..9a0499a8140 100644
--- a/packages/craftcms-cp/src/components/tooltip/Tooltip.mdx
+++ b/packages/craftcms-cp/src/components/tooltip/Tooltip.mdx
@@ -1,7 +1,7 @@
 import {Canvas, Meta} from '@storybook/addon-docs/blocks';
 import TooltipMeta, {Playground} from './tooltip.stories';
 
-<Meta of={TooltipMeta} />
+<Meta of={TooltipMeta} name="Docs" />
 
 # Tooltip
 
diff --git a/packages/craftcms-cp/src/constants/colors.ts b/packages/craftcms-cp/src/constants/colors.ts
index 5069cf43d93..68f312efae9 100644
--- a/packages/craftcms-cp/src/constants/colors.ts
+++ b/packages/craftcms-cp/src/constants/colors.ts
@@ -20,3 +20,5 @@ export const Color = {
   Gray: 'gray',
   Black: 'black',
 } as const;
+
+export type ColorKey = (typeof Color)[keyof typeof Color];
diff --git a/packages/craftcms-cp/src/index.ts b/packages/craftcms-cp/src/index.ts
index fc68049f859..2fcd34669a7 100644
--- a/packages/craftcms-cp/src/index.ts
+++ b/packages/craftcms-cp/src/index.ts
@@ -57,6 +57,7 @@ export {default as CraftFieldGroup} from './components/field-group/field-group.j
 export {default as CraftPane} from './components/pane/pane.js';
 export {CraftAuthChallengeForm} from './components/auth-challenge-form/auth-challenge-form.js';
 export {default as CraftVisuallyHidden} from './components/visually-hidden/visually-hidden.js';
+export {default as CraftStatusBadge} from './components/status-badge/status-badge.js';
 /* plop:component */
 
 export * from './utilities/cookies.js';
diff --git a/packages/craftcms-cp/src/styles/shared/colorable.css b/packages/craftcms-cp/src/styles/shared/colorable.css
index 9618fc87b22..f6e494531b6 100644
--- a/packages/craftcms-cp/src/styles/shared/colorable.css
+++ b/packages/craftcms-cp/src/styles/shared/colorable.css
@@ -309,10 +309,6 @@
   --c-color-on-quiet: var(--c-color-neutral-on-quiet);
   --c-color-on-normal: var(--c-color-neutral-on-normal);
   --c-color-on-loud: var(--c-color-neutral-on-loud);
-
-  background-color: var(--c-color-fill-quiet);
-  border-color: var(--c-color-border-quiet);
-  color: var(--c-color-on-quiet);
 }
 
 .c-colorable--red,
diff --git a/src/Cp/Components/ActionItem.php b/src/Cp/Components/ActionItem.php
new file mode 100644
index 00000000000..80e98eb749b
--- /dev/null
+++ b/src/Cp/Components/ActionItem.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components;
+
+use CraftCms\Cms\Cp\Components\Generated\ActionItemComponent;
+
+/**
+ * PHP counterpart to the `<craft-action-item>` web component.
+ *
+ * The fluent attribute and slot API is generated from the custom element
+ * manifest in {@see ActionItemComponent}; add any bespoke behavior here.
+ */
+class ActionItem extends ActionItemComponent {}
diff --git a/src/Cp/Components/Generated/ActionItemComponent.php b/src/Cp/Components/Generated/ActionItemComponent.php
new file mode 100644
index 00000000000..c9d3767f2e1
--- /dev/null
+++ b/src/Cp/Components/Generated/ActionItemComponent.php
@@ -0,0 +1,184 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components\Generated;
+
+use Closure;
+use CraftCms\Cms\Cp\Components\ViewComponent;
+use Illuminate\Contracts\Support\Htmlable;
+use Stringable;
+
+/**
+ * A menu entry that renders as a link or a button and can run an
+ * action, showing inline loading/success/error feedback.
+ *
+ * @generated from the `craft-action-item` custom element. Do not edit by hand.
+ *           Run `npm run generate:php` in packages/craftcms-cp to regenerate.
+ *           Add behavior in the concrete subclass, not here.
+ */
+abstract class ActionItemComponent extends ViewComponent
+{
+    protected ?string $icon = null;
+
+    protected ?string $href = null;
+
+    protected bool $disabled = false;
+
+    protected ?string $variant = null;
+
+    protected bool $checked = false;
+
+    protected bool $active = false;
+
+    protected string $type = 'button';
+
+    protected mixed $action = null;
+
+    protected mixed $feedback = null;
+
+    protected int|float $feedbackDuration = 1000;
+
+    protected ?string $confirm = null;
+
+    protected mixed $shortcut = null;
+
+    public function icon(?string $icon): static
+    {
+        $this->icon = $icon;
+
+        return $this;
+    }
+
+    public function href(?string $href): static
+    {
+        $this->href = $href;
+
+        return $this;
+    }
+
+    public function disabled(bool $disabled): static
+    {
+        $this->disabled = $disabled;
+
+        return $this;
+    }
+
+    public function variant(?string $variant): static
+    {
+        $this->variant = $variant;
+
+        return $this;
+    }
+
+    public function checked(bool $checked): static
+    {
+        $this->checked = $checked;
+
+        return $this;
+    }
+
+    public function active(bool $active): static
+    {
+        $this->active = $active;
+
+        return $this;
+    }
+
+    /**
+     * @param  'button' | 'checkbox'  $type
+     */
+    public function type(string $type): static
+    {
+        $this->type = $type;
+
+        return $this;
+    }
+
+    public function action(mixed $action): static
+    {
+        $this->action = $action;
+
+        return $this;
+    }
+
+    public function feedback(mixed $feedback): static
+    {
+        $this->feedback = $feedback;
+
+        return $this;
+    }
+
+    public function feedbackDuration(int|float $feedbackDuration): static
+    {
+        $this->feedbackDuration = $feedbackDuration;
+
+        return $this;
+    }
+
+    public function confirm(?string $confirm): static
+    {
+        $this->confirm = $confirm;
+
+        return $this;
+    }
+
+    public function shortcut(mixed $shortcut): static
+    {
+        $this->shortcut = $shortcut;
+
+        return $this;
+    }
+
+    public function content(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots[''] = $content;
+
+        return $this;
+    }
+
+    public function iconSlot(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['icon'] = $content;
+
+        return $this;
+    }
+
+    public function checkmark(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['checkmark'] = $content;
+
+        return $this;
+    }
+
+    public function suffix(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['suffix'] = $content;
+
+        return $this;
+    }
+
+    protected function tagName(): string
+    {
+        return 'craft-action-item';
+    }
+
+    #[\Override]
+    protected function hostAttributes(): array
+    {
+        return [
+            'icon' => $this->icon,
+            'href' => $this->href,
+            'disabled' => $this->disabled === false ? null : $this->disabled,
+            'variant' => $this->variant,
+            'checked' => $this->checked === false ? null : $this->checked,
+            'active' => $this->active === false ? null : $this->active,
+            'type' => $this->type === 'button' ? null : $this->type,
+            'action' => $this->action,
+            'feedback' => $this->feedback,
+            'feedbackDuration' => $this->feedbackDuration === 1000 ? null : $this->feedbackDuration,
+            'confirm' => $this->confirm,
+            'shortcut' => $this->shortcut,
+        ];
+    }
+}
diff --git a/src/Cp/Components/Generated/IndicatorComponent.php b/src/Cp/Components/Generated/IndicatorComponent.php
new file mode 100644
index 00000000000..e54489a2281
--- /dev/null
+++ b/src/Cp/Components/Generated/IndicatorComponent.php
@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components\Generated;
+
+use CraftCms\Cms\Cp\Components\ViewComponent;
+use CraftCms\Cms\Shared\Enums\Color;
+
+/**
+ * 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.
+ *
+ * @generated from the `craft-indicator` custom element. Do not edit by hand.
+ *           Run `npm run generate:php` in packages/craftcms-cp to regenerate.
+ *           Add behavior in the concrete subclass, not here.
+ */
+abstract class IndicatorComponent extends ViewComponent
+{
+    protected string $size = 'md';
+
+    protected Color|string $fill = 'var(--c-color-fill-loud)';
+
+    protected ?string $label = null;
+
+    protected string $appearance = 'solid';
+
+    /**
+     * @param  'md' | 'lg'  $size
+     */
+    public function size(string $size): static
+    {
+        $this->size = $size;
+
+        return $this;
+    }
+
+    public function fill(Color|string $fill): static
+    {
+        $this->fill = $fill;
+
+        return $this;
+    }
+
+    public function label(?string $label): static
+    {
+        $this->label = $label;
+
+        return $this;
+    }
+
+    /**
+     * @param  'solid' | 'empty'  $appearance
+     */
+    public function appearance(string $appearance): static
+    {
+        $this->appearance = $appearance;
+
+        return $this;
+    }
+
+    protected function tagName(): string
+    {
+        return 'craft-indicator';
+    }
+
+    #[\Override]
+    protected function hostAttributes(): array
+    {
+        return [
+            'size' => $this->size === 'md' ? null : $this->size,
+            'fill' => $this->fill === 'var(--c-color-fill-loud)' ? null : ($this->fill instanceof Color ? $this->fill->value : $this->fill),
+            'label' => $this->label,
+            'appearance' => $this->appearance === 'solid' ? null : $this->appearance,
+        ];
+    }
+}
diff --git a/src/Cp/Components/Generated/NavItemComponent.php b/src/Cp/Components/Generated/NavItemComponent.php
new file mode 100644
index 00000000000..cce5f8ed6f5
--- /dev/null
+++ b/src/Cp/Components/Generated/NavItemComponent.php
@@ -0,0 +1,148 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components\Generated;
+
+use Closure;
+use CraftCms\Cms\Cp\Components\ViewComponent;
+use Illuminate\Contracts\Support\Htmlable;
+use Stringable;
+
+/**
+ * A navigation item, rendered as a link within a nav list, optionally
+ * with a collapsible subnav, a prefix icon/indicator, and an icon-only mode.
+ *
+ * @generated from the `craft-nav-item` custom element. Do not edit by hand.
+ *           Run `npm run generate:php` in packages/craftcms-cp to regenerate.
+ *           Add behavior in the concrete subclass, not here.
+ */
+abstract class NavItemComponent extends ViewComponent
+{
+    protected ?string $icon = null;
+
+    protected ?string $href = null;
+
+    protected bool $active = false;
+
+    protected bool $external = false;
+
+    protected bool $indicator = false;
+
+    protected ?string $id = null;
+
+    protected bool $iconOnly = false;
+
+    protected bool $flush = false;
+
+    public function icon(?string $icon): static
+    {
+        $this->icon = $icon;
+
+        return $this;
+    }
+
+    public function href(?string $href): static
+    {
+        $this->href = $href;
+
+        return $this;
+    }
+
+    public function active(bool $active): static
+    {
+        $this->active = $active;
+
+        return $this;
+    }
+
+    public function external(bool $external): static
+    {
+        $this->external = $external;
+
+        return $this;
+    }
+
+    public function indicator(bool $indicator): static
+    {
+        $this->indicator = $indicator;
+
+        return $this;
+    }
+
+    public function id(?string $id): static
+    {
+        $this->id = $id;
+
+        return $this;
+    }
+
+    public function iconOnly(bool $iconOnly): static
+    {
+        $this->iconOnly = $iconOnly;
+
+        return $this;
+    }
+
+    public function flush(bool $flush): static
+    {
+        $this->flush = $flush;
+
+        return $this;
+    }
+
+    public function content(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots[''] = $content;
+
+        return $this;
+    }
+
+    public function prefix(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['prefix'] = $content;
+
+        return $this;
+    }
+
+    public function iconSlot(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['icon'] = $content;
+
+        return $this;
+    }
+
+    public function suffix(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['suffix'] = $content;
+
+        return $this;
+    }
+
+    public function subnav(Closure|Htmlable|Stringable|string $content): static
+    {
+        $this->slots['subnav'] = $content;
+
+        return $this;
+    }
+
+    protected function tagName(): string
+    {
+        return 'craft-nav-item';
+    }
+
+    #[\Override]
+    protected function hostAttributes(): array
+    {
+        return [
+            'icon' => $this->icon,
+            'href' => $this->href,
+            'active' => $this->active === false ? null : $this->active,
+            'external' => $this->external === false ? null : $this->external,
+            'indicator' => $this->indicator === false ? null : $this->indicator,
+            'id' => $this->id,
+            'icon-only' => $this->iconOnly === false ? null : $this->iconOnly,
+            'flush' => $this->flush === false ? null : $this->flush,
+        ];
+    }
+}
diff --git a/src/Cp/Components/Indicator.php b/src/Cp/Components/Indicator.php
new file mode 100644
index 00000000000..74befbc7bdc
--- /dev/null
+++ b/src/Cp/Components/Indicator.php
@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components;
+
+use CraftCms\Cms\Component\Contracts\Statusable;
+use CraftCms\Cms\Cp\Components\Generated\IndicatorComponent;
+use CraftCms\Cms\Shared\Enums\Color;
+use CraftCms\Cms\Support\Arr;
+use CraftCms\Cms\Support\Html;
+use Illuminate\Contracts\Support\Htmlable;
+use Illuminate\Support\HtmlString;
+
+use function CraftCms\Cms\t;
+
+/**
+ * PHP counterpart to the `<craft-indicator>` web component.
+ *
+ * The fluent `fill`/`size`/`appearance`/`label` API is generated from the
+ * custom element manifest in {@see IndicatorComponent}; this class adds the
+ * control-panel status helpers on top.
+ */
+class Indicator extends IndicatorComponent
+{
+    /**
+     * Builds the control-panel status indicator for a given status.
+     *
+     * Most statuses render as a colored dot. The special `draft` status renders
+     * the draft icon instead. The accessible label is prefixed with "Status:".
+     *
+     * @param  array{label?: string|null, color?: string|Color|null}  $def  Status definition (see {@see Statusable::statuses()}).
+     * @param  array<string, mixed>  $attributes  Additional HTML attributes for the host element.
+     */
+    public static function forStatus(string $status, array $def = [], array $attributes = []): Htmlable
+    {
+        $label = array_key_exists('label', $def) ? $def['label'] : ucfirst($status);
+
+        if ($status === 'draft') {
+            return new HtmlString(Html::tag('span', '', Arr::merge($attributes, [
+                'data' => ['icon' => 'draft'],
+                'class' => 'icon',
+                'role' => 'img',
+                'aria' => [
+                    'label' => sprintf('%s %s', t('Status:'), $label ?? t('Draft')),
+                ],
+            ])));
+        }
+
+        return static::make()
+            ->fill(($def['color'] ?? null) ?? $status)
+            ->label(sprintf('%s %s', t('Status:'), $label))
+            ->attributes($attributes);
+    }
+
+    /**
+     * Convenience for {@see IndicatorComponent::appearance()} — renders the hollow (ring-only) variant.
+     */
+    public function empty(bool $empty = true): static
+    {
+        return $this->appearance($empty ? 'empty' : 'solid');
+    }
+}
diff --git a/src/Cp/Components/NavItem.php b/src/Cp/Components/NavItem.php
new file mode 100644
index 00000000000..632431545e3
--- /dev/null
+++ b/src/Cp/Components/NavItem.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components;
+
+use CraftCms\Cms\Cp\Components\Generated\NavItemComponent;
+
+/**
+ * PHP counterpart to the `<craft-nav-item>` web component.
+ *
+ * The fluent attribute and slot API is generated from the custom element
+ * manifest in {@see NavItemComponent}; add any bespoke behavior here.
+ */
+class NavItem extends NavItemComponent {}
diff --git a/src/Cp/Components/ViewComponent.php b/src/Cp/Components/ViewComponent.php
new file mode 100644
index 00000000000..2a87a9c3ff4
--- /dev/null
+++ b/src/Cp/Components/ViewComponent.php
@@ -0,0 +1,133 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Components;
+
+use Closure;
+use CraftCms\Cms\Support\Arr;
+use CraftCms\Cms\Support\Html;
+use Illuminate\Contracts\Support\Htmlable;
+use Stringable;
+
+/**
+ * Base class for PHP components that render a Craft custom element.
+ *
+ * Subclasses (typically generated from the custom elements manifest) provide
+ * the {@see self::tagName()} and {@see self::hostAttributes()}, plus typed
+ * fluent setters. This base supplies attribute merging and slot handling.
+ *
+ * Slot content is supplied as a closure (or a renderable value) and resolved
+ * lazily when {@see self::toHtml()} is called, so child components can be
+ * configured up until the parent is rendered. A slot callback may return a
+ * string, an {@see Htmlable}/{@see Stringable}, or another {@see ViewComponent}
+ * (which is rendered into the slot, with its `slot` attribute set for you).
+ */
+abstract class ViewComponent implements Htmlable, Stringable
+{
+    /** Key under which the default (unnamed) slot is stored. */
+    protected const DEFAULT_SLOT = '';
+
+    /** @var array<string, mixed> Additional host HTML attributes. */
+    protected array $attributes = [];
+
+    /** @var array<string, mixed> Slot content keyed by slot name. */
+    protected array $slots = [];
+
+    final public function __construct() {}
+
+    public static function make(): static
+    {
+        return app(static::class);
+    }
+
+    /**
+     * Merges additional HTML attributes (e.g. `class`) onto the host element.
+     *
+     * @param  array<string, mixed>  $attributes
+     */
+    public function attributes(array $attributes): static
+    {
+        $this->attributes = Arr::merge($this->attributes, $attributes);
+
+        return $this;
+    }
+
+    /**
+     * Assigns this component to a named slot of its parent.
+     */
+    public function slot(string $name): static
+    {
+        $this->attributes['slot'] = $name;
+
+        return $this;
+    }
+
+    /**
+     * The custom element tag name, e.g. `craft-nav-item`.
+     */
+    abstract protected function tagName(): string;
+
+    /**
+     * Host element attributes derived from the component's typed properties.
+     *
+     * @return array<string, mixed>
+     */
+    protected function hostAttributes(): array
+    {
+        return [];
+    }
+
+    public function toHtml(): string
+    {
+        return Html::tag(
+            $this->tagName(),
+            $this->renderSlots(),
+            Arr::merge($this->attributes, $this->hostAttributes()),
+        );
+    }
+
+    public function __toString(): string
+    {
+        return $this->toHtml();
+    }
+
+    /**
+     * Resolves and concatenates all assigned slot content.
+     */
+    protected function renderSlots(): string
+    {
+        $html = '';
+
+        foreach ($this->slots as $name => $content) {
+            $html .= $this->renderSlot($name, $content);
+        }
+
+        return $html;
+    }
+
+    protected function renderSlot(string $name, mixed $content): string
+    {
+        $resolved = $content instanceof Closure ? $content() : $content;
+
+        if ($resolved === null || $resolved === '') {
+            return '';
+        }
+
+        // A nested component drops straight into the named slot.
+        if ($name !== static::DEFAULT_SLOT && $resolved instanceof self) {
+            return $resolved->slot($name)->toHtml();
+        }
+
+        $rendered = $resolved instanceof Htmlable
+            ? $resolved->toHtml()
+            : Html::encode((string) $resolved);
+
+        if ($name === static::DEFAULT_SLOT) {
+            return $rendered;
+        }
+
+        // Other renderable content still needs a slotted wrapper element.
+        return Html::tag('span', $rendered, ['slot' => $name]);
+    }
+}
diff --git a/src/Cp/Html/StatusHtml.php b/src/Cp/Html/StatusHtml.php
index 849d4a1e3bc..f737df82357 100644
--- a/src/Cp/Html/StatusHtml.php
+++ b/src/Cp/Html/StatusHtml.php
@@ -5,7 +5,7 @@
 namespace CraftCms\Cms\Cp\Html;
 
 use CraftCms\Cms\Component\Contracts\Statusable;
-use CraftCms\Cms\Cp\Icons;
+use CraftCms\Cms\Cp\Components\Indicator;
 use CraftCms\Cms\Shared\Enums\Color;
 use CraftCms\Cms\Support\Html;
 use Illuminate\Container\Attributes\Singleton;
@@ -17,62 +17,29 @@
 {
     public function statusIndicatorHtml(string $status, array $attributes = []): ?string
     {
-        $attributes += [
-            'color' => null,
-            'label' => ucfirst($status),
-            'class' => $status,
-        ];
-
-        if ($status === 'draft') {
-            return Html::tag('span', '', [
-                'data' => ['icon' => 'draft'],
-                'class' => 'icon',
-                'role' => 'img',
-                'aria' => [
-                    'label' => sprintf('%s %s',
-                        t('Status:'),
-                        $attributes['label'] ?? t('Draft'),
-                    ),
-                ],
-            ]);
-        }
-
-        if ($attributes['color'] instanceof Color) {
-            $attributes['color'] = $attributes['color']->value;
-        }
+        $color = $attributes['color'] ?? null;
+        $label = array_key_exists('label', $attributes) ? $attributes['label'] : ucfirst($status);
+        unset($attributes['color'], $attributes['label']);
 
-        $options = [
-            'class' => array_filter([
-                'status',
-                $attributes['class'],
-                $attributes['color'],
-            ]),
-        ];
-
-        if ($attributes['label'] !== null) {
-            $options['role'] = 'img';
-            $options['aria']['label'] = sprintf('%s %s', t('Status:'), $attributes['label']);
-        }
-
-        return Html::tag('span', '', $options);
+        return Indicator::forStatus($status, ['color' => $color, 'label' => $label], $attributes)->toHtml();
     }
 
     public function componentStatusIndicatorHtml(Statusable $component): ?string
     {
         $status = $component->getStatus();
 
-        if ($status === 'draft') {
-            return $this->statusIndicatorHtml('draft');
+        if ($status === null) {
+            return null;
         }
 
         $statusDef = $component::statuses()[$status] ?? [];
 
-        // Just to give the `statusIndicatorHtml` clean types
+        // Just to give `Indicator::forStatus()` clean types
         if (is_string($statusDef)) {
             $statusDef = ['label' => $statusDef];
         }
 
-        return $this->statusIndicatorHtml($status, $statusDef);
+        return Indicator::forStatus($status, $statusDef)->toHtml();
     }
 
     public function statusLabelHtml(array $config = []): ?string
@@ -89,25 +56,23 @@ public function statusLabelHtml(array $config = []): ?string
         }
 
         if ($config['icon']) {
-            $html = Html::tag('span', Icons::svg($config['icon']), [
-                'class' => ['cp-icon', 'puny', $config['color']],
+            $html = Html::tag('craft-icon', '', [
+                'slot' => 'prefix',
+                'name' => $config['icon'],
             ]);
         } else {
-            $html = $this->statusIndicatorHtml($config['color'], [
-                'label' => null,
-                'class' => $config['indicatorClass'] ?? $config['color'],
-            ]);
+            $html = Indicator::make()
+                ->fill($config['color'])
+                ->attributes(['slot' => 'prefix'])
+                ->toHtml();
         }
 
         if ($config['label']) {
-            $html .= ' '.Html::tag('span', Html::encode($config['label']), ['class' => 'status-label-text']);
+            $html .= Html::encode($config['label']);
         }
 
-        return Html::tag('span', $html, [
-            'class' => array_filter([
-                'status-label',
-                $config['color'],
-            ]),
+        return Html::tag('craft-status-badge', $html, [
+            'data-color' => $config['color'],
         ]);
     }
 
diff --git a/src/Element/Concerns/HasControlPanelUI.php b/src/Element/Concerns/HasControlPanelUI.php
index 3e2ba0058e5..58238b139d7 100644
--- a/src/Element/Concerns/HasControlPanelUI.php
+++ b/src/Element/Concerns/HasControlPanelUI.php
@@ -713,18 +713,11 @@ public function getMetadata(): array
                         'aria' => ['hidden' => 'true'],
                     ]);
                     $label = t('Draft');
-                } else {
-                    $status = $this->getStatus();
-                    $statusDef = static::statuses()[$status] ?? null;
-                    $color = $statusDef['color'] ?? $status;
-                    if ($color instanceof Color) {
-                        $color = $color->value;
-                    }
-                    $icon = Html::tag('span', '', ['class' => ['status', $color]]);
-                    $label = $statusDef['label'] ?? $statusDef ?? ucfirst($status);
+
+                    return $icon.Html::tag('span', $label);
                 }
 
-                return $icon.Html::tag('span', $label);
+                return static::attributeHtml('status');
             },
         ], $metadata, [
             t('Created at') => $this->dateCreated && ! $this->getIsUnpublishedDraft()
diff --git a/tests/Feature/Element/ElementAttributeRendererTest.php b/tests/Feature/Element/ElementAttributeRendererTest.php
index f97882adb85..500b4c21af3 100644
--- a/tests/Feature/Element/ElementAttributeRendererTest.php
+++ b/tests/Feature/Element/ElementAttributeRendererTest.php
@@ -94,7 +94,7 @@
 
     $result = $this->renderer->render($entry, 'status');
 
-    expect((string) $result)->toContain('status-label');
+    expect((string) $result)->toContain('craft-status-badge');
 });
 
 it('renders empty string for generatedField when not found', function () {
diff --git a/tests/Unit/Cp/StatusHtmlTest.php b/tests/Unit/Cp/StatusHtmlTest.php
index 82b22cbcb1a..86215ba6d04 100644
--- a/tests/Unit/Cp/StatusHtmlTest.php
+++ b/tests/Unit/Cp/StatusHtmlTest.php
@@ -14,13 +14,14 @@
             ->and($html)->toContain('role="img"');
     });
 
-    it('renders standard status class and aria label', function () {
+    it('renders an indicator with the status fill and label', function () {
         $html = app(StatusHtml::class)->statusIndicatorHtml('enabled', [
             'label' => 'Enabled',
         ]);
 
-        expect($html)->toContain('class="status enabled"')
-            ->and($html)->toContain('aria-label="Status: Enabled"');
+        expect($html)->toContain('<craft-indicator')
+            ->and($html)->toContain('fill="enabled"')
+            ->and($html)->toContain('label="Status: Enabled"');
     });
 });
 
@@ -41,7 +42,10 @@ public function getStatus(): string
 
         $html = app(StatusHtml::class)->componentStatusIndicatorHtml($component);
 
-        expect($html)->toContain('status pending yellow');
+        expect($html)->toContain('<craft-indicator')
+            ->and($html)->toContain('fill="yellow"')
+            ->and($html)->toContain('label="Status: Pending"')
+            ->and($html)->not->toContain('color="yellow"');
     });
 
     it('renders component status label and edited status label', function () {
@@ -62,7 +66,7 @@ public function getStatus(): string
         $labelHtml = $statusHtml->componentStatusLabelHtml($component);
         $editedHtml = $statusHtml->editedStatusLabelHtml();
 
-        expect($labelHtml)->toContain('status-label')
+        expect($labelHtml)->toContain('craft-status-badge')
             ->and($labelHtml)->toContain('Pending')
             ->and($editedHtml)->toContain('Edited');
     });