@repobit/dex-system-design 1.0.0 → 2.0.0

package/schemas/component-manifest.json

@@ -1,7 +1,7 @@
 {
   "manifestVersion": 1,
   "package": "@repobit/dex-system-design",
-  "packageVersion": "1.0.0",
+  "packageVersion": "2.0.0",
   "generatedFrom": [
     "package.json exports",
     "Lit static properties",
@@ -188,7 +188,7 @@
     },
     {
       "tag": "bd-custom-input-clipboard",
-      "packageExport": "./input",
+      "packageExport": "./input-clipboard",
       "module": "./src/components/input/input-clipboard.js",
       "role": "form",
       "contentModel": "none",
@@ -231,7 +231,8 @@
         },
         {
           "name": "focused",
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Has keyboard focus. Setting it moves focus into the field and clearing it blurs the field; it reflects whether the field is focused. Set it on at most one field, since only one can hold focus."
         },
         {
           "name": "tooltip",
@@ -253,7 +254,16 @@
           "name": "value",
           "type": "string",
           "description": "The field contents. A paste button sits over the right-hand end and fills it from the clipboard."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Carried on the bd-input and bd-change event detail. NOT submitted with a form — the input lives in a shadow root."
         }
+      ],
+      "events": [
+        "bd-input",
+        "bd-change"
       ]
     },
     {
@@ -479,10 +489,11 @@
           "name": "size",
           "type": "string",
           "enum": [
-            "small",
-            "default",
-            "large"
-          ]
+            "sm",
+            "md",
+            "lg"
+          ],
+          "description": "A size step. small, default and large still resolve, and are rewritten to these."
         }
       ]
     },
@@ -622,6 +633,11 @@
         "custom-click"
       ],
       "props": [
+        {
+          "name": "description",
+          "type": "string",
+          "description": "Extra text a screen reader reads after the name, wired with aria-describedby inside the shadow root, where the control is. bd-tooltip sets it on a trigger."
+        },
         {
           "name": "variant",
           "type": "string",
@@ -767,6 +783,11 @@
         "custom-click"
       ],
       "props": [
+        {
+          "name": "description",
+          "type": "string",
+          "description": "Extra text a screen reader reads after the name, wired with aria-describedby inside the shadow root, where the control is. bd-tooltip sets it on a trigger."
+        },
         {
           "name": "variant",
           "type": "string",
@@ -933,9 +954,10 @@
           "name": "size",
           "type": "string",
           "enum": [
-            "default",
-            "small"
-          ]
+            "sm",
+            "md"
+          ],
+          "description": "A size step; only sm has a rule of its own. default and small still resolve, and are rewritten to these."
         }
       ]
     },
@@ -1154,28 +1176,15 @@
       "role": "action",
       "contentModel": "none",
       "props": [
-        {
-          "name": "variant",
-          "type": "string",
-          "enum": [
-            "primary",
-            "secondary",
-            "tertiary",
-            "ghost",
-            "accent",
-            "white",
-            "outline-white"
-          ],
-          "description": "Visual variant. Replaces kind, which meant appearance here and size or marker elsewhere; kind still resolves. tertiary is a blue outline, ghost a dark outline, accent the red conversion fill — red is not a danger signal in this system. white and outline-white are fixed presets for a solid-colour banner and ignore surface on purpose."
-        },
         {
           "name": "label",
           "type": "string",
-          "description": "Both the visible text and the accessible name for this preset."
+          "description": "Both the visible text and the accessible name. Defaults to \"Contact us\"."
         },
         {
           "name": "href",
-          "type": "string"
+          "type": "string",
+          "description": "Where the CTA goes. It renders an <a>, so without one it is not a link."
         },
         {
           "name": "align",
@@ -1184,7 +1193,8 @@
             "left",
             "center",
             "right"
-          ]
+          ],
+          "description": "Horizontal placement, as on bd-button. Set it as an attribute."
         },
         {
           "name": "shape",
@@ -1195,6 +1205,9 @@
           ],
           "description": "Corner shape. rounded takes --radius-3xl whatever the size; default keeps the size band's radius."
         }
