@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/tokens/spacing.stories.js

@@ -1,723 +1,228 @@
 import { html } from 'lit';
+import {
+  copyToken,
+  discoverConsumers,
+  discoverTokens,
+  docsPage,
+  readAllCssText,
+  refSection,
+  resolve,
+  usageCell
+} from './story-chrome.js';
 
 export default {
-  title: 'Design Tokens/Spacing',
-  tags : ['autodocs'],
-
-  args: {
-    spaceNone: 'var(--space-none, 0)',
-    space4xs : 'var(--space-4xs, 0.125rem)',
-    space3xs : 'var(--space-3xs, 0.25rem)',
-    space2xs : 'var(--space-2xs, 0.5rem)',
-    spaceXs  : 'var(--space-xs, 0.75rem)',
-    spaceSm  : 'var(--space-sm, 1rem)',
-    spaceMd  : 'var(--space-md, 1.5rem)',
-    spaceLg  : 'var(--space-lg, 2rem)',
-    spaceXl  : 'var(--space-xl, 2.5rem)',
-    space2xl : 'var(--space-2xl, 3rem)',
-    space3xl : 'var(--space-3xl, 4rem)',
-    space4xl : 'var(--space-4xl, 6rem)',
-    space5xl : 'var(--space-5xl, 8rem)'
-  },
-
-  argTypes: {
-    spaceNone: {
-      control    : 'text',
-      name       : '--space-none',
-      description: 'No spacing (0)',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '0' }
-      }
-    },
-    space4xs: {
-      control    : 'text',
-      name       : '--space-4xs',
-      description: 'Extra extra extra small spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '0.125rem (2px)' }
-      }
-    },
-    space3xs: {
-      control    : 'text',
-      name       : '--space-3xs',
-      description: 'Extra extra small spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '0.25rem (4px)' }
-      }
-    },
-    space2xs: {
-      control    : 'text',
-      name       : '--space-2xs',
-      description: 'Extra small spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '0.5rem (8px)' }
-      }
-    },
-    spaceXs: {
-      control    : 'text',
-      name       : '--space-xs',
-      description: 'Extra small spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '0.75rem (12px)' }
-      }
-    },
-    spaceSm: {
-      control    : 'text',
-      name       : '--space-sm',
-      description: 'Small spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '1rem (16px)' }
-      }
-    },
-    spaceMd: {
-      control    : 'text',
-      name       : '--space-md',
-      description: 'Medium spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '1.5rem (24px)' }
-      }
-    },
-    spaceLg: {
-      control    : 'text',
-      name       : '--space-lg',
-      description: 'Large spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '2rem (32px)' }
-      }
-    },
-    spaceXl: {
-      control    : 'text',
-      name       : '--space-xl',
-      description: 'Extra large spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '2.5rem (40px)' }
-      }
-    },
-    space2xl: {
-      control    : 'text',
-      name       : '--space-2xl',
-      description: 'Extra extra large spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '3rem (48px)' }
-      }
-    },
-    space3xl: {
-      control    : 'text',
-      name       : '--space-3xl',
-      description: 'Extra extra extra large spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '4rem (64px)' }
-      }
-    },
-    space4xl: {
-      control    : 'text',
-      name       : '--space-4xl',
-      description: 'Huge spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '6rem (96px)' }
-      }
-    },
-    space5xl: {
-      control    : 'text',
-      name       : '--space-5xl',
-      description: 'Extra huge spacing',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '8rem (128px)' }
-      }
-    }
-  },
-
-  parameters: {
-    docs: {
-      description: {
-        component: `
-# Spacing Design Tokens
-
-Consistent spacing system using CSS custom properties for margin, padding, and gaps.
-
-## Overview
-
-The spacing system provides a consistent scale of spacing values based on rem units. Using CSS custom properties ensures consistency across the entire application and makes responsive design easier.
-
-## Spacing Scale
-
-The system follows a t-shirt size naming convention (xs, sm, md, lg, xl) with additional granularity for smaller increments.
-
-## Usage
-
-### Direct CSS Custom Properties
-\`\`\`css
-/* Using spacing tokens */
-.element {
-  margin: var(--space-md);
-  padding: var(--space-sm) var(--space-lg);
-  gap: var(--space-xs);
-}
-
-/* Multiple values */
-.container {
-  padding: var(--space-sm) var(--space-md) var(--space-lg) var(--space-xl);
-}
-
-/* Specific properties */
-.card {
-  margin-top: var(--space-2xl);
-  margin-bottom: var(--space-lg);
-}
-\`\`\`
-
-### In Component Properties
-\`\`\`html
-<style>
-  .custom-component {
-    --component-padding: var(--space-md);
-    --component-gap: var(--space-sm);
-  }
-</style>
-\`\`\`
-
-## Spacing Tokens Reference
-
-| Token | Value (rem) | Value (px) | Use Case |
-|-------|-------------|------------|----------|
-| \`--space-none\` | 0 | 0px | No spacing, reset margins/padding |
-| \`--space-4xs\` | 0.125rem | 2px | Minimal spacing, tight layouts |
-| \`--space-3xs\` | 0.25rem | 4px | Small spacing, icon padding |
-| \`--space-2xs\` | 0.5rem | 8px | Compact spacing, dense UI |
-| \`--space-xs\` | 0.75rem | 12px | Standard small spacing |
-| \`--space-sm\` | 1rem | 16px | Small spacing, component padding |
-| \`--space-md\` | 1.5rem | 24px | Medium spacing, default gap |
-| \`--space-lg\` | 2rem | 32px | Large spacing, section margins |
-| \`--space-xl\` | 2.5rem | 40px | Extra large spacing |
-| \`--space-2xl\` | 3rem | 48px | Page section spacing |
-| \`--space-3xl\` | 4rem | 64px | Large section spacing |
-| \`--space-4xl\` | 6rem | 96px | Hero section spacing |
-| \`--space-5xl\` | 8rem | 128px | Maximum spacing, full page |
-
-## Base Unit
-
-The system uses **rem** units based on the root font size (typically 16px). This ensures:
-
-1. **Accessibility**: Respects user's browser font size settings
-2. **Consistency**: Maintains proportional relationships
-3. **Responsive**: Scales appropriately across breakpoints
-
-## Best Practices
-
-### 1. Use Tokens Consistently
-\`\`\`css
-/* Good ✅ */
-margin: var(--space-md);
-padding: var(--space-sm);
-
-/* Bad ❌ */
-margin: 16px;
-padding: 1rem;
-\`\`\`
-
-### 2. Combine Tokens for Complex Spacing
-\`\`\`css
-/* Multi-direction spacing */
-.element {
-  margin: var(--space-sm) var(--space-md);
-  padding: var(--space-xs) var(--space-lg);
-}
-
-/* Stacking with gap */
-.grid {
-  display: grid;
-  gap: var(--space-md);
-}
-\`\`\`
-
-### 3. Responsive Spacing
-\`\`\`css
-.container {
-  padding: var(--space-sm);
-  
-  @media (min-width: 768px) {
-    padding: var(--space-md);
-  }
-  
-  @media (min-width: 1024px) {
-    padding: var(--space-lg);
-  }
-}
-\`\`\`
-
-### 4. Semantic Spacing
-\`\`\`css
-:root {
-  /* Define semantic spacing for components */
-  --button-padding: var(--space-xs) var(--space-sm);
-  --card-padding: var(--space-md);
-  --section-margin: var(--space-xl);
-  --form-gap: var(--space-sm);
-}
-\`\`\`
-
-## Examples
-
-### Button Spacing
-\`\`\`css
-.button {
-  padding: var(--space-xs) var(--space-sm);
-  margin-right: var(--space-xs);
-}
-\`\`\`
-
-### Card Layout
-\`\`\`css
-.card {
-  padding: var(--space-md);
-  margin-bottom: var(--space-lg);
-}
-
-.card-content {
-  margin-top: var(--space-sm);
-}
-\`\`\`
-
-### Grid System
-\`\`\`css
-.grid-container {
-  display: grid;
-  gap: var(--space-md);
-  padding: var(--space-lg);
-}
-
-.grid-item {
-  margin-bottom: var(--space-sm);
-}
-\`\`\`
-
-### Form Layout
-\`\`\`css
-.form-group {
-  margin-bottom: var(--space-md);
-}
-
-.form-label {
-  margin-bottom: var(--space-xs);
-}
-
-.form-input {
-  padding: var(--space-xs) var(--space-sm);
-}
-\`\`\`
-
-## Browser Support
-
-CSS Custom Properties are supported in:
-- Chrome 49+
-- Firefox 31+
-- Safari 9.1+
-- Edge 16+
-
-For older browsers, provide fallbacks:
-\`\`\`css
-.element {
-  margin: 1rem; /* Fallback */
-  margin: var(--space-sm);
-}
-\`\`\`
-
-## Testing Visual Balance
-
-Use the visualizer in this story to ensure spacing creates proper visual hierarchy and breathing room between elements. Each token is demonstrated with its actual spacing applied as padding.
-        `
-      }
-    }
-  }
+  title: 'Foundations/Spacing',
+  tags : ['autodocs']
 };
 
