@repobit/dex-system-design 0.21.2 → 0.22.1

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

@@ -1,83 +1,932 @@
 import { html } from 'lit';
 
 export default {
-  title: 'Design Tokens/Grid',
+  title     : 'Design Tokens/Grid System',
+  tags      : ['autodocs'],
   parameters: {
     layout: 'fullscreen',
+    docs  : {
+      description: {
+        component: `
+# Grid System
+
+A responsive, mobile-first grid system based on CSS Grid with semantic classes and design tokens.
+
+## Overview
+
+The grid system provides a flexible layout foundation using CSS Grid Layout. It supports responsive design, fixed and fluid columns, and consistent spacing through design tokens.
+
+## Core Concepts
+
+### 1. Container
+The outermost wrapper that centers content and sets maximum width.
+
+### 2. Row
+Horizontal containers that hold columns. Uses CSS Grid for layout.
+
+### 3. Column
+Content containers that span across the grid. Can be fixed or fluid.
+
+## Usage
+
+### Basic Grid Structure
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="grid-col">
+      <!-- Column content -->
+    </div>
+    <div class="grid-col">
+      <!-- Column content -->
+    </div>
+  </div>
+</div>
+\`\`\`
+
+### Fixed Width Columns
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="col-6">
+      <!-- 50% width column -->
+    </div>
+    <div class="col-6">
+      <!-- 50% width column -->
+    </div>
+  </div>
+</div>
+\`\`\`
+
+### Responsive Grid
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="col-12 col-md-8 col-lg-6">
+      <!-- Responsive column -->
+    </div>
+  </div>
+</div>
+\`\`\`
+
+## Grid Classes Reference
+
+### Container Classes
+| Class | Description | CSS Equivalent |
+|-------|-------------|----------------|
+| \`.grid-container\` | Centers content with max-width | \`max-width: var(--container-max-width)\` |
+| \`.container-fluid\` | Full-width container | \`width: 100%\` |
+
+### Row Classes
+| Class | Description | CSS Equivalent |
+|-------|-------------|----------------|
+| \`.grid-row\` | Grid container row | \`display: grid; grid-template-columns: repeat(auto-fit, minmax(min-content, 1fr))\` |
+| \`.row-gap-sm\` | Small row gap | \`row-gap: var(--space-sm)\` |
+| \`.row-gap-md\` | Medium row gap | \`row-gap: var(--space-md)\` |
+| \`.row-gap-lg\` | Large row gap | \`row-gap: var(--space-lg)\` |
+
+### Column Classes
+#### Fluid Columns
+| Class | Description | Behavior |
+|-------|-------------|----------|
+| \`.grid-col\` | Auto-sizing column | Fills available space equally |
+| \`.col-auto\` | Content-based width | Width based on content size |
+
+#### Fixed Columns (12-column grid)
+| Class | Width | Columns |
+|-------|-------|---------|
+| \`.col-1\` | 8.33% | 1 of 12 |
+| \`.col-2\` | 16.66% | 2 of 12 |
+| \`.col-3\` | 25% | 3 of 12 |
+| \`.col-4\` | 33.33% | 4 of 12 |
+| \`.col-5\` | 41.66% | 5 of 12 |
+| \`.col-6\` | 50% | 6 of 12 |
+| \`.col-7\` | 58.33% | 7 of 12 |
+| \`.col-8\` | 66.66% | 8 of 12 |
+| \`.col-9\` | 75% | 9 of 12 |
+| \`.col-10\` | 83.33% | 10 of 12 |
+| \`.col-11\` | 91.66% | 11 of 12 |
+| \`.col-12\` | 100% | 12 of 12 |
+
+#### Responsive Columns
+| Class | Breakpoint | Description |
+|-------|------------|-------------|
+| \`.col-sm-*\` | ≥576px | Small devices |
+| \`.col-md-*\` | ≥768px | Medium devices |
+| \`.col-lg-*\` | ≥992px | Large devices |
+| \`.col-xl-*\` | ≥1200px | Extra large devices |
+
+## Design Tokens
+
+The grid system uses CSS custom properties for consistent spacing and sizing:
+
+\`\`\`css
+:root {
+  /* Container */
+  --container-max-width: 1200px;
+  --container-padding: var(--space-lg);
+  
+  /* Grid */
+  --grid-columns: 12;
+  --grid-gap: var(--space-md);
+  
+  /* Breakpoints */
+  --breakpoint-sm: 576px;
+  --breakpoint-md: 768px;
+  --breakpoint-lg: 992px;
+  --breakpoint-xl: 1200px;
+}
+\`\`\`
+
+## Examples
+
+### Equal Width Columns
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="grid-col">Column 1</div>
+    <div class="grid-col">Column 2</div>
+    <div class="grid-col">Column 3</div>
+  </div>
+</div>
+\`\`\`
+
+### Mixed Fixed and Fluid
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="col-4">Fixed 33%</div>
+    <div class="grid-col">Fluid remaining</div>
+  </div>
+</div>
+\`\`\`
+
+### Nested Grids
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="col-8">
+      <div class="grid-row">
+        <div class="col-6">Nested 50%</div>
+        <div class="col-6">Nested 50%</div>
+      </div>
+    </div>
+    <div class="col-4">Sidebar</div>
+  </div>
+</div>
+\`\`\`
+
+### Responsive Layout
+\`\`\`html
+<div class="grid-container">
+  <div class="grid-row">
+    <div class="col-12 col-md-8 col-lg-6">
+      Content adjusts based on screen size
+    </div>
+    <div class="col-12 col-md-4 col-lg-6">
+      Sidebar adjusts accordingly
+    </div>
+  </div>
+</div>
+\`\`\`
+
+## Best Practices
+
+### 1. Always Use Container
+Wrap your grid in a container for proper centering and padding:
+\`\`\`html
+<!-- Good ✅ -->
+<div class="grid-container">
+  <div class="grid-row">...</div>
+</div>
+
+<!-- Bad ❌ -->
+<div class="grid-row">...</div>
+\`\`\`
+
+### 2. Column Sum Should Equal 12 (for fixed grids)
+\`\`\`html
+<!-- Good ✅ -->
+<div class="col-8">...</div>
+<div class="col-4">...</div>
+<!-- Total: 12 -->
+
+<!-- Bad ❌ -->
+<div class="col-7">...</div>
+<div class="col-6">...</div>
+<!-- Total: 13, will wrap -->
+\`\`\`
+
+### 3. Use Semantic Class Names
+\`\`\`html
+<!-- Good ✅ -->
+<div class="grid-col">Main Content</div>
+<div class="col-4">Sidebar</div>
+
+<!-- Avoid ❌ -->
+<div style="grid-column: span 8;">Main Content</div>
+\`\`\`
+
+### 4. Responsive Considerations
+- Test on multiple screen sizes
+- Use responsive column classes
+- Consider mobile-first approach
+- Ensure touch targets are adequate
+
+## Browser Support
+
+CSS Grid is supported in:
+- Chrome 57+
+- Firefox 52+
+- Safari 10.1+
+- Edge 16+
+
+For older browsers, consider using feature detection with \`@supports\`:
+\`\`\`css
+@supports (display: grid) {
+  .grid-row {
+    display: grid;
+  }
+}
+
+@supports not (display: grid) {
+  .grid-row {
+    display: flex;
+    flex-wrap: wrap;
+  }
+}
+\`\`\`
+
+## Performance
+
+- CSS Grid has excellent performance in modern browsers
+- Avoid deeply nested grids when possible
+- Use \`grid-auto-flow: dense\` for complex layouts
+- Consider \`will-change: transform\` for animated grids
+
+## Accessibility
+
+- Maintain logical source order
+- Ensure proper heading hierarchy within grids
+- Test keyboard navigation
+- Verify screen reader announcements
+- Maintain sufficient color contrast
+        `
+      }
+    }
   },
+
   argTypes: {
-    backgroundColor: { control: 'color' },
-    padding: { control: 'text' },
-    gutter: { control: 'text' },
-    colBg1: { control: 'color' },
-    colBg2: { control: 'color' },
-  },
+    backgroundColor: {
+      control    : 'color',
+      description: 'Background color for container',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '#f4f4f4' }
+      }
+    },
+    padding: {
+      control    : 'text',
+      description: 'Padding for container and columns',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'var(--space-md)' }
+      }
+    },
+    gutter: {
+      control    : 'text',
+      description: 'Gap between columns',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'var(--grid-gap, var(--space-md))' }
+      }
+    },
+    colBg1: {
+      control    : 'color',
+      description: 'Background color for first column',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '#bbb' }
+      }
+    },
+    colBg2: {
+      control    : 'color',
+      description: 'Background color for second column',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '#999' }
+      }
+    },
+    maxWidth: {
+      control    : 'text',
+      description: 'Maximum width of container',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'var(--container-max-width, 1200px)' }
+      }
+    }
+  }
 };
 