+      ],
+      "events": [
+        "custom-click"
       ]
     },
     {
@@ -1245,7 +1258,21 @@
         {
           "name": "disabled",
           "type": "boolean"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "description": "The chosen option. Read it, or set it to choose one; unset, or set to an option that is not there, it is the first. Carried on the bd-input / bd-change detail."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Carried on the bd-input and bd-change event detail. NOT submitted with a form — the select lives in a shadow root."
         }
+      ],
+      "events": [
+        "bd-input",
+        "bd-change"
       ]
     },
     {
@@ -1287,7 +1314,8 @@
         },
         {
           "name": "focused",
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Has keyboard focus. Setting it moves focus into the field and clearing it blurs the field; it reflects whether the field is focused. Set it on at most one field, since only one can hold focus."
         },
         {
           "name": "tooltip",
@@ -1488,7 +1516,16 @@
         },
         {
           "name": "thickness",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "0",
+            "1",
+            "2",
+            "3",
+            "4",
+            "8"
+          ],
+          "description": "A border-width step, resolved to var(--border-width-N). \"1px\" and the other px spellings are read as their step; anything else is the 1px step."
         },
         {
           "name": "color",
@@ -2061,7 +2098,15 @@
         },
         {
           "name": "fit",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "cover",
+            "contain",
+            "fill",
+            "none",
+            "scale-down"
+          ],
+          "description": "object-fit for the image. Applied as a class; any other value falls back to \"cover\"."
         },
         {
           "name": "radius",
@@ -2080,7 +2125,15 @@
         },
         {
           "name": "shadow",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "none",
+            "sm",
+            "md",
+            "lg",
+            "xl"
+          ],
+          "description": "A shadow step. Applied as a class; any other value falls back to \"none\"."
         }
       ]
     },
@@ -2133,10 +2186,11 @@
           "name": "size",
           "type": "string",
           "enum": [
-            "small",
-            "default",
-            "large"
-          ]
+            "sm",
+            "md",
+            "lg"
+          ],
+          "description": "A size step. small, default and large still resolve, and are rewritten to these."
         },
         {
           "name": "for",
@@ -2320,6 +2374,11 @@
       "role": "content",
       "contentModel": "text-or-children",
       "props": [
+        {
+          "name": "description",
+          "type": "string",
+          "description": "Extra text a screen reader reads after the link's name, wired with aria-describedby inside the shadow root, where the <a> is. bd-tooltip sets it on a trigger."
+        },
         {
           "name": "variant",
           "type": "string",
@@ -2401,6 +2460,11 @@
             "error"
           ],
           "description": "A semantic colour role, not a CSS colour. Resolves to a palette token."
+        },
+        {
+          "name": "arrow",
+          "type": "boolean",
+          "description": "A trailing arrow after the label, for a standalone call-to-action link such as Read more. Every variant, state and surface applies; the arrow takes the link's ink. Slot a bd-*-icon into slot=\"icon\" to swap the glyph. It is decorative: the label must say where the link goes."
         }
       ]
     },
@@ -2413,15 +2477,32 @@
       "props": [
         {
           "name": "type",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "unordered",
+            "ordered"
+          ],
+          "description": "The tag: <ul> or <ol>. Any other value falls back to \"unordered\"."
         },
         {
           "name": "spacing",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "description": "The gap between items when horizontal. Any other value falls back to \"md\"."
         },
         {
           "name": "variant",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "default",
+            "compact",
+            "spacious"
+          ],
+          "description": "The gap between items. Any other value falls back to \"default\"."
         },
         {
           "name": "start",
@@ -2429,7 +2510,12 @@
         },
         {
           "name": "orientation",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "vertical",
+            "horizontal"
+          ],
+          "description": "Flow of the items. Any other value falls back to \"vertical\"."
         }
       ]
     },
@@ -2549,9 +2635,10 @@
             "small",
             "regular",
             "large",
