@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/tokens/layout.css

@@ -1,10 +1,13 @@
-@import './tokens.css';
+/* Layout helpers for non-component markup.
+   Tokens are not imported here: every entry point that loads this file loads
+   tokens.css first, and the @import was pulling in a second ~39KB copy. */
+
 .bd-button-container {
     display: flex;
     flex-direction: column; 
     align-items: center; 
-    gap: 1rem;
-    padding: 1rem;
+    gap: var(--spacing-16);
+    padding: var(--spacing-16);
   }
 
   @media (min-width: 768px) {
@@ -18,18 +21,29 @@
   .bd-button-container > bd-button,
   .bd-button-container > bd-contact-button {
     width: 100%; 
+    /* no token: the cap a stacked call-to-action column is allowed to grow to.
+       It is a layout decision with no home on the spacing or dimension scales,
+       which stop well below it, and no --layout-* token names it. */
     max-width: 300px;
   }
 
 
+/* The page column for light-DOM markup: the twin of .bd-ensemble in
+   src/components/shared/ensemble.css.js, which is the source of truth. A page
+   that lays out its own sections gets the same edges the modules draw. The
+   breakpoints are the scale's own values (576 / 768 / 992 / 1200 / 1400). */
 .bd-container {
-    max-width: 1200px;
-    margin: 0 auto;
-    padding: var(--spacing-16);
-    display: flex;
-    flex-direction: column; 
-    gap: var(--spacing-8); 
+    box-sizing: border-box;
+    width: 100%;
+    max-width: var(--grid-container-max-xs);
+    margin-inline: auto;
+    padding-inline: var(--grid-padding-xs);
   }
+  @media (min-width: 576px)  { .bd-container { max-width: var(--grid-container-max-sm);  padding-inline: var(--grid-padding-sm); } }
+  @media (min-width: 768px)  { .bd-container { max-width: var(--grid-container-max-md);  padding-inline: var(--grid-padding-md); } }
+  @media (min-width: 992px)  { .bd-container { max-width: var(--grid-container-max-lg);  padding-inline: var(--grid-padding-lg); } }
+  @media (min-width: 1200px) { .bd-container { max-width: var(--grid-container-max-xl); } }
+  @media (min-width: 1400px) { .bd-container { max-width: var(--grid-container-max-xxl); } }
   
   .bd-container-fluid {
     width: 100%;
@@ -38,9 +52,9 @@
 
   .pricing-container {
     display: flex;
-    gap: 16px; 
+    gap: var(--spacing-16); 
     justify-content: center; 
     align-items: stretch; 
-    padding: 20px; 
+    padding: var(--spacing-20); 
   }
   

package/src/tokens/motion.stories.js

@@ -0,0 +1,231 @@
+import { html } from 'lit';
+import {
+  discoverConsumers,
+  docsPage,
+  primitiveTable,
+  readAllCssText,
+  refSection,
+  referenceNote,
+  resolve,
+  tokensFor
+} from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Motion',
+  tags : ['autodocs']
+};
+
+const motionStyles = html`
+  <style>
+    .track {
+      position: relative;
+      height: var(--spacing-24);
+      background: var(--color-neutral-50);
+      border-radius: var(--radius-full);
+      min-width: 220px;
+    }
+
+    .runner {
+      position: absolute;
+      top: var(--spacing-4);
+      left: var(--spacing-4);
+      width: var(--spacing-16);
+      height: var(--spacing-16);
+      background: var(--color-blue-500);
+      border-radius: var(--radius-full);
+      transition-property: transform;
+    }
+
+    /* .is-running is toggled on the page, so every runner moves together and
+       the durations and curves can be compared in one pass. */
+    .is-running .runner {
+      transform: translateX(calc(100% + 180px));
+    }
+
+    .replay {
+      font: inherit;
+      font-size: var(--typography-fontSize-xs);
+      font-weight: var(--typography-fontWeight-medium);
+      color: var(--color-neutral-0);
+      background: var(--color-blue-500);
+      border: 0;
+      border-radius: var(--radius-md);
+      padding: var(--spacing-8) var(--spacing-16);
+      cursor: pointer;
+      margin-bottom: var(--spacing-16);
+    }
+
+    .replay:hover {
+      background: var(--color-blue-600);
+    }
+
+    .replay:focus-visible {
+      outline: var(--focus-outline-traditional);
+      outline-offset: var(--focus-outline-offset);
+    }
+
+    .hover-chip {
+      display: inline-block;
+      background: var(--color-neutral-100);
+      color: var(--color-neutral-900);
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      padding: var(--spacing-8) var(--spacing-12);
+      border-radius: var(--radius-md);
+      transition-property: background-color, transform;
+      transition-timing-function: var(--transition-easing-smooth);
+    }
+
+    .hover-chip:hover {
+      background: var(--color-blue-500);
+      color: var(--color-neutral-0);
+      transform: translateY(-2px);
+    }
+
+    /* Honour the user's motion preference — a motion page especially must. */
+    @media (prefers-reduced-motion: reduce) {
+      .runner,
+      .hover-chip {
+        transition: none !important;
+      }
+
+      .is-running .runner {
+        transform: none;
+      }
+    }
+
+    .reduced-note {
+      display: none;
+      font-size: var(--typography-fontSize-xs);
+      color: var(--color-neutral-700);
+      background: var(--color-yellow-50);
+      border-radius: var(--radius-md);
+      padding: var(--spacing-12) var(--spacing-16);
+      margin-bottom: var(--spacing-16);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .reduced-note {
+        display: block;
+      }
+    }
+  </style>
+`;
+
+const replay = event => {
+  const root = event.currentTarget.closest('.section');
+  const demo = root && root.querySelector('.demo-body');
+  if (!demo) return;
+  demo.classList.remove('is-running');
+  // force a reflow so the transition restarts from the beginning
+  void demo.offsetWidth;
+  demo.classList.add('is-running');
+};
+
+export const Motion = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+
+  const durations = tokensFor(cssText, 'transition-duration-');
+  const easings = tokensFor(cssText, 'transition-easing-');
+
+  return html`
+    ${motionStyles}
+    ${docsPage({
+      title: 'Motion',
+      lede : html`Durations and easing curves. Components combine them as
+        <code>transition: background-color var(--transition-duration-normal)
+        var(--transition-easing-smooth)</code>. There is no composed
+        <code>--transition-*</code> shorthand token — the two halves are always applied separately.`,
+      note: html`Every animated example here is disabled under
+        <code>prefers-reduced-motion: reduce</code>. Components should do the same;
+        <code>button.css.js</code> is the pattern to copy. ${referenceNote}`,
+      children: html`
+        <div class="reduced-note">
+          Your system requests reduced motion, so the demos below are static. The tokens and their
+          values are still listed.
+        </div>
+
+        ${refSection({
+          name    : 'Duration',
+          meta    : `${durations.length} steps · --transition-duration-*`,
+          children: html`
+            ${primitiveTable({
+              caption: 'Duration tokens',
+              tokens : durations,
+              consumers
+            })}
+            <button class="replay" @click=${replay}>Replay durations</button>
+            <div class="specimen demo-body is-running">
+              ${durations.map(
+                token => html`
+                  <p style="margin: 0 0 var(--spacing-6); font-family: var(--typography-fontFamily-mono); font-size: var(--typography-fontSize-xxs); color: var(--color-neutral-600)">
+                    ${token} — ${resolve(token)}
+                  </p>
+                  <div class="track" style="margin-bottom: var(--spacing-16)">
+                    <div
+                      class="runner"
+                      style="transition-duration: var(${token}); transition-timing-function: linear"
+                    ></div>
+                  </div>
+                `
+              )}
+            </div>
+          `
+        })}
+
+        ${refSection({
+          name    : 'Easing',
+          meta    : `${easings.length} curves · --transition-easing-*`,
+          children: html`
+            ${primitiveTable({
+              caption: 'Easing tokens',
+              tokens : easings,
+              consumers
+            })}
+            <button class="replay" @click=${replay}>Replay easings</button>
+            <div class="specimen demo-body is-running">
+              ${easings.map(
+                token => html`
+                  <p style="margin: 0 0 var(--spacing-6); font-family: var(--typography-fontFamily-mono); font-size: var(--typography-fontSize-xxs); color: var(--color-neutral-600)">
+                    ${token} — ${resolve(token)}
+                  </p>
+                  <div class="track" style="margin-bottom: var(--spacing-16)">
+                    <div
+                      class="runner"
+                      style="transition-duration: var(--transition-duration-slower); transition-timing-function: var(${token})"
+                    ></div>
+                  </div>
+                `
+              )}
+            </div>
+            <p class="docs-lede" style="margin-top: var(--spacing-16)">
+              <code>--transition-easing-bounce</code> is
+              <code>${resolve('--transition-easing-bounce')}</code> — the negative and
+              greater-than-one control points make it overshoot at both ends. Use it for a
+              deliberate spring, not for hover states.
+            </p>
+          `
+        })}
+
+        ${refSection({
+          name    : 'In context',
+          meta    : 'hover a chip',
+          children: html`
+            <div class="specimen">
+              ${durations.map(
+                token => html`
+                  <span
+                    class="hover-chip"
+                    style="transition-duration: var(${token}); margin: 0 var(--spacing-8) var(--spacing-8) 0"
+                    >${token.replace('--transition-duration-', '')} · ${resolve(token)}</span
+                  >
+                `
+              )}
+            </div>
+          `
+        })}
+      `
+    })}
+  `;
+};