-export const GridContainer = ({ backgroundColor, padding }) => html`
-  <div class="grid-container" style="background: ${backgroundColor}; padding: ${padding};">
-    <p style="margin: 0;">.grid-container (folosește max-width & padding din tokens)</p>
+const Template = (args) => html`
+  <style>
+    :root {
+      --container-max-width: 1200px;
+      --grid-gap: var(--space-md);
+      --space-md: 1.5rem;
+      --space-lg: 2rem;
+    }
+    
+    .story-container {
+      padding: 2rem;
+      background: #f8f9fa;
+      min-height: 100vh;
+    }
+    
+    .grid-container {
+      max-width: ${args.maxWidth};
+      margin: 0 auto;
+      padding: ${args.padding};
+      background: ${args.backgroundColor};
+      border-radius: 8px;
+      border: 2px solid #dee2e6;
+    }
+    
+    .grid-row {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(min-content, 1fr));
+      gap: ${args.gutter};
+    }
+    
+    .grid-col {
+      min-height: 100px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      border-radius: 4px;
+    }
+    
+    .col-6 {
+      grid-column: span 6;
+      min-height: 100px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      border-radius: 4px;
+    }
+    
+    .col-4 {
+      grid-column: span 4;
+    }
+    
+    .col-8 {
+      grid-column: span 8;
+    }
+    
+    .col-12 {
+      grid-column: span 12;
+    }
+    
+    .info-panel {
+      background: white;
+      padding: 1.5rem;
+      border-radius: 8px;
+      margin-bottom: 2rem;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    
+    .info-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 1.25rem;
+      font-weight: 600;
+      margin: 0 0 1rem 0;
+      color: #212529;
+    }
+    
+    .info-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      gap: 1rem;
+      margin-top: 1rem;
+    }
+    
+    .info-item {
+      padding: 1rem;
+      background: #f8f9fa;
+      border-radius: 4px;
+      border-left: 4px solid #007bff;
+    }
+    
+    .info-label {
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      color: #495057;
+      margin: 0 0 0.25rem 0;
+      font-size: 0.9rem;
+    }
+    
+    .info-value {
+      font-family: var(--font-family-mono, monospace);
+      color: #6c757d;
+      margin: 0;
+      font-size: 0.85rem;
+    }
+    
+    .code-block {
+      background: #1a1a1a;
+      color: #f8f8f2;
+      padding: 1.5rem;
+      border-radius: 4px;
+      font-family: var(--font-family-mono, monospace);
+      font-size: 0.85rem;
+      line-height: 1.5;
+      overflow-x: auto;
+      margin-top: 1rem;
+    }
+    
+    .code-comment { color: #6272a4; }
+    .code-class { color: #50fa7b; }
+    .code-property { color: #f1fa8c; }
+    .code-value { color: #ff79c6; }
+  </style>
+
+  <div class="story-container">
+    <div class="info-panel">
+      <h3 class="info-title">Grid System Configuration</h3>
+      <div class="info-grid">
+        <div class="info-item">
+          <p class="info-label">Container Max Width</p>
+          <p class="info-value">${args.maxWidth}</p>
+        </div>
+        <div class="info-item">
+          <p class="info-label">Container Padding</p>
+          <p class="info-value">${args.padding}</p>
+        </div>
+        <div class="info-item">
+          <p class="info-label">Grid Gutter</p>
+          <p class="info-value">${args.gutter}</p>
+        </div>
+      </div>
+    </div>
+    
+    <div class="grid-container">
+      <div class="grid-row" style="gap: ${args.gutter};">
+        <div class="grid-col" style="background: ${args.colBg1}; padding: ${args.padding};">
+          .grid-col (auto width)
+        </div>
+        <div class="grid-col" style="background: ${args.colBg2}; padding: ${args.padding};">
+          .grid-col (auto width)
+        </div>
+      </div>
+    </div>
+    
+    <div class="code-block">
+      <span class="code-comment">HTML Structure:</span><br>
+      &lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-container"</span>&gt;<br>
+      &nbsp;&nbsp;&lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-row"</span>&gt;<br>
+      &nbsp;&nbsp;&nbsp;&nbsp;&lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-col"</span>&gt;Column 1&lt;/<span class="code-class">div</span>&gt;<br>
+      &nbsp;&nbsp;&nbsp;&nbsp;&lt;<span class="code-class">div</span> <span class="code-property">class</span>=<span class="code-value">"grid-col"</span>&gt;Column 2&lt;/<span class="code-class">div</span>&gt;<br>
+      &nbsp;&nbsp;&lt;/<span class="code-class">div</span>&gt;<br>
+      &lt;/<span class="code-class">div</span>&gt;
+    </div>
   </div>
 `;
+
+export const GridContainer = Template.bind({});
 GridContainer.args = {
   backgroundColor: '#f4f4f4',
-  padding: '1rem',
+  padding        : 'var(--space-lg)',
+  gutter         : 'var(--space-md)',
+  colBg1         : '#bbb',
+  colBg2         : '#999',
+  maxWidth       : 'var(--container-max-width, 1200px)'
+};
+GridContainer.storyName = 'Basic Grid';
+GridContainer.parameters = {
+  docs: {
+    description: {
+      story: 'Basic grid container with auto-sizing columns. Demonstrates the foundational grid structure with container, row, and columns.'
+    }
+  }
 };
-GridContainer.storyName = 'Container';
 
-export const GridRowCol = ({ colBg1, colBg2, padding }) => html`
-  <div class="grid-container" style="margin-top: 2rem;">
-    <div class="grid-row" style="background: #ddd;">
-      <div class="grid-col" style="background: ${colBg1}; text-align: center; padding: ${padding};">
-        .grid-col 1
-      </div>
-      <div class="grid-col" style="background: ${colBg2}; text-align: center; padding: ${padding};">
-        .grid-col 2
+export const FixedColumns = (args) => html`
+  <style>
+    .demo-container {
+      padding: 2rem;
+      background: #f8f9fa;
+      min-height: 100vh;
+    }
+    
+    .grid-container {
+      max-width: ${args.maxWidth};
+      margin: 0 auto;
+      padding: ${args.padding};
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    
+    .grid-row {
+      display: grid;
+      grid-template-columns: repeat(12, 1fr);
+      gap: ${args.gutter};
+      margin-bottom: 2rem;
+    }
+    
+    .col {
+      min-height: 80px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      border-radius: 4px;
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      color: white;
+    }
+    
+    .col-1 { grid-column: span 1; background: #007bff; }
+    .col-2 { grid-column: span 2; background: #6f42c1; }
+    .col-3 { grid-column: span 3; background: #e83e8c; }
+    .col-4 { grid-column: span 4; background: #fd7e14; }
+    .col-5 { grid-column: span 5; background: #20c997; }
+    .col-6 { grid-column: span 6; background: #17a2b8; }
+    .col-7 { grid-column: span 7; background: #ffc107; color: #212529; }
+    .col-8 { grid-column: span 8; background: #dc3545; }
+    .col-9 { grid-column: span 9; background: #343a40; }
+    .col-10 { grid-column: span 10; background: #28a745; }
+    .col-11 { grid-column: span 11; background: #6c757d; }
+    .col-12 { grid-column: span 12; background: #6610f2; }
+    
+    .grid-example {
+      margin-bottom: 3rem;
+    }
+    
+    .example-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 1.1rem;
+      font-weight: 600;
+      margin: 0 0 1rem 0;
+      color: #212529;
+    }
+    
+    .example-description {
+      font-family: var(--font-family-sans, sans-serif);
+      color: #6c757d;
+      margin: 0 0 1.5rem 0;
+      font-size: 0.9rem;
+    }
+  </style>
+
+  <div class="demo-container">
+    <div class="grid-container">
+      <div class="grid-example">
+        <h3 class="example-title">12-Column Grid System</h3>
+        <p class="example-description">All available fixed-width column classes:</p>
+        <div class="grid-row">
+          ${[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map(num => html`
+            <div class="col col-1">.col-1</div>
+          `)}
+        </div>
+        
+        <div class="grid-row">
+          <div class="col col-6">.col-6 (50%)</div>
+          <div class="col col-6">.col-6 (50%)</div>
+        </div>
+        
+        <div class="grid-row">
+          <div class="col col-4">.col-4 (33%)</div>
+          <div class="col col-4">.col-4 (33%)</div>
+          <div class="col col-4">.col-4 (33%)</div>
+        </div>
+        
+        <div class="grid-row">
+          <div class="col col-8">.col-8 (66%)</div>
+          <div class="col col-4">.col-4 (33%)</div>
+        </div>
+        
+        <div class="grid-row">
+          <div class="col col-3">.col-3 (25%)</div>
+          <div class="col col-6">.col-6 (50%)</div>
+          <div class="col col-3">.col-3 (25%)</div>
+        </div>
       </div>
     </div>
   </div>
 `;
-GridRowCol.args = {
-  colBg1: '#bbb',
-  colBg2: '#999',
-  padding: '1rem',
+FixedColumns.args = {
+  padding : 'var(--space-lg)',
+  gutter  : 'var(--space-sm)',
+  maxWidth: 'var(--container-max-width, 1200px)'
+};
+FixedColumns.storyName = 'Fixed Columns';
+FixedColumns.parameters = {
+  docs: {
+    description: {
+      story: 'Fixed-width column system based on a 12-column grid. Demonstrates all available column classes from .col-1 to .col-12.'
+    }
+  }
 };
-GridRowCol.storyName = 'Row + Col (auto)';
 
-export const FixedColumns = ({ colBg1, colBg2, padding }) => html`
-  <div class="grid-container" style="margin-top: 2rem;">
-    <div class="grid-row">
-      <div class="col-6" style="background: ${colBg1}; padding: ${padding}; text-align: center;">
-        .col-6 (50%)
+export const ResponsiveGrid = () => html`
+  <style>
+    .responsive-demo {
+      padding: 2rem;
+      background: #f8f9fa;
+      min-height: 100vh;
+    }
+    
+    .grid-container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 2rem;
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    
+    .grid-row {
+      display: grid;
+      gap: 1rem;
+      margin-bottom: 2rem;
+    }
+    
+    .col {
+      padding: 1.5rem;
+      border-radius: 6px;
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      text-align: center;
+      min-height: 120px;
+    }
+    
+    .col-1 { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; }
+    .col-2 { background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%); color: white; }
+    .col-3 { background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%); color: white; }
+    
+    .breakpoint-info {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      gap: 1rem;
+      margin-bottom: 2rem;
+    }
+    
+    .breakpoint-card {
+      padding: 1rem;
+      background: #f8f9fa;
+      border-radius: 6px;
+      border-left: 4px solid #007bff;
+    }
+    
+    .breakpoint-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      margin: 0 0 0.5rem 0;
+      color: #212529;
+    }
+    
+    .breakpoint-desc {
+      font-family: var(--font-family-sans, sans-serif);
+      color: #6c757d;
+      margin: 0;
+      font-size: 0.9rem;
+    }
+    
+    .device-preview {
+      position: relative;
+      border: 2px solid #dee2e6;
+      border-radius: 12px;
+      padding: 1rem;
+      margin: 1rem 0;
+      background: #f8f9fa;
+    }
+    
+    .device-label {
+      position: absolute;
+      top: -12px;
+      left: 1rem;
+      background: #007bff;
+      color: white;
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-family: var(--font-family-sans, sans-serif);
+      font-size: 0.8rem;
+      font-weight: 600;
+    }
+    
+    .responsive-code {
+      background: #1a1a1a;
+      color: #f8f8f2;
+      padding: 1.5rem;
+      border-radius: 6px;
+      font-family: var(--font-family-mono, monospace);
+      font-size: 0.85rem;
+      line-height: 1.5;
+      margin-top: 2rem;
+    }
+  </style>
+
+  <div class="responsive-demo">
+    <div class="grid-container">
+      <h3 style="font-family: var(--font-family-sans, sans-serif); margin: 0 0 2rem 0;">Responsive Grid System</h3>
+      
+      <div class="breakpoint-info">
+        <div class="breakpoint-card">
+          <h4 class="breakpoint-title">Mobile First</h4>
+          <p class="breakpoint-desc">Columns stack vertically by default on small screens</p>
+        </div>
+        <div class="breakpoint-card">
+          <h4 class="breakpoint-title">Tablet (≥768px)</h4>
+          <p class="breakpoint-desc">Use .col-md-* classes for tablet layouts</p>
+        </div>
+        <div class="breakpoint-card">
+          <h4 class="breakpoint-title">Desktop (≥992px)</h4>
+          <p class="breakpoint-desc">Use .col-lg-* classes for desktop layouts</p>
+        </div>
+      </div>
+      
+      <div class="device-preview">
+        <div class="device-label">Mobile (Stacked)</div>
+        <div class="grid-row">
+          <div class="col col-12" style="background: #007bff; color: white;">.col-12 (100%)</div>
+          <div class="col col-12" style="background: #28a745; color: white;">.col-12 (100%)</div>
+        </div>
       </div>
-      <div class="col-6" style="background: ${colBg2}; padding: ${padding}; text-align: center;">
-        .col-6 (50%)
+      
+      <div class="device-preview">
+        <div class="device-label">Tablet (2 Columns)</div>
+        <div class="grid-row" style="grid-template-columns: repeat(2, 1fr);">
+          <div class="col col-1">.col-md-6</div>
+          <div class="col col-2">.col-md-6</div>
+        </div>
+      </div>
+      
+      <div class="device-preview">
+        <div class="device-label">Desktop (3 Columns)</div>
+        <div class="grid-row" style="grid-template-columns: repeat(3, 1fr);">
+          <div class="col col-1">.col-lg-4</div>
+          <div class="col col-2">.col-lg-4</div>
+          <div class="col col-3">.col-lg-4</div>
+        </div>
+      </div>
+      
+      <div class="responsive-code">
+        <span style="color: #6272a4;">/* Responsive column example */</span><br>
+        &lt;div class="col-12 col-md-6 col-lg-4"&gt;<br>
+        &nbsp;&nbsp;<span style="color: #6272a4;">&lt;!-- Stacked on mobile, 2 columns on tablet, 3 columns on desktop --&gt;</span><br>
+        &lt;/div&gt;
       </div>
     </div>
   </div>
 `;
-FixedColumns.args = {
-  colBg1: '#ccc',
-  colBg2: '#aaa',
-  padding: '1rem',
+ResponsiveGrid.storyName = 'Responsive Grid';
+ResponsiveGrid.parameters = {
+  docs: {
+    description: {
+      story: 'Responsive grid system with mobile-first approach. Shows how columns adapt to different screen sizes using responsive classes.'
+    }
+  }
 };
-FixedColumns.storyName = 'Coloane fixe (.col-6)';
 
-export const GutterExample = ({ gutter, colBg1, colBg2 }) => html`
-  <div class="grid-container" style="margin-top: 2rem;">
-    <div class="grid-row" style="gap: ${gutter};">
-      <div class="grid-col" style="background: ${colBg1}; padding: 1rem; border: 1px dashed red;">
-        .grid-col cu gutter (verifică spacing)
+export const GutterExample = (args) => html`
+  <style>
+    .gutter-demo {
+      padding: 2rem;
+      background: #f8f9fa;
+      min-height: 100vh;
+    }
+    
+    .grid-container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 2rem;
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    
+    .gutter-visualization {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr);
+      gap: 2rem;
+      margin-bottom: 3rem;
+    }
+    
+    .gutter-example {
+      padding: 1.5rem;
+      border-radius: 6px;
+      border: 2px solid #dee2e6;
+    }
+    
+    .example-title {
+      font-family: var(--font-family-sans, sans-serif);
+      font-weight: 600;
+      margin: 0 0 1rem 0;
+      color: #212529;
+    }
+    
+    .grid-row-demo {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr);
+      margin: 1rem 0;
+    }
+    
+    .grid-col-demo {
+      background: #007bff;
+      color: white;
+      padding: 1rem;
+      border-radius: 4px;
+      font-family: var(--font-family-sans, sans-serif);
+      text-align: center;
+    }
+    
+    .no-gap { gap: 0; }
+    .gap-sm { gap: var(--space-sm); }
+    .gap-md { gap: var(--space-md); }
+    .gap-lg { gap: var(--space-lg); }
+    
+    .gutter-preview {
+      height: 60px;
+      background: repeating-linear-gradient(
+        90deg,
+        #dee2e6,
+        #dee2e6 1px,
+        transparent 1px,
+        transparent calc(${args.gutter} - 1px)
+      );
+      margin: 1rem 0;
+      border-radius: 4px;
+    }
+    
+    .gutter-value {
+      font-family: var(--font-family-mono, monospace);
+      background: #f8f9fa;
+      padding: 0.5rem;
+      border-radius: 4px;
+      margin: 0.5rem 0;
+    }
+  </style>
+
+  <div class="gutter-demo">
+    <div class="grid-container">
+      <h3 style="font-family: var(--font-family-sans, sans-serif); margin: 0 0 2rem 0;">Grid Gutter System</h3>
+      
+      <div class="gutter-visualization">
+        <div class="gutter-example">
+          <h4 class="example-title">No Gutter</h4>
+          <div class="grid-row-demo no-gap">
+            <div class="grid-col-demo">Column 1</div>
+            <div class="grid-col-demo">Column 2</div>
+          </div>
+          <div class="gutter-value">gap: 0</div>
+        </div>
+        
+        <div class="gutter-example">
+          <h4 class="example-title">Small Gutter</h4>
+          <div class="grid-row-demo gap-sm">
+            <div class="grid-col-demo">Column 1</div>
+            <div class="grid-col-demo">Column 2</div>
+          </div>
+          <div class="gutter-value">gap: var(--space-sm)</div>
+        </div>
+        
+        <div class="gutter-example">
+          <h4 class="example-title">Medium Gutter (Default)</h4>
+          <div class="grid-row-demo gap-md">
+            <div class="grid-col-demo">Column 1</div>
+            <div class="grid-col-demo">Column 2</div>
+          </div>
+          <div class="gutter-value">gap: var(--space-md)</div>
+        </div>
+        
+        <div class="gutter-example">
+          <h4 class="example-title">Large Gutter</h4>
+          <div class="grid-row-demo gap-lg">
+            <div class="grid-col-demo">Column 1</div>
+            <div class="grid-col-demo">Column 2</div>
+          </div>
+          <div class="gutter-value">gap: var(--space-lg)</div>
+        </div>
       </div>
-      <div class="grid-col" style="background: ${colBg2}; padding: 1rem; border: 1px dashed red;">
-        .grid-col cu gutter
+      
+      <div style="background: #f8f9fa; padding: 1.5rem; border-radius: 6px; margin-top: 2rem;">
+        <h4 style="font-family: var(--font-family-sans, sans-serif); margin: 0 0 1rem 0;">Current Gutter Preview</h4>
+        <div class="gutter-preview"></div>
+        <div class="gutter-value">Current gutter value: ${args.gutter}</div>
       </div>
     </div>
   </div>
 `;
 GutterExample.args = {
-  gutter: '1rem',
-  colBg1: '#e0e0e0',
-  colBg2: '#d0d0d0',
+  gutter: 'var(--space-md)'
 };
-GutterExample.storyName = 'Spațiere între coloane (gutter)';
+GutterExample.storyName = 'Grid Gutter';
+GutterExample.parameters = {
+  docs: {
+    description: {
+      story: 'Grid gutter (gap) system demonstrating different spacing options between columns. Shows visual comparison of no gutter, small, medium, and large gutters.'
+    }
+  }
+};