@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/tokens/typography.stories.js

@@ -1,1011 +1,1049 @@
 import { html } from 'lit';
+import { until } from 'lit/directives/until.js';
+import { ceilingWords, sampledLanguages, unsampledLanguages } from './type-ceiling-words.js';
+import {
+  copyToken,
+  discoverConsumers,
+  discoverTokens,
+  docsPage,
+  readAllCssText,
+  refSection,
+  referenceNote,
+  resolve,
+  toPx,
+  usageCell
+} from './story-chrome.js';
 
 export default {
-  title: 'Design Tokens/Typography',
-  tags : ['autodocs'],
-
-  argTypes: {
-    sampleText: {
-      control    : 'text',
-      description: 'Sample text to display typography examples',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'The quick brown fox jumps over the lazy dog.' }
-      }
-    },
-    showLineHeight: {
-      control    : 'boolean',
-      description: 'Show line height visualization',
-      table      : {
-        type        : { summary: 'boolean' },
-        defaultValue: { summary: 'true' }
-      }
-    },
-    showLetterSpacing: {
-      control    : 'boolean',
-      description: 'Show letter spacing visualization',
-      table      : {
-        type        : { summary: 'boolean' },
-        defaultValue: { summary: 'false' }
-      }
-    }
-  },
-
-  parameters: {
-    docs: {
-      description: {
-        component: `
-# Typography System
-
-Complete typography system with font families, sizes, weights, and spacing tokens for consistent text styling across the application.
-
-## Overview
-
-The typography system uses CSS custom properties to ensure consistency in font styling. It includes comprehensive scales for font sizes, weights, line heights, and letter spacing.
-
-## Design Tokens
-
-### Font Families
-| Token | Value | Use Case |
-|-------|-------|----------|
-| \`--font-family-sans\` | 'IBM Plex Sans', Arial, sans-serif | Primary UI font |
-| \`--font-family-mono\` | 'IBM Plex Mono', monospace | Code, technical content |
-
-### Font Sizes (Modular Scale)
-| Token | Value (rem) | Value (px) | Use Case |
-|-------|-------------|------------|----------|
-| \`--font-size-xs\` | 0.75rem | 12px | Labels, captions |
-| \`--font-size-sm\` | 0.875rem | 14px | Small body text |
-| \`--font-size-md\` | 1rem | 16px | Base body text |
-| \`--font-size-lg\` | 1.25rem | 20px | Subheadings |
-| \`--font-size-xl\` | 1.5rem | 24px | Headings |
-| \`--font-size-2xl\` | 2rem | 32px | Large headings |
-| \`--font-size-3xl\` | 2.5rem | 40px | Page titles |
-| \`--font-size-4xl\` | 3rem | 48px | Hero text |
-
-### Font Weights
-| Token | Value | Use Case |
-|-------|-------|----------|
-| \`--font-weight-light\` | 300 | Light text, subtle emphasis |
-| \`--font-weight-regular\` | 400 | Normal body text |
-| \`--font-weight-medium\` | 500 | Medium emphasis |
-| \`--font-weight-semibold\` | 600 | Strong emphasis, subheadings |
-| \`--font-weight-bold\` | 700 | Bold text, headings |
-| \`--font-weight-extrabold\` | 800 | Heavy emphasis, display text |
-
-### Line Heights
-| Token | Value | Use Case |
-|-------|-------|----------|
-| \`--line-height-tight\` | 1.2 | Headings, single lines |
-| \`--line-height-normal\` | 1.5 | Body text, paragraphs |
-| \`--line-height-relaxed\` | 1.75 | Long-form content |
-| \`--line-height-loose\` | 2 | Poetry, special layouts |
-
-### Letter Spacing
-| Token | Value | Use Case |
-|-------|-------|----------|
-| \`--letter-spacing-tighter\` | -0.05em | Condensed text |
-| \`--letter-spacing-tight\` | -0.025em | Slightly condensed |
-| \`--letter-spacing-normal\` | 0 | Normal text |
-| \`--letter-spacing-wide\` | 0.025em | Slightly expanded |
-| \`--letter-spacing-wider\` | 0.05em | Expanded text |
-| \`--letter-spacing-widest\` | 0.1em | Display text, headers |
-
-## Usage
-
-### Basic Typography
-\`\`\`css
-/* Using CSS custom properties */
-body {
-  font-family: var(--font-family-sans);
-  font-size: var(--font-size-md);
-  line-height: var(--line-height-normal);
-  font-weight: var(--font-weight-regular);
-}
-
-h1 {
-  font-size: var(--font-size-3xl);
-  font-weight: var(--font-weight-bold);
-  line-height: var(--line-height-tight);
-}
-
-code {
-  font-family: var(--font-family-mono);
-  font-size: var(--font-size-sm);
-}
-\`\`\`
-
-### Semantic CSS Classes
-\`\`\`html
-<p class="text-sm">Small text</p>
-<p class="text-lg font-semibold">Large semi-bold text</p>
-<p class="text-xl font-bold leading-tight">Extra large bold text with tight leading</p>
-<div class="font-mono text-sm">Monospace code text</div>
-\`\`\`
-
-### Responsive Typography
-\`\`\`css
-.heading {
-  font-size: var(--font-size-lg);
-  
-  @media (min-width: 768px) {
-    font-size: var(--font-size-xl);
-  }
-  
-  @media (min-width: 1024px) {
-    font-size: var(--font-size-2xl);
-  }
-}
-\`\`\`
-
-## Complete CSS Custom Properties
-
-\`\`\`css
-:root {
-  /* Font Families */
-  --font-family-sans: 'IBM Plex Sans', Arial, sans-serif;
-  --font-family-mono: 'IBM Plex Mono', monospace;
-  
-  /* Font Sizes */
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-md: 1rem;
-  --font-size-lg: 1.25rem;
-  --font-size-xl: 1.5rem;
-  --font-size-2xl: 2rem;
-  --font-size-3xl: 2.5rem;
-  --font-size-4xl: 3rem;
-  
-  /* Font Weights */
-  --font-weight-light: 300;
-  --font-weight-regular: 400;
-  --font-weight-medium: 500;
-  --font-weight-semibold: 600;
-  --font-weight-bold: 700;
-  --font-weight-extrabold: 800;
-  
-  /* Line Heights */
-  --line-height-tight: 1.2;
-  --line-height-normal: 1.5;
-  --line-height-relaxed: 1.75;
-  --line-height-loose: 2;
-  
-  /* Letter Spacing */
-  --letter-spacing-tighter: -0.05em;
-  --letter-spacing-tight: -0.025em;
-  --letter-spacing-normal: 0;
-  --letter-spacing-wide: 0.025em;
-  --letter-spacing-wider: 0.05em;
-  --letter-spacing-widest: 0.1em;
-  
-  /* Text Colors */
-  --text-color-primary: #212529;
-  --text-color-secondary: #6c757d;
-  --text-color-muted: #adb5bd;
-  --text-color-on-dark: #ffffff;
-}
-\`\`\`
-
-## Best Practices
-
-### 1. Use Relative Units
-\`\`\`css
-/* Good ✅ - Uses rem for accessibility */
-font-size: var(--font-size-md);
-
-/* Bad ❌ - Fixed pixels ignore user preferences */
-font-size: 16px;
-\`\`\`
-
-### 2. Maintain Hierarchy
-\`\`\`css
-h1 { font-size: var(--font-size-3xl); }
-h2 { font-size: var(--font-size-2xl); }
-h3 { font-size: var(--font-size-xl); }
-h4 { font-size: var(--font-size-lg); }
-h5 { font-size: var(--font-size-md); }
-h6 { font-size: var(--font-size-sm); }
-\`\`\`
-
-### 3. Ensure Readability
-- Minimum 16px (1rem) for body text
-- Line length between 45-75 characters
-- Contrast ratio of at least 4.5:1 for normal text
-- Adequate line spacing (1.5× for body text)
-
-### 4. Responsive Considerations
-- Increase font sizes on larger screens
-- Adjust line heights for different viewports
-- Consider touch targets for interactive text
-
-## Accessibility
-
-### Text Scaling
-All typography tokens use \`rem\` units, which respect the user's browser font size settings.
-
-### Color Contrast
-Ensure text meets WCAG 2.1 contrast requirements:
-- Normal text: 4.5:1 minimum
-- Large text (18px+): 3:1 minimum
-
-### Screen Readers
-- Use semantic HTML headings (h1-h6)
-- Provide alternative text for images
-- Ensure proper reading order
-- Test with screen readers
-
-## Browser Support
-
-All typography features are supported in modern browsers:
-- Chrome 60+
-- Firefox 55+
-- Safari 11+
-- Edge 79+
-
-For variable fonts support (if using IBM Plex Variable):
-- Chrome 60+
-- Firefox 62+
-- Safari 11+
-- Edge 17+
-
-## Performance
-
-- Use \`font-display: swap\` for web fonts
-- Subset fonts when possible
-- Consider system fonts as fallbacks
-- Implement font loading strategies
-
-## Testing
-
-Test typography with:
-- Different screen sizes and resolutions
-- High contrast modes
-- Screen magnifiers
-- Various browser zoom levels
-- Different operating systems
-        `
-      }
-    }
-  }
-};
-
-const typographyTokens = {
-  families: {
-    'Sans': 'var(--font-family-sans, "IBM Plex Sans", Arial, sans-serif)',
-    'Mono': 'var(--font-family-mono, "IBM Plex Mono", monospace)'
-  },
-  sizes: {
-    'xs' : 'var(--font-size-xs, 0.75rem)',
-    'sm' : 'var(--font-size-sm, 0.875rem)',
-    'md' : 'var(--font-size-md, 1rem)',
-    'lg' : 'var(--font-size-lg, 1.25rem)',
-    'xl' : 'var(--font-size-xl, 1.5rem)',
-    '2xl': 'var(--font-size-2xl, 2rem)',
-    '3xl': 'var(--font-size-3xl, 2.5rem)',
-    '4xl': 'var(--font-size-4xl, 3rem)'
-  },
-  weights: {
-    'light'    : 'var(--font-weight-light, 300)',
-    'regular'  : 'var(--font-weight-regular, 400)',
-    'medium'   : 'var(--font-weight-medium, 500)',
-    'semibold' : 'var(--font-weight-semibold, 600)',
-    'bold'     : 'var(--font-weight-bold, 700)',
-    'extrabold': 'var(--font-weight-extrabold, 800)'
-  },
-  lineHeights: {
-    'tight'  : 'var(--line-height-tight, 1.2)',
-    'normal' : 'var(--line-height-normal, 1.5)',
-    'relaxed': 'var(--line-height-relaxed, 1.75)',
-    'loose'  : 'var(--line-height-loose, 2)'
-  },
-  letterSpacing: {
-    'tighter': 'var(--letter-spacing-tighter, -0.05em)',
-    'tight'  : 'var(--letter-spacing-tight, -0.025em)',
-    'normal' : 'var(--letter-spacing-normal, 0)',
-    'wide'   : 'var(--letter-spacing-wide, 0.025em)',
-    'wider'  : 'var(--letter-spacing-wider, 0.05em)',
-    'widest' : 'var(--letter-spacing-widest, 0.1em)'
-  }
+  title: 'Foundations/Typography',
+  tags : ['autodocs']
 };
 
