@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/caption/caption.css.js

@@ -0,0 +1,21 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const captionCSS = css`
+  :host { display: block; }
+
+  figcaption {
+    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);
+  }
+
+  :host([size='sm']) figcaption {
+    letter-spacing: var(--typography-caption-small-letterSpacing);
+  }
+`;
+
+export default captionCSS;

package/src/components/caption/caption.js

@@ -0,0 +1,31 @@
+import { LitElement, html } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { captionCSS } from './caption.css.js';
+import { resolveSize } from '../shared/prop-vocabulary.js';
+
+export class BdCaption extends LitElement {
+  static styles = [captionCSS];
+
+  static properties = {
+    size: { type: String, reflect: true }
+  };
+
+  constructor() {
+    super();
+    this.size = 'md';
+  }
+
+  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`
+      <figcaption><slot></slot></figcaption>
+    `;
+  }
+}
+
+customElements.define('bd-caption', BdCaption);

package/src/components/caption/caption.stories.js

@@ -0,0 +1,62 @@
+import { html } from 'lit';
+import './caption.js';
+
+export default {
+  title     : 'Atoms/Caption',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdCaption** is the small explanatory line under a figure, table or chart.
+
+### Usage
+\`\`\`html
+<figure>
+  <img src="/images/chart.png" alt="Detections per month">
+  <bd-caption>Threat detections per month, 2026.</bd-caption>
+</figure>
+
+<bd-caption size="sm">Source: internal telemetry.</bd-caption>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`size\` | \`default\`, \`small\` | \`default\` |
+
+### Contrast
+The caption is \`--color-neutral-600\`, which is 6.59:1 on white and stays above
+4.5:1 at the \`small\` size too. Caption text is the most common place a design
+system slips below AA, because it is both small and grey — anything lighter
+than \`neutral-600\` would not clear it.
+
+### The figcaption is cosmetic
+This renders a \`<figcaption>\`, but inside its own shadow root. A native
+\`figure\`/\`figcaption\` association needs them to be parent and child in the same
+tree, so **placing this in a \`<figure>\` does not create that relationship** —
+the element is styled as a caption but carries no grouping semantics.
+
+If the association matters to you, use a real \`<figcaption>\` in the light DOM
+and reach for this only where the styling alone is wanted.
+        `
+      }
+    }
+  },
+  argTypes: {
+    size: {
+      control    : { type: 'select' },
+      options    : ['default', 'small'],
+      description: 'Type size of the caption.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+    }
+  }
+};
+
+export const Default = () => html`
+    <bd-caption>Threat detections per month, 2026.</bd-caption>
+  `;
+
+export const Small = () => html`
+    <bd-caption size="sm">Source: Bitdefender Labs</bd-caption>
+  `;

package/src/components/card-features/card-features.css.js

@@ -3,10 +3,6 @@ import { css } from "lit";
 export default css`
   :host {
     display: block;
-    --background-card-grey: var(--color-neutral-25);
-    --border-card-grey: var(--color-neutral-50);
-    // padding-top: var(--spacing-32);
-    // padding-bottom: var(--spacing-32);
   }
 
   .bd-card-features-s {
@@ -14,13 +10,12 @@ export default css`
     align-items: center;
     justify-content: center;
     position: relative;
+    /* Same reason as the card below, which already sets it: the gutters belong
+       inside the 100% and inside the max-width, not added on top of them. */
+    box-sizing: border-box;
     width: 100%;
     overflow: hidden;
     flex-direction: column;
