@repobit/dex-system-design 0.21.2 → 0.22.0

package/src/tokens/spacing.stories.js

@@ -2,55 +2,722 @@ import { html } from 'lit';
 
 export default {
   title: 'Design Tokens/Spacing',
+  tags : ['autodocs'],
+
   args: {
     spaceNone: 'var(--space-none, 0)',
-    space4xs: 'var(--space-4xs, 0.125rem)',
-    space3xs: 'var(--space-3xs, 0.25rem)',
-    space2xs: 'var(--space-2xs, 0.5rem)',
-    spaceXs: 'var(--space-xs, 0.75rem)',
-    spaceSm: 'var(--space-sm, 1rem)',
-    spaceMd: 'var(--space-md, 1.5rem)',
-    spaceLg: 'var(--space-lg, 2rem)',
-    spaceXl: 'var(--space-xl, 2.5rem)',
-    space2xl: 'var(--space-2xl, 3rem)',
-    space3xl: 'var(--space-3xl, 4rem)',
-    space4xl: 'var(--space-4xl, 6rem)',
-    space5xl: 'var(--space-5xl, 8rem)',
+    space4xs : 'var(--space-4xs, 0.125rem)',
+    space3xs : 'var(--space-3xs, 0.25rem)',
+    space2xs : 'var(--space-2xs, 0.5rem)',
+    spaceXs  : 'var(--space-xs, 0.75rem)',
+    spaceSm  : 'var(--space-sm, 1rem)',
+    spaceMd  : 'var(--space-md, 1.5rem)',
+    spaceLg  : 'var(--space-lg, 2rem)',
+    spaceXl  : 'var(--space-xl, 2.5rem)',
+    space2xl : 'var(--space-2xl, 3rem)',
+    space3xl : 'var(--space-3xl, 4rem)',
+    space4xl : 'var(--space-4xl, 6rem)',
+    space5xl : 'var(--space-5xl, 8rem)'
   },
+
   argTypes: {
-    spaceNone: { control: 'text', name: '--space-none' },
-    space4xs: { control: 'text', name: '--space-4xs' },
-    space3xs: { control: 'text', name: '--space-3xs' },
-    space2xs: { control: 'text', name: '--space-2xs' },
-    spaceXs: { control: 'text', name: '--space-xs' },
-    spaceSm: { control: 'text', name: '--space-sm' },
-    spaceMd: { control: 'text', name: '--space-md' },
-    spaceLg: { control: 'text', name: '--space-lg' },
-    spaceXl: { control: 'text', name: '--space-xl' },
-    space2xl: { control: 'text', name: '--space-2xl' },
-    space3xl: { control: 'text', name: '--space-3xl' },
-    space4xl: { control: 'text', name: '--space-4xl' },
-    space5xl: { control: 'text', name: '--space-5xl' },
+    spaceNone: {
+      control    : 'text',
+      name       : '--space-none',
+      description: 'No spacing (0)',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '0' }
+      }
+    },
+    space4xs: {
+      control    : 'text',
+      name       : '--space-4xs',
+      description: 'Extra extra extra small spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '0.125rem (2px)' }
+      }
+    },
+    space3xs: {
+      control    : 'text',
+      name       : '--space-3xs',
+      description: 'Extra extra small spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '0.25rem (4px)' }
+      }
+    },
+    space2xs: {
+      control    : 'text',
+      name       : '--space-2xs',
+      description: 'Extra small spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '0.5rem (8px)' }
+      }
+    },
+    spaceXs: {
+      control    : 'text',
+      name       : '--space-xs',
+      description: 'Extra small spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '0.75rem (12px)' }
+      }
+    },
+    spaceSm: {
+      control    : 'text',
+      name       : '--space-sm',
+      description: 'Small spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '1rem (16px)' }
+      }
+    },
+    spaceMd: {
+      control    : 'text',
+      name       : '--space-md',
+      description: 'Medium spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '1.5rem (24px)' }
+      }
+    },
+    spaceLg: {
+      control    : 'text',
+      name       : '--space-lg',
+      description: 'Large spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '2rem (32px)' }
+      }
+    },
+    spaceXl: {
+      control    : 'text',
+      name       : '--space-xl',
+      description: 'Extra large spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '2.5rem (40px)' }
+      }
+    },
+    space2xl: {
+      control    : 'text',
+      name       : '--space-2xl',
+      description: 'Extra extra large spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '3rem (48px)' }
+      }
+    },
+    space3xl: {
+      control    : 'text',
+      name       : '--space-3xl',
+      description: 'Extra extra extra large spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '4rem (64px)' }
+      }
+    },
+    space4xl: {
+      control    : 'text',
+      name       : '--space-4xl',
+      description: 'Huge spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '6rem (96px)' }
+      }
+    },
+    space5xl: {
+      control    : 'text',
+      name       : '--space-5xl',
+      description: 'Extra huge spacing',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '8rem (128px)' }
+      }
+    }
   },
