@repobit/dex-system-design 0.25.12 → 1.0.0

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

@@ -0,0 +1,111 @@
+import { html } from "lit";
+import "./grid.js";
+
+export default {
+  title     : "Layout/Grid",
+  component : "bd-grid",
+  tags      : ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs  : {
+      description: {
+        component: `
+**BdGrid** is a responsive column layout. It had no story until P6B, which is why
+nothing rendered it and no gate could see it.
+
+Columns are set per breakpoint and the component steps between them on its own:
+\`cols\` below 576, then \`cols-sm\`, \`cols-md\` at 768 and \`cols-lg\` at 992 — the
+\`--breakpoint-*\` scale. \`gap\` and \`padding\` take space step names
+(\`none\`, \`2xs\`, \`xs\`, \`sm\`, \`md\`, \`lg\`, \`xl\` …), not lengths.
+
+Its one consumer today is the footer's link columns.
+        `
+      }
+    }
+  },
+  argTypes: {
+    cols   : { control: { type: "number", min: 1, max: 6 }, description: "Columns below 576px." },
+    colsSm : { name: "cols-sm", control: { type: "number", min: 1, max: 6 }, description: "Columns from 576px." },
+    colsMd : { name: "cols-md", control: { type: "number", min: 1, max: 6 }, description: "Columns from 768px." },
+    colsLg : { name: "cols-lg", control: { type: "number", min: 1, max: 6 }, description: "Columns from 992px." },
+    gap    : { control: "select", options: ["none", "2xs", "xs", "sm", "md", "lg", "xl"], description: "Space step between cells." },
+    padding: { control: "select", options: ["none", "xs", "sm", "md", "lg"], description: "Space step inside the grid." },
+    align  : { control: "select", options: ["start", "center", "end", "stretch"] },
+    justify: { control: "select", options: ["start", "center", "end", "stretch"] }
+  }
+};
+
+/* A cell that shows its own box, so the columns and the gap are both visible. */
+const cell = (n) => html`
+  <div style="
+    background: var(--color-surface-container);
+    border: var(--border-width-1) solid var(--color-border-container);
+    border-radius: var(--radius-2xl);
+    padding: var(--spacing-16);
+    width: 100%;
+    box-sizing: border-box;
+    font-family: var(--typography-fontFamily-sans);
+    color: var(--color-text-primary);
+  ">Item ${n}</div>`;
+
+const cells = (n) => html`${Array.from({ length: n }, (_, i) => cell(i + 1))}`;
+
+export const Default = {
+  name  : "Default",
+  args  : { cols: 1, colsSm: 2, colsMd: 3, colsLg: 3, gap: "md", align: "stretch", justify: "stretch", padding: "none" },
+  render: (a) => html`
+    <bd-grid
+      cols=${a.cols} cols-sm=${a.colsSm} cols-md=${a.colsMd} cols-lg=${a.colsLg}
+      gap=${a.gap} align=${a.align} justify=${a.justify} padding=${a.padding}
+    >${cells(6)}</bd-grid>`,
+  parameters: { docs: { description: { story: "Six cells stepping one → two → three columns as the viewport crosses 576 and 768." } } }
+};
+
+export const ResponsiveColumns = {
+  name  : "Responsive columns",
+  render: () => html`
+    <bd-grid cols="1" cols-sm="2" cols-md="3" cols-lg="4" gap="md">${cells(8)}</bd-grid>`,
+  parameters: {
+    docs: { description: { story: "One column below 576, two from 576, three from 768, four from 992. Resize the frame — the component carries its own breakpoints, so there is no wrapper media query to look for." } }
+  }
+};
+
+export const SingleColumn = {
+  name      : "Single column",
+  render    : () => html`<bd-grid cols="1" cols-sm="1" cols-md="1" cols-lg="1" gap="sm">${cells(3)}</bd-grid>`,
+  parameters: { docs: { description: { story: "Pinned to one column at every width — what a narrow viewport renders, and what the footer's left column uses." } } }
+};
+
+export const GapScale = {
+  name  : "Gap scale",
+  render: () => html`
+    <div style="display: grid; gap: var(--spacing-32)">
+      ${["none", "2xs", "sm", "lg", "xl"].map((g) => html`
+        <div>
+          <p style="margin: 0 0 var(--spacing-8); font-family: var(--typography-fontFamily-mono); font-size: var(--typography-fontSize-xs); color: var(--color-text-muted)">
+            gap="${g}"
+          </p>
+          <bd-grid cols="3" cols-sm="3" cols-md="3" cols-lg="3" gap=${g}>${cells(3)}</bd-grid>
+        </div>`)}
+    </div>`,
+  parameters: { docs: { description: { story: "gap takes a space step name, not a length. An unrecognised name resolves to nothing rather than to a guess." } } }
+};
+
+export const Alignment = {
+  name  : "Alignment",
+  render: () => html`
+    <div style="display: grid; gap: var(--spacing-32)">
+      ${["start", "center", "stretch"].map((j) => html`
+        <div>
+          <p style="margin: 0 0 var(--spacing-8); font-family: var(--typography-fontFamily-mono); font-size: var(--typography-fontSize-xs); color: var(--color-text-muted)">
+            justify="${j}"
+          </p>
+          <bd-grid cols="3" cols-sm="3" cols-md="3" cols-lg="3" gap="sm" justify=${j}>
+            <div style="background: var(--color-surface-muted); padding: var(--spacing-8); border-radius: var(--radius-lg)">Short</div>
+            <div style="background: var(--color-surface-muted); padding: var(--spacing-8); border-radius: var(--radius-lg)">A wider cell</div>
+            <div style="background: var(--color-surface-muted); padding: var(--spacing-8); border-radius: var(--radius-lg)">Mid</div>
+          </bd-grid>
+        </div>`)}
+    </div>`,
+  parameters: { docs: { description: { story: "justify sets justify-items on the cells. stretch is the default the footer relies on." } } }
+};

