@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/comparison-panel/comparison-panel.css.js

@@ -1,80 +1,66 @@
-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);
-    background: var(--color-blue-50);
+    background: var(--status-brand-surface);
   }
 
-  /* === DARK VARIANT === */
+  /* === DARK VARIANT ===
+     The same inverse band bd-process-steps draws, read through the same
+     inverse roles, so the two dark sections agree. */
   :host([variant="dark"]) {
+    /* no token: the #0b1626 end stop is bd-process-steps' gradient, shared
+       until the inverse band has a role of its own. */
     background: linear-gradient(160deg, var(--color-neutral-800) 0%, #0b1626 100%);
   }
 
   :host([variant="dark"]) .bd-comparisonpanel-title {
-    color: var(--color-neutral-0, #fff);
+    color: var(--color-text-inverse);
   }
 
   :host([variant="dark"]) .bd-comparisonpanel-description {
-    color: rgba(255, 255, 255, 0.55);
-  }
-
-  :host([variant="dark"]) .bd-comparisonpanel-eyebrow {
-    color: var(--color-blue-400, #60a5fa);
+    color: var(--color-text-muted-inverse);
   }
 
   :host([variant="dark"]) .bd-comparisonpanel-column {
-    background: rgba(255, 255, 255, 0.03);
-    border-color: rgba(255, 255, 255, 0.1);
+    /* no token: a 3% white lift on the inverse band; no surface role is
+       translucent. */
+    background: color-mix(in srgb, var(--color-neutral-0) 3%, transparent);
+    border-color: var(--color-border-container-inverse);
   }
 
   :host([variant="dark"]) .bd-comparisonpanel-column-title {
-    color: rgba(255, 255, 255, 0.5);
-    font-family: var(--typography-fontFamily-mono, monospace);
+    color: var(--color-text-muted-inverse);
+    font-family: var(--typography-fontFamily-mono);
     text-transform: uppercase;
-    letter-spacing: 0.08em;
-    font-weight: var(--typography-fontWeight-bold, 700);
-    font-size: var(--typography-fontSize-xs, 12px);
+    letter-spacing: var(--typography-letterSpacing-widest);
+    /* no role: the mono column label, a marker rather than a text type --
+       see header-code.css.js's code badge. */
+    font-weight: var(--typography-fontWeight-bold);
+    /* no role: the size of the same marker. */
+    font-size: var(--typography-fontSize-xs);
   }
 
   :host([variant="dark"]) .bd-comparisonpanel-text {
-    color: rgba(255, 255, 255, 0.85);
-  }
-
-  :host([variant="dark"]) .bd-comparisonpanel-icon--positive {
-    background: var(--color-green-600, #16a34a);
-  }
-
-  :host([variant="dark"]) .bd-comparisonpanel-icon--negative {
-    background: var(--color-red-500, #ef4444);
+    color: var(--color-text-inverse);
   }
 
   .bd-comparisonpanel-wrapper {
-    max-width: var(--layout-ensemble-max-width, 1200px);
-    margin: 0 auto;
-    padding: var(--spacing-48) var(--layout-ensemble-inline-padding, var(--spacing-24));
+    padding-block: var(--spacing-48);
     box-sizing: border-box;
   }
 
-  /* Small eyebrow label above the title, e.g. "Clarity" — optional, only
-     rendered when the eyebrow prop/slot is used. */
-  .bd-comparisonpanel-eyebrow {
-    margin: 0 0 var(--spacing-8);
-    color: var(--color-blue-500);
-    font-weight: var(--typography-fontWeight-bold, 700);
-  }
-
   .bd-comparisonpanel-title {
     margin: 0 0 var(--spacing-16);
-    color: var(--color-neutral-900);
-    line-height: var(--typography-lineHeight-tight, 1.1);
   }
 
   .bd-comparisonpanel-description {
     margin: 0 0 var(--spacing-48);
-    color: var(--color-neutral-600);
-    max-width: 72ch;
+    color: var(--color-text-muted);
+    max-width: var(--content-width-readable);
   }
 
   /* === COLUMNS === */
@@ -85,16 +71,15 @@ export default css`
   }
 
   .bd-comparisonpanel-column {
-    background: var(--color-neutral-0, #fff);
-    border: 1px solid var(--color-neutral-100, #e5e7eb);
-    border-radius: var(--radius-2xl);
-    padding: var(--spacing-32);
+    background: var(--color-surface-default);
+    border: var(--border-width-1) solid var(--color-border-container);
+    border-radius: var(--card-radius);
+    padding: var(--card-padding);
     box-sizing: border-box;
   }
 
   .bd-comparisonpanel-column-title {
     margin: 0 0 var(--spacing-16);
-    color: var(--color-neutral-900);
   }
 
   /* === LIST === */
@@ -125,21 +110,23 @@ export default css`
   }
 
   .bd-comparisonpanel-icon--positive {
-    background: var(--color-green-700);
+    background: var(--status-success-fill);
   }
 
   .bd-comparisonpanel-icon--negative {
-    background: var(--color-red-600);
+    background: var(--status-error-fill);
   }
 
   .bd-comparisonpanel-text {
     margin: 0;
-    color: var(--color-neutral-800);
-    line-height: var(--typography-lineHeight-normal);
+    /* Body copy. It sat on neutral-800, which is not the primitive
+       behind any text role -- primary is neutral-900, secondary
+       neutral-700 -- so it belonged to no tier. */
+    color: var(--color-text-primary);
   }
 
   /* === RESPONSIVE === */
-  @media (max-width: 767px) {
+  @media ${unsafeCSS(below('md'))} {
     .bd-comparisonpanel-columns {
       grid-template-columns: 1fr;
     }
@@ -149,7 +136,7 @@ export default css`
     }
 
     .bd-comparisonpanel-column {
-      padding: var(--spacing-24);
+      padding: var(--card-padding-compact);
     }
   }
 `;

package/src/components/comparison-panel/comparison-panel.js

@@ -3,6 +3,7 @@ import { tokens } from "../../tokens/tokens.js";
 import "../heading/heading.js";
 import "../paragraph/paragraph.js";
 import comparisonPanelCSS from "./comparison-panel.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
 class ComparisonPanel extends LitElement {
   static properties = {
@@ -18,7 +19,7 @@ class ComparisonPanel extends LitElement {
     variant      : { type: String, reflect: true }
   };
 
-  static styles = [tokens, comparisonPanelCSS];
+  static styles = [tokens, ensembleCSS, comparisonPanelCSS];
 
   constructor() {
     super();
@@ -63,7 +64,7 @@ class ComparisonPanel extends LitElement {
                         </svg>
                       `}
                 </span>
-                <bd-p kind="regular" class="bd-comparisonpanel-text">${item}</bd-p>
+                <bd-p variant="regular" class="bd-comparisonpanel-text">${item}</bd-p>
               </li>
             `
           )}
@@ -76,7 +77,7 @@ class ComparisonPanel extends LitElement {
 
   render() {
     return html`
-      <div class="bd-comparisonpanel-wrapper">
+      <div class="bd-ensemble bd-comparisonpanel-wrapper">
         ${this.title
           ? html`
               <bd-h as="h2" class="bd-comparisonpanel-title">
@@ -87,7 +88,7 @@ class ComparisonPanel extends LitElement {
 
         ${this.description
           ? html`
-              <bd-p kind="large" class="bd-comparisonpanel-description">
+              <bd-p variant="large" class="bd-comparisonpanel-description">
                 <slot name="description">${this.description}</slot>
               </bd-p>
             `

package/src/components/comparison-panel/comparison-panel.stories.js

@@ -2,7 +2,7 @@ import { html } from "lit";
 import "./comparison-panel.js";
 
 export default {
-  title     : "Components/Comparison Panel",
+  title     : "Modules/Comparison Panel",
   component : "bd-comparison-panel",
   tags      : ["autodocs"],
   parameters: {

package/src/components/compatibility-table/compatibility-table.css.js

@@ -1,4 +1,5 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
@@ -7,56 +8,62 @@ export default css`
   }
 
   :host([background="blue"]) {
-    background: var(--color-blue-50);
+    background: var(--status-brand-surface);
   }
   /* variant="light" + background="bordered": renders its own card border
      and hover lift, so callers don't need a manual wrapper <div> just to
      get the bordered-card look (e.g. side-by-side requirement cards). */
   :host([variant="light"][background="bordered"]) {
     display: block;
-    border: 1px solid var(--color-neutral-100, #e5e7eb);
-    border-radius: var(--radius-xl, 12px);
-    padding: var(--spacing-24, 24px);
+    border: var(--border-width-1) solid var(--color-border-container);
+    border-radius: var(--radius-xl);
+    padding: var(--spacing-24);
     box-sizing: border-box;
-    transition: transform 0.25s ease, box-shadow 0.25s ease, border-color 0.25s ease;
+    transition:
+      transform var(--transition-duration-normal) var(--transition-easing-ease),
+      box-shadow var(--transition-duration-normal) var(--transition-easing-ease),
+      border-color var(--transition-duration-normal) var(--transition-easing-ease);
   }
 
   :host([variant="light"][background="bordered"]:hover) {
-    transform: translateY(-3px);
-    box-shadow: 0 14px 40px #00000012;
-    border-color: var(--color-neutral-200);
+    transform: translateY(calc(-1 * var(--spacing-4)));
+    box-shadow: var(--shadow-lg);
+    border-color: var(--color-border-subtle);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :host([variant="light"][background="bordered"]) {
+      transition: none;
+    }
   }
 
   :host([variant="light"][background="bordered"]) .bd-compattable-wrapper {
-    padding: 0;
+    padding: var(--spacing-0);
   }
+
   .bd-compattable-wrapper {
-    max-width: var(--layout-ensemble-max-width, 1200px);
-    margin: 0 auto;
-    padding: var(--spacing-48) 0px var(--spacing-0);
+    padding-block: var(--spacing-48) var(--spacing-0);
     box-sizing: border-box;
   }
 
   .bd-compattable-title {
     display: block;
     margin: 0 0 var(--spacing-12);
-    color: var(--color-neutral-1000);
-    line-height: var(--typography-lineHeight-tight, 1.1);
   }
 
   .bd-compattable-description {
     display: block;
     margin: 0 0 var(--spacing-32);
-    color: var(--color-neutral-600);
-    max-width: 72ch;
+    color: var(--color-text-muted);
+    max-width: var(--content-width-readable);
   }
 
   .bd-compattable-table-container {
     display: table;
     width: 100%;
-    background: var(--color-neutral-0, #fff);
-    border: 1px solid var(--color-neutral-100, #e5e7eb);
-    border-radius: var(--radius-xl, 12px);
+    background: var(--color-surface-default);
+    border: var(--border-width-1) solid var(--color-border-container);
+    border-radius: var(--radius-xl);
     overflow: hidden;
     box-sizing: border-box;
   }
@@ -64,8 +71,8 @@ export default css`
   .bd-compattable-header {
     display: grid;
     grid-template-columns: 1.4fr 1.2fr 2.4fr;
-    background: var(--color-neutral-50);
-    border-bottom: 1px solid var(--color-neutral-200);
+    background: var(--color-surface-subtle);
+    border-bottom: var(--border-width-1) solid var(--color-border-subtle);
   }
 
   :host([variant="outcome"]) .bd-compattable-header {
@@ -78,18 +85,48 @@ export default css`
 
   .bd-compattable-header-cell {
     padding: var(--spacing-16) var(--spacing-24);
-    color: var(--color-neutral-700);
-    font-family: var(--typography-fontFamily-mono, monospace);
+    color: var(--color-text-secondary);
+    font-family: var(--typography-fontFamily-mono);
+    /* no role: the size is part of the same decision as the leading below --
+       mono, semibold and tracked at 14px is a table header, and no role in the
+       vocabulary carries that combination. */
     font-size: var(--typography-fontSize-sm);
+    /* The leading these five text sites were all missing. Measured before, every
+       one of them computed line-height: normal -- the font's own metric rather
+       than a decision, which CLAUDE.md rule 2 says is never a typography
+       contract. 34 elements across the built stories rendered that way.
+
+       --typography-lineHeight-tight, because it is what the metric already
+       resolved to: the 16px cells measured a 20px line box (1.25 exactly) and
+       the 12px header 15px (1.25 exactly). Naming it makes today's appearance a
+       choice that survives a font fallback instead of an accident that does
+       not. The 14px mono header is the one that moves -- IBM Plex Mono's normal
+       is 1.286 there, so its line box goes 18px to 17.5px inside 16px of
+       padding.
+
+       no role: nothing in the role vocabulary matches this table. The headers
+       are mono, semibold and tracked, and the cells are semibold at 16px where
+       body-regular is 400 -- adopting a role would restyle the table rather
+       than give it the leading it was missing. */
+    line-height: var(--typography-lineHeight-tight);
     text-transform: uppercase;
     letter-spacing: .06em;
-    font-weight: var(--font-weight-mono-semibold);
+    /* no role: the weight completes the combination the leading comment above
+       describes. body-regular is 400 and label-default is 500; a header cell at
+       600 belongs to no declared role. */
+    font-weight: var(--typography-fontWeight-semibold);
   }
 
   :host([variant="outcome"]) .bd-compattable-header-cell,
   :host([variant="risk"]) .bd-compattable-header-cell {
+    /* no role: same table, same decision as the header cell above. The pair of
+       axes this rule sets happens to match control-label-small, but a table cell is
+       not a control label -- adopting it would restyle the table rather than
+       give it the leading it was missing. */
     font-size: var(--typography-fontSize-xs);
-    color: var(--color-neutral-600);
+    /* no role: see the header cell above on the missing leading. */
+    line-height: var(--typography-lineHeight-tight);
+    color: var(--color-text-muted);
   }
 
   .bd-compattable-body {
@@ -100,7 +137,14 @@ export default css`
   .bd-compattable-row {
     display: grid;
     grid-template-columns: 1.4fr 1.2fr 2.4fr;
-    border-bottom: 1px solid var(--color-neutral-50, #f3f4f6);
+    /* no role: a boundary, and no border role sits at neutral-50 -- the family
+       starts at container (neutral-100) and gets darker. The decision of
+       2026-09-14 was that a boundary like this is DECORATIVE, so it is exempt
+       from the 3:1 non-text bar (it measures 1.12:1 against white) and does not
+       need to move up the family to earn one. The lighter row is deliberately
+       lighter than .bd-compattable-lightrow below, which takes
+       --color-border-container. */
+    border-bottom: var(--border-width-1) solid var(--color-neutral-50);
   }
 
   :host([variant="outcome"]) .bd-compattable-row {
@@ -119,17 +163,29 @@ export default css`
     padding: var(--spacing-20) var(--spacing-24);
     display: flex;
     align-items: center;
-    color: var(--color-neutral-800);
+    /* Cell data, one step back from the row label beside it, which
+       is text-primary. Secondary keeps that hierarchy; primary
+       would have flattened the two together. */
+    color: var(--color-text-secondary);
+    /* no role: same table, same decision as the header cell above. The pair of
+       axes this rule sets happens to match control-label-large, but a table cell is
+       not a control label -- adopting it would restyle the table rather than
+       give it the leading it was missing. */
     font-size: var(--typography-fontSize-base);
+    /* no role: see the header cell above on the missing leading. */
+    line-height: var(--typography-lineHeight-tight);
   }
 
   .bd-compattable-cell--environment {
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
+    /* no role: the weight axis of the same table, and the same decision --
+       see the header cell above. */
     font-weight: var(--typography-fontWeight-semibold);
   }
 
   .bd-compattable-cell--notes {
-    color: var(--color-neutral-800);
+    /* Supporting notes. */
+    color: var(--color-text-secondary);
     gap: var(--spacing-8);
   }
 
@@ -138,62 +194,115 @@ export default css`
   }
 
   .bd-compattable-cell--event {
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
+    /* no role: the weight axis of the same table, and the same decision --
+       see the header cell above. */
     font-weight: var(--typography-fontWeight-semibold);
   }
 
+  /* These two cells say whether a product has a feature, which is the success
+     and error responsibility rather than "a green" and "a red". The status
+     roles were already the right answer and also the legible one: green-600
+     measures 3.20:1 on white and --status-success-text 6.77, red-600 5.44 and
+     --status-error-text 7.56. The green was a genuine failure; the red was only
+     the wrong family. */
   .bd-compattable-cell--without {
-    color: var(--color-red-600, #dc2626);
+    color: var(--status-error-text);
   }
 
   .bd-compattable-cell--with {
-    color: var(--color-green-600, #16a34a);
+    color: var(--status-success-text);
   }
 
   .bd-compattable-cell--category {
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
+    /* no role: the weight axis of the same table, and the same decision --
+       see the header cell above. */
     font-weight: var(--typography-fontWeight-semibold);
   }
 
   .bd-compattable-cell--riskcoverage {
-    color: var(--color-neutral-900);
-  }
-.bd-compattable-lightgrid {
-  display: grid;
-  grid-template-columns: repeat(var(--bd-compattable-light-columns, 2), 1fr);
-  column-gap: var(--spacing-48);
-  row-gap: 0;
-}
-.bd-compattable-lightrow:last-of-type {
-  border-bottom: none;
-}
+    /* no role: the risk-coverage cell's ink. This is the one genuine non-interactive
+       brand-ink site in the package -- everything else at blue-700 is a :hover, an
+       active state, a glyph on a tinted disc, or dead. ONE SITE DOES NOT NAME A ROLE:
+       phase-1-eyebrow-investigation settled that precedent when "eyebrow" turned out to
+       be one question asked four times and took a marker rather than a role, and the
+       plan's single-consumer-semantic-token item exists because Phase 3's job is to
+       FIND AND DELETE exactly the shape a --color-text-brand-strong invented here would
+       create.
+       .
+       The size-dependent-ink hypothesis was tested package-wide and rejected; see
+       plans/reports/phase-2-size-dependent-ink-check.md. Note separately that this cell
+       is role="cell" with no href and renders as blue running prose, so it reads as a
+       link without being one -- a UX question, not a token one. */
+    color: var(--color-blue-700);
+  }
+
+  /* === LIGHT VARIANT === */
+  .bd-compattable-lightgrid {
+    display: grid;
+    grid-template-columns: repeat(var(--bd-compattable-light-columns, 2), 1fr);
+    column-gap: var(--spacing-48);
+    row-gap: 0;
+  }
+
+  .bd-compattable-lightrow:last-of-type {
+    border-bottom: none;
+  }
+
   .bd-compattable-lightrow {
     display: flex;
     align-items: baseline;
     justify-content: space-between;
     gap: var(--spacing-16);
     padding: var(--spacing-16) 0;
-    border-bottom: 1px solid var(--color-neutral-100, #e5e7eb);
+    /* A boundary, not a divider: the line belongs to the row it closes, so it
+       is a border and takes a border role. --color-border-container is
+       neutral-100 exactly, so nothing moves. Decided 2026-09-14 -- see
+       plans/reports/phase-2-vocab-e-has-role-pass.md question E3. */
+    border-bottom: var(--border-width-1) solid var(--color-border-container);
   }
 
   .bd-compattable-lightlabel {
-    color: var(--color-neutral-500);
+    color: var(--color-text-subtle);
+    /* no role: same table, same decision as the header cell above. The pair of
+       axes this rule sets happens to match control-label-large, but a table cell is
+       not a control label -- adopting it would restyle the table rather than
+       give it the leading it was missing. */
     font-size: var(--typography-fontSize-base);
+    /* no role: see the header cell above on the missing leading. */
+    line-height: var(--typography-lineHeight-tight);
     flex-shrink: 0;
   }
 
+  /* On the blue band the label leaves subtle for muted: subtle sits on the
+     page or a card, and on --status-brand-surface it measured 4.46:1. Muted
+     reads 6.10 there. Dark mode decision 17. */
+  :host([background="blue"]) .bd-compattable-lightlabel {
+    color: var(--color-text-muted);
+  }
+
   .bd-compattable-lightvalue {
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
+    /* no role: the weight axis of the same table, and the same decision --
+       see the header cell above. */
     font-weight: var(--typography-fontWeight-semibold);
     text-align: right;
   }
 
-  @media (max-width: 767px) {
+  /* === RESPONSIVE === */
+  @media ${unsafeCSS(below('md'))} {
     .bd-compattable-header {
       display: none;
     }
 
-    .bd-compattable-row {
+    /* The two variant rules above are more specific than a bare class, and a
+       media query adds no specificity, so naming only .bd-compattable-row here
+       left the outcome and risk variants on their desktop column template at
+       phone widths. Outcome stayed three columns and ran 113px off the page. */
+    .bd-compattable-row,
+    :host([variant="outcome"]) .bd-compattable-row,
+    :host([variant="risk"]) .bd-compattable-row {
       grid-template-columns: 1fr;
       padding: var(--spacing-16) var(--spacing-20);
       gap: var(--spacing-4);
@@ -203,38 +312,29 @@ export default css`
       padding: var(--spacing-4) 0;
     }
 
-    .bd-compattable-cell--coverage::before {
-      content: "Coverage: ";
-      color: var(--color-neutral-500);
-      font-size: var(--typography-fontSize-xs);
-      text-transform: uppercase;
-    }
-
-    .bd-compattable-cell--notes::before {
-      content: "Notes: ";
-      color: var(--color-neutral-500);
-      font-size: var(--typography-fontSize-xs);
-      text-transform: uppercase;
-    }
-
-    .bd-compattable-cell--without::before {
-      content: "Without AI Guardian: ";
-      color: var(--color-neutral-500);
-      font-size: var(--typography-fontSize-xs);
-      text-transform: uppercase;
-    }
-
-    .bd-compattable-cell--with::before {
-      content: "With AI Guardian: ";
-      color: var(--color-neutral-500);
-      font-size: var(--typography-fontSize-xs);
-      text-transform: uppercase;
-    }
-
+    /* One rule, and the name comes from --bd-cell-label, which
+       compatibility-table.js sets per cell out of the columns prop. Five rules
+       stood here with the column names written into content as English
+       strings -- "Without AI Guardian: " and the rest -- so below md, where
+       the header is display: none, the only column labelling on screen was
+       text the consumer could neither change nor translate. Measured at 375
+       with Romanian columns: header "Fara AI Guardian", cell label
+       "Without AI Guardian". The empty fallback means a cell with no column
+       name shows nothing rather than the literal text of a broken var(). */
+    .bd-compattable-cell--coverage::before,
+    .bd-compattable-cell--notes::before,
+    .bd-compattable-cell--without::before,
+    .bd-compattable-cell--with::before,
     .bd-compattable-cell--riskcoverage::before {
-      content: "AI Guardian coverage: ";
-      color: var(--color-neutral-500);
+      content: var(--bd-cell-label, "");
+      color: var(--color-text-subtle);
+    /* no role: same table, same decision as the header cell above. The pair of
+       axes this rule sets happens to match control-label-small, but a table cell is
+       not a control label -- adopting it would restyle the table rather than
+       give it the leading it was missing. */
       font-size: var(--typography-fontSize-xs);
+      /* no role: see the header cell above on the missing leading. */
+      line-height: var(--typography-lineHeight-tight);
       text-transform: uppercase;
     }