@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/overview/overview.css.js

@@ -12,9 +12,7 @@ export default css`
     grid-template-rows: auto auto;
     column-gap: var(--spacing-48);
     row-gap: 0;
-    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;
   }
 
@@ -23,8 +21,6 @@ export default css`
     grid-column: 1 / -1;
     grid-row: 1;
     margin: 0;
-    color: var(--color-neutral-1000);
-    line-height: var(--typography-lineHeight-tight, 1.1);
     margin-bottom: var(--spacing-48);
   }
 
@@ -39,9 +35,11 @@ export default css`
 
   .bd-infopanel-description {
     margin: 0;
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
     max-width: 46ch;
-    line-height: 1.5;
+    /* Keep: the max-width above is in ch, and ch resolves against THIS
+       element's font. Stating the family here is what pins the measure;
+       removing it would leave 46ch depending on whatever is inherited. */
     font-family: var(--typography-fontFamily-sans);
   }
 
@@ -69,24 +67,31 @@ export default css`
     padding-bottom: 0;
   }
 
+  /* --border-width-2, not a 2px literal. The 2px rule itself is deliberate --
+     it is the blue brand rule that separates each label/value pair, and
+     bd-trust-panel uses the same visual language for its statistics -- so this
+     is a token-category fix, not a design change. --border-width-2 is 2px, so
+     nothing moves. Removes the one baselined finding recorded against this
+     file, border-width-literal|overview.css.js|border-top: 2px. */
   .bd-infopanel-divider {
-    border-top: 2px solid var(--color-blue-500);
+    border-top: var(--border-width-2) solid var(--color-border-brand);
     margin-bottom: var(--spacing-16);
   }
 
   .bd-infopanel-label {
     margin: 0;
-    color: var(--color-neutral-600);
+    color: var(--color-text-muted);
+    /* Load-bearing, despite sitting on a bd-p host where the type axes are
+       inert. Those axes are dead because bd-p sets them on its own inner p;
+       text-transform it never sets, so this value inherits down to the
+       rendered text like any inherited property would. Deleting it
+       un-uppercases the label. See scripts/atom-inert-properties.json. */
     text-transform: uppercase;
-    letter-spacing: .1em;
-    font-family: var(--typography-fontFamily-mono, monospace);
-    font-size: var(--typography-fontSize-xxs);
   }
 
   .bd-infopanel-value {
     margin: 0;
-    color: var(--color-neutral-1000);
-    font-weight: var(--typography-fontWeight-bold, 700);
+    color: var(--color-text-primary);
   }
 
   /* === RESPONSIVE === */

package/src/components/overview/overview.js

