@repobit/dex-system-design 1.0.1 → 2.0.1

package/src/components/divider/divider.css.js

@@ -3,7 +3,10 @@ import { css } from "lit";
 export const dividerHorizontal = css`
   .hr-line {
     border: none;
-    border-top: var(--border-width-1) solid var(--color-border-default);
+    /* --color-border-container, the rule every bare divider already rendered:
+       it used to be --color-border-default dimmed to 0.25, which composites to
+       the same colour. See divider-horizontal.js. */
+    border-top: var(--border-width-1) solid var(--color-border-container);
     margin: 0;
     width: 100%;
     margin-left: auto;

package/src/components/divider/divider.stories.js

@@ -33,12 +33,12 @@ Two divider components are available:
       control    : { type: 'select' },
       options    : ['primary', 'strong', 'muted', 'subtle', 'inverse', 'success', 'warning', 'error'],
       description: '(Horizontal) A semantic colour role, not a CSS colour.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: 'subtle' }, category: 'Horizontal' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "'' (--color-border-container)" }, category: 'Horizontal' }
     },
     hOpacity: {
       control    : 'text',
-      description: '(Horizontal) Opacity value between 0 and 1',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '0.25' }, category: 'Horizontal' }
+      description: '(Horizontal) Opacity from 0 to 1. Anything else is ignored. None by default.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Horizontal' }
     },
     height: {
       control: { type: 'select' },
@@ -49,8 +49,8 @@ Two divider components are available:
     },
     thickness: {
       control    : 'text',
-      description: '(Vertical) Width/thickness of the line e.g. "1px"',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '1px' }, category: 'Vertical' }
+      description: '(Vertical) A border-width step — 0, 1, 2, 3, 4 or 8, also written "1px" etc. Resolves to var(--border-width-N); anything else is the 1px step.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '1' }, category: 'Vertical' }
     },
     vColor: {
       control    : { type: 'select' },
@@ -71,7 +71,7 @@ Two divider components are available:
 export const HorizontalDefault = {
   name      : 'Horizontal — Default',
   render    : () => html`<bd-divider-horizontal></bd-divider-horizontal>`,
-  parameters: { docs: { description: { story: 'Default horizontal divider with default color and 0.25 opacity.' } } }
+  parameters: { docs: { description: { story: 'Default horizontal divider: --color-border-container at full strength, no opacity.' } } }
 };
 
 export const HorizontalFullWidth = {

package/src/components/dropdown/dropdown.js

@@ -7,10 +7,26 @@ import dropdownCSS from "../dropdown/dropdown.css.js";
 import { resolveSize } from '../shared/prop-vocabulary.js';
 
 
+/* options is a JSON array, as a property or as an attribute. Anything else --
+   malformed JSON, a comma list, a JSON object, a removed attribute -- is no
+   options rather than a crash. type: Array could not say that: Lit's Array
+   converter turns unparseable text into null before the setter sees it, and
+   render() then threw on null.map, so the field drew nothing at all. */
+const toOptions = value => {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string") return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+};
+
 class CustomDropdown extends LitElement {
   static properties = {
     label    : { type: String },
-    options  : { type: Array },
+    options  : { converter: { fromAttribute: toOptions } },
     size     : { type: String, reflect: true },
     /** @deprecated pass `size`. It named the size, not the kind. */
     kind     : { type: String },
@@ -19,6 +35,12 @@ class CustomDropdown extends LitElement {
     invalid  : { type: Boolean },
     validated: { type: Boolean },
     disabled : { type: Boolean },
+    /* The chosen option, and what the events carry, so a form handler written
+       for bd-custom-input reads this one unchanged. It always names an option
+       that exists: unset, or set to one that is not there, it is the first. */
+    value    : { type: String },
+    /** Carried on the event detail, as on bd-custom-input. */
+    name     : { type: String },
     /* Whether the native picker is showing. A best effort, not a fact: a
        <select> renders its popup in the OS, so the page is never told when it
        opens or closes. See _onSelectMouseDown. */
@@ -37,6 +59,8 @@ class CustomDropdown extends LitElement {
     this.invalid = false;
     this.validated = false;
     this.disabled = false;
+    this.value = "";
+    this.name = "";
     this._open = false;
   }
 
@@ -97,15 +121,7 @@ class CustomDropdown extends LitElement {
   }
 
   set options(val) {
-    if (typeof val === "string") {
-      try {
-        this._options = JSON.parse(val);
-      } catch {
-        this._options = [];
-      }
-    } else {
-      this._options = val;
-    }
+    this._options = toOptions(val);
   }
 
   get options() {
@@ -116,6 +132,37 @@ class CustomDropdown extends LitElement {
     // so it moved; see shared/prop-vocabulary.js
     if (changed.has("kind") && this.kind) this.size = this.kind;
     if (changed.has("size") || changed.has("kind")) this.size = resolveSize(this.size);
+    if (!this.options.map(String).includes(this.value)) this.value = this.options.length ? String(this.options[0]) : "";
+  }
+
+  /* The select is told its value after its options exist. A binding on the
+     <select> would be committed before the options inside it rendered, and
+     an option's selected attribute stops counting once a visitor has chosen,
+     so neither could move the selection when value is set from outside. */
+  updated() {
+    const select = this.shadowRoot.querySelector("select");
+    if (select && select.value !== this.value) select.value = this.value;
+  }
+
+  /* WHY TWO EVENTS FOR ONE CHOICE.
+     This dispatched nothing: choosing an option changed nothing observable
+     from outside, and the chosen value could only be read by reaching into
+     the shadow root. The native change and input do not help -- change is not
+     composed, so it never leaves the shadow root, and input arrives
+     retargeted to the host with no value on it.
+
+     A select commits the moment an option is chosen, so its input and change
+     are the same moment. Both are sent anyway, with bd-custom-input's names,
+     detail and flags, so a handler written for a form of inputs -- live
+     validation on bd-input, saving on bd-change -- needs nothing special for
+     this field. */
+  _onChange(e) {
+    this._closePicker();
+    this.value = e.target.value;
+    const detail = { value: this.value, name: this.name };
+    for (const type of ["bd-input", "bd-change"]) {
+      this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+    }
   }
 
   render() {
@@ -145,6 +192,10 @@ class CustomDropdown extends LitElement {
         ? "form-help-text--success"
         : "form-help-text--default";
 
+    // The hint is the select's description, and the state is announced, not
+    // only drawn: invalid used to be a red border alone and the hint was never
+    // pointed at, so the reason a field was invalid reached a screen reader
+    // not at all. Both as bd-custom-input does them.
     return html`
       <div class="input-container">
         ${this.label
@@ -161,13 +212,16 @@ class CustomDropdown extends LitElement {
             class="form-input-bd ${inputClass} ${inputStateClass}"
             ?required="${this.required}"
             ?disabled="${this.disabled}"
+            aria-invalid="${this.invalid ? "true" : nothing}"
+            aria-describedby="${this.tooltip ? "custom-dropdown-help" : nothing}"
             @mousedown="${this._onSelectMouseDown}"
             @keydown="${this._onSelectKeyDown}"
-            @change="${this._closePicker}"
+            name="${this.name || nothing}"
+            @change="${this._onChange}"
             @blur="${this._closePicker}"
           >
             ${this.options.map(
-              (option, index) => html`<option value="${option}" ?selected="${index === 0}">
+              option => html`<option value="${option}" ?selected="${String(option) === this.value}">
                 ${option}
               </option>`
             )}
@@ -178,7 +232,7 @@ class CustomDropdown extends LitElement {
           ></bd-arrow-down-icon>
         </div>
         ${this.tooltip
-          ? html`<div class="form-help-text ${helpTextClass}">
+          ? html`<div id="custom-dropdown-help" class="form-help-text ${helpTextClass}">
               ${this.tooltip}
             </div>`
           : ""}

package/src/components/dropdown/dropdown.stories.js

@@ -55,20 +55,21 @@ descender.
   stories under **Atoms/Input**. They are one component; the Atoms/Input page
   carries the fuller write-up.
 
-### Known gaps
-Three things the sibling \`bd-custom-input\` has and this does not. They are
-listed here because the states above imply a parity that is not there yet:
-
-- **No \`value\` and no event.** Nothing is emitted when a selection changes, so
-  the chosen option cannot be read without reaching into the shadow root. The
-  input's \`value\` property plus \`bd-input\` / \`bd-change\` is the pattern to
-  copy.
-- **\`invalid\` is colour only.** It sets a red border but no
-  \`aria-invalid="true"\`, so a screen reader is told nothing. The input sets it.
-- **\`tooltip\` is not announced.** It renders as help text but the select does
-  not point at it with \`aria-describedby\`, so when it carries the reason a
-  field is invalid, that reason is visual only.
-
+### Value and events
+\`value\` is the chosen option — read it, or set it to choose one; unset, or
+set to an option that is not there, it is the first. Choosing an option fires
+\`bd-input\` and then \`bd-change\`, both with \`detail\` \`{ value, name }\`,
+bubbling and composed — the same names, shape and flags as
+\`bd-custom-input\`, so one form handler reads both. A select commits on choice,
+so the two arrive together.
+
+### Accessibility
+\`invalid\` sets \`aria-invalid="true"\` on the select as well as the red
+border, and \`tooltip\` is the select's description through
+\`aria-describedby\`, so the reason a field is invalid is announced, not only
+drawn — as on \`bd-custom-input\`.
+
+### Known gap
 Being in a shadow root, the select also does not participate in an enclosing
 \`<form>\` — a \`<form>\` containing it yields no \`FormData\` entry.
         `

package/src/components/fieldset/fieldset.stories.js

@@ -1,8 +1,7 @@
 import { html } from 'lit';
 import './fieldset.js';
 import '../switch/switch.js';
-import '../label/label.js';
-import '../help-text/help-text.js';
+import '../radio/radio.js';
 import '../input/input.js';
 
 export default {
@@ -37,6 +36,14 @@ they are choosing between. The \`legend\` is what supplies that.
 Because slotted controls sit inside the \`<fieldset>\` in the flattened tree, the
 native grouping does apply here — unlike a \`for\` reference, which cannot cross
 the shadow boundary.
+
+### Labelling the fields inside it
+Give each field its own label and hint through its own props —
+\`label\`, \`required\` and \`tooltip\` on \`bd-custom-input\` — not a
+\`<bd-label for>\` and a \`<bd-help-text>\` beside it. The field keeps its
+\`<input>\` in its own shadow root, and a \`for\` or an \`aria-describedby\`
+in another tree resolves to nothing there: the field is then named only by its
+placeholder, which disappears as soon as anyone types.
         `
       }
     }
@@ -50,6 +57,22 @@ the shadow boundary.
   }
 };
 
