@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/skeleton/skeleton.stories.js

@@ -0,0 +1,70 @@
+import { html } from 'lit';
+import './skeleton.js';
+
+export default {
+  title     : 'Atoms/Skeleton',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdSkeleton** is a placeholder for content that has not arrived yet, shaped
+roughly like the thing it stands in for.
+
+### Usage
+\`\`\`html
+<bd-skeleton></bd-skeleton>
+<bd-skeleton lines="3"></bd-skeleton>
+<bd-skeleton shape="title"></bd-skeleton>
+<bd-skeleton shape="circle"></bd-skeleton>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`lines\` | number of bars | \`1\` |
+| \`shape\` | \`line\`, \`title\`, \`circle\` | \`line\` |
+
+### Notes
+With more than one line the last bar is drawn at 60% width, because real
+paragraphs do not end flush with the column.
+
+\`shape="circle"\` stands in for an avatar, \`title\` for a heading.
+
+### It is invisible to assistive tech, on purpose
+The whole thing carries \`aria-hidden="true"\`, so a screen reader is not read a
+list of meaningless bars.
+
+That means **the skeleton alone tells a screen reader user nothing is
+happening.** Pair it with a live region — an \`aria-busy\` on the container, or a
+\`<bd-spinner>\` with its own label — or the wait is silent for them.
+
+It respects \`prefers-reduced-motion\`: the shimmer stops and the bars settle to
+a static tint.
+        `
+      }
+    }
+  },
+  argTypes: {
+    lines: {
+      control    : 'number',
+      description: 'How many bars to draw. Above one, the last is shortened to 60%.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: "1" }, category: 'Structure' }
+    },
+    shape: {
+      control    : { type: 'select' },
+      options    : ['line', 'title', 'circle'],
+      description: 'What the placeholder stands in for.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "line" }, category: 'Appearance' }
+    }
+  }
+};
+
+export const Lines = () => html`
+    <bd-skeleton lines="3"></bd-skeleton>
+  `;
+
+export const Shapes = () => html`
+    <bd-skeleton shape="title"></bd-skeleton>
+    <bd-skeleton shape="circle"></bd-skeleton>
+  `;

package/src/components/spinner/spinner.css.js

@@ -0,0 +1,62 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const spinnerCSS = css`
+  /* The arc and the track are component-local properties rather than values
+     written into the rule, because a spinner is often the one thing on a
+     coloured panel and was previously pinned to blue-500 on neutral-200 —
+     3.5:1 against a white page, and invisible on a blue one. Set them on the
+     element to place it anywhere, or use surface="dark" for the common case.
+
+     bd-button does not use this element. Its loading mark is drawn inline
+     because it needs to be em-sized to track the button's own type scale,
+     currentColor to follow the variant's label, and decorative rather than
+     announced — the button already carries aria-busy. Three different
+     requirements from this component's one, so they stay separate. */
+  :host {
+    display: inline-flex;
+    --bd-spinner-arc: var(--color-action-primary);
+    --bd-spinner-track: var(--color-border-subtle);
+    /* no role: the two roles at blue-100 are the heavier tints of the brand
+       and info families -- a badge shade. This is a decorative pulse behind a
+       spinning arc, which is not that job. Note the name says "fill" and .pulse
+       reads it as a background, so the gate's kind inference is off by a
+       category here; the classification does not depend on it. */
+    --bd-spinner-pulse-fill: var(--color-blue-100);
+  }
+
+  :host([surface='dark']) {
+    --bd-spinner-arc: var(--color-neutral-0);
+    --bd-spinner-track: color-mix(in srgb, var(--color-neutral-0) 30%, transparent);
+    /* no role: an alpha value, which an opaque palette cannot express at all --
+       the same class as the scrim in modal.css.js. */
+    --bd-spinner-pulse-fill: color-mix(in srgb, var(--color-neutral-0) 30%, transparent);
+  }
+
+  .spinner {
+    width: var(--dimension-24);
+    height: var(--dimension-24);
+    border: var(--border-width-2) solid var(--bd-spinner-track);
+    border-top-color: var(--bd-spinner-arc);
+    border-radius: var(--radius-full);
+    animation: bd-spin var(--transition-duration-slower) var(--transition-easing-linear) infinite;
+  }
+
+  :host([size='sm']) .spinner { width: var(--dimension-16); height: var(--dimension-16); }
+  :host([size='lg']) .spinner { width: var(--dimension-40); height: var(--dimension-40); }
+
+  @keyframes bd-spin { to { transform: rotate(360deg); } }
+
+  /* a spinner that cannot spin should still say something, so fall back to a
+     pulse rather than freezing solid */
+  @media (prefers-reduced-motion: reduce) {
+    .spinner {
+      animation: bd-pulse var(--transition-duration-slower) var(--transition-easing-smooth) infinite alternate;
+      border-top-color: var(--bd-spinner-track);
+      background: var(--bd-spinner-pulse-fill);
+    }
+    @keyframes bd-pulse { to { opacity: var(--opacity-pulse); } }
+  }
+`;
+
+export default spinnerCSS;

