@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/tokens/dimension.stories.js

@@ -0,0 +1,251 @@
+import { html } from 'lit';
+import {
+  discoverConsumers,
+  docsPage,
+  primitiveTable,
+  readAllCssText,
+  refSection,
+  referenceNote,
+  resolve,
+  tokensFor
+} from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Dimension',
+  tags : ['autodocs']
+};
+
+const dimensionStyles = html`
+  <style>
+    .rule {
+      height: var(--spacing-12);
+      background: var(--color-blue-500);
+      border-radius: var(--radius-sm);
+      min-width: 1px;
+    }
+
+    .multiple {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-500);
+    }
+
+    .multiple[data-of4='false'] {
+      color: var(--color-neutral-900);
+      font-weight: var(--typography-fontWeight-semibold);
+    }
+
+    .callout {
+      font-size: var(--typography-fontSize-xs);
+      line-height: var(--typography-lineHeight-normal);
+      color: var(--color-neutral-700);
+      background: var(--color-neutral-50);
+      border-radius: var(--radius-md);
+      padding: var(--spacing-12) var(--spacing-16);
+    }
+
+    .callout code {
+      font-family: var(--typography-fontFamily-mono);
+    }
+
+    /* The guide line must cross the boxes at the target height, so the boxes
+       and the line share one positioned container and both sit on its floor. */
+    .target-zone {
+      position: relative;
+      padding-top: var(--spacing-24);
+      overflow-x: auto;
+    }
+
+    .target-demo {
+      display: flex;
+      align-items: flex-end;
+      gap: var(--spacing-16);
+      flex-wrap: nowrap;
+    }
+
+    .guide {
+      position: absolute;
+      left: 0;
+      right: 0;
+      border-top: var(--border-width-2) dashed var(--color-red-500);
+      pointer-events: none;
+    }
+
+    .guide span {
+      position: absolute;
+      right: 0;
+      top: calc(-1 * var(--spacing-18));
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-red-800);
+      background: var(--color-neutral-25);
+      padding: 0 var(--spacing-4);
+    }
+
+    .target {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: var(--color-blue-100);
+      border: var(--border-width-1) solid var(--color-blue-500);
+      border-radius: var(--radius-md);
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-900);
+      padding: 0 var(--spacing-8);
+      white-space: nowrap;
+    }
+
+    .target--under {
+      background: var(--color-red-50);
+      border-color: var(--color-red-500);
+    }
+
+  </style>
+`;
+
+/**
+ * Purely factual: is the value a multiple of 4?
+ *
+ * The dimension scale never claims a 4px grid — that claim belonged to the
+ * --space-* scale, which is gone. So this column
+ * reports, it does not judge. What is worth noticing is which values are not
+ * multiples of 4, and that is called out under the table.
+ */
+function multipleOfFour(value) {
+  const px = parseFloat(value);
+  if (!Number.isFinite(px)) return html``;
+  const isMultiple = px % 4 === 0;
+  return html`<span class="multiple" data-of4=${isMultiple}>${isMultiple ? 'yes' : 'no'}</span>`;
+}
+
+export const Dimensions = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+  const dimensions = tokensFor(cssText, 'dimension-');
+  const max = Math.max(...dimensions.map(token => parseFloat(resolve(token)) || 0), 1);
+
+  // any step that is not a multiple of 4 — should be empty now that the scale is aligned
+  const offGrid = dimensions
+    .map(token => ({ token, px: parseFloat(resolve(token)) || 0 }))
+    .filter(({ px }) => px % 4 !== 0);
+
+  return html`
+    ${dimensionStyles}
+    ${docsPage({
+      title: 'Dimension',
+      lede : html`Fixed sizes for control heights and icon boxes — button and input heights, icon
+        squares. Unlike spacing, these are not a rhythm scale; each value exists because a specific
+        control needs it.`,
+      note: html`The names embed the value (<code>--dimension-36</code>), so changing a value
+        means renaming the token or leaving the name lying. There is no semantic height alias
+        to prefer instead: the <code>--button-medium-*</code> family covers fontSize, padding,
+        gap and borderRadius and deliberately has no height, because buttons here are
+        padding-driven and have no height at all. Form controls are the ones with a height
+        contract, and <code>form-field.css.js</code> derives it — padding plus fontSize times
+        lineHeight — so the box and the text it holds cannot disagree. Copy that shape rather
+        than reaching for a height token. ${referenceNote}`,
+      children: html`
+        ${refSection({
+          name    : 'Scale',
+          meta    : `${dimensions.length} steps · --dimension-*`,
+          children: primitiveTable({
+            caption     : 'Dimension scale',
+            tokens      : dimensions,
+            consumers,
+            visualHeader: 'Multiple of 4',
+            visual      : (_token, value) => html`
+            <div style="display: flex; align-items: center; gap: var(--spacing-8)">
+              <div class="rule" style="width: ${((parseFloat(value) || 0) / max) * 120}px"></div>
+              ${multipleOfFour(value)}
+            </div>
+          `
+          })
+        })}
+        ${refSection({
+          name    : 'Grid alignment',
+          children: html`
+            <div class="callout">
+              <p style="margin: 0">
+                ${offGrid.length
+                  ? html`<b>${offGrid.map(({ px }) => `${px}px`).join(', ')}</b> ${offGrid.length === 1 ? 'is' : 'are'}
+                      not ${offGrid.length === 1 ? 'a multiple' : 'multiples'} of 4. Every other step is.`
+                  : html`Every step is a multiple of 4, and each token is named after its own
+                      value. The control heights were <code>34px</code>, <code>45px</code> and
+                      <code>55px</code> before this scale was aligned; they are now
+                      <code>36px</code>, <code>44px</code> and <code>56px</code>, which also puts
+                      the medium control exactly on the 44px WCAG 2.5.5 target.`}
+              </p>
+            </div>
+          `
+        })}
+      `
+    })}
+  `;
+};
+
+export const TouchTargets = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+  const touch = tokensFor(cssText, 'touch-');
+
+  const minimum = parseFloat(resolve('--touch-target-size')) || 44;
+  const controls = [
+    ['--dimension-36', 'button/input small'],
+    ['--dimension-44', 'button/input medium'],
+    ['--dimension-56', 'button/input large']
+  ];
+
+  return html`
+    ${dimensionStyles}
+    ${docsPage({
+      title: 'Touch targets',
+      lede : html`<code>--touch-target-size</code> is the minimum hit area for a pointer or finger,
+        and <code>--touch-target-spacing</code> the minimum gap between two of them.`,
+      note: html`WCAG 2.2 has two thresholds: <b>2.5.8 Target Size (Minimum)</b> is level AA and
+        asks for <b>24×24</b> CSS px; <b>2.5.5 Target Size (Enhanced)</b> is level AAA and asks for
+        <b>44×44</b>. This token encodes the AAA figure. ${referenceNote}`,
+      children: html`
+        ${refSection({
+          name    : 'Tokens',
+          meta    : `${touch.length} tokens · --touch-*`,
+          children: primitiveTable({ caption: 'Touch target tokens', tokens: touch, consumers })
+        })}
+        ${refSection({
+          name    : 'Control heights against the target',
+          meta    : `dashed line = --touch-target-size (${minimum}px)`,
+          children: html`
+            <div class="specimen">
+              <div class="target-zone">
+                <div class="target-demo">
+                  ${controls.map(([token, label]) => {
+                    const height = parseFloat(resolve(token)) || 0;
+                    const under = height < minimum;
+                    return html`
+                      <div
+                        class="target ${under ? 'target--under' : ''}"
+                        style="height: ${height}px"
+                        title="${label}"
+                      >
+                        ${height}px
+                      </div>
+                    `;
+                  })}
+                </div>
+                <div class="guide" style="bottom: ${minimum}px">
+                  <span>${minimum}px — WCAG 2.5.5 (AAA)</span>
+                </div>
+              </div>
+              <p class="docs-lede" style="margin-top: var(--spacing-16)">
+                The small control height is
+                <b>${resolve('--dimension-36')}</b>, below the ${minimum}px AAA target but above
+                the 24px AA minimum. Where a small control is the only way to perform an action,
+                give it padding or spacing so the hit area still reaches ${minimum}px.
+              </p>
+            </div>
+          `
+        })}
+      `
+    })}
+  `;
+};