package/src/components/header/header-code.css.js

@@ -1,16 +1,17 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
     font-family: var(--typography-fontFamily-sans);
     position: relative;
-    background-color: var(--color-neutral-0, #fff);
+    background-color: var(--color-surface-default);
     overflow: hidden; /* clips the ::after floor grid, which extends past the edges */
   }
 
   :host([variant="tint"]) {
-    background-image: radial-gradient(ellipse 900px 560px at 84% 8%, rgba(59, 130, 246, 0.16), transparent 65%);
+    background-image: radial-gradient(ellipse 900px 560px at 84% 8%, color-mix(in srgb, var(--color-surface-brand) 16%, transparent), transparent 65%);
     background-repeat: no-repeat;
   }
 
@@ -24,10 +25,10 @@ export default css`
     transform-origin: 50% 0;
     transform: perspective(620px) rotateX(64deg);
     background:
-      linear-gradient(#006dff1a 1px, #0000 1px) 0 0 / 100% 44px,
-      linear-gradient(90deg, #006dff1a 1px, #0000 1px) 0 0 / 44px 100%;
-    -webkit-mask-image: linear-gradient(#0000 0%, #000 45%, #0000 100%);
-    mask-image: linear-gradient(#0000 0%, #000 45%, #0000 100%);
+      linear-gradient(color-mix(in srgb, var(--color-blue-500) 10%, transparent) 1px, transparent 1px) 0 0 / 100% 44px,
+      linear-gradient(90deg, color-mix(in srgb, var(--color-blue-500) 10%, transparent) 1px, transparent 1px) 0 0 / 44px 100%;
+    -webkit-mask-image: linear-gradient(transparent 0%, var(--color-neutral-1000) 45%, transparent 100%);
+    mask-image: linear-gradient(transparent 0%, var(--color-neutral-1000) 45%, transparent 100%);
     pointer-events: none;
     z-index: 0;
   }
@@ -37,12 +38,10 @@ export default css`
     grid-template-columns: 1fr 1fr;
     align-items: center;
     gap: var(--spacing-48);
-    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;
     position: relative;
-    z-index: 1;
+    z-index: var(--z-base);
   }
 
   /* === ENTRANCE ANIMATION === */
@@ -59,11 +58,11 @@ export default css`
 
   .bd-headercode-left,
   .bd-headercode-right {
-    animation: bd-headercode-fade-up 0.6s cubic-bezier(0.16, 1, 0.3, 1) both;
+    animation: bd-headercode-fade-up var(--transition-duration-slower) var(--transition-easing-ease-out) both;
   }
 
   .bd-headercode-right {
-    animation-delay: 0.12s;
+    animation-delay: var(--transition-duration-fast);
   }
 
   @media (prefers-reduced-motion: reduce) {
@@ -86,9 +85,11 @@ export default css`
     flex-wrap: wrap;
     align-items: center;
     gap: var(--spacing-16);
