@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/tokens/spacing-rhythm.stories.js

@@ -0,0 +1,359 @@
+import { html } from 'lit';
+import { docsPage, refSection } from './story-chrome.js';
+/* The registry itself, not a copy of it — the same rule the typography pages
+   follow. A table transcribed by hand drifts from the thing it documents the
+   first time either one changes. */
+import sizeSites from '../../scripts/spacing-as-size.json';
+
+import '../components/cards/card.js';
+import '../components/heading/heading.js';
+import '../components/paragraph/paragraph.js';
+
+export default {
+  title: 'Foundations/Spacing/Rhythm',
+  tags : ['autodocs']
+};
+
+/* ------------------------------------------------------------------ chrome - */
+
+/* A relationship, shown rather than described: two real elements with the token
+   between them, and the measurement beside it. The samples are built from the
+   tokens, so a token change moves the sample with it. */
+const relationship = ({ name, kind, token, measured, responsibility, exceptions, avoid, sample }) => html`
+  <div style="padding:var(--spacing-24) 0;border-top:var(--border-width-1) solid var(--color-border-subtle)">
+    <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)">
+      <b style="color:var(--color-text-primary)">${name}</b>
+      · ${kind}
+      · <code>${token}</code>
+      · measured ${measured}
+    </p>
+    <p style="margin:0 0 var(--spacing-16);color:var(--color-text-secondary);max-width:70ch">
+      ${responsibility}
+    </p>
+    <div style="background:var(--color-surface-muted);padding:var(--spacing-24);border-radius:var(--radius-lg);margin-bottom:var(--spacing-16)">
+      ${sample}
+    </div>
+    <p style="margin:0 0 var(--spacing-4);font-size:var(--typography-fontSize-sm);max-width:70ch">
+      <b>Legitimate exceptions.</b> ${exceptions}
+    </p>
+    <p style="margin:0;font-size:var(--typography-fontSize-sm);color:var(--color-text-secondary);max-width:70ch">
+      <b>Do not reach for it when…</b> ${avoid}
+    </p>
+  </div>`;
+
+/* ------------------------------------------------------- the relationships - */
+
+const RELATIONSHIPS = [
+  {
+    name          : 'card inset',
+    kind          : 'OBSERVED COMPONENT-FAMILY CONTRACT',
+    token         : '--spacing-32',
+    measured      : '32/32/32/32 in 38 places',
+    responsibility: `The padding between a self-contained object and its own contents. Every
+                     card in the family agrees on it: Card, CardFeatures, LightCarousel, Bento,
+                     the Awards card and the Trust Panel card all measure 32 on all four sides.`,
+    exceptions: html`Panels that are not cards. The Terminal panel measures 20/20/28/20 —
+                     asymmetric because its content is a scrolling transcript with its own
+                     bottom affordance.`,
+    avoid: html`…the object is not self-contained. A row inside a table is bounded by
+                     the table, not by itself, and takes the table's cell padding.`,
+    sample: html`
+      <bd-card-item title="Machine Learning">
+        <bd-p variant="small">32px on every side, and no resting shadow.</bd-p>
+      </bd-card-item>`
+  },
+  {
+    name          : 'item title → its content',
+    kind          : 'OBSERVED COMPONENT-FAMILY CONTRACT',
+    token         : '--spacing-8',
+    measured      : '8px, 9 components',
+    responsibility: `The gap between the title of one item — a card, a step, a feature — and the
+                     copy underneath it. The pair reads as one object, so the gap is small enough
+                     to bind them.`,
+    exceptions: html`The Trust Panel card measures 12 for exactly this relationship at
+                     exactly this type size. See the unresolved section below.`,
+    avoid: html`…the title labels a region of the page rather than one object. That is
+                     the section relationship, and it is 16.`,
+    sample: html`
+      <bd-h as="h3" visual-level="h5" fontWeight="bold" paddingBottom="8">Machine Learning</bd-h>
+      <bd-p variant="small">Behaviour learned from millions of daily threats.</bd-p>`
+  },
+  {
+    name          : 'section title → its content',
+    kind          : 'OBSERVED COMPONENT-FAMILY CONTRACT',
+    token         : '--spacing-16',
+    measured      : '16px, 7 components',
+    responsibility: `The gap between the title of a page section and the standfirst or content
+                     it introduces. Larger than the item gap because the title is anchoring a
+                     region rather than labelling an object.`,
+    exceptions: html`Compatibility Table and Process Steps measure 12 for this relationship
+                     at identical type sizes. See below.`,
+    avoid: html`…the title belongs to one card. Copying the section value into a card
+                     is how a 36px title and a 20px title came to share a gap.`,
+    sample: html`
+      <bd-h as="h2" visual-level="h2" paddingBottom="16">What is AI Guardian?</bd-h>
+      <bd-p variant="small">The standfirst that introduces the region below it.</bd-p>`
+  },
+  {
+    name          : 'icon ↔ text',
+    kind          : 'OBSERVED COMPONENT-FAMILY CONTRACT',
+    token         : '--spacing-16',
+    measured      : '16px in 18 places, 12px in 9',
+    responsibility: `The horizontal distance between a glyph and the text it belongs to. 16 is
+                     the majority; 12 is the denser variant, and both occur inside single
+                     components, so this is the least settled of the horizontal relationships.`,
+    exceptions: html`Dense rows — the Comparison Panel's icon list runs at 12 because its
+                     rows are a scan target rather than reading matter.`,
+    avoid: html`…the icon is the control. A button's glyph is inset by the button's own
+                     padding, not by this gap.`,
+    sample: html`
+      <div style="display:flex;align-items:center;gap:var(--spacing-16)">
+        <span style="width:var(--spacing-20);height:var(--spacing-20);border-radius:var(--radius-full);background:var(--color-blue-500);flex-shrink:0"></span>
+        <bd-p variant="small">16px from the glyph to the text it belongs to.</bd-p>
+      </div>`
+  },
+  {
+    name          : 'label → control',
+    kind          : 'FOUNDATION TOKEN',
+    token         : '--form-label-*-marginBottom',
+    measured      : '4px',
+    responsibility: `The only one of these relationships that is already a token rather than an
+                     observation: the form label tokens carry their own marginBottom, so the
+                     label and the control cannot drift apart component by component.`,
+    exceptions: html`None measured. Every form label in the package resolves through the
+                     same tokens.`,
+    avoid: html`…the text under a control is help text rather than a label. That is a
+                     different relationship with a different owner.`,
+    sample: html`
+      <div>
+        <label style="display:block;margin-bottom:var(--form-label-default-marginBottom);font-size:var(--form-label-default-fontSize);font-weight:var(--form-label-default-fontWeight);color:var(--form-label-default-color)">Email address</label>
+        <input style="display:block;width:100%;max-width:320px;box-sizing:border-box;padding:var(--spacing-12);border:var(--border-width-1) solid var(--color-border-subtle);border-radius:var(--radius-lg);font:inherit" />
+      </div>`
+  }
+];
+
+/* --------------------------------------------------------------- the page - */
+
+const SIZE_ROWS = Object.entries(sizeSites.sites);
+
+export const SpacingRhythm = () =>
+  docsPage({
+    title: 'Spacing rhythm',
+    lede : `The distances between things, as opposed to the scale the distances come from.
+            Foundations/Spacing lists the steps; this page is about which step means which
+            relationship, and which relationships the package has actually agreed on.`,
+    note: html`<b>Three different kinds of thing appear on this page, and only one of them is
+            a token.</b><br />
+            A <b>FOUNDATION TOKEN</b> is declared in <code>tokens.js</code> and a component
+            asks for it by name.
+            An <b>OBSERVED COMPONENT-FAMILY CONTRACT</b> is a value several components
+            independently agree on, measured rather than declared — it is documentation, and
+            nothing enforces it.
+            A <b>SEMANTIC SPACING ROLE</b> would be a named token for a relationship
+            (<code>--stack-tight</code>, <code>--inset-card</code>). <b>There are none, and
+            that is deliberate:</b> forty-nine of them were declared here once —
+            <code>--space-*</code>, <code>--inset-*</code>, <code>--stack-*</code>,
+            <code>--inline-*</code> and more — and every one was a duplicate of a live scale
+            under a different name with no component referencing it. They were deleted. The
+            8 and 16 below are <i>observations</i>, not a proposal to declare them again.`,
+    children: html`
+      ${refSection({
+        name    : 'Relationships the package agrees on',
+        meta    : `${RELATIONSHIPS.length} relationships, measured against the built Storybook`,
+        children: html`
+        <p style="max-width:70ch">
+          Each block gives the responsibility, the value measured across the components that
+          share it, a rendered example built from the tokens, and — the part that stops a
+          contract turning into a rule — where it legitimately does not apply.
+        </p>
+        ${RELATIONSHIPS.map(relationship)}`
+      })}
+
+      ${refSection({
+        name    : 'The unresolved 12',
+        meta    : 'classified, not resolved',
+        children: html`
+        <p style="border-left:var(--border-width-4) solid var(--color-border-brand);padding-left:var(--spacing-16);max-width:70ch">
+          <b>Three components use 12 where their peers use 8 or 16, and the type is identical
+          in every case.</b> That rules out the explanation that would have made 12 a third
+          responsibility: there is no size difference for the extra 4px to be compensating for.
+        </p>
+        <div class="table-scroll">
+          <table>
+            <caption>
+              Every title → its own description pair in the package, measured at 1440.
+              Optical ratio is (gap + half-leading either side) ÷ title size — the metric that
+              showed the 8 and 16 tiers are closer than their declared values look.
+            </caption>
+            <thead>
+              <tr>
+                <th scope="col">Component</th>
+                <th scope="col">Level</th>
+                <th scope="col">Gap</th>
+                <th scope="col">Title</th>
+                <th scope="col">Leading</th>
+                <th scope="col">Ratio</th>
+              </tr>
+            </thead>
+            <tbody>
+              ${[
+                ['Agent Endpoints', 'section', 16, 36, 49.5, 0.743, false],
+                ['Comparison Panel', 'section', 16, 36, 49.5, 0.743, false],
+                ['Trust Panel', 'section', 16, 36, 49.5, 0.743, false],
+                ['Compatibility Table', 'section', 12, 36, 49.5, 0.632, true],
+                ['Process Steps', 'section', 12, 36, 49.5, 0.632, true],
+                ['Trust Panel card', 'item', 12, 24, 33, 0.854, true],
+                ['Process Steps step', 'item', 8, 24, 33, 0.688, false]
+              ].map(([c, lv, gap, size, lh, ratio, odd]) => html`
+                <tr style="${odd ? 'background:var(--color-surface-muted)' : ''}">
+                  <td>${odd ? html`<b>${c}</b>` : c}</td>
+                  <td>${lv}</td>
+                  <td class="num">${gap}px</td>
+                  <td class="num">${size}px</td>
+                  <td class="num">${lh}px</td>
+                  <td class="num">${ratio}</td>
+                </tr>`)}
+            </tbody>
+          </table>
+        </div>
+        <h3 style="font-size:var(--typography-fontSize-base);margin:var(--spacing-32) 0 var(--spacing-8)">
+          Classification: drift, in two directions, and not a third tier
+        </h3>
+        <p style="max-width:70ch">
+          <b>Compatibility Table and Process Steps section titles — drift toward 16.</b> Same
+          relationship, same 36px title at the same 49.5px leading, same 16px description as
+          the three components that use 16. Nothing distinguishes them but the number.
+        </p>
+        <p style="max-width:70ch">
+          <b>Trust Panel card title — drift toward 8.</b> Same relationship as the Process
+          Steps step title at the same 24px and the same 33px leading. At 0.854 it is the
+          loosest heading-to-body relationship measured anywhere in the package.
+        </p>
+        <p style="max-width:70ch">
+          <b>How it happened is visible in the pairs.</b> Trust Panel runs 16 at section level
+          and 12 in its card; Process Steps runs 12 at section level and 8 in its step. Each
+          component steps down by exactly 4px inside itself, so each is internally coherent —
+          the two ladders simply start a rung apart. That is why neither looks wrong on its
+          own screen, and why this was invisible until they were measured side by side.
+        </p>
+        <p style="max-width:70ch">
+          <b>Nothing here has been changed.</b> The measurements establish that the components
+          disagree; they do not establish which value is right, and a majority is not an
+          argument — this package already learned that when one section title meant 48, 36, 32
+          and 24 at once. Converging them is a design decision about three visible section
+          headers, recorded here rather than made quietly. <b>It is not a case for a token:</b>
+          a semantic role for a relationship whose value is under dispute would freeze the
+          dispute rather than settle it.
+        </p>`
+      })}
+
+      ${refSection({
+        name    : 'Responsive density',
+        meta    : 'three cases, none of them drift',
+        children: html`
+        <p style="max-width:70ch">
+          A gap that changes with the viewport is usually density. Three cases looked like
+          something else when read from the declared values alone, and all three turned out to
+          be a layout changing rather than a value drifting — which is the reason a spacing
+          rule cannot be written against declared numbers.
+        </p>
+        <div class="table-scroll">
+          <table>
+            <caption>Gaps that change across the breakpoints, and what is actually changing</caption>
+            <thead>
+              <tr>
+                <th scope="col">Where</th>
+                <th scope="col">Measured</th>
+                <th scope="col">What it is</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Awards intro</td>
+                <td class="num">8 → 16 at sm</td>
+                <td>Density. One relationship, loosened once there is room for it.</td>
+              </tr>
+              <tr>
+                <td>Header container</td>
+                <td class="num">32 below 1024, 30 above</td>
+                <td>
+                  Two layouts, not one value. Below 1024 it is a column stack and the gap is
+                  vertical; above it, a two-column grid and the gap is horizontal. Different
+                  axis, different relationship. <b>30px is off the scale</b> and 32 is on it —
+                  that is raw-literal debt, not a responsive anomaly.
+                </td>
+              </tr>
+              <tr>
+                <td>Footer links</td>
+                <td class="num">8 → 0 → 32</td>
+                <td>
+                  Three layouts. Mobile is a column at 8; 768–1024 is a column at
+                  <code>gap: 0</code> because a <code>bd-divider-horizontal</code> with 16px
+                  margins sits between the groups and carries the separation itself; desktop is
+                  a row at 32. The zero is correct — using both the gap and the divider would
+                  count the distance twice.
+                </td>
+              </tr>
+              <tr>
+                <td>Pricing Cards</td>
+                <td class="num">52 → 24 at xl</td>
+                <td>
+                  <b>PRODUCT_FROZEN.</b> Pricing Cards runs its own em-derived scale off the
+                  token scale entirely; its architecture is frozen by product decision and is
+                  reported rather than migrated, as with its typography.
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>`
+      })}
+
+      ${refSection({
+        name    : 'Spacing steps used as sizes',
+        meta    : `${SIZE_ROWS.length} registered sites · scripts/spacing-as-size.json`,
+        children: html`
+        <p style="border-left:var(--border-width-4) solid var(--color-border-brand);padding-left:var(--spacing-16);max-width:70ch">
+          <b><code>--spacing-*</code> is rem and <code>--dimension-*</code> is px.</b>
+          They carry the same numbers and are not the same value: <code>--spacing-44</code>
+          renders 44px at a 16px root and <b>66px at a 24px root</b>, where
+          <code>--dimension-44</code> is 44px at both.
+        </p>
+        <p style="max-width:70ch">
+          So a spacing step used as a size is not simply the wrong category name. Renaming it
+          is a decision to stop that box growing when a reader enlarges their text — measured
+          on the carousel arrow, a <code>role="button"</code> target that would go from 66px
+          back to 44px for exactly the reader a larger target helps. The question at each site
+          is <b>should this box grow when the reader's text grows</b>, and
+          <code>skeleton.css.js</code> answers it both ways in one file: the bone standing in
+          for a line of text is <code>--spacing-16</code>, and the avatar circle two rules
+          below is <code>--dimension-40</code>.
+        </p>
+        <div class="table-scroll">
+          <table>
+            <caption>
+              Read from scripts/spacing-as-size.json at build time, so this table cannot drift
+              from what lint:tokens enforces. An entry whose token stops appearing in its file
+              is reported as spacing-as-size-stale.
+            </caption>
+            <thead>
+              <tr>
+                <th scope="col">Site</th>
+                <th scope="col">Step</th>
+                <th scope="col">Kind</th>
+                <th scope="col">Why it stays</th>
+              </tr>
+            </thead>
+            <tbody>
+              ${SIZE_ROWS.map(([name, s]) => html`
+                <tr>
+                  <td><code>${name}</code><br /><span style="color:var(--color-text-muted)">${s.file.split('/').pop()}</span></td>
+                  <td class="num">${s.token.replace('--spacing-', '')}</td>
+                  <td class="num">${s.kind}</td>
+                  <td>${s.reason}</td>
+                </tr>`)}
+            </tbody>
+          </table>
+        </div>`
+      })}
+    `
+  });