@repobit/dex-system-design 1.0.1 → 2.0.1

package/src/components/badge/badge.stories.js

@@ -1,7 +1,7 @@
 import { html } from 'lit';
 import './badge.js';
 
-const TONES    = ['default', 'primary', 'success', 'warning', 'error', 'info'];
+const TONES    = ['neutral', 'brand', 'success', 'warning', 'error', 'info'];
 const SIZES    = ['sm', 'md', 'lg'];
 const VARIANTS = ['shade', 'fill'];
 
@@ -35,10 +35,10 @@ matched to the token that already carries it.
 ### Usage
 \`\`\`html
 <bd-badge tone="success" variant="shade">Save 44%</bd-badge>
-<bd-badge tone="primary" variant="fill" size="sm">New</bd-badge>
+<bd-badge tone="brand" variant="fill" size="sm">New</bd-badge>
 <bd-badge mode="count" tone="error" variant="fill">3</bd-badge>
 <bd-badge mode="dot" tone="warning" variant="fill"></bd-badge>
-<bd-badge tone="primary" variant="fill" icon="family">Family Pack</bd-badge>
+<bd-badge tone="brand" variant="fill" icon="family">Family Pack</bd-badge>
 \`\`\`
 
 ### Props
@@ -46,7 +46,7 @@ matched to the token that already carries it.
 |---|---|---|
 | \`mode\` | \`text\`, \`dot\`, \`count\` | \`text\` |
 | \`size\` | \`sm\`, \`md\`, \`lg\` | \`md\` |
-| \`tone\` | \`default\`, \`primary\`, \`success\`, \`warning\`, \`error\`, \`info\` | \`default\` |
+| \`tone\` | \`neutral\`, \`brand\`, \`success\`, \`warning\`, \`error\`, \`info\` | \`neutral\` |
 | \`variant\` | \`shade\`, \`fill\` | \`shade\` |
 | \`icon\` | \`individual\`, \`family\`, \`''\` | \`''\` |
 | \`label\` | any string — accessible name for \`mode="dot"\` | tone name |
@@ -107,7 +107,7 @@ matched to the token that already carries it.
       control    : { type: 'select' },
       options    : TONES,
       description: 'Semantic colour pairing.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: 'default' }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'neutral' }, category: 'Appearance' }
     },
     variant: {
       control    : { type: 'inline-radio' },
@@ -135,7 +135,7 @@ matched to the token that already carries it.
   args: {
     mode   : 'text',
     size   : 'md',
-    tone   : 'default',
+    tone   : 'neutral',
     variant: 'shade',
     icon   : '',
     label  : '',
@@ -172,7 +172,7 @@ export const Sizes = {
   render    : () => html`
     ${VARIANTS.map(variant => html`
       ${row(variant, SIZES.map(size => html`
-        <bd-badge size="${size}" tone="primary" variant="${variant}">${size}</bd-badge>
+        <bd-badge size="${size}" tone="brand" variant="${variant}">${size}</bd-badge>
       `))}
     `)}
   `
@@ -212,7 +212,7 @@ export const WithIcon = {
       <bd-badge tone="success" icon="family">Family Pack</bd-badge>
     `)}
     ${row('fill', html`
-      <bd-badge variant="fill" tone="primary" icon="individual">Individual</bd-badge>
+      <bd-badge variant="fill" tone="brand" icon="individual">Individual</bd-badge>
       <bd-badge variant="fill" tone="success" icon="family">Family Pack</bd-badge>
     `)}
   `
@@ -220,11 +220,15 @@ export const WithIcon = {
 
 export const Legacy = {
   name      : 'Legacy variants',
-  parameters: { docs: { description: { story: 'Pre-`ds-badge` markup still renders, mapped onto the new axes.' } } },
+  parameters: { docs: { description: { story: 'Pre-`ds-badge` markup still renders, mapped onto the new axes: the old variants, and the two retired tone names, `default` (now `neutral`) and `primary` (now `brand`). Write the new names; these are here so a page still using the old ones is shown to work.' } } },
   render    : () => html`
     ${row('mapped', html`
       <bd-badge variant="bd-light-blue">bd-light-blue</bd-badge>
       <bd-badge variant="bd-light-green">bd-light-green</bd-badge>
     `)}