package/src/components/spinner/spinner.js

@@ -0,0 +1,38 @@
+import { LitElement, html } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { spinnerCSS } from './spinner.css.js';
+import { resolveSize } from '../shared/prop-vocabulary.js';
+
+export class BdSpinner extends LitElement {
+  static styles = [spinnerCSS];
+
+  static properties = {
+    size   : { type: String, reflect: true },
+    label  : { type: String },
+    /* The surface the spinner sits on. Its default arc and track were both
+       chosen against a white page, so on a filled panel it all but disappears.
+       Same attribute, same meaning, as on bd-button. */
+    surface: { type: String, reflect: true }
+  };
+
+  constructor() {
+    super();
+    this.size = 'md';
+    this.label = 'Loading';
+    this.surface = 'light';
+  }
+
+  willUpdate(changed) {
+    // small / default / large still resolve; see shared/prop-vocabulary.js
+    if (changed.has('size')) this.size = resolveSize(this.size, 'md');
+  }
+
+  render() {
+    return html`
+      <span class="spinner" role="status" aria-label=${this.label}></span>
+    `;
+  }
+}
+
+customElements.define('bd-spinner', BdSpinner);

package/src/components/spinner/spinner.stories.js

@@ -0,0 +1,92 @@
+import { html } from 'lit';
+import './spinner.js';
+import '../button/button.js';
+
+export default {
+  title     : 'Atoms/Spinner',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdSpinner** is an indeterminate loading indicator — for work whose length is
+unknown. When you know the proportion done, use \`<bd-progress>\` instead.
+
+### Usage
+\`\`\`html
+<bd-spinner></bd-spinner>
+<bd-spinner size="sm"></bd-spinner>
+<bd-spinner size="lg" label="Checking your licence"></bd-spinner>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+| \`label\` | the accessible name | \`Loading\` |
+
+### Accessibility
+It carries \`role="status"\` with \`aria-label\` from \`label\`, so the wait is
+announced politely rather than interrupting. Give it a specific \`label\` where
+you can — "Checking your licence" is more use than the default "Loading".
+
+Under \`prefers-reduced-motion\` it stops spinning and pulses instead, so it
+still reads as active without rotating.
+
+### Note on colour
+The spinner's track and head are fixed at \`--color-neutral-200\` and
+\`--color-blue-500\`, and its sizes are fixed pixel steps. That makes it wrong
+for use on a coloured surface or inside a filled button, where the mark needs
+to follow the surrounding text colour — \`bd-button\`'s loading state draws its
+own \`currentColor\` spinner for that reason. A \`currentColor\` mode here would
+let the two converge.
+        `
+      }
+    }
+  },
+  argTypes: {
+    size: {
+      control    : { type: 'select' },
+      options    : ['small', 'default', 'large'],
+      description: 'Diameter of the spinner.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+    },
+    label: {
+      control    : 'text',
+      description: 'The accessible name, announced politely. Prefer something specific to the task.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "Loading" }, category: 'Accessibility' }
+    }
+  }
+};
+
+export const Sizes = () => html`
+    <bd-spinner size="sm"></bd-spinner>
+    <bd-spinner></bd-spinner>
+    <bd-spinner size="lg"></bd-spinner>
+  `;
+
+/**
+ * On a filled panel the default arc — `--color-action-primary` on a
+ * `--color-border-subtle` track — is nearly invisible, because both were
+ * chosen against a white page. `surface="dark"` switches them to white and a
+ * translucent white, the same attribute `bd-button` uses to say the same
+ * thing.
+ *
+ * The first spinner below is the default and shows what opting out looks like;
+ * the second and third opt in. The button draws its own `currentColor` mark
+ * rather than composing this element — it needs to be em-sized to the button's
+ * type scale and decorative rather than announced — so it is here as the thing
+ * the opted-in spinner should match.
+ */
+export const OnDarkSurface = () => html`
+    <div
+      style="display: flex; align-items: center; gap: var(--spacing-24);
+             padding: var(--spacing-24); border-radius: var(--radius-md);
+             background: var(--color-blue-600)"
+    >
+      <bd-spinner label="Default, on a panel it was not designed for"></bd-spinner>
+      <bd-spinner surface="dark" size="sm"></bd-spinner>
+      <bd-spinner surface="dark"></bd-spinner>
+      <bd-button variant="primary" surface="dark" loading>Loading</bd-button>
+    </div>
+  `;