@@ -3,6 +3,7 @@ import { tokens } from "../../tokens/tokens.js";
 import "../heading/heading.js";
 import "../paragraph/paragraph.js";
 import infoPanelCSS from "./overview.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
 class Overview extends LitElement {
   static properties = {
@@ -11,7 +12,7 @@ class Overview extends LitElement {
     facts      : { type: Array } // [{ label: String, value: String }]
   };
 
-  static styles = [tokens, infoPanelCSS];
+  static styles = [tokens, ensembleCSS, infoPanelCSS];
 
   constructor() {
     super();
@@ -22,7 +23,7 @@ class Overview extends LitElement {
 
   render() {
     return html`
-      <div class="bd-infopanel-container">
+      <div class="bd-ensemble bd-infopanel-container">
         ${this.title
           ? html`
               <bd-h as="h2" class="bd-infopanel-title">
@@ -34,7 +35,7 @@ class Overview extends LitElement {
         <div class="bd-infopanel-left">
           ${this.description
             ? html`
-                <bd-p kind="large" class="bd-infopanel-description">
+                <bd-p variant="large" class="bd-infopanel-description">
                   <slot name="description">${this.description}</slot>
                 </bd-p>
               `
@@ -48,8 +49,8 @@ class Overview extends LitElement {
             (fact) => html`
               <div class="bd-infopanel-row">
                 <div class="bd-infopanel-divider"></div>
-                <bd-p kind="xsmall" class="bd-infopanel-label">${fact.label}</bd-p>
-                <bd-p kind="normal" class="bd-infopanel-value">${fact.value}</bd-p>
+                <bd-p variant="xsmall" class="bd-infopanel-label">${fact.label}</bd-p>
+                <bd-p variant="regular" class="bd-infopanel-value">${fact.value}</bd-p>
               </div>
             `
           )}

package/src/components/overview/overview.stories.js

@@ -2,8 +2,8 @@ import { html } from "lit";
 import "./overview.js";
 
 export default {
-  title     : "Components/Overview",
-  component : "bd-info-panel",
+  title     : "Modules/Overview",
+  component : "bd-overview",
   tags      : ["autodocs"],
   parameters: {
     layout: "fullscreen",
@@ -16,7 +16,7 @@ labeled facts on the right, each row separated by a thin top border line — a
 
 ### Usage
 \`\`\`html
-<bd-info-panel
+<bd-overview
   title="What is AI Guardian?"
   description="AI Guardian is a Bitdefender security product that helps protect people and organisations from the risks of autonomous AI agents — prompt injection, unsafe tool use, data leakage, and unauthorised actions. It adds a baseline security model of policies, permissions, and auditing, guardrails for tool execution, and monitoring and response workflows."
   .facts=\${[
@@ -25,7 +25,7 @@ labeled facts on the right, each row separated by a thin top border line — a
     { label: "RUNS AS", value: "Background service" },
     { label: "VERDICTS", value: "Allowed / Flagged / Blocked" }
   ]}
-></bd-info-panel>
+></bd-overview>
 \`\`\`
 
 ### Attributes
@@ -54,11 +54,11 @@ labeled facts on the right, each row separated by a thin top border line — a
 };
 
 const render = (args) => html`
-  <bd-info-panel
+  <bd-overview
     title=${args.title}
     description=${args.description}
     .facts=${args.facts}
-  ></bd-info-panel>
+  ></bd-overview>
 `;
 
 export const Default = {
@@ -150,16 +150,16 @@ export const NoDescription = {
 export const SlottedContent = {
   name  : "Slotted Title, Description, and Extra Facts",
   render: () => html`
-    <bd-info-panel>
+    <bd-overview>
       <span slot="title">Custom <em>slotted</em> title</span>
       <span slot="description">Custom slotted description with <strong>inline markup</strong>.</span>
 
       <div slot="facts" class="bd-infopanel-row" style="display:flex; flex-direction:column; gap:4px; padding-top:16px;">
-        <div style="border-top: 1px solid #3b82f6; margin-bottom:16px;"></div>
-        <span style="text-transform:uppercase; letter-spacing:0.06em; font-size:12px; color:#60a5fa;">EXTRA</span>
+        <div style="border-top: 1px solid var(--color-border-brand); margin-bottom:16px;"></div>
+        <span style="text-transform:uppercase; letter-spacing:0.06em; font-size:12px; color:var(--color-text-brand);">EXTRA</span>
         <strong>A manually slotted fact row</strong>
       </div>
-    </bd-info-panel>
+    </bd-overview>
   `,
   parameters: {
     docs: {

package/src/components/page-switcher/page-switcher.css.js

@@ -5,92 +5,149 @@ export const pageSwitcherStyles = css`
     display: block;
     position: sticky;
     top: 0;
-    z-index: 200;
-    background: var(--color-neutral-0);
-    border-bottom: var(--border-width-1) solid var(--color-neutral-100);
-    --bd-accesibility-focus: var(--color-blue-500);
+    z-index: var(--z-sticky);
+    /* --color-surface-default, the role, not --color-neutral-0, the primitive
+       it resolves to. Same value; the category is the point, and CLAUDE.md's
+       "same primitive value is not same semantic meaning" section exists for
+       exactly this. Found by check:color-coverage once the background shorthand came into
+       its scope -- it had been invisible because the check counted
+       background-color: and this package almost never writes that. */
+    background: var(--color-surface-default);
+    border-bottom: var(--border-width-1) solid var(--color-border-container);
   }
 
   .inner {
-    max-width: 1200px;
-    margin-inline: auto;
     padding-block: var(--spacing-16);
-    padding-inline: var(--spacing-24);
     box-sizing: border-box;
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: var(--spacing-32);
+    /* The logo is a fixed 126px and the row could not give way, so on a 320px
+       screen the nav simply carried on past the edge. Letting the row wrap puts
+       the navigation under the brand when there is no room for both, and does
+       nothing at any width where they fit -- which is why there is no media
+       query here: the layout can tell when it has run out of room. */
+    flex-wrap: wrap;
+    gap: var(--spacing-16) var(--spacing-32);
   }
 
   .logo {
+      /* no role: a wordmark, not running text. Picking a text role for it would
+         assert a relationship to the type scale that a brand mark does not
+         have. The nearest role by value is heading-h6, which is a heading. */
     font-size: var(--typography-fontSize-lg);
+      /* no role: a wordmark, not running text. Picking a text role for it would
+         assert a relationship to the type scale that a brand mark does not
+         have. The nearest role by value is heading-h6, which is a heading. */
     font-weight: var(--typography-fontWeight-semibold);
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
   }
 
-  .logo span {
-    color: var(--color-blue-500);
-  }
+  /* No ".logo span" rule. .logo is the class this component puts on a
+     bd-ai-icon, and that element renders a single svg in its own shadow root --
+     there is no span for a descendant selector to reach, and it never matched
+     in 4 shadow roots across 556 stories. The mark colours itself from the
+     token in its own path fill. */
 
   nav {
     display: flex;
     align-items: center;
+    /* This row gap was already declared for two lines of links and could never
+       apply, because nothing was allowed to wrap. Now it can. */
+    flex-wrap: wrap;
     gap: var(--spacing-16) var(--spacing-32);
   }
 
+  /* .page-link is the class this component puts on a bd-link HOST, so it can
+     style the host's box and nothing inside it. The ink is bd-link's, and the
+     six colour declarations that used to stand here were all overridden by the
+     atom's own variant rules on the anchor one level down. Measured at 1440,
+     rest and hover, current and not, after the family review moved every item
+     to variant="primary":
+
+       not current, rest    --color-text-brand             rgb(0, 89, 214)
+       not current, hover   --color-action-primary-active   rgb(0, 69, 173)
+       current, rest        --color-text-primary            rgb(21, 23, 25), weight 700
+       current, hover       --color-text-primary            rgb(21, 23, 25), weight 700
+
+     The last row is the one that changed behaviour rather than value: the
+     current item used to turn blue under the pointer, because
+     .bd-link--primary:hover outweighed .bd-link--active. bd-link now declares
+     .bd-link--active:hover and it holds.
+
+     None of those was what this sheet declared: the host went to
+     --color-action-primary-hover on hover and no text ever read it, and the
+     semibold on .page-link.active lost to the atom's .bd-link--active bold.
+     What is left here is the box -- position, padding, the indicator -- and the
+     ink is asked for through the atom's API, which is where it renders. */
   .page-link {
     position: relative;
     text-decoration: none !important;
-    color: var(--color-neutral-900);
-    font-weight: var(--typography-fontWeight-normal);
-    padding: var(--spacing-10) var(--spacing-0);
     display: inline-block;
     font-size: var(--typography-body-regular-fontSize);
     font-family: var(--typography-body-regular-fontFamily);
-    transition: color var(--transition-duration-fast) var(--transition-easing-smooth);
   }
 
-  .page-link.active {
-    font-weight: var(--typography-fontWeight-semibold);
-    color: var(--color-neutral-900);
-  }
+  /* The padding belongs to the PART, not to the host.
 
-  .page-link:hover,
-  .page-link.bd-link--primary:hover {
-    color: var(--color-blue-500) !important;
-    text-decoration: none !important;
-  }
+     A host's padding does not extend the anchor inside it, so this rule used
+     to build a 44px-tall row around a 24px-tall target: measured 93x44 on the
+     host with a 93x24 <a> inside it, and elementsFromPoint 4px below the top
+     edge came back bd-page-switcher > bd-root > div with no <a> in the stack at
+     all. The top and bottom 10px of every item were dead, 45% of the height a
+     reader aims at.
 
-  .page-link.bd-link--secondary:hover {
-    color: var(--color-neutral-900) !important;
-    text-decoration: none !important;
-  }
+     It is also why the focus ring wrapped the glyphs rather than the item: the
+     ring is drawn on whatever element is focusable, and that was the 24px
+     anchor. One boundary, two symptoms.
 
-  .page-link.active:hover {
-    color: var(--color-neutral-900) !important;
+     bd-breadcrumb already fixed exactly this by moving its padding onto
+     ::part(link) -- its comment records a 343x40 row whose focusable anchor
+     was 43x24 -- and this is the same move. Layout is unchanged: the host has
+     no padding now but wraps an anchor that does, so it still measures 44px
+     and the indicator's offset still lands on the bar's bottom edge. */
+  .page-link::part(link) {
+    padding: var(--spacing-10) var(--spacing-0);
   }
 
+  /* The selected-item underline, through the role that names it. This was the
+     third spelling of the same line -- Components/Tab List and the anchor nav are
+     the two the --indicator-* comment already names -- and it is the one the
+     token comment says the role exists to end. Height, colour and duration
+     resolve to the same values it declared by hand; the easing does not, and
+     that drift is the reason the role was named.
+
+     The offset is the inner's padding-bottom, so the indicator lands on the
+     bar's bottom edge. This inner pads 16, and the 14 that stood here was
+     close enough to look right -- the indicator sat 2px shy of the edge --
+     which is how the number survived being copied into bd-anchor-nav, which
+     pads 10, and put the indicator outside that bar entirely.
+
+     Measured: link box bottom at 60, indicator was 71-74 against an inner
+     bottom edge of 76; now 73-76. */
   .page-link::after {
     content: "";
     position: absolute;
     left: var(--spacing-0);
-    bottom: calc(-1 * var(--spacing-14));
+    bottom: calc(-1 * var(--spacing-16));
     width: 0%;
-    height: var(--border-width-3);
-    background-color: var(--color-blue-500);
-    transition: width var(--transition-duration-slow) var(--transition-easing-ease-out);
+    height: var(--indicator-underline-height);
+    background-color: var(--indicator-color);
+    transition: width var(--indicator-underline-duration) var(--indicator-underline-easing);
   }
 
   .page-link.active::after {
     width: 100%;
   }
 
-  .page-link:focus-visible {
-    outline: var(--spacing-2) solid var(--bd-accesibility-focus);
-    outline-offset: var(--spacing-2);
-    border-radius: var(--space-2xs);
-  }
+  /* No .page-link:focus-visible rule. .page-link is the class this component
+     puts on a bd-link HOST, and the focusable anchor lives inside bd-link's own
+     shadow root -- measured: 2 .page-link elements, both bd-link, neither
+     focusable, each with its own shadow root. The rule that stood here could
+     never match, so the outline it declared, the misspelled
+     --bd-accesibility-focus alias behind it and the two spacing steps it used
+     as an outline width and offset never rendered at all. bd-link already
+     carries the one focus ring, verified here by keyboard. */
 
   @media (prefers-reduced-motion: reduce) {
     .page-link::after {

package/src/components/page-switcher/page-switcher.js

@@ -3,13 +3,37 @@ import { tokens } from "../../tokens/tokens.js";
 import "../icons/bd-ai-icon.js";
 import "../link/link.js";
 import { pageSwitcherStyles } from "./page-switcher.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
+/**
+ * The product-level page navigation: a brand mark and one link per page, with
+ * the page you are on marked.
+ *
+ * Two notes on the markup below, both measured rather than assumed.
+ *
+ * The ink is Position 2 of the wayfinding family review: colour means
+ * AVAILABLE and neutral means current. Every item is variant="primary", so a
+ * resting item is --color-text-brand and hovers to --color-action-primary-active;
+ * the current one carries `active`, which drops it to --color-text-primary at
+ * weight 700 and takes the 3px indicator. bd-link's new .bd-link--active:hover
+ * keeps it there under the pointer.
+ *
+ * The variant is no longer switched per item. It used to be primary for the
+ * current one and secondary for the rest, which made the current item the only
+ * blue one -- the inverse of what the indicator says -- and left the resting
+ * items on the muted ramp. One variant plus `active` is the same information
+ * with one fewer thing to keep in step.
+ *
+ * `aria-current` is `page`, not the generic `true`. These items are pages; the
+ * anchor nav's items are positions inside one page and say `location`. Both are
+ * current-location markers and they are not the same claim.
+ */
 class BdPageSwitcher extends LitElement {
   static properties = {
     items: { type: Array } // [{ title, href, active }]
   };
 
-  static styles = [tokens, pageSwitcherStyles];
+  static styles = [tokens, ensembleCSS, pageSwitcherStyles];
 
   constructor() {
     super();
@@ -18,18 +42,17 @@ class BdPageSwitcher extends LitElement {
 
   render() {
     return html`
-      <div class="inner">
+      <div class="bd-ensemble inner">
         <bd-ai-icon class="logo" width="200" height="24"></bd-ai-icon>
 
         <nav aria-label="Product navigation">
           ${this.items.map(({ title, href, active }) => html`
             <bd-link
               href=${href}
-              kind=${active ? "primary" : "secondary"}
+              variant="primary"
               no-underline
-              color="var(--color-neutral-900)"
               ?active=${active}
-              aria-current=${active ? "true" : nothing}
+              aria-current=${active ? "page" : nothing}
               class="page-link ${active ? "active" : ""}"
             >${title || nothing}</bd-link>
           `)}

package/src/components/page-switcher/page-switcher.stories.js

@@ -0,0 +1,95 @@
+import { html } from 'lit';
+import './page-switcher.js';
+
+export default {
+  title     : 'Components/Page Switcher',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Page Switcher** is the sticky product bar that carries the brand mark and a
+short set of sibling pages. One of them is current.
+
+\`\`\`html
+<bd-page-switcher
+  .items=\${[
+    { title: 'AI Guardian', href: '/ai-guardian', active: true },
+    { title: 'Skill Scanner', href: '/skill-scanner' }
+  ]}
+></bd-page-switcher>
+\`\`\`
+
+### Layout
+
+The brand mark is a fixed width and the row wraps when the two cannot sit side
+by side, which puts the navigation under the brand rather than off the side of
+the screen. There is no breakpoint involved: the row wraps when it runs out of
+room, so the same rule holds for a long label on a wide screen as for a short
+one on a narrow screen.
+
+Until P5D.1 the row could not wrap, and the component ran 22px off a 320px
+viewport. It had no story of its own, so the only place that was visible was
+inside a demo — which is why these stories exist.
+`
+      }
+    }
+  }
+};
+
+const ITEMS = [
+  { title: 'AI Guardian', href: '#ai-guardian', active: true },
+  { title: 'Skill Scanner', href: '#skill-scanner' }
+];
+
+const render = items => html`<bd-page-switcher .items=${items}></bd-page-switcher>`;
+
+export const Default = {
+  name      : 'Default',
+  render    : () => render(ITEMS),
+  parameters: {
+    docs: { description: { story: 'Brand and navigation on one row, which is what fits at any usual width.' } }
+  }
+};
+
+export const Narrow = {
+  name      : 'Narrow (320px)',
+  render    : () => render(ITEMS),
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+    docs    : {
+      description: {
+        story: 'The width the component used to overflow at. The row wraps instead, and nothing leaves the viewport.'
+      }
+    }
+  }
+};
+
+export const ThreePages = {
+  name  : 'Three pages',
+  render: () => render([
+    { title: 'AI Guardian', href: '#ai-guardian', active: true },
+    { title: 'Skill Scanner', href: '#skill-scanner' },
+    { title: 'Threat Map', href: '#threat-map' }
+  ]),
+  parameters: {
+    docs: { description: { story: 'More siblings than the demo carries, so the wrap is exercised earlier.' } }
+  }
+};
+
+export const LongLabels = {
+  name  : 'Long labels',
+  render: () => render([
+    { title: 'Bitdefender AI Guardian for Home', href: '#one', active: true },
+    { title: 'Agentic Skill Scanner and Report', href: '#two' }
+  ]),
+  parameters: {
+    docs: {
+      description: {
+        story: `Labels long enough to overflow a wide screen if the row could not give
+                way. This is the case a breakpoint would have missed, because the width
+                that matters is the content's, not the window's.`
+      }
+    }
+  }
+};

package/src/components/paragraph/paragraph.css.js

@@ -1,47 +1,52 @@
 import { css } from "lit";
 
 export default css`
+  /* --color-text-primary, not --color-neutral-1000. Body copy was set in pure
+     black while bd-display used neutral-900 and bd-li neutral-700, so a
+     heading, its paragraph and its list rendered in three different inks. The
+     line below the font-family used to carry the intended value as
+     a // prefix, which CSS does not treat as a comment — the parser dropped
+     it, and the pure black above won by default. */
   :host {
     display: block;
-    color: var(--bd-paragraph-color, var(--color-neutral-1000));
+    color: var(--bd-paragraph-color, var(--color-text-primary));
   }
 
   p {
     all: unset;
     display: block;
-    font-family: var(--typography-body-regular-fontFamily, var(--typography-fontFamily-sans));
-    // color: var(--color-neutral-900);
-    margin-bottom: var(--spacing-md);
+    font-family: var(--typography-body-regular-fontFamily);
+    margin-bottom: var(--spacing-16);
   }
 
   /* === Font Size Variants === */
-  :host([kind="large"]) p {
+  :host([variant="large"]) p {
     font-size: var(--typography-body-large-fontSize);
     font-weight: var(--typography-body-large-fontWeight);
     line-height: var(--typography-body-large-lineHeight);
     letter-spacing: var(--typography-body-large-letterSpacing);
   }
 
-  :host([kind="regular"]) p {
+  :host([variant="regular"]) p {
     font-size: var(--typography-body-regular-fontSize);
     font-weight: var(--typography-body-regular-fontWeight);
     line-height: var(--typography-body-regular-lineHeight);
     letter-spacing: var(--typography-body-regular-letterSpacing);
   }
 
-  :host([kind="small"]) p {
+  :host([variant="small"]) p {
     font-size: var(--typography-body-small-fontSize);
     font-weight: var(--typography-body-small-fontWeight);
     line-height: var(--typography-body-small-lineHeight);
     letter-spacing: var(--typography-body-small-letterSpacing);
   }
-  :host([kind="xsmall"]) p {
-    font-size: var(--typography-label-xsmall-fontSize);
+  :host([variant="xsmall"]) p {
+    font-size: var(--typography-body-xsmall-fontSize);
     font-weight: var(--typography-body-small-fontWeight);
     line-height: var(--typography-body-small-lineHeight);
     letter-spacing: var(--typography-body-small-letterSpacing);
   }
-  :host([kind="lead"]) p {
+  :host([variant="lead"]) p {
     font-size: var(--typography-body-lead-fontSize);
     font-weight: var(--typography-body-lead-fontWeight);
     line-height: var(--typography-body-lead-lineHeight);