+/**
+ * The case the docs are about: a choice among radios, named by the legend.
+ * Each radio's own label says only "Basic" or "Premium"; the legend is what
+ * says they are plans. It renders the usage example above, so the page shows
+ * the grouping it describes rather than only asserting it.
+ */
+export const ChooseOne = {
+  name  : 'Choose one — radios under a legend',
+  render: () => html`
+    <bd-fieldset legend="Choose your plan">
+      <bd-radio name="plan" value="basic" label="Basic"></bd-radio>
+      <bd-radio name="plan" value="premium" label="Premium"></bd-radio>
+    </bd-fieldset>
+  `
+};
+
 export const Default = () => html`
     <bd-fieldset legend="Notifications">
       <bd-switch label="Email"></bd-switch>
@@ -63,22 +86,24 @@ export const Default = () => html`
  * `--form-help-text-default-marginTop`. None of those three is visible in a
  * fieldset of bare switches, so this story is the one that shows them — it is
  * where a change to the form spacing tokens actually appears.
+ *
+ * Each label and hint is the field's own, through its label / required /
+ * tooltip props. This story used to pair <bd-label for="line1"> and a
+ * <bd-help-text> with an unlabelled field, and no for in it resolved: the
+ * three fields were named by their placeholders and the hints described
+ * nothing. The field's own props wire the label and aria-describedby inside
+ * its shadow root, where the <input> is.
  */
 export const FieldStack = () => html`
     <bd-fieldset legend="Billing address">
-      <div>
-        <bd-label for="line1" required>Street</bd-label>
-        <bd-custom-input label="" size="md" placeholder="221B Baker Street"></bd-custom-input>
-        <bd-help-text>Include the building number.</bd-help-text>
-      </div>
-      <div>
-        <bd-label for="city" required>City</bd-label>
-        <bd-custom-input label="" size="md" placeholder="London"></bd-custom-input>
-      </div>
-      <div>
-        <bd-label for="post">Postcode</bd-label>
-        <bd-custom-input label="" size="md" placeholder="NW1 6XE"></bd-custom-input>
-        <bd-help-text tone="error">We could not find that postcode.</bd-help-text>
-      </div>
+      <bd-custom-input
+        label="Street" required size="md" placeholder="221B Baker Street"
+        tooltip="Include the building number."
+      ></bd-custom-input>
+      <bd-custom-input label="City" required size="md" placeholder="London"></bd-custom-input>
+      <bd-custom-input
+        label="Postcode" size="md" placeholder="NW1 6XE"
+        invalid tooltip="We could not find that postcode."
+      ></bd-custom-input>
     </bd-fieldset>
   `;