package/src/tokens/elevation.stories.js

@@ -0,0 +1,143 @@
+import { html } from 'lit';
+import {
+  discoverConsumers,
+  docsPage,
+  primitiveTable,
+  readAllCssText,
+  refSection,
+  referenceNote,
+  tokensFor
+} from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Elevation',
+  tags : ['autodocs']
+};
+
+const elevationStyles = html`
+  <style>
+    .shadow-chip {
+      width: var(--spacing-64);
+      height: var(--spacing-40);
+      background: var(--color-neutral-0);
+      border-radius: var(--radius-md);
+    }
+
+    /* shadows need room around them or the blur is clipped */
+    .shadow-cell {
+      padding: var(--spacing-12) var(--spacing-8);
+    }
+
+    .ladder {
+      display: flex;
+      flex-wrap: wrap;
+      gap: var(--spacing-32);
+      background: var(--color-neutral-50);
+      padding: var(--spacing-32);
+      border-radius: var(--radius-md);
+    }
+
+    .ladder figure {
+      margin: 0;
+      text-align: center;
+    }
+
+    .ladder .card {
+      width: var(--spacing-96);
+      height: var(--spacing-64);
+      background: var(--color-neutral-0);
+      border-radius: var(--radius-lg);
+      margin-bottom: var(--spacing-8);
+    }
+
+    .ladder figcaption {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+    }
+
+    .value {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+      white-space: normal;
+      max-width: 32ch;
+      line-height: var(--typography-lineHeight-normal);
+    }
+  </style>
+`;
+
+export const Shadows = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+
+  const all = tokensFor(cssText, 'shadow-');
+  const surface = all.filter(token => !token.includes('focus'));
+  const rings = all.filter(token => token.includes('focus'));
+
+  const ladder = ['--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl', '--shadow-2xl'];
+
+  return html`
+    ${elevationStyles}
+    ${docsPage({
+      title: 'Elevation',
+      lede : html`Shadows are the only elevation mechanism in the system — there is no z-index
+        scale. <code>sm</code> through <code>2xl</code> form a ladder;
+        <code>--shadow-inner</code> is an inset press state.`,
+      note    : referenceNote,
+      children: html`
+        ${refSection({
+          name    : 'Surface shadows',
+          meta    : `${surface.length} tokens · --shadow-*`,
+          children: primitiveTable({
+            caption     : 'Surface shadow tokens',
+            tokens      : surface,
+            consumers,
+            valueClass  : 'value',
+            visualHeader: 'Preview',
+            visual      : token =>
+              html`<div class="shadow-cell">
+                <div class="shadow-chip" style="box-shadow: var(${token})"></div>
+              </div>`
+          })
+        })}
+        ${refSection({
+          name    : 'The ladder on a tinted surface',
+          meta    : 'sm → 2xl',
+          children: html`
+            <div class="ladder">
+              ${ladder.map(
+                token => html`
+                  <figure>
+                    <div class="card" style="box-shadow: var(${token})"></div>
+                    <figcaption>${token.replace('--shadow-', '')}</figcaption>
+                  </figure>
+                `
+              )}
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'Focus ring shadows',
+          meta    : `${rings.length} tokens · --shadow-focus-outline-*`,
+          children: html`
+            <p class="docs-lede">
+              Soft 3px rings at 15% alpha. These are decorative glows, not accessible focus
+              indicators — see the <b>Focus</b> page for the rings that meet contrast requirements.
+            </p>
+            ${primitiveTable({
+              caption   : 'Focus ring shadow tokens',
+              tokens    : rings,
+              consumers,
+              valueClass: 'value',
+              visual    : token =>
+                html`<div class="shadow-cell">
+                  <div class="shadow-chip" style="box-shadow: var(${token})"></div>
+                </div>`
+            })}
+          `
+        })}
+      `
+    })}
+  `;
+};

package/src/tokens/focus.stories.js

@@ -0,0 +1,276 @@
+import { html } from 'lit';
+import {
+  INK,
+  PAPER,
+  contrast,
+  discoverConsumers,
+  docsPage,
+  levelBadge,
+  primitiveTable,
+  readAllCssText,
+  refSection,
+  referenceNote,
+  resolve,
+  tokensFor
+} from './story-chrome.js';
+
+export default {
+  title: 'Foundations/Focus',
+  tags : ['autodocs']
+};
+
+const focusStyles = html`
+  <style>
+    .rule-note {
+      margin: 0 0 var(--spacing-12);
+      font-size: var(--typography-fontSize-sm);
+      line-height: var(--typography-lineHeight-normal);
+      color: var(--color-neutral-900);
+    }
+
+    .rule-note:last-child { margin-bottom: 0; }
+
+    .rule-code {
+      margin: 0 0 var(--spacing-16);
+      padding: var(--spacing-12) var(--spacing-16);
+      background: var(--color-neutral-50);
+      border-radius: var(--radius-md);
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xs);
+      line-height: var(--typography-lineHeight-relaxed);
+      overflow-x: auto;
+    }
+    .focus-demo {
+      display: flex;
+      flex-wrap: wrap;
+      gap: var(--spacing-24);
+      align-items: center;
+    }
+
+    .focus-demo--dark {
+      background: var(--color-neutral-900);
+      padding: var(--spacing-24);
+      border-radius: var(--radius-md);
+    }
+
+    /* Rings are shown permanently so they can be compared without tabbing. */
+    .ring {
+      font-family: var(--typography-fontFamily-sans);
+      font-size: var(--typography-fontSize-sm);
+      font-weight: var(--typography-fontWeight-medium);
+      padding: var(--spacing-8) var(--spacing-16);
+      border: var(--border-width-1) solid var(--color-neutral-300);
+      border-radius: var(--radius-md);
+      background: var(--color-neutral-0);
+      color: var(--color-neutral-900);
+    }
+
+    .ring-label {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+      display: block;
+      margin-bottom: var(--spacing-6);
+    }
+
+    .focus-demo--dark .ring-label {
+      color: var(--color-neutral-300);
+    }
+
+    /* A genuinely interactive control, so the real :focus-visible can be tested. */
+    .try-me {
+      font: inherit;
+      font-size: var(--typography-fontSize-sm);
+      padding: var(--spacing-8) var(--spacing-16);
+      border: var(--border-width-1) solid var(--color-neutral-300);
+      border-radius: var(--radius-md);
+      background: var(--color-neutral-0);
+      cursor: pointer;
+    }
+
+    .try-me:focus-visible {
+      outline: var(--focus-outline-traditional);
+      outline-offset: var(--focus-outline-offset);
+    }
+
+    .try-me--shadow:focus-visible {
+      outline: none;
+      box-shadow: var(--focus-outline-primary);
+    }
+
+    .value {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+      white-space: normal;
+      max-width: 34ch;
+      line-height: var(--typography-lineHeight-normal);
+    }
+  </style>
+`;
+
+export const FocusRings = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+  const tokens = tokensFor(cssText, 'focus-');
+
+  // -offset and -radius are lengths, not rings; they would render as empty swatches
+  const NOT_RINGS = ['--focus-outline-offset', '--focus-outline-radius'];
+  const rings = tokens.filter(token => token.startsWith('--focus-outline-') && !NOT_RINGS.includes(token));
+  const ringColour = resolve('--color-blue-500');
+  const onLight = contrast(ringColour, PAPER);
+  const onDark = contrast(ringColour, INK);
+
+  return html`
+    ${focusStyles}
+    ${docsPage({
+      title: 'Focus',
+      lede : html`<code>--focus-outline-primary</code> is <b>the</b> focus ring — every interactive
+          component uses it and none define their own. It is a two-colour ring: an
+        inner band of <code>--color-neutral-0</code> and an outer band of the state colour. The
+        inner band is what makes the ring visible on both light and dark backgrounds.
+        <br /><br />
+        The ring is a <code>box-shadow</code>, so it already follows the radius of whatever it
+        sits on — a component with its own radius should set nothing and let the ring take its
+        shape. <code>--focus-outline-radius</code> is the default for the ones that have no
+        radius of their own, so the ring is not a hard rectangle around a link or a tab.`,
+      note: html`WCAG 2.2 <b>1.4.11 Non-text Contrast</b> asks for <b>3:1</b> between a focus
+        indicator and its adjacent background. The blue ring is
+        ${onLight.toFixed(2)}${levelBadge(onLight)} on white and
+        ${onDark.toFixed(2)}${levelBadge(onDark)} on <code>--color-neutral-900</code> — which is
+        exactly why the white inner band matters on dark surfaces. ${referenceNote}`,
+      children: html`
+        ${refSection({
+          name    : 'The rule',
+          meta    : 'one ring, every interactive component',
+          children: html`
+            <div class="specimen">
+              <p class="rule-note">
+                Every interactive component shows the same ring on keyboard focus,
+                and it is two lines:
+              </p>
+              <pre class="rule-code"><code>.control:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-outline-primary);
+}</code></pre>
+              <p class="rule-note">
+                <b>Always <code>:focus-visible</code>, never <code>:focus</code>.</b>
+                <code>:focus</code> fires on a mouse click too, which rings
+                something the user just clicked. The browser already decides
+                keyboard modality — do not reimplement it. bd-button used to,
+                with two requestAnimationFrame hops and a data attribute.
+              </p>
+              <p class="rule-note">
+                <b>Never suppress it without replacing it.</b>
+                <code>outline: none</code> on its own removes the only cue a
+                keyboard user has for where they are, which fails WCAG 2.4.7. Two
+                accordion triggers did exactly that.
+              </p>
+              <p class="rule-note">
+                <b>Text fields are the one exception.</b> Inputs, textareas and
+                selects keep the field border and add
+                <code>--shadow-focus-outline-blue</code> as a glow, because an
+                offset ring around a full-width field reads as a second border.
+                Everything else you can operate — buttons, links, checkboxes,
+                radios, switches, tabs, accordion triggers, the scrollable code
+                block — uses the ring.
+              </p>
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'Tokens',
+          meta    : `${tokens.length} tokens · --focus-*`,
+          children: primitiveTable({
+            caption   : 'Focus tokens',
+            tokens,
+            consumers,
+            valueClass: 'value'
+          })
+        })}
+        ${refSection({
+          name    : 'On a light surface',
+          meta    : 'rings shown permanently for comparison',
+          children: html`
+            <div class="specimen">
+              <div class="focus-demo">
+                ${rings.map(
+                  token => html`
+                    <div>
+                      <span class="ring-label">${token.replace('--focus-outline-', '')}</span>
+                      <div class="ring" style="box-shadow: var(${token})">Button</div>
+                    </div>
+                  `
+                )}
+              </div>
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'On a dark surface',
+          meta    : 'the white inner band keeps the ring readable',
+          children: html`
+            <div class="focus-demo focus-demo--dark">
+              ${rings.map(
+                token => html`
+                  <div>
+                    <span class="ring-label">${token.replace('--focus-outline-', '')}</span>
+                    <div class="ring" style="box-shadow: var(${token})">Button</div>
+                  </div>
+                `
+              )}
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'Try it',
+          meta    : 'tab to these — real :focus-visible, not a simulation',
+          children: html`
+            <div class="specimen">
+              <div class="focus-demo">
+                <button class="try-me">outline (traditional)</button>
+                <button class="try-me try-me--shadow">box-shadow (two-colour)</button>
+              </div>
+            </div>
+          `
+        })}
+        ${refSection({
+          name    : 'The ring owns its corner',
+          meta    : 'one place to change it',
+          children: html`
+            <p>
+              The ring is a <code>box-shadow</code>, so it already follows the corner of whatever
+              it is on. <code>--focus-outline-radius</code> is for the elements that have no
+              corner of their own, and it is the only place a standard ring should get one.
+              Five components used to set <code>--radius-lg</code> here instead, so the same
+              indicator drew an 8px corner in five places and a 4px corner in fifteen. They
+              resolve through the role now, which makes the radius one decision in one place
+              rather than five — <code>focus-radius-bypass</code> in
+              <code>npm run lint:tokens</code> fails on a new one.
+            </p>
+            <p>
+              <b>The exception is shape, not preference.</b> A circular control needs a circular
+              ring, so <code>--radius-full</code> and <code>50%</code> are allowed and the
+              AwardsFlex dot uses one. The rule knows about that case; a new kind of exception
+              belongs in the rule with a self-test, not in a comment.
+            </p>
+            <p>
+              <b>A ring that is clipped is not an indicator.</b> It is drawn outside the box, so
+              an ancestor with <code>overflow: hidden</code> can cut it off entirely while every
+              static check still passes. Leave at least 4px of room inside any clipping ancestor,
+              or move the clipping.
+            </p>
+            <p>
+              <b>Verify with the keyboard, not with code.</b> Calling
+              <code>element.focus()</code> does not reliably match
+              <code>:focus-visible</code>, so a programmatic check can report a ring that a
+              reader never sees — and can equally miss one that is broken. Press Tab. Two real
+              defects in this package were invisible to programmatic focus and obvious to a
+              keyboard: the header's ring never reached its slotted links, and one accordion
+              variant drew a different colour from the other.
+            </p>`
+        })}
+      `
+    })}
+  `;
+};