@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/compare/compare.css.js

@@ -1,18 +1,44 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
 
 :host(bd-compare-section) {
   display: block;
 
-  --cs-bar-primary-fg:   var(--color-neutral-0);
-  --cs-bar-primary-bg:   var(--color-blue-500);
+  /* The brand fill and the ink that belongs to it. theme-green and theme-red
+     adopted --status-*-fill / --status-*-on-fill below with the argument that a
+     saturated fill carrying a label is exactly that pair's responsibility; the
+     default bar IS that shape and the migration skipped it, so it kept the
+     primitives. Value-identical -- --status-brand-fill is blue-500 and
+     --status-brand-on-fill is neutral-0 -- and the label measures 4.53:1 here,
+     which passes 4.5:1 with almost nothing spare. Worth knowing before anyone
+     retunes blue-500: green-500 and red-500 both failed this same test. */
+  --cs-bar-primary-fg:   var(--status-brand-on-fill);
+  --cs-bar-primary-bg:   var(--status-brand-fill);
+  /* no role: the competitor bar is a resting fill. The three roles at
+     neutral-100 are a state (surface-muted), a disabled control
+     (surface-disabled) and a surface in the neutral status family, whose FILL
+     is neutral-900 -- so the family that matches on job does not match on
+     value, and the ones that match on value do not match on job. */
   --cs-bar-secondary-bg: var(--color-neutral-100);
   --cs-bar-track-bg:     transparent;
-  --cs-bar-track-border: var(--color-neutral-200);
-  --cs-bar-height:       var(--dimension-48px);
+  --cs-bar-track-border: var(--color-border-subtle);
+  --cs-bar-height:       var(--dimension-48);
   --cs-gap:              var(--spacing-32);
-  --cs-grid-max:         1228px;
+
+  /* The section's own text, which is the only text that sits on the page's
+     ground rather than on a card. .theme-dark recoloured the bars and the icon
+     and stopped there, so on a dark ground the section title kept
+     --color-text-primary and rendered at 1.05:1 -- a documented story whose
+     heading was invisible.
+
+     Deliberately section-scoped. .card sets its own --color-surface-container
+     and stays light under .theme-dark, so card titles, descriptions, footnotes
+     and bar labels must keep their light-surface roles; inverting those turned
+     white text onto a light card at 1.04:1 when it was tried. This is a
+     component-context fix, not a theme architecture. */
+  --cs-section-text: var(--color-text-primary);
 }
 
 :host(compare-card) {
@@ -39,30 +65,30 @@ export default css`
 
 .cs-section {
   background: transparent;
-  padding:    var(--spacing-0) var(--spacing-24);
+  padding-block: var(--spacing-0);
   box-sizing: border-box;
 }
 
 .cs-heading {
   text-align: center;
+  /* not the column: a centred heading measure, one grid step narrower than the page */
   max-width:  var(--grid-container-max-md);
   margin:     0 auto var(--spacing-40);
 }
 
-.cs-title    { margin: 0 0 var(--spacing-8); }
-.cs-subtitle { margin: 0; }
+.cs-title    { margin: 0 0 var(--spacing-8); color: var(--cs-section-text); }
+.cs-subtitle { margin: 0; color: var(--cs-section-text); }
 
 .cs-grid {
   display:               grid;
   grid-template-columns: repeat(var(--_cols, 2), minmax(0, 598px));
   gap:                   var(--cs-gap);
-  max-width:             var(--cs-grid-max);
   margin:                0 auto;
   justify-content:       center;
   align-items:           stretch;
 }
 
-@media (max-width: 768px) {
+@media ${unsafeCSS(below('md'))} {
   .cs-grid {
     grid-template-columns: 1fr !important;
   }
@@ -73,9 +99,16 @@ export default css`
 }
 
 .card {
-  background:      var(--color-neutral-25);
-  border-radius:   var(--radius-3xl);
-  padding:         var(--spacing-32);
+  background:      var(--color-surface-container);
+  /* --radius-2xl, the established card-family corner. This card sat at
+     --radius-3xl and was otherwise identical to the family: the same
+     --color-surface-container, the same 32px inset, no resting elevation and
+     no card-level interaction. P5G could find no responsibility, affordance or
+     recorded decision behind the extra 8px -- unlike the carousel item, whose
+     24px corner goes with a 2px border and real drag/modal behaviour and is a
+     recorded open question. */
+  border-radius:   var(--card-radius);
+  padding:         var(--card-padding);
   display:         flex;
   flex-direction:  column;
   gap:             var(--spacing-24);
@@ -94,8 +127,8 @@ export default css`
 
 .card-icon-wrap {
   flex-shrink: 0;
-  width:       var(--icon-2xl-size, 48px);
-  height:      var(--icon-2xl-size, 48px);
+  width:       var(--icon-2xl-size);
+  height:      var(--icon-2xl-size);
 }
 
 .card-icon-wrap bd-img {
@@ -124,7 +157,7 @@ export default css`
 
 .card-footnote {
   margin: 0;
-  color:  var(--color-neutral-900);
+  color:  var(--color-text-primary);
   flex:   0 0 auto;
 }
 
@@ -158,8 +191,8 @@ slot[name="header"] { display: contents; }
 }
 
 .card--horizontal .card-icon-wrap {
-  width:  var(--dimension-40px);
-  height: var(--dimension-40px);
+  width:  var(--dimension-40);
+  height: var(--dimension-40);
 }
 
 .card--horizontal .card-description { margin: 0; }
