@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/progress/progress.css.js

@@ -0,0 +1,80 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const progressCSS = css`
+  :host { display: block; }
+
+  .track {
+    height: var(--spacing-8);
+    background: var(--color-surface-muted);
+    border-radius: var(--radius-full);
+    overflow: hidden;
+  }
+
+  .fill {
+    height: 100%;
+    background: var(--status-info-accent);
+    border-radius: var(--radius-full);
+    transition: width var(--transition-duration-slow) var(--transition-easing-smooth);
+  }
+
+  /* The tones come from the shared status roles, so a progress bar and a
+     bd-alert rule or a bd-badge dot of the same tone are the same colour by
+     construction. They were not: this atom spelled all three out in palette
+     steps that happened to match, so retinting --status-success-accent moved
+     alert, badge and tag and left the bar green.
+
+     Measured against the track the fill sits in, not the page: the bar is a
+     graphic whose colour carries the meaning, so 1.4.11 wants 3:1 there.
+     On the track the default blue is 3.52 and error red-600 is 4.23, but
+     success at green-600 was only 2.49. green-700 — which is the step
+     --status-success-accent names — is 3.69. */
+  /* info has its own rule even though .fill above already resolves to the same
+     token, and the duplication is the point. It used to work by OMISSION --
+     there was no info rule, so tone="info" fell through to the default fill,
+     which happened to be --status-info-accent. Nothing rendered wrong, and
+     nothing ever would have caught it: Figma and the Code Connect template
+     both offer info as a tone, the manifest offered "default" instead, and the
+     stories only ever exercised success and error, so the info path had never
+     been rendered anywhere.
+     .
+     Two things stay separate now. The bare .fill is what a bd-progress with NO
+     tone attribute looks like; this rule is what tone="info" MEANS. They agree
+     today. If somebody later changes the untoned default, info keeps its
+     meaning instead of silently following it. */
+  :host([tone='info']) .fill    { background: var(--status-info-accent); }
+  :host([tone='success']) .fill { background: var(--status-success-accent); }
+  :host([tone='error']) .fill   { background: var(--status-error-accent); }
+
+  /* The caption role, all five axes from the role rather than one from it and
+     the rest from nowhere. This box holds the label and the percentage, so it
+     owns their typography -- and it declared a family, a size and a colour and
+     never declared a line-height, leaving IBM Plex Sans's own "normal" metric
+     to decide. Measured before: 12px text in a 15px box, a leading nobody
+     chose, and one that stops being 1.25 the moment the font falls back.
+
+     The colour is the same value it already used: --typography-caption-default-color
+     resolves to --color-text-muted. It is named through the role here so that
+     retinting captions moves this label with them.
+
+     Neither gate could see it. lint:tokens has nothing to scan when a leading
+     is absent rather than wrong, and verify:typography fails on multi-line
+     text a component renders with no role -- these two spans are single-line. */
+  .label {
+    display: flex;
+    justify-content: space-between;
+    margin-bottom: var(--spacing-4);
+    font-family: var(--typography-caption-default-fontFamily);
+    font-size: var(--typography-caption-default-fontSize);
+    font-weight: var(--typography-caption-default-fontWeight);
+    line-height: var(--typography-caption-default-lineHeight);
+    letter-spacing: var(--typography-caption-default-letterSpacing);
+    color: var(--typography-caption-default-color);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .fill { transition: none; }
+  }
+`;
+
+export default progressCSS;

package/src/components/progress/progress.js

@@ -0,0 +1,42 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { progressCSS } from './progress.css.js';
+
+export class BdProgress extends LitElement {
+  static styles = [progressCSS];
+
+  static properties = {
+    value: { type: Number },
+    max  : { type: Number },
+    label: { type: String },
+    tone : { type: String, reflect: true }
+  };
+
+  constructor() {
+    super();
+    this.value = 0;
+    this.max = 100;
+    this.label = '';
+  }
+
+  render() {
+    return html`
+      ${this.label
+        ? html`<span class="label"><span>${this.label}</span><span>${Math.round((this.value / this.max) * 100)}%</span></span>`
+        : nothing}
+      <div
+        class="track"
+        role="progressbar"
+        aria-valuenow=${this.value}
+        aria-valuemin="0"
+        aria-valuemax=${this.max}
+        aria-label=${this.label || 'Progress'}
+      >
+        <div class="fill" style="width: ${Math.min(100, (this.value / this.max) * 100)}%"></div>
+      </div>
+    `;
+  }
+}
+
+customElements.define('bd-progress', BdProgress);