+
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# Spacing Design Tokens
+
+Consistent spacing system using CSS custom properties for margin, padding, and gaps.
+
+## Overview
+
+The spacing system provides a consistent scale of spacing values based on rem units. Using CSS custom properties ensures consistency across the entire application and makes responsive design easier.
+
+## Spacing Scale
+
+The system follows a t-shirt size naming convention (xs, sm, md, lg, xl) with additional granularity for smaller increments.
+
+## Usage
+
+### Direct CSS Custom Properties
+\`\`\`css
+/* Using spacing tokens */
+.element {
+  margin: var(--space-md);
+  padding: var(--space-sm) var(--space-lg);
+  gap: var(--space-xs);
+}
+
+/* Multiple values */
+.container {
+  padding: var(--space-sm) var(--space-md) var(--space-lg) var(--space-xl);
+}
+
+/* Specific properties */
+.card {
+  margin-top: var(--space-2xl);
+  margin-bottom: var(--space-lg);
+}
+\`\`\`
+
+### In Component Properties
+\`\`\`html
+<style>
+  .custom-component {
+    --component-padding: var(--space-md);
+    --component-gap: var(--space-sm);
+  }
+</style>
+\`\`\`
+
+## Spacing Tokens Reference
+
+| Token | Value (rem) | Value (px) | Use Case |
+|-------|-------------|------------|----------|
+| \`--space-none\` | 0 | 0px | No spacing, reset margins/padding |
+| \`--space-4xs\` | 0.125rem | 2px | Minimal spacing, tight layouts |
+| \`--space-3xs\` | 0.25rem | 4px | Small spacing, icon padding |
+| \`--space-2xs\` | 0.5rem | 8px | Compact spacing, dense UI |
+| \`--space-xs\` | 0.75rem | 12px | Standard small spacing |
+| \`--space-sm\` | 1rem | 16px | Small spacing, component padding |
+| \`--space-md\` | 1.5rem | 24px | Medium spacing, default gap |
+| \`--space-lg\` | 2rem | 32px | Large spacing, section margins |
+| \`--space-xl\` | 2.5rem | 40px | Extra large spacing |
+| \`--space-2xl\` | 3rem | 48px | Page section spacing |
+| \`--space-3xl\` | 4rem | 64px | Large section spacing |
+| \`--space-4xl\` | 6rem | 96px | Hero section spacing |
+| \`--space-5xl\` | 8rem | 128px | Maximum spacing, full page |
+
+## Base Unit
+
+The system uses **rem** units based on the root font size (typically 16px). This ensures:
+
+1. **Accessibility**: Respects user's browser font size settings
+2. **Consistency**: Maintains proportional relationships
+3. **Responsive**: Scales appropriately across breakpoints
+
+## Best Practices
+
+### 1. Use Tokens Consistently
+\`\`\`css
+/* Good ✅ */
+margin: var(--space-md);
+padding: var(--space-sm);
+
+/* Bad ❌ */
+margin: 16px;
+padding: 1rem;
+\`\`\`
+
+### 2. Combine Tokens for Complex Spacing
+\`\`\`css
+/* Multi-direction spacing */
+.element {
+  margin: var(--space-sm) var(--space-md);
+  padding: var(--space-xs) var(--space-lg);
+}
+
+/* Stacking with gap */
+.grid {
+  display: grid;
+  gap: var(--space-md);
+}
+\`\`\`
+
+### 3. Responsive Spacing
+\`\`\`css
+.container {
+  padding: var(--space-sm);
+  
+  @media (min-width: 768px) {
+    padding: var(--space-md);
+  }
+  
+  @media (min-width: 1024px) {
+    padding: var(--space-lg);
+  }
+}
+\`\`\`
+
+### 4. Semantic Spacing
+\`\`\`css
+:root {
+  /* Define semantic spacing for components */
+  --button-padding: var(--space-xs) var(--space-sm);
+  --card-padding: var(--space-md);
+  --section-margin: var(--space-xl);
+  --form-gap: var(--space-sm);
+}
+\`\`\`
+
+## Examples
+
+### Button Spacing
+\`\`\`css
+.button {
+  padding: var(--space-xs) var(--space-sm);
+  margin-right: var(--space-xs);
+}
+\`\`\`
+
+### Card Layout
+\`\`\`css
+.card {
+  padding: var(--space-md);
+  margin-bottom: var(--space-lg);
+}
+
+.card-content {
+  margin-top: var(--space-sm);
+}
+\`\`\`
+
+### Grid System
+\`\`\`css
+.grid-container {
+  display: grid;
+  gap: var(--space-md);
+  padding: var(--space-lg);
+}
+
+.grid-item {
+  margin-bottom: var(--space-sm);
+}
+\`\`\`
+
+### Form Layout
+\`\`\`css
+.form-group {
+  margin-bottom: var(--space-md);
+}
+
+.form-label {
+  margin-bottom: var(--space-xs);
+}
+
+.form-input {
+  padding: var(--space-xs) var(--space-sm);
+}
+\`\`\`
+
+## Browser Support
+
+CSS Custom Properties are supported in:
+- Chrome 49+
+- Firefox 31+
+- Safari 9.1+
+- Edge 16+
+
+For older browsers, provide fallbacks:
+\`\`\`css
+.element {
+  margin: 1rem; /* Fallback */
+  margin: var(--space-sm);
+}
+\`\`\`
+
+## Testing Visual Balance
+
+Use the visualizer in this story to ensure spacing creates proper visual hierarchy and breathing room between elements. Each token is demonstrated with its actual spacing applied as padding.
+        `
+      }
+    }
+  }
 };
 
 export const AllSpacings = (args) => html`
   <style>
+    :root {
+      --color-neutral-100: #f8f9fa;
+      --color-neutral-200: #e9ecef;
+      --color-neutral-300: #dee2e6;
+      --color-primary: #007bff;
+    }
+    
+    .spacing-container {
+      max-width: 800px;
+      margin: 0 auto;
+      padding: var(--space-lg);
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    
+    .spacing-header {
+      margin-bottom: var(--space-xl);
+      padding-bottom: var(--space-sm);
+      border-bottom: 2px solid var(--color-neutral-300);
+    }
+    
+    .spacing-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 1.5rem;
+      font-weight: 600;
+      color: #212529;
+      margin: 0 0 var(--space-xs) 0;
+    }
+    
+    .spacing-subtitle {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 0.9rem;
+      color: #6c757d;
+      margin: 0;
+    }
+    
     .spacing-box {
-      background-color: var(--color-neutral-200, #eee);
-      margin-bottom: 16px;
+      background-color: var(--color-neutral-200);
+      margin-bottom: var(--space-md);
+      border-radius: 4px;
+      border: 1px dashed var(--color-neutral-300);
+      transition: all 0.2s ease;
+      position: relative;
+      overflow: hidden;
+    }
+    
+    .spacing-box:hover {
+      background-color: var(--color-neutral-300);
+      transform: translateY(-2px);
+      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+    }
+    
+    .spacing-content {
+      font-family: var(--font-family-mono, monospace);
+      font-size: 0.9rem;
+      color: #495057;
+      line-height: 1.4;
+    }
+    
+    .spacing-token {
+      font-weight: 600;
+      color: var(--color-primary);
+      display: inline-block;
+      background: white;
+      padding: 2px 6px;
+      border-radius: 3px;
+      border: 1px solid var(--color-neutral-300);
+      margin-right: var(--space-xs);
+    }
+    
+    .spacing-value {
+      color: #6c757d;
+    }
+    
+    .spacing-visual {
+      position: absolute;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      width: 60px;
+      background: repeating-linear-gradient(
+        45deg,
+        var(--color-neutral-300),
+        var(--color-neutral-300) 1px,
+        transparent 1px,
+        transparent 8px
+      );
+      opacity: 0.3;
+    }
+    
+    .legend {
+      display: flex;
+      align-items: center;
+      gap: var(--space-sm);
+      margin-top: var(--space-2xl);
+      padding: var(--space-md);
+      background: var(--color-neutral-100);
+      border-radius: 4px;
+      border-left: 4px solid var(--color-primary);
+    }
+    
+    .legend-item {
+      display: flex;
+      align-items: center;
+      gap: var(--space-xs);
+    }
+    
+    .legend-color {
+      width: 12px;
+      height: 12px;
+      border-radius: 2px;
+    }
+    
+    .legend-text {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 0.85rem;
+      color: #495057;
+    }
+    
+    .usage-example {
+      margin-top: var(--space-xl);
+      padding: var(--space-md);
+      background: var(--color-neutral-100);
       border-radius: 4px;
+    }
+    
+    .usage-title {
       font-family: var(--font-family-sans, sans-serif);
       font-weight: 600;
-      border: 1px dashed #ccc;
+      color: #212529;
+      margin: 0 0 var(--space-sm) 0;
+    }
+    
+    .code-block {
+      background: #1a1a1a;
+      color: #f8f8f2;
+      padding: var(--space-md);
+      border-radius: 4px;
+      font-family: var(--font-family-mono, monospace);
+      font-size: 0.85rem;
+      line-height: 1.5;
+      overflow-x: auto;
     }
+    
+    .code-comment { color: #6272a4; }
+    .code-property { color: #50fa7b; }
+    .code-value { color: #f1fa8c; }
+    .code-punctuation { color: #f8f8f2; }
   </style>
 
-  <section>
-    ${Object.entries(args).map(([key, value]) => html`
-      <div class="spacing-box" style="padding: ${value}">
-        Token <strong>${key.replace('space', '--space-').toLowerCase()}</strong>: ${value}
+  <div class="spacing-container">
+    <div class="spacing-header">
+      <h1 class="spacing-title">Spacing Tokens</h1>
+      <p class="spacing-subtitle">Visual reference for all spacing design tokens</p>
+    </div>
+
+    <section>
+      ${Object.entries(args).map(([key, value]) => html`
+        <div class="spacing-box" style="padding: ${value}">
+          <div class="spacing-visual"></div>
+          <div class="spacing-content">
+            <span class="spacing-token">${key.replace('space', '--space-').toLowerCase()}</span>
+            <span class="spacing-value">${value}</span>
+          </div>
+        </div>
+      `)}
+    </section>
+
+    <div class="legend">
+      <div class="legend-item">
+        <div class="legend-color" style="background: var(--color-neutral-200);"></div>
+        <span class="legend-text">Box background shows applied padding</span>
+      </div>
+      <div class="legend-item">
+        <div class="legend-color" style="background: repeating-linear-gradient(45deg, #dee2e6, #dee2e6 1px, transparent 1px, transparent 8px);"></div>
+        <span class="legend-text">Diagonal pattern indicates spacing area</span>
+      </div>
+    </div>
+
+    <div class="usage-example">
+      <h3 class="usage-title">Usage Example</h3>
+      <div class="code-block">
+        <span class="code-comment">/* Using spacing tokens in CSS */</span><br>
+        <span class="code-property">.card</span> {<br>
+        &nbsp;&nbsp;<span class="code-property">padding</span>: <span class="code-value">var(--space-md)</span><span class="code-punctuation">;</span><br>
+        &nbsp;&nbsp;<span class="code-property">margin-bottom</span>: <span class="code-value">var(--space-lg)</span><span class="code-punctuation">;</span><br>
+        }<br><br>
+        <span class="code-comment">/* Responsive spacing */</span><br>
+        <span class="code-property">.container</span> {<br>
+        &nbsp;&nbsp;<span class="code-property">padding</span>: <span class="code-value">var(--space-sm)</span><span class="code-punctuation">;</span><br>
+        }<br>
+        <span class="code-property">@media</span> (<span class="code-property">min-width</span>: <span class="code-value">768px</span>) {<br>
+        &nbsp;&nbsp;<span class="code-property">.container</span> {<br>
+        &nbsp;&nbsp;&nbsp;&nbsp;<span class="code-property">padding</span>: <span class="code-value">var(--space-lg)</span><span class="code-punctuation">;</span><br>
+        &nbsp;&nbsp;}<br>
+        }
       </div>
