@repobit/dex-system-design 1.0.1 → 2.0.0

package/schemas/manifest-omissions.json

@@ -51,6 +51,7 @@
  "bd-compare-section: component declares \"scoreLabel\" but the manifest omits it",
  "bd-compare-section: component declares \"variant\" but the manifest omits it",
  "bd-contact-button: component declares \"buyLink\" but the manifest omits it",
+ "bd-contact-button: component declares \"description\" but the manifest omits it",
  "bd-contact-button: component declares \"disabled\" but the manifest omits it",
  "bd-contact-button: component declares \"fontSize\" but the manifest omits it",
  "bd-contact-button: component declares \"fontWeight\" but the manifest omits it",
@@ -64,6 +65,7 @@
  "bd-contact-button: component declares \"strong\" but the manifest omits it",
  "bd-contact-button: component declares \"surface\" but the manifest omits it",
  "bd-contact-button: component declares \"target\" but the manifest omits it",
+ "bd-contact-button: component declares \"variant\" but the manifest omits it",
  "bd-feature-col is registered by ./features but absent from the manifest",
  "bd-features is registered by ./features but absent from the manifest",
  "bd-features-tab is registered by ./features-tab but absent from the manifest",

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

@@ -58,6 +58,12 @@ export const accordionItem = css`
     position: relative;
     z-index: var(--z-base);
     box-shadow: var(--focus-outline-primary);
+    /* 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);
   }
 
   :host(:last-child) {
@@ -367,7 +373,12 @@ export const accordionSection = css`
   }
 
   .user-guide-link 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/agent-endpoints/agent-endpoints.js

@@ -31,7 +31,7 @@ class AgentEndpoints extends LitElement {
     return html`
       <div class="bd-ensemble bd-agentendpoints-wrapper">
         ${this.eyebrow
-          ? html`<bd-p variant="regular" font-weight="semibold" class="bd-agentendpoints-eyebrow"><slot name="eyebrow">${this.eyebrow}</slot></bd-p>`
+          ? html`<bd-p variant="eyebrow" class="bd-agentendpoints-eyebrow"><slot name="eyebrow">${this.eyebrow}</slot></bd-p>`
           : nothing}
 
         ${this.title

package/src/components/alert/alert.css.js

@@ -177,7 +177,17 @@ export const alertCSS = css`
     display: none;
   }
 