+    ${row('tones', html`
+      <bd-badge tone="default">tone="default" → neutral</bd-badge>
+      <bd-badge tone="primary">tone="primary" → brand</bd-badge>
+    `)}
   `
 };

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

@@ -220,7 +220,7 @@ class BentoGrid extends LitElement {
             <div class="bd-bentogrid-header">
               ${this.eyebrow
                 ? html`
-                    <bd-p variant="regular" class="bd-bentogrid-eyebrow">
+                    <bd-p variant="eyebrow" class="bd-bentogrid-eyebrow">
                       <slot name="eyebrow">${this.eyebrow}</slot>
                     </bd-p>
                   `

package/src/components/blockquote/blockquote.css.js

@@ -4,8 +4,17 @@ import { css } from 'lit';
 export const blockquoteCSS = css`
   :host { display: block; }
 
+  /* .quote is the outer element: the <figure> when there is an attribution,
+     the bare <blockquote> when there is not. The bar and the type live on it,
+     so the caption inherits the quotation's family and leading the way the
+     <footer> did when it sat inside the <blockquote> -- the rhythm the note
+     below is about. */
+  figure,
   blockquote {
     margin: 0;
+  }
+
+  .quote {
     padding-left: var(--spacing-16);
     border-left: var(--border-width-4) solid var(--color-border-brand);
     font-family: var(--typography-body-large-fontFamily);
@@ -15,7 +24,7 @@ export const blockquoteCSS = css`
     color: var(--color-text-primary);
   }
 
-  footer {
+  figcaption {
     margin-top: var(--spacing-8);
     font-size: var(--typography-caption-default-fontSize);
     /* no role: two roles are each a near-miss, from opposite directions, and
@@ -24,8 +33,8 @@ export const blockquoteCSS = css`
        .
        label-small matches this text's size and weight exactly -- but adopting
        it would add letterSpacing-wide, which has no job on mixed-case sentence
-       text because nothing here crowds, and would replace the 1.625 leading
-       this inherits from the quote it attributes with 1.5. That inherited
+       text because nothing here crowds, and would replace the leading this
+       inherits from the quote it attributes with 1.5. That inherited
        rhythm is the one thing in this rule that means something: the credit
        line sits on the same measure as the quotation it belongs to, where 1.5
        merely comes attached to the role.

package/src/components/blockquote/blockquote.js

@@ -17,12 +17,19 @@ export class BdBlockquote extends LitElement {
     this.attribution = '';
   }
 
+  /* WHERE THE ATTRIBUTION GOES.
+     It used to be a <footer> inside the <blockquote>, and everything inside a
+     blockquote is the quotation, so the name of the person quoted was read as
+     part of what they said. The HTML spec's pattern puts the credit outside
+     the quote: a <figure> holding the <blockquote> and a <figcaption>. With
+     no attribution there is no caption, so the bare <blockquote> renders, as
+     before -- a figure with nothing to name it would only add an empty
+     "figure" for a screen reader to step through. */
   render() {
-    return html`
-      <blockquote cite=${this.cite || nothing}>
-        <slot></slot>${this.attribution ? html`<footer>\u2014 ${this.attribution}</footer>` : nothing}
-      </blockquote>
-    `;
+    const quote = html`<blockquote class=${this.attribution ? nothing : 'quote'} cite=${this.cite || nothing}><slot></slot></blockquote>`;
+    return this.attribution
+      ? html`<figure class="quote">${quote}<figcaption>\u2014 ${this.attribution}</figcaption></figure>`
+      : quote;
   }
 }
 

package/src/components/blockquote/blockquote.stories.js