-    color: var(--color-neutral-500);
-    font-family: var(--typography-fontFamily-mono, monospace);
-    font-size: var(--typography-fontSize-xs, 12px);
+    color: var(--color-text-subtle);
+    font-family: var(--typography-fontFamily-mono);
+    /* no role: the breadcrumb strip, in mono -- see awards-flex.css.js's
+       .bd-awardsflex-quote-source for the argument. */
+    font-size: var(--typography-fontSize-xs);
   }
 
   .bd-headercode-breadcrumb:not(:has(*)) {
@@ -96,19 +97,18 @@ export default css`
   }
 
   .bd-headercode-eyebrow {
-    color: var(--color-blue-400);
-    font-weight: var(--typography-fontWeight-bold);
+    /* blue-400 is 3.35:1 on white. The eyebrow is brand-coloured on purpose, so
+       it wants the brand text role rather than a lighter blue. */
+    color: var(--color-text-brand);
     margin: 0;
   }
 
   .bd-headercode-title {
     margin: 0;
-    color: var(--color-neutral-1000);
-    line-height: var(--typography-lineHeight-tight, 1.05);
   }
 
   .bd-headercode-description {
-    color: var(--color-neutral-600);
+    color: var(--color-text-muted);
     max-width: 480px;
     margin: 0;
   }
@@ -124,14 +124,16 @@ export default css`
   .bd-headercode-badge {
     display: inline-flex;
     align-items: center;
-    color: var(--color-neutral-600);
-    font-family: var(--typography-fontFamily-mono, monospace);
-    font-size: var(--typography-fontSize-xs, 12px);
+    color: var(--color-text-muted);
+    font-family: var(--typography-fontFamily-mono);
+    /* no role: the code badge, in mono and tracked -- see awards-flex.css.js's
+       .bd-awardsflex-quote-source for the argument. */
+    font-size: var(--typography-fontSize-xs);
     letter-spacing: 0.05em;
-    padding: var(--spacing-4, 4px) var(--spacing-12, 12px);
-    border: 1px solid var(--color-neutral-200, #e5e7eb);
-    border-radius: var(--radius-full, 999px);
-    background: var(--color-neutral-0, #fff);
+    padding: var(--spacing-4) var(--spacing-12);
+    border: 1px solid var(--color-border-subtle);
+    border-radius: var(--radius-full);
+    background: var(--color-surface-default);
   }
 
   .bd-headercode-badge:not(:has(*)) {
@@ -145,7 +147,7 @@ export default css`
   }
 
   .bd-headercode-meta-spec {
-    color: var(--color-neutral-500);
+    color: var(--color-text-subtle);
     margin: 0;
     padding-top: var(--spacing-16);
   }
@@ -156,28 +158,30 @@ export default css`
     gap: var(--spacing-8) var(--spacing-32);
     margin-top: var(--spacing-40);
     padding-top: var(--spacing-24);
-    border-top: 1px solid var(--color-neutral-100);
+    border-top: 1px solid var(--color-border-container);
   }
 
   .bd-headercode-meta-fact {
     display: flex;
     align-items: baseline;
-    gap: var(--spacing-8, 8px);
+    gap: var(--spacing-8);
     white-space: nowrap;
   }
 
   .bd-headercode-meta-fact-label {
     margin: 0;
-    color: var(--color-neutral-400);
+    /* subtle, not neutral-400: that is the disabled step and measured 2.5:1
+       on white; this is 4.67:1. */
+    color: var(--color-text-subtle);
     text-transform: uppercase;
   }
 
   .bd-headercode-meta-fact-value {
     margin: 0;
-    color: var(--color-neutral-900);
+    color: var(--color-text-primary);
   }
 
-  @media (max-width: 480px) {
+  @media ${unsafeCSS(below('sm'))} {
     .bd-headercode-meta-facts {
       grid-template-columns: repeat(2, auto);
     }
@@ -199,8 +203,10 @@ export default css`
     justify-content: flex-end;
     align-items: center;
     perspective: 1300px;
+    /* no token: the 3D scene's floor, sized to the terminal it tilts -- a
+       layout measure, not a step on any scale. */
     min-height: 400px;
-    padding: var(--spacing-16, 16px) 0;
+    padding: var(--spacing-16) 0;
     margin: 0;
     position: relative;
   }
@@ -217,7 +223,7 @@ export default css`
       rotateY(var(--ry, -10deg))
       rotateX(var(--rx, 6deg))
       rotateZ(1deg);
-    transition: transform 0.4s cubic-bezier(0.16, 1, 0.3, 1);
+    transition: transform var(--transition-duration-slow) var(--transition-easing-ease-out);
   }
 
   @media (prefers-reduced-motion: reduce) {
@@ -231,7 +237,7 @@ export default css`
     width: 100%;
     box-shadow: 0 1px 2px #0003, 0 18px 48px #000a1e73;
     position: relative;
-    z-index: 1; /* sits above the rings */
+    z-index: var(--z-base); /* sits above the rings */
   }
 
   @media (prefers-reduced-motion: reduce) {
@@ -241,10 +247,10 @@ export default css`
   }
 
   .bd-headercode-terminal-caption {
-    color: var(--color-neutral-500);
+    color: var(--color-text-subtle);
     margin: 0;
     position: relative;
-    z-index: 1;
+    z-index: var(--z-base);
   }
 
   .bd-headercode-rings {
@@ -258,20 +264,24 @@ export default css`
   .bd-headercode-ring {
     position: absolute;
     inset: 0;
-    border-radius: 28px;
-    border: 1.5px solid rgba(0, 109, 255, calc(0.5 - var(--d) * 0.08));
-    background: rgba(0, 109, 255, calc(0.05 - var(--d) * 0.008));
-    box-shadow: 0 0 26px rgba(0, 109, 255, calc(0.16 - var(--d) * 0.025));
-    animation: bd-headercode-ring-breathe 6s ease-in-out calc(var(--d) * -1.2s) infinite;
+    border-radius: var(--radius-3xl);
+    border: var(--border-width-2) solid color-mix(in srgb, var(--color-border-brand) calc((0.5 - var(--d) * 0.08) * 100%), transparent);
+    background: color-mix(in srgb, var(--color-surface-brand) calc((0.05 - var(--d) * 0.008) * 100%), transparent);
+    box-shadow: 0 0 26px color-mix(in srgb, var(--color-blue-500) calc((0.16 - var(--d) * 0.025) * 100%), transparent);
+    /* no token: an ambient loop, an order of magnitude longer than any
+       interaction the duration scale is for. */
+    animation: bd-headercode-ring-breathe 6s var(--transition-easing-smooth) calc(var(--d) * -1.2s) infinite;
     transform: translate(calc(var(--d) * 10px), calc(var(--d) * 8px));
   }
 
   @keyframes bd-headercode-ring-breathe {
     0%, 100% {
+      /* no token: the bright end of the ambient breath; the dim end is the
+         package's one pulse dimness. */
       opacity: 0.85;
     }
     50% {
-      opacity: 0.45;
+      opacity: var(--opacity-pulse);
     }
   }
 
@@ -284,18 +294,18 @@ export default css`
   /* === FLOATING ANNOTATION PILLS === */
   .bd-headercode-annotation {
     position: absolute;
-    z-index: 2;
+    z-index: var(--z-raised);
     pointer-events: none;
   }
 
   .bd-headercode-annotation--top {
-    top: -14px;
-    right: 32px;
+    top: calc(-1 * var(--spacing-14));
+    right: var(--spacing-32);
   }
 
   .bd-headercode-annotation--bottom {
-    bottom: -14px;
-    left: 16px;
+    bottom: calc(-1 * var(--spacing-14));
+    left: var(--spacing-16);
     right: auto;
   }
 
@@ -306,7 +316,7 @@ export default css`
   .bd-headercode-annotation ::slotted(*) {
     width: auto;
     max-width: none;
-    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+    box-shadow: 0 4px 12px color-mix(in srgb, var(--color-neutral-1000) 12%, transparent);
     pointer-events: auto;
   }
 

package/src/components/header/header-code.js

@@ -5,11 +5,13 @@ import "../heading/heading.js";
 import "../paragraph/paragraph.js";
 import "../terminal/terminal-message.js";
 import headerCodeCSS from "./header-code.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
 class HeaderCode extends LitElement {
   static properties = {
     eyebrow        : { type: String },
     title          : { type: String },
+    headingLevel   : { type: Number, attribute: "heading-level" },
     description    : { type: String },
     terminalCaption: { type: String, attribute: "terminal-caption" },
     variant        : { type: String, reflect: true },
@@ -18,12 +20,13 @@ class HeaderCode extends LitElement {
     _hasBadge      : { state: true }
   };
 
-  static styles = [tokens, headerCodeCSS];
+  static styles = [tokens, ensembleCSS, headerCodeCSS];
 
   constructor() {
     super();
     this.eyebrow = "";
     this.title = "";
+    this.headingLevel = 2;
     this.description = "";
     this.terminalCaption = "";
     this.variant = "default";
@@ -117,16 +120,15 @@ class HeaderCode extends LitElement {
 
     if (!hasSpec && !hasFacts) return nothing;
 
-    const monoFontFamily = "'IBM Plex Mono', ui-monospace, SFMono-Regular, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace";
 
     return html`
       <div class="bd-headercode-meta">
         ${hasSpec
           ? html`<bd-p
-              kind="xsmall"
+              variant="xsmall"
               class="bd-headercode-meta-spec"
-              font-family=${monoFontFamily}
-              letter-spacing=".1em"
+              font-family="mono"
+              letter-spacing="widest"
             >${this.metaSpec}</bd-p>`
           : nothing}
 
@@ -137,12 +139,12 @@ class HeaderCode extends LitElement {
                   (fact) => html`
                     <div class="bd-headercode-meta-fact">
                       <bd-p
-                        kind="xsmall"
+                        variant="xsmall"
                         class="bd-headercode-meta-fact-label"
-                        font-family=${monoFontFamily}
-                        letter-spacing=".1em"
+                        font-family="mono"
+                        letter-spacing="widest"
                       >${fact.label}</bd-p>
-                      <bd-p kind="regular" font-weight="700" class="bd-headercode-meta-fact-value">${fact.value}</bd-p>
+                      <bd-p kind="regular" font-weight="bold" class="bd-headercode-meta-fact-value">${fact.value}</bd-p>
                     </div>
                   `
                 )}
@@ -153,24 +155,36 @@ class HeaderCode extends LitElement {
     `;
   }
 
+
+  /**
+   * Level is the document-outline question and belongs to page composition;
+   * the type scale is this component's and stays where it was. visual-level
+   * pins the look at h1 so only the semantics move. Defaults to h2, because a
+   * reusable section cannot know it is the page's only heading.
+   */
+  get _headingTag() {
+    const n = Number(this.headingLevel);
+    return Number.isInteger(n) && n >= 1 && n <= 6 ? `h${n}` : "h2";
+  }
+
   render() {
     return html`
-      <div class="bd-headercode-container">
+      <div class="bd-ensemble bd-headercode-container">
         <div class="bd-headercode-left">
           <div class="bd-headercode-breadcrumb">
             <slot name="breadcrumb"></slot>
           </div>
 
           ${this.eyebrow
-            ? html`<bd-p kind="normal" class="bd-headercode-eyebrow">${this.eyebrow}</bd-p>`
+            ? html`<bd-p variant="regular" class="bd-headercode-eyebrow">${this.eyebrow}</bd-p>`
             : nothing}
 
-          <bd-h as="h1" class="bd-headercode-title">
+          <bd-h as="${this._headingTag}" visual-level="h1" class="bd-headercode-title">
             <slot name="title">${this.title}</slot>
           </bd-h>
 
           ${this.description
-            ? html`<bd-p kind="regular" class="bd-headercode-description">${this.description}</bd-p>`
+            ? html`<bd-p variant="regular" class="bd-headercode-description">${this.description}</bd-p>`
             : nothing}
 
           <div class="bd-headercode-cta">
@@ -200,7 +214,7 @@ class HeaderCode extends LitElement {
           </div>
 
           ${this.terminalCaption
-            ? html`<bd-p kind="small" class="bd-headercode-terminal-caption" font-family="'IBM Plex Mono', ui-monospace, SFMono-Regular, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace"
+            ? html`<bd-p variant="small" class="bd-headercode-terminal-caption" font-family="mono"
 >${this.terminalCaption}</bd-p>`
             : nothing}
         </div>

package/src/components/header/header-code.stories.js

@@ -33,8 +33,8 @@ dot-grid pattern, and gives the \`badge\` slot a bordered pill treatment.
   terminal-caption="// illustrative — every connection closes when the prompt ends"
 >
   <span slot="badge">EXTERNAL BETA</span>
-  <bd-button-link slot="primary-button" label="Download for macOS" kind="primary">Download for macOS</bd-button-link>
-  <bd-button-link slot="secondary-button" label="See how it works" kind="outline">See how it works</bd-button-link>
+  <bd-button-link slot="primary-button" label="Download for macOS" variant="primary">Download for macOS</bd-button-link>
+  <bd-button-link slot="secondary-button" label="See how it works" variant="outline">See how it works</bd-button-link>
 
   <div slot="meta">…facts row…</div>
 
@@ -100,7 +100,7 @@ const render = (args) => html`
     <bd-button-link
       slot="primary-button"
       label="Download BETA Today"
-      kind="primary"
+      variant="primary"
       size="md"
       font-size="18px"
       font-weight="600"
@@ -109,7 +109,7 @@ const render = (args) => html`
     <bd-button-link
       slot="secondary-button"
       label="See how it works"
-      kind="primary-outline"
+      variant="primary-outline"
       size="md"
       font-size="18px"
       font-weight="600"
@@ -227,7 +227,7 @@ export const SingleButton = {
       <bd-button-link
         slot="primary-button"
         label="Download BETA Today"
-        kind="primary"
+        variant="primary"
         size="md"
       >Download BETA Today</bd-button-link>