-            "lead"
+            "lead",
+            "eyebrow"
           ],
-          "description": "Body type role. Replaces kind, which still resolves."
+          "description": "Body type role. Replaces kind, which still resolves. eyebrow is the short brand-ink label above a section title, in text-brand: the label-large role (16px, Medium 500) from lg up, label-default (14px) below lg."
         },
         {
           "name": "kind",
@@ -2652,7 +2739,7 @@
             "warning",
             "error"
           ],
-          "description": "A text colour role, the same vocabulary as bd-h. Anything else is dropped."
+          "description": "A semantic colour role, not a CSS colour, the same set bd-h and bd-display take. primary is brand blue; inverse is white on a dark or brand band."
         }
       ]
     },
@@ -2732,6 +2819,66 @@
         }
       ]
     },
+    {
+      "tag": "bd-pagination-dots",
+      "packageExport": "./pagination-dots",
+      "module": "./src/components/pagination-dots/pagination-dots.js",
+      "role": "navigation",
+      "contentModel": "none",
+      "events": [
+        "bd-change",
+        "bd-toggle"
+      ],
+      "props": [
+        {
+          "name": "count",
+          "type": "number",
+          "description": "How many dots, one per slide or page. Below 2 nothing renders."
+        },
+        {
+          "name": "current",
+          "type": "number",
+          "description": "Which dot is current, 1-based, held between 1 and count. The owner of the slides sets it; a visitor's pick fires bd-change with detail.current."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "default": "Slides",
+          "description": "Accessible name of the group: what the dots move through. Set it in the page's language."
+        },
+        {
+          "name": "itemLabel",
+          "type": "string",
+          "attributeName": "item-label",
+          "default": "Go to slide",
+          "description": "Starts each dot's accessible name; the dot's number follows it. Set it in the page's language."
+        },
+        {
+          "name": "autoplay",
+          "type": "boolean",
+          "default": false,
+          "description": "The atom advances itself every delay ms, wrapping after the last slide, and the current pill fills as the time runs. Each advance fires bd-change like a click. Picking a dot stops it for good (WCAG 2.2.2); it never starts under prefers-reduced-motion."
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "default": 4000,
+          "description": "Milliseconds each slide shows under autoplay. Held at 1000 or more."
+        },
+        {
+          "name": "paused",
+          "type": "boolean",
+          "default": false,
+          "description": "Autoplay stopped for good: set when the visitor picks a dot, or under prefers-reduced-motion, and otherwise only by the owner. bd-toggle reports it."
+        },
+        {
+          "name": "held",
+          "type": "boolean",
+          "default": false,
+          "description": "A transient hold the owner sets while the pointer or focus is on its slides. The atom holds itself the same way while the pointer or focus is on the dots."
+        }
+      ]
+    },
     {
       "tag": "bd-picture",
       "packageExport": "./picture",
@@ -2767,7 +2914,15 @@
         },
         {
           "name": "fit",
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "cover",
+            "contain",
+            "fill",
+            "none",
+            "scale-down"
+          ],
+          "description": "object-fit for the fallback image. Applied as a class; any other value falls back to \"cover\"."
         },
         {
           "name": "radius",
@@ -2886,7 +3041,8 @@
             "info",
             "success",
             "error"
-          ]
+          ],
+          "description": "Colour of the fill. Unset is the default fill; any other value is cleared."
         }
       ]
     },
@@ -2960,10 +3116,11 @@
           "name": "size",
           "type": "string",
           "enum": [
-            "small",
-            "default",
-            "large"
-          ]
+            "sm",
+            "md",
+            "lg"
+          ],
+          "description": "A size step. small, default and large still resolve, and are rewritten to these."
         },
         {
           "name": "surface",
@@ -3251,7 +3408,8 @@
         },
         {
           "name": "controls",
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Native playback controls, on by default. In HTML, controls=\"false\" turns them off; leaving the attribute out does not. Off only for decoration that is muted and loops."
         },
         {
           "name": "muted",

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>
     `;
   }