-const Template = (args) => html`
+const typeStyles = html`
   <style>
-    .typography-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);
+    .specimen-row {
+      padding: var(--spacing-16) 0;
+      border-bottom: var(--border-width-1) solid var(--color-neutral-100);
     }
-    
-    .section {
-      margin-bottom: var(--space-2xl);
-      padding-bottom: var(--space-lg);
-      border-bottom: 2px solid #f0f0f0;
+
+    .specimen-row:last-child {
+      border-bottom: 0;
     }
-    
-    .section-title {
-      font-family: var(--font-family-sans);
-      font-size: var(--font-size-xl);
-      font-weight: var(--font-weight-bold);
-      margin: 0 0 var(--space-lg) 0;
-      color: #212529;
+
+    .specimen-meta {
       display: flex;
-      align-items: center;
-      gap: var(--space-sm);
-    }
-    
-    .section-title::before {
-      content: '';
-      width: 4px;
-      height: 24px;
-      background: #007bff;
-      border-radius: 2px;
-    }
-    
-    .token-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-      gap: var(--space-md);
-    }
-    
-    .token-card {
-      padding: var(--space-md);
-      background: #f8f9fa;
-      border-radius: 6px;
-      border: 1px solid #e9ecef;
-      transition: all 0.2s ease;
+      flex-wrap: wrap;
+      gap: var(--spacing-4) var(--spacing-12);
+      margin-bottom: var(--spacing-8);
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-500);
     }