@@ -173,7 +206,7 @@ slot[name="header"] { display: contents; }
   justify-content: center;
 }
 
-@media (max-width: 768px) {
+@media ${unsafeCSS(below('md'))} {
   .card--horizontal {
     grid-template-columns: 1fr;
   }
@@ -181,13 +214,27 @@ slot[name="header"] { display: contents; }
   .card--horizontal .card-footnote { margin-top: 0; }
 }
 
+/* Every --cs-bar-* read here carries a fallback, because all of them are
+   declared on :host(bd-compare-section) and none on :host(compare-bar). A
+   var() with no fallback is invalid at computed-value time, so a bar used
+   outside a section lost its height entirely: measured on CompareSection
+   "compare-bar (isolated)", which puts four bars in a plain div, the track
+   was 0px tall with no border and no fill, and the overflow: hidden below
+   clipped the label away with it. Four invisible bars in a story whose whole
+   job is to show the bar on its own -- and render-health cannot see it,
+   because other things on the page do occupy space.
+   
+   The fallbacks are the same values the section declares, so a bar inside a
+   section is unchanged, and a themed section still wins: a custom property
+   inheriting from an ancestor beats a fallback, where a declaration on
+   :host(compare-bar) would have beaten the theme and pinned every bar. */
 .bar-track {
   position:      relative;
-  height:        var(--cs-bar-height);
+  height:        var(--cs-bar-height, var(--dimension-48));
   border-radius: var(--radius-xl);
   overflow:      hidden;
   background:    var(--cs-bar-track-bg, transparent);
-  border:        var(--border-width-1) solid var(--cs-bar-track-border);
+  border:        var(--border-width-1) solid var(--cs-bar-track-border, var(--color-border-subtle));
   box-sizing:    border-box;
 }
 
@@ -234,52 +281,141 @@ slot[name="header"] { display: contents; }
 
 .bar-score { font-variant-numeric: tabular-nums; }
 
+/* The fallbacks matter: --cs-bar-primary-bg and -fg are declared on
+   :host(bd-compare-section) only, so a compare-bar used on its own has neither.
+   var() with no fallback is invalid at computed-value time, which made the fill
+   transparent and dropped the label back to inherited ink -- measured on
+   CompareSection "compare-bar (isolated)", a primary bar with
+   background rgba(0, 0, 0, 0) and a dark label, indistinguishable from a
+   secondary bar apart from its weight.
+   
+   Fallbacks rather than a declaration on :host(compare-bar): a value set on the
+   bar's own host would override the one inheriting from a themed section and
+   pin every bar blue. */
 :host(compare-bar[variant="primary"]) .bar-fill {
-  background: var(--cs-bar-primary-bg);
+  background: var(--cs-bar-primary-bg, var(--status-brand-fill));
 }
 :host(compare-bar[variant="primary"]) .bar-label,
 :host(compare-bar[variant="primary"]) .bar-score {
-  color:       var(--cs-bar-primary-fg);
+  color:       var(--cs-bar-primary-fg, var(--status-brand-on-fill));
+  /* no role: this weight belongs to the primary VARIANT, not to the text --
+     the same bar reads 400 in every other variant. A variant is a UI state,
+     the category CLAUDE.md keeps apart from type when it says a focus ring is
+     never expressed by swapping a border colour. See button.css.js's
+     .button--bold for the argument. */
   font-weight: var(--typography-fontWeight-semibold);
 }
 
 :host(compare-bar[variant="secondary"]) .bar-fill,
 :host(compare-bar:not([variant]))       .bar-fill {
-  background: var(--cs-bar-secondary-bg);
+  /* no role: the same decision as --cs-bar-secondary-bg, which this repeats as
+     a fallback for a compare-bar used outside a bd-compare-section. */
+  background: var(--cs-bar-secondary-bg, var(--color-neutral-100));
 }
 :host(compare-bar[variant="secondary"]) .bar-label,
 :host(compare-bar:not([variant]))       .bar-label,
 :host(compare-bar[variant="secondary"]) .bar-score,
 :host(compare-bar:not([variant]))       .bar-score {
-  color:       var(--color-neutral-900);
+  color:       var(--color-text-primary);
   font-weight: var(--typography-body-regular-fontWeight);
 }
 
+/* theme-green and theme-red take --status-*-fill and --status-*-on-fill: a
+   saturated fill carrying a label on it is exactly the responsibility those
+   roles name, and bd-badge variant="fill" already draws it.
+   
+   This is adopting a decision the system recorded rather than making a new one.
+   badge.css.js: "green-700 with a white label, rather than the design's
+   green-500 with a dark one. green-700 is the lightest step in the family that
+   carries white text at 4.5:1 -- it measures 4.75, where green-600 is only
+   3.20." So green-500-with-dark-ink was considered there and rejected.
+   
+   Measured on the built stories, white label on the primary fill:
+     theme-green  green-500 #15c14f  2.39:1  FAIL  ->  green-700 #0e8532  4.75:1
+     theme-red    red-500   #ff0000  4.00:1  FAIL  ->  red-600   #d60000  5.44:1
+   Both are 16px/600, which is not WCAG large text, so the bar is 4.5:1.
+
+   Each theme also used to set --cs-icon-color and --cs-icon-filter, eight
+   declarations in all, and nothing read either one: the card icon is a <bd-img>
+   sized by .card-icon-wrap and given no colour treatment at all. git log -S on
+   the reading form finds no commit in the history where a consumer existed, so
+   they were written and never wired up rather than orphaned by a later change.
+   Removed. They were carrying a paragraph of contrast reasoning about the -500
+   steps that read as a live decision, and one of the two occurrences of the raw
+   #7c3aed literal -- the fill below is the only one left.
+
+   Worth recording so it is not re-derived: green-500 is 2.39:1 on white, which
+   is below the 3:1 non-text minimum, so tinting that icon green-500 would have
+   been a 1.4.11 question if it had ever happened. It would not have failed even
+   then -- compare.js renders the icon aria-hidden with alt="", which is the
+   exemption -- but the margin is why nothing should reach for -500 here later
+   on the strength of the deleted comment. */
 :host(bd-compare-section.theme-green) {
-  --cs-bar-primary-bg: var(--color-green-500);
-  --cs-bar-primary-fg: var(--color-neutral-0);
-  --cs-icon-color:     var(--color-green-500);
-  --cs-icon-filter: invert(35%) sepia(72%) saturate(500%) hue-rotate(100deg) brightness(95%) contrast(95%);
+  --cs-bar-primary-bg: var(--status-success-fill);
+  --cs-bar-primary-fg: var(--status-success-on-fill);
 }
 :host(bd-compare-section.theme-red) {
-  --cs-bar-primary-bg: var(--color-red-500);
-  --cs-bar-primary-fg: var(--color-neutral-0);
-  --cs-icon-color:     var(--color-red-500);
-  --cs-icon-filter: invert(22%) sepia(90%) saturate(700%) hue-rotate(345deg) brightness(95%) contrast(95%);
-}
+  --cs-bar-primary-bg: var(--status-error-fill);
+  --cs-bar-primary-fg: var(--status-error-on-fill);
+}
+/* theme-dark and theme-purple have no --status-*-fill pair to adopt -- "dark"
+   and "purple" are themes, not statuses -- so the migration above does not
+   reach them. They are settled separately, and only one of them is settled.
+
+   theme-dark is D1, approved. The label measured 3.35:1 on the blue-400 fill
+   and failed. Two directions had precedent here and they look different:
+   darken the fill to blue-500 and keep the white label (4.53:1), or keep
+   blue-400 and flip the ink dark (5.37:1). The approved direction is the
+   second, because blue-400 is deliberately the brighter step so the fill still
+   reads on a dark ground -- darkening it to blue-500 would have spent the one
+   thing this theme exists for in order to fix the ink.
+
+   The ink is --color-text-primary, and that is a responsibility rather than a
+   value. Two tokens resolve to neutral-900 today and only one of them means
+   this. --status-warning-on-fill is the ink belonging to the *warning* fill,
+   and a compare bar is not a warning; taking it for the value would also tie
+   this theme to yellow-500's future, so a warning fill later dark enough to
+   carry white would turn this label white on light blue. --color-text-primary
+   is the default ink for copy on a light ground, which is what a label on a
+   light blue fill is, and it is already what the secondary bar's label uses on
+   --cs-bar-secondary-bg two rules above. Same job in the same file, same role.
+
+   Measured on the built stories at 16px/600, which is not WCAG large text, so
+   the bar is 4.5:1:
+     theme-dark  blue-400 #338bff  white #ffffff  3.35:1  FAIL
+                                -> ink   #151719  5.37:1  PASS
+
+   theme-purple measures 5.70:1 and passes, so there is no accessibility
+   pressure; #7c3aed is a raw hex for a colour the palette does not contain.
+   Giving it a token or retiring the theme is a product decision, still open.
+
+   This used to add "and lint:tokens does not report it", which reads as a gate
+   weakness and is not one. lint:tokens carries the literal in ALLOW.hex with
+   the reason on the line above it -- no purple in the palette, nearest token
+   34.6 deltaE away -- so the silence is a registered exception, not a miss.
+   Checked by probe: an unlisted off-scale hex reports hex-off-scale and fails
+   the build, a palette value reports hex-for-token, and this one stays quiet.
+   The check:color-coverage side needs its own record, which is what the
+   no token: marker below is; the two gates do not share an exemption. */
 :host(bd-compare-section.theme-purple) {
+  /* no token: the open product decision recorded above -- purple is not in the
+     palette, so neither the fill nor the ink that belongs to it can resolve.
+     green and red take --status-*-fill / --status-*-on-fill because they ARE
+     statuses; there is no such pair to adopt here, and giving white ink a role
+     while its ground stays a literal would record half a decision. */
   --cs-bar-primary-bg: #7c3aed;
-  --cs-bar-primary-fg: var(--color-neutral-0);
-  --cs-icon-color:     #7c3aed;
-  --cs-icon-filter: invert(25%) sepia(80%) saturate(800%) hue-rotate(255deg) brightness(90%) contrast(95%);
+  --cs-bar-primary-fg: var(--color-neutral-0);  /* no token: as above */
 }
 :host(bd-compare-section.theme-dark) {
+  /* no role: nothing in the semantic set resolves to blue-400. That is the
+     point of the D1 decision above -- blue-400 is deliberately the brighter
+     step so the fill still reads on a dark ground -- so the absence is the
+     theme working, not a gap to close. */
   --cs-bar-primary-bg: var(--color-blue-400);
-  --cs-bar-primary-fg: var(--color-neutral-0);
-  --cs-icon-color:     var(--color-blue-400);
-  --cs-icon-filter: invert(65%) sepia(50%) saturate(500%) hue-rotate(195deg) brightness(105%) contrast(95%);
+  --cs-bar-primary-fg: var(--color-text-primary);
+  --cs-section-text: var(--color-text-inverse);
 }
 
