@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/bento-grid/bento-grid.stories.js

@@ -1,4 +1,5 @@
 import { html } from "lit";
+import "../button/button.js";
 import "../icons/analysis-icon.js";
 import "../icons/arrow-up-icon.js";
 import "../icons/family-icon.js";
@@ -8,7 +9,7 @@ import "../icons/machine-learning-icon.js";
 import "./bento-grid.js";
 import "./bento-item.js";
 export default {
-  title     : "Components/Bento Grid",
+  title     : "Modules/Bento Grid",
   component : "bd-bento-grid",
   tags      : ["autodocs"],
   parameters: {
@@ -280,12 +281,12 @@ export const WithCTA = {
       <bd-bento-item title="AI Protection">
         <bd-individual-icon slot="icon" width="32" height="32" color="#006DFF"></bd-individual-icon>
         <bd-p>Powered by machine learning and behavioral analysis.</bd-p>
-        <bd-button-link href="#" kind="primary" size="sm">Learn more</bd-button-link>
+        <bd-button-link href="#" variant="primary" size="sm">Learn more</bd-button-link>
       </bd-bento-item>
       <bd-bento-item title="Multi-layer Security">
         <bd-globe-icon slot="icon" width="32" height="32" color="#006DFF"></bd-globe-icon>
         <bd-p>Multiple independent protection layers stop any attack.</bd-p>
-        <bd-button-link href="#" kind="primary" size="sm">Learn more</bd-button-link>
+        <bd-button-link href="#" variant="primary" size="sm">Learn more</bd-button-link>
       </bd-bento-item>
     </bd-bento-grid>
   `,
@@ -449,29 +450,29 @@ export const EqualColumns = {
       description="Each protection is structural: every request the agent routes through Bitdefender's MCP tools gets it automatically, with no setting to remember."
     >
       <bd-bento-item>
-        <span slot="icon" style="color: var(--color-blue-500, #006DFF); font-weight: 700; font-family: var(--typography-fontFamily-mono, monospace); font-size: 14px; letter-spacing: 0.05em;">01</span>
-        <bd-h as="h5" font-weight="700" style="margin: 0 0 8px;">IP masking</bd-h>
-        <bd-p color="var(--color-neutral-600)">When your agent reaches a site, it sees the VPN server's exit IP. Not your home address or IP-based location.</bd-p>
+        <span slot="icon" style="color: var(--color-blue-500); font-weight: 700; font-family: var(--typography-fontFamily-mono); font-size: 14px; letter-spacing: 0.05em;">01</span>
+        <bd-h as="h5" fontWeight="bold" style="margin: 0 0 8px;">IP masking</bd-h>
+        <bd-p color="muted">When your agent reaches a site, it sees the VPN server's exit IP. Not your home address or IP-based location.</bd-p>
       </bd-bento-item>
       <bd-bento-item>
-        <span slot="icon" style="color: var(--color-blue-500, #006DFF); font-weight: 700; font-family: var(--typography-fontFamily-mono, monospace); font-size: 14px; letter-spacing: 0.05em;">02</span>
-        <bd-h as="h5" font-weight="700" style="margin: 0 0 8px;">Per-prompt encryption</bd-h>
-        <bd-p color="var(--color-neutral-600)">Every request opens its own encrypted tunnel from your device to Bitdefender, so whoever runs the Wi-Fi you're on can't read what the agent sends.</bd-p>
+        <span slot="icon" style="color: var(--color-blue-500); font-weight: 700; font-family: var(--typography-fontFamily-mono); font-size: 14px; letter-spacing: 0.05em;">02</span>
+        <bd-h as="h5" fontWeight="bold" style="margin: 0 0 8px;">Per-prompt encryption</bd-h>
+        <bd-p color="muted">Every request opens its own encrypted tunnel from your device to Bitdefender, so whoever runs the Wi-Fi you're on can't read what the agent sends.</bd-p>
       </bd-bento-item>
       <bd-bento-item>
-        <span slot="icon" style="color: var(--color-blue-500, #006DFF); font-weight: 700; font-family: var(--typography-fontFamily-mono, monospace); font-size: 14px; letter-spacing: 0.05em;">03</span>
-        <bd-h as="h5" font-weight="700" style="margin: 0 0 8px;">Session isolation</bd-h>
-        <bd-p color="var(--color-neutral-600)">Each tunnel closes the moment the prompt ends. If a site sees two of your agent's requests, it has no network-level way to tell they came from the same prompt.</bd-p>
+        <span slot="icon" style="color: var(--color-blue-500); font-weight: 700; font-family: var(--typography-fontFamily-mono); font-size: 14px; letter-spacing: 0.05em;">03</span>
+        <bd-h as="h5" fontWeight="bold" style="margin: 0 0 8px;">Session isolation</bd-h>
+        <bd-p color="muted">Each tunnel closes the moment the prompt ends. If a site sees two of your agent's requests, it has no network-level way to tell they came from the same prompt.</bd-p>
       </bd-bento-item>
       <bd-bento-item>
-        <span slot="icon" style="color: var(--color-blue-500, #006DFF); font-weight: 700; font-family: var(--typography-fontFamily-mono, monospace); font-size: 14px; letter-spacing: 0.05em;">04</span>
-        <bd-h as="h5" font-weight="700" style="margin: 0 0 8px;">Clean-IP browsing</bd-h>
-        <bd-p color="var(--color-neutral-600)">Every request exits on the VPN server's IP rather than the same home address every time, useful for QA and monitoring work that needs a neutral, non-residential vantage point.</bd-p>
+        <span slot="icon" style="color: var(--color-blue-500); font-weight: 700; font-family: var(--typography-fontFamily-mono); font-size: 14px; letter-spacing: 0.05em;">04</span>
+        <bd-h as="h5" fontWeight="bold" style="margin: 0 0 8px;">Clean-IP browsing</bd-h>
+        <bd-p color="muted">Every request exits on the VPN server's IP rather than the same home address every time, useful for QA and monitoring work that needs a neutral, non-residential vantage point.</bd-p>
       </bd-bento-item>
       <bd-bento-item>
-        <span slot="icon" style="color: var(--color-blue-500, #006DFF); font-weight: 700; font-family: var(--typography-fontFamily-mono, monospace); font-size: 14px; letter-spacing: 0.05em;">05</span>
-        <bd-h as="h5" font-weight="700" style="margin: 0 0 8px;">Regional routing</bd-h>
-        <bd-p color="var(--color-neutral-600)">Need to see a page the way a visitor from a specific country would? Route that one request through a Bitdefender server there, just for that prompt.</bd-p>
+        <span slot="icon" style="color: var(--color-blue-500); font-weight: 700; font-family: var(--typography-fontFamily-mono); font-size: 14px; letter-spacing: 0.05em;">05</span>
+        <bd-h as="h5" fontWeight="bold" style="margin: 0 0 8px;">Regional routing</bd-h>
+        <bd-p color="muted">Need to see a page the way a visitor from a specific country would? Route that one request through a Bitdefender server there, just for that prompt.</bd-p>
       </bd-bento-item>
     </bd-bento-grid>
   `,

package/src/components/bento-grid/bento-item.css.js

@@ -1,17 +1,17 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
     height: 100%;
-    --background-card-grey: var(--color-neutral-25);
     box-sizing: border-box;
   }
 
   .bd-bentoitem-box {
-    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: stretch;
@@ -21,8 +21,21 @@ export default css`
     box-sizing: border-box;
     font-family: var(--typography-fontFamily-sans);
     min-width: 0;
-    transition: transform 0.25s ease, box-shadow 0.25s ease;
-    border: 1px solid var(--color-neutral-100);
+    /* The same hover lift as trust-panel, now at the same scale step. */
+    transition: transform var(--transition-duration-normal) var(--transition-easing-ease),
+      box-shadow var(--transition-duration-normal) var(--transition-easing-ease);
+    /* No edge. --color-surface-container is documented as "the ground of a
+       self-contained object -- a card, a tile, a panel -- one step off the page
+       so it reads as its own object WITHOUT needing a border or a shadow to say
+       so", and this card sits on the page ground, so the tonal step is the
+       separation and an edge is redundant with the role's own purpose.
+
+       The rule, from the cards-and-surfaces review: a card on the page ground
+       takes surface/container and no edge; a card on a tinted section takes
+       surface/default plus a 1px border/container, because there is no tonal
+       step available there and the edge earns its keep. Six components on the
+       page ground drew no edge; this one drew one, and five identical siblings
+       did not. See CLAUDE.md, "A card's ground and its edge". */
   }
 
 
@@ -31,6 +44,18 @@ transform: translateY(-3px);
 box-shadow: 0px 14px 40px #00000012;
 }
 
+  /* Same reasoning as trust-panel, checked separately: the shadow is the part
+     that communicates hover, the 3px is the part that moves. */
+  @media (prefers-reduced-motion: reduce) {
+    .bd-bentoitem-box {
+      transition: none;
+    }
+
+    .bd-bentoitem-box:hover {
+      transform: none;
+    }
+  }
+
   .bd-bentoitem-icon-wrap {
     display: flex;
     flex-direction: column;
@@ -54,16 +79,15 @@ box-shadow: 0px 14px 40px #00000012;
   .bd-bentoitem-title-wrap {
     display: flex;
     align-items: flex-start;
-    gap: var(--spacing-4, 4px);
+    gap: var(--spacing-4);
     overflow: hidden;
     margin-bottom: var(--spacing-8);
     width: 100%;
   }
 
   .bd-bentoitem-body {
-    font-size: var(--spacing-16);
     margin: 0 0 1em 0;
-    color: var(--color-neutral-700, inherit);
+    color: var(--color-text-secondary);
     width: 100%;
   }
 
@@ -71,37 +95,37 @@ box-shadow: 0px 14px 40px #00000012;
     width: 100%;
   }
 
-  /* === TONE VARIANTS === */
-
-  :host([tone="tint"]) {
-    --background-card-grey: var(--color-blue-50);
-  }
-
+  /* === TONE VARIANTS ===
+     The card has no edge (see .bd-bentoitem-box), so a tone is the fill
+     alone. */
   :host([tone="tint"]) .bd-bentoitem-box {
-    border-color: var(--color-blue-50);
-  }
-
-  :host([tone="dark"]) {
-    --background-card-grey: linear-gradient(160deg, var(--color-neutral-800) 0%, var(--color-blue-950) 130%);
-;
+    background: var(--status-brand-surface);
   }
 
   :host([tone="dark"]) .bd-bentoitem-box {
-    border-color: linear-gradient(160deg, var(--color-neutral-800) 0%, var(--color-blue-950) 130%);
-;
+    /* The inverse ground the card's inverse ink is written for, running into
+       the brand's darkest blue.
+       no role: blue-950 is a gradient's far stop, decoration rather than a
+       ground any text is measured against -- the same stop bd-cta-banner ends on. */
+    background: linear-gradient(160deg, var(--color-surface-inverse) 0%, var(--color-blue-950) 130%);
   }
 
   :host([tone="dark"]) .bd-bentoitem-title-wrap bd-h {
-    color: var(--color-neutral-0);
+    color: var(--color-text-inverse);
   }
 
   :host([tone="dark"]) .bd-bentoitem-body {
-    --bd-paragraph-color: var(--color-neutral-0);
+    color: var(--color-text-inverse);
   }
 
-  @media (max-width: 599px) {
+  /* below('md'), not below('sm'). The Comparison Panel and the Trust Panel both
+     take the compact inset at md and this took it at sm, so the same card was
+     affording 32px at 600px wide in one component and not in another. Two of
+     the three picked md; this one moved. Visible: the inset steps down 192px
+     of viewport earlier than it used to. */
+  @media ${unsafeCSS(below('md'))} {
     .bd-bentoitem-box {
-      padding: var(--spacing-24);
+      padding: var(--card-padding-compact);
     }
   }
 `;

package/src/components/bento-grid/bento-item.js

@@ -39,13 +39,13 @@ class BentoItem extends LitElement {
         ${this.title
           ? html`
               <div class="bd-bentoitem-title-wrap">
-                <bd-h as="h5" fontWeight="700">${this.title}</bd-h>
+                <bd-h as="h5" fontWeight="bold">${this.title}</bd-h>
               </div>
             `
           : ""}
 
         ${this.body
-          ? html`<bd-p kind="regular" class="bd-bentoitem-body">${this.body}</bd-p>`
+          ? html`<bd-p variant="regular" class="bd-bentoitem-body">${this.body}</bd-p>`
           : ""}
 
         <slot></slot>

package/src/components/blockquote/blockquote.css.js

@@ -0,0 +1,47 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const blockquoteCSS = css`
+  :host { display: block; }
+
+  blockquote {
+    margin: 0;
+    padding-left: var(--spacing-16);
+    border-left: var(--border-width-4) solid var(--color-border-brand);
+    font-family: var(--typography-body-large-fontFamily);
+    font-size: var(--typography-body-large-fontSize);
+    font-weight: var(--typography-body-large-fontWeight);
+    line-height: var(--typography-body-large-lineHeight);
+    color: var(--color-text-primary);
+  }
+
+  footer {
+    margin-top: var(--spacing-8);
+    font-size: var(--typography-caption-default-fontSize);
+    /* no role: two roles are each a near-miss, from opposite directions, and
+       no declared role sits at the intersection of this size, this weight,
+       this leading and this colour.
+       .
+       label-small matches this text's size and weight exactly -- but adopting
+       it would add letterSpacing-wide, which has no job on mixed-case sentence
+       text because nothing here crowds, and would replace the 1.625 leading
+       this inherits from the quote it attributes with 1.5. That inherited
+       rhythm is the one thing in this rule that means something: the credit
+       line sits on the same measure as the quotation it belongs to, where 1.5
+       merely comes attached to the role.
+       .
+       caption-default matches this text's size and colour exactly -- the same
+       --color-text-muted token, not just the same value, so this rule already
+       half-resolves through it. But its weight is normal, and normal is what
+       the quote itself renders. Adopting it would remove the attribution's
+       only distinguishing signal and demote a credit line to what reads as a
+       continuation of the quotation rather than a citation of it.
+       .
+       Neither disagreement is drift; both are the reason this rule exists as
+       written. So the weight stays a primitive and says why. */
+    font-weight: var(--typography-fontWeight-medium);
+    color: var(--color-text-muted);
+  }
+`;
+
+export default blockquoteCSS;

package/src/components/blockquote/blockquote.js

@@ -0,0 +1,29 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { blockquoteCSS } from './blockquote.css.js';
+
+export class BdBlockquote extends LitElement {
+  static styles = [blockquoteCSS];
+
+  static properties = {
+    cite       : { type: String },
+    attribution: { type: String }
+  };
+
+  constructor() {
+    super();
+    this.cite = '';
+    this.attribution = '';
+  }
+
+  render() {
+    return html`
+      <blockquote cite=${this.cite || nothing}>
+        <slot></slot>${this.attribution ? html`<footer>\u2014 ${this.attribution}</footer>` : nothing}
+      </blockquote>
+    `;
+  }
+}
+
+customElements.define('bd-blockquote', BdBlockquote);

package/src/components/blockquote/blockquote.stories.js

@@ -0,0 +1,62 @@
+import { html } from 'lit';
+import './blockquote.js';
+
+export default {
+  title     : 'Atoms/Blockquote',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdBlockquote** is a quotation set apart from the surrounding prose, with an
+optional attribution.
+
+### Usage
+\`\`\`html
+<bd-blockquote>The best way to predict the future is to invent it.</bd-blockquote>
+
+<bd-blockquote
+  attribution="Alan Kay"
+  cite="https://example.com/source"
+>The best way to predict the future is to invent it.</bd-blockquote>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`attribution\` | who said it — omit for an unattributed quote | \`''\` |
+| \`cite\` | URL of the source | \`''\` |
+
+### Notes
+\`attribution\` renders as a \`<footer>\` inside the \`<blockquote>\`, prefixed with
+an em dash. That is the pairing the HTML spec recommends for a credit that
+belongs to the quote itself.
+
+\`cite\` maps to the native \`cite\` attribute. It is **metadata only** — browsers
+do not render it and it is not a link, so if the source should be visible or
+clickable, put it in \`attribution\` or in the slotted content.
+        `
+      }
+    }
+  },
+  argTypes: {
+    attribution: {
+      control    : 'text',
+      description: 'Who said it. Renders as a footer inside the blockquote, prefixed with an em dash.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    },
+    cite: {
+      control    : 'text',
+      description: 'Source URL for the native cite attribute. Metadata only — not rendered, not a link.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    }
+  }
+};
+
+export const Default = () => html`
+    <bd-blockquote>Protection has to keep pace, quietly.</bd-blockquote>
+  `;
+
+export const Withattribution = () => html`
+    <bd-blockquote attribution="Bitdefender Labs">Threats move faster than annual reviews.</bd-blockquote>
+  `;

package/src/components/breadcrumb/breadcrumb.css.js

@@ -26,7 +26,12 @@ export default css`
       flex-direction: row;
     }
 
-    .bd-breadcrumb--horizontal .bd-breadcrumb-item:not(:last-child) {
+    /* Parent-owned layout, so it is spelled against the slotted hosts. The
+       rule this replaces targeted .bd-breadcrumb-item, which lives inside the
+       item's own shadow root: the descendant combinator could not reach it,
+       and :not(:last-child) could not have helped anyway, since that div is
+       the only child of its root and so is always the last one. */
+    .bd-breadcrumb--horizontal ::slotted(bd-breadcrumb-item:not(:last-child)) {
       margin-right: var(--spacing-8);
     }
 
@@ -34,11 +39,26 @@ export default css`
     .bd-breadcrumb__divider {
       margin-left: var(--spacing-8);
       margin-right: var(--spacing-8);
-      color: var(--color-neutral-400);
+      /* the "/" is rendered text and is not aria-hidden, so it needs 4.5:1;
+         neutral-400 gave 3.23 */
+      color: var(--color-text-subtle);
+    /* no role: the "/" is real rendered text -- see the contrast note above on
+       why it is not aria-hidden -- but it is a single glyph in a fixed-height
+       divider, the same category as the icon-only line box rule 7 already
+       covers for its leading. Sizing a separator is not a text role. */
       font-size: var(--typography-fontSize-sm);
-      line-height: 1;
+      line-height: var(--typography-lineHeight-none);
     }
 
+    /* Vertical layout.
+
+       The four rules below are spelled :host([orientation]) rather than as
+       descendants of .bd-breadcrumb--vertical. That class sits on the nav in
+       bd-breadcrumb's shadow root, while every element they style lives in
+       bd-breadcrumb-item's, so as descendant selectors they matched nothing:
+       measured at 375px, dividers stayed display block and items had no
+       padding and no background. bd-breadcrumb now reflects its orientation
+       onto each item, which is what these selectors read. */
     /* Vertical layout */
     .bd-breadcrumb--vertical .bd-breadcrumb__items {
       flex-direction: column;
@@ -46,7 +66,7 @@ export default css`
       gap: var(--spacing-4);
     }
 
-    .bd-breadcrumb--vertical .bd-breadcrumb__divider {
+    :host([orientation="vertical"]) .bd-breadcrumb__divider {
       display: none;
     }
 
@@ -58,41 +78,91 @@ export default css`
       color: inherit;
     }
 
-    /* Link styles */
+    /* Link styles.
+
+       The ink is bd-link's, and the two colours declared here were not the ones
+       that rendered. Measured at 1440: resting text rgb(0, 89, 214) and hovered
+       text rgb(0, 69, 173), both from the atom's own .bd-link--primary rules --
+       --color-text-brand and --color-action-primary-hover's next step,
+       --color-action-primary-active. The --color-blue-400 that stood here never
+       reached any text, which is the only reason it never showed as a failure:
+       it is 3.02:1 on white. The --color-blue-700 hover was the same value the
+       role already resolves to, spelled a second time by hand.
+
+       That answers the question P5H.1 left open about this hover. It is neither
+       a navigation-specific state nor a responsibility the token system is
+       missing: the action ramp already renders it, and 8.56:1 is what
+       --color-action-primary-active measures, not what a local choice bought.
+
+       The underline is the state cue that was missing. It was declared on the
+       host, and a host's text-decoration does not propagate into an
+       inline-flex anchor, so hover was colour alone -- 7.0:1 to 8.6:1, a change
+       a reader is not required to be able to see. It is now on the part that
+       holds the text. */
     bd-link.bd-breadcrumb__item {
-      color: var(--color-blue-400);
       text-decoration: none;
-      transition: all 0.15s ease-in-out;
+      transition: all var(--transition-duration-fast) var(--transition-easing-smooth);
     }
 
-    bd-link.bd-breadcrumb__item:hover {
-      color: var(--color-blue-700);
+    bd-link.bd-breadcrumb__item:hover::part(link) {
       text-decoration: underline;
-      text-underline-offset: 2px;
     }
 
-    /* Vertical item styles */
-    .bd-breadcrumb--vertical .bd-breadcrumb__item {
+    /* Vertical item styles.
+
+       The pill is the target here, so the padding goes on the part rather than
+       on the host. Measured before: a 343x40 row whose focusable anchor was
+       43x24, because the padding was on the bd-link host and the anchor inside
+       stayed the width of its own text -- 7.5% of the area a finger aims at,
+       and a focus ring that hugged the text inside a large grey box. The
+       background and the corner stay on the host, which is the box that draws
+       them; only the padding moves to where the target is. */
+    :host([orientation="vertical"]) .bd-breadcrumb__item {
+      background: var(--color-surface-subtle);
+      border-radius: var(--radius-sm);
+      width: 100%;
+    }
+
+    :host([orientation="vertical"]) span.bd-breadcrumb__item {
+      padding: var(--spacing-8) var(--spacing-12);
+    }
+
+    :host([orientation="vertical"]) bd-link.bd-breadcrumb__item::part(link) {
       padding: var(--spacing-8) var(--spacing-12);
-      background: var(--color-neutral-50);
-      border-radius: var(--spacing-4);
       width: 100%;
+      box-sizing: border-box;
     }
 
-    .bd-breadcrumb--vertical bd-link.bd-breadcrumb__item:hover {
-      background: var(--color-neutral-100);
+    :host([orientation="vertical"]) bd-link.bd-breadcrumb__item:hover {
+      background: var(--color-surface-muted);
+    }
+
+    :host([orientation="vertical"]) bd-link.bd-breadcrumb__item:hover::part(link) {
       text-decoration: none;
     }
 
-    /* Current item styles */
+    /* Current item styles.
+
+       No colour and no weight here. Both were declared on this span and both
+       lost to bd-p's own paragraph rule one level down -- the colour by
+       coincidence, since --color-text-primary is what bd-p sets anyway, and the
+       weight not at all. The weight is asked for through bd-p's font-weight
+       prop in breadcrumb.js, which is the only place it renders. */
     .bd-breadcrumb__item--current {
-      color: var(--color-neutral-900);
-      font-weight: var(--typography-fontWeight-medium);
       cursor: default;
     }
 
-    .bd-breadcrumb--vertical .bd-breadcrumb__item--current {
-      background: var(--color-neutral-100);
+    :host([orientation="vertical"]) .bd-breadcrumb__item--current {
+      background: var(--color-surface-muted);
+    }
+  }
+
+  /* A reader who asked for less motion was still getting the item hover. Twenty-three
+     of the thirty animated directories in this package honour the query; this
+     one did not. */
+  @media (prefers-reduced-motion: reduce) {
+    bd-link.bd-breadcrumb__item {
+      transition: none;
     }
   }
-`;
+`;