-    
-    .token-card:hover {
-      transform: translateY(-2px);
-      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
-      border-color: #007bff;
+
+    .specimen-meta .name {
+      color: var(--color-neutral-900);
+      font-weight: var(--typography-fontWeight-semibold);
     }
-    
-    .token-header {
-      display: flex;
-      justify-content: space-between;
-      align-items: flex-start;
-      margin-bottom: var(--space-sm);
+
+    /* Sample text is deliberately unstyled apart from the tokens under test. */
+    .specimen-text {
+      margin: 0;
+      color: var(--color-neutral-900);
+      /* long specimens should not force the page wide */
+      overflow-wrap: anywhere;
     }
-    
-    .token-name {
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-sm);
-      color: #007bff;
-      font-weight: var(--font-weight-semibold);
-      background: white;
-      padding: 2px 8px;
-      border-radius: 4px;
-      border: 1px solid #dee2e6;
+
+    .sample-cell {
+      color: var(--color-neutral-900);
+      white-space: nowrap;
     }
-    
-    .token-value {
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-xs);
-      color: #6c757d;
-      background: white;
-      padding: 2px 6px;
-      border-radius: 3px;
-      border: 1px solid #dee2e6;
+
+    /* Leading cannot be judged on one line, so this sample is deliberately
+       narrow enough to wrap. */
+    .leading-sample {
+      margin: 0;
+      width: 30ch;
+      min-width: 22ch;
+      font-size: var(--typography-fontSize-sm);
+      color: var(--color-neutral-900);
+      background: var(--color-blue-50);
     }
-    
-    .token-preview {
-      font-family: inherit;
-      font-size: inherit;
-      font-weight: inherit;
-      line-height: inherit;
-      letter-spacing: inherit;
-      margin: var(--space-sm) 0;
-      padding: var(--space-sm);
-      background: white;
-      border-radius: 4px;
-      border: 1px solid #dee2e6;
-      min-height: 60px;
+
+    .ratio-demo {
       display: flex;
-      align-items: center;
-    }
-    
-    .line-height-visual {
-      height: 40px;
-      background: linear-gradient(to bottom, 
-        transparent 0%, 
-        transparent calc(50% - 0.6px), 
-        #007bff calc(50% - 0.6px), 
-        #007bff calc(50% + 0.6px), 
-        transparent calc(50% + 0.6px), 
-        transparent 100%
-      );
-      margin-top: var(--space-xs);
-      position: relative;
+      flex-wrap: wrap;
+      gap: var(--spacing-24);
     }
-    
-    .line-height-label {
-      position: absolute;
-      right: 0;
-      top: 50%;
-      transform: translateY(-50%);
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-xs);
-      color: #6c757d;
-      background: white;
-      padding: 2px 6px;
-      border-radius: 3px;
-      border: 1px solid #dee2e6;
+
+    .ratio-demo figure {
+      margin: 0;
+      flex: 1 1 200px;
+      min-width: 180px;
     }
-    
-    .letter-spacing-visual {
-      display: flex;
-      align-items: center;
-      gap: 2px;
-      margin-top: var(--space-xs);
-      padding: var(--space-xs);
-      background: white;
-      border-radius: 4px;
-      border: 1px solid #dee2e6;
+
+    .ratio-demo figcaption {
+      font-family: var(--typography-fontFamily-mono);
+      font-size: var(--typography-fontSize-xxs);
+      color: var(--color-neutral-600);
+      margin-bottom: var(--spacing-6);
     }
-    
-    .letter-box {
-      width: 12px;
-      height: 20px;
-      background: #007bff;
-      border-radius: 2px;
-      opacity: 0.7;
+
+    .ratio-demo p {
+      margin: 0;
+      background: var(--color-blue-50);
+      color: var(--color-neutral-900);
     }
-    
-    .info-panel {
-      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-      color: white;
-      padding: var(--space-lg);
-      border-radius: 8px;
-      margin-bottom: var(--space-xl);
+
+    .rule-list {
+      margin: 0;
+      padding-left: var(--spacing-20);
+      font-size: var(--typography-fontSize-xs);
+      line-height: var(--typography-lineHeight-normal);
+      color: var(--color-neutral-700);
     }
-    
-    .info-title {
-      font-family: var(--font-family-sans);
-      font-size: var(--font-size-lg);
-      font-weight: var(--font-weight-bold);
-      margin: 0 0 var(--space-sm) 0;
+
+    .rule-list li + li {
+      margin-top: var(--spacing-6);
     }
-    
-    .info-text {
-      font-family: var(--font-family-sans);
-      font-size: var(--font-size-sm);
-      opacity: 0.9;
-      margin: 0;
+
+    .rule-list code {
+      font-family: var(--typography-fontFamily-mono);
     }
   </style>
+`;
+
+/* ---------- primitive scales ---------- */
 
-  <div class="typography-container">
-    <div class="info-panel">
-      <h3 class="info-title">Typography System</h3>
-      <p class="info-text">${args.sampleText}</p>
+function primitiveTable({ caption, tokens, consumers, sample, leading }) {
+  return html`
+    <div class="table-scroll">
+      <table>
+        <caption>${caption}</caption>
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">Value</th>
+            ${leading ? html`<th scope="col">At 16px</th>` : ''}
+            ${sample ? html`<th scope="col">Sample</th>` : ''}
+            ${leading ? html`<th scope="col">Leading</th>` : ''}
+            <th scope="col">Referenced by</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${tokens.map(token => {
+            const value = resolve(token);
+            // a rem step is hard to place without the pixel value beside it
+            const px = toPx(value);
+            return html`
+              <tr>
+                <td>${copyToken(token)}</td>
+                <td class="num">
+                  ${value}${px ? html`<span class="px-hint">${px}</span>` : ''}
+                </td>
+                ${leading
+                  ? html`<td class="num muted">${(parseFloat(value) * 16).toFixed(parseFloat(value) * 16 % 1 ? 2 : 0)}px</td>`
+                  : ''}
+                ${sample
+                  ? html`<td class="sample-cell" style=${sample(token)}>Aa Bb Cc 123</td>`
+                  : ''}
+                ${leading
+                  ? html`<td>
+                      <p class="leading-sample" style="line-height: var(${token})">
+                        Leading only becomes visible across more than one line, so this
+                        sample is deliberately narrow enough to wrap onto three.
+                      </p>
+                    </td>`
+                  : ''}
+                <td>${usageCell(consumers.get(token))}</td>
+              </tr>
+            `;
+          })}
+        </tbody>
+      </table>
     </div>
+  `;
+}
+
+function tokensMatching(cssText, pattern) {
+  return discoverTokens(cssText, pattern).map(match => match[1]);
+}
+
+/* ---------------------------------------------------------------------------
+   Nine roles are fluid. This page renders them live at the current viewport
+   AND states what they resolve to at each of the seven column widths, so the
+   numbers can be checked against what the browser is actually doing rather
+   than against a table somebody typed.
+
+   The column widths are derived from the grid tokens, not measured: a
+   Storybook story sits inside 16px of harness body padding either side, and
+   measuring one is how a 288px column once got recorded as 256 and moved a
+   conclusion by a whole step of the type scale. */
+const FLUID = [
+  ['heading-h1', 48, 30, 'Bold'],
+  ['heading-h2', 36, 27, 'Bold'],
+  ['heading-h3', 32, 24, 'SemiBold'],
+  ['heading-h4', 24, 21, 'SemiBold'],
+  ['heading-h5', 20, 18, 'Medium'],
+  ['heading-h6', 18, 16, 'Medium'],
+  ['display-md', 48, 30, 'Bold'],
+  ['display-sm', 36, 30, 'Bold'],
+  ['body-lead', 20, 18, 'Regular']
+];
+/* viewport -> column, from --grid-container-max-* minus 2x --grid-padding-* */
+const COLUMNS = [[320, 288], [375, 343], [576, 492], [768, 656], [992, 880], [1200, 1060], [1400, 1240]];
+const WINDOW = [320, 992];
+
+/** What the clamp resolves to at a given viewport width, in px. */
+const fluidAt = (vw, min, max) => {
+  const [v1, v2] = WINDOW;
+  if (vw <= v1) return min;
+  if (vw >= v2) return max;
+  return min + ((max - min) * (vw - v1)) / (v2 - v1);
+};
+
+/* ---------------------------------------------------------------------------
+   The evidence the mobile ladder was chosen from, rendered LIVE rather than
+   transcribed from the Figma study.
+
+   Live matters here: it measures the real IBM Plex Sans in the reader's own
+   browser at the reader's own viewport, so it cannot drift from the file the
+   way a pasted table can, and it re-measures when you resize. The Figma page
+   "Type on mobile" holds the same study as a fixed artifact for designers;
+   this is the developer's copy, and if the two ever disagree the browser wins.
+
+   The words are representative compounds written for the study, NOT strings
+   from the real translation memory -- English is roughly twice as permissive
+   as German and Finnish, so English alone would flatter every number here. */
+/* From src/tokens/type-ceiling-words.js, which carries the provenance of every
+   entry -- `tm` for a real translation-memory string, `representative` for a
+   plausible compound written for the study, `outlier` for a deliberately
+   extreme one that is shown but never sets a ceiling. Entries marked `retired`
+   are excluded from the worst case: Finnish does not ship, and the three fi
+   words are kept only because the shipped ladder was calibrated against the
+   widest of them. */
+const CEILING_WORDS = ceilingWords.words
+  .filter(w => !w.retired)
+  .map(w => [w.lang, w.word, w.source, w.observedAt || 0]);
+const RETIRED_WORDS = ceilingWords.words
+  .filter(w => w.retired)
+  .map(w => [w.lang, w.word, w.source, 0]);
 
-    <!-- Font Families -->
-    <div class="section">
-      <h3 class="section-title">Font Families</h3>
-      <div class="token-grid">
-        ${Object.entries(typographyTokens.families).map(([name, family]) => html`
-          <div class="token-card">
-            <div class="token-header">
-              <span class="token-name">--font-family-${name.toLowerCase()}</span>
-              <span class="token-value">${family}</span>
+/* The face every measurement on this page depends on. Spelled once, because
+   it is passed to fonts.load(), asserted with fonts.check(), and named in the
+   banner the story shows when the assertion fails. */
+const PLEX_BOLD = '700 100px "IBM Plex Sans"';
+
+/* Set by widthPer100 whenever it is asked to measure before the face is
+   available. It must stay false; the story renders a red banner if it does not,
+   because the alternative is a page of numbers that are quietly ~3% wrong. */
+let measuredWithoutPlex = false;
+
+/** Width of `text` at 100px in `weight`, measured in this browser. */
+function widthPer100(text, weight) {
+  /* THE BUG THIS GUARDS, measured 2026-09-17. Before the await was added below,
+     this page rendered its tables at whatever font was available when the story
+     function ran -- which on a cold load is system-ui, not Plex. The same word
+     measured 9.045 px per px of size in Plex Bold and 8.778 in system-ui Bold,
+     so every number on the page came out about 3% low, INTERMITTENTLY, and the
+     ranking itself could change: `worst` is chosen by width, so a fallback
+     render can hand the title to a different word.
+     That 3% is the whole of the "Figma renders 3.5% wider than the browser"
+     discrepancy this study recorded and then reasoned from. There is no
+     renderer difference. There was a font race.
+     scripts/verify-runtime.mjs has carried the same lesson since P1.5 -- and
+     its own header says why it recurred: the await had been written
+     per-investigation. This was another investigation. */
+  if (!document.fonts.check(PLEX_BOLD)) measuredWithoutPlex = true;
+  const el = document.createElement('span');
+  el.style.cssText = 'position:absolute;visibility:hidden;white-space:nowrap;'
+    + 'font-family:var(--typography-fontFamily-sans);letter-spacing:0;font-size:100px;'
+    + `font-weight:${weight}`;
+  el.textContent = text;
+  document.body.appendChild(el);
+  const w = el.getBoundingClientRect().width / 100;
+  el.remove();
+  return w;
+}
+
+const whyTheseSizes = async () => {
+  /* Nothing below may run before the face lands -- see widthPer100. load()
+     rather than ready(), because ready() resolves when nothing more is
+     PENDING, and a face nobody has asked for yet is not pending. */
+  await document.fonts.load(PLEX_BOLD);
+  await document.fonts.ready;
+  /* measured on demand, so a font swap or a metric change shows up here */
+  const measure = ([lang, word, source, observedAt]) => {
+    const per = widthPer100(word, 700);
+    return {
+      lang, word, source, observedAt, per,
+      tier    : observedAt >= 40 ? 'headline' : 'feature',
+      ceilings: COLUMNS.map(([, col]) => Math.floor(col / per))
+    };
+  };
+  const rows = CEILING_WORDS.map(measure);
+  const retired = RETIRED_WORDS.map(measure);
+  /* An `outlier` is shown and never sets a ceiling -- that is what the source
+     vocabulary is for, rather than excluding a word by name. */
+  const worst = rows.filter(r => r.source !== 'outlier')
+    .reduce((a, r) => (r.per > a.per ? r : a));
+  const worstRetired = retired.length
+    ? retired.reduce((a, r) => (r.per > a.per ? r : a))
+    : null;
+  /* The tier split is the whole point of the 2026-09-17 harvest: the widest
+     tokens are real, and they are FEATURE copy. `worst` is the widest token in
+     any tier -- the conservative ceiling. `headlineWorst` is the widest token
+     actually observed playing the part heading-h1 plays, which is the one that
+     decides whether h1's mobile size is wrong or merely tight. */
+  const headline = rows.filter(r => r.tier === 'headline' && r.source !== 'outlier');
+  const headlineWorst = headline.length
+    ? headline.reduce((a, r) => (r.per > a.per ? r : a))
+    : null;
+  /* Per role, against both worsts, on the two phone columns. */
+  const exposure = FLUID.map(([name, , min]) => ({
+    name,
+    min,
+    all     : [288, 343].map(col => Math.round(worst.per * min) <= col),
+    headline: headlineWorst
+      ? [288, 343].map(col => Math.round(headlineWorst.per * min) <= col)
+      : [true, true],
+    needAll     : Math.round(worst.per * min),
+    needHeadline: headlineWorst ? Math.round(headlineWorst.per * min) : 0
+  }));
+  const overAnywhere = exposure.filter(e => !e.all[0] || !e.all[1]);
+
+  return html`
+    ${typeStyles}
+    ${docsPage({
+      title: 'Why these sizes',
+      lede : html`The measurement the mobile ladder was derived from, run live in your browser.
+        For large type the binding constraint is not how many lines a sentence takes — it is
+        whether the longest <b>unbreakable word</b> fits the column. A word wider than its column
+        overflows or hyphenates, and neither is a size anyone chose.`,
+      note: html`<b>These are real words now.</b> Every entry was harvested on 2026-09-17 from
+        live localized <code>bitdefender.com</code> copy rendering at 24px or more — nine
+        languages, two product pages each — and carries the page it came from and the size that
+        page sets it at. The invented compounds this study started with are gone, and so is the
+        Finnish word the shipped ladder was actually calibrated against: Finnish does not sell.
+        The widest English token in the sample is 31% narrower than the widest Swedish one —
+        a 41px ceiling against 28 on the same column — so an English-only check does not merely
+        pass one size that overflows elsewhere, it passes every size on the ladder.
+        ${referenceNote}`,
+      children: html`
+        ${measuredWithoutPlex
+          ? html`<p style="border: 2px solid var(--color-text-error); padding: var(--spacing-16);
+                      color: var(--color-text-error)">
+        <b>These numbers are wrong — do not read them.</b> At least one measurement ran before
+        <code>${PLEX_BOLD}</code> had a loaded face, so it measured a fallback font, which is
+        about 3% narrower. Reload. This banner exists because the page used to do this silently.
+      </p>`
+          : ''}
+        <p>
+          Word width scales linearly with font size, so one measurement per word gives the
+          ceiling at every size: <b>ceiling = column ÷ (width per px of size)</b>. The widest
+          real token in the sample is <b>${worst.word}</b> (${worst.lang},
+          ${(worst.per * 100).toFixed(0)}px per 100px), which puts the ceiling on a 288px column
+          at <b>${Math.floor(288 / worst.per)}px</b> — below <code>heading-h1</code>'s mobile
+          30. ${headlineWorst
+            ? html`But it is <b>feature copy</b>, set at ${worst.observedAt}px on its own page. The
+            widest token observed doing <code>heading-h1</code>'s job is
+            <b>${headlineWorst.word}</b> (${headlineWorst.lang},
+            ${(headlineWorst.per * 100).toFixed(0)}px per 100px), whose ceiling is
+            <b>${Math.floor(288 / headlineWorst.per)}px</b> — above 30, by one.`
+            : ''}
+        </p>
+        <p>
+          <b>That gap is the finding, and it is why the ladder did not move.</b> Both numbers are
+          real. Which one binds depends on whether a twenty-character compound from a feature
+          list can ever be promoted into a headline — a copy question, not a token question.
+        </p>
+        ${refSection({
+          name    : 'Language coverage — complete, for every language this model applies to',
+          meta    : `${sampledLanguages.length} of ${ceilingWords.shippingLanguages.languages.length} shipping languages sampled from production copy · the other ${Object.keys(ceilingWords.wrappingCaveats).length} wrap per character`,
+          children: html`
+            <p>
+              <b>Sampled, from shipped copy:</b>
+              ${sampledLanguages.map(l => html`<code>${l}</code> `)} — all nine of the
+              eleven shipping languages that wrap on spaces, the other two being
+              ${Object.keys(ceilingWords.wrappingCaveats).map(l => html`<code>${l}</code> `)}
+              below —
+              ${rows.length} tokens, harvested ${ceilingWords.harvest.date} from
+              <code>/consumer/total-security</code> and
+              <code>/consumer/ultimate-security</code> in each market.
+            </p>
+            <p>
+              <b>The ladder that shipped was calibrated against a language this product does not
+              sell in.</b> Its worst case was Finnish <i>Henkilöllisyyssuoja</i>${worstRetired
+                ? html` (${(worstRetired.per * 100).toFixed(0)}px per 100px)`
+                : ''}, and there is no <code>fi-FI</code> locale in <code>localeMap.js</code>.
+              The three Finnish words stay in the sample file marked <code>retired</code> —
+              deleting them would erase the record of what the shipped ladder was sized against —
+              and they set no number on this page. <b>The production harvest has since found
+              three real tokens wider than that Finnish one</b>, in Swedish, Dutch and German.
+            </p>
+            <p>
+              <b>Not sampled: ${unsampledLanguages.length
+                ? html`${unsampledLanguages.map(l => html`<code>${l}</code> `)}`
+                : html`nothing`}.</b> Coverage is complete for every shipping language this
+              model applies to, and the last gap closed by turning out not to be one.
+              Hungarian was listed here as an untested compounding language because no
+              Hungarian copy could be found. There is none: <b>Hungary is an English
+              market</b>, served at <code>/en-hu/</code>.
+            </p>
+            <p>
+              Finding that took a defect with it. The footer had the locale as
+              <code>hu-HU</code>, and <code>footer.js</code> navigates to
+              <code>/{locale}/</code> on country click — so picking Hungary sent the user
+              to <code>/hu-hu/</code>, which is rewritten to <code>/en-us/hu-hu/</code>
+              and returns 404. It was the only one of the 46 roots that did not resolve.
+              <code>localeMap.js</code> says <code>en-HU</code> — <i>Hungary -
+              English</i> — now, and all 46 resolve. Hungarian is no longer claimed as a
+              language this product sells in, which is why it is no longer counted as
+              unsampled.
+            </p>
+            <p>
+              <b>Not applicable:</b>
+              ${Object.keys(ceilingWords.wrappingCaveats).map(l => html`<code>${l}</code> `)} —
+              they wrap between characters, so the longest-word constraint barely applies. The
+              relevant question there is characters per line at roughly one em per glyph, which
+              this study still does not model.
+            </p>
+            <p>
+              <b>What changed, and what did not.</b> The margin is measured now instead of
+              unknown. The numbers did not move the ladder: they moved the worst case
+              <i>up</i> in the feature tier and confirmed it in the headline tier, and those two
+              results argue in opposite directions — see the next section.
+            </p>
+          `
+        })}
+        ${refSection({
+          name: 'Which role is actually exposed',
+          meta: overAnywhere.length
+            ? `${overAnywhere.length} of ${exposure.length} roles overflow against the widest real token — all three at the same 30px floor`
+            : 'no role overflows against the widest real token',
+          children: html`
+            <p>
+              The ladder is nine fluid roles, and only the mobile end of each can overflow. Each
+              row asks the same question twice: does the role's <b>320px size</b> fit the column
+              when set in the widest real token of any tier, and when set in the widest token
+              observed doing headline work?
+            </p>
+            <div style="overflow-x: auto">
+              <table class="tokens-table">
+                <caption>
+                  Fits at the role's 320px size · any-tier worst is
+                  <b>${worst.word}</b> (${worst.lang})${headlineWorst
+                    ? html` · headline-tier worst is <b>${headlineWorst.word}</b> (${headlineWorst.lang})`
+                    : ''}
+                </caption>
+                <thead>
+                  <tr>
+                    <th>role</th><th>size at 320</th>
+                    <th>any tier<br /><small>288px col</small></th>
+                    <th>any tier<br /><small>343px col</small></th>
+                    <th>headline tier<br /><small>288px col</small></th>
+                    <th>headline tier<br /><small>343px col</small></th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${exposure.map(e => html`
+                    <tr>
+                      <td><code>${e.name}</code></td>
+                      <td>${e.min}px</td>
+                      <td style="color: ${e.all[0] ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+                        ${e.needAll}px — ${e.all[0] ? 'fits' : 'OVER'}
+                      </td>
+                      <td style="color: ${e.all[1] ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+                        ${e.needAll}px — ${e.all[1] ? 'fits' : 'OVER'}
+                      </td>
+                      <td style="color: ${e.headline[0] ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+                        ${e.needHeadline}px — ${e.headline[0] ? 'fits' : 'OVER'}
+                      </td>
+                      <td style="color: ${e.headline[1] ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+                        ${e.needHeadline}px — ${e.headline[1] ? 'fits' : 'OVER'}
+                      </td>
+                    </tr>
+                  `)}
+                </tbody>
+              </table>
             </div>
-            <div class="token-preview" style="font-family: ${family};">
-              ${args.sampleText}
+            <p style="margin-top: var(--spacing-16)">
+              <b>The exposure is one size, on one tier, at one viewport.</b> Everything at
+              27px and below fits every real token in the sample at both phone columns. The
+              30px floor is shared by three roles — <code>heading-h1</code>,
+              <code>display-md</code> and <code>display-sm</code> — and all three clear the
+              headline-tier worst and fail the feature-tier worst, on the 288px column only,
+              because 343px absorbs even the widest token in the set.
+            </p>
+            <p>
+              <b>So the ladder stays at 30, and now for a reason rather than an artefact.</b>
+              Dropping the floor to ${Math.floor(288 / worst.per)} would buy protection against a
+              headline nobody has written — no twenty-character compound appears above 24px in
+              any of the nine markets — and would spend a real step of hierarchy to do it, on the
+              one role whose whole job is to outrank the rest. What the measurement buys instead
+              is a copy constraint that can be stated: <b>a headline token wider than
+              ${(288 / 30 * 100).toFixed(0)}px per 100px of size overflows a 320px phone</b>, and
+              five real tokens in <code>sv</code>, <code>nl</code> and <code>de</code> exceed it.
+              None of them is a headline today.
+            </p>
+          `
+        })}
+        ${refSection({
+          name    : 'The ceiling, per word and per column',
+          meta    : `${rows.length} words · Bold · measured in this browser`,
+          children: html`
+            <div style="overflow-x: auto">
+              <table class="tokens-table">
+                <caption>Largest font size at which the word still fits the column</caption>
+                <thead>
+                  <tr>
+                    <th>lang</th><th>word</th><th>source</th><th>seen at</th><th>w / 100px</th>
+                    ${COLUMNS.map(([vw, col]) => html`<th>${vw}<br /><small>${col}px</small></th>`)}
+                  </tr>
+                </thead>
+                <tbody>
+                  ${rows.map(r => html`
+                    <tr>
+                      <td><code>${r.lang}</code></td>
+                      <td>${r.word}</td>
+                      <td><code>${r.source}</code></td>
+                      <td>${r.observedAt ? html`${r.observedAt}px · ${r.tier}` : '—'}</td>
+                      <td>${(r.per * 100).toFixed(0)}</td>
+                      ${r.ceilings.map(c => html`<td>${c}</td>`)}
+                    </tr>
+                  `)}
+                </tbody>
+              </table>
             </div>
-          </div>
-        `)}
-      </div>
-    </div>
-
-    <!-- Font Sizes -->
-    <div class="section">
-      <h3 class="section-title">Font Sizes</h3>
-      <div class="token-grid">
-        ${Object.entries(typographyTokens.sizes).map(([name, size]) => html`
-          <div class="token-card">
-            <div class="token-header">
-              <span class="token-name">--font-size-${name}</span>
-              <span class="token-value">${size}</span>
+          `
+        })}
+        ${refSection({
+          name    : 'The same thing, visible',
+          meta    : 'the dashed edge is the column — red type crosses it',
+          children: html`
+            <p style="margin-bottom: var(--spacing-16)">
+              <b>The mobile ladder's own steps</b> — 16 / 18 / 21 / 24 / 27 / 30 — plus the two
+              desktop sizes above them, set in <b>${worst.word}</b> inside a 288px column, which
+              is what type gets on a 320px phone. Read down: the first size that crosses the
+              dashed edge is where this word stops fitting, and it lands exactly on the ladder's
+              top step.
+            </p>
+            <p style="margin-bottom: var(--spacing-16)">
+              <b>Correction, 2026-09-17: Figma and this browser agree to within 0.05%, and the
+              3.5% margin this study thought it had was a font race in this very page.</b> The
+              Figma study on page <i>Type on mobile</i> records the Finnish compound at
+              <b>907px per 100px</b>. Measured here in Plex Bold it is
+              ${worstRetired ? html`<b>${(worstRetired.per * 100).toFixed(1)}</b>` : ''} — the
+              same number, and it is not one lucky word: <b>seven were then measured in both
+              tools</b> — 1017/1016.2, 1015/1014.8, 1011/1010.5, 905/904.5, 792/791.4,
+              907/906.6, 844/843.5 — agreeing to within 0.1% every time. What reproduces the 875
+              that was written down as "the browser" is <b>the same word in system-ui Bold:
+              874.1</b>, because this page measured before the Plex face had loaded and silently
+              read the fallback. Same cause, same 3%, and
+              it could also change <i>which</i> word won the worst-case title, since the ranking
+              is by width. The measurement now waits for the face and says so if it ever cannot.
+              The rule that came out of the discrepancy survives, because it never depended on
+              the number: where the two disagree about whether something <i>renders</i>, the
+              browser is right; where they disagree about what to <i>ship</i>, the conservative
+              number is. But there was no renderer margin, and the ladder must not be credited
+              with one. The word on screen here is <b>${worst.word}</b> at
+              ${(worst.per * 100).toFixed(0)}px per 100px, production copy the Figma study never
+              saw.
+            </p>
+            <div style="width: 288px; max-width: 100%; border: 2px dashed var(--color-text-error);
+                        padding-block: var(--spacing-16); display: grid; gap: var(--spacing-16)">
+              ${[16, 18, 21, 24, 27, 30, 36, 48].map(size => {
+                const need = Math.round(worst.per * size);
+                const fits = need <= 288;
+                return html`
+                  <div>
+                    <div style="font-family: var(--typography-fontFamily-mono);
+                                font-size: var(--typography-fontSize-xxs);
+                                color: ${fits ? 'var(--color-text-muted)' : 'var(--color-text-error)'}">
+                      ${size}px · needs ${need}px · ${fits ? `fits by ${288 - need}` : `OVER by ${need - 288}`}
+                    </div>
+                    <div style="font-size: ${size}px; font-weight: var(--typography-fontWeight-bold);
+                                line-height: var(--typography-lineHeight-tight);
+                                white-space: nowrap;
+                                color: ${fits ? 'var(--color-text-primary)' : 'var(--color-text-error)'}">
+                      ${worst.word}
+                    </div>
+                  </div>
+                `;
+              })}
             </div>
-            <div class="token-preview" style="font-size: ${size};">
-              ${args.sampleText}
+          `
+        })}
+        ${refSection({
+          name    : 'And what the roles do about it',
+          meta    : 'the same word, at each fluid role, live at your viewport',
+          children: html`
+            <p style="margin-bottom: var(--spacing-16)">
+              Resize the window: every line below changes size, and none of them crosses its
+              column at any width. Compare with the block above, where the sizes are fixed.
+            </p>
+            <div style="display: grid; gap: var(--spacing-16)">
+              ${FLUID.map(([name, max, min]) => html`
+                <div>
+                  <div style="font-family: var(--typography-fontFamily-mono);
+                              font-size: var(--typography-fontSize-xxs);
+                              color: var(--color-text-muted)">
+                    ${name} · ${min}px at 320 → ${max}px at 992
+                  </div>
+                  <div style="font-size: var(--typography-${name}-fontSize);
+                              font-weight: var(--typography-${name}-fontWeight);
+                              line-height: var(--typography-${name}-lineHeight);
+                              color: var(--color-text-primary)">${worst.word}</div>
+                </div>
+              `)}
             </div>
-            ${args.showLineHeight
-              ? html`
-              <div class="line-height-visual" style="height: calc(${size} * var(--line-height-normal));">
-                <span class="line-height-label">Line height: ${size}</span>
-              </div>
-            `
-              : ''}
-          </div>
-        `)}
-      </div>
-    </div>
+          `
+        })}
+      `
+    })}
+  `;
+};
 
-    <!-- Font Weights -->
-    <div class="section">
-      <h3 class="section-title">Font Weights</h3>
-      <div class="token-grid">
-        ${Object.entries(typographyTokens.weights).map(([name, weight]) => html`
-          <div class="token-card">
-            <div class="token-header">
-              <span class="token-name">--font-weight-${name}</span>
-              <span class="token-value">${weight}</span>
+/* The measurement is async now, so the story resolves a promise rather than
+   returning a template. `until` renders the placeholder for the one frame the
+   font takes on a warm cache, and for however long it takes on a cold one --
+   which is the point: a visible "measuring" beats an invisible wrong number. */
+export const WhyTheseSizes = () => html`${until(
+  whyTheseSizes(),
+  html`<p style="font-family: var(--typography-fontFamily-mono);
+                 font-size: var(--typography-fontSize-xs);
+                 color: var(--color-text-muted)">
+    Loading IBM Plex Sans Bold before measuring anything…
+  </p>`
+)}`;
+
+export const FluidType = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+  return html`
+    ${typeStyles}
+    ${docsPage({
+      title: 'Fluid type',
+      lede : html`Nine roles change size with the viewport. The minimum is reached at
+        <b>320px</b> and the maximum — the size this system already shipped — at
+        <b>992px</b>, the <code>lg</code> breakpoint. <b>Above lg nothing changed</b>, so every
+        desktop layout that has been reviewed renders exactly as reviewed.`,
+      note: html`<b>Why the role and not <code>bd-h</code>.</b> More than one thing reads these
+        roles — the hero's final price reads <code>--typography-heading-h2-*</code> directly, and
+        so does <code>blog-heading</code>. A media query inside <code>heading.css.js</code> would
+        have made one role render 36px in some places and 32px in others, and would have failed at
+        the job it was for: the headline would have dropped while the price stayed, flattening the
+        hierarchy it was meant to protect. ${referenceNote}`,
+      children: html`
+        <p>
+          <b>The constraint is a long word, not a long sentence.</b> What decides whether large
+          type works on a phone is whether the longest <b>unbreakable word</b> fits the column —
+          and the column is the viewport minus twice <code>--grid-padding-*</code>, so a 320px
+          phone gives type 288px. Against that column the widest token in shipped copy
+          (Swedish <i>kalenderinbjudningar</i>, harvested 2026-09-17) tops out at <b>28px</b>,
+          and the widest token observed doing a headline's job (German
+          <i>Gründungsmitglied</i>) at <b>31px</b>. <code>heading-h1</code> is 48, so it
+          overflowed at 375 as well as 320 — in German, Dutch and Swedish. See
+          <i>Why these sizes</i> for the per-role exposure and the tier split.
+        </p>
+        <p>
+          <b>A breakpoint step was tried first and abandoned.</b> Stepping h1 to 36 below
+          <code>sm</code> still overflows at 320 and changes nothing at 576–767, where the ceiling
+          is already 54. The constraint moves continuously with the column, because the column is
+          a function of viewport width — a step function approximates a line with a staircase.
+        </p>
+        <p>
+          <b>The middle term carries a <code>rem</code>, and that is not optional.</b>
+          <code>clamp(2rem, 4vw, 3rem)</code> is the spelling everyone reaches for and it breaks
+          text resize: a size depending only on viewport width ignores the reader's own font-size
+          setting, which is WCAG 1.4.4. Same principle as unitless <code>line-height</code> and
+          rem <code>--spacing-*</code>.
+        </p>
+        <p>
+          <b>The mobile ladder is the design decision</b> — 30 / 27 / 24 / 21 / 18 / 16 for h1–h6,
+          held in six <code>--typography-*-fontSizeMin</code> tokens. Its ratios are even
+          (1.11–1.17) against the desktop ladder's irregular 1.33 / 1.13 / 1.33 / 1.20 / 1.11,
+          because a phone has less range to spend: 16 to the 31px ceiling is a factor of 1.94
+          where desktop has 18 to 48, a factor of 2.67.
+        </p>
+        <p>
+          <b><code>display-lg</code> and above are desktop-only.</b> Five roles from 60 to 128px
+          cannot squeeze between 30px and a 31px ceiling, so the family has no mobile identity
+          above <code>display-md</code>. A component that needs one on a phone should take a
+          heading role.
+        </p>
+        <p>
+          <b>Do not judge a phone's measure against 45–75 characters per line.</b> That band is a
+          print and desktop yardstick. Reaching 45 CPL on a 288px column needs 14.2px body text
+          and 50 CPL needs 12.8px, so applying it to a phone trades the 16px floor for a soft
+          target. <code>body-regular</code> runs 40 characters there and stays 16px.
+          <code>body-lead</code> is the one prose role that moves, 20 → 18.
+        </p>
+        ${refSection({
+          name    : 'What each role resolves to',
+          meta    : `${FLUID.length} fluid roles · clamp(min, rem + vw, max) · window 320–992`,
+          children: html`
+            <div style="overflow-x: auto">
+              <table class="tokens-table">
+                <caption>Resolved size in px at each viewport. Column = viewport − 2 × gutter.</caption>
+                <thead>
+                  <tr>
+                    <th>role</th><th>weight</th>
+                    ${COLUMNS.map(([vw, col]) => html`<th>${vw}<br /><small>${col}px col</small></th>`)}
+                  </tr>
+                </thead>
+                <tbody>
+                  ${FLUID.map(([name, max, min, weight]) => html`
+                    <tr>
+                      <td><code>--typography-${name}-fontSize</code></td>
+                      <td>${weight}</td>
+                      ${COLUMNS.map(([vw]) => html`<td>${fluidAt(vw, min, max).toFixed(1)}</td>`)}
+                    </tr>
+                  `)}
+                </tbody>
+              </table>
             </div>
-            <div class="token-preview" style="font-weight: ${weight};">
-              ${args.sampleText}
+          `
+        })}
+        ${refSection({
+          name    : 'Live, at this viewport',
+          meta    : 'resize the window — every line below moves',
+          children: html`
+            <div style="display: grid; gap: var(--spacing-16)">
+              ${FLUID.map(([name]) => html`
+                <div>
+                  <div style="font-family: var(--typography-fontFamily-mono);
+                              font-size: var(--typography-fontSize-xs);
+                              color: var(--color-text-muted)">${name}</div>
+                  <div style="font-size: var(--typography-${name}-fontSize);
+                              font-weight: var(--typography-${name}-fontWeight);
+                              line-height: var(--typography-${name}-lineHeight);
+                              letter-spacing: var(--typography-${name}-letterSpacing);
+                              font-family: var(--typography-${name}-fontFamily);
+                              color: var(--color-text-primary)">Henkilöllisyyssuoja</div>
+                </div>
+              `)}
             </div>
-          </div>
-        `)}
-      </div>
-    </div>
+          `
+        })}
+        ${refSection({
+          name    : 'The minimums',
+          meta    : '9 tokens · --typography-*-fontSizeMin · the mobile ladder',
+          children: primitiveTable({
+            caption: 'Mobile endpoint tokens',
+            tokens : FLUID.map(([name]) => `--typography-${name}-fontSizeMin`),
+            consumers,
+            sample : token => `font-size: var(${token})`
+          })
+        })}
+      `
+    })}
+  `;
+};
 
-    <!-- Line Heights -->
-    ${args.showLineHeight
-      ? html`
-      <div class="section">
-        <h3 class="section-title">Line Heights</h3>
-        <div class="token-grid">
-          ${Object.entries(typographyTokens.lineHeights).map(([name, lineHeight]) => html`
-            <div class="token-card">
-              <div class="token-header">
-                <span class="token-name">--line-height-${name}</span>
-                <span class="token-value">${lineHeight}</span>
-              </div>
-              <div class="token-preview" style="line-height: ${lineHeight};">
-                ${args.sampleText}<br>
-                ${args.sampleText}
-              </div>
-              <div class="line-height-visual" style="height: calc(1rem * ${lineHeight});">
-                <span class="line-height-label">${lineHeight}</span>
+export const TypographyScale = () => {
+  const cssText = readAllCssText();
+  const consumers = discoverConsumers(cssText);
+
+  const families = tokensMatching(cssText, /(--typography-fontFamily-[a-zA-Z0-9-]+)\s*:/g);
+  const sizes = tokensMatching(cssText, /(--typography-fontSize-[a-zA-Z0-9]+)\s*:/g);
+  const weights = tokensMatching(cssText, /(--typography-fontWeight-[a-zA-Z0-9]+)\s*:/g);
+  const lineHeights = tokensMatching(cssText, /(--typography-lineHeight-[a-zA-Z0-9]+)\s*:/g);
+  const tracking = tokensMatching(cssText, /(--typography-letterSpacing-[a-zA-Z0-9]+)\s*:/g);
+
+  return html`
+    ${typeStyles}
+    ${docsPage({
+      title: 'Type scale',
+      lede : html`The primitive typography 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`These are the raw scales. For a style you can apply directly to a heading, a
+        paragraph or a label, use the composed tokens on the <b>Typography</b> page — those are
+        what components consume. ${referenceNote}`,
+      children: html`
+        ${refSection({
+          name    : 'Font family',
+          meta    : `${families.length} tokens · --typography-fontFamily-*`,
+          children: primitiveTable({
+            caption: 'Font family tokens',
+            tokens : families,
+            consumers,
+            sample : token => `font-family: var(${token})`
+          })
+        })}
+        ${refSection({
+          name    : 'Font size',
+          meta    : `${sizes.length} steps · --typography-fontSize-*`,
+          children: primitiveTable({
+            caption: 'Font size scale',
+            tokens : sizes,
+            consumers,
+            sample : token => `font-size: var(${token}); line-height: 1.2`
+          })
+        })}
+        ${refSection({
+          name    : 'Font weight',
+          meta    : `${weights.length} steps · --typography-fontWeight-*`,
+          children: primitiveTable({
+            caption: 'Font weight scale',
+            tokens : weights,
+            consumers,
+            sample : token => `font-weight: var(${token}); font-size: var(--typography-fontSize-lg)`
+          })
+        })}
+        ${refSection({
+          name    : 'Line height',
+          meta    : `${lineHeights.length} steps · --typography-lineHeight-*`,
+          children: primitiveTable({
+            caption: 'Line height scale',
+            tokens : lineHeights,
+            consumers,
+            leading: true
+          })
+        })}
+        ${refSection({
+          name    : 'A ratio is not a fixed leading',
+          meta    : '--typography-lineHeight-normal at three sizes',
+          children: html`
+            <div class="specimen">
+              <p class="docs-lede" style="margin-top: 0">
+                One unitless value produces different leading at every size, because each element
+                resolves it against its own font-size. That is the whole reason these tokens are
+                ratios and not lengths.
+              </p>
+              <div class="ratio-demo">
+                ${['--typography-fontSize-xs', '--typography-fontSize-base', '--typography-fontSize-2xl'].map(
+                  sizeToken => {
+                    const px = parseFloat(resolve(sizeToken)) * 16;
+                    const ratio = parseFloat(resolve('--typography-lineHeight-normal'));
+                    return html`
+                      <figure>
+                        <figcaption>
+                          ${sizeToken.replace('--typography-', '')} · ${px}px × ${ratio} =
+                          ${(px * ratio).toFixed(0)}px
+                        </figcaption>
+                        <p
+                          style="font-size: var(${sizeToken}); line-height: var(--typography-lineHeight-normal)"
+                        >
+                          The line box grows with the text, so the rhythm holds at any size.
+                        </p>
+                      </figure>
+                    `;
+                  }
+                )}
               </div>
             </div>
-          `)}
-        </div>
-      </div>
-    `
-      : ''}
-
-    <!-- Letter Spacing -->
-    ${args.showLetterSpacing
-      ? html`
-      <div class="section">
-        <h3 class="section-title">Letter Spacing</h3>
-        <div class="token-grid">
-          ${Object.entries(typographyTokens.letterSpacing).map(([name, spacing]) => html`
-            <div class="token-card">
-              <div class="token-header">
-                <span class="token-name">--letter-spacing-${name}</span>
-                <span class="token-value">${spacing}</span>
-              </div>
-              <div class="token-preview" style="letter-spacing: ${spacing};">
-                ${args.sampleText}
-              </div>
-              <div class="letter-spacing-visual">
-                ${'abcdef'.split('').map(letter => html`
-                  <div class="letter-box" style="margin-right: ${spacing};"></div>
-                `)}
-              </div>
+          `
+        })}
+
+        ${refSection({
+          name    : 'Rules',
+          children: html`
+            <div class="docs-note">
+              <ol class="rule-list">
+                <li>
+                  <b>Always unitless.</b> Never <code>px</code>, <code>rem</code> or
+                  <code>em</code>. A unitless value inherits as a number and each child
+                  recomputes it against its own font-size; a length inherits as a fixed line box,
+                  so nested text of a different size gets the wrong leading and stops growing when
+                  a reader raises their default font size.
+                </li>
+                <li>
+                  <b>Always from this scale.</b> Use
+                  <code>--typography-lineHeight-*</code>, or the composed style token for the role
+                  you are styling — <code>--typography-heading-h2-lineHeight</code>,
+                  <code>--typography-body-regular-lineHeight</code>. Do not invent a ratio.
+                </li>
+                <li>
+                  <b>Never a spacing or dimension token.</b>
+                  <code>line-height: var(--spacing-18)</code> is both an absolute value and a
+                  category error.
+                </li>
+                <li>
+                  <b>Anything that can wrap needs at least
+                  <code>tight</code></b> (${resolve('--typography-lineHeight-tight')}). A ratio at
+                  or below 1 makes the line box shorter than the text, which clips descenders and
+                  collides wrapped lines.
+                </li>
+                <li>
+                  <b>Tighter as text gets bigger.</b> Display and the two largest headings sit on
+                  <code>tight</code>, h3 and h4 on <code>130</code>, the smaller headings and most
+                  body copy on <code>140</code> and <code>145</code>, and running prose at 16px on
+                  <code>normal</code>. The ramp tightens as the size grows rather than holding one
+                  value per family. The composed tokens already encode this, which is the simplest
+                  reason to use them rather than picking a primitive by hand.
+                </li>
+                <li>
+                  <b>No fallback.</b> A fallback of the form
+                  <code>var(--typography-lineHeight-normal, 1.5)</code> restates the token's
+                  current value and silently lies the moment it changes.
+                </li>
+              </ol>
             </div>
-          `)}
-        </div>
-      </div>
-    `
-      : ''}
-  </div>
-`;
+          `
+        })}
 
-export const Typography = Template.bind({});
-Typography.args = {
-  sampleText       : 'The quick brown fox jumps over the lazy dog.',
-  showLineHeight   : true,
-  showLetterSpacing: false
-};
-Typography.parameters = {
-  docs: {
-    description: {
-      story: 'Complete typography token system showing font families, sizes, weights, line heights, and letter spacing with visual examples.'
-    }
-  }
+        ${refSection({
+          name    : 'Letter spacing',
+          meta    : `${tracking.length} steps · --typography-letterSpacing-*`,
+          children: primitiveTable({
+            caption: 'Letter spacing scale',
+            tokens : tracking,
+            consumers,
+            sample : token =>
+              `letter-spacing: var(${token}); font-size: var(--typography-fontSize-base)`
+          })
+        })}
+      `
+    })}
+  `;
 };
 
-export const TypographyScale = () => html`
-  <style>
-    .scale-container {
-      max-width: 800px;
-      margin: 0 auto;
-      padding: var(--space-xl);
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .scale-title {
-      font-family: var(--font-family-sans);
-      font-size: var(--font-size-2xl);
-      font-weight: var(--font-weight-bold);
-      margin: 0 0 var(--space-xl) 0;
-      color: #212529;
-      text-align: center;
-    }
-    
-    .scale-item {
-      display: flex;
-      align-items: center;
-      margin-bottom: var(--space-md);
-      padding: var(--space-sm);
-      border-radius: 6px;
-      background: #f8f9fa;
-      border-left: 4px solid #007bff;
-    }
-    
-    .scale-size {
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-sm);
-      color: #007bff;
-      font-weight: var(--font-weight-semibold);
-      min-width: 120px;
-      padding-right: var(--space-md);
-    }
-    
-    .scale-preview {
-      flex: 1;
-      font-family: var(--font-family-sans);
-      line-height: var(--line-height-normal);
-    }
-    
-    .scale-label {
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-xs);
-      color: #6c757d;
-      background: white;
-      padding: 2px 6px;
-      border-radius: 3px;
-      border: 1px solid #dee2e6;
-      margin-left: var(--space-sm);
-    }
-    
-    .heading-hierarchy {
-      margin-top: var(--space-2xl);
-      padding-top: var(--space-xl);
-      border-top: 2px solid #f0f0f0;
-    }
-    
-    .hierarchy-title {
-      font-family: var(--font-family-sans);
-      font-size: var(--font-size-xl);
-      font-weight: var(--font-weight-bold);
-      margin: 0 0 var(--space-lg) 0;
-      color: #212529;
-    }
-    
-    .heading-sample {
-      margin-bottom: var(--space-lg);
-      padding: var(--space-md);
-      background: white;
-      border-radius: 6px;
-      border: 1px solid #e9ecef;
-    }
-    
-    .heading-info {
-      display: flex;
-      align-items: center;
-      gap: var(--space-md);
-      margin-top: var(--space-sm);
-    }
-    
-    .heading-token {
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-xs);
-      color: #6c757d;
-    }
-  </style>
+/* ---------- composed styles ---------- */
 
-  <div class="scale-container">
-    <h2 class="scale-title">Typography Scale</h2>
-    
-    ${Object.entries(typographyTokens.sizes).map(([name, size]) => html`
-      <div class="scale-item">
-        <div class="scale-size">--font-size-${name}</div>
-        <div class="scale-preview" style="font-size: ${size};">
-          The quick brown fox jumps over the lazy dog.
-        </div>
-        <span class="scale-label">${size}</span>
-      </div>
-    `)}
-    
-    <div class="heading-hierarchy">
-      <h3 class="hierarchy-title">Heading Hierarchy</h3>
-      
-      <div class="heading-sample">
-        <h1 style="font-size: var(--font-size-4xl); font-weight: var(--font-weight-bold); margin: 0 0 var(--space-sm) 0;">
-          Heading 1 (h1)
-        </h1>
-        <div class="heading-info">
-          <span class="heading-token">--font-size-4xl</span>
-          <span class="heading-token">--font-weight-bold</span>
-          <span class="heading-token">--line-height-tight</span>
-        </div>
-      </div>
-      
-      <div class="heading-sample">
-        <h2 style="font-size: var(--font-size-3xl); font-weight: var(--font-weight-bold); margin: 0 0 var(--space-sm) 0;">
-          Heading 2 (h2)
-        </h2>
-        <div class="heading-info">
-          <span class="heading-token">--font-size-3xl</span>
-          <span class="heading-token">--font-weight-bold</span>
-          <span class="heading-token">--line-height-tight</span>
-        </div>
-      </div>
-      
-      <div class="heading-sample">
-        <h3 style="font-size: var(--font-size-2xl); font-weight: var(--font-weight-semibold); margin: 0 0 var(--space-sm) 0;">
-          Heading 3 (h3)
-        </h3>
-        <div class="heading-info">
-          <span class="heading-token">--font-size-2xl</span>
-          <span class="heading-token">--font-weight-semibold</span>
-          <span class="heading-token">--line-height-tight</span>
-        </div>
-      </div>
-      
-      <div class="heading-sample">
-        <h4 style="font-size: var(--font-size-xl); font-weight: var(--font-weight-semibold); margin: 0 0 var(--space-sm) 0;">
-          Heading 4 (h4)
-        </h4>
-        <div class="heading-info">
-          <span class="heading-token">--font-size-xl</span>
-          <span class="heading-token">--font-weight-semibold</span>
-          <span class="heading-token">--line-height-normal</span>
-        </div>
-      </div>
-      
-      <div class="heading-sample">
-        <h5 style="font-size: var(--font-size-lg); font-weight: var(--font-weight-medium); margin: 0 0 var(--space-sm) 0;">
-          Heading 5 (h5)
-        </h5>
-        <div class="heading-info">
-          <span class="heading-token">--font-size-lg</span>
-          <span class="heading-token">--font-weight-medium</span>
-          <span class="heading-token">--line-height-normal</span>
-        </div>
-      </div>
-      
-      <div class="heading-sample">
-        <h6 style="font-size: var(--font-size-md); font-weight: var(--font-weight-medium); margin: 0 0 var(--space-sm) 0;">
-          Heading 6 (h6)
-        </h6>
-        <div class="heading-info">
-          <span class="heading-token">--font-size-md</span>
-          <span class="heading-token">--font-weight-medium</span>
-          <span class="heading-token">--line-height-normal</span>
-        </div>
-      </div>
-    </div>
-  </div>
-`;
-TypographyScale.storyName = 'Typography Scale';
-TypographyScale.parameters = {
-  docs: {
-    description: {
-      story: 'Complete typography scale showing all font sizes with visual hierarchy and proper heading structure examples.'
-    }
+const PROPERTIES = [
+  ['fontFamily', 'font-family'],
+  ['fontSize', 'font-size'],
+  ['fontWeight', 'font-weight'],
+  ['lineHeight', 'line-height'],
+  ['letterSpacing', 'letter-spacing']
+];
+
+const SAMPLE = 'Security that keeps up with you';
+
+/**
+ * Finds every composed style — any --typography-<group>-<variant>-fontSize —
+ * and groups them, so a style added to the tokens appears here automatically.
+ */
+function discoverComposedStyles(cssText) {
+  const groups = new Map();
+  const pattern = /--typography-([a-z]+)-([a-z0-9-]+?)-fontSize\s*:/g;
+  for (const [, group, variant] of cssText.matchAll(pattern)) {
+    if (!groups.has(group)) groups.set(group, new Set());
+    groups.get(group).add(variant);
+  }
+  return [...groups].map(([group, variants]) => ({ group, variants: [...variants] }));
+}
+
+function styleFor(group, variant) {
+  const declarations = [];
+  const used = [];
+  for (const [suffix, property] of PROPERTIES) {
+    const token = `--typography-${group}-${variant}-${suffix}`;
+    if (!resolve(token)) continue;
+    declarations.push(`${property}: var(${token})`);
+    // a full fallback stack is too long for the meta line; the stack itself is
+    // documented on the Fonts page
+    const raw = resolve(token);
+    const value = property === 'font-family' ? raw.split(',')[0].replace(/['"]/g, '').trim() : raw;
+    used.push({ token, property, value });
   }
+  return { css: declarations.join('; '), used };
+}
+
+export const Typography = () => {
+  const cssText = readAllCssText();
+  const groups = discoverComposedStyles(cssText);
+
+  return html`
+    ${typeStyles}
+    ${docsPage({
+      title: 'Typography',
+      lede : html`The composed type styles components actually use. Each specimen is rendered by
+        applying that style's own tokens, so what you see is what the token produces — nothing is
+        hardcoded.`,
+      note: html`Every style is discovered from the loaded CSS by looking for a
+        <code>-fontSize</code> token, so adding a style to
+        <code>src/tokens/tokens.css</code> makes it appear here without touching this page.`,
+      children: groups.map(({ group, variants }) =>
+        refSection({
+          name    : group,
+          meta    : `${variants.length} styles · --typography-${group}-*`,
+          children: html`
+            <div class="specimen">
+              ${variants.map(variant => {
+                const { css, used } = styleFor(group, variant);
+                if (!used.length) return html``;
+                return html`
+                  <div class="specimen-row">
+                    <div class="specimen-meta">
+                      <span class="name">${group}-${variant}</span>
+                      ${used.map(
+                        ({ property, value }) => html`<span>${property}: ${value}</span>`
+                      )}
+                    </div>
+                    <p class="specimen-text" style=${css}>${SAMPLE}</p>
+                  </div>
+                `;
+              })}
+            </div>
+          `
+        })
+      )
+    })}
+  `;
 };
 
-export const TypographyCombinations = () => html`
-  <style>
-    .combinations-container {
-      max-width: 800px;
-      margin: 0 auto;
-      padding: var(--space-xl);
-      background: white;
-      border-radius: 8px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
-    }
-    
-    .combinations-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(350px, 1fr));
-      gap: var(--space-lg);
-    }
-    
-    .combination-card {
-      padding: var(--space-lg);
-      border-radius: 8px;
-      border: 1px solid #e9ecef;
-      background: #f8f9fa;
-    }
-    
-    .combination-title {
-      font-family: var(--font-family-sans);
-      font-size: var(--font-size-lg);
-      font-weight: var(--font-weight-semibold);
-      margin: 0 0 var(--space-md) 0;
-      color: #212529;
-    }
-    
-    .combination-preview {
-      font-family: inherit;
-      font-size: inherit;
-      font-weight: inherit;
-      line-height: inherit;
-      letter-spacing: inherit;
-      margin: var(--space-md) 0;
-      padding: var(--space-md);
-      background: white;
-      border-radius: 6px;
-      border: 1px solid #dee2e6;
-    }
-    
-    .combination-tokens {
-      display: flex;
-      flex-wrap: wrap;
-      gap: var(--space-xs);
-      margin-top: var(--space-sm);
-    }
-    
-    .token-tag {
-      font-family: var(--font-family-mono);
-      font-size: var(--font-size-xs);
-      color: #6c757d;
-      background: white;
-      padding: 2px 6px;
-      border-radius: 3px;
-      border: 1px solid #dee2e6;
+export const TypographyCombinations = () => {
+  const pairings = [
+    {
+      name  : 'Page header',
+      layers: [
+        ['display', 'md', 'Complete digital security'],
+        ['body', 'lead', 'One plan for every device you own, with privacy and identity cover built in.']
+      ]
+    },
+    {
+      name  : 'Section',
+      layers: [
+        ['heading', 'h2', 'Why it matters'],
+        ['body', 'regular', 'Threats move faster than annual reviews. Protection has to keep pace, quietly, without asking you to manage it.']
+      ]
+    },
+    {
+      name  : 'Card',
+      layers: [
+        ['heading', 'h5', 'Password Manager'],
+        ['body', 'small', 'Generate, store and autofill strong credentials across your devices.'],
+        ['caption', 'default', 'Included in every plan']
+      ]
+    },
+    {
+      name  : 'Form field',
+      layers: [
+        ['label', 'default', 'Email address'],
+        ['caption', 'small', 'We only use this for your licence key.']
+      ]
     }
-  </style>
+  ];
 
-  <div class="combinations-container">
-    <h2 style="font-family: var(--font-family-sans); font-size: var(--font-size-2xl); font-weight: var(--font-weight-bold); margin: 0 0 var(--space-xl) 0; text-align: center;">
-      Common Typography Combinations
-    </h2>
-    
-    <div class="combinations-grid">
-      <!-- Body Text -->
-      <div class="combination-card">
-        <h3 class="combination-title">Body Text</h3>
-        <div class="combination-preview" style="
-          font-family: var(--font-family-sans);
-          font-size: var(--font-size-md);
-          font-weight: var(--font-weight-regular);
-          line-height: var(--line-height-normal);
-          letter-spacing: var(--letter-spacing-normal);
-        ">
-          The quick brown fox jumps over the lazy dog. This is standard body text used for paragraphs and general content.
-        </div>
-        <div class="combination-tokens">
-          <span class="token-tag">--font-family-sans</span>
-          <span class="token-tag">--font-size-md</span>
-          <span class="token-tag">--font-weight-regular</span>
-          <span class="token-tag">--line-height-normal</span>
-        </div>
-      </div>
-      
-      <!-- Heading -->
-      <div class="combination-card">
-        <h3 class="combination-title">Page Heading</h3>
-        <div class="combination-preview" style="
-          font-family: var(--font-family-sans);
-          font-size: var(--font-size-3xl);
-          font-weight: var(--font-weight-bold);
-          line-height: var(--line-height-tight);
-          letter-spacing: var(--letter-spacing-tight);
-        ">
-          Main Page Title
-        </div>
-        <div class="combination-tokens">
-          <span class="token-tag">--font-family-sans</span>
-          <span class="token-tag">--font-size-3xl</span>
-          <span class="token-tag">--font-weight-bold</span>
-          <span class="token-tag">--line-height-tight</span>
-        </div>
-      </div>
-      
-      <!-- Code Block -->
-      <div class="combination-card">
-        <h3 class="combination-title">Code Snippet</h3>
-        <div class="combination-preview" style="
-          font-family: var(--font-family-mono);
-          font-size: var(--font-size-sm);
-          font-weight: var(--font-weight-regular);
-          line-height: var(--line-height-normal);
-          letter-spacing: var(--letter-spacing-normal);
-          background: #1a1a1a;
-          color: #f8f8f2;
-        ">
-          const greeting = "Hello, World!";<br>
-          console.log(greeting);
-        </div>
-        <div class="combination-tokens">
-          <span class="token-tag">--font-family-mono</span>
-          <span class="token-tag">--font-size-sm</span>
-          <span class="token-tag">--font-weight-regular</span>
-        </div>
-      </div>
-      
-      <!-- Label -->
-      <div class="combination-card">
-        <h3 class="combination-title">Form Label</h3>
-        <div class="combination-preview" style="
-          font-family: var(--font-family-sans);
-          font-size: var(--font-size-sm);
-          font-weight: var(--font-weight-semibold);
-          line-height: var(--line-height-tight);
-          letter-spacing: var(--letter-spacing-wide);
-          text-transform: uppercase;
-        ">
-          Email Address
-        </div>
-        <div class="combination-tokens">
-          <span class="token-tag">--font-family-sans</span>
-          <span class="token-tag">--font-size-sm</span>
-          <span class="token-tag">--font-weight-semibold</span>
-          <span class="token-tag">--letter-spacing-wide</span>
-        </div>
-      </div>
-      
-      <!-- Quote -->
-      <div class="combination-card">
-        <h3 class="combination-title">Block Quote</h3>
-        <div class="combination-preview" style="
-          font-family: var(--font-family-sans);
-          font-size: var(--font-size-lg);
-          font-weight: var(--font-weight-light);
-          line-height: var(--line-height-relaxed);
-          letter-spacing: var(--letter-spacing-normal);
-          font-style: italic;
-          border-left: 4px solid #007bff;
-          padding-left: var(--space-md);
-        ">
-          The only way to do great work is to love what you do.
-        </div>
-        <div class="combination-tokens">
-          <span class="token-tag">--font-family-sans</span>
-          <span class="token-tag">--font-size-lg</span>
-          <span class="token-tag">--font-weight-light</span>
-          <span class="token-tag">--line-height-relaxed</span>
-        </div>
-      </div>
-      
-      <!-- Button Text -->
-      <div class="combination-card">
-        <h3 class="combination-title">Button Text</h3>
-        <div class="combination-preview" style="
-          font-family: var(--font-family-sans);
-          font-size: var(--font-size-md);
-          font-weight: var(--font-weight-semibold);
-          line-height: var(--line-height-tight);
-          letter-spacing: var(--letter-spacing-wide);
-          text-align: center;
-          background: #007bff;
-          color: white;
-          padding: var(--space-sm) var(--space-lg);
-          border-radius: 4px;
-        ">
-          Submit Form
-        </div>
-        <div class="combination-tokens">
-          <span class="token-tag">--font-family-sans</span>
-          <span class="token-tag">--font-size-md</span>
-          <span class="token-tag">--font-weight-semibold</span>
-          <span class="token-tag">--letter-spacing-wide</span>
-        </div>
-      </div>
-    </div>
-  </div>
-`;
-TypographyCombinations.storyName = 'Common Combinations';
-TypographyCombinations.parameters = {
-  docs: {
-    description: {
-      story: 'Practical typography combinations for common UI elements like headings, body text, code blocks, labels, quotes, and buttons.'
-    }
-  }
-};
+  return html`
+    ${typeStyles}
+    ${docsPage({
+      title   : 'Type pairings',
+      lede    : 'Composed styles combined the way pages actually use them, so the relative scale and weight can be judged in context rather than one specimen at a time.',
+      children: pairings.map(({ name, layers }) =>
+        refSection({
+          name,
+          children: html`
+            <div class="specimen">
+              ${layers.map(([group, variant, text]) => {
+                const { css, used } = styleFor(group, variant);
+                if (!used.length) return html``;
+                return html`
+                  <p
+                    class="specimen-text"
+                    style="${css}; margin-bottom: var(--spacing-8)"
+                    title="--typography-${group}-${variant}-*"
+                  >
+                    ${text}
+                  </p>
+                `;
+              })}
+            </div>
+          `
+        })
+      )
+    })}
+  `;
+};