@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/display/display.stories.js

@@ -1,8 +1,9 @@
 import { html } from 'lit';
+import { until } from 'lit/directives/until.js';
 import './display.js';
 
 export default {
-  title     : 'Components/Display',
+  title     : 'Atoms/Display',
   tags      : ['autodocs'],
   parameters: {
     docs: {
@@ -12,35 +13,61 @@ export default {
 
 ### Usage
 \`\`\`html
-<bd-display kind="xl" color="#026DFF" align="center">
+<bd-display variant="xl" color="primary" align="center">
   World-class protection
 </bd-display>
 \`\`\`
 
-### Kind Values
-| Kind | Description |
-|---|---|
-| \`sm\` | Small display |
-| \`md\` | Medium display (default) |
-| \`lg\` | Large display |
-| \`xl\` | Extra large |
-| \`xxl\` | 2x extra large |
-| \`xxxl\` | 3x extra large |
+### The six steps, and which of them a phone can take
+
+| variant | role | desktop | at 320 | fits a 288px column? |
+|---|---|---|---|---|
+| \`sm\` | \`display-sm\` | 36px | **30px**, fluid | yes |
+| \`md\` | \`display-md\` | 48px | **30px**, fluid | yes |
+| \`lg\` | \`display-lg\` | 60px | 60px, fixed | only words under 480 per 100px |
+| \`xl\` | \`display-xl\` | 72px | 72px, fixed | rarely |
+| \`xxl\` | \`display-2xl\` | 96px | 96px, fixed | no |
+| \`xxxl\` | \`display-3xl\` | 128px | 128px, fixed | no |
+
+**\`md\` is the default**, as of 2026-09-17 — the largest step that fits at
+every width. It used to be \`lg\`, the largest step that does *not*; see
+\`plans/LATER.md\` entry 14, and *On a phone* below, which measures all six in
+a real 288px column. An unrecognised variant lands on \`md\` too, because a
+typo should not render larger than what was asked for.
+
+### Four of these roles are desktop-only, and that is a decision
+
+Decided 2026-09-17, \`plans/LATER.md\` entry 9. \`display-sm\` and
+\`display-md\` are fluid — \`clamp()\` in the role token, floor 30px at a 320px
+viewport. **\`lg\`, \`xl\`, \`2xl\` and \`3xl\` are not, and will not be.**
+
+Giving them mobile endpoints was measured and rejected. A floor that fits the
+widest token in the production sample is **29px**, so all four would land on
+the same number as \`sm\` and \`md\` — which already share 30 and are
+indistinguishable at 320. Six steps rendering one size makes \`variant\` a
+no-op on a phone, which is worse than a step that has to be chosen.
+
+So the rule is: **which step belongs at which breakpoint is the composing
+page's choice, and the role never shrinks itself.** The atom contains the
+damage rather than hiding it — \`overflow-wrap: break-word\` keeps a 128px
+word inside the column instead of scrolling the document sideways — but a
+contained word is still split across four lines. Step down.
         `
       }
     }
   },
   argTypes: {
-    kind: {
+    variant: {
       control    : { type: 'select' },
       options    : ['sm', 'md', 'lg', 'xl', 'xxl', 'xxxl'],
-      description: 'Display size variant — maps to a CSS class',
-      table      : { type: { summary: "'sm'|'md'|'lg'|'xl'|'xxl'|'xxxl'" }, defaultValue: { summary: 'lg' }, category: 'Appearance' }
+      description: 'Which display role to render. `kind` is the old name and still resolves.',
+      table      : { type: { summary: "'sm'|'md'|'lg'|'xl'|'xxl'|'xxxl'" }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     },
     color: {
-      control    : 'color',
-      description: 'Inline text color applied via style attribute',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Appearance' }
+      control    : { type: 'select' },
+      options    : ['', 'primary', 'strong', 'muted', 'subtle', 'inverse', 'success', 'warning', 'error'],
+      description: 'A semantic colour role, not a CSS colour. Resolves to a palette token; anything else is dropped.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Appearance' }
     },
     align: {
       control    : { type: 'select' },
@@ -52,43 +79,51 @@ export default {
 };
 
 const render = (args) => html`
-  <bd-display kind="${args.kind}" color="${args.color}" align="${args.align}">
+  <bd-display variant="${args.variant}" color="${args.color}" align="${args.align}">
     World-class security software
   </bd-display>
 `;
 
-const defaultArgs = { kind: 'lg', color: '', align: 'left' };
+const defaultArgs = { variant: 'md', color: '', align: 'left' };
 
 // ─── Stories ───────────────────────────────────────────────────────────────
 
 export const Default = {
-  name      : 'Default (lg, left)',
-  render    : () => html`<bd-display kind="lg">World-class security software</bd-display>`,
-  parameters: { docs: { description: { story: 'Default display text with `kind="lg"` and left alignment.' } } }
+  name      : 'Default (md, left)',
+  render    : () => html`<bd-display>World-class security software</bd-display>`,
+  parameters: {
+    docs: {
+      description: {
+        story: 'No `variant` at all — this is what a bare `<bd-display>` renders. It is '
+          + '`md` (48px on desktop, 30px on a phone) since 2026-09-17; it was `lg` (60px, '
+          + 'fixed at every width) before. See `plans/LATER.md` entry 14.'
+      }
+    }
+  }
 };
 
 export const AllKinds = {
   name  : 'All Kinds',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:16px;">
-      <bd-display kind="sm">Small Display</bd-display>
-      <bd-display kind="md">Medium Display</bd-display>
-      <bd-display kind="lg">Large Display</bd-display>
-      <bd-display kind="xl">Extra Large Display</bd-display>
-      <bd-display kind="xxl">2x Extra Large</bd-display>
-      <bd-display kind="xxxl">3x Extra Large</bd-display>
+      <bd-display variant="sm">Small Display</bd-display>
+      <bd-display variant="md">Medium Display</bd-display>
+      <bd-display variant="lg">Large Display</bd-display>
+      <bd-display variant="xl">Extra Large Display</bd-display>
+      <bd-display variant="xxl">2x Extra Large</bd-display>
+      <bd-display variant="xxxl">3x Extra Large</bd-display>
     </div>
   `,
-  parameters: { docs: { description: { story: 'All six `kind` values stacked vertically for scale comparison.' } } }
+  parameters: { docs: { description: { story: 'All six `variant` values stacked vertically for scale comparison.' } } }
 };
 
 export const AllAlignments = {
   name  : 'All Alignments',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:16px; width:100%;">
-      <bd-display kind="lg" align="left">Left aligned display</bd-display>
-      <bd-display kind="lg" align="center">Center aligned display</bd-display>
-      <bd-display kind="lg" align="right">Right aligned display</bd-display>
+      <bd-display variant="lg" align="left">Left aligned display</bd-display>
+      <bd-display variant="lg" align="center">Center aligned display</bd-display>
+      <bd-display variant="lg" align="right">Right aligned display</bd-display>
     </div>
   `,
   parameters: { docs: { description: { story: 'All three alignment options: left, center, and right.' } } }
@@ -98,10 +133,10 @@ export const CustomColor = {
   name  : 'Custom Color',
   render: () => html`
     <div style="display:flex; flex-direction:column; gap:12px;">
-      <bd-display kind="lg" color="#026DFF">Blue Display</bd-display>
-      <bd-display kind="lg" color="#E53935">Red Display</bd-display>
-      <bd-display kind="lg" color="#43A047">Green Display</bd-display>
-      <bd-display kind="lg" color="var(--color-neutral-1000)">Token Color</bd-display>
+      <bd-display variant="lg" color="primary">Blue Display</bd-display>
+      <bd-display variant="lg" color="error">Red Display</bd-display>
+      <bd-display variant="lg" color="success">Green Display</bd-display>
+      <bd-display variant="lg" color="strong">Token Color</bd-display>
     </div>
   `,
   parameters: { docs: { description: { story: 'Custom `color` values including hex codes and CSS custom properties.' } } }
@@ -111,17 +146,212 @@ export const HeroVariant = {
   name  : 'Hero Variant',
   render: () => html`
     <div style="text-align:center; padding:40px;">
-      <bd-display kind="xxxl" color="#026DFF" align="center">
+      <bd-display variant="xxxl" color="primary" align="center">
         Award-winning cybersecurity
       </bd-display>
     </div>
   `,
-  parameters: { docs: { description: { story: 'Large hero-style display with xxxl size, blue color, and center alignment.' } } }
+  parameters: {
+    docs: {
+      description: {
+        story: 'Large hero-style display with xxxl size, blue color and center '
+          + 'alignment. **A usage pattern, not a variant** — the name predates, and '
+          + 'outlived, a `hero` variant that no longer exists. That variant and its '
+          + '`--typography-display-hero-*` role were retired because a 64px header '
+          + 'headline was their only reason to exist and the chosen header '
+          + 'configuration dropped to 48. There is no `hero` value on this prop; '
+          + 'this story reaches for `xxxl` and always did.'
+      }
+    }
+  }
+};
+
+/* Measured live, because a width written down is a width that goes stale --
+   and because measuring before IBM Plex Bold has loaded reads system-ui and
+   comes out about 3% narrow. See Foundations/Typography -> Why These Sizes. */
+const PHONE_WORDS = [
+  ['Safe', 'en'],
+  ['Security', 'en'],
+  ['Protection', 'en'],
+  ['Cybersecurity', 'en'],
+  ['Gründungsmitglied', 'de'],
+  ['kalenderinbjudningar', 'sv']
+];
+/* variant, desktop size, and the 320px floor for the two FLUID roles -- null
+   means the role has no mobile endpoint and renders its desktop size at every
+   width, which is the whole subject of this story. */
+const STEPS = [
+  ['sm', 36, 30], ['md', 48, 30],
+  ['lg', 60, null], ['xl', 72, null], ['xxl', 96, null], ['xxxl', 128, null]
+];
+const COLS = [[320, 288], [375, 343]];
+const FLUID_WINDOW = [320, 992];
+
+/** What a clamp(min, .., max) role resolves to at a given viewport width. */
+const fluidAt = (vw, min, max) => {
+  const [v1, v2] = FLUID_WINDOW;
+  if (vw <= v1) return min;
+  if (vw >= v2) return max;
+  return min + ((max - min) * (vw - v1)) / (v2 - v1);
+};
+
+/** Width per px of size, at the display family's own tight tracking. */
+function displayPer(text) {
+  const el = document.createElement('span');
+  el.style.cssText = 'position:absolute;visibility:hidden;white-space:nowrap;'
+    + 'font-family:var(--typography-fontFamily-sans);font-weight:700;'
+    + 'letter-spacing:var(--typography-letterSpacing-tight);font-size:100px';
+  el.textContent = text;
+  document.body.appendChild(el);
+  const w = el.getBoundingClientRect().width / 100;
+  el.remove();
+  return w;
+}
+
+const phoneColumn = async () => {
+  await document.fonts.load('700 100px "IBM Plex Sans"');
+  await document.fonts.ready;
+  const rows = PHONE_WORDS.map(([word, lang]) => {
+    const per = displayPer(word);
+    return { word, lang, per, max: COLS.map(([, col]) => Math.floor(col / per)) };
+  });
+  const probe = displayPer('Cybersecurity');
+
+  return html`
+    <div style="display:grid; gap:var(--spacing-32)">
+      <p style="margin:0; max-width:64ch">
+        Every step of the family set in <b>Cybersecurity</b> inside a real 288px column —
+        what type gets on a 320px phone once both <code>--grid-padding-*</code> gutters
+        come out. Nothing scrolls sideways, because the atom sets
+        <code>overflow-wrap: break-word</code>; look instead at <b>where the word breaks</b>.
+      </p>
+      <!-- STACKED, not side by side. At 128px this word overruns its column by
+           508px, so two columns in a row painted over each other and the wider
+           one won. The overflow is the finding; the overlap was just my layout. -->
+      <div style="display:flex; flex-direction:column; gap:var(--spacing-48)">
+        ${COLS.map(([vw, col]) => html`
+          <div>
+            <p style="margin:0 0 var(--spacing-8); font:500 12px/1.4 var(--typography-fontFamily-mono);
+                      color:var(--color-text-muted)">
+              ${vw}px viewport · ${col}px column
+            </p>
+            <!-- The two fluid roles are pinned to the value their clamp resolves to
+                 at THIS viewport, not at the one your browser happens to be. Without
+                 the pin the demo drew md at its desktop 48 inside a phone column and
+                 called it a split, which is the opposite of what a phone does. -->
+            <div style="width:${col}px; outline:2px dashed var(--color-text-error);
+                        display:grid; gap:var(--spacing-16); padding-block:var(--spacing-12);
+                        --typography-display-sm-fontSize:${Math.round(fluidAt(vw, 30, 36))}px;
+                        --typography-display-md-fontSize:${Math.round(fluidAt(vw, 30, 48))}px">
+              ${STEPS.map(([variant, desktop, floor]) => {
+                /* The size this role really renders at THIS viewport: the
+                   clamp's value for the two fluid roles, the fixed desktop
+                   size for the other four. */
+                const size = floor === null ? desktop : Math.round(fluidAt(vw, floor, desktop));
+                const need = Math.round(probe * size);
+                const fits = need <= col;
+                return html`
+                  <!-- min-width:0 on the row and display:block on the atom: a grid
+                       item keeps its min-content width by default, and an inline
+                       host does not hand the shadow div a width to break against,
+                       so without both the word overflowed instead of wrapping --
+                       which would have libelled the component's own break-word. -->
+                  <div style="min-width:0">
+                    <div style="font:500 10px/1.4 var(--typography-fontFamily-mono);
+                                color:${fits ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+                      ${variant} · ${size}px${floor === null ? '' : ' (fluid)'} · needs ${need}
+                      ${fits ? html`· fits by ${col - need}` : html`· <b>splits</b>, over by ${need - col}`}
+                    </div>
+                    <bd-display variant="${variant}" style="display:block">Cybersecurity</bd-display>
+                  </div>
+                `;
+              })}
+            </div>
+          </div>
+        `)}
+      </div>
+      <div style="overflow-x:auto">
+        <table style="border-collapse:collapse; font-size:14px">
+          <caption style="text-align:left; padding-bottom:var(--spacing-8); color:var(--color-text-muted)">
+            The largest display size each word can take, measured in this browser at the
+            family's own tracking
+          </caption>
+          <thead>
+            <tr>
+              ${['word', 'lang', 'w / 100px', '288px column', '343px column'].map(h => html`
+                <th style="text-align:left; padding:6px 12px; border-bottom:1px solid var(--color-border-default)">${h}</th>
+              `)}
+            </tr>
+          </thead>
+          <tbody>
+            ${rows.map(r => html`
+              <tr>
+                <td style="padding:6px 12px">${r.word}</td>
+                <td style="padding:6px 12px"><code>${r.lang}</code></td>
+                <td style="padding:6px 12px">${Math.round(r.per * 100)}</td>
+                <td style="padding:6px 12px">${r.max[0]}px</td>
+                <td style="padding:6px 12px">${r.max[1]}px</td>
+              </tr>
+            `)}
+          </tbody>
+        </table>
+      </div>
+      <p style="margin:0; max-width:64ch">
+        <b>Read the last two rows.</b> A German or Swedish compound caps the family at
+        ${rows[4].max[0]}–${rows[5].max[0]}px on a phone — below every step except the
+        fluid floor that <code>sm</code> and <code>md</code> already reach. That is the
+        measurement that decided the four large roles stay desktop-only: there is no
+        mobile endpoint to give them that would not collapse the whole family onto one
+        size.
+      </p>
+    </div>
+  `;
+};
+
+export const PhoneColumn = {
+  name      : 'On a phone (288px column)',
+  render    : () => html`${until(phoneColumn(), html`<p style="color:var(--color-text-muted)">Loading IBM Plex Sans Bold before measuring anything…</p>`)}`,
+  parameters: {
+    controls: { disable: true },
+    docs    : {
+      description: {
+        story: `The limit, measured rather than asserted. **\`sm\` and \`md\` are fluid** and
+reach a 30px floor at 320, so they fit. **\`lg\` and up are fixed**, so on a phone the
+word breaks mid-syllable — contained, but not designed.
+
+The atom deliberately knows nothing about viewports: it maps a variant onto a
+\`--typography-display-*\` role, and six steps exist precisely so the composing page can
+choose one per breakpoint. \`plans/LATER.md\` entry 9 has the decision and the rejected
+alternative.`
+      }
+    }
+  }
 };
 
 export const Playground = {
   name      : '🛝 Playground',
   args      : { ...defaultArgs },
   render,
-  parameters: { docs: { description: { story: 'Interactive playground. Adjust kind, color, and alignment via Controls.' } } }
-};
+  parameters: { docs: { description: { story: 'Interactive playground. Adjust variant, color, and alignment via Controls.' } } }
+};
+export const LegacyKind = {
+  name  : 'Legacy kind prop',
+  render: () => html`
+    <div style="display:grid; gap: var(--spacing-16)">
+      <bd-display variant="sm">kind="sm" — the old spelling</bd-display>
+      <bd-display variant="sm">variant="sm" — the current one</bd-display>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `The visual axis was called \`kind\` before the vocabulary settled on
+one word per axis — \`size\` for how big, \`variant\` for how it looks, \`tone\` for
+what it means. bd-p and bd-li were converted then and this atom was missed.
+
+\`kind\` still resolves to \`variant\`, so no consumer's markup breaks. These two
+rows must render identically; if they ever stop, the alias has been dropped.`
+      }
+    }
+  }
+};

package/src/components/divider/divider-horizontal.js

@@ -1,9 +1,11 @@
 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 { dividerHorizontal } from "./divider.css.js";
+import { borderColor } from "../shared/token-scales.js";
 
 export class BdDividerHorizontal extends LitElement {
-  static styles = [tokens, dividerHorizontal];
+  static styles = [dividerHorizontal];
 
   static properties = {
     width  : { type: String },
@@ -13,18 +15,32 @@ export class BdDividerHorizontal extends LitElement {
 
   constructor() {
     super();
-    this.width = "";
-    this.color = "var(--color-neutral-400)";
+    this.width = "100%";   // the rule spans its container by default
+    /* No colour by default: the stylesheet draws the rule in
+       --color-border-default, which is the role for a hairline, and leaving
+       this empty lets that stand. It used to say "subtle", which is a *text*
+       role — it resolved to the same step by coincidence, so the divider was
+       reading its colour out of the ink vocabulary and nobody could see it.
+
+       The prop now resolves through BORDER_ROLES first (see token-scales.js),
+       so `subtle` means --color-border-subtle and a rule on a brand tint can
+       ask for `brand-subtle`. The ink vocabulary is still accepted as a
+       fallback for the names already in the markup. */
+    this.color = "";
     this.opacity = "0.25";
   }
 
   render() {
+    // An unrecognised or empty colour emits no declaration at all, so the
+    // stylesheet's --color-border-default stands rather than being overridden
+    // with an empty value.
+    const ink = borderColor(this.color);
     return html`
       <hr
         class="hr-line"
         style="
           width: ${this.width};
-          border-top-color: ${this.color};
+          ${ink ? `border-top-color: ${ink};` : ''}
           opacity: ${this.opacity};
         "
       />

package/src/components/divider/divider-vertical.js

@@ -1,9 +1,11 @@
 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 { dividerVertical } from "./divider.css.js";
+import { borderColor, spacing } from "../shared/token-scales.js";
 
 export class BdDividerVertical extends LitElement {
-  static styles = [tokens, dividerVertical];
+  static styles = [dividerVertical];
 
   static properties = {
     height   : { type: String },
@@ -15,23 +17,29 @@ export class BdDividerVertical extends LitElement {
 
   constructor() {
     super();
-    this.height = "15px";
+    this.height = "16";   // a spacing step; was a 15px literal, off every scale
     this.thickness = "1px";
-    this.color = "var(--color-neutral-400)";
+    /* No colour by default — see the note in divider-horizontal.js. The
+       stylesheet's --color-border-default is the role for a hairline; "subtle"
+       was a text role that happened to resolve to the same step. The prop
+       resolves through BORDER_ROLES first; see token-scales.js. */
+    this.color = "";
     this.opacity = "1.00";
 
   }
 
   render() {
+    // See divider-horizontal.js: no colour means no declaration, so the
+    // stylesheet's --color-border-default stands.
+    const ink = borderColor(this.color);
     return html`
       <div
         class="divider"
         style="
           width: ${this.thickness};
-          height: ${this.height};
-          background-color: ${this.color};
+          height: ${spacing(this.height)};
+          ${ink ? `background-color: ${ink};` : ''}
           opacity: ${this.opacity};
-
         "
       ></div>
     `;

package/src/components/divider/divider.css.js

@@ -3,7 +3,7 @@ import { css } from "lit";
 export const dividerHorizontal = css`
   .hr-line {
     border: none;
-    border-top: 1px solid var(--color-neutral-400);
+    border-top: var(--border-width-1) solid var(--color-border-default);
     margin: 0;
     width: 100%;
     margin-left: auto;
@@ -13,7 +13,7 @@ export const dividerHorizontal = css`
 
 export const dividerVertical = css`
   .divider {
-    background-color: var(--color-neutral-400);
+    background-color: var(--color-border-default);
     display: inline-block;
   }
 `;