package/src/components/progress/progress.stories.js

@@ -0,0 +1,79 @@
+import { html } from 'lit';
+import './progress.js';
+
+export default {
+  title     : 'Atoms/Progress',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdProgress** is a determinate progress bar — it shows how far through a known
+quantity something is. For work of unknown length use \`<bd-spinner>\`.
+
+### Usage
+\`\`\`html
+<bd-progress value="40"></bd-progress>
+<bd-progress value="7" max="10" label="Devices protected"></bd-progress>
+<bd-progress value="95" max="100" label="Storage used" tone="error"></bd-progress>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`value\` | number, current progress | \`0\` |
+| \`max\` | number, the total | \`100\` |
+| \`label\` | caption shown above the bar, with a percentage | \`''\` |
+| \`tone\` | \`default\`, \`success\`, \`error\` | \`default\` |
+
+### Notes
+When \`label\` is set, a row above the bar shows the label on the left and the
+rounded percentage on the right, so the number is visible and not only
+announced.
+
+The fill is clamped at 100%, so a \`value\` above \`max\` cannot overflow the
+track.
+
+### Accessibility
+The track carries \`role="progressbar"\` with \`aria-valuenow\`, \`aria-valuemin\`
+and \`aria-valuemax\`, so assistive tech reports real progress rather than just
+"busy". Its accessible name comes from \`label\`, falling back to the literal
+"Progress" — pass a \`label\` so it says what is progressing.
+        `
+      }
+    }
+  },
+  argTypes: {
+    value: {
+      control    : 'number',
+      description: 'Current progress. Clamped to max when rendering the fill.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: "0" }, category: 'Data' }
+    },
+    max: {
+      control    : 'number',
+      description: 'The total that value is measured against.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: "100" }, category: 'Data' }
+    },
+    label: {
+      control    : 'text',
+      description: 'Caption above the bar, shown with the percentage. Also the accessible name.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    },
+    tone: {
+      control    : { type: 'select' },
+      options    : ['default', 'success', 'error'],
+      description: 'Colour of the fill.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+    }
+  }
+};
+
+export const Default = () => html`
+    <bd-progress value="64" label="Scan progress"></bd-progress>
+  `;
+
+export const Tones = () => html`
+    <bd-progress value="60" tone="info" label="In progress"></bd-progress>
+    <bd-progress value="100" tone="success" label="Complete"></bd-progress>
+    <bd-progress value="30" tone="error" label="Failed"></bd-progress>
+  `;

package/src/components/quick-answer/quick-answer.css.js

@@ -1,33 +1,63 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
     font-family: var(--typography-fontFamily-sans);
-        line-height: 1.55;
-    
   }
 
   .bd-quickanswer-container {
-    background: var(--color-blue-50, #eef4ff);
-    // border-radius: var(--radius-2xl, 16px);
+    background: var(--status-brand-surface);
     padding: var(--spacing-32) var(--spacing-28) var(--spacing-32) var(--spacing-28);
     box-sizing: border-box;
   }
 
+  /* text-brand, not blue-500: this label is 16px on --status-brand-surface,
+     where blue-500 measures 4.20:1 and fails 1.4.3. blue-600 gives 5.72:1.
+
+     The weight is set through bd-p's font-weight attribute, not here. This rule
+     used to declare --typography-fontWeight-medium and it never reached the
+     text: the label renders inside bd-p's shadow paragraph, which sets its own
+     weight, and a slotted node inherits from its flattened-tree parent -- that
+     paragraph -- rather than from this host. Measured, the label came out at
+     400 while this rule asked for 500. */
   .bd-quickanswer-label {
-    color: var(--color-blue-500);
-    font-weight: var(--typography-fontWeight-medium);
+    color: var(--color-text-brand);
     margin: 0 0 var(--spacing-16);
   }
 
   .bd-quickanswer-text {
-    color: var(--color-neutral-800);
+    /* Body copy, same as above: off the text ladder rather than a
+       step on it. */
+    color: var(--color-text-primary);
     margin: 0;
   }
 
+  /* The atom, not a border of our own.
+
+     This was a bare div with a border-top, and CLAUDE.md is explicit that a
+     line separating regions of content is a divider rather than a boundary.
+     The reason it was hand-drawn is that bd-divider-horizontal could not say
+     what this line needs: its colour prop resolved through COLOR_ROLES, the
+     *ink* vocabulary, and no text role expresses --status-brand-border. A
+     neutral hairline reads as dirt on a brand tint, so the component drew its
+     own rather than accept the wrong colour -- the atom lost a consumer to a
+     category error in its own API.
+
+     token-scales.js now carries BORDER_ROLES and the atom resolves through it
+     first, so brand-subtle is sayable and this is an instance again. The
+     colour is unchanged: brand-subtle IS --status-brand-border, which is the
+     step the hand-drawn rule already named after an earlier fix moved it off
+     --color-blue-100.
+
+     opacity is set to 1 explicitly because the atom dims to 0.25 by default,
+     which
+     would have taken this line to a quarter of the value the rule asked for.
+
+     The margins stay here: they are this panel's rhythm, not the rule's. */
   .bd-quickanswer-divider {
-    border-top: 1px solid var(--color-blue-100, rgba(59, 130, 246, 0.15));
+    display: block;
     margin: var(--spacing-24) 0 var(--spacing-16);
   }
 
@@ -44,19 +74,51 @@ export default css`
   }
 
 .bd-quickanswer-meta-label {
-  color: var(--color-neutral-500);
+  /* subtle is only safe on the page ground: on this tint it lands at 4.33:1 and
+     these labels are 11px. muted is the next step in the same family. */
+  color: var(--color-text-muted);
+  /* no role: this is not the "eyebrow" the package keeps almost naming a role
+     for. Measured against the other three sites that share that visual job --
+     a small label above a heading -- it shares no axis with any of them:
+     .
+       bento-grid  .bd-bentogrid-eyebrow   16px / 1.5 / 400 / sans / 0 / none
+       header-code .bd-headercode-eyebrow  16px / 1.5 / 400 / sans / 0 / none
+       highlight   .sub-title              14px / 1.5 / 400 / sans / 0 / none
+       here                                11px / -   / 400 / MONO / .04em / UPPERCASE
+     .
+     The first three are the same treatment at two size steps, and all three
+     already resolve through a role: each is a <bd-p variant="regular"|"small">
+     and declares nothing but colour and margin, so body-regular and body-small
+     answer them and none of them ever had a typography finding. "Eyebrow" turns
+     out to be a design pattern -- text above a heading, brand-coloured -- and
+     not a typography combination, so there is nothing for a role to name that
+     body-regular and body-small do not already say.
+     .
+     This label is a different treatment: mono, uppercase and tracked at 11px,
+     which is a meta strip's key, not a kicker above a title. label-extra-small
+     is the only declared role at xxs and it is sans with normal tracking, so it
+     describes different text. The size stays a primitive and says why. */
   font-size: var(--typography-fontSize-xxs);
   text-transform: uppercase;
   letter-spacing: 0.04em;
-  font-family: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
+  font-family: var(--typography-fontFamily-mono);
 }
 
   .bd-quickanswer-meta-value {
-    color: var(--color-neutral-1000);
+    color: var(--color-text-primary);
+    /* no role: and this is a separate question from the label above, not the
+       other half of one. Measured 16px / 400-weight-overridden-to-600 / sans,
+       with no transform and no tracking -- it shares nothing with the label but
+       the strip it sits in. The two are a pair by function, a key and its
+       value, and by treatment they are deliberately unlike: a mono uppercase
+       key at 11px against a sans value at 16px. The weight is what marks the
+       value as the answer rather than the question, which is emphasis within
+       the component's own micro-vocabulary and not a text-content type -- see
+       button.css.js's .button--bold for that argument. */
     font-weight: var(--typography-fontWeight-semibold);
   }
 
-  @media (max-width: 599px) {
+  @media ${unsafeCSS(below('sm'))} {
     .bd-quickanswer-container {
       padding: var(--spacing-24);
     }

package/src/components/quick-answer/quick-answer.js

@@ -2,6 +2,7 @@ import { LitElement, html, nothing } from "lit";
 import { tokens } from "../../tokens/tokens.js";
 import "../paragraph/paragraph.js";
 import quickAnswerCSS from "./quick-answer.css.js";
+import "../divider/divider-horizontal.js";
 
 class QuickAnswer extends LitElement {
   static properties = {
@@ -24,13 +25,13 @@ class QuickAnswer extends LitElement {
       <div class="bd-quickanswer-container">
         ${this.label
           ? html`
-              <bd-p kind="normal" class="bd-quickanswer-label">
+              <bd-p variant="regular" font-weight="medium" class="bd-quickanswer-label">
                 <slot name="label">${this.label}</slot>
               </bd-p>
             `
           : nothing}
 
-        <bd-p kind="large" class="bd-quickanswer-text">
+        <bd-p variant="large" class="bd-quickanswer-text">
           <slot name="text">${this.text}</slot>
         </bd-p>
 
@@ -38,7 +39,11 @@ class QuickAnswer extends LitElement {
 
         ${this.items && this.items.length
           ? html`
-              <div class="bd-quickanswer-divider"></div>
+              <bd-divider-horizontal
+                class="bd-quickanswer-divider"
+                color="brand-subtle"
+                opacity="1"
+              ></bd-divider-horizontal>
               <div class="bd-quickanswer-meta">
                 ${this.items.map(
                   (item) => html`

package/src/components/radio/radio.css.js

@@ -1,5 +1,17 @@
 import { css } from "lit";
 
+/**
+ * Shared by bd-radio and bd-toggle-radio.
+ *
+ * Styled entirely from src/tokens/tokens.js — see CLAUDE.md, "The foundation
+ * rule". Measurements were matched to the ds-radio design by finding the token
+ * that already carries each value.
+ *
+ * The whole row is the control, not just the circle. That makes clicking the
+ * label work and gives the target the 24px minimum WCAG 2.5.8 asks for, which
+ * a 20px circle alone cannot reach. Padding rather than a min-height, so the
+ * focus ring is inset evenly on all four sides.
+ */
 export default css`
   :host {
     display: inline-block;
@@ -8,161 +20,113 @@ export default css`
   .bd-radio {
     display: inline-flex;
     align-items: center;
-    cursor: pointer;
     gap: var(--spacing-8);
-    font-family: sans-serif;
-    font-size: 14px;
+    padding: var(--spacing-2);
+    cursor: pointer;
+    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);
     vertical-align: middle;
+    outline: none;
   }
 
-  .bd-radio.disabled {
-    cursor: not-allowed;
-    opacity: 0.6;
-  }
-
-  .radio-label {
-    font-size: 14px;
-    color: black;
+  .bd-radio:focus-visible {
+    /* 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;
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
   }
 
-  .bd-outer,
-  .custom-radio {
-    width: var(--spacing-22);
-    height: var(--spacing-22);
-    border:var(--spacing-2) solid var(--color-blue-500);
-    border-radius: 50%;
-    display: flex;
+  /* ---- the circle -------------------------------------------------------
+     flex: none matters. Without it the circle shrank in the flex row — it
+     rendered 16x22, and a 50% radius on a non-square box is an ellipse. */
+  .box {
+    flex: none;
+    width: var(--dimension-20);
+    height: var(--dimension-20);
+    box-sizing: border-box;
+    /* The action role when unchecked, matching bd-checkbox. ds-radio specifies
+       a neutral ring and ds-checkbox a brand one for the same conceptual
+       state; the two frames disagree, and one system should not.
+
+       Spelled as the role rather than the blue-500 step it resolves to: this
+       and bd-checkbox were the two atoms a --color-action-primary override
+       did not reach, where bd-button and bd-switch already did. */
+    border: var(--border-width-2) solid var(--color-action-primary);
+    border-radius: var(--radius-full);
+    background: var(--color-surface-default);
+    display: inline-flex;
     align-items: center;
     justify-content: center;
-    box-sizing: border-box;
-    transition: border-color 0.2s ease;
+    transition: background-color var(--transition-duration-normal) var(--transition-easing-smooth),
+      border-color var(--transition-duration-normal) var(--transition-easing-smooth);
   }
 
-  .bd-inner {
-    width: var(--spacing-12);
-    height: var(--spacing-12);
-    background-color: var(--color-blue-500);
-    border-radius: 50%;
-    transform: scale(0);
-    transition: transform 0.2s ease, background-color 0.2s ease;
-  }
-
-  .bd-inner.visible {
-    transform: scale(1);
-  }
-
-  .bd-outer:hover {
-    border-color: var(--color-blue-700);
+  /* ---- checked: the circle fills and the dot is the hole in it ---------- */
+  :host([checked]) .box {
+    background: var(--color-action-primary);
+    border-color: var(--color-action-primary);
   }
 
-  .bd-inner:hover {
-    background-color: var(--color-blue-700);
+  .bd-radio:hover .box {
+    border-color: var(--color-action-primary-hover);
   }
 
-  .bd-radio.disabled .bd-outer.checked {
-    border-color: #b0b0b0; 
+  :host([checked]) .bd-radio:hover .box {
+    background: var(--color-action-primary-hover);
+    border-color: var(--color-action-primary-hover);
   }
 
-   .bd-outer.checked:hover {
-    border-color: var(--color-blue-700);
+  .dot {
+    width: var(--dimension-12);
+    height: var(--dimension-12);
+    border-radius: var(--radius-full);
+    /* ink on an action fill, like the checkbox mark */
+    background: var(--color-action-on-fill);
+    transform: scale(0);
+    transition: transform var(--transition-duration-normal) var(--transition-easing-smooth);
   }
 
- 
-  .bd-radio.disabled .bd-outer {
-    border-color: #b0b0b0;
+  :host([checked]) .dot {
+    transform: scale(1);
   }
 
-  .bd-radio.disabled .bd-inner {
-    background-color: #b0b0b0;
-  }
+  /* ---- disabled --------------------------------------------------------
+     The label greys with the control rather than the whole row dropping to an
+     opacity. Exempt from contrast under WCAG 1.4.3.
 
-  .bd-radio[disabled] {
-    opacity: 0.5;
+     The edge is --color-border-disabled, the state role, for the reasons
+     written out over bd-checkbox's disabled block: one disabled-edge value
+     across the control family, and 2.27:1 where the hierarchy role gave 1.66.
+     The dot fill below is a fill rather than an edge and is unchanged. */
+  :host([disabled]) .bd-radio {
     cursor: not-allowed;
+    color: var(--color-text-subtle);
   }
 
-  
-  .bd-radio.focus .bd-outer,
-  .bd-outer.focus {
-    outline: var(--spacing-2) solid var(--color-blue-500);
-    outline-offset: var(--spacing-2);
+  :host([disabled]) .box,
+  :host([disabled]) .bd-radio:hover .box {
+    border-color: var(--color-border-disabled);
+    background: var(--color-surface-default);
   }
 
-  .hidden-input {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    margin: -1px;
-    padding: 0;
-    border: 0;
-    clip: rect(0 0 0 0);
-    overflow: hidden;
-    white-space: nowrap;
+  :host([disabled][checked]) .box,
+  :host([disabled][checked]) .bd-radio:hover .box {
+    background: var(--color-border-subtle);
+    border-color: var(--color-border-disabled);
   }
 
-
-  .custom-radio::after {
-    content: "";
-    position: absolute;
-    top: 50%;
-    left: 50%;
-    width: var(--spacing-12);
-    height: var(--spacing-12);
-    background-color: #006dff;
-    border-radius: 50%;
-    transform: translate(-50%, -50%) scale(0);
-    transition: transform 0.2s;
+  @media (prefers-reduced-motion: reduce) {
+    .box,
+    .dot {
+      transition: none;
+    }
   }
-
-  input:checked + .custom-radio::after {
-    transform: translate(-50%, -50%) scale(1);
-  }
-
-  .bd-radio:not(.disabled):hover .custom-radio {
-    border-color: #004bbd;
-  }
-  .bd-radio.disabled .bd-inner.visible {
-    background-color: #b0b0b0;
-    transform: scale(1); 
-  }
-  .bd-radio:not(.disabled):focus-within .custom-radio {
-    box-shadow: 0 0 0 3px rgba(0, 109, 255, 0.5);
-  }
-  .bd-outer:focus {
-    outline: none;
-  }
-
-  .bd-outer:focus-visible {
-    outline: var(--spacing-2) solid var(--color-blue-500);
-    outline-offset: var(--spacing-2);
-  }
-  .bd-outer:focus:not(:focus-visible) {
-    outline: none;
-  }
-  .bd-outer.focus {
-    outline: var(--spacing-2) solid var(--color-blue-500);
-    outline-offset: var(--spacing-2);
-  }
-  .bd-outer:active {
-    outline: var(--spacing-2) solid var(--color-blue-500);
-    outline-offset: var(--spacing-2);
-  }
-  .bd-outer:focus-visible.checked {
-    outline: var(--spacing-2) solid var(--color-blue-500);
-    outline-offset: var(--spacing-2);
-  }
-
-  .bd-outer:focus-visible.checked .bd-inner {
-    background-color: var(--color-blue-500);
-  }
-  .bd-outer:focus-visible .bd-inner.visible {
-    background-color: var(--color-blue-700);
-  }
-    .bd-outer:focus-visible {
-  border-color: var(--color-blue-700);
-}
-
-.bd-outer:focus-visible .bd-inner.visible {
-  background-color: var(--color-blue-700);
-}
 `;