@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/radio/radio.js

@@ -1,8 +1,24 @@
 import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import radioCSS from "./radio.css.js";
 
+const NEXT_KEYS = ["ArrowDown", "ArrowRight"];
+const PREV_KEYS = ["ArrowUp", "ArrowLeft"];
+
+/**
+ * A single radio. Selecting one clears the others sharing its `name`, and the
+ * arrow keys move between them.
+ *
+ * The group behaviour is worked out by finding same-name siblings in the same
+ * root, because there is no group element yet. That covers exclusivity, arrow
+ * navigation and the roving tabindex, but it cannot supply role="radiogroup"
+ * or a group label — those need an owning element, so a screen reader still
+ * gets no "1 of 4" context. A bd-radio-group is the missing piece.
+ */
 class BdRadio extends LitElement {
+  static styles = [radioCSS];
+
   static properties = {
     name    : { type: String },
     value   : { type: String },
@@ -11,105 +27,109 @@ class BdRadio extends LitElement {
     label   : { type: String }
   };
 
-  static styles = [tokens, radioCSS];
-
   constructor() {
     super();
     this.name = "";
     this.value = "";
+    // checked was left undefined, which rendered aria-checked="" — not a valid
+    // value, so an unselected radio announced no state at all
+    this.checked = false;
     this.disabled = false;
     this.label = "";
-    this._hadKeyboardFocus = false;
-
-    this._handleDocumentKeydown = (e) => {
-      if (e.key === "Tab") {
-        this._hadKeyboardFocus = true;
-      }
-    };
-
-    this._handleDocumentMousedown = () => {
-      setTimeout(() => {
-        this._hadKeyboardFocus = false;
-      }, 0);
-    };
   }
 
-  connectedCallback() {
-    super.connectedCallback();
-    document.addEventListener("keydown", this._handleDocumentKeydown);
-    document.addEventListener("mousedown", this._handleDocumentMousedown);
+  /** Same-name radios in this root, in document order. */
+  get _group() {
+    if (!this.name) return [this];
+    const root = this.getRootNode();
+    const scope = root instanceof Document || root instanceof ShadowRoot ? root : document;
+    return [...scope.querySelectorAll(`bd-radio[name="${this.name}"]`)];
   }
 
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    document.removeEventListener("keydown", this._handleDocumentKeydown);
-    document.removeEventListener("mousedown", this._handleDocumentMousedown);
+  /**
+   * One tab stop per group, as the radiogroup pattern requires: the selected
+   * radio, or the first enabled one when nothing is selected yet.
+   */
+  get _tabbable() {
+    if (this.disabled) return false;
+    const group = this._group;
+    if (group.some(r => r.checked)) return this.checked;
+    return group.find(r => !r.disabled) === this;
   }
 
-  handleKeydown(e) {
-    if (this.disabled) return;
-    if (e.key === " " || e.key === "Enter") {
-      e.preventDefault();
-      this.handleChange();
-    }
-  }
+  _select() {
+    if (this.disabled || this.checked) return;
 
-  handleFocus(e) {
-    if (this._hadKeyboardFocus) {
-      e.target.classList.add("focus");
+    // the defining behaviour of a radio, and the part that was missing: the
+    // rest of the group has to let go
+    for (const radio of this._group) {
+      if (radio !== this && radio.checked) radio.checked = false;
     }
-  }
-  handleBlur(e) {
-    e.target.classList.remove("focus");
-  }
-  handleChange() {
-    if (this.disabled) {
-      console.warn("Blocked because disabled = true");
-      return;
-    }
-
     this.checked = true;
 
-    this.updateComplete.then(() => {
-      const outer = this.renderRoot.querySelector(".bd-outer");
-      if (outer) {
-        outer.focus();
-      }
-    });
-
     this.dispatchEvent(
       new CustomEvent("change", {
-        detail  : { value: this.value },
+        detail  : { name: this.name, value: this.value },
         bubbles : true,
         composed: true
       })
     );
   }
 
+  /** Move to the next or previous enabled radio, select it, and focus it. */
+  _move(step) {
+    const enabled = this._group.filter(r => !r.disabled);
+    if (enabled.length < 2) return;
+    const from = enabled.indexOf(this);
+    const next = enabled[(from + step + enabled.length) % enabled.length];
+    next._select();
+    next.updateComplete.then(() => {
+      next.shadowRoot.querySelector(".bd-radio")?.focus();
+    });
+  }
+
+  _handleKeydown(e) {
+    if (this.disabled) return;
+
+    if (NEXT_KEYS.includes(e.key)) {
+      e.preventDefault();
+      this._move(1);
+    } else if (PREV_KEYS.includes(e.key)) {
+      e.preventDefault();
+      this._move(-1);
+    } else if (e.key === " ") {
+      e.preventDefault();
+      this._select();
+    }
+  }
+
   render() {
     return html`
-      <label class="bd-radio ${this.disabled ? "disabled" : ""}">
-        <span
-          class="bd-outer ${this.checked && !this.disabled ? "checked" : ""}"
-          role="radio"
-          aria-checked="${this.checked}"
-          aria-disabled="${this.disabled}"
-          tabindex="${this.disabled ? -1 : 0}"
-          @click=${this.handleChange}
-          @keydown=${this.handleKeydown}
-          @focus=${this.handleFocus}
-          @blur=${this.handleBlur}
-        >
-          <span class="bd-inner ${this.checked ? "visible" : ""}"></span>
-        </span>
-        <span class="radio-label">${this.label}</span>
-      </label>
+      <div
+        class="bd-radio"
+        role="radio"
+        aria-checked="${this.checked ? "true" : "false"}"
+        aria-disabled="${this.disabled ? "true" : "false"}"
+        tabindex="${this._tabbable ? 0 : -1}"
+        @click=${this._select}
+        @keydown=${this._handleKeydown}
+      >
+        <span class="box" part="box"><span class="dot"></span></span>
+        <span class="label" part="label"><slot>${this.label}</slot></span>
+      </div>
     `;
   }
 }
 
+/**
+ * Toggles independently despite looking like a radio, which is why it declares
+ * role="checkbox". It duplicates bd-checkbox with a circular skin, and a round
+ * control that does not behave exclusively misleads people — it should be
+ * retired in favour of bd-checkbox. Kept working here because it is a
+ * published element with stories against it.
+ */
 class BdToggleRadio extends LitElement {
-  static styles = [tokens, radioCSS];
+  static styles = [radioCSS];
 
   static properties = {
     name    : { type: String },
@@ -123,90 +143,49 @@ class BdToggleRadio extends LitElement {
     super();
     this.name = "";
     this.value = "";
+    this.checked = false;
     this.disabled = false;
     this.label = "";
-    this._hadKeyboardFocus = false;
-
-    this._handleDocumentKeydown = (e) => {
-      if (e.key === "Tab") {
-        this._hadKeyboardFocus = true;
-      }
-    };
-
-    this._handleDocumentMousedown = () => {
-      setTimeout(() => {
-        this._hadKeyboardFocus = false;
-      }, 0);
-    };
-  }
-
-  connectedCallback() {
-    super.connectedCallback();
-    document.addEventListener("keydown", this._handleDocumentKeydown);
-    document.addEventListener("mousedown", this._handleDocumentMousedown);
   }
 
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    document.removeEventListener("keydown", this._handleDocumentKeydown);
-    document.removeEventListener("mousedown", this._handleDocumentMousedown);
-  }
-
-  handleClick() {
+  _toggle() {
     if (this.disabled) return;
     this.checked = !this.checked;
 
     this.dispatchEvent(
       new CustomEvent("change", {
-        detail  : { value: this.checked ? this.value : null },
+        detail  : { checked: this.checked, value: this.checked ? this.value : null },
         bubbles : true,
         composed: true
       })
     );
   }
 
-  handleFocus(e) {
-    if (this._hadKeyboardFocus) {
-      e.target.classList.add("focus");
-    }
-  }
-
-  handleBlur(e) {
-    e.target.classList.remove("focus");
-  }
-
-  handleKeydown(e) {
+  _handleKeydown(e) {
     if (this.disabled) return;
     if (e.key === " " || e.key === "Enter") {
       e.preventDefault();
-      this.handleClick();
+      this._toggle();
     }
   }
 
-
   render() {
     return html`
-      <label class="bd-radio ${this.disabled ? "disabled" : ""}">
-        <span
-          class="bd-outer ${this.checked && !this.disabled ? "checked" : ""}"
-          role="checkbox"
-          aria-checked="${this.checked}"
-          aria-disabled="${this.disabled}"
-          tabindex="${this.disabled ? -1 : 0}"
-          @click=${this.handleClick}
-          @keydown=${this.handleKeydown}
-          @focus=${this.handleFocus}
-          @blur=${this.handleBlur}
-        >
-          <span class="bd-inner ${this.checked ? "visible" : ""}"></span>
-        </span>
-        <span class="radio-label">${this.label}</span>
-      </label>
+      <div
+        class="bd-radio"
+        role="checkbox"
+        aria-checked="${this.checked ? "true" : "false"}"
+        aria-disabled="${this.disabled ? "true" : "false"}"
+        tabindex="${this.disabled ? -1 : 0}"
+        @click=${this._toggle}
+        @keydown=${this._handleKeydown}
+      >
+        <span class="box" part="box"><span class="dot"></span></span>
+        <span class="label" part="label"><slot>${this.label}</slot></span>
+      </div>
     `;
   }
 }
-BdRadio.styles = [tokens, radioCSS];
-BdToggleRadio.styles = [tokens, radioCSS];
 
 customElements.define("bd-toggle-radio", BdToggleRadio);
 customElements.define("bd-radio", BdRadio);

package/src/components/radio/radio.stories.js

@@ -2,39 +2,74 @@ import { html } from 'lit';
 import './radio.js';
 
 export default {
-  title     : 'Components/Radio',
+  title     : 'Atoms/Radio',
   tags      : ['autodocs'],
   parameters: {
     docs: {
       description: {
         component: `
-Two radio components are available:
-
-- \`<bd-radio>\` — a standard radio button (once selected, stays selected; dispatches value on change)
-- \`<bd-toggle-radio>\` — a toggleable radio that can be unchecked again (behaves like a checkbox with radio styling)
+- \`<bd-radio>\` — one choice from a group. Selecting one clears the others
+  that share its \`name\`.
+- \`<bd-toggle-radio>\` — **deprecated.** It is circular like a radio but
+  declares \`role="checkbox"\` and toggles independently, so it looks exclusive
+  and is not. Use \`<bd-checkbox>\` instead.
 
 ### Usage
 \`\`\`html
-<bd-radio name="plan" value="basic" label="Basic Plan"></bd-radio>
-<bd-radio name="plan" value="premium" label="Premium Plan" checked></bd-radio>
-<bd-toggle-radio name="addon" value="vpn" label="Add VPN"></bd-toggle-radio>
+<bd-radio name="plan" value="basic" label="Basic"></bd-radio>
+<bd-radio name="plan" value="premium" label="Premium" checked></bd-radio>
+
+<!-- the label is slotted, so it can carry markup -->
+<bd-radio name="plan" value="custom">See the <a href="/plans">plans</a></bd-radio>
 \`\`\`
 
-### Key Differences
-| Feature | bd-radio | bd-toggle-radio |
-|---|---|---|
-| Can be unchecked | No | Yes |
-| role | \`radio\` | \`checkbox\` |
-| change detail | \`{ value }\` always | \`{ value }\` or \`null\` when unchecked |
+### Group behaviour
+Radios find their group by \`name\` among their siblings in the same root, so no
+wrapper element is needed for the behaviour below.
+
+| | |
+|---|---|
+| Exclusivity | Selecting one clears every other radio with the same \`name\`. |
+| Arrow keys | Up and Left move to the previous option, Down and Right to the next, wrapping at both ends and skipping disabled ones. Moving selects, as it does natively. |
+| Tab | **One stop for the whole group**, on the selected radio, or the first enabled one when nothing is selected. |
+| Space | Selects the focused radio. Re-selecting the current one does nothing. |
+
+### Still missing: role="radiogroup"
+A screen reader gets each radio with its own state but **no group context** — no
+"1 of 4", and no group label. That needs an owning element, so a
+\`bd-radio-group\` is the missing piece. The behaviour above works without it;
+the announcement does not.
+
+### Not form-associated
+\`name\` groups the radios and is carried on the \`change\` event, but this
+element does **not** participate in form submission — a \`<form>\` containing it
+yields no \`FormData\` entry, because there is no native input behind it.
 
 ### Accessibility
-- Both use \`role\`, \`aria-checked\`, \`aria-disabled\`
-- Keyboard: Space and Enter toggle the state
-- Focus ring appears only on keyboard Tab navigation
-- \`tabindex="-1"\` when disabled
+- The **whole row is the control**, so clicking the label selects, and the
+  target clears the 24px WCAG 2.5.8 asks for — a 20px circle cannot on its own.
+- \`role="radio"\` with \`aria-checked\` reporting \`true\` or \`false\`, plus
+  \`aria-disabled\`.
+- The focus ring appears on keyboard navigation only, via \`:focus-visible\`, and
+  is inset evenly on all four sides.
+
+### Appearance
+Unchecked is a \`--color-blue-500\` ring on white, going \`--color-blue-600\` on
+hover; checked is a \`--color-blue-500\` fill with a white centre, which reads as
+a thick blue ring. The fill-and-white-mark language matches \`bd-checkbox\`.
+
+Two deviations from the design, both deliberate:
+
+- \`ds-radio\` specifies a neutral ring when unchecked while \`ds-checkbox\`
+  specifies a brand one, for the same conceptual state. The two frames disagree
+  and one system should not, so both controls use blue here.
+- The design drops the white centre when a checked radio is disabled, leaving a
+  plain grey disc. It is kept, so a disabled selection still reads as selected,
+  and to stay consistent with \`bd-checkbox\`.
 
 ### Events
-- \`change\` — CustomEvent with \`detail: { value }\`
+- \`change\` — \`detail: { name, value }\` on \`bd-radio\`;
+  \`detail: { checked, value }\` on \`bd-toggle-radio\`.
         `
       }
     }

package/src/components/review/review-grid.css.js

@@ -1,19 +1,17 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
     width: 100%;
     box-sizing: border-box;
-    max-width: var(--layout-ensemble-max-width, 1290px);
-    margin: 0 auto;
-    padding-inline: var(--layout-ensemble-inline-padding, var(--spacing-24));
   }
 
   .bd-reviewgrid-title {
     text-align: center;
     margin: 0 0 var(--spacing-32);
-    color: var(--color-neutral-1000);
+    color: var(--color-text-primary);
   }
 
   .bd-reviewgrid-grid {
@@ -32,7 +30,8 @@ export default css`
     min-width: 0;
   }
 
-  @media (max-width: 899px) {
+  /* below lg, as install-options: three cards stack across 900-991 too. */
+  @media ${unsafeCSS(below('lg'))} {
     .bd-reviewgrid-grid {
       grid-template-columns: 1fr;
     }

package/src/components/review/review-grid.js

@@ -2,6 +2,7 @@ import { LitElement, html, nothing } from "lit";
 import { tokens } from "../../tokens/tokens.js";
 import "../heading/heading.js";
 import reviewGridCSS from "./review-grid.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 import "./review.js";
 
 
@@ -11,7 +12,7 @@ class BdReviewGrid extends LitElement {
     _columns: { state: true }
   };
 
-  static styles = [tokens, reviewGridCSS];
+  static styles = [tokens, ensembleCSS, reviewGridCSS];
 
   constructor() {
     super();
@@ -32,16 +33,18 @@ class BdReviewGrid extends LitElement {
     const singleCard = this._columns === 1;
 
     return html`
-      ${this.title
-        ? html`<bd-h as="h2" class="bd-reviewgrid-title"><slot name="title">${this.title}</slot></bd-h>`
-        : nothing}
-
-      <div
-        class="bd-reviewgrid-grid ${singleCard ? "bd-reviewgrid-grid--single" : ""}"
-        style="--bd-review-columns: ${this._columns};"
-        role="list"
-      >
-        <slot @slotchange=${this._onSlotChange}></slot>
+      <div class="bd-ensemble">
+        ${this.title
+          ? html`<bd-h as="h2" class="bd-reviewgrid-title"><slot name="title">${this.title}</slot></bd-h>`
+          : nothing}
+
+        <div
+          class="bd-reviewgrid-grid ${singleCard ? "bd-reviewgrid-grid--single" : ""}"
+          style="--bd-review-columns: ${this._columns};"
+          role="list"
+        >
+          <slot @slotchange=${this._onSlotChange}></slot>
+        </div>
       </div>
     `;
   }

package/src/components/review/review.css.js

@@ -9,7 +9,7 @@ export default css`
   }
 
   .bd-review-card {
-    background: var(--color-blue-50);
+    background: var(--status-brand-surface);
     border-radius: var(--radius-3xl);
     padding: var(--spacing-28);
     box-sizing: border-box;
@@ -19,16 +19,17 @@ export default css`
   }
 
   :host([variant="neutral"]) .bd-review-card {
-    background: var(--color-neutral-25, #fafafa);
+    background: var(--color-surface-container);
   }
 
   .bd-review-mark {
     display: block;
+    color: var(--color-text-brand);
     margin-bottom: var(--spacing-8);
   }
 
   .bd-review-quote {
-    --bd-paragraph-color: var(--color-neutral-900);
+    --bd-paragraph-color: var(--color-text-primary);
     margin-bottom: var(--spacing-16);
     flex-grow: 1;
   }
@@ -39,12 +40,16 @@ export default css`
   }
 
   .bd-review-source {
-    --bd-paragraph-color: var(--color-neutral-900);
+    --bd-paragraph-color: var(--color-text-primary);
     margin: 0;
   }
 
   .bd-review-date {
-    color: var(--color-neutral-600);
-    font-size: var(--typography-fontSize-sm);
+    color: var(--color-text-muted);
+    font-family: var(--typography-body-small-fontFamily);
+    font-size: var(--typography-body-small-fontSize);
+    font-weight: var(--typography-body-small-fontWeight);
+    line-height: var(--typography-body-small-lineHeight);
+    letter-spacing: var(--typography-body-small-letterSpacing);
   }
 `;

package/src/components/review/review.js

@@ -35,19 +35,14 @@ class BdReview extends LitElement {
   render() {
     return html`
       <div class="bd-review-card">
-        <bd-quote-icon
-          class="bd-review-mark"
-          width="34"
-          height="35"
-          color="var(--color-blue-500)"
-        ></bd-quote-icon>
+        <bd-quote-icon class="bd-review-mark" size="xl"></bd-quote-icon>
 
-        <bd-p kind="regular" class="bd-review-quote">
+        <bd-p variant="regular" class="bd-review-quote">
           <slot name="quote"></slot>
         </bd-p>
 
         <div class="bd-review-meta">
-          <bd-p kind="small" font-weight="bold" class="bd-review-source"><slot name="source"></slot></bd-p>
+          <bd-p variant="small" font-weight="bold" class="bd-review-source"><slot name="source"></slot></bd-p>
           <span class="bd-review-date"><slot name="date"></slot></span>
         </div>
       </div>

package/src/components/shared/ensemble.css.js

@@ -0,0 +1,93 @@
+import { css, unsafeCSS } from "lit";
+import { above } from "./token-scales.js";
+
+/**
+ * The page column: the one wrapper every page-level section composes, so that
+ * a page assembled from independent modules has its content on one pair of
+ * edges without any module knowing about the others.
+ *
+ * It exists because there was no such thing. Foundations/Grid System documents
+ * a container -- "each container caps content at its breakpoint's max width and
+ * applies the matching horizontal padding" -- and nothing in the package
+ * implemented it: bd-grid lays out columns, layout.css's .bd-container is a
+ * light-DOM class no shadow root can reach. So fourteen modules each wrote a
+ * wrapper of their own, and a composed page measured ten different left edges
+ * (16, 86, 88, 99, 113, 137, 240, 307, 310, 409px at 1440). Seven of them had
+ * copied 1290px from one another since 2026-04-30 with no reason recorded
+ * anywhere; two carried 1400; the hero used a 240px gutter that made it the one
+ * section whose width depended on the viewport.
+ *
+ * This is that container, implemented once, on the scale the docs promised:
+ * --grid-container-max-* with --grid-padding-* per breakpoint. A module
+ * imports it first and puts the class on the element that holds its content:
+ *
+ *   static styles = [ensembleCSS, ownCSS];
+ *   <div class="bd-ensemble bd-thing-wrapper">...</div>
+ *
+ * A band that must run full-bleed keeps its background on :host and puts the
+ * column inside. A heading or prose block that is deliberately narrower than
+ * the page keeps its own measure; that is a measure, not a column.
+ *
+ * Sections nest -- bd-features inside bd-tabs, an accordion inside a feature
+ * column, bd-features-tab inside a tab panel -- and a column inside a column
+ * must not pad or cap again. So the width and gutter are read through two
+ * component-local properties with the grid step as fallback, and the column
+ * neutralises both on its children. Custom properties inherit through slots
+ * and into shadow trees, so a nested column finds `none` and `0` waiting for it
+ * and collapses to its parent's edges. No module has to know whether it is the
+ * outer one. The neutralisers go on the children rather than the column
+ * itself, because a custom property set on an element is what that element's
+ * own declarations read.
+ *
+ * check:ensemble holds this: a unit the registry marks `column: true` must
+ * compose this file and write the class, and no section-layer stylesheet may
+ * spell a column of its own again.
+ */
+export const ensembleCSS = css`
+  .bd-ensemble {
+    box-sizing: border-box;
+    width: 100%;
+    max-width: var(--bd-ensemble-max-width, var(--grid-container-max-xs));
+    margin-inline: auto;
+    padding-inline: var(--bd-ensemble-inline-padding, var(--grid-padding-xs));
+  }
+
+  /* a column inside this column is not a column */
+  .bd-ensemble > * {
+    --bd-ensemble-max-width: none;
+    --bd-ensemble-inline-padding: 0;
+  }
+
+  @media ${unsafeCSS(above('sm'))} {
+    .bd-ensemble {
+      max-width: var(--bd-ensemble-max-width, var(--grid-container-max-sm));
+      padding-inline: var(--bd-ensemble-inline-padding, var(--grid-padding-sm));
+    }
+  }
+
+  @media ${unsafeCSS(above('md'))} {
+    .bd-ensemble {
+      max-width: var(--bd-ensemble-max-width, var(--grid-container-max-md));
+      padding-inline: var(--bd-ensemble-inline-padding, var(--grid-padding-md));
+    }
+  }
+
+  @media ${unsafeCSS(above('lg'))} {
+    .bd-ensemble {
+      max-width: var(--bd-ensemble-max-width, var(--grid-container-max-lg));
+      padding-inline: var(--bd-ensemble-inline-padding, var(--grid-padding-lg));
+    }
+  }
+
+  @media ${unsafeCSS(above('xl'))} {
+    .bd-ensemble {
+      max-width: var(--bd-ensemble-max-width, var(--grid-container-max-xl));
+    }
+  }
+
+  @media ${unsafeCSS(above('xxl'))} {
+    .bd-ensemble {
+      max-width: var(--bd-ensemble-max-width, var(--grid-container-max-xxl));
+    }
+  }
+`;