+  /* A 24px target around the 16px icon. The button was the icon and
+     nothing else, 16x16, under the 24px WCAG 2.5.8 asks of a pointer target
+     -- and an alert's close button is the one control on it a reader is
+     trying to hit. The ::before below is that target: it reaches
+     --spacing-4 past the button on each side, and a click on it is a click
+     on the button -- 24x24 at the default text size, and larger, never
+     smaller, for a reader who enlarges their text, since the reach is rem.
+     The button's own box is unchanged, so the icon sits exactly where it did
+     and the alert is no taller. */
   .dismiss {
+    position: relative;
     flex: none;
     display: flex;
     padding: var(--spacing-0);
@@ -188,9 +198,20 @@ export const alertCSS = css`
     cursor: pointer;
   }
 
+  .dismiss::before {
+    content: "";
+    position: absolute;
+    inset: calc(-1 * var(--spacing-4));
+  }
+
   /* One token, one painter -- the same invariant accordion.css.js records. */
   .dismiss: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);
   }
 `;

package/src/components/anchor/anchor-nav.css.js

@@ -54,7 +54,12 @@ export const anchorNavStyles = css`
   .bd-anchor-nav__dropdown-toggle:focus-visible,
   .bd-anchor-nav__dropdown-option: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);
     /* No border-radius here, for the reason back.css.js records: the ring is a
        box-shadow and already follows the shape of what it sits on, and both of

package/src/components/annotation/annotation.css.js

@@ -33,7 +33,12 @@ export const annotationCSS = css`
     /* the one focus ring — see Foundations/Focus. A two-colour ring whose
        white inner band keeps it visible on a coloured or dark surface, which
        a single-colour outline cannot do. */
-    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/architecture.stories.js

@@ -146,10 +146,12 @@ export const LayerModel = () =>
     lede : 'Foundations, Atoms, Components, Modules, Layout, and internal primitives — what each one owns in ' +
            'this repository, with the rules for adding to them. Derived from the library as it stands, not from a ' +
            'textbook hierarchy.',
-    note: html`This page is documentation. It is filed under its own group because
-      <code>lint:tokens</code> reads the atom tier from a story&rsquo;s <code>title</code>, and
-      <code>verify:typography</code> builds its population from the <code>Atoms/</code> and
-      <code>Components/</code> prefixes — so where a page is filed changes what the gates believe.`,
+    note: html`This page is documentation, and where it is filed changes nothing the gates
+      believe. <code>lint:tokens</code> and <code>verify:typography</code> read each unit&rsquo;s layer
+      from <code>scripts/architecture.json</code>, keyed on its source path — not from a story&rsquo;s
+      <code>title</code>, which is what they used to read — so a page can be moved between groups
+      without changing what is enforced. This one is recorded there as <code>FOUNDATION</code>; see
+      <em>Where classification lives</em> below.`,
     children: html`
       ${refSection({ name: 'The six layers', meta: 'what belongs where', children: layerTable() })}
 

package/src/components/avatar/avatar.js

@@ -1,4 +1,4 @@
-import { LitElement, html } from 'lit';
+import { LitElement, html, nothing } from 'lit';
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import '../../tokens/tokens.js';
 import { avatarCSS } from './avatar.css.js';
@@ -8,9 +8,10 @@ export class BdAvatar extends LitElement {
   static styles = [avatarCSS];
 
   static properties = {
-    src : { type: String },
-    name: { type: String },
-    size: { type: String, reflect: true }
+    src    : { type: String },
+    name   : { type: String },
+    size   : { type: String, reflect: true },
+    _failed: { state: true }
   };
 
   constructor() {
@@ -23,17 +24,42 @@ export class BdAvatar extends LitElement {
   willUpdate(changed) {
     // small / default / large still resolve; see shared/prop-vocabulary.js
     if (changed.has('size')) this.size = resolveSize(this.size, 'md');
+    // a new image gets its own chance to load
+    if (changed.has('src')) this._failed = false;
   }
 
+  /* The first letter of each word, at most two, upper-cased. name can be
+     null -- a removed attribute sets it so -- and used to throw on split. */
+  get _initials() {
+    return (this.name ?? '').trim()
+      .split(/\s+/)
+      .map(w => w[0] || '')
+      .join('')
+      .slice(0, 2)
+      .toUpperCase();
+  }
+
+  /* THE FALLBACKS.
+     An image that fails to load used to stay on screen as an empty circle;
+     it now falls back to the initials, as having no src does.
+
+     With no name there is nothing to say, so the avatar is hidden from
+     assistive technology instead of being announced: it used to be an img
+     named "Avatar", which tells a screen reader user only that a picture is
+     there, on every avatar in a list. */
   render() {
+    const name = (this.name ?? '').trim();
+    const showImage = this.src && !this._failed;
     return html`
-      <span class="avatar" role="img" aria-label=${this.name || 'Avatar'}>
-        ${this.src
-          ? html`<img src=${this.src} alt="" />`
-          : html`${this.name.split(' ').map(w => w[0] || '')
-            .join('')
-            .slice(0, 2)
-            .toUpperCase()}`}
+      <span
+        class="avatar"
+        role=${name ? 'img' : nothing}
+        aria-label=${name || nothing}
+        aria-hidden=${name ? nothing : 'true'}
+      >
+        ${showImage
+          ? html`<img src=${this.src} alt="" @error=${() => { this._failed = true; }} />`
+          : this._initials}
       </span>
     `;
   }

package/src/components/avatar/avatar.stories.js

@@ -23,7 +23,7 @@ there is no image.
 |---|---|---|
 | \`src\` | image URL — omit to fall back to initials | \`''\` |
 | \`name\` | the person's name | \`''\` |
-| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+| \`size\` | \`sm\`, \`md\`, \`lg\` — \`small\` / \`default\` / \`large\` still resolve | \`md\` |
 
 ### Always pass a name
 \`name\` does two jobs. It is the source of the initials when there is no \`src\`,
@@ -31,9 +31,13 @@ and it is the accessible name in both cases — the wrapper carries
 \`role="img"\` with \`aria-label\` from \`name\`, and the inner image is given an
 empty \`alt\` so it is not announced twice.
 
-Without a \`name\` the accessible name falls back to the literal string
-"Avatar", which tells a screen reader user nothing. Pass one even when you have
-an image.
+Without a \`name\` the avatar has nothing to say, so it is hidden from assistive
+technology rather than announced — it used to be an image named "Avatar", which
+tells a screen reader user nothing. Pass one even when you have an image.
+
+### When the image does not load
+A \`src\` that fails to load falls back to the initials, the same as no \`src\`
+at all. A new \`src\` gets its own chance to load.
 
 ### How the initials are derived
 The first letter of each whitespace-separated word, capped at two characters
@@ -57,9 +61,9 @@ first and last.
     },
     size: {
       control    : { type: 'select' },
-      options    : ['small', 'default', 'large'],
+      options    : ['sm', 'md', 'lg'],
       description: 'Diameter of the avatar.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     }
   }
 };

package/src/components/awards/awards-flex.css.js

@@ -203,136 +203,21 @@ export const awardsFlexCSS = css`
     margin: 0;
   }
 