-:host(bd-compare-section.bars-tall)    { --cs-bar-height: var(--dimension-55px); }
-:host(bd-compare-section.bars-compact) { --cs-bar-height: var(--dimension-40px); --cs-gap: var(--spacing-24); }
+:host(bd-compare-section.bars-tall)    { --cs-bar-height: var(--dimension-56); }
+:host(bd-compare-section.bars-compact) { --cs-bar-height: var(--dimension-40); --cs-gap: var(--spacing-24); }
 `;

package/src/components/compare/compare.js

@@ -1,6 +1,13 @@
 import { LitElement, html, nothing } from "lit";
-import { tokens } from "../../tokens/tokens.js";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
+import "../heading/heading.js";
+import "../image/image.js";
+import "../link/link.js";
+import "../paragraph/paragraph.js";
 import compareCSS from "./compare.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
+import { matchesBelow } from "../shared/token-scales.js";
 
 function readStretchVars(el) {
   const styles = getComputedStyle(el);
@@ -49,7 +56,7 @@ class CompareBar extends LitElement {
     _animatedScore: { state: true }
   };
 
-  static styles = [tokens, compareCSS];
+  static styles = [compareCSS];
 
   constructor() {
     super();
@@ -230,7 +237,7 @@ class CompareCard extends LitElement {
     chartScale     : { type: Number,  attribute: "chart-scale" }
   };
 
-  static styles = [tokens, compareCSS];
+  static styles = [compareCSS];
 
   constructor() {
     super();
@@ -341,7 +348,7 @@ class CompareCard extends LitElement {
     if (!this.footnote) return "";
 
     if (!this.footnoteHref) {
-      return html`<bd-p kind="xsmall" class="card-footnote">${this.footnote}</bd-p>`;
+      return html`<bd-p variant="xsmall" class="card-footnote">${this.footnote}</bd-p>`;
     }
 
     const splitOn    = "Source ";
@@ -349,8 +356,8 @@ class CompareCard extends LitElement {
 
     if (idx === -1) {
       return html`