@@ -28,9 +28,11 @@ optional attribution.
 | \`cite\` | URL of the source | \`''\` |
 
 ### Notes
-\`attribution\` renders as a \`<footer>\` inside the \`<blockquote>\`, prefixed with
-an em dash. That is the pairing the HTML spec recommends for a credit that
-belongs to the quote itself.
+\`attribution\` renders as a \`<figcaption>\`, prefixed with an em dash, beside
+the \`<blockquote>\` inside a \`<figure>\`. That is the HTML spec's pattern for
+crediting a quotation: everything inside a \`<blockquote>\` is the quote, so the
+name of the person quoted belongs outside it. Without an attribution there is
+no figure, only the \`<blockquote>\`.
 
 \`cite\` maps to the native \`cite\` attribute. It is **metadata only** — browsers
 do not render it and it is not a link, so if the source should be visible or
@@ -42,7 +44,7 @@ clickable, put it in \`attribution\` or in the slotted content.
   argTypes: {
     attribution: {
       control    : 'text',
-      description: 'Who said it. Renders as a footer inside the blockquote, prefixed with an em dash.',
+      description: 'Who said it. Renders as a figcaption beside the blockquote in a figure, prefixed with an em dash.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
     },
     cite: {

package/src/components/button/button.css.js

@@ -79,6 +79,11 @@ export default css`
        boundary, so the value is switched rather than the rule */
     --bd-button-accent-ring: var(--button-accent-ring-default);
 
+    /* the focus ring is switched the same way: surface="dark" swaps the blue
+       outline for a white one. white and outline-white do not read this; see
+       FOCUS. */
+    --bd-button-focus-ring: var(--button-shared-focus-outline);
+
     --bd-button-border-width: var(--border-width-2);
   }
 
@@ -121,14 +126,29 @@ export default css`
      FOCUS
      The design specifies no focus state, but 2.4.7 requires one.
 
+     The ring is an outline held 2px off the control, and the 2px between is
+     left transparent, so it is whatever surface the button sits on. That is
+     the one thing code can do here that Figma cannot, and it is why the two
+     differ. Figma builds a ring from spread shadows, every band of which is a
+     painted colour, so its library paints the gap and keeps one ring per
+     surface: focus/ring-primary on light, focus/ring-inverse on dark and
+     brand. Painted in code, that gap is what went wrong twice: a white band
+     merged into a white fill on surface="dark", and the neutral-900 band
+     that replaced it drew a black outline round every button on a brand
+     hero. A transparent gap cannot do either, on any surface.
+
+     So only the colour switches: blue on light, white under surface="dark",
+     which covers a brand hero and a neutral one alike; the numbers are on
+     --focus-outline-traditional. Every variant takes the same ring, ghost
+     included. An outline is also kept in forced-colors mode, where a
+     box-shadow ring is not drawn at all.
+
+     The rule leaves box-shadow alone, so an outlined variant's own boundary
+     in --bd-button-edge stays put while focused.
+
      This used to be driven from JavaScript: two requestAnimationFrame hops
      checked :focus-visible and set a data attribute the CSS then styled.
-     :focus-visible does that natively, so the detection is gone and the ring
-     is the shared one from Foundations/Focus — a two-colour ring whose white
-     inner band keeps it visible on a coloured hero, which the old
-     single-colour outline could not do. It is composed with
-     --bd-button-edge rather than replacing it, so an outlined variant keeps
-     its own boundary while focused; see the note on that property.
+     :focus-visible does that natively.
      ============================================ */
   button:focus,
   a:focus {
@@ -136,21 +156,17 @@ export default css`
   }
 
   .button:focus-visible {
-    outline: none;
-    box-shadow: var(--focus-outline-primary), var(--bd-button-edge);
+    outline: var(--bd-button-focus-ring);
+    outline-offset: var(--button-shared-focus-outlineOffset);
   }
 