-    padding-left: var(--spacing-14);
-    padding-right: var(--spacing-14);
-    max-width: 1400px;
-    margin: 0 auto;
   }
 
   .bd-card-features-header-s {
@@ -29,12 +24,6 @@ export default css`
     text-align: center;
   }
 
-  .bd-card-features-title-s {
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-semibold);
-    font-size: var(--typography-fontSize-2xl);
-  }
-
   .bd-card-features-track-s {
     width: 100%;
     display: grid;
@@ -47,9 +36,12 @@ export default css`
     flex-direction: row;
     align-items: flex-start;
     gap: var(--spacing-16);
-    background: var(--background-card-grey);
-    border-radius: var(--spacing-20);
-    padding: var(--spacing-24);
+    background: var(--color-surface-container);
+    border-radius: var(--card-radius);
+    /* The other content cards are all on 32, and this one is not the small one
+       that would justify less: at 431px it is wider than both the card box and
+       the light carousel item, which are 304 and 413 and still take 32. */
+    padding: var(--card-padding);
     font-family: var(--typography-fontFamily-sans);
     box-sizing: border-box;
     height: 100%;
@@ -75,15 +67,15 @@ export default css`
   }
 
   .bd-card-features-item-title-s {
-    font-size: var(--typography-fontSize-md);
-    font-weight: var(--typography-fontWeight-semibold);
     margin: 0;
   }
 
+  /* No type here: this selector needs a directly-slotted raw <p>, and every
+     consumer slots <bd-p>, so it has never matched anything. The size and
+     leading are gone; the rest of the rule is dead by the same proof and is
+     left for a follow-up rather than widened into this one. */
   ::slotted(p) {
-    font-size: var(--typography-fontSize-sm);
-    color: var(--color-neutral-700);
-    line-height: var(--typography-lineHeight-normal);
+    color: var(--color-text-secondary);
     margin: 0;
     font-family: var(--typography-fontFamily-sans);
   }

package/src/components/card-features/card-features.js

@@ -1,17 +1,21 @@
 import { LitElement, html } 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 "../badge/badge.js";
 import "../heading/heading.js";
 import cardFeaturesCSS from "./card-features.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
 class CardFeatures extends LitElement {
   static properties = {
-    title: { type: String }
+    title       : { type: String },
+    headingLevel: { type: Number, attribute: "heading-level" }
   };
 
   constructor() {
     super();
     this.title = "";
+    this.headingLevel = 2;
     this._resizeObserver = null;
   }
 
@@ -60,13 +64,36 @@ class CardFeatures extends LitElement {
     });
   }
 
+
+  /**
+   * The heading element this section renders. Level is the document-outline
+   * question and belongs to whoever composes the page; the type scale is this
+   * component's own and does not move with it. Defaults to h2, because a
+   * reusable section cannot know it is the only thing on the page, and two of
+   * these used to put two h1s on one.
+   */
+  get _headingTag() {
+    const n = Number(this.headingLevel);
+    return Number.isInteger(n) && n >= 1 && n <= 6 ? `h${n}` : "h2";
+  }
+
+  /* bd-h already builds the dynamic tag, and it keeps the two questions apart
+     the way this component needs: as= is the outline level the page composes,
+     visual-level= is the type role, which is ours. Building the element here
+     meant re-implementing bd-h and then hand-writing the type on top of it. */
+  _renderTitle(className) {
+    return html`<bd-h as=${this._headingTag} visual-level="h3" class=${className}
+      >${this.title}</bd-h
+    >`;
+  }
+
   render() {
     return html`
-      <section class="bd-card-features-s">
+      <section class="bd-ensemble bd-card-features-s">
         ${this.title
           ? html`
               <div class="bd-card-features-header-s">
-                <h1 class="bd-card-features-title-s">${this.title}</h1>
+                ${this._renderTitle("bd-card-features-title-s")}
               </div>
             `
           : null}
@@ -83,15 +110,35 @@ class CardFeaturesItem extends LitElement {
     title       : { type: String },
     icon        : { type: String },
     badge       : { type: String },
-    badgeVariant: { type: String }
+    /* `badge-variant`, which this component documents twice over: the usage
+       example in card-features.stories.js writes
+       badge-variant="bd-light-blue", and the props table there lists
+       `badge-variant` as a documented String input. It was never observed --
+       Lit was listening for `badgevariant` -- so the property held its "fill"
+       default and every badge rendered the same fill treatment: measured on
+       Modules/CardFeatures Default, the item asking for "bd-light-green" came
+       out rgb(0, 109, 255), the identical blue as the four asking for
+       "bd-light-blue".
+
+       Zero consumers of the lowercase spelling, so the mapping is safe. The
+       value is passed straight through to bd-badge's own `variant`, which is
+       where the colour decision lives; nothing about the badge's design
+       changes here beyond the variant finally being the one that was asked
+       for. */
+    badgeVariant: { type: String, attribute: "badge-variant" },
+    badgeTone   : { type: String },
+    headingLevel: { type: Number, attribute: "heading-level" }
   };
 
   constructor() {
     super();
     this.title        = "";
+    this.headingLevel = 3;
     this.icon         = "";
     this.badge        = "";
-    this.badgeVariant = "";
+    // reproduces the blue fill these badges carried before ds-badge
+    this.badgeVariant = "fill";
+    this.badgeTone = "primary";
   }
 
   _renderIcon() {
@@ -112,6 +159,17 @@ class CardFeaturesItem extends LitElement {
     return "";
   }
 
+
+  /**
+   * One level below the section default. The h5 it used to carry was a type
+   * choice, not an outline one, so the size stays on visual-level while the
+   * level itself stops skipping three steps below its own section.
+   */
+  get _headingTag() {
+    const n = Number(this.headingLevel);
+    return Number.isInteger(n) && n >= 1 && n <= 6 ? `h${n}` : "h3";
+  }
+
   render() {
     return html`
       <div class="bd-card-features-box-s">
@@ -121,10 +179,11 @@ class CardFeaturesItem extends LitElement {
           ${this.title
             ? html`
                 <div class="bd-card-features-title-badge-wrapper-s">
-                  <bd-h as="h5" fontWeight="700" class="bd-card-features-item-title-s">${this.title}</bd-h>
+                  <bd-h as="${this._headingTag}" visual-level="h5" fontWeight="bold" class="bd-card-features-item-title-s">${this.title}</bd-h>
                   ${this.badge
                     ? html`<bd-badge
                         variant="${this.badgeVariant}"
+                        tone="${this.badgeTone}"
                         size="sm"
                       >${this.badge}</bd-badge>`
                     : ""}
@@ -138,8 +197,8 @@ class CardFeaturesItem extends LitElement {
   }
 }
 
-CardFeatures.styles     = [tokens, cardFeaturesCSS];
-CardFeaturesItem.styles = [tokens, cardFeaturesCSS];
+CardFeatures.styles     = [ensembleCSS, cardFeaturesCSS];
+CardFeaturesItem.styles = [cardFeaturesCSS];
 
 customElements.define("bd-card-features-item", CardFeaturesItem);
 customElements.define("bd-card-features-section", CardFeatures);

package/src/components/card-features/card-features.stories.js

@@ -11,7 +11,7 @@ import '../paragraph/paragraph.js';
 import './card-features.js';
 
 export default {
-  title     : 'Components/CardFeatures',
+  title     : 'Modules/CardFeatures',
   tags      : ['autodocs'],
   parameters: {
     docs: {
@@ -26,7 +26,7 @@ export default {
     badge="NEW"
     badge-variant="bd-light-blue"
   >
-    <bd-individual-icon slot="icon" width="32" height="32" color="#006DFF"></bd-individual-icon>
+    <bd-individual-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-individual-icon>
     <bd-p>Specialized AI chatbot that helps you identify suspicious online interactions.</bd-p>
   </bd-card-features-item>
 </bd-card-features-section>
@@ -45,15 +45,15 @@ export default {
 };
 
 const iconMap = [
-  html`<bd-individual-icon slot="icon" width="32" height="32" color="#006DFF"></bd-individual-icon>`,
-  html`<bd-globe-icon slot="icon" width="32" height="32" color="#006DFF"></bd-globe-icon>`,
-  html`<bd-machine-learning-icon slot="icon" width="32" height="32" color="#006DFF"></bd-machine-learning-icon>`,
-  html`<bd-analysis-icon slot="icon" width="32" height="32" color="#006DFF"></bd-analysis-icon>`,
-  html`<bd-family-icon slot="icon" width="32" height="32" color="#006DFF"></bd-family-icon>`,
-  html`<bd-arrow-up-icon slot="icon" width="32" height="32" color="#006DFF"></bd-arrow-up-icon>`,
-  html`<bd-close-icon slot="icon" width="32" height="32" color="#006DFF"></bd-close-icon>`,
-  html`<bd-globe-icon slot="icon" width="32" height="32" color="#006DFF"></bd-globe-icon>`,
-  html`<bd-analysis-icon slot="icon" width="32" height="32" color="#006DFF"></bd-analysis-icon>`
+  html`<bd-individual-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-individual-icon>`,
+  html`<bd-globe-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-globe-icon>`,
+  html`<bd-machine-learning-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-machine-learning-icon>`,
+  html`<bd-analysis-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-analysis-icon>`,
+  html`<bd-family-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-family-icon>`,
+  html`<bd-arrow-up-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-arrow-up-icon>`,
+  html`<bd-close-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-close-icon>`,
+  html`<bd-globe-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-globe-icon>`,
+  html`<bd-analysis-icon slot="icon" width="32" height="32" color="var(--color-blue-500)"></bd-analysis-icon>`
 ];
 
 const items = [

package/src/components/cards/card.css.js

@@ -1,34 +1,22 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { above, below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
-    --background-card-grey: var(--color-neutral-25);
-    --border-card-grey: var(--color-neutral-50);
     --bd-card-cols: 4;
-    max-width: 1290px;
-    margin: 0 auto;
   }
 
-  ::slotted([slot="icon"]) {
-    max-width: 120px !important;
-    max-height: 120px !important;
-    object-fit: contain !important;
-    display: block !important;
-  }
 
   ::slotted(bd-card-item) {
     display: block;
     width: var(--bd-card-width, 280px);
     flex: 0 0 var(--bd-card-width, 280px);
     min-width: 200px;
-    margin: 0 !important;
+    margin: 0;
   }
 
   .bd-section-title-s {
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-semibold);
-    font-size: 2em;
     text-align: center;
     margin: 0;
   }
@@ -36,7 +24,7 @@ export default css`
   .bd-section-subtitle-s {
     font-family: var(--typography-fontFamily-sans);
     font-size: var(--typography-body-regular-fontSize);
-    color: var(--color-neutral-700);
+    color: var(--color-text-secondary);
     text-align: center;
     margin: var(--spacing-8) 0 0 0;
   }
@@ -53,7 +41,7 @@ export default css`
   /* Outline-variant sections get extra top padding above the header,
      per the reference design. */
   :host([variant="outline"]) .bd-header-light-carousel-s {
-    padding-top: 80px;
+    padding-top: var(--spacing-80);
   }
 
   .bd-light-carousel-s {
@@ -63,7 +51,6 @@ export default css`
     position: relative;
     width: 100%;
     flex-direction: column;
-    max-width: 1290px;
     margin: 0 auto;
     padding-top: var(--spacing-64);
     padding-bottom: var(--spacing-64);
@@ -80,17 +67,17 @@ export default css`
   }
 
   .bd-light-box-s {
-    background: var(--background-card-grey);
-    border-radius: var(--spacing-20);
-    padding: var(--spacing-32);
+    background: var(--color-surface-container);
+    border-radius: var(--card-radius);
+    padding: var(--card-padding);
     display: flex;
     flex-direction: column;
     align-items: flex-start;
     justify-content: flex-start;
     text-align: start;
-    transition: transform 0.2s ease-in-out;
+    transition: transform var(--transition-duration-normal) var(--transition-easing-smooth);
     position: relative;
-    z-index: 2;
+    z-index: var(--z-raised);
     font-family: var(--typography-fontFamily-sans);
     box-sizing: border-box;
     width: 100%;
@@ -98,17 +85,17 @@ export default css`
   }
 
   .bd-light-box-blue {
-    background: #E4F2FF !important;
+    background: var(--status-brand-surface);
   }
 
   /* === OUTLINE VARIANT — bordered, tinted, fully centered card. Set
      variant="outline" on bd-card-section (propagates to items) or on an
      individual bd-card-item to opt it in/out per-card. === */
   .bd-light-box-outline {
-    background-color: var(--color-neutral-25);
-    border: 2px solid var(--color-blue-500);
-    border-radius: var(--radius-2xl, 1rem);
-    padding: 40px;
+    background-color: var(--color-surface-container);
+    border: var(--border-width-2) solid var(--color-border-brand);
+    border-radius: var(--radius-2xl);
+    padding: var(--spacing-40);
     align-items: center !important;
     justify-content: center !important;
     text-align: center !important;
@@ -127,18 +114,18 @@ export default css`
   .bd-light-box-outline .bd-card-title-group {
     align-items: center;
     text-align: center;
-    margin-top: 60px;
+    margin-top: var(--spacing-64);
   }
 
   .bd-light-box-outline .bd-card-title-group bd-h {
-    color: var(--color-blue-500, #006dff);
+    color: var(--color-text-brand);
     text-align: center;
   }
 
   .bd-light-box-outline .bd-card-item-subtitle,
   .bd-light-box-outline .bd-card-content-wrapper p,
   .bd-light-box-outline .bd-card-content-wrapper ::slotted(*) {
-    color: var(--color-neutral-700);
+    color: var(--color-text-secondary);
     text-align: center;
   }
 
@@ -152,9 +139,9 @@ export default css`
   }
 
   .bd-light-box-center {
-    align-items: center !important;
-    justify-content: center !important;
-    text-align: center !important;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
   }
 
   .bd-light-box-center .bd-light-box-header-s {
@@ -174,30 +161,6 @@ export default css`
     justify-content: center;
   }
 
-  .bd-light-box-s h3 {
-    font-size: var(--heading-xsmall);
-    margin: var(--spacing-0) var(--spacing-8) var(--spacing-8) var(--spacing-0);
-    font-weight: 600;
-    font-family: var(--typography-fontFamily-sans);
-    text-align: start;
-  }
-
-  .bd-light-box-center h3 {
-    text-align: center !important;
-    margin: var(--spacing-0) var(--spacing-0) var(--spacing-8) var(--spacing-0) !important;
-  }
-
-  .bd-light-box-s p {
-    font-size: var(--spacing-16);
-    margin: var(--spacing-0) var(--spacing-0) 1em var(--spacing-0);
-    font-family: var(--typography-fontFamily-sans);
-    text-align: start;
-  }
-
-  .bd-light-box-center p {
-    text-align: center !important;
-  }
-
   .bd-light-icon-s {
     max-width: 120px;
     max-height: 120px;
@@ -220,7 +183,7 @@ export default css`
   .bd-light-title-badge-wrapper-s {
     display: flex;
     align-items: flex-start;
-    gap: var(--spacing-4, 4px);
+    gap: var(--spacing-4);
     overflow: hidden;
     margin-bottom: var(--spacing-8);
     width: 100%;
@@ -235,10 +198,14 @@ export default css`
 
   .bd-card-item-subtitle {
     font-family: var(--typography-fontFamily-sans);
-    font-size: var(--typography-fontSize-sm);
-    color: var(--color-neutral-600);
+    /* 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);
+    color: var(--color-text-muted);
     margin: 0;
-    line-height: var(--typography-lineHeight-normal);
+    line-height: var(--typography-body-small-lineHeight);
   }
 
   .bd-card-content-wrapper {
@@ -266,13 +233,13 @@ export default css`
      content wraps differently. Row counts come from _syncAlignRows(). Row gaps
      between tracks stay 0 so spacing inside cards is unchanged; spacing
      between wrapped card rows comes from the item margin instead. === */
-  @media (min-width: 769px) {
+  @media ${unsafeCSS(above('md'))} {
     :host([align-rows]) .bd-light-carousel-track-s {
       display: grid;
       grid-template-columns: repeat(var(--bd-card-cols), minmax(0, 1fr));
-      column-gap: 1.5rem;
+      column-gap: var(--spacing-24);
       row-gap: 0;
-      margin-bottom: -1.5rem;
+      margin-bottom: calc(-1 * var(--spacing-24));
     }
 
     :host([align-rows]) ::slotted(bd-card-item) {
@@ -281,7 +248,7 @@ export default css`
       grid-row: span var(--bd-card-rows, 4);
       width: auto;
       min-width: 0;
-      margin: 0 0 1.5rem !important;
+      margin: 0 0 var(--spacing-24) !important;
     }
 
     :host([align-rows]) .bd-light-box-s {
@@ -323,7 +290,7 @@ export default css`
   }
 
 
-  @media (max-width: 768px) {
+  @media ${unsafeCSS(below('md'))} {
     .bd-light-carousel-track-s {
       flex-direction: column;
       gap: var(--spacing-20);
@@ -334,23 +301,35 @@ export default css`
       padding: 0 20px;
   }
     ::slotted(bd-card-item) {
-      width: 100% !important;
-      max-width: 100% !important;
-      flex: 0 0 auto !important;
-      min-width: 0 !important;
-      margin: 0 auto !important;
-       padding: 0 20px;
-
+      width: 100%;
+      max-width: 100%;
+      flex: 0 0 auto;
+      min-width: 0;
+      margin: 0 auto;
+      padding: 0 20px;
+      /* The gutters have to sit inside the 100%, exactly as they already do on
+         the box below. Without this the item is the full column plus 40px and
+         pushes the page 24px wider than the phone. */
+      box-sizing: border-box;
     }
 
     .bd-light-box-s {
-      width: 100% !important;
-      max-width: 100% !important;
-      min-width: 0 !important;
-      flex: none !important;
-      margin: 0 !important;
-      box-sizing: border-box !important;
+      width: 100%;
+      max-width: 100%;
+      min-width: 0;
+      flex: none;
+      margin: 0;
+      box-sizing: border-box;
     }
   }
 
-`;
+
+  /* A reader who asked for less motion was still getting the card lift. Twenty-three
+     of the thirty animated directories in this package honour the query; this
+     one did not. */
+  @media (prefers-reduced-motion: reduce) {
+    .bd-light-box-s {
+      transition: none;
+    }
+  }
+`;