@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/tokens/tokens-grid.stories.js

@@ -1,932 +1,420 @@
 import { html } from 'lit';
+import {
+  copyToken,
+  discoverConsumers,
+  discoverTokens,
+  docsPage,
+  readAllCssText,
+  refSection,
+  resolve,
+  usageCell
+} from './story-chrome.js';
 
 export default {
-  title     : 'Design Tokens/Grid System',
-  tags      : ['autodocs'],
-  parameters: {
-    layout: 'fullscreen',
-    docs  : {
-      description: {
-        component: `
-# Grid System
-
-A responsive, mobile-first grid system based on CSS Grid with semantic classes and design tokens.
-
-## Overview
-
-The grid system provides a flexible layout foundation using CSS Grid Layout. It supports responsive design, fixed and fluid columns, and consistent spacing through design tokens.
-
-## Core Concepts
-
-### 1. Container
-The outermost wrapper that centers content and sets maximum width.
-
-### 2. Row
-Horizontal containers that hold columns. Uses CSS Grid for layout.
-
-### 3. Column
-Content containers that span across the grid. Can be fixed or fluid.
-
-## Usage
-
-### Basic Grid Structure
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="grid-col">
-      <!-- Column content -->
-    </div>
-    <div class="grid-col">
-      <!-- Column content -->
-    </div>
-  </div>
-</div>
-\`\`\`
-
-### Fixed Width Columns
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="col-6">
-      <!-- 50% width column -->
-    </div>
-    <div class="col-6">
-      <!-- 50% width column -->
-    </div>
-  </div>
-</div>
-\`\`\`
-
-### Responsive Grid
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="col-12 col-md-8 col-lg-6">
-      <!-- Responsive column -->
-    </div>
-  </div>
-</div>
-\`\`\`
-
-## Grid Classes Reference
-
-### Container Classes
-| Class | Description | CSS Equivalent |
-|-------|-------------|----------------|
-| \`.grid-container\` | Centers content with max-width | \`max-width: var(--container-max-width)\` |
-| \`.container-fluid\` | Full-width container | \`width: 100%\` |
-
-### Row Classes
-| Class | Description | CSS Equivalent |
-|-------|-------------|----------------|
-| \`.grid-row\` | Grid container row | \`display: grid; grid-template-columns: repeat(auto-fit, minmax(min-content, 1fr))\` |
-| \`.row-gap-sm\` | Small row gap | \`row-gap: var(--space-sm)\` |
-| \`.row-gap-md\` | Medium row gap | \`row-gap: var(--space-md)\` |
-| \`.row-gap-lg\` | Large row gap | \`row-gap: var(--space-lg)\` |
-
-### Column Classes
-#### Fluid Columns
-| Class | Description | Behavior |
-|-------|-------------|----------|
-| \`.grid-col\` | Auto-sizing column | Fills available space equally |
-| \`.col-auto\` | Content-based width | Width based on content size |
-
-#### Fixed Columns (12-column grid)
-| Class | Width | Columns |
-|-------|-------|---------|
-| \`.col-1\` | 8.33% | 1 of 12 |
-| \`.col-2\` | 16.66% | 2 of 12 |
-| \`.col-3\` | 25% | 3 of 12 |
-| \`.col-4\` | 33.33% | 4 of 12 |
-| \`.col-5\` | 41.66% | 5 of 12 |
-| \`.col-6\` | 50% | 6 of 12 |
-| \`.col-7\` | 58.33% | 7 of 12 |
-| \`.col-8\` | 66.66% | 8 of 12 |
-| \`.col-9\` | 75% | 9 of 12 |
-| \`.col-10\` | 83.33% | 10 of 12 |
-| \`.col-11\` | 91.66% | 11 of 12 |
-| \`.col-12\` | 100% | 12 of 12 |
-
-#### Responsive Columns
-| Class | Breakpoint | Description |
-|-------|------------|-------------|
-| \`.col-sm-*\` | ≥576px | Small devices |
-| \`.col-md-*\` | ≥768px | Medium devices |
-| \`.col-lg-*\` | ≥992px | Large devices |
-| \`.col-xl-*\` | ≥1200px | Extra large devices |
-
-## Design Tokens
-
-The grid system uses CSS custom properties for consistent spacing and sizing:
-
-\`\`\`css
-:root {
-  /* Container */
-  --container-max-width: 1200px;
-  --container-padding: var(--space-lg);
-  
-  /* Grid */
-  --grid-columns: 12;
-  --grid-gap: var(--space-md);
-  
-  /* Breakpoints */
-  --breakpoint-sm: 576px;
-  --breakpoint-md: 768px;
-  --breakpoint-lg: 992px;
-  --breakpoint-xl: 1200px;
-}
-\`\`\`
-
-## Examples
-
-### Equal Width Columns
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="grid-col">Column 1</div>
-    <div class="grid-col">Column 2</div>
-    <div class="grid-col">Column 3</div>
-  </div>
-</div>
-\`\`\`
-
-### Mixed Fixed and Fluid
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="col-4">Fixed 33%</div>
-    <div class="grid-col">Fluid remaining</div>
-  </div>
-</div>
-\`\`\`
-
-### Nested Grids
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="col-8">
-      <div class="grid-row">
-        <div class="col-6">Nested 50%</div>
-        <div class="col-6">Nested 50%</div>
-      </div>
-    </div>
-    <div class="col-4">Sidebar</div>
-  </div>
-</div>
-\`\`\`
-
-### Responsive Layout
-\`\`\`html
-<div class="grid-container">
-  <div class="grid-row">
-    <div class="col-12 col-md-8 col-lg-6">
-      Content adjusts based on screen size
-    </div>
-    <div class="col-12 col-md-4 col-lg-6">
-      Sidebar adjusts accordingly
-    </div>
-  </div>
-</div>
-\`\`\`
-
-## Best Practices
-
-### 1. Always Use Container
-Wrap your grid in a container for proper centering and padding:
-\`\`\`html
-<!-- Good ✅ -->
-<div class="grid-container">
-  <div class="grid-row">...</div>
-</div>
-
-<!-- Bad ❌ -->
-<div class="grid-row">...</div>
-\`\`\`
-
-### 2. Column Sum Should Equal 12 (for fixed grids)
-\`\`\`html
-<!-- Good ✅ -->
-<div class="col-8">...</div>
-<div class="col-4">...</div>
-<!-- Total: 12 -->
-
-<!-- Bad ❌ -->
-<div class="col-7">...</div>
-<div class="col-6">...</div>
-<!-- Total: 13, will wrap -->
-\`\`\`
-
-### 3. Use Semantic Class Names
-\`\`\`html
-<!-- Good ✅ -->
-<div class="grid-col">Main Content</div>
-<div class="col-4">Sidebar</div>
-
-<!-- Avoid ❌ -->
-<div style="grid-column: span 8;">Main Content</div>
-\`\`\`
-
-### 4. Responsive Considerations
-- Test on multiple screen sizes
-- Use responsive column classes
-- Consider mobile-first approach
-- Ensure touch targets are adequate
-
-## Browser Support
-
-CSS Grid is supported in:
-- Chrome 57+
-- Firefox 52+
-- Safari 10.1+
-- Edge 16+
-
-For older browsers, consider using feature detection with \`@supports\`:
-\`\`\`css
-@supports (display: grid) {
-  .grid-row {
-    display: grid;
-  }
-}
-
-@supports not (display: grid) {
-  .grid-row {
-    display: flex;
-    flex-wrap: wrap;
-  }
-}
-\`\`\`
-
-## Performance
-
-- CSS Grid has excellent performance in modern browsers
-- Avoid deeply nested grids when possible
-- Use \`grid-auto-flow: dense\` for complex layouts
-- Consider \`will-change: transform\` for animated grids
-
-## Accessibility
-
-- Maintain logical source order
-- Ensure proper heading hierarchy within grids
-- Test keyboard navigation
-- Verify screen reader announcements
-- Maintain sufficient color contrast
-        `
-      }
-    }
-  },
-
-  argTypes: {
-    backgroundColor: {
-      control    : 'color',
-      description: 'Background color for container',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '#f4f4f4' }
-      }
-    },
-    padding: {
-      control    : 'text',
-      description: 'Padding for container and columns',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'var(--space-md)' }
-      }
-    },
-    gutter: {
-      control    : 'text',
-      description: 'Gap between columns',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'var(--grid-gap, var(--space-md))' }
-      }
-    },
-    colBg1: {
-      control    : 'color',
-      description: 'Background color for first column',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '#bbb' }
-      }
-    },
-    colBg2: {
-      control    : 'color',
-      description: 'Background color for second column',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '#999' }
-      }
-    },
-    maxWidth: {
-      control    : 'text',
-      description: 'Maximum width of container',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'var(--container-max-width, 1200px)' }
-      }
-    }
-  }
+  title: 'Foundations/Grid System',
+  tags : ['autodocs']
 };
 