-export const AllSpacings = (args) => html`
+const barStyles = html`
   <style>
-    :root {
-      --color-neutral-100: #f8f9fa;
-      --color-neutral-200: #e9ecef;
-      --color-neutral-300: #dee2e6;
-      --color-primary: #007bff;
-    }
-    
-    .spacing-container {
-      max-width: 800px;
-      margin: 0 auto;
-      padding: var(--space-lg);
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .spacing-header {
-      margin-bottom: var(--space-xl);
-      padding-bottom: var(--space-sm);
-      border-bottom: 2px solid var(--color-neutral-300);
+    .bar-cell {
+      width: 40%;
+      min-width: 180px;
     }
-    
-    .spacing-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 1.5rem;
-      font-weight: 600;
-      color: #212529;
-      margin: 0 0 var(--space-xs) 0;
-    }
-    
-    .spacing-subtitle {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 0.9rem;
-      color: #6c757d;
-      margin: 0;
-    }
-    
-    .spacing-box {
-      background-color: var(--color-neutral-200);
-      margin-bottom: var(--space-md);
-      border-radius: 4px;
-      border: 1px dashed var(--color-neutral-300);
-      transition: all 0.2s ease;
-      position: relative;
-      overflow: hidden;
+
+    .bar {
+      height: var(--spacing-12);
+      background: var(--color-blue-500);
+      border-radius: var(--radius-sm);
+      /* zero-width tokens still need to be visible as a hairline */
+      min-width: 1px;
     }
-    
-    .spacing-box:hover {
-      background-color: var(--color-neutral-300);
-      transform: translateY(-2px);
-      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+
+    .bar--alias {
+      background: var(--color-neutral-400);
     }
-    
-    .spacing-content {
-      font-family: var(--font-family-mono, monospace);
-      font-size: 0.9rem;
-      color: #495057;
-      line-height: 1.4;
+
+    .composite {
+      font-family: var(--typography-fontFamily-mono);
+      color: var(--color-neutral-700);
+      white-space: nowrap;
     }
-    
-    .spacing-token {
-      font-weight: 600;
-      color: var(--color-primary);
+
+    .box-demo {
       display: inline-block;
-      background: white;
-      padding: 2px 6px;
-      border-radius: 3px;
-      border: 1px solid var(--color-neutral-300);
-      margin-right: var(--space-xs);
-    }
-    
-    .spacing-value {
-      color: #6c757d;
-    }
-    
-    .spacing-visual {
-      position: absolute;
-      top: 0;
-      right: 0;
-      bottom: 0;
-      width: 60px;
-      background: repeating-linear-gradient(
-        45deg,
-        var(--color-neutral-300),
-        var(--color-neutral-300) 1px,
-        transparent 1px,
-        transparent 8px
-      );
-      opacity: 0.3;
-    }
-    
-    .legend {
-      display: flex;
-      align-items: center;
-      gap: var(--space-sm);
-      margin-top: var(--space-2xl);
-      padding: var(--space-md);
-      background: var(--color-neutral-100);
-      border-radius: 4px;
-      border-left: 4px solid var(--color-primary);
-    }
-    
-    .legend-item {
-      display: flex;
-      align-items: center;
-      gap: var(--space-xs);
+      background: var(--color-blue-50);
+      border: var(--border-width-1) dashed var(--color-blue-300);
+      border-radius: var(--radius-sm);
     }
-    
-    .legend-color {
-      width: 12px;
-      height: 12px;
-      border-radius: 2px;
-    }
-    
-    .legend-text {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 0.85rem;
-      color: #495057;
-    }
-    
-    .usage-example {
-      margin-top: var(--space-xl);
-      padding: var(--space-md);
-      background: var(--color-neutral-100);
-      border-radius: 4px;
-    }
-    
-    .usage-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      color: #212529;
-      margin: 0 0 var(--space-sm) 0;
-    }
-    
-    .code-block {
-      background: #1a1a1a;
-      color: #f8f8f2;
-      padding: var(--space-md);
-      border-radius: 4px;
-      font-family: var(--font-family-mono, monospace);
-      font-size: 0.85rem;
-      line-height: 1.5;
-      overflow-x: auto;
-    }
-    
-    .code-comment { color: #6272a4; }
-    .code-property { color: #50fa7b; }
-    .code-value { color: #f1fa8c; }
-    .code-punctuation { color: #f8f8f2; }
-  </style>
-
-  <div class="spacing-container">
-    <div class="spacing-header">
-      <h1 class="spacing-title">Spacing Tokens</h1>
-      <p class="spacing-subtitle">Visual reference for all spacing design tokens</p>
-    </div>
-
-    <section>
-      ${Object.entries(args).map(([key, value]) => html`
-        <div class="spacing-box" style="padding: ${value}">
-          <div class="spacing-visual"></div>
-          <div class="spacing-content">
-            <span class="spacing-token">${key.replace('space', '--space-').toLowerCase()}</span>
-            <span class="spacing-value">${value}</span>
-          </div>
-        </div>
-      `)}
-    </section>
-
-    <div class="legend">
-      <div class="legend-item">
-        <div class="legend-color" style="background: var(--color-neutral-200);"></div>
-        <span class="legend-text">Box background shows applied padding</span>
-      </div>
-      <div class="legend-item">
-        <div class="legend-color" style="background: repeating-linear-gradient(45deg, #dee2e6, #dee2e6 1px, transparent 1px, transparent 8px);"></div>
-        <span class="legend-text">Diagonal pattern indicates spacing area</span>
-      </div>
-    </div>
-
-    <div class="usage-example">
-      <h3 class="usage-title">Usage Example</h3>
-      <div class="code-block">
-        <span class="code-comment">/* Using spacing tokens in CSS */</span><br>
-        <span class="code-property">.card</span> {<br>
-        &nbsp;&nbsp;<span class="code-property">padding</span>: <span class="code-value">var(--space-md)</span><span class="code-punctuation">;</span><br>
-        &nbsp;&nbsp;<span class="code-property">margin-bottom</span>: <span class="code-value">var(--space-lg)</span><span class="code-punctuation">;</span><br>
-        }<br><br>
-        <span class="code-comment">/* Responsive spacing */</span><br>
-        <span class="code-property">.container</span> {<br>
-        &nbsp;&nbsp;<span class="code-property">padding</span>: <span class="code-value">var(--space-sm)</span><span class="code-punctuation">;</span><br>
-        }<br>
-        <span class="code-property">@media</span> (<span class="code-property">min-width</span>: <span class="code-value">768px</span>) {<br>
-        &nbsp;&nbsp;<span class="code-property">.container</span> {<br>
-        &nbsp;&nbsp;&nbsp;&nbsp;<span class="code-property">padding</span>: <span class="code-value">var(--space-lg)</span><span class="code-punctuation">;</span><br>
-        &nbsp;&nbsp;}<br>
-        }
-      </div>
-    </div>
-  </div>
-`;
 
-export const SpacingExamples = () => html`
-  <style>
-    .examples-container {
-      max-width: 800px;
-      margin: 0 auto;
-      padding: var(--space-lg);
-    }
-    
-    .example-section {
-      margin-bottom: var(--space-xl);
-      padding: var(--space-lg);
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .example-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 1.25rem;
-      font-weight: 600;
-      color: #212529;
-      margin: 0 0 var(--space-md) 0;
-    }
-    
-    .button-group {
-      display: flex;
-      gap: var(--space-sm);
-      flex-wrap: wrap;
-      margin-bottom: var(--space-md);
-    }
-    
-    .button {
-      padding: var(--space-xs) var(--space-sm);
-      background: #007bff;
-      color: white;
-      border: none;
-      border-radius: 4px;
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 0.9rem;
-      cursor: pointer;
-      transition: background 0.2s;
-    }
-    
-    .button:hover {
-      background: #0056b3;
-    }
-    
-    .card-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
-      gap: var(--space-md);
-    }
-    
-    .card {
-      padding: var(--space-md);
-      background: var(--color-neutral-100, #f8f9fa);
-      border-radius: 6px;
-      border: 1px solid var(--color-neutral-300, #dee2e6);
-    }
-    
-    .card-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      margin: 0 0 var(--space-xs) 0;
-      color: #212529;
-    }
-    
-    .card-content {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 0.9rem;
-      color: #6c757d;
-      margin: 0;
-    }
-    
-    .form-group {
-      margin-bottom: var(--space-md);
-    }
-    
-    .form-label {
+    .box-demo > span {
       display: block;
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      margin-bottom: var(--space-xs);
-      color: #495057;
-    }
-    
-    .form-input {
-      width: 100%;
-      padding: var(--space-xs) var(--space-sm);
-      border: 1px solid var(--color-neutral-300, #dee2e6);
-      border-radius: 4px;
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 0.9rem;
-    }
-    
-    .spacing-visual {
-      display: flex;
-      align-items: center;
-      gap: var(--space-md);
-      padding: var(--space-lg);
-      background: linear-gradient(45deg, #f8f9fa, #e9ecef);
-      border-radius: 6px;
-    }
-    
-    .spacing-dot {
-      width: var(--space-sm);
-      height: var(--space-sm);
-      background: #007bff;
-      border-radius: 50%;
-    }
-    
-    .spacing-label {
-      font-family: var(--font-family-mono, monospace);
-      font-size: 0.85rem;
-      color: #495057;
-      background: white;
-      padding: 2px 6px;
-      border-radius: 3px;
-      border: 1px solid #dee2e6;
+      background: var(--color-neutral-0);
+      border: var(--border-width-1) solid var(--color-neutral-200);
+      border-radius: var(--radius-sm);
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-700);
+      padding: var(--spacing-4) var(--spacing-8);
     }
   </style>
+`;
 
-  <div class="examples-container">
-    <div class="example-section">
-      <h3 class="example-title">Button Spacing</h3>
-      <div class="button-group">
-        <button class="button" style="padding: var(--space-xs) var(--space-sm);">Small Button</button>
-        <button class="button" style="padding: var(--space-sm) var(--space-md);">Medium Button</button>
-        <button class="button" style="padding: var(--space-md) var(--space-lg);">Large Button</button>
-      </div>
-      <p style="font-family: var(--font-family-sans, sans-serif); color: #6c757d; font-size: 0.9rem;">
-        Buttons use consistent padding tokens: --space-xs/--space-sm, --space-sm/--space-md, --space-md/--space-lg
-      </p>
-    </div>
-
-    <div class="example-section">
-      <h3 class="example-title">Card Grid</h3>
-      <div class="card-grid">
-        ${[1, 2, 3].map(i => html`
-          <div class="card">
-            <h4 class="card-title">Card ${i}</h4>
-            <p class="card-content">This card uses --space-md for padding and the grid uses --space-md for gaps.</p>
-          </div>
-        `)}
-      </div>
+/** px equivalent of a rem/px length, for the reference column. */
+function toPx(value) {
+  const probe = document.createElement('div');
+  probe.style.cssText = `position:absolute;visibility:hidden;width:${value}`;
+  document.body.appendChild(probe);
+  const px = getComputedStyle(probe).width;
+  probe.remove();
+  return px;
+}
+
+/** Longest value in a set, used to scale the visual bars proportionally. */
+function widestPx(values) {
+  return Math.max(...values.map(v => parseFloat(toPx(v)) || 0), 1);
+}
+
+function scaleTable({ caption, tokens, consumers, alias = false }) {
+  const resolved = tokens.map(token => ({ token, value: resolve(token) })).filter(row => row.value);
+  const simple = resolved.filter(row => !row.value.includes(' '));
+  const max = widestPx(simple.map(row => row.value));
+
+  return html`
+    <div class="table-scroll">
+      <table>
+        <caption>${caption}</caption>
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">Value</th>
+            <th scope="col">px</th>
+            <th scope="col">Scale</th>
+            <th scope="col">Used by</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${resolved.map(({ token, value }) => {
+            const composite = value.includes(' ');
+            const px = composite ? '—' : toPx(value);
+            const width = composite ? 0 : (parseFloat(px) / max) * 100;
+
+            return html`
+              <tr>
+                <td>${copyToken(token)}</td>
+                <td class="${composite ? 'composite' : 'num'}">${value}</td>
+                <td class="num muted">${px}</td>
+                <td class="bar-cell">
+                  ${composite
+                    ? html`<span class="muted">composite</span>`
+                    : html`<div
+                        class="bar ${alias ? 'bar--alias' : ''}"
+                        style="width: ${width}%"
+                        role="img"
+                        aria-label="${px} wide"
+                      ></div>`}
+                </td>
+                <td>${usageCell(consumers.get(token))}</td>
+              </tr>
+            `;
+          })}
+        </tbody>
+      </table>
     </div>
+  `;
+}
+
+/** Tokens matching a prefix, in declaration order, read from the loaded CSS. */
+function tokensFor(cssText, prefix) {
+  const pattern = new RegExp(`(--${prefix}[A-Za-z0-9-]*)\\s*:`, 'g');
+  return discoverTokens(cssText, pattern).map(match => match[1]);
+}
+
+export const AllSpacings = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+
+  const spacing = tokensFor(cssText, 'spacing-').sort(
+    (a, b) => Number(a.replace(/\D/g, '')) - Number(b.replace(/\D/g, ''))
+  );
+
+  return html`
+    ${barStyles}
+    ${docsPage({
+      title: 'Spacing',
+      lede : html`Values are read from the loaded token CSS at render time, so this page always
+        matches <code>src/tokens/tokens.css</code>. Click a token name to copy its
+        <code>var()</code> reference.`,
+      note: html`One scale, named after its pixel value. There used to be a second,
+        <code>--space-*</code>, a t-shirt scale of thirteen duplicates that existed mainly so
+        <code>bd-grid</code> could build a token name from its <code>gap</code> and
+        <code>padding</code> props. Those props still take t-shirt names; the mapping moved to
+        <code>SPACE_STEPS</code> in <code>shared/token-scales.js</code>, where a prop
+        vocabulary belongs, and the duplicate scale is gone.
+        <br><br>
+        Note that <code>--spacing-1</code> is <b>1px</b>, not one grid unit — reach for
+        <code>--spacing-4</code> when you want 4px. Reading the number as a position rather
+        than a value is what left a form stacking its fields 6px apart.`,
+      children: html`
+        ${refSection({
+          name    : 'Primitive scale',
+          meta    : `${spacing.length} steps · --spacing-*`,
+          children: scaleTable({ caption: 'Primitive spacing scale', tokens: spacing, consumers })
+        })}
+      `
+    })}
+  `;
+};
 
-    <div class="example-section">
-      <h3 class="example-title">Form Layout</h3>
-      <div class="form-group">
-        <label class="form-label">Email Address</label>
-        <input type="email" class="form-input" placeholder="Enter your email">
-      </div>
-      <div class="form-group">
-        <label class="form-label">Password</label>
-        <input type="password" class="form-input" placeholder="Enter your password">
-      </div>
-      <button class="button" style="margin-top: var(--space-md);">Submit</button>
-    </div>
+export const SemanticSpacing = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+
+  const groups = [
+    { name: 'Inset (padding on all sides)', prefix: 'inset-' },
+    { name: 'Stack (vertical rhythm)', prefix: 'stack-' },
+    { name: 'Inline (horizontal rhythm)', prefix: 'inline-' },
+    { name: 'Component padding', prefix: 'padding-' },
+    { name: 'Container padding', prefix: 'container-padding' }
+  ];
+
+  return html`
+    ${barStyles}
+    ${docsPage({
+      title: 'Semantic spacing',
+      lede : html`Named roles layered over the primitive scale. These express intent — an inset,
+        a stack, a container gutter — so a component does not have to pick a raw step.`,
+      note: html`Every token here is defined but the <b>Used by</b> column shows how few are
+        actually referenced. Components mostly reach past this layer straight to
+        <code>--spacing-*</code>, which is worth knowing before you rely on one of these.`,
+      children: groups.map(({ name, prefix }) => {
+        const tokens = tokensFor(cssText, prefix);
+        if (!tokens.length) return html``;
+        return refSection({
+          name,
+          meta    : `${tokens.length} tokens · --${prefix}*`,
+          children: scaleTable({ caption: name, tokens, consumers, alias: true })
+        });
+      })
+    })}
+  `;
+};
 
-    <div class="example-section">
-      <h3 class="example-title">Spacing Visualization</h3>
-      <div class="spacing-visual">
-        <div class="spacing-dot"></div>
-        <span class="spacing-label">--space-sm (1rem)</span>
-        <div class="spacing-dot" style="width: var(--space-md); height: var(--space-md);"></div>
-        <span class="spacing-label">--space-md (1.5rem)</span>
-        <div class="spacing-dot" style="width: var(--space-lg); height: var(--space-lg);"></div>
-        <span class="spacing-label">--space-lg (2rem)</span>
-      </div>
-    </div>
-  </div>
-`;
+export const SpacingExamples = () => {
+  const insets = ['--spacing-8', '--spacing-16', '--spacing-24', '--spacing-32'];
+
+  return html`
+    ${barStyles}
+    ${docsPage({
+      title   : 'Spacing applied',
+      lede    : 'The same scale used as padding, so the steps can be judged against real content rather than as bars.',
+      children: refSection({
+        name    : 'Inset padding',
+        meta    : 'padding applied to a box',
+        children: html`
+          <div class="specimen">
+            ${insets.map(
+              token => html`
+                <div class="box-demo" style="padding: var(${token}); margin: 0 var(--spacing-12) var(--spacing-12) 0">
+                  <span>${token}</span>
+                </div>
+              `
+            )}
+          </div>
+        `
+      })
+    })}
+  `;
+};