package/src/tokens/shape.stories.js

@@ -0,0 +1,272 @@
+import { html } from 'lit';
+import {
+  discoverConsumers,
+  docsPage,
+  primitiveTable,
+  readAllCssText,
+  refSection,
+  referenceNote,
+  resolve,
+  tokensFor
+} from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Shape',
+  tags : ['autodocs']
+};
+
+const shapeStyles = html`
+  <style>
+    .radius-chip {
+      width: var(--spacing-56);
+      height: var(--spacing-36);
+      background: var(--color-blue-100);
+      border: var(--border-width-1) solid var(--color-blue-500);
+    }
+
+    .border-chip {
+      width: var(--spacing-56);
+      height: var(--spacing-36);
+      background: var(--color-neutral-0);
+      border-style: solid;
+      border-color: var(--color-neutral-700);
+      border-radius: var(--radius-sm);
+    }
+
+    /* radius reads differently depending on the size of the box it is on */
+    .scale-demo {
+      display: flex;
+      align-items: flex-end;
+      gap: var(--spacing-16);
+      flex-wrap: wrap;
+    }
+
+    .scale-demo figure {
+      margin: 0;
+      text-align: center;
+    }
+
+    .scale-demo .box {
+      background: var(--color-blue-100);
+      border: var(--border-width-1) solid var(--color-blue-500);
+      margin-bottom: var(--spacing-4);
+    }
+
+    .scale-demo figcaption {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+    }
+
+    .warn {
+      color: var(--color-red-800);
+      background: var(--color-red-50);
+      border-radius: var(--radius-md);
+      padding: var(--spacing-12) var(--spacing-16);
+      font-size: var(--typography-fontSize-xs);
+      line-height: var(--typography-lineHeight-normal);
+      margin-bottom: var(--spacing-16);
+    }
+
+    .warn code {
+      font-family: var(--typography-fontFamily-mono);
+    }
+  </style>
+`;
+
+export const Radius = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+  const radii = tokensFor(cssText, 'radius-');
+
+  return html`
+    ${shapeStyles}
+    ${docsPage({
+      title: 'Border radius',
+      lede : html`Eight steps, and which one to reach for is a question of role rather than
+        taste.
+        <br><br>
+        <b>Controls</b> — button, input, select, textarea — read a size-matched alias rather
+        than a step: <code>--button-<b>small</b>-borderRadius</code> beside
+        <code>--form-input-<b>small</b>-borderRadius</code>, and so on for medium and large.
+        A button and a field of the same size sit in the same row, and matching the size in
+        the name is what keeps their corners in step. They were a step apart at
+        <code>sm</code> and <code>md</code> until this was written down.
+        <br><br>
+        <b>Containers</b> that hold content take <code>--radius-md</code> — alert, fieldset.
+        <b>Media</b> takes <code>--radius-lg</code> — video, and the default for image and
+        picture. <b>Pills and circles</b> take <code>--radius-full</code> — badge, tag,
+        avatar, switch, progress, spinner. Small inline surfaces take
+        <code>--radius-sm</code> — inline code, the checkbox box, skeleton.
+        <br><br>
+        <code>--radius-xl</code>, <code>--radius-2xl</code> and <code>--radius-3xl</code> have
+        no role in the atom layer. They are reachable through the radius prop on bd-img and
+        bd-picture, and one block in bd-code uses <code>3xl</code>; nothing else should reach
+        for them without a reason.`,
+      note    : referenceNote,
+      children: html`
+        ${refSection({
+          name    : 'Scale',
+          meta    : `${radii.length} steps · --radius-*`,
+          children: primitiveTable({
+            caption: 'Border radius scale',
+            tokens : radii,
+            consumers,
+            visual : token => html`<div class="radius-chip" style="border-radius: var(${token})"></div>`
+          })
+        })}
+        ${refSection({
+          name    : 'The same radius on different box sizes',
+          meta    : '--radius-lg on 32px, 64px and 128px',
+          children: html`
+            <div class="specimen">
+              <div class="scale-demo">
+                ${[32, 64, 128].map(
+                  size => html`
+                    <figure>
+                      <div
+                        class="box"
+                        style="width: ${size}px; height: ${size}px; border-radius: var(--radius-lg)"
+                      ></div>
+                      <figcaption>${size}px</figcaption>
+                    </figure>
+                  `
+                )}
+              </div>
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'Rules',
+          children: html`
+            <div class="warn">
+              <p style="margin: 0 0 var(--spacing-8)">
+                <b>Always a token, never a literal.</b> Components used to hardcode
+                <code>2px</code>, <code>5px</code>, <code>20px</code>, <code>22px</code> and
+                <code>28px</code> as radii — none of which are steps on this scale. They are all
+                on the scale now, and <code>npm run lint:tokens</code> fails on a new one.
+              </p>
+              <p style="margin: 0 0 var(--spacing-8)">
+                <b>Never a fallback.</b> <code>var(--radius-lg, 16px)</code> appeared five times,
+                and the fallback was wrong — <code>--radius-lg</code> is
+                <b>${resolve('--radius-lg')}</b> (8px), so it claimed double. Tokens are always
+                present in document scope, so a fallback can only ever lie.
+              </p>
+              <p style="margin: 0">
+                <b>Use <code>--radius-full</code>, never <code>50%</code>.</b> They are not the
+                same shape: on a box that is not square, <code>50%</code> is an ellipse and
+                <code>--radius-full</code> is a stadium. The atom layer had six of them, and
+                <code>radius-percent</code> in <code>npm run lint:tokens</code> fails on a new
+                one.
+              </p>
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'Which step, and why',
+          meta    : 'responsibility, not proximity',
+          children: html`
+            <p>
+              A radius is a claim about what kind of thing this is. Controls run a
+              <b>size-derived ladder</b>: <code>--form-input-*-borderRadius</code> and
+              <code>--button-*-borderRadius</code> both resolve small to <code>--radius-sm</code>,
+              medium to <code>--radius-md</code> and large to <code>--radius-lg</code>, so a
+              control's corner follows its own size rather than a designer's mood.
+            </p>
+            <p>
+              <b>The card family is 16px, and it is now unanimous.</b> All eleven
+              card-shaped objects use <code>--radius-2xl</code> on a
+              <code>--spacing-32</code> inset with no resting elevation: the Card box,
+              CardFeatures, LightCarousel, Bento, the Awards feature card, the TrustPanel
+              card, the CompareSection card, the Carousel item, the Comparison Panel column
+              and both Pricing cards.
+            </p>
+            <p>
+              <b>So the shape is a role now, not an observation.</b>
+              <code>--card-radius</code> and <code>--card-padding</code> are declared in
+              <code>tokens.js</code>, and every one of the eleven asks for them by name. This
+              page used to say the family agreed; it can now say the family is checked —
+              <code>scripts/card-shapes.json</code> lists them and <code>lint:tokens</code>
+              reads it both ways, so a card that stops using the role, a rule that uses the
+              role without being a card, and a registry entry that matches nothing are all
+              findings.
+            </p>
+            <p>
+              <b>The inset has a second step, and finding that out corrected this page.</b>
+              <code>--card-padding-compact</code> is 24px, and it exists because five of the
+              eleven were already reducing their inset on small viewports — Bento, the
+              Comparison Panel, the Trust Panel, the Carousel item and LightCarousel — while
+              this page said the family held 32 everywhere. Three of them had independently
+              picked exactly 24, which is what makes it a role rather than five local
+              decisions. They now take it at the same breakpoint, below md.
+            </p>
+            <p>
+              One card is outside it and recorded: the Carousel item drops to
+              <code>--spacing-0 --spacing-20</code> below 480, which is not a smaller inset
+              but a different shape — the only card that stops insetting an axis at all.
+              That is in the registry with its reason and a review trigger, not quietly
+              tolerated. A new content card joins the family; it does not pick a corner.
+            </p>
+            <p>
+              <b>24px is not a card corner.</b> It is valid only where a responsibility or a
+              recorded decision supports it, and exactly one live case does:
+              <code>bd-img</code> and <code>bd-picture</code> expose <code>radius-3xl</code>
+              as a public variant, so the corner is the consuming page's choice. Those two
+              variants are the only <code>--radius-3xl</code> left in the package.
+            </p>
+            <p>
+              <b>Two cards used to sit outside and no longer do, and the reasons differed.</b>
+              The CompareSection card was never an exception: same surface, same inset, no
+              elevation, no interaction, no recorded reason. The Carousel item had a real
+              argument — it is draggable and its plus button opens a modal — and it was still
+              dropped, because nothing about a carousel item asks for a softer corner than the
+              same card sitting in a grid. Behaviour earns a state, a cue or a control; it does
+              not earn a different corner. Both are 16px now, and the Carousel item lost its
+              2px border to the ground-and-edge rule at the same time.
+            </p>
+            <h3 style="font-size: var(--typography-fontSize-base); margin: var(--spacing-32) 0 var(--spacing-8)">
+              Nested corners
+            </h3>
+            <p>
+              An inner corner should be smaller than the corner containing it, ideally the
+              parent's radius minus the padding between them. A child rounded more than its
+              parent either bulges past the parent's curve or, if the parent clips, is cut flat.
+            </p>
+            <p>
+              Do not reach for <code>overflow: hidden</code> to make a mismatch look right. It
+              also clips everything else that has to leave the box: a focus ring, a hover shadow,
+              a legend sitting on the border line. Terminal deliberately lets a label overlap its
+              own panel edge, and it can only do that because the panel does not clip.
+            </p>`
+        })}
+      `
+    })}
+  `;
+};
+
+export const BorderWidth = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+  const widths = tokensFor(cssText, 'border-width-');
+
+  return html`
+    ${shapeStyles}
+    ${docsPage({
+      title: 'Border width',
+      lede : html`Named after the pixel value. <code>--border-width-1</code> is the default hairline
+        for inputs, cards and dividers; <code>--border-width-2</code> is used for outline buttons
+        and focus rings.`,
+      note    : referenceNote,
+      children: refSection({
+        name    : 'Scale',
+        meta    : `${widths.length} steps · --border-width-*`,
+        children: primitiveTable({
+          caption: 'Border width scale',
+          tokens : widths,
+          consumers,
+          visual : token => html`<div class="border-chip" style="border-width: var(${token})"></div>`
+        })
+      })
+    })}
+  `;
+};