@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/paragraph/paragraph.js

@@ -1,10 +1,19 @@
 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 {
+  spacing, spacingShorthand, fontFamily, fontWeight, fontSize, letterSpacing, color
+} from "../shared/token-scales.js";
 import paragraphCSS from "./paragraph.css.js";
 
+/** The five body roles the stylesheet carries. */
+const VARIANTS = ["xsmall", "small", "regular", "large", "lead"];
+
 export class BdP extends LitElement {
   static properties = {
-    kind         : { type: String, reflect: true },
+    variant      : { type: String, reflect: true },
+    /** @deprecated pass `variant`. */
+    kind         : { type: String },
     padding      : { type: String },
     paddingBottom: { type: String },
     paddingTop   : { type: String },
@@ -17,7 +26,8 @@ export class BdP extends LitElement {
 
   constructor() {
     super();
-    this.kind = "regular";
+    this.variant = "regular";
+    this.kind = "";
     this.padding = "";
     this.paddingBottom = "";
     this.paddingTop = "";
@@ -28,58 +38,45 @@ export class BdP extends LitElement {
     this.color = "";
   }
 
-  _getKindClass() {
-    switch (this.kind) {
-      case "small":
-        return "bd-paragraph--small";
-      case "regular":
-        return "bd-paragraph--regular";
-      case "large":
-        return "bd-paragraph--large";
-      default:
-        return "bd-paragraph--regular";
-    }
-  }
-
-  // Same validation as bd-h's _getValidColor — only accepts CSS token
-  // references or real colour syntax, so a typo or stray text never lands
-  // in the inline style attribute as literal (and potentially unsafe) CSS.
-  _getValidColor(color) {
-    if (!color) return "";
-    if (
-      color.startsWith("var(") ||
-      color.startsWith("#") ||
-      color.startsWith("rgb") ||
-      color.startsWith("hsl")
-    ) {
-      return color;
+  willUpdate(changed) {
+    if (changed.has("kind") && this.kind) this.variant = this.kind;
+    if (changed.has("variant") || changed.has("kind")) {
+      if (!VARIANTS.includes(this.variant)) this.variant = "regular";
     }
-    return "";
   }
 
   render() {
-    const styles = [];
-    if (this.padding) styles.push(`padding: ${this.padding};`);
-    if (this.paddingBottom) styles.push(`padding-bottom: ${this.paddingBottom};`);
-    if (this.paddingTop) styles.push(`padding-top: ${this.paddingTop};`);
-    if (this.fontFamily) styles.push(`font-family: ${this.fontFamily};`);
-    if (this.fontWeight) styles.push(`font-weight: ${this.fontWeight};`);
-    if (this.fontSize) styles.push(`font-size: ${this.fontSize};`);
-    if (this.letterSpacing) styles.push(`letter-spacing: ${this.letterSpacing};`);
-
-    const validColor = this._getValidColor(this.color);
-    if (validColor) styles.push(`color: ${validColor};`);
-
-    const kindClass = this._getKindClass();
+    // Step names, resolved to token references by shared/token-scales.js. The
+    // three spacing props took raw CSS lengths before, which is the one thing
+    // the foundation rule forbids.
+    //
+    // fontFamily and fontWeight were declared here and in the manifest and
+    // then never applied — every value passed to them was silently dropped,
+    // so bd-terminal-message asked four paragraphs for mono and got sans.
+    // They resolve through the same closed sets as everything else, so
+    // font-family takes "sans" or "mono" rather than a CSS font stack.
+    //
+    // fontSize, letterSpacing and color arrived from main as raw CSS; they take
+    // a font-size step, a letter-spacing step and a COLOR_ROLES name.
+    const styles = [
+      ["padding",        spacingShorthand(this.padding)],
+      ["padding-bottom", spacing(this.paddingBottom)],
+      ["padding-top",    spacing(this.paddingTop)],
+      ["font-family",    fontFamily(this.fontFamily)],
+      ["font-weight",    fontWeight(this.fontWeight)],
+      ["font-size",      fontSize(this.fontSize)],
+      ["letter-spacing", letterSpacing(this.letterSpacing)],
+      ["color",          color(this.color)]
+    ].filter(([, v]) => v).map(([prop, v]) => `${prop}: ${v};`);
 
     return html`
-      <p class="bd-paragraph ${kindClass}" style="${styles.join(' ')}">
+      <p class="bd-paragraph" style="${styles.join(' ')}">
         <slot></slot>
       </p>
     `;
   }
 
-  static styles = [tokens, paragraphCSS];
+  static styles = [paragraphCSS];
 }
 
 customElements.define("bd-p", BdP);

package/src/components/paragraph/paragraph.stories.js

@@ -2,29 +2,45 @@ import { html } from 'lit';
 import './paragraph.js';
 
 export default {
-  title     : 'Components/Paragraph',
+  title     : 'Atoms/Paragraph',
   tags      : ['autodocs'],
   parameters: {
     docs: {
       description: {
         component: `
-**BdP** is a Lit paragraph component that renders a \`<p>\` tag with kind-based typography styling.
+**BdP** is a Lit paragraph component that renders a \`<p>\` tag with variant-based typography styling.
 
 ### Usage
 \`\`\`html
-<bd-p kind="large">Large paragraph text</bd-p>
-<bd-p kind="regular">Regular body text</bd-p>
-<bd-p kind="small">Small supporting text</bd-p>
+<bd-p variant="large">Large paragraph text</bd-p>
+<bd-p variant="regular">Regular body text</bd-p>
+<bd-p variant="small">Small supporting text</bd-p>
 \`\`\`
 
 ### Kind Values
-The \`kind\` attribute is reflected and used as a CSS selector for typography styling:
+The \`variant\` attribute is reflected and used as a CSS selector for typography styling:
 | Kind | Use case |
 |---|---|
 | \`large\` | Lead text, intro paragraphs |
 | \`regular\` | Default body text |
 | \`small\` | Captions, disclaimers, supporting text |
 
+### Spacing
+\`padding\`, \`paddingBottom\` and \`paddingTop\` take **spacing step names, not
+CSS lengths**:
+
+\`\`\`html
+<bd-p paddingBottom="16">Body text with 16px below.</bd-p>
+<bd-p padding="12 0">Twelve above and below, none at the sides.</bd-p>
+\`\`\`
+
+Each step resolves to \`var(--spacing-N)\`. \`padding\` accepts one to four steps
+as a shorthand, and if any part is off the scale the whole value is dropped
+rather than half-applied. Passing \`16px\` does nothing.
+
+Reach for these sparingly — spacing between paragraphs usually belongs to the
+layout around them, not to the paragraph itself.
+
 ### Notes
 - Content is passed via \`<slot>\`
 - Supports rich HTML content inside the slot (strong, em, a, etc.)
@@ -33,11 +49,30 @@ The \`kind\` attribute is reflected and used as a CSS selector for typography st
     }
   },
   argTypes: {
-    kind: {
+    variant: {
       control    : { type: 'select' },
       options    : ['large', 'regular', 'small'],
       description: 'Typography size variant, reflected as an attribute for CSS targeting',
       table      : { type: { summary: "'large'|'regular'|'small'" }, defaultValue: { summary: 'regular' }, category: 'Appearance' }
+    },
+    padding: {
+      control    : 'text',
+      description: 'One to four spacing steps, e.g. `12 0`. Each part resolves to `var(--spacing-N)`; if any part is off the scale the whole value is dropped.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Spacing' }
+    },
+    paddingBottom: {
+      control: { type: 'select' },
+      options: ['', '0', '1', '2', '4', '6', '8', '10', '12', '14', '16', '18', '20', '22', '24',
+        '28', '32', '36', '40', '44', '48', '52', '56', '64', '80', '96', '112', '128'],
+      description: 'A spacing step. Resolves to `var(--spacing-N)`.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Spacing' }
+    },
+    paddingTop: {
+      control: { type: 'select' },
+      options: ['', '0', '1', '2', '4', '6', '8', '10', '12', '14', '16', '18', '20', '22', '24',
+        '28', '32', '36', '40', '44', '48', '52', '56', '64', '80', '96', '112', '128'],
+      description: 'A spacing step. Resolves to `var(--spacing-N)`.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Spacing' }
     }
   }
 };
@@ -48,7 +83,7 @@ const sampleText = 'Bitdefender delivers award-winning cybersecurity to over 500
 
 export const Default = {
   name      : 'Default (Regular)',
-  render    : () => html`<bd-p kind="regular">${sampleText}</bd-p>`,
+  render    : () => html`<bd-p variant="regular">${sampleText}</bd-p>`,
   parameters: { docs: { description: { story: 'Default regular paragraph.' } } }
 };
 
@@ -56,30 +91,30 @@ export const AllKinds = {
   name  : 'All Kinds',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:16px;">
-      <bd-p kind="large">${sampleText}</bd-p>
-      <bd-p kind="regular">${sampleText}</bd-p>
-      <bd-p kind="small">${sampleText}</bd-p>
+      <bd-p variant="large">${sampleText}</bd-p>
+      <bd-p variant="regular">${sampleText}</bd-p>
+      <bd-p variant="small">${sampleText}</bd-p>
     </div>
   `,
-  parameters: { docs: { description: { story: 'All three kind values stacked for typographic scale comparison: large, regular, small.' } } }
+  parameters: { docs: { description: { story: 'All three variant values stacked for typographic scale comparison: large, regular, small.' } } }
 };
 
 export const LargeKind = {
   name      : 'Kind — Large',
-  render    : () => html`<bd-p kind="large">${sampleText}</bd-p>`,
+  render    : () => html`<bd-p variant="large">${sampleText}</bd-p>`,
   parameters: { docs: { description: { story: 'Large paragraph — suited for lead or intro text.' } } }
 };
 
 export const SmallKind = {
   name      : 'Kind — Small',
-  render    : () => html`<bd-p kind="small">${sampleText}</bd-p>`,
+  render    : () => html`<bd-p variant="small">${sampleText}</bd-p>`,
   parameters: { docs: { description: { story: 'Small paragraph — suited for captions, disclaimers, and supporting text.' } } }
 };
 
 export const RichContent = {
   name  : 'Rich Slotted Content',
   render: () => html`
-    <bd-p kind="regular">
+    <bd-p variant="regular">
       Protect your devices with <strong>award-winning</strong> security.
       Visit our <a href="/products">products page</a> or <em>contact us</em> for more info.
     </bd-p>
@@ -90,21 +125,21 @@ export const RichContent = {
 export const Disclaimer = {
   name  : 'Disclaimer Use Case',
   render: () => html`
-    <bd-p kind="small">
+    <bd-p variant="small">
       Protection for 1 account & 5 PCs, Macs, tablets, or smartphones.
       Windows® | macOS® | Android™ | iOS®
     </bd-p>
   `,
-  parameters: { docs: { description: { story: 'Small kind used as a product disclaimer below pricing or CTA buttons.' } } }
+  parameters: { docs: { description: { story: 'Small variant used as a product disclaimer below pricing or CTA buttons.' } } }
 };
 
 export const MultiParagraph = {
   name  : 'Multiple Paragraphs',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:12px;">
-      <bd-p kind="large">Complete protection for your digital life.</bd-p>
-      <bd-p kind="regular">Bitdefender Total Security combines award-winning antivirus protection with advanced features including VPN, parental controls, and identity protection.</bd-p>
-      <bd-p kind="small">Available on Windows, macOS, Android, and iOS. Subscription required.</bd-p>
+      <bd-p variant="large">Complete protection for your digital life.</bd-p>
+      <bd-p variant="regular">Bitdefender Total Security combines award-winning antivirus protection with advanced features including VPN, parental controls, and identity protection.</bd-p>
+      <bd-p variant="small">Available on Windows, macOS, Android, and iOS. Subscription required.</bd-p>
     </div>
   `,
   parameters: { docs: { description: { story: 'Three paragraphs of different kinds used together as a typical content block.' } } }
@@ -113,6 +148,6 @@ export const MultiParagraph = {
 export const Playground = {
   name      : '🛝 Playground',
   args      : { kind: 'regular' },
-  render    : (args) => html`<bd-p kind="${args.kind}">${sampleText}</bd-p>`,
+  render    : (args) => html`<bd-p variant="${args.kind}">${sampleText}</bd-p>`,
   parameters: { docs: { description: { story: 'Interactive playground. Switch between large, regular, and small via Controls.' } } }
 };

package/src/components/picture/picture.css.js

@@ -37,23 +37,35 @@ export default css`
 
     /* Radius Classes */
     .bd-picture.radius-none img {
-      border-radius: 0;
+      border-radius: var(--radius-none);
     }
 
     .bd-picture.radius-sm img {
-      border-radius: var(--radius-sm, 0.25rem);
+      border-radius: var(--radius-sm);
     }
 
     .bd-picture.radius-md img {
-      border-radius: var(--radius-md, 0.5rem);
+      border-radius: var(--radius-md);
     }
 
     .bd-picture.radius-lg img {
-      border-radius: var(--radius-lg, 0.75rem);
+      border-radius: var(--radius-lg);
+    }
+
+    .bd-picture.radius-xl img {
+      border-radius: var(--radius-xl);
+    }
+
+    .bd-picture.radius-2xl img {
+      border-radius: var(--radius-2xl);
+    }
+
+    .bd-picture.radius-3xl img {
+      border-radius: var(--radius-3xl);
     }
 
     .bd-picture.radius-full img {
-      border-radius: 50%;
+      border-radius: var(--radius-full);
     }
 
     /* Responsive Behavior */
@@ -97,31 +109,84 @@ export default css`
       object-fit: cover;
     }
 
-    /* Focus styles for accessibility */
     .bd-picture:focus-within {
-      outline: 2px solid var(--color-primary-500, #3b82f6);
-      outline-offset: 2px;
-      border-radius: 2px;
-    }
-
-    /* Loading state */
+      /* the one focus ring — see Foundations/Focus */
+      outline: none;
+      box-shadow: var(--focus-outline-primary);
+      border-radius: var(--focus-outline-radius);
+    }
+
+    /* Loading state.
+
+       The label overlays the reserved box instead of sitting beside the image
+       in it. This rule used to be display: flex with the ::before as a flex
+       sibling of the <img>, so the placeholder's width came out as the label's
+       width plus the image's -- measured, with each story served an image at
+       its own declared size, the box was exactly 84px too wide every time:
+
+         declared 200x150  ->  placeholder 284x150   (Fit Variants)
+         declared 180x180  ->  placeholder 264x180   (Radius Variants)
+         declared 300x200  ->  placeholder 384x200   (Lazy vs Eager)
+
+       84px is the rendered width of "Loading image" at
+       --typography-fontSize-sm. So the placeholder reserved a box the shape of
+       its own sentence rather than the shape of the image about to arrive, and
+       every image narrower than the label jumped left when it loaded: CLS
+       0.0188, 0.0370 and 0.0049 for those three stories. The two stories whose
+       images fill the row measured 0.0000, because max-width: 100% pinned both
+       states to the same width and hid the flaw.
+
+       This was unreachable until the [loaded] flag in picture.js started being
+       set: with the reveal permanently stuck at opacity 0 the image never
+       appeared, so nothing ever moved. Taking the label out of flow is what
+       keeps that fix from trading an invisible image for a visible jump.
+
+       position: absolute on the ::before leaves the <img> -- which carries the
+       declared width and height attributes, and therefore an intrinsic box
+       before any bytes arrive -- as the only thing sizing the placeholder. */
     .bd-picture:not([loaded]) {
-      background-color: var(--color-neutral-100, #f3f4f6);
+      position: relative;
+      background-color: var(--color-surface-muted);
+      /* no token: the dimension scale stops at 64px */
       min-height: 100px;
+      /* --color-text-muted, not --color-text-disabled. Loading is not disabled,
+         and the difference is not academic: the disabled text role carries a
+         contrast exemption -- WCAG 1.4.3 excuses disabled controls from the
+         4.5:1 minimum -- and this label claims that exemption without being
+         entitled to it. It is a sentence a reader is meant to read while they
+         wait.
+
+         Measured on this ground: neutral-400 on neutral-100 is 2.51:1, which
+         misses even the 3:1 floor for non-text. --color-text-muted is
+         neutral-600 at 5.12:1 and is the role this package already uses for
+         low-emphasis readable text -- caption and form help text both resolve
+         to it.
+
+         The ground stays --color-surface-muted. Loading is a state, muted is
+         the state surface, and bd-skeleton -- the package's other loading
+         affordance -- already sits on it. Only the ink was choosing by value.
+         See "Choosing a semantic role" in the package README. */
+      color: var(--color-text-muted);
+    }
+
+    /* One sentence for this state, shared with bd-img, and a local property
+       rather than a string in the stylesheet so it can be translated. */
+    .bd-picture:not([loaded])::before {
+      content: var(--bd-img-loading-label, "Loading image");
+      /* no role: the pre-load placeholder -- a glyph/marker/placeholder box, not running
+         prose. See list-item.css.js's .bd-list-item-marker::before for the
+         argument. */
+      font-size: var(--typography-fontSize-sm);
+      position: absolute;
+      inset: var(--spacing-0);
       display: flex;
       align-items: center;
       justify-content: center;
-      color: var(--color-neutral-400, #9ca3af);
-    }
-
-    .bd-picture:not([loaded])::before {
-      content: "Loading image...";
-      font-size: var(--text-sm, 0.875rem);
     }
 
     /* Smooth transitions */
     .bd-picture img {
-      transition: opacity 0.3s ease, transform 0.3s ease;
+      transition: opacity var(--transition-duration-slow) var(--transition-easing-smooth), transform var(--transition-duration-slow) var(--transition-easing-smooth);
     }
 
     .bd-picture img[loading="lazy"] {
@@ -141,7 +206,7 @@ export default css`
 
     .bd-picture.hover-lift:hover {
       transform: translateY(-2px);
-      transition: transform 0.3s ease;
+      transition: transform var(--transition-duration-slow) var(--transition-easing-smooth);
     }
 
     /* Performance optimizations */
@@ -149,20 +214,15 @@ export default css`
       will-change: transform, opacity;
     }
 
-    /* Responsive width utilities */
-    @container (max-width: 480px) {
-      .bd-picture.mobile-full {
-        width: 100vw;
-        margin-left: -1rem;
-        margin-right: -1rem;
-      }
-    }
+    /* Two @container queries used to sit here, for .mobile-full and
+       .tablet-optimized. Neither could ever match: a container query needs an
+       ancestor with container-type, and nothing in this component or around it
+       declares one, so both rules were dead the day they were written. Nothing
+       else in the package referenced .mobile-full or .tablet-optimized either,
+       so the rules went and there was nothing else to remove.
 
-    @container (max-width: 768px) {
-      .bd-picture.tablet-optimized img {
-        object-fit: contain;
-      }
-    }
+       If this comes back, the wrapper needs container-type: inline-size and
+       the 480px value needs to be on the breakpoint scale, which it was not. */
 
     /* Print styles */
     @media print {
@@ -171,15 +231,15 @@ export default css`
       }
       
       .bd-picture img {
-        max-width: 100% !important;
-        height: auto !important;
+        max-width: 100%;
+        height: auto;
       }
     }
 
     /* High contrast mode support */
     @media (prefers-contrast: high) {
       .bd-picture img {
-        border: 1px solid currentColor;
+        border: var(--border-width-1) solid currentColor;
       }
     }
 
@@ -198,12 +258,11 @@ export default css`
       }
     }
 
-    /* Dark mode support */
-    @media (prefers-color-scheme: dark) {
-      .bd-picture:not([loaded]) {
-        background-color: var(--color-neutral-800, #1f2937);
-        color: var(--color-neutral-400, #9ca3af);
-      }
-    }
+    /* No @media (prefers-color-scheme: dark) block. This was the one atom that
+       themed itself in CSS, which is the thing CLAUDE.md says a component must
+       never need to do — an atom changes appearance through tokens. The
+       placeholder now reads --color-surface-muted and --color-text-muted, so
+       whenever a dark theme redefines those on :root it follows without this
+       component being touched. */
   }
 `;