-const Template = (args) => html`
+const gridStyles = html`
   <style>
-    :root {
-      --container-max-width: 1200px;
-      --grid-gap: var(--space-md);
-      --space-md: 1.5rem;
-      --space-lg: 2rem;
-    }
-    
-    .story-container {
-      padding: 2rem;
-      background: #f8f9fa;
-      min-height: 100vh;
-    }
-    
-    .grid-container {
-      max-width: ${args.maxWidth};
-      margin: 0 auto;
-      padding: ${args.padding};
-      background: ${args.backgroundColor};
-      border-radius: 8px;
-      border: 2px solid #dee2e6;
-    }
-    
-    .grid-row {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(min-content, 1fr));
-      gap: ${args.gutter};
-    }
-    
-    .grid-col {
-      min-height: 100px;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      border-radius: 4px;
-    }
-    
-    .col-6 {
-      grid-column: span 6;
-      min-height: 100px;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      border-radius: 4px;
-    }
-    
-    .col-4 {
-      grid-column: span 4;
-    }
-    
-    .col-8 {
-      grid-column: span 8;
-    }
-    
-    .col-12 {
-      grid-column: span 12;
-    }
-    
-    .info-panel {
-      background: white;
-      padding: 1.5rem;
-      border-radius: 8px;
-      margin-bottom: 2rem;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .info-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 1.25rem;
-      font-weight: 600;
-      margin: 0 0 1rem 0;
-      color: #212529;
-    }
-    
-    .info-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-      gap: 1rem;
-      margin-top: 1rem;
-    }
-    
-    .info-item {
-      padding: 1rem;
-      background: #f8f9fa;
-      border-radius: 4px;
-      border-left: 4px solid #007bff;
-    }
-    
-    .info-label {
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      color: #495057;
-      margin: 0 0 0.25rem 0;
-      font-size: 0.9rem;
-    }
-    
-    .info-value {
-      font-family: var(--font-family-mono, monospace);
-      color: #6c757d;
-      margin: 0;
-      font-size: 0.85rem;
-    }
-    
-    .code-block {
-      background: #1a1a1a;
-      color: #f8f8f2;
-      padding: 1.5rem;
-      border-radius: 4px;
-      font-family: var(--font-family-mono, monospace);
-      font-size: 0.85rem;
-      line-height: 1.5;
+    .demo-frame {
+      background: var(--color-neutral-25);
+      border: var(--border-width-1) solid var(--color-neutral-100);
+      border-radius: var(--radius-md);
+      padding: var(--spacing-16);
+      /* the demos are width-sensitive; keep them off the page scrollbar */
       overflow-x: auto;
-      margin-top: 1rem;
-    }
-    
-    .code-comment { color: #6272a4; }
-    .code-class { color: #50fa7b; }
-    .code-property { color: #f1fa8c; }
-    .code-value { color: #ff79c6; }
-  </style>
-
-  <div class="story-container">
-    <div class="info-panel">
-      <h3 class="info-title">Grid System Configuration</h3>
-      <div class="info-grid">
-        <div class="info-item">
-          <p class="info-label">Container Max Width</p>
-          <p class="info-value">${args.maxWidth}</p>
-        </div>
-        <div class="info-item">
-          <p class="info-label">Container Padding</p>
-          <p class="info-value">${args.padding}</p>
-        </div>
-        <div class="info-item">
-          <p class="info-label">Grid Gutter</p>
-          <p class="info-value">${args.gutter}</p>
-        </div>
-      </div>
-    </div>
-    
-    <div class="grid-container">
-      <div class="grid-row" style="gap: ${args.gutter};">
-        <div class="grid-col" style="background: ${args.colBg1}; padding: ${args.padding};">
-          .grid-col (auto width)
-        </div>
-        <div class="grid-col" style="background: ${args.colBg2}; padding: ${args.padding};">
-          .grid-col (auto width)
-        </div>
-      </div>
-    </div>
-    
-    <div class="code-block">
-      <span class="code-comment">HTML Structure:</span><br>
-      &lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-container"</span>&gt;<br>
-      &nbsp;&nbsp;&lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-row"</span>&gt;<br>
-      &nbsp;&nbsp;&nbsp;&nbsp;&lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-col"</span>&gt;Column 1&lt;/<span class="code-class">div</span>&gt;<br>
-      &nbsp;&nbsp;&nbsp;&nbsp;&lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-col"</span>&gt;Column 2&lt;/<span class="code-class">div</span>&gt;<br>
-      &nbsp;&nbsp;&lt;/<span class="code-class">div</span>&gt;<br>
-      &lt;/<span class="code-class">div</span>&gt;
-    </div>
-  </div>
-`;
-
-export const GridContainer = Template.bind({});
-GridContainer.args = {
-  backgroundColor: '#f4f4f4',
-  padding        : 'var(--space-lg)',
-  gutter         : 'var(--space-md)',
-  colBg1         : '#bbb',
-  colBg2         : '#999',
-  maxWidth       : 'var(--container-max-width, 1200px)'
-};
-GridContainer.storyName = 'Basic Grid';
-GridContainer.parameters = {
-  docs: {
-    description: {
-      story: 'Basic grid container with auto-sizing columns. Demonstrates the foundational grid structure with container, row, and columns.'
     }
-  }
-};
 
-export const FixedColumns = (args) => html`
-  <style>
     .demo-container {
-      padding: 2rem;
-      background: #f8f9fa;
-      min-height: 100vh;
-    }
-    
-    .grid-container {
-      max-width: ${args.maxWidth};
       margin: 0 auto;
-      padding: ${args.padding};
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .grid-row {
-      display: grid;
-      grid-template-columns: repeat(12, 1fr);
-      gap: ${args.gutter};
-      margin-bottom: 2rem;
-    }
-    
-    .col {
-      min-height: 80px;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      border-radius: 4px;
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      color: white;
-    }
-    
-    .col-1 { grid-column: span 1; background: #007bff; }
-    .col-2 { grid-column: span 2; background: #6f42c1; }
-    .col-3 { grid-column: span 3; background: #e83e8c; }
-    .col-4 { grid-column: span 4; background: #fd7e14; }
-    .col-5 { grid-column: span 5; background: #20c997; }
-    .col-6 { grid-column: span 6; background: #17a2b8; }
-    .col-7 { grid-column: span 7; background: #ffc107; color: #212529; }
-    .col-8 { grid-column: span 8; background: #dc3545; }
-    .col-9 { grid-column: span 9; background: #343a40; }
-    .col-10 { grid-column: span 10; background: #28a745; }
-    .col-11 { grid-column: span 11; background: #6c757d; }
-    .col-12 { grid-column: span 12; background: #6610f2; }
-    
-    .grid-example {
-      margin-bottom: 3rem;
-    }
-    
-    .example-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 1.1rem;
-      font-weight: 600;
-      margin: 0 0 1rem 0;
-      color: #212529;
-    }
-    
-    .example-description {
-      font-family: var(--font-family-sans, sans-serif);
-      color: #6c757d;
-      margin: 0 0 1.5rem 0;
-      font-size: 0.9rem;
+      background: var(--color-blue-50);
+      border: var(--border-width-1) dashed var(--color-blue-300);
+      border-radius: var(--radius-sm);
     }
-  </style>
 
-  <div class="demo-container">
-    <div class="grid-container">
-      <div class="grid-example">
-        <h3 class="example-title">12-Column Grid System</h3>
-        <p class="example-description">All available fixed-width column classes:</p>
-        <div class="grid-row">
-          ${[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map(num => html`
-            <div class="col col-1">.col-1</div>
-          `)}
-        </div>
-        
-        <div class="grid-row">
-          <div class="col col-6">.col-6 (50%)</div>
-          <div class="col col-6">.col-6 (50%)</div>
-        </div>
-        
-        <div class="grid-row">
-          <div class="col col-4">.col-4 (33%)</div>
-          <div class="col col-4">.col-4 (33%)</div>
-          <div class="col col-4">.col-4 (33%)</div>
-        </div>
-        
-        <div class="grid-row">
-          <div class="col col-8">.col-8 (66%)</div>
-          <div class="col col-4">.col-4 (33%)</div>
-        </div>
-        
-        <div class="grid-row">
-          <div class="col col-3">.col-3 (25%)</div>
-          <div class="col col-6">.col-6 (50%)</div>
-          <div class="col col-3">.col-3 (25%)</div>
-        </div>
-      </div>
-    </div>
-  </div>
-`;
-FixedColumns.args = {
-  padding : 'var(--space-lg)',
-  gutter  : 'var(--space-sm)',
-  maxWidth: 'var(--container-max-width, 1200px)'
-};
-FixedColumns.storyName = 'Fixed Columns';
-FixedColumns.parameters = {
-  docs: {
-    description: {
-      story: 'Fixed-width column system based on a 12-column grid. Demonstrates all available column classes from .col-1 to .col-12.'
-    }
-  }
-};
-
-export const ResponsiveGrid = () => html`
-  <style>
-    .responsive-demo {
-      padding: 2rem;
-      background: #f8f9fa;
-      min-height: 100vh;
-    }
-    
-    .grid-container {
-      max-width: 1200px;
-      margin: 0 auto;
-      padding: 2rem;
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .grid-row {
+    .demo-grid {
       display: grid;
-      gap: 1rem;
-      margin-bottom: 2rem;
+      grid-template-columns: repeat(var(--demo-cols, 12), 1fr);
     }
-    
-    .col {
-      padding: 1.5rem;
-      border-radius: 6px;
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      display: flex;
-      align-items: center;
-      justify-content: center;
+
+    .demo-cell {
+      background: var(--color-blue-500);
+      color: var(--color-neutral-0);
+      border-radius: var(--radius-sm);
+      padding: var(--spacing-8) 0;
       text-align: center;
-      min-height: 120px;
-    }
-    
-    .col-1 { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; }
-    .col-2 { background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%); color: white; }
-    .col-3 { background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%); color: white; }
-    
-    .breakpoint-info {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-      gap: 1rem;
-      margin-bottom: 2rem;
-    }
-    
-    .breakpoint-card {
-      padding: 1rem;
-      background: #f8f9fa;
-      border-radius: 6px;
-      border-left: 4px solid #007bff;
-    }
-    
-    .breakpoint-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      margin: 0 0 0.5rem 0;
-      color: #212529;
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      font-weight: var(--typography-fontWeight-semibold);
     }
-    
-    .breakpoint-desc {
-      font-family: var(--font-family-sans, sans-serif);
-      color: #6c757d;
-      margin: 0;
-      font-size: 0.9rem;
+
+    .demo-cell--alt {
+      background: var(--color-neutral-400);
     }
-    
-    .device-preview {
-      position: relative;
-      border: 2px solid #dee2e6;
-      border-radius: 12px;
-      padding: 1rem;
-      margin: 1rem 0;
-      background: #f8f9fa;
+
+    .demo-label {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+      margin: 0 0 var(--spacing-8);
     }
-    
-    .device-label {
-      position: absolute;
-      top: -12px;
-      left: 1rem;
-      background: #007bff;
-      color: white;
-      padding: 2px 8px;
-      border-radius: 4px;
-      font-family: var(--font-family-sans, sans-serif);
-      font-size: 0.8rem;
-      font-weight: 600;
+
+    .demo-label + .demo-frame {
+      margin-bottom: var(--spacing-24);
     }
-    
-    .responsive-code {
-      background: #1a1a1a;
-      color: #f8f8f2;
-      padding: 1.5rem;
-      border-radius: 6px;
-      font-family: var(--font-family-mono, monospace);
-      font-size: 0.85rem;
-      line-height: 1.5;
-      margin-top: 2rem;
+
+    .ruler {
+      height: var(--spacing-8);
+      background: var(--color-blue-500);
+      border-radius: var(--radius-sm);
+      min-width: 1px;
     }
   </style>
+`;
 
-  <div class="responsive-demo">
-    <div class="grid-container">
-      <h3 style="font-family: var(--font-family-sans, sans-serif); margin: 0 0 2rem 0;">Responsive Grid System</h3>
-      
-      <div class="breakpoint-info">
-        <div class="breakpoint-card">
-          <h4 class="breakpoint-title">Mobile First</h4>
-          <p class="breakpoint-desc">Columns stack vertically by default on small screens</p>
-        </div>
-        <div class="breakpoint-card">
-          <h4 class="breakpoint-title">Tablet (≥768px)</h4>
-          <p class="breakpoint-desc">Use .col-md-* classes for tablet layouts</p>
-        </div>
-        <div class="breakpoint-card">
-          <h4 class="breakpoint-title">Desktop (≥992px)</h4>
-          <p class="breakpoint-desc">Use .col-lg-* classes for desktop layouts</p>
-        </div>
-      </div>
-      
-      <div class="device-preview">
-        <div class="device-label">Mobile (Stacked)</div>
-        <div class="grid-row">
-          <div class="col col-12" style="background: #007bff; color: white;">.col-12 (100%)</div>
-          <div class="col col-12" style="background: #28a745; color: white;">.col-12 (100%)</div>
-        </div>
-      </div>
-      
-      <div class="device-preview">
-        <div class="device-label">Tablet (2 Columns)</div>
-        <div class="grid-row" style="grid-template-columns: repeat(2, 1fr);">
-          <div class="col col-1">.col-md-6</div>
-          <div class="col col-2">.col-md-6</div>
-        </div>
-      </div>
-      
-      <div class="device-preview">
-        <div class="device-label">Desktop (3 Columns)</div>
-        <div class="grid-row" style="grid-template-columns: repeat(3, 1fr);">
-          <div class="col col-1">.col-lg-4</div>
-          <div class="col col-2">.col-lg-4</div>
-          <div class="col col-3">.col-lg-4</div>
-        </div>
-      </div>
-      
-      <div class="responsive-code">
-        <span style="color: #6272a4;">/* Responsive column example */</span><br>
-        &lt;div class="col-12 col-md-6 col-lg-4"&gt;<br>
-        &nbsp;&nbsp;<span style="color: #6272a4;">&lt;!-- Stacked on mobile, 2 columns on tablet, 3 columns on desktop --&gt;</span><br>
-        &lt;/div&gt;
-      </div>
+function tokensFor(cssText, prefix) {
+  const pattern = new RegExp(`(--${prefix}[A-Za-z0-9-]*)\\s*:`, 'g');
+  return discoverTokens(cssText, pattern).map(match => match[1]);
+}
+
+function tokenTable({ caption, tokens, consumers, ruler = false }) {
+  const rows = tokens.map(token => ({ token, value: resolve(token) })).filter(r => r.value);
+  const max = ruler ? Math.max(...rows.map(r => parseFloat(r.value) || 0), 1) : 0;
+
+  return html`
+    <div class="table-scroll">
+      <table>
+        <caption>${caption}</caption>
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">Value</th>
+            ${ruler ? html`<th scope="col">Scale</th>` : ''}
+            <th scope="col">Used by</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${rows.map(
+            ({ token, value }) => html`
+              <tr>
+                <td>${copyToken(token)}</td>
+                <td class="num">${value}</td>
+                ${ruler
+                  ? html`<td style="width: 40%">
+                      <div
+                        class="ruler"
+                        style="width: ${((parseFloat(value) || 0) / max) * 100}%"
+                      ></div>
+                    </td>`
+                  : ''}
+                <td>${usageCell(consumers.get(token))}</td>
+              </tr>
+            `
+          )}
+        </tbody>
+      </table>
     </div>
-  </div>
+  `;
+}
+
+/* ---------------------------------------------------------------------------
+   The one table everything else in this system rests on, and it was missing.
+
+   Type, images and controls never get the viewport -- they get what is left
+   after the gutters. Until this was written down, the number had to be
+   re-derived by whoever needed it, and at least once it was got wrong by
+   MEASURING a Storybook story instead: the harness adds 16px of body padding
+   either side, so a 288px column was recorded as 256 and moved a typography
+   conclusion by a whole step of the scale. Derive it from the tokens. */
+const COLUMN_TABLE = [
+  ['320', 'xs', '100%', 16],
+  ['375', 'xs', '100%', 16],
+  ['576', 'sm', '540px', 24],
+  ['768', 'md', '720px', 32],
+  ['992', 'lg', '960px', 40],
+  ['1200', 'xl', '1140px', 40],
+  ['1400', 'xxl', '1320px', 40]
+];
+const columnOf = (vw, cmax, padding) => {
+  const box = cmax === '100%' ? Number(vw) : parseInt(cmax, 10);
+  return Math.min(box, Number(vw)) - padding * 2;
+};
+
+export const TheColumn = () => html`
+  ${gridStyles}
+  ${docsPage({
+    title: 'The column',
+    lede : html`What content actually gets at each viewport:
+      <code>--grid-container-max-*</code> capped by the viewport, minus
+      <b>twice</b> <code>--grid-padding-*</code>. Every sizing decision in the
+      system — type, media, controls — is really a decision against this
+      number, not against the viewport.`,
+    note: html`<b>Derive it, do not measure it.</b> A Storybook story sits inside 16px of
+      harness body padding either side, so measuring one understates the column at the
+      <code>xs</code> tier. That mistake recorded a 288px column as 256 and moved a typography
+      conclusion by a whole step of the type scale.`,
+    children: html`
+      ${refSection({
+        name    : 'Viewport to column',
+        meta    : '7 widths · container − 2 × gutter',
+        children: html`
+          <div style="overflow-x: auto">
+            <table class="tokens-table">
+              <caption>The column at each breakpoint, and what the gutters cost</caption>
+              <thead>
+                <tr>
+                  <th>viewport</th><th>tier</th><th>container max</th>
+                  <th>gutter × 2</th><th>column</th><th>lost to gutters</th>
+                </tr>
+              </thead>
+              <tbody>
+                ${COLUMN_TABLE.map(([vw, tier, cmax, padding]) => {
+                  const col = columnOf(vw, cmax, padding);
+                  return html`
+                    <tr>
+                      <td>${vw}px</td>
+                      <td><code>${tier}</code></td>
+                      <td>${cmax === '100%' ? html`<code>100%</code> → ${vw}px` : cmax}</td>
+                      <td>${padding} × 2 = ${padding * 2}px</td>
+                      <td><b>${col}px</b></td>
+                      <td>${Math.round((padding * 2 / Number(vw)) * 100)}%</td>
+                    </tr>
+                  `;
+                })}
+              </tbody>
+            </table>
+          </div>
+          <p>
+            <b><code>xl</code> and <code>xxl</code> inherit <code>--grid-padding-lg</code>.</b>
+            <code>ensemble.css.js</code> raises <code>max-width</code> above <code>lg</code> but
+            never the padding, so <b>40px is the widest gutter this system has</b> — and the
+            column therefore grows more slowly than the screen does. At 320 the gutters are 10%
+            of the screen; at 1400 they are 6%.
+          </p>
+          <p>
+            <b>Why it matters most at the narrow end.</b> A 320px phone gives type 288px. Against
+            that column the largest size at which the longest realistic compound word still fits
+            is <b>31px</b> — which is why nine type roles are fluid. See
+            <i>Foundations/Typography → Fluid type</i>.
+          </p>
+        `
+      })}
+    `
+  })}
 `;
-ResponsiveGrid.storyName = 'Responsive Grid';
-ResponsiveGrid.parameters = {
-  docs: {
-    description: {
-      story: 'Responsive grid system with mobile-first approach. Shows how columns adapt to different screen sizes using responsive classes.'
-    }
-  }
+
+export const GridTokens = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+
+  const groups = [
+    { name: 'Breakpoints', prefix: 'breakpoint-', ruler: true, caption: 'Breakpoint tokens' },
+    { name: 'Container max widths', prefix: 'grid-container-max-', ruler: true, caption: 'Container max widths' },
+    { name: 'Gutters', prefix: 'grid-gutter-', ruler: true, caption: 'Gutter tokens' },
+    { name: 'Container padding', prefix: 'grid-padding-', ruler: true, caption: 'Grid padding tokens' },
+    { name: 'Columns', prefix: 'grid-columns', ruler: false, caption: 'Column count' },
+    { name: 'Content widths', prefix: 'content-width-', ruler: false, caption: 'Content width tokens' }
+  ];
+
+  return html`
+    ${gridStyles}
+    ${docsPage({
+      title: 'Grid system',
+      lede : html`The layout tokens, 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`<b>Breakpoint tokens cannot be used in a media query.</b>
+        <code>@media (min-width: var(--breakpoint-md))</code> does not work — custom properties are
+        not allowed in media conditions. Write the value literally, or import the breakpoint map
+        from JavaScript (<code>src/blog/src/breakpoints.js</code> does this for Lit
+        <code>css</code> templates). Note also that components currently hardcode several widths
+        that are not on this scale, so check the <b>Used by</b> column before assuming a
+        breakpoint is authoritative.`,
+      children: groups.map(({ name, prefix, ruler, caption }) => {
+        const tokens = tokensFor(cssText, prefix);
+        if (!tokens.length) return html``;
+        return refSection({
+          name,
+          meta    : `${tokens.length} token${tokens.length === 1 ? '' : 's'} · --${prefix}*`,
+          children: tokenTable({ caption, tokens, consumers, ruler })
+        });
+      })
+    })}
+  `;
 };
 
-export const GutterExample = (args) => html`
-  <style>
-    .gutter-demo {
-      padding: 2rem;
-      background: #f8f9fa;
-      min-height: 100vh;
-    }
-    
-    .grid-container {
-      max-width: 1200px;
-      margin: 0 auto;
-      padding: 2rem;
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .gutter-visualization {
-      display: grid;
-      grid-template-columns: repeat(2, 1fr);
-      gap: 2rem;
-      margin-bottom: 3rem;
-    }
-    
-    .gutter-example {
-      padding: 1.5rem;
-      border-radius: 6px;
-      border: 2px solid #dee2e6;
-    }
-    
-    .example-title {
-      font-family: var(--font-family-sans, sans-serif);
-      font-weight: 600;
-      margin: 0 0 1rem 0;
-      color: #212529;
-    }
-    
-    .grid-row-demo {
-      display: grid;
-      grid-template-columns: repeat(2, 1fr);
-      margin: 1rem 0;
-    }
-    
-    .grid-col-demo {
-      background: #007bff;
-      color: white;
-      padding: 1rem;
-      border-radius: 4px;
-      font-family: var(--font-family-sans, sans-serif);
-      text-align: center;
-    }
-    
-    .no-gap { gap: 0; }
-    .gap-sm { gap: var(--space-sm); }
-    .gap-md { gap: var(--space-md); }
-    .gap-lg { gap: var(--space-lg); }
-    
-    .gutter-preview {
-      height: 60px;
-      background: repeating-linear-gradient(
-        90deg,
-        #dee2e6,
-        #dee2e6 1px,
-        transparent 1px,
-        transparent calc(${args.gutter} - 1px)
-      );
-      margin: 1rem 0;
-      border-radius: 4px;
-    }
-    
-    .gutter-value {
-      font-family: var(--font-family-mono, monospace);
-      background: #f8f9fa;
-      padding: 0.5rem;
-      border-radius: 4px;
-      margin: 0.5rem 0;
-    }
-  </style>
+export const GridContainer = () => {
+  const sizes = ['xs', 'sm', 'md', 'lg', 'xl', 'xxl'];
+
+  return html`
+    ${gridStyles}
+    ${docsPage({
+      title: 'Containers',
+      lede : html`Each container caps content at its breakpoint's max width and applies the
+        matching horizontal padding. Widths are the real token values, so the bars below are to
+        scale with each other.`,
+      children: html`${refSection({
+        name    : 'Container max widths',
+        meta    : '--grid-container-max-* with --grid-padding-*',
+        children: html`
+          ${sizes.map(size => {
+            const maxToken = `--grid-container-max-${size}`;
+            const padToken = `--grid-padding-${['xs', 'sm', 'md', 'lg'].includes(size) ? size : 'lg'}`;
+            return html`
+              <p class="demo-label">${maxToken} = ${resolve(maxToken)} · ${padToken} = ${resolve(padToken)}</p>
+              <div class="demo-frame">
+                <div
+                  class="demo-container"
+                  style="max-width: var(${maxToken}); padding: var(--spacing-12) var(${padToken})"
+                >
+                  <div class="demo-cell">${size}</div>
+                </div>
+              </div>
+            `;
+          })}
+        `
+      })}${refSection({
+        name    : 'The page column',
+        meta    : '.bd-ensemble · src/components/shared/ensemble.css.js',
+        children: html`
+          <p class="demo-label">
+            This container is implemented once, as <code>ensembleCSS</code>. Every page-level
+            module composes it and puts <code>bd-ensemble</code> on the element that holds its
+            content, so a page assembled from independent sections has its content on one pair
+            of edges. A column nested inside another collapses on its own. See
+            <code>check:ensemble</code>, and the page column section of CLAUDE.md.
+          </p>
+        `
+      })}`
+    })}
+  `;
+};
 
-  <div class="gutter-demo">
-    <div class="grid-container">
-      <h3 style="font-family: var(--font-family-sans, sans-serif); margin: 0 0 2rem 0;">Grid Gutter System</h3>
-      
-      <div class="gutter-visualization">
-        <div class="gutter-example">
-          <h4 class="example-title">No Gutter</h4>
-          <div class="grid-row-demo no-gap">
-            <div class="grid-col-demo">Column 1</div>
-            <div class="grid-col-demo">Column 2</div>
-          </div>
-          <div class="gutter-value">gap: 0</div>
-        </div>
-        
-        <div class="gutter-example">
-          <h4 class="example-title">Small Gutter</h4>
-          <div class="grid-row-demo gap-sm">
-            <div class="grid-col-demo">Column 1</div>
-            <div class="grid-col-demo">Column 2</div>
-          </div>
-          <div class="gutter-value">gap: var(--space-sm)</div>
-        </div>
-        
-        <div class="gutter-example">
-          <h4 class="example-title">Medium Gutter (Default)</h4>
-          <div class="grid-row-demo gap-md">
-            <div class="grid-col-demo">Column 1</div>
-            <div class="grid-col-demo">Column 2</div>
-          </div>
-          <div class="gutter-value">gap: var(--space-md)</div>
-        </div>
-        
-        <div class="gutter-example">
-          <h4 class="example-title">Large Gutter</h4>
-          <div class="grid-row-demo gap-lg">
-            <div class="grid-col-demo">Column 1</div>
-            <div class="grid-col-demo">Column 2</div>
+export const FixedColumns = () => {
+  const columnCount = Number(resolve('--grid-columns')) || 12;
+  const spans = [
+    [12],
+    [6, 6],
+    [4, 4, 4],
+    [3, 3, 3, 3],
+    [8, 4],
+    [2, 8, 2]
+  ];
+
+  return html`
+    ${gridStyles}
+    ${docsPage({
+      title: 'Columns',
+      lede : html`The grid is <b>${columnCount}</b> columns
+        (<code>--grid-columns</code>), with <code>--grid-gutter-md</code> between them.`,
+      children: refSection({
+        name    : 'Common splits',
+        meta    : `${columnCount} columns · --grid-gutter-md`,
+        children: html`
+          ${spans.map(
+            row => html`
+              <p class="demo-label">${row.join(' + ')}</p>
+              <div class="demo-frame">
+                <div
+                  class="demo-grid"
+                  style="--demo-cols: ${columnCount}; gap: var(--grid-gutter-md)"
+                >
+                  ${row.map(
+                    (span, index) => html`
+                      <div
+                        class="demo-cell ${index % 2 ? 'demo-cell--alt' : ''}"
+                        style="grid-column: span ${span}"
+                      >
+                        ${span}
+                      </div>
+                    `
+                  )}
+                </div>
+              </div>
+            `
+          )}
+        `
+      })
+    })}
+  `;
+};
+
+export const ResponsiveGrid = () => html`
+  ${gridStyles}
+  ${docsPage({
+    title: 'Responsive columns',
+    lede : html`Resize the canvas to see the column count change. The media queries below use the
+      literal breakpoint values, because <code>var(--breakpoint-*)</code> is not valid inside a
+      media condition — this is the gap the token scale cannot close on its own.`,
+    children: refSection({
+      name    : 'One / two / three / four up',
+      meta    : '576px · 768px · 992px — mirrors --breakpoint-sm/md/lg',
+      children: html`
+        <style>
+          .responsive-demo {
+            display: grid;
+            gap: var(--grid-gutter-md);
+            grid-template-columns: 1fr;
+          }
+          /* literal values, matching --breakpoint-sm/md/lg */
+          @media (min-width: 576px) {
+            .responsive-demo { grid-template-columns: repeat(2, 1fr); }
+          }
+          @media (min-width: 768px) {
+            .responsive-demo { grid-template-columns: repeat(3, 1fr); }
+          }
+          @media (min-width: 992px) {
+            .responsive-demo { grid-template-columns: repeat(4, 1fr); }
+          }
+        </style>
+        <div class="demo-frame">
+          <div class="responsive-demo">
+            ${Array.from(
+              { length: 8 },
+              (_unused, index) => html`
+                <div class="demo-cell ${index % 2 ? 'demo-cell--alt' : ''}">${index + 1}</div>
+              `
+            )}
           </div>
-          <div class="gutter-value">gap: var(--space-lg)</div>
         </div>
-      </div>
-      
-      <div style="background: #f8f9fa; padding: 1.5rem; border-radius: 6px; margin-top: 2rem;">
-        <h4 style="font-family: var(--font-family-sans, sans-serif); margin: 0 0 1rem 0;">Current Gutter Preview</h4>
-        <div class="gutter-preview"></div>
-        <div class="gutter-value">Current gutter value: ${args.gutter}</div>
-      </div>
-    </div>
-  </div>
+      `
+    })
+  })}
 `;
-GutterExample.args = {
-  gutter: 'var(--space-md)'
+
+export const GutterExample = () => {
+  const gutters = ['xs', 'sm', 'md', 'lg'];
+
+  return html`
+    ${gridStyles}
+    ${docsPage({
+      title   : 'Gutters',
+      lede    : 'The four gutter steps applied to the same four-column grid, so the difference is judged against identical content.',
+      children: refSection({
+        name    : 'Gutter scale',
+        meta    : '--grid-gutter-*',
+        children: html`
+          ${gutters.map(size => {
+            const token = `--grid-gutter-${size}`;
+            return html`
+              <p class="demo-label">${token} = ${resolve(token)}</p>
+              <div class="demo-frame">
+                <div class="demo-grid" style="--demo-cols: 4; gap: var(${token})">
+                  ${Array.from(
+                    { length: 4 },
+                    (_unused, index) => html`
+                      <div class="demo-cell ${index % 2 ? 'demo-cell--alt' : ''}">
+                        ${index + 1}
+                      </div>
+                    `
+                  )}
+                </div>
+              </div>
+            `;
+          })}
+        `
+      })
+    })}
+  `;
 };
-GutterExample.storyName = 'Grid Gutter';
-GutterExample.parameters = {
-  docs: {
-    description: {
-      story: 'Grid gutter (gap) system demonstrating different spacing options between columns. Shows visual comparison of no gutter, small, medium, and large gutters.'
-    }
-  }
-};