-  /* A white control needs the ring the other way up. --focus-outline-primary
-     puts its WHITE band against the control, which is what keeps it visible on
-     a coloured hero -- and is exactly wrong when the control is itself white:
-     measured on Button — White / Outline-White, the inner band was 1.00:1
-     against the button's own fill and the blue band 2.38:1 against the hero
-     (1.75:1 at the gradient's light end), so neither reached the 3:1 WCAG
-     2.4.11 asks. outline-white is here too because restoring its boundary
-     above puts a white border where the white band used to sit on the hero. */
+  /* white and outline-white are presets for a coloured banner and ignore
+     surface, so they take the white ring on their own: 4.53:1 on blue-500,
+     7.95:1 at the light end of the banner gradient. A blue ring there was
+     2.38:1, and 1.75:1 at that end. */
   .button--white:focus-visible,
   .button--outline-white:focus-visible {
-    box-shadow: var(--focus-outline-inverse), var(--bd-button-edge);
+    outline: var(--focus-outline-traditional-inverse);
   }
 
   a.button {
@@ -175,14 +191,14 @@ export default css`
     vertical-align: middle;
     box-sizing: border-box;
 
-    /* The variant's own boundary, held in a custom property so the focus ring
-       can COMPOSE with it. box-shadow is a single list, not additive, and
-       .button:focus-visible (0,2,0) outranks .button--ghost (0,1,0) -- so a
-       focus rule that declared box-shadow directly erased the border of every
-       outlined variant. A focused ghost button lost its dark outline and wore
-       a blue ring instead, which read as a tertiary button. The default is a
-       zero-spread transparent shadow rather than the keyword none, so the value
-       a valid shadow the focus rule can append to. */
+    /* The variant's own boundary, held in a custom property so each state can
+       switch it. It was introduced while the focus ring was a box-shadow, so
+       the ring could COMPOSE with it: box-shadow is a single list, not
+       additive, and .button:focus-visible (0,2,0) outranks .button--ghost
+       (0,1,0) -- so a focus rule that declared box-shadow directly erased the
+       border of every outlined variant, and a focused ghost button read as a
+       tertiary one. The ring is an outline now and does not touch box-shadow;
+       a focus rule that goes back to declaring it brings that defect back. */
     --bd-button-edge: 0 0 0 0 transparent;
     box-shadow: var(--bd-button-edge);
 
@@ -557,6 +573,11 @@ export default css`
     /* unchanged red, plus a boundary against the hero */
     --bd-button-accent-ring: var(--color-neutral-0);
 
+    /* a white ring, the one colour that clears 3:1 on a brand hero and a
+       neutral one alike, which this surface has to cover without knowing
+       which it is on. The gap inside it is the hero itself; see FOCUS. */
+    --bd-button-focus-ring: var(--focus-outline-traditional-inverse);
+
     /* muted downward instead of upward: a neutral-100 fill would read as an
        active control on a dark hero. Exempt from contrast under WCAG 1.4.3. */
     --bd-button-disabled-bg: var(--color-neutral-700);  /* no role: on-dark ground; see the block note */

package/src/components/button/button.js

@@ -29,6 +29,14 @@ const SIZE_CLASS = { sm: "button--small", md: "button--medium", lg: "button--lar
 const SURFACES = ["light", "dark"];
 const SHAPES = ["default", "rounded"];
 
+/* custom-click bubbles and is composed, like every sibling event in the
+   package -- bd-checkbox's and bd-radio's change, bd-switch's and
+   bd-custom-input's bd-change. It was a plain Event, which does not bubble,
+   so it reached a listener on the button itself and nothing above it: a form
+   or a card delegating from a wrapper heard nothing. composed carries it out
+   of any shadow root the button is rendered inside, too. */
+const clickEvent = () => new CustomEvent("custom-click", { bubbles: true, composed: true });
+
 /**
  * Everything bd-button and bd-button-link share.
  *
@@ -42,31 +50,37 @@ class BdButtonBase extends LitElement {
   static styles = [buttonsCSS];
 
   static properties = {
-    label     : { type: String },
-    size      : { type: String },
-    variant   : { type: String, reflect: true },
+    label      : { type: String },
+    size       : { type: String },
+    variant    : { type: String, reflect: true },
     /** @deprecated pass `variant`. kind meant four different things across the
         atoms; on this one it always meant appearance. */
-    kind      : { type: String },
-    fullWidth : { type: Boolean, attribute: "fullwidth" },
-    strong    : { type: Boolean },
-    disabled  : { type: Boolean, reflect: true },
-    loading   : { type: Boolean, reflect: true },
-    fontSize  : { type: String, attribute: "font-size" },
-    fontWeight: { type: String, attribute: "font-weight" },
-    align     : { type: String },
-    surface   : { type: String, reflect: true },
+    kind       : { type: String },
+    fullWidth  : { type: Boolean, attribute: "fullwidth" },
+    strong     : { type: Boolean },
+    disabled   : { type: Boolean, reflect: true },
+    loading    : { type: Boolean, reflect: true },
+    fontSize   : { type: String, attribute: "font-size" },
+    fontWeight : { type: String, attribute: "font-weight" },
+    align      : { type: String },
+    surface    : { type: String, reflect: true },
     /** "rounded" takes the pill corner; see .button--rounded. */
-    shape     : { type: String, reflect: true },
+    shape      : { type: String, reflect: true },
     /** The accent variant reveals a trailing arrow on hover; this opts out. */
-    noArrow   : { type: Boolean, attribute: "no-arrow" },
+    noArrow    : { type: Boolean, attribute: "no-arrow" },
     /* A circle holding one icon instead of a label: the homepage's audience
        cards and the mobile menu toggle. A mode, not a variant, because every
        variant, size, surface and state applies to it unchanged -- which is how
        the Button icon sets in the foundation Figma file are drawn. With no
        visible text there is nothing to name the control, so label becomes
        required rather than optional. */
-    iconOnly  : { type: Boolean, attribute: "icon-only", reflect: true }
+    iconOnly   : { type: Boolean, attribute: "icon-only", reflect: true },
+    /* Extra text a screen reader reads after the name, through
+       aria-describedby on the inner control. It has to be carried in here:
+       the control is in this shadow root, so an aria-describedby written on
+       the host, or pointing at an id outside, never reaches it. bd-tooltip
+       sets it on a bd-button trigger; a page can set it directly. */
+    description: { type: String }
   };
 
   constructor() {
@@ -90,6 +104,7 @@ class BdButtonBase extends LitElement {
     this.shape = "default";
     this.noArrow = false;
     this.iconOnly = false;
+    this.description = "";
   }
 
   willUpdate(changed) {
@@ -162,6 +177,14 @@ class BdButtonBase extends LitElement {
    * lg 24 against padding 8, 12 and 16 -- so the size passes straight through
    * and the circle comes out 32, 44 and 56.
    */
+  get _describedBy() {
+    return this.description ? "description" : nothing;
+  }
+
+  get _description() {
+    return this.description ? html`<span id="description" hidden>${this.description}</span>` : nothing;
+  }
+
   get _iconContent() {
     if (this.loading) return html`<span class="spinner" aria-hidden="true"></span>`;
     return html`<slot><bd-arrow-icon size="${this.size}" aria-hidden="true"></bd-arrow-icon></slot>`;
@@ -173,7 +196,7 @@ class BdButtonBase extends LitElement {
       e.stopPropagation();
       return;
     }
-    this.dispatchEvent(new Event("custom-click"));
+    this.dispatchEvent(clickEvent());
   }
 }
 
@@ -186,10 +209,11 @@ class Button extends BdButtonBase {
         class="${this._classes}"
         aria-label="${this.label || nothing}"
         aria-busy="${this.loading ? "true" : nothing}"
+        aria-describedby="${this._describedBy}"
         ?disabled="${this.disabled}"
         style="${this._inlineStyle}"
         @click=${this._handleClick}
-      >${this._content}</button>
+      >${this._content}</button>${this._description}
     `;
   }
 }
@@ -211,35 +235,11 @@ class ButtonLink extends BdButtonBase {
     super();
     this.href = "";
     this.buyLink = false;
-    this.shadow = true;
     this.align = "left";
     this.target = "";
     this.rel = "";
   }
 
-  _onFocusin(e) {
-    const el = e.currentTarget;
-    requestAnimationFrame(() =>
-      requestAnimationFrame(() => {
-        if (el.matches(':focus-visible')) {
-          this.setAttribute('data-bd-button-focus', '');
-        }
-      })
-    );
-  }
-
-  _onFocusout() {
-    this.removeAttribute('data-bd-button-focus');
-  }
-
-  get fullWidthClass() {
-    return this.fullWidth ? "max--width" : "";
-  }
-
-  get strongClass() {
-    return this.strong ? "button--bold" : "";
-  }
-
   /* Reverse tabnabbing is the reason rather than convention: a new tab opened
      from here keeps a window.opener handle back unless rel says otherwise. An
      explicit rel always wins, so a consumer can still opt out deliberately. */
@@ -265,11 +265,12 @@ class ButtonLink extends BdButtonBase {
         aria-label="${this.label || nothing}"
         aria-busy="${this.loading ? "true" : nothing}"
         aria-disabled="${this.disabled ? "true" : nothing}"
+        aria-describedby="${this._describedBy}"
         style="${this._inlineStyle}"
         @click=${this._handleClick}
         ?data-store-render="${this.buyLink}"
         ?data-store-buy-link="${this.buyLink}"
-      >${this._content}</a>
+      >${this._content}</a>${this._description}
     `;
   }
 }
@@ -297,7 +298,7 @@ class ContactButton extends LitElement {
   }
 
   _handleClick() {
-    this.dispatchEvent(new Event("custom-click"));
+    this.dispatchEvent(clickEvent());
   }
 
   render() {

package/src/components/button/button.stories.js

@@ -100,7 +100,7 @@ variant, so every \`variant\`, \`size\`, \`surface\` and state applies unchanged
 | \`right\` | Aligns button to the right |
 
 ### Events
-- \`custom-click\` — dispatched on click or Enter/Space keypress
+- \`custom-click\` — dispatched on click or Enter/Space keypress. It bubbles and is composed, so a wrapper can listen for it
         `
       }
     }
@@ -430,7 +430,7 @@ export const ButtonKeyboard = {
     <p style="font-size:14px; margin-bottom:8px;">Tab to focus, press Enter or Space to trigger.</p>
     <bd-button variant="primary" size="md" label="Keyboard test">Press me</bd-button>
   `,
-  parameters: { docs: { description: { story: 'Demonstrates keyboard activation. Enter/Space trigger `custom-click` and toggle the `active` class briefly.' } } }
+  parameters: { docs: { description: { story: 'Demonstrates keyboard activation. Enter and Space trigger `custom-click`.' } } }
 };
 
 // ─── bd-button-link Stories ────────────────────────────────────────────────

package/src/components/caption/caption.css.js

@@ -13,7 +13,17 @@ export const captionCSS = css`
     color: var(--typography-caption-default-color);
   }
 
+  /* sm takes the caption-small role whole. Today it differs from
+     caption-default in tracking alone -- 0.025em against 0, the design's
+     caption/small -- so reading only letter-spacing drew the same thing, but
+     left the role's other four axes unread, and a change to any of them would
+     never have reached the element. The colour stays the default's: the role
+     carries none of its own. */
   :host([size='sm']) figcaption {
+    font-family: var(--typography-caption-small-fontFamily);
+    font-size: var(--typography-caption-small-fontSize);
+    font-weight: var(--typography-caption-small-fontWeight);
+    line-height: var(--typography-caption-small-lineHeight);
     letter-spacing: var(--typography-caption-small-letterSpacing);
   }
 `;

package/src/components/caption/caption.stories.js

@@ -23,11 +23,11 @@ export default {
 ### Props
 | Prop | Values | Default |
 |---|---|---|
-| \`size\` | \`default\`, \`small\` | \`default\` |
+| \`size\` | \`md\`, \`sm\` — \`sm\` is the same size tracked wider (\`caption-small\`); \`default\` / \`small\` still resolve | \`md\` |
 
 ### Contrast
 The caption is \`--color-neutral-600\`, which is 6.59:1 on white and stays above
-4.5:1 at the \`small\` size too. Caption text is the most common place a design
+4.5:1 at the \`sm\` size too. Caption text is the most common place a design
 system slips below AA, because it is both small and grey — anything lighter
 than \`neutral-600\` would not clear it.
 
@@ -46,9 +46,9 @@ and reach for this only where the styling alone is wanted.
   argTypes: {
     size: {
       control    : { type: 'select' },
-      options    : ['default', 'small'],
+      options    : ['md', 'sm'],
       description: 'Type size of the caption.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     }
   }
 };