package/src/components/spotlight-section/spotlight-section.css.js

@@ -1,15 +1,15 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
-    font-family: "Roboto", "roboto-normal-400-fallback", helvetica, ubuntu, roboto, noto, sans-serif;
-    max-width: 1290px;
-    margin: 0 auto;
+    font-family: var(--typography-fontFamily-sans);
   }
 
   .bd-spotlightsection-container {
-    background: linear-gradient(87.6deg, var(--color-blue-500) 0%, var(--color-blue-950) 100%);
+    /* no role: blue-950 is the gradient's far stop, as on bd-cta-banner. */
+    background: linear-gradient(87.6deg, var(--color-surface-brand) 0%, var(--color-blue-950) 100%);
     border-radius: var(--radius-2xl);
     padding: var(--spacing-48);
     box-sizing: border-box;
@@ -27,20 +27,19 @@ export default css`
     align-items: flex-start;
     gap: var(--spacing-16);
     flex: 1 1 320px;
-    max-width: 560px;
+    max-width: var(--content-width-readable);
   }
 
   .bd-spotlightsection-title {
     display: block;
     margin: 0;
-    color: var(--color-neutral-0, #fff);
-    line-height: var(--typography-lineHeight-tight, 1.15);
+    color: var(--color-text-inverse);
   }
 
   .bd-spotlightsection-icon {
     display: flex;
     align-items: center;
-    color: var(--color-neutral-0, #fff);
+    color: var(--color-text-inverse);
     margin-bottom: var(--spacing-4);
   }
 
@@ -55,6 +54,7 @@ export default css`
      left column is a mirror of the right one, not a different layout. */
   .bd-spotlightsection-icon ::slotted(*) {
     display: block;
+    /* no token: a logo's width cap, set by the artwork rather than a scale. */
     max-width: 160px;
     width: 100%;
     height: auto;
@@ -62,7 +62,9 @@ export default css`
 
   .bd-spotlightsection-description {
     margin: 0;
-    color: rgba(255, 255, 255, 0.65);
+    /* Full inverse ink. White at 65% measured 2.6:1 on the brand end of the
+       gradient, and bd-p's color="inverse" already painted over it. */
+    color: var(--color-text-inverse);
   }
 
   .bd-spotlightsection-buttons {
@@ -73,7 +75,7 @@ export default css`
     margin-top: var(--spacing-4);
   }
 
-  @media (max-width: 699px) {
+  @media ${unsafeCSS(below('md'))} {
     .bd-spotlightsection-container {
       padding: var(--spacing-28) var(--spacing-24);
       flex-direction: column;
@@ -99,7 +101,6 @@ export default css`
   .bd-spotlightsection-description--large {
     display: block;
     margin: 0;
-    color: var(--color-neutral-0, #fff);
-    line-height: var(--typography-lineHeight-tight, 1.15);
+    color: var(--color-text-inverse);
   }
 `;

package/src/components/spotlight-section/spotlight-section.js

@@ -3,6 +3,7 @@ import { tokens } from "../../tokens/tokens.js";
 import "../heading/heading.js";
 import "../paragraph/paragraph.js";
 import spotlightSectionCSS from "./spotlight-section.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
 
 class BdSpotlightSection extends LitElement {
@@ -15,7 +16,7 @@ class BdSpotlightSection extends LitElement {
     _hasRightButtons: { state: true }
   };
 
-  static styles = [tokens, spotlightSectionCSS];
+  static styles = [tokens, ensembleCSS, spotlightSectionCSS];
 
   constructor() {
     super();
@@ -38,50 +39,52 @@ class BdSpotlightSection extends LitElement {
     const flipped = this._hasLeftIcon;
 
     return html`
-      <div class="bd-spotlightsection-container">
-        <div class="bd-spotlightsection-left">
-          <div class="bd-spotlightsection-icon" ?hidden=${!this._hasLeftIcon}>
-            <slot name="left-icon" @slotchange=${(e) => this._onSlotChange("_hasLeftIcon", e)}></slot>
-          </div>
+      <div class="bd-ensemble">
+        <div class="bd-spotlightsection-container">
+          <div class="bd-spotlightsection-left">
+            <div class="bd-spotlightsection-icon" ?hidden=${!this._hasLeftIcon}>
+              <slot name="left-icon" @slotchange=${(e) => this._onSlotChange("_hasLeftIcon", e)}></slot>
+            </div>
 
-          ${flipped
-            ? html`
-                <bd-p kind="large" color="var(--color-neutral-0)" class="bd-spotlightsection-title bd-spotlightsection-title--small">
-                  <slot name="title">${this.title}</slot>
-                </bd-p>
-              `
-            : html`
-                <bd-h as="h2" fontWeight="400" class="bd-spotlightsection-title">
-                  <slot name="title">${this.title}</slot>
-                </bd-h>
-              `}
+            ${flipped
+              ? html`
+                  <bd-p kind="large" color="inverse" class="bd-spotlightsection-title bd-spotlightsection-title--small">
+                    <slot name="title">${this.title}</slot>
+                  </bd-p>
+                `
+              : html`
+                  <bd-h as="h2" fontWeight="normal" class="bd-spotlightsection-title">
+                    <slot name="title">${this.title}</slot>
+                  </bd-h>
+                `}
 
-          <div class="bd-spotlightsection-buttons" ?hidden=${!this._hasLeftButtons}>
-            <slot name="left-buttons" @slotchange=${(e) => this._onSlotChange("_hasLeftButtons", e)}></slot>
+            <div class="bd-spotlightsection-buttons" ?hidden=${!this._hasLeftButtons}>
+              <slot name="left-buttons" @slotchange=${(e) => this._onSlotChange("_hasLeftButtons", e)}></slot>
+            </div>
           </div>
-        </div>
 
-        <div class="bd-spotlightsection-side">
-          <div class="bd-spotlightsection-icon" ?hidden=${!this._hasRightIcon}>
-            <slot name="icon" @slotchange=${(e) => this._onSlotChange("_hasRightIcon", e)}></slot>
-          </div>
+          <div class="bd-spotlightsection-side">
+            <div class="bd-spotlightsection-icon" ?hidden=${!this._hasRightIcon}>
+              <slot name="icon" @slotchange=${(e) => this._onSlotChange("_hasRightIcon", e)}></slot>
+            </div>
 
-          ${this.description
-            ? flipped
-              ? html`
-                  <bd-h as="h2" fontWeight="400" color="var(--color-neutral-0)" class="bd-spotlightsection-description bd-spotlightsection-description--large">
-                    <slot name="description">${this.description}</slot>
-                  </bd-h>
-                `
-              : html`
-                  <bd-p kind="large" color="var(--color-neutral-0)" class="bd-spotlightsection-description">
-                    <slot name="description">${this.description}</slot>
-                  </bd-p>
-                `
-            : nothing}
+            ${this.description
+              ? flipped
+                ? html`
+                    <bd-h as="h2" fontWeight="normal" color="inverse" class="bd-spotlightsection-description bd-spotlightsection-description--large">
+                      <slot name="description">${this.description}</slot>
+                    </bd-h>
+                  `
+                : html`
+                    <bd-p kind="large" color="inverse" class="bd-spotlightsection-description">
+                      <slot name="description">${this.description}</slot>
+                    </bd-p>
+                  `
+              : nothing}
 
-          <div class="bd-spotlightsection-buttons" ?hidden=${!this._hasRightButtons}>
-            <slot name="right-buttons" @slotchange=${(e) => this._onSlotChange("_hasRightButtons", e)}></slot>
+            <div class="bd-spotlightsection-buttons" ?hidden=${!this._hasRightButtons}>
+              <slot name="right-buttons" @slotchange=${(e) => this._onSlotChange("_hasRightButtons", e)}></slot>
+            </div>
           </div>
         </div>
       </div>

package/src/components/switch/switch.css.js

@@ -0,0 +1,103 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const switchCSS = css`
+  :host { display: inline-flex; }
+
+  /* The row is the control, matching bd-checkbox and bd-radio: same gap, same
+     padding, same type, same inherited weight. This was the label-default
+     weight (medium) where those two inherit normal, so a switch label sat
+     bolder than a checkbox label on the same line of the same form.
+
+     Padding rather than a min-height, so the focus ring below insets evenly on
+     all four sides. */
+  label {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-8);
+    padding: var(--spacing-2);
+    font-family: var(--typography-fontFamily-sans);
+    /* body-small: sm / normal / 1.5, which is what this already rendered on all
+       three axes. Only the axes this rule declares are adopted -- the role also
+       carries a family and a tracking, and importing those would change text
+       the rule never spoke for. */
+    font-size: var(--typography-body-small-fontSize);
+    line-height: var(--typography-body-small-lineHeight);
+    color: var(--color-text-primary);
+    cursor: pointer;
+    outline: none;
+  }
+
+  /* the real control stays in the accessibility tree */
+  input {
+    position: absolute;
+    /* no token: 1px is the clip idiom's own measure, not a border. It was
+       spelled --border-width-1, which resolves to the same pixel and reads as
+       a category error — the lint already sanctions the literal here, as it
+       does the -1px below. */
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+  }
+
+  /* neutral-400, not neutral-300: off is a state the user has to be able to
+     perceive, so 1.4.11 wants 3:1 against the page. neutral-300 measured 2.27
+     and neutral-400 measures 3.23 — the same step bd-custom-input already uses
+     for the edge of a control. It is also the boundary the white thumb is read
+     against, which was failing for the same reason.
+     The disabled track below stays lighter; disabled is exempt under 1.4.3. */
+  .track {
+    position: relative;
+    width: var(--dimension-40);
+    height: var(--dimension-24);
+    background: var(--color-border-default);
+    border-radius: var(--radius-full);
+    transition: background-color var(--transition-duration-normal) var(--transition-easing-smooth);
+    flex: none;
+  }
+
+  .thumb {
+    position: absolute;
+    top: var(--spacing-2);
+    left: var(--spacing-2);
+    width: var(--dimension-20);
+    height: var(--dimension-20);
+    /* the knob on the track, white on both tracks: --color-action-on-fill,
+       like the checkbox mark, not the page colour it happens to equal here */
+    background: var(--color-action-on-fill);
+    border-radius: var(--radius-full);
+    box-shadow: var(--shadow-sm);
+    transition: transform var(--transition-duration-normal) var(--transition-easing-smooth);
+  }
+
+  :host([checked]) .track { background: var(--color-action-primary); }
+
+  /* The off track is --color-border-default and this is one step darker. The
+     border roles name no hover step — this is the only track in the system
+     that hovers — so the primitive stands rather than a text role being
+     borrowed for a background or a role being invented for one consumer.
+     If a second component ever needs it, that is when it earns a name. */
+  label:hover .track { background: var(--color-neutral-500); }
+  :host([checked]) label:hover .track { background: var(--color-action-primary-hover); }
+  :host([checked]) .thumb { transform: translateX(var(--spacing-16)); }
+
+  /* the one focus ring — see Foundations/Focus. On the row rather than the
+     track, so the target and the indicator are the same shape here as on
+     bd-checkbox and bd-radio. */
+  label:has(input:focus-visible) {
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
+  }
+
+  :host([disabled]) label { cursor: not-allowed; color: var(--color-text-subtle); }
+  :host([disabled]) label:hover .track,
+  :host([disabled]) .track { background: var(--color-border-subtle); }
+
+  @media (prefers-reduced-motion: reduce) {
+    .track, .thumb { transition: none; }
+  }
+`;
+
+export default switchCSS;

package/src/components/switch/switch.js

@@ -0,0 +1,44 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { switchCSS } from './switch.css.js';
+
+export class BdSwitch extends LitElement {
+  static styles = [switchCSS];
+
+  static properties = {
+    checked : { type: Boolean, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    label   : { type: String },
+    name    : { type: String }
+  };
+
+  constructor() {
+    super();
+    this.checked = false;
+    this.disabled = false;
+    this.label = '';
+  }
+
+  render() {
+    return html`
+      <label>
+        <input
+          type="checkbox"
+          role="switch"
+          name=${this.name || nothing}
+          .checked=${this.checked}
+          ?disabled=${this.disabled}
+          @change=${e => {
+            this.checked = e.target.checked;
+            this.dispatchEvent(new CustomEvent('bd-change', { detail: this.checked }));
+          }}
+        />
+        <span class="track"><span class="thumb"></span></span>
+        <span>${this.label}<slot></slot></span>
+      </label>
+    `;
+  }
+}
+
+customElements.define('bd-switch', BdSwitch);