-        <bd-p kind="xsmall" class="card-footnote">
-          <bd-link href="${this.footnoteHref}" target="_blank" font-size="12px" color="var(--color-neutral-900)" underline>
+        <bd-p variant="xsmall" class="card-footnote">
+          <bd-link href="${this.footnoteHref}" target="_blank" font-size="xs" color="strong" underline>
             ${this.footnote}
           </bd-link>
         </bd-p>
@@ -361,12 +368,28 @@ class CompareCard extends LitElement {
     const linkedText = this.footnote.slice(idx + splitOn.length);
 
     return html`
-      <bd-p kind="xsmall" class="card-footnote">
-        ${before}<bd-link href="${this.footnoteHref}" target="_blank" font-size="12px" color="var(--color-neutral-900)" underline>${linkedText}</bd-link>
+      <bd-p variant="xsmall" class="card-footnote">
+        ${before}<bd-link href="${this.footnoteHref}" target="_blank" font-size="xs" color="strong" underline>${linkedText}</bd-link>
       </bd-p>
     `;
   }
 
+  /* aria-labelledby resolves against the root it is written in, and a
+     plain id on the <bd-h> HOST is what makes that possible: the host
+     sits in this shadow root beside the element referring to it, while
+     the <h3> bd-h renders lives in bd-h's own shadow root where an IDREF
+     from here cannot reach it. Name computation walks the flattened
+     tree, so the host carries the slotted title text.
+     This used to be spelled heading-id, which bd-h has never had a
+     property for and has never read, so nothing carried the id at all
+     and all 43 references across 16 Compare stories pointed at nothing.
+     The <section> was not merely unnamed -- a section with no accessible
+     name gets no region role, so the landmark did not exist.
+     id, not a new bd-h attribute, because modal.js already does exactly
+     this two components over and it works: its role=dialog resolves
+     aria-labelledby="modal-title" to a <bd-h id="modal-title"> and
+     reports the accessible name "VPN Protection". The manifest never
+     claimed a headingId property either. */
   _renderHorizontal() {
     return html`
       <div
@@ -382,7 +405,8 @@ class CompareCard extends LitElement {
         <div class="card-left">
           <slot name="header">
             <div class="card-left-top">
-              ${this.iconSrc ? html`
+              ${this.iconSrc
+                ? html`
                 <div class="card-icon-wrap" aria-hidden="true">
                   <bd-img
                     src="${this.iconSrc}"
@@ -395,12 +419,15 @@ class CompareCard extends LitElement {
                     loading="eager"
                   ></bd-img>
                 </div>
-              ` : ""}
-              <bd-h as="h3" class="card-title" heading-id="${this._headingId}">${this.title}</bd-h>
+              `
+                : ""}
+              <bd-h as="h3" class="card-title" id="${this._headingId}">${this.title}</bd-h>
             </div>
-            ${this.description ? html`
-              <bd-p kind="regular" class="card-description">${this.description}</bd-p>
-            ` : ""}
+            ${this.description
+              ? html`
+              <bd-p variant="regular" class="card-description">${this.description}</bd-p>
+            `
+              : ""}
             ${this._renderFootnote()}
           </slot>
         </div>
@@ -417,7 +444,7 @@ class CompareCard extends LitElement {
   render() {
     if (this.layout === "horizontal") return this._renderHorizontal();
 
-    const isMobile = window.matchMedia("(max-width: 767px)").matches;
+    const isMobile = matchesBelow('md');
 
     return html`
       <div
@@ -449,11 +476,11 @@ class CompareCard extends LitElement {
             : ""}
           <div class="card-text-wrap">
             ${isMobile
-              ? html`<bd-h as="h5" class="card-title" heading-id="${this._headingId}">${this.title}</bd-h>`
-              : html`<bd-h as="h4" class="card-title" heading-id="${this._headingId}">${this.title}</bd-h>`}
+              ? html`<bd-h as="h5" class="card-title" id="${this._headingId}">${this.title}</bd-h>`
+              : html`<bd-h as="h4" class="card-title" id="${this._headingId}">${this.title}</bd-h>`}
             ${this.description
               ? html`
-                <bd-p kind="${isMobile ? "small" : "regular"}" class="card-description">
+                <bd-p variant="${isMobile ? "small" : "regular"}" class="card-description">
                   ${this.description}
                 </bd-p>
               `
@@ -484,7 +511,7 @@ class CompareSection extends LitElement {
     gap     : { type: String }
   };
 
-  static styles = [tokens, compareCSS];
+  static styles = [ensembleCSS, compareCSS];
 
   constructor() {
     super();
@@ -527,7 +554,7 @@ class CompareSection extends LitElement {
     this._syncRaf = requestAnimationFrame(() => {
       this._syncRaf = 0;
 
-      const isMobile = window.matchMedia("(max-width: 767px)").matches;
+      const isMobile = matchesBelow('md');
 
       // Get all slotted compare-card elements
       const slot = this.shadowRoot?.querySelector("slot");
@@ -560,14 +587,14 @@ class CompareSection extends LitElement {
   }
 
   render() {
-    const isMobile = window.matchMedia("(max-width: 767px)").matches;
+    const isMobile = matchesBelow('md');
     const gapStyle = this.gap
       ? `--_cols: ${this.columns}; --cs-gap: ${this.gap}`
       : `--_cols: ${this.columns}`;
 
     return html`
       <section
-        class="cs-section"
+        class="bd-ensemble cs-section"
         aria-labelledby="${this.title ? this._sectionTitleId : nothing}"
       >
         ${this.title || this.subtitle
@@ -575,12 +602,12 @@ class CompareSection extends LitElement {
             <div class="cs-heading">
               ${this.title
                 ? isMobile
-                  ? html`<bd-h as="h4" class="cs-title" heading-id="${this._sectionTitleId}">${this.title}</bd-h>`
-                  : html`<bd-h as="h3" class="cs-title" heading-id="${this._sectionTitleId}">${this.title}</bd-h>`
+                  ? html`<bd-h as="h4" class="cs-title" id="${this._sectionTitleId}">${this.title}</bd-h>`
+                  : html`<bd-h as="h3" class="cs-title" id="${this._sectionTitleId}">${this.title}</bd-h>`
                 : ""}
               ${this.subtitle
                 ? html`
-                  <bd-p kind="${isMobile ? "small" : "regular"}" class="cs-subtitle">
+                  <bd-p variant="${isMobile ? "small" : "regular"}" class="cs-subtitle">
                     ${this.subtitle}
                   </bd-p>
                 `

package/src/components/compare/compare.stories.js

@@ -80,7 +80,7 @@ Three Lit web components for building customizable comparison sections with anim
 | \`--cs-bar-primary-fg\`     | \`var(--color-neutral-0)\`     | Primary bar text colour        |
 | \`--cs-bar-secondary-bg\`   | \`var(--color-neutral-100)\`   | Secondary bar fill colour      |
 | \`--cs-bar-track-border\`   | \`var(--color-neutral-200)\`   | Bar track border colour        |
-| \`--cs-bar-height\`         | \`var(--dimension-48px)\`      | Height of every bar            |
+| \`--cs-bar-height\`         | \`var(--dimension-48)\`      | Height of every bar            |
 | \`--cs-gap\`                | \`var(--spacing-32)\`          | Gap between cards              |
 | \`--cs-grid-max\`           | \`1228px\`                     | Max width of the card grid     |
         `
@@ -552,6 +552,46 @@ export const ThemeGreen = {
   `
 };
 
+export const ThemeRed = {
+  name  : "Theme — Red",
+  render: () => html`
+    <bd-compare-section
+      title="Red Theme"
+      gap="32px"
+      class="theme-red"
+    >
+      <compare-card
+        title="Best Protection"
+        description="Scale of 0–6. Higher is better."
+        footnote="Overall Score. July 2011 – February 2025. Source AV TEST.org"
+        footnote-href="${AV_TEST_URL}"
+        icon-src="${SHIELD_ICON}"
+        bar-stretch="false"
+      >
+        <compare-bar label="Bitdefender" score="5.95" max-score="6" variant="primary"></compare-bar>
+        <compare-bar label="Norton"      score="5.59" max-score="6" variant="secondary" scale="0.93"></compare-bar>
+        <compare-bar label="McAfee"      score="5.45" max-score="6" variant="secondary" scale="0.47"></compare-bar>
+      </compare-card>
+    </bd-compare-section>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `\`theme-red\` is a shipped variant of bd-compare-section and had no story, so
+                nothing rendered it and no gate opened it — which is how its primary bar label
+                sat at 4.00:1 unnoticed. P6C.5 measured that by applying the class at runtime,
+                because there was no story to measure.
+
+                It now takes \`--status-error-fill\` and \`--status-error-on-fill\`, the pair
+                the design system already defines for a saturated fill carrying a label, so
+                the label measures 5.44:1 against the 4.00:1 of the red-500 it replaced. The
+                other four themes are in the sibling stories; theme-dark's label was the one
+                remaining failure in this family and D1 has since fixed it.`
+      }
+    }
+  }
+};
+
 export const ThemePurple = {
   name  : "Theme — Purple",
   render: () => html`
@@ -625,7 +665,24 @@ export const ThemeDark = {
         </compare-card>
       </bd-compare-section>
     </div>
-  `
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `The primary bar label used to be white on the blue-400 fill, which measured
+                3.35:1 and failed. D1 kept the fill and changed the ink: blue-400 is
+                deliberately the brighter blue so the fill still reads on a dark ground, and
+                darkening it to blue-500 to carry white would have spent the one thing this
+                theme exists for.
+
+                The ink is \`--color-text-primary\`, the default ink for copy on a light
+                ground — which is what a label on a light blue fill is, and already what the
+                secondary bars beside it use. It measures 5.37:1 at 16px/600, against a 4.5:1
+                bar. The card stays light under this theme on purpose, so only the section
+                title inverts.`
+      }
+    }
+  }
 };
 
 
@@ -666,8 +723,8 @@ export const HorizontalLayoutCustomSlot = {
             <bd-img src="${SHIELD_ICON}" alt="" width="40" height="40" fit="contain" radius="none" shadow="none" loading="eager"></bd-img>
             <bd-h as="h3">Award-Winning Protection</bd-h>
           </div>
-          <bd-p kind="regular">Scale of 0–6. Higher is better. Independently tested since 2011.</bd-p>
-          <bd-p kind="xsmall" style="margin-top:auto">Overall Score. July 2011 – February 2025. Source AV TEST.org</bd-p>
+          <bd-p variant="regular">Scale of 0–6. Higher is better. Independently tested since 2011.</bd-p>
+          <bd-p variant="xsmall" style="margin-top:auto">Overall Score. July 2011 – February 2025. Source AV TEST.org</bd-p>
         </div>
         <compare-bar label="Bitdefender" score="5.95" max-score="6" variant="primary"></compare-bar>
         <compare-bar label="Norton"      score="5.89" max-score="6" variant="secondary" scale="0.93"></compare-bar>