package/src/components/footer/footer-nav-menu.css.js

@@ -37,7 +37,12 @@ export default css`
      Spelled ::slotted, which is the only selector that crosses this boundary,
      and :focus-visible so a mouse click does not draw it. */
   ::slotted(a:focus-visible) {
-    outline: none;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/footer/footer.css.js

@@ -36,7 +36,12 @@ export default css`
 .country-toggle:focus,
 .close-countries-button:focus,
 .social-icons a:focus {
-  outline: none;
+  /* forced-colors mode does not paint box-shadow, so the ring
+     vanishes there; it does paint an outline, in a system colour. This one
+     is transparent everywhere else, and the offset lands it on the ring's
+     outer band. */
+  outline: var(--border-width-2) solid transparent;
+  outline-offset: var(--focus-outline-offset);
   /* The ring is --focus-outline-primary alone, as in every other component.
      The 2px border that stood here was redundant and, since these elements
      have no border otherwise, it shifted the layout by 2px on focus. */

package/src/components/header/header-code.js

@@ -176,7 +176,7 @@ class HeaderCode extends LitElement {
           </div>
 
           ${this.eyebrow
-            ? html`<bd-p variant="regular" class="bd-headercode-eyebrow">${this.eyebrow}</bd-p>`
+            ? html`<bd-p variant="eyebrow" class="bd-headercode-eyebrow">${this.eyebrow}</bd-p>`
             : nothing}
 
           <bd-h as="${this._headingTag}" visual-level="h1" class="bd-headercode-title">

package/src/components/header/header.css.js

@@ -36,7 +36,12 @@ export default css`
      failure mode as the bare descendant selector this replaced. */
   ::slotted(a:focus-visible) {
     /* the one focus ring — see Foundations/Focus */
-    outline: none;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
     border-radius: var(--focus-outline-radius);
   }
@@ -736,9 +741,9 @@ export default css`
        :host { height: var(--bd-icon-size, ...) }, and a consuming rule and a
        :host rule match the SAME element, where the outer tree wins -- the same
        mechanism scripts/atom-inert-properties.json records for colour on a
-       bd-p host. --bd-icon-size, which the element sets inline from its size prop, is
-       deliberately not what is overridden here: an inline custom property
-       would beat this rule.
+       bd-p host. Setting --bd-icon-size here would work as well, since the
+       atom now sets it from a :host rule rather than inline; height is kept
+       because it was measured, and it says the job directly.
        .
        sm on the icon scale is 16px, so the mark renders 121 wide -- 47% of a
        256px panel. --bd-header-mark-height above is set to the same step, so

package/src/components/heading/heading.stories.js

@@ -8,25 +8,42 @@ export default {
     docs: {
       description: {
         component: `
-**BdH** is a Lit heading component that renders semantic HTML heading elements (h1–h6) with configurable styling.
+**BdH** renders a semantic heading, \`<h1>\`–\`<h6>\`, on the system's type scale.
 
 ### Usage
 \`\`\`html
 <bd-h as="h1">Page Title</bd-h>
+<bd-h as="h2" visual-level="h3">A component section inside a page section</bd-h>
 <bd-h as="h3" color="primary" fontWeight="bold" paddingBottom="16">Section Title</bd-h>
 \`\`\`
 
-### Valid Heading Tags
-\`h1\`, \`h2\`, \`h3\`, \`h4\`, \`h5\`, \`h6\` — falls back to \`h1\` for invalid values.
-
-### Style Prop Validation
-- **fontWeight**: accepts numeric strings (\`"100"\`–\`"900"\`) and keyword values (\`"normal"\`, \`"bold"\`, \`"lighter"\`, \`"bolder"\`)
-- **color**: accepts \`var(--...)\`, \`#hex\`, \`rgb(...)\`, \`hsl(...)\` — rejects bare color names
-- **padding / paddingBottom**: any valid CSS value string
-
-### Notes
-- \`ariaLevel\` can override the implicit ARIA level for accessibility
-- Styles are applied inline via \`_computeStyles()\`
+### Level and size are two questions
+\`as\` is the document outline — which heading element is rendered — and
+belongs to the composing page. \`visual-level\` is the type role — which step of
+the heading scale it looks like — and follows \`as\` when omitted. Both take
+\`h1\`–\`h6\` or \`1\`–\`6\`. An \`as\` that is not a heading level renders an
+\`h2\`: still a heading, never the page's \`h1\`.
+
+Change the size with \`visual-level\`, not with \`aria-level\`: an \`aria-level\`
+that disagrees with the element tells assistive technology one level and the
+outline another.
+
+### Style props take steps, not CSS
+Each resolves to a token; a value that is not a step is dropped and the
+heading keeps its own styling.
+
+- **fontWeight** — \`light\`, \`normal\`, \`medium\`, \`semibold\`, \`bold\`, each
+  \`var(--typography-fontWeight-*)\`. The scale stops at \`bold\`; numbers are
+  not accepted.
+- **color** — a text role, not a CSS colour: \`primary\` (the brand text role,
+  \`--color-text-brand\`), \`strong\` (\`--color-text-primary\`), \`muted\`,
+  \`subtle\`, \`inverse\`, \`success\`, \`warning\`, \`error\`. Hex, \`rgb()\`,
+  \`var()\` and colour keywords are all dropped.
+- **padding** — one to four spacing steps, e.g. \`24 40\`, each
+  \`var(--spacing-N)\`; if any part is off the scale the whole value is dropped.
+  **paddingBottom** — one spacing step.
+
+The resolved values are applied as an inline style on the rendered heading.
         `
       }
     }
@@ -35,12 +52,18 @@ export default {
     as: {
       control    : { type: 'select' },
       options    : ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
-      description: 'Which heading tag to render. Falls back to `h1` if invalid.',
+      description: 'Which heading element to render — the document outline. Falls back to `h2` if it is not a heading level.',
       table      : { type: { summary: "'h1'|'h2'|'h3'|'h4'|'h5'|'h6'" }, defaultValue: { summary: 'h1' }, category: 'Semantic' }
     },
+    visualLevel: {
+      control    : { type: 'select' },
+      options    : ['', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      description: 'Which step of the heading type scale to render. Follows `as` when empty.',
+      table      : { type: { summary: "'h1'…'h6' | '1'…'6'" }, defaultValue: { summary: 'as' }, category: 'Semantic' }
+    },
     ariaLevel: {
       control    : 'number',
-      description: 'Overrides the implicit ARIA level (e.g. for accessibility when visual level differs from semantic level)',
+      description: 'Overrides the element\'s ARIA level. Rarely right: to make a heading look a different size, use `visual-level`; to change its place in the outline, change `as`.',
       table      : { type: { summary: 'number' }, defaultValue: { summary: 'null' }, category: 'Accessibility' }
     },
     padding: {
@@ -73,6 +96,7 @@ export default {
 const render = (args) => html`
   <bd-h
     as="${args.as}"
+    visual-level="${args.visualLevel}"
     padding="${args.padding}"
     paddingBottom="${args.paddingBottom}"
     fontWeight="${args.fontWeight}"
@@ -82,7 +106,7 @@ const render = (args) => html`
   </bd-h>
 `;
 
-const defaultArgs = { as: 'h2', padding: '', paddingBottom: '', fontWeight: '', color: '' };
+const defaultArgs = { as: 'h2', visualLevel: '', padding: '', paddingBottom: '', fontWeight: '', color: '' };
 
 // ─── Stories ───────────────────────────────────────────────────────────────
 
@@ -111,13 +135,13 @@ export const CustomColor = {
   name  : 'Custom Color',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:12px;">
-      <bd-h as="h2" color="primary">primary — var(--color-blue-600)</bd-h>
-      <bd-h as="h2" color="error">error — var(--color-red-700)</bd-h>
-      <bd-h as="h2" color="success">success — var(--color-green-800)</bd-h>
-      <bd-h as="h2" color="strong">strong — var(--color-neutral-900)</bd-h>
+      <bd-h as="h2" color="primary">primary — --color-text-brand</bd-h>
+      <bd-h as="h2" color="error">error — --color-text-error</bd-h>
+      <bd-h as="h2" color="success">success — --color-text-success</bd-h>
+      <bd-h as="h2" color="strong">strong — --color-text-primary</bd-h>
     </div>
   `,
-  parameters: { docs: { description: { story: 'Headings with hex colors and a CSS variable token. Bare color names like "blue" are rejected by `_getValidColor()`.' } } }
+  parameters: { docs: { description: { story: '`color` takes a text role and resolves it to that role\'s token. Each label names the role it reads, not today\'s value.' } } }
 };
 
 export const FontWeights = {
@@ -131,7 +155,7 @@ export const FontWeights = {
       <bd-h as="h3" fontWeight="bold">bold (700)</bd-h>
     </div>
   `,
-  parameters: { docs: { description: { story: 'Various font weights from light (300) to black (900). Invalid weights like "purple" are silently ignored.' } } }
+  parameters: { docs: { description: { story: 'The five weight steps, light (300) to bold (700); the scale has nothing heavier. A value that is not a step is ignored.' } } }
 };
 
 export const CustomPadding = {
@@ -144,37 +168,46 @@ export const CustomPadding = {
       <bd-h as="h3" paddingBottom="32">With Padding Bottom Only</bd-h>
     </div>
   `,
-  parameters: { docs: { description: { story: 'Demonstrates `padding` shorthand and `paddingBottom` applied inline.' } } }
+  parameters: { docs: { description: { story: '`padding` takes one to four spacing steps and `paddingBottom` one, applied inline.' } } }
+};
+
+export const VisualLevel = {
+  name  : 'Level and size apart',
+  render: () => html`
+    <bd-h as="h2" visual-level="h4">An h2 in the outline, at the h4 size</bd-h>
+    <bd-h as="h4" visual-level="h2">An h4 in the outline, at the h2 size</bd-h>
+  `,
+  parameters: { docs: { description: { story: '`as` sets the element and `visual-level` the type step, so a heading keeps its place in the outline at whatever size the design needs. This is the tool for a level that has to look different — not `aria-level`.' } } }
 };
 
 export const AriaLevelOverride = {
   name  : 'ARIA Level Override',
   render: () => html`
     <p style="font-size:14px; margin-bottom:8px;">
-      Visually renders as <code>h4</code> but has <code>aria-level="2"</code>.
+      An <code>h4</code> element carrying <code>aria-level="2"</code>.
     </p>
     <bd-h as="h4" aria-level="2" color="primary">
-      Visually h4, semantically level 2
+      An h4 element, announced as level 2
     </bd-h>
   `,
-  parameters: { docs: { description: { story: '`ariaLevel` overrides the implicit ARIA heading level for accessibility without changing the visual rendering.' } } }
+  parameters: { docs: { description: { story: '`ariaLevel` overrides the level assistive technology announces without changing the element. The element and the announced level then disagree, so prefer `as` with `visual-level` (see "Level and size apart"); this is for the rare page that cannot change the element.' } } }
 };
 
 export const InvalidTag = {
-  name  : 'Invalid Tag (fallback to h1)',
+  name  : 'Invalid Tag (fallback to h2)',
   render: () => html`
-    <bd-h as="div">This falls back to h1</bd-h>
+    <bd-h as="div">This falls back to h2</bd-h>
   `,
-  parameters: { docs: { description: { story: '`as="div"` is not a valid heading tag — component falls back to rendering `<h1>`.' } } }
+  parameters: { docs: { description: { story: '`as="div"` is not a heading level, so the component renders an `<h2>` — still a heading, never the page\'s `<h1>`.' } } }
 };
 
 export const InvalidColor = {
   name  : 'Invalid Color (silently ignored)',
   render: () => html`
     <bd-h as="h3" color="blue">A bare CSS keyword is not a role, so it is dropped and the heading keeps its own colour</bd-h>
-    <bd-h as="h3" color="primary">color="primary" resolves to var(--color-blue-600)</bd-h>
+    <bd-h as="h3" color="primary">color="primary" resolves to --color-text-brand</bd-h>
   `,
-  parameters: { docs: { description: { story: 'Bare color name `"blue"` is rejected by `_getValidColor()` and falls back to the default color. `"#026DFF"` is accepted.' } } }
+  parameters: { docs: { description: { story: '`color="blue"` is not a role, so it is dropped and the heading keeps its own colour. Hex values and `var()` are dropped the same way.' } } }
 };
 
 export const Combined = {
@@ -191,5 +224,5 @@ export const Playground = {
   name      : '🛝 Playground',
   args      : { ...defaultArgs },
   render,
-  parameters: { docs: { description: { story: 'Interactive playground. Adjust `as`, `color`, `fontWeight`, `padding`, and `paddingBottom` via Controls.' } } }
+  parameters: { docs: { description: { story: 'Interactive playground. Adjust `as`, `visual-level`, `color`, `fontWeight`, `padding`, and `paddingBottom` via Controls.' } } }
 };