-  /* === DOTS === */
-  /* Dots and the pause control share one row; the dots keep their own spacing
-     so the treatment is unchanged when no control is shown. */
-  .bd-awardsflex-controls {
-    display: flex;
-    align-items: center;
-    gap: var(--spacing-16);
-  }
-
-  .bd-awardsflex-dots {
-    display: flex;
-    /* The buttons below carry their own 24px of target, so the space between
-       two dots now comes from the boxes rather than from a gap. Adding one on
-       top would push them apart without making either easier to hit. */
-    gap: 0;
+  /* === SLIDE CONTROLS ===
+     bd-pagination-dots, which also runs the autoplay clock. This file used to
+     draw its own dots and pause button -- a dot row that called itself a
+     tablist with no tabpanels, resting dots at neutral-300 (2.10:1 on the
+     tint, under the 3:1 a control needs), and a setInterval the dots knew
+     nothing about. The atom owns all of that now; the margin is all that is
+     left to decide here. */
+  bd-pagination-dots {
     margin-top: var(--spacing-8);
   }
 
-  .bd-awardsflex-autoplay-toggle {
-    margin-top: var(--spacing-8);
-    padding: var(--spacing-2) var(--spacing-8);
-    background: transparent;
-    border: var(--border-width-1) solid var(--color-border-default);
-    border-radius: var(--radius-full);
-    color: var(--color-text-muted);
-    font-family: var(--typography-fontFamily-sans);
-    /* no role: four roles sit at this size and each fails differently, so the
-       size stays a primitive. Note the weight is not declared here at all --
-       it inherits 400 -- which is why two of these are about what adopting a
-       role would ADD.
-       .
-       caption-default matches every value exactly, including the colour token:
-       xs / 400 / 1.5 / tracking 0 / sans, and its own colour axis is
-       --color-text-muted, which is what this rule already declares two lines
-       up. It renders as the same pixels. It is declined anyway, because
-       vertical-rhythm.stories.js documents it as "text under an image or a
-       figure" and this is the visible label of a toggle button. A
-       five-axis-plus-colour identity is the most seductive form of choosing a
-       role by its value rather than its meaning -- not an exemption from
-       CLAUDE.md's rule against that, but the case the rule is for.
-       .
-       caption-small carries the same wrong meaning and adds
-       letterSpacing-wide, which has no job on a five-letter word.
-       .
-       label-small is the right family -- "a small label: a badge, a tag, a
-       field hint" -- but the wrong result: it would declare a weight of 500
-       where nothing is declared today, and add wide tracking, making the
-       control bolder and 2.2px wider. This control is deliberately recessive:
-       muted, 2px of vertical padding, sitting beside the carousel dots as
-       chrome whose job is not to compete with the quote cards. Adopting a role
-       should not invert that.
-       .
-       control-label-small is the right meaning -- built for the name of a
-       control -- and fails on the leading. See the line below. */
-    font-size: var(--typography-fontSize-xs);
-    /* no role: and this leading in particular cannot move. The line box is
-       18px, which with 2px of padding and a 1px border makes the button
-       exactly 24px -- the same 24px as the .bd-awardsflex-dot buttons it shares
-       a row with, which are 24 square deliberately for the WCAG 2.5.8 target
-       size the comment further down explains.
-       .
-       control-label-small would take the line box to 15px and the button to
-       21px, misaligning it from the dots. Its tight leading exists for controls
-       whose height is DERIVED from padding + fontSize x lineHeight, the way
-       form-field computes one. This button's height is not derived -- it is
-       matched to a sibling. So the constraint is a pixel alignment between two
-       controls in one row, and nothing else in this file says so: a later pass
-       adopting control-label-small on meaning alone would quietly break the
-       row. */
-    line-height: var(--typography-lineHeight-normal);
-    cursor: pointer;
-  }
-
-  .bd-awardsflex-autoplay-toggle:hover {
-    color: var(--color-text-primary);
-    border-color: var(--color-border-strong);
-  }
-
-  .bd-awardsflex-autoplay-toggle:focus-visible {
-    /* the one focus ring — see Foundations/Focus */
-    outline: none;
-    box-shadow: var(--focus-outline-primary);
-    border-radius: var(--focus-outline-radius);
-  }
-
-  /* An 8px dot was an 8px target, which is a third of what WCAG 2.5.8 asks and
-     close enough to its neighbour that the 24px circles would have overlapped
-     as well. The button is the target and the dot is only what you see, so the
-     button is 24 square and the dot is drawn inside it at the size it always
-     was. Nothing about the component looks bigger; the part you can hit does. */
-  .bd-awardsflex-dot {
-    width: var(--dimension-24);
-    height: var(--dimension-24);
-    display: grid;
-    place-items: center;
-    border: none;
-    background: transparent;
-    padding: 0;
-    cursor: pointer;
-  }
-
-  .bd-awardsflex-dot::before {
-    content: "";
-    width: var(--spacing-8);
-    height: var(--spacing-8);
-    border-radius: 50%;
-    background: var(--color-neutral-300);
-    transition: background var(--transition-duration-normal) var(--transition-easing-ease),
-      transform var(--transition-duration-normal) var(--transition-easing-ease);
-  }
-
-  .bd-awardsflex-dot.active::before {
-    /* The current slide's mark, and it takes the indicator role now that the
-       role is not named for a shape. --indicator-color IS blue-500, so nothing
-       moves; what changes is that this dot and the tab/nav underlines can no
-       longer drift apart, which is the reason the role exists.
-       .
-       The geometry stays local on purpose: an underline slides its width, a dot
-       scales, so --indicator-underline-height and its transition are not this
-       component's to borrow. */
-    background: var(--indicator-color);
-    transform: scale(1.2);
-  }
-
-  .bd-awardsflex-dot:focus-visible {
-    /* the one focus ring — see Foundations/Focus. It follows the target, not
-       the dot, so keyboard focus is visible at the size the button really is. */
-    outline: none;
-    box-shadow: var(--focus-outline-primary);
-    border-radius: var(--radius-full);
+  @media (prefers-reduced-motion: reduce) {
+    .bd-awardsflex-carousel-track {
+      transition: none;
+    }
   }
 
   @media ${unsafeCSS(below('sm'))} {
@@ -342,12 +227,29 @@ export const awardsFlexCSS = css`
       min-height: var(--bd-awardsflex-min-height-mobile, 280px);
     }
 
-    .bd-awardsflex-quotes-row,
-    .bd-awardsflex-carousel-slide {
+    /* The static row stacks. The carousel slide does not: below sm it holds
+       one card, and in a column the card's 200px flex-basis became its
+       height. In the row it fills the width and takes its own height. */
+    .bd-awardsflex-quotes-row {
       flex-direction: column;
       align-items: center;
     }
 
+    /* A stacked card is as tall as what it holds. In the column, the card's
+       200px flex-basis became its height and the 160px min-height had nothing
+       left to do -- it keeps cards that stand side by side the same height,
+       and stacked cards stand side by side with nothing. Measured at 390:
+       200px cards whose content ended at 111 and 132. The width is the
+       column's, so a short quote no longer hugs its source line.
+       .
+       The carousel slide keeps the min-height: there it stops the section
+       jumping in height from one slide to the next. */
+    .bd-awardsflex-quotes-row .bd-awardsflex-quote-card {
+      flex: none;
+      width: 100%;
+      min-height: 0;
+    }
+
     .bd-awardsflex-quote-card {
       max-width: none;
     }