-    `)}
-  </section>
+    </div>
+  </div>
 `;
+
+export const SpacingExamples = () => html`
+  <style>
+    .examples-container {
+      max-width: 800px;
+      margin: 0 auto;
+      padding: var(--space-lg);
+    }
+    
+    .example-section {
+      margin-bottom: var(--space-xl);
+      padding: var(--space-lg);
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    
+    .example-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 1.25rem;
+      font-weight: 600;
+      color: #212529;
+      margin: 0 0 var(--space-md) 0;
+    }
+    
+    .button-group {
+      display: flex;
+      gap: var(--space-sm);
+      flex-wrap: wrap;
+      margin-bottom: var(--space-md);
+    }
+    
+    .button {
+      padding: var(--space-xs) var(--space-sm);
+      background: #007bff;
+      color: white;
+      border: none;
+      border-radius: 4px;
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 0.9rem;
+      cursor: pointer;
+      transition: background 0.2s;
+    }
+    
+    .button:hover {
+      background: #0056b3;
+    }
+    
+    .card-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+      gap: var(--space-md);
+    }
+    
+    .card {
+      padding: var(--space-md);
+      background: var(--color-neutral-100, #f8f9fa);
+      border-radius: 6px;
+      border: 1px solid var(--color-neutral-300, #dee2e6);
+    }
+    
+    .card-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      margin: 0 0 var(--space-xs) 0;
+      color: #212529;
+    }
+    
+    .card-content {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 0.9rem;
+      color: #6c757d;
+      margin: 0;
+    }
+    
+    .form-group {
+      margin-bottom: var(--space-md);
+    }
+    
+    .form-label {
+      display: block;
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      margin-bottom: var(--space-xs);
+      color: #495057;
+    }
+    
+    .form-input {
+      width: 100%;
+      padding: var(--space-xs) var(--space-sm);
+      border: 1px solid var(--color-neutral-300, #dee2e6);
+      border-radius: 4px;
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 0.9rem;
+    }
+    
+    .spacing-visual {
+      display: flex;
+      align-items: center;
+      gap: var(--space-md);
+      padding: var(--space-lg);
+      background: linear-gradient(45deg, #f8f9fa, #e9ecef);
+      border-radius: 6px;
+    }
+    
+    .spacing-dot {
+      width: var(--space-sm);
+      height: var(--space-sm);
+      background: #007bff;
+      border-radius: 50%;
+    }
+    
+    .spacing-label {
+      font-family: var(--font-family-mono, monospace);
+      font-size: 0.85rem;
+      color: #495057;
+      background: white;
+      padding: 2px 6px;
+      border-radius: 3px;
+      border: 1px solid #dee2e6;
+    }
+  </style>
+
+  <div class="examples-container">
+    <div class="example-section">
+      <h3 class="example-title">Button Spacing</h3>
+      <div class="button-group">
+        <button class="button" style="padding: var(--space-xs) var(--space-sm);">Small Button</button>
+        <button class="button" style="padding: var(--space-sm) var(--space-md);">Medium Button</button>
+        <button class="button" style="padding: var(--space-md) var(--space-lg);">Large Button</button>
+      </div>
+      <p style="font-family: var(--font-family-sans, sans-serif); color: #6c757d; font-size: 0.9rem;">
+        Buttons use consistent padding tokens: --space-xs/--space-sm, --space-sm/--space-md, --space-md/--space-lg
+      </p>
+    </div>
+
+    <div class="example-section">
+      <h3 class="example-title">Card Grid</h3>
+      <div class="card-grid">
+        ${[1, 2, 3].map(i => html`
+          <div class="card">
+            <h4 class="card-title">Card ${i}</h4>
+            <p class="card-content">This card uses --space-md for padding and the grid uses --space-md for gaps.</p>
+          </div>
+        `)}
+      </div>
+    </div>
+
+    <div class="example-section">
+      <h3 class="example-title">Form Layout</h3>
+      <div class="form-group">
+        <label class="form-label">Email Address</label>
+        <input type="email" class="form-input" placeholder="Enter your email">
+      </div>
+      <div class="form-group">
+        <label class="form-label">Password</label>
+        <input type="password" class="form-input" placeholder="Enter your password">
+      </div>
+      <button class="button" style="margin-top: var(--space-md);">Submit</button>
+    </div>
+
+    <div class="example-section">
+      <h3 class="example-title">Spacing Visualization</h3>
+      <div class="spacing-visual">
+        <div class="spacing-dot"></div>
+        <span class="spacing-label">--space-sm (1rem)</span>
+        <div class="spacing-dot" style="width: var(--space-md); height: var(--space-md);"></div>
+        <span class="spacing-label">--space-md (1.5rem)</span>
+        <div class="spacing-dot" style="width: var(--space-lg); height: var(--space-lg);"></div>
+        <span class="spacing-label">--space-lg (2rem)</span>
+      </div>
+    </div>
+  </div>
+`;