@repobit/dex-system-design 0.21.2 → 0.22.1

package/src/tokens/typography.stories.js

@@ -2,68 +2,1010 @@ import { html } from 'lit';
 
 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)',
+    '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)',
+    '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: {
-    regular: 'var(--font-weight-regular, 400)',
-    semibold: 'var(--font-weight-semibold, 600)',
-    bold: 'var(--font-weight-bold, 700)',
+    '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)'
+  }
 };
 
-export const Typography = () => html`
+const Template = (args) => html`
   <style>
-    h3 {
+    .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);
+    }
+    
+    .section {
+      margin-bottom: var(--space-2xl);
+      padding-bottom: var(--space-lg);
+      border-bottom: 2px solid #f0f0f0;
+    }
+    
+    .section-title {
       font-family: var(--font-family-sans);
-      font-weight: 600;
-      font-size: var(--heading-medium);
-      margin-bottom: 16px;
-      text-transform: capitalize;
+      font-size: var(--font-size-xl);
+      font-weight: var(--font-weight-bold);
+      margin: 0 0 var(--space-lg) 0;
+      color: #212529;
+      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);
     }
-    .typo-family-sample {
-      margin-bottom: 12px;
-      font-size: 1rem;
+    
+    .token-card {
+      padding: var(--space-md);
+      background: #f8f9fa;
+      border-radius: 6px;
+      border: 1px solid #e9ecef;
+      transition: all 0.2s ease;
     }
-    .typo-size-sample {
-      margin-bottom: 8px;
+    
+    .token-card:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+      border-color: #007bff;
     }
-    .typo-weight-sample {
-      margin-bottom: 8px;
+    
+    .token-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin-bottom: var(--space-sm);
+    }
+    
+    .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;
+    }
+    
+    .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;
+    }
+    
+    .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;
+      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;
+    }
+    
+    .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;
+    }
+    
+    .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;
+    }
+    
+    .letter-box {
+      width: 12px;
+      height: 20px;
+      background: #007bff;
+      border-radius: 2px;
+      opacity: 0.7;
+    }
+    
+    .info-panel {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+      padding: var(--space-lg);
+      border-radius: 8px;
+      margin-bottom: var(--space-xl);
+    }
+    
+    .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;
+    }
+    
+    .info-text {
+      font-family: var(--font-family-sans);
+      font-size: var(--font-size-sm);
+      opacity: 0.9;
+      margin: 0;
     }
   </style>
 
-  <section>
-    <h3>Font Families</h3>
-    ${Object.entries(typographyTokens.families).map(([name, family]) => html`
-      <div class="typo-family-sample" style="font-family: ${family}">
-        This text uses <strong>${name}</strong> font family.
+  <div class="typography-container">
+    <div class="info-panel">
+      <h3 class="info-title">Typography System</h3>
+      <p class="info-text">${args.sampleText}</p>
+    </div>
+
+    <!-- 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>
+            </div>
+            <div class="token-preview" style="font-family: ${family};">
+              ${args.sampleText}
+            </div>
+          </div>
+        `)}
       </div>
-    `)}
+    </div>
 
-    <h3>Font Sizes</h3>
-    ${Object.entries(typographyTokens.sizes).map(([sizeName, sizeValue]) => html`
-      <div class="typo-size-sample" style="font-size: ${sizeValue}">
-        Font size <strong>${sizeName}</strong> (${sizeValue})
+    <!-- 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>
+            </div>
+            <div class="token-preview" style="font-size: ${size};">
+              ${args.sampleText}
+            </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>
+            </div>
+            <div class="token-preview" style="font-weight: ${weight};">
+              ${args.sampleText}
+            </div>
+          </div>
+        `)}
+      </div>
+    </div>
+
+    <!-- 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>
+              </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>
+            </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.'
+    }
+  }
+};
+
+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>
 
-    <h3>Font Weights</h3>
-    ${Object.entries(typographyTokens.weights).map(([weightName, weightValue]) => html`
-      <div class="typo-weight-sample" style="font-weight: ${weightValue}">
-        Font weight <strong>${weightName}</strong> (${weightValue})
+  <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>
     `)}
-  </section>
+    
+    <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.'
+    }
+  }
+};
+
+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;
+    }
+  </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.'
+    }
+  }
+};