@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/accordion/accordion.css.js

@@ -8,12 +8,56 @@ export const accordionItem = css`
     border-radius: var(--radius-sm);
   }
 
+  /* The one focus ring, on the item.
+
+     Two owners are in play and they are deliberately different elements. The
+     TRIGGER owns focus: it is the button, it carries aria-expanded, a keyboard
+     lands on it and a screen reader announces it. The ITEM owns the focus
+     VISUAL: a disclosure is perceived as one object -- the question and, when
+     open, its answer -- and the ring goes round that object, growing with the
+     answer when it is revealed. Measured before this rule, on Components/
+     Accordion "Item open by default": host [99,131,1242,61], trigger
+     [99,131,1242,24], content [99,171,1242,21] -- the ring stopped at the
+     question and the answer sat outside it.
+
+     Exactly one painter. The trigger's :focus-visible rule below sets outline
+     none and nothing else; the ring lives here. P6C.2.1 found both painting the
+     same --focus-outline-primary and removed the host's; P6C.2.2 moves the one
+     ring back up to the item and takes the trigger's away, so the invariant
+     that phase established -- one token, one painter -- still holds.
+
+     No border-radius here. The ring is a box-shadow and follows the shape of
+     the item it sits on: --radius-sm on this host, --radius-lg on the tinted
+     FAQ item. Setting --focus-outline-radius here is what P6C.2.1 removed,
+     because it pulled a focused FAQ card's corners from 8px to 4px.
+
+     Why an attribute and not a pseudo-class. This rule needs to fire when the
+     trigger -- inside this shadow root -- matches :focus-visible, and no
+     selector says that from the host. Measured with a probe sheet injected at
+     runtime: :host(:has(button:focus-visible)) never matches, because :has()
+     inside :host() looks at light-DOM descendants and cannot see the shadow
+     tree (:host(:has(.bd-accordion-bg-question)) fails the same way);
+     :host(:focus-within) matches on a real Tab AND on a real mouse click, so it
+     cannot tell keyboard from pointer; :host(:focus-visible) never matches. The
+     JS in accordion.js sets data-bd-acc-focus after two animation frames when
+     -- and only when -- the trigger matches :focus-visible, and re-checks on
+     every keydown, because a keypress can make an already-focused button
+     :focus-visible without a focus change. Measured: after a mouse click the
+     attribute stays off; after Tab it is on.
+
+     The stacking is the other reason the attribute exists, and it is measured:
+     --bd-acc-item-margin-bottom is a public custom property, and with it zeroed
+     on AccordionBg "FAQ - Default" a 300x5 sample where the ring overlaps the
+     next item holds 600 blue-500 pixels with position/z-index and 0 without --
+     the next item's tint paints over the ring. On the untinted
+     bd-accordion-item it reads 600 either way.
+
+     bd-accordion-bg-item adopts this stylesheet too, so this is the one rule
+     that rings and stacks the whole accordion family. */
   :host([data-bd-acc-focus]) {
-    outline: none;
-    box-shadow: var(--focus-outline-primary);
     position: relative;
-    z-index: 1;
-    border-radius: var(--radius-sm);
+    z-index: var(--z-base);
+    box-shadow: var(--focus-outline-primary);
   }
 
   :host(:last-child) {
@@ -21,20 +65,26 @@ export const accordionItem = css`
   }
 
   :host-context(bd-accordion-section:not([variant="small"])) {
-    --bd-acc-title-font-size: var(--typography-fontSize-base);
-    --bd-acc-title-font-weight: var(--typography-fontWeight-semibold);
-    --bd-acc-title-line-height: var(--typography-lineHeight-normal);
-    --bd-acc-title-color-expanded: var(--color-neutral-900);
-    --bd-acc-title-color-collapsed: var(--color-neutral-900);
-    --bd-acc-panel-font-size: var(--typography-fontSize-sm);
-    --bd-acc-panel-font-weight: var(--typography-fontWeight-normal);
-    --bd-acc-panel-line-height: var(--typography-lineHeight-normal);
-    --bd-acc-panel-color: var(--color-neutral-800);
+    --bd-acc-title-font-size: var(--typography-label-large-fontSize);
+    --bd-acc-title-font-weight: var(--typography-label-large-fontWeight);
+    --bd-acc-title-line-height: var(--typography-label-large-lineHeight);
+    /* Section titles. The role, not neutral-900: same value, but a primitive
+       records what the colour IS and a role records what it is FOR, and only
+       the second survives a theme or a palette revision. */
+    --bd-acc-title-color-expanded: var(--color-text-primary);
+    --bd-acc-title-color-collapsed: var(--color-text-primary);
+    --bd-acc-panel-font-size: var(--typography-body-small-fontSize);
+    --bd-acc-panel-font-weight: var(--typography-body-small-fontWeight);
+    --bd-acc-panel-line-height: var(--typography-body-small-lineHeight);
+    /* Panel body copy. */
+    --bd-acc-panel-color: var(--color-text-primary);
   }
 
   :host-context(bd-accordion-section[variant="default-blue"]) {
-    --bd-acc-title-color-expanded: var(--color-blue-600);
-    --bd-acc-title-color-collapsed: var(--color-blue-600);
+    /* -text-brand IS blue-600; naming the role also inherits the reason it is
+       blue-600 and not blue-500, which tokens.js records. */
+    --bd-acc-title-color-expanded: var(--color-text-brand);
+    --bd-acc-title-color-collapsed: var(--color-text-brand);
   }
 
   :host-context(bd-accordion-section[variant="small"]) {
@@ -42,13 +92,14 @@ export const accordionItem = css`
     --bd-acc-header-margin-bottom: var(--spacing-0);
     --bd-acc-icon-gap: var(--spacing-12);
     --bd-acc-toggle-size: var(--icon-sm-size);
-    --bd-acc-title-font-size: var(--typography-fontSize-xs);
-    --bd-acc-title-font-weight: var(--typography-fontWeight-semibold);
-    --bd-acc-title-line-height: 1.3;
-    --bd-acc-panel-font-size: var(--typography-fontSize-xs);
-    --bd-acc-panel-font-weight: var(--typography-fontWeight-normal);
-    --bd-acc-panel-line-height: 1.3;
-    --bd-acc-panel-color: var(--color-neutral-800);
+    --bd-acc-title-font-size: var(--typography-label-default-fontSize);
+    --bd-acc-title-font-weight: var(--typography-label-default-fontWeight);
+    --bd-acc-title-line-height: var(--typography-label-default-lineHeight);
+    --bd-acc-panel-font-size: var(--typography-caption-default-fontSize);
+    --bd-acc-panel-font-weight: var(--typography-caption-default-fontWeight);
+    --bd-acc-panel-line-height: var(--typography-caption-default-lineHeight);
+    /* Panel body copy, small variant. */
+    --bd-acc-panel-color: var(--color-text-primary);
     --bd-acc-panel-padding: var(--spacing-0) var(--spacing-8) var(--spacing-8)
       var(--spacing-36);
     --bd-acc-panel-paragraph-gap: var(--spacing-0);
@@ -87,8 +138,8 @@ export const accordionItem = css`
     font-family: var(--typography-fontFamily-sans);
     font-style: normal;
     font-size: var(--bd-acc-title-font-size, var(--typography-label-large-fontSize));
-    font-weight: var(--bd-acc-title-font-weight, var(--typography-fontWeight-semibold));
-    line-height: var(--bd-acc-title-line-height, var(--typography-lineHeight-normal));
+    font-weight: var(--bd-acc-title-font-weight, var(--typography-label-large-fontWeight));
+    line-height: var(--bd-acc-title-line-height, var(--typography-label-large-lineHeight));
     margin-bottom: var(--bd-acc-header-margin-bottom, var(--spacing-16));
   }
 
@@ -96,25 +147,29 @@ export const accordionItem = css`
     margin-bottom: var(--spacing-8);
   }
 
+  /* No ring on the trigger. outline: none is not a removal: the visible focus
+     indicator is the item's ring, drawn by :host([data-bd-acc-focus]) above on
+     exactly the frames this pseudo-class matches. Painting it here as well is
+     the double ring P6C.2.1 measured and removed. */
   .header:focus-visible {
     outline: none;
-    box-shadow: none;
   }
 
   .header[aria-expanded="true"] .title {
-    color: var(--color-blue-500);
+  /* blue-500 is 4.2:1 on the blue-50 tint these titles sit on; blue-600 is 5.72 */
+    color: var(--color-text-brand);
   }
 
   .header[aria-expanded="false"] .title {
-    color: var(--color-blue-500);
+    color: var(--color-text-brand);
   }
 
   :host-context(bd-accordion-section[variant="small"]) .header[aria-expanded="false"] .title {
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
   }
 
   :host-context(bd-accordion-section[variant="small"]) .header[aria-expanded="false"]:hover .title {
-    color: var(--color-blue-500);
+    color: var(--color-text-brand);
   }
 
   :host-context(bd-accordion-section[variant="small"]) .header[aria-expanded="true"] .title {
@@ -122,7 +177,7 @@ export const accordionItem = css`
   }
 
   :host-context(bd-accordion-section[variant="small"]) .header[aria-expanded="true"]:hover .title {
-    color: var(--color-blue-500);
+    color: var(--color-text-brand);
   }
 
   .toggle {
@@ -133,25 +188,40 @@ export const accordionItem = css`
     display: flex;
     align-items: center;
     justify-content: center;
-    line-height: 0;
+    /* the box holds an icon, not text; none collapses the leading to the
+       glyph rather than reserving a text line around it */
+    line-height: var(--typography-lineHeight-none);
     user-select: none;
     margin-top: calc(
-      (var(--bd-acc-title-line-height, var(--typography-lineHeight-normal)) * 1em -
+      (var(--bd-acc-title-line-height, var(--typography-label-large-lineHeight)) * 1em -
       var(--bd-acc-toggle-size, var(--icon-sm-size))) / 2
     );
   }
 
-  .toggle img {
-    display: block;
-    width: 100%;
-    height: 100%;
-    object-fit: contain;
-  }
+  /* A ".toggle img" rule stood here and could never match. The toggle renders
+     <bd-plus-icon>, <bd-minus-icon> or the chevron atoms, each taking its own
+     size and color props -- there has been no <img> here since that migration,
+     and the atom's props already carry what this rule was sizing.
+     .
+     Those props pass --color-text-brand, the same role .header carries and the
+     one bd-link's whole family resolves to. They passed --color-blue-500 until
+     the Figma audit put icon and label side by side: the label was already the
+     role, so the toggle disagreed with its own text by one step. This file had
+     already made the same move twice -- on .header[aria-expanded="true"] .title
+     and on .user-guide-link a -- and the icon was the hold-out, passing on the
+     3:1 non-text bar where the text beside it needed 4.5:1. */
 
   .title {
-    font-weight: var(--bd-acc-title-font-weight, var(--typography-fontWeight-semibold));
+    font-weight: var(--bd-acc-title-font-weight, var(--typography-label-large-fontWeight));
   }
 
+  /* Wrapping is the whole mechanism: whether a title and its badge fit on one
+     line depends on how long the title is and how much room this accordion
+     has, not on how wide the window is. A 430px viewport rule used to force
+     the column stack, which was both too eager and too narrow -- measured, a
+     320px-wide accordion on a 1280px viewport never triggered it and laid out
+     correctly anyway, while a short title on a 320px viewport was stacked when
+     it would have fitted. flex-wrap answers the question actually being asked. */
   .title-badge-wrapper {
     display: flex;
     align-items: center;
@@ -163,10 +233,14 @@ export const accordionItem = css`
   .content {
     padding: var(--bd-acc-panel-padding, 0 0 0 calc(var(--icon-sm-size) + var(--spacing-12)));
     font-family: var(--typography-fontFamily-sans);
-    font-size: var(--bd-acc-panel-font-size, var(--typography-fontSize-sm));
-    font-weight: var(--bd-acc-panel-font-weight, var(--typography-fontWeight-normal));
-    line-height: var(--bd-acc-panel-line-height, var(--typography-lineHeight-normal));
-    color: var(--bd-acc-panel-color, var(--color-neutral-700));
+    font-size: var(--bd-acc-panel-font-size, var(--typography-body-small-fontSize));
+    font-weight: var(--bd-acc-panel-font-weight, var(--typography-body-small-fontWeight));
+    line-height: var(--bd-acc-panel-line-height, var(--typography-body-small-lineHeight));
+    /* The fallback is -primary because both :host-context blocks above set
+       -primary, so it was only ever reachable by a standalone bd-accordion-item
+       outside any section -- one rendering that disagreed with every real
+       usage, and with the Figma item, which draws this at text/primary. */
+    color: var(--bd-acc-panel-color, var(--color-text-primary));
   }
 
   .content[hidden] {
@@ -187,15 +261,6 @@ export const accordionItem = css`
     margin-bottom: 0;
   }
 
-  @media (max-width: 430px) {
-    .title-badge-wrapper {
-      flex-direction: column;
-      align-items: flex-start;
-      gap: var(--spacing-0);
-      width: 100%;
-    }
-  }
-
   /* === CHEVRON VARIANT (text + arrow icon only, no visible border/pill/background) === */
   .header--chevron {
     display: inline-flex;
@@ -205,11 +270,11 @@ export const accordionItem = css`
     gap: var(--spacing-8);
     padding: 0;
     border: none;
-    border-radius: 0;
+    border-radius: var(--radius-none);
     background: none;
     margin-bottom: var(--spacing-24);
-    font-size: var(--typography-fontSize-sm);
-    font-weight: var(--typography-fontWeight-semibold);
+    font-size: var(--typography-label-default-fontSize);
+    font-weight: var(--typography-label-default-fontWeight);
   }
 
   .header--chevron .title-badge-wrapper {
@@ -217,7 +282,7 @@ export const accordionItem = css`
   }
 
   .header--chevron .title {
-    color: var(--color-blue-600);
+    color: var(--color-text-brand);
     white-space: nowrap;
   }
 
@@ -239,8 +304,8 @@ export const accordionItem = css`
 
 export const accordionSection = css`
   .bd-accordion-section-container {
-    background-color: var(--bd-acc-section-bg, var(--color-neutral-25));
-    border-radius: 0;
+    background-color: var(--bd-acc-section-bg, var(--color-surface-container));
+    border-radius: var(--radius-none);
     box-sizing: border-box;
 
     /* Bleed — bg full width */
@@ -255,65 +320,62 @@ export const accordionSection = css`
   }
 
   .bd-accordion-section-inner {
-    max-width: 1290px;
-    margin-inline: auto;
-    padding-inline: var(--layout-ensemble-inline-padding, var(--spacing-24));
     box-sizing: border-box;
   }
 
   :host([variant="small"]) {
-    --bd-acc-section-bg: var(--color-neutral-0);
+    /* White here means "the untinted page ground", which is -surface-default's
+       job; the default variant two rules up already asks for a surface role. */
+    --bd-acc-section-bg: var(--color-surface-default);
     --bd-acc-section-padding-v: var(--spacing-24);
   }
 
   :host([variant="default-blue"]) {
-    --bd-acc-section-bg: var(--color-blue-50);
-  }
-
-  :host(:not([variant="small"])) .user-guide-link {
-    color: var(--color-blue-700);
+    /* The brand tint as a surface, which is what the Figma section already
+       binds this to (status/brand/surface) and what bd-accordion-bg's item
+       ground uses for the same tint. */
+    --bd-acc-section-bg: var(--status-brand-surface);
   }
 
   .section-title {
     margin-bottom: var(--spacing-24);
     margin-top: var(--spacing-0);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-bold);
-    font-size: var(--typography-body-regular-fontSize);
-    line-height: var(--typography-lineHeight-normal);
-    color: var(--color-neutral-1000);
   }
 
   :host([variant="small"]) .section-title {
-    font-size: var(--typography-fontSize-lg);
     margin-bottom: var(--spacing-16);
   }
 
   .user-guide-link {
     margin-top: var(--spacing-32);
-    color: var(--color-blue-600);
+    color: var(--color-text-brand);
   }
 
   .user-guide-link a {
     display: inline-flex;
     align-items: center;
     text-decoration: none;
-    color: var(--color-blue-500);
+    /* --color-text-brand, which is what .user-guide-link one rule up already
+       says. This anchor overrode its own parent with the raw primitive, and
+       blue-500 measures 4.34:1 on the --color-surface-container these links sit
+       on -- the exact trap the token comment two hundred lines up describes and
+       that this file already avoids twice elsewhere. blue-600 is 5.92. */
+    color: var(--color-text-brand);
     gap: var(--spacing-12);
-    font-family: Arial, Helvetica, sans-serif;
-    font-size: var(--typography-fontSize-xs);
+    font-family: var(--typography-fontFamily-sans);
+    font-size: var(--typography-body-xsmall-fontSize);
   }
 
   .user-guide-link a:focus-visible {
     outline: none;
     box-shadow: var(--focus-outline-primary);
-    border-radius: var(--radius-sm);
+    border-radius: var(--focus-outline-radius);
   }
 
   .user-guide-link .icon img {
     display: block;
-    width: var(--dimension-16px);
-    height: var(--dimension-16px);
+    width: var(--dimension-16);
+    height: var(--dimension-16);
     object-fit: contain;
   }
 `;

package/src/components/accordion/accordion.js

@@ -1,5 +1,6 @@
 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 "../heading/heading.js";
 import "../icons/arrow-down-icon.js";
 import "../icons/arrow-up-icon.js";
@@ -7,9 +8,11 @@ import "../icons/minus-icon.js";
 import "../icons/plus-icon.js";
 import "../paragraph/paragraph.js";
 import { accordionItem, accordionSection } from "./accordion.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
+import { onTriggerKeydown } from "./accordion-keyboard.js";
 
 export class BdAccordionItem extends LitElement {
-  static styles = [tokens, accordionItem];
+  static styles = [accordionItem];
 
   static properties = {
     open    : { type: Boolean, reflect: true },
@@ -31,6 +34,18 @@ export class BdAccordionItem extends LitElement {
     this.open = !this.open;
   }
 
+  /**
+   * The trigger is the focus target; the item draws the ring. This puts
+   * data-bd-acc-focus on the host when -- and only when -- the trigger matches
+   * :focus-visible, which is the one thing no selector can say from the host
+   * (see the note on :host([data-bd-acc-focus]) in accordion.css.js). Two
+   * frames, because :focus-visible is decided after the focus event.
+   *
+   * Called on focusin and on every keydown. The keydown matters: after a mouse
+   * click the button is focused without :focus-visible and the attribute is
+   * rightly off, but a keypress then makes it :focus-visible with no focus
+   * change, and without this the item would show no ring for a keyboard user.
+   */
   _onTriggerFocusIn() {
     const btn = this.renderRoot?.querySelector(".header");
     if (!btn) return;
@@ -47,6 +62,16 @@ export class BdAccordionItem extends LitElement {
     this.removeAttribute("data-bd-acc-focus");
   }
 
+  _onTriggerKeydown(e) {
+    onTriggerKeydown(this, e);
+    this._onTriggerFocusIn();
+  }
+
+  /** Move keyboard focus to this item's disclosure trigger. */
+  focusTrigger() {
+    this.renderRoot?.querySelector(".header")?.focus();
+  }
+
   render() {
     const badgeEl = this.querySelector("[slot='badge']");
 
@@ -60,6 +85,7 @@ export class BdAccordionItem extends LitElement {
           @click=${this.toggle}
           @focusin=${this._onTriggerFocusIn}
           @focusout=${this._onTriggerFocusOut}
+          @keydown=${this._onTriggerKeydown}
         >
           <span class="title-badge-wrapper">
             <span class="title">${this.title}</span>
@@ -67,8 +93,8 @@ export class BdAccordionItem extends LitElement {
           </span>
           <span class="toggle toggle--chevron" aria-hidden="true">
             ${this.open
-              ? html`<bd-arrow-up-icon size="16" color="#006DFF"></bd-arrow-up-icon>`
-              : html`<bd-arrow-down-icon size="16" color="#006DFF"></bd-arrow-down-icon>`}
+              ? html`<bd-arrow-up-icon size="16" color="var(--color-text-brand)"></bd-arrow-up-icon>`
+              : html`<bd-arrow-down-icon size="16" color="var(--color-text-brand)"></bd-arrow-down-icon>`}
           </span>
         </button>
         <div id="${this._panelId}" class="content content--chevron" ?hidden=${!this.open}>
@@ -86,11 +112,12 @@ export class BdAccordionItem extends LitElement {
         @click=${this.toggle}
         @focusin=${this._onTriggerFocusIn}
         @focusout=${this._onTriggerFocusOut}
+        @keydown=${this._onTriggerKeydown}
       >
         <span class="toggle" aria-hidden="true">
           ${this.open
-            ? html`<bd-minus-icon size="16" color="#006DFF"></bd-minus-icon>`
-            : html`<bd-plus-icon  size="16" color="#006DFF"></bd-plus-icon>`}
+            ? html`<bd-minus-icon size="16" color="var(--color-text-brand)"></bd-minus-icon>`
+            : html`<bd-plus-icon  size="16" color="var(--color-text-brand)"></bd-plus-icon>`}
         </span>
         <span class="title-badge-wrapper">
           <span class="title">${this.title}</span>
@@ -105,7 +132,7 @@ export class BdAccordionItem extends LitElement {
 }
 
 export class BdAccordionSection extends LitElement {
-  static styles = [tokens, accordionSection];
+  static styles = [ensembleCSS, accordionSection];
 
   static properties = {
     title      : { type: String },
@@ -129,12 +156,12 @@ export class BdAccordionSection extends LitElement {
   render() {
     const content = html`
       ${this.title
-        ? html`<bd-h as="h6" fontWeight="700" paddingBottom="var(--spacing-32)" class="section-title">${this.title}</bd-h>`
+        ? html`<bd-h as="h6" fontWeight="bold" class="section-title">${this.title}</bd-h>`
         : ""}
       <slot></slot>
       ${this.guideLabel
         ? html`
-            <bd-p kind="small" class="user-guide-link">
+            <bd-p variant="small" class="user-guide-link">
               <a href=${this.guideHref}>
                 ${this.guideIcon
                   ? html`<span class="icon"><img src=${this.guideIcon} alt="" /></span>`
@@ -151,7 +178,7 @@ export class BdAccordionSection extends LitElement {
 
     return html`
       <div class="bd-accordion-section-container">
-        <div class="bd-accordion-section-inner">
+        <div class="bd-ensemble bd-accordion-section-inner">
           ${content}
         </div>
       </div>

package/src/components/accordion/accordion.stories.js

@@ -257,8 +257,8 @@ export const RiskMappingAccordion = {
   name  : "Chevron variant — Risk mapping table",
   render: () => html`
     <div style="max-width: 900px;">
-      <bd-h as="h2" font-weight="700" style="margin: 0 0 8px;">Coverage against agentic AI risk categories</bd-h>
-      <bd-p kind="regular" style="color: var(--color-neutral-700); margin: 0 0 24px;">
+      <bd-h as="h2" fontWeight="bold" style="margin: 0 0 8px;">Coverage against agentic AI risk categories</bd-h>
+      <bd-p variant="regular" style="color: var(--color-neutral-700); margin: 0 0 24px;">
         How AI Guardian maps to the risk categories the industry is standardising on for agentic applications.
       </bd-p>
 
@@ -276,7 +276,7 @@ export const RiskMappingAccordion = {
         ></bd-compatibility-table>
       </bd-accordion-item>
 
-      <bd-p kind="small" style="color: var(--color-neutral-500); margin-top: 16px;">
+      <bd-p variant="small" style="color: var(--color-neutral-500); margin-top: 16px;">
         Category naming follows OWASP Top 10 for Agentic Applications (2026).
       </bd-p>
     </div>
@@ -323,14 +323,14 @@ export const DefaultVsChevron = {
   render: () => html`
     <div style="display: flex; flex-direction: column; gap: 32px;">
       <div>
-        <bd-p kind="small" style="color: var(--color-neutral-500); margin-bottom: 8px;">Default (plus/minus, left icon)</bd-p>
+        <bd-p variant="small" style="color: var(--color-neutral-500); margin-bottom: 8px;">Default (plus/minus, left icon)</bd-p>
         <bd-accordion-item title="Default accordion item">
           <p>Regular accordion content, unaffected by the new chevron variant.</p>
         </bd-accordion-item>
       </div>
 
       <div>
-        <bd-p kind="small" style="color: var(--color-neutral-500); margin-bottom: 8px;">Chevron (plain text, right arrow icon, no border)</bd-p>
+        <bd-p variant="small" style="color: var(--color-neutral-500); margin-bottom: 8px;">Chevron (plain text, right arrow icon, no border)</bd-p>
         <bd-accordion-item chevron title="Chevron accordion item">
           <p>Same underlying component, opt-in chevron styling via the chevron attribute.</p>
         </bd-accordion-item>
@@ -351,8 +351,8 @@ export const OperationalDetailsAccordion = {
   name  : "Chevron variant — Operational details (light table)",
   render: () => html`
     <div style="max-width: 900px;">
-      <bd-h as="h2" font-weight="700" style="margin: 0 0 8px;">How it runs</bd-h>
-      <bd-p kind="regular" style="color: var(--color-neutral-700); margin: 0 0 24px;">
+      <bd-h as="h2" fontWeight="bold" style="margin: 0 0 8px;">How it runs</bd-h>
+      <bd-p variant="regular" style="color: var(--color-neutral-700); margin: 0 0 24px;">
         AI Guardian installs from a signed macOS installer and runs as a background service; the rows below list how it installs, where analysis happens, and what the BETA costs.
       </bd-p>
 

package/src/components/agent-endpoints/agent-endpoints.css.js

@@ -1,4 +1,5 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
@@ -7,30 +8,32 @@ export default css`
   }
 
   .bd-agentendpoints-wrapper {
-    max-width: var(--layout-ensemble-max-width, 1200px);
-    margin: 0 auto;
-    padding: var(--spacing-48) var(--layout-ensemble-inline-padding, var(--spacing-24));
+    padding-block: var(--spacing-48);
     box-sizing: border-box;
   }
 
   .bd-agentendpoints-eyebrow {
     display: block;
     margin: 0 0 var(--spacing-8);
-    color: var(--color-blue-500);
+    /* The brand text role, not the brand primitive. This darkens the ink: the
+       role is blue-600, so contrast on white goes 4.53:1 -> 6.18:1. It is not a
+       like-for-like swap, and it cannot be -- no text role exists at blue-500's
+       value. The roles sitting there are surface, border, action, two status
+       fills, an accent and the tab indicator, and blue-500 is the step
+       CLAUDE.md says is not for text. */
+    color: var(--color-text-brand);
   }
 
   .bd-agentendpoints-title {
     display: block;
     margin: 0 0 var(--spacing-16);
-    color: var(--color-neutral-1000);
-    line-height: var(--typography-lineHeight-tight, 1.1);
   }
 
   .bd-agentendpoints-description {
     display: block;
     margin: 0 0 var(--spacing-24);
-    color: var(--color-neutral-600);
-    max-width: 70ch;
+    color: var(--color-text-muted);
+    max-width: var(--content-width-readable);
   }
 
   .bd-agentendpoints-row {
@@ -44,39 +47,33 @@ export default css`
     margin-bottom: 0;
   }
 
-  /* === button--outline-white ===
-     White pill button with a thin gray border, rounded corners — used both
-     for the /endpoint links (with a leading arrow, monospace label) and the
-     "Ask <assistant>" links (with a leading brand icon). Reusable class,
-     not scoped to this component only. */
-  .button--outline-white {
-    display: inline-flex;
-    align-items: center;
-    gap: var(--spacing-8);
-    padding: var(--spacing-10, 10px) var(--spacing-16);
-    background: var(--color-neutral-0, #fff);
-    border: 1px solid var(--color-neutral-200, #e5e7eb);
-    border-radius: var(--radius-full, 999px);
-    color: var(--color-neutral-800);
-    font-size: var(--typography-fontSize-sm);
-    font-weight: var(--typography-fontWeight-medium, 500);
-    text-decoration: none;
-    white-space: nowrap;
-    transition: border-color 0.2s ease, background 0.2s ease;
-  }
+  /* === pill ===
+     A white pill with a thin grey border, used for the /endpoint links (leading
+     arrow, monospace label) and the Ask <assistant> links (leading brand icon).
 
-  .button--outline-white:hover {
-    border-color: var(--color-blue-300, #93c5fd);
-    background: var(--color-blue-50, #eef4ff);
-  }
+     This was called button--outline-white, which is the name the button atom
+     uses for something else entirely: there, outline-white is a fixed preset
+     for a coloured banner and its label is white. Here the pill sits on a light
+     surface and its label is dark. The two never met, because a shadow root
+     scopes a class to its own component and nothing here was ever reusable, but
+     the shared name invited the wrong one to be reasoned about. */
+  /* No rule for .bd-agentendpoints-pill any more. It was a hand-rolled control
+     -- surface, border, radius, colour, type, hover and a focus ring, all
+     reimplemented -- and the class now sits on a <bd-button-link variant=
+     "tertiary" size="sm">, which supplies every one of them from the button
+     atom. Left in place it also doubled the padding, since the host and the
+     anchor inside it were both padding the same content: the host measured
+     55.5px against the anchor's 33.5px.
 
-  .bd-agentendpoints-arrow {
-    color: var(--color-neutral-400, #9ca3af);
-  }
+     The class is kept as a hook only, for the two spans below. */
 
+  /* No colour on either span: the button owns the ink. These were
+     neutral-400 and text-secondary, chosen when the pill was a white box with
+     dark text; on a tertiary button they overrode its blue and left the file
+     path grey inside a blue control. The mono face stays, because a path
+     rendered in the text face is the thing this span exists to prevent. */
   .bd-agentendpoints-mono {
-    font-family: var(--typography-fontFamily-mono, monospace);
-    color: var(--color-neutral-700);
+    font-family: var(--typography-fontFamily-mono);
   }
 
   .bd-agentendpoints-icon {
@@ -84,7 +81,7 @@ export default css`
     flex-shrink: 0;
   }
 
-  @media (max-width: 599px) {
+  @media ${unsafeCSS(below('sm'))} {
     .bd-agentendpoints-wrapper {
       padding: var(--spacing-32) var(--spacing-24);
     }