@repobit/dex-system-design 0.21.1 → 0.22.0

package/src/components/heading/heading.stories.js

@@ -1,260 +1,502 @@
 import { html } from 'lit';
+import '../paragraph/paragraph.js';
 import './heading.js';
 
 export default {
   title    : 'Atoms/Heading',
   component: 'bd-h',
+  tags     : ['autodocs'],
   argTypes : {
-    kind: {
+    as: {
       control    : { type: 'select' },
       options    : ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
-      description: 'Heading level (h1-h6)'
+      description: 'Semantic HTML heading level (h1-h6)',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'h2' }
+      }
+    },
+    color: {
+      control    : 'color',
+      description: 'Custom text color for the heading',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'inherit' }
+      }
+    },
+    align: {
+      control    : { type: 'select' },
+      options    : ['left', 'center', 'right'],
+      description: 'Text alignment',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'left' }
+      }
     },
     content: {
       control    : 'text',
-      description: 'Heading text content'
+      description: 'Heading text content',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'Heading Text' }
+      }
     }
   },
   parameters: {
     docs: {
       description: {
-        component: 'A customizable heading component with semantic HTML and consistent typography.'
+        component: 'A semantic heading component that provides proper HTML structure with consistent typography. Supports all heading levels from h1 to h6 with customizable styling.'
       }
     }
   }
 };
 
-const Template = ({ kind, content }) => html`
-  <bd-h as="${kind}">${content}</bd-h>
+const Template = ({ as, color, align, content }) => html`
+  <bd-h 
+    as="${as}" 
+    style="${color ? `color: ${color};` : ''} ${align ? `text-align: ${align};` : ''}"
+  >
+    ${content}
+  </bd-h>
 `;
 
-export const AllHeadings = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem;">
-    <bd-h as="h1">Heading Level 1 - Main Title</bd-h>
-    <bd-h as="h2">Heading Level 2 - Section Title</bd-h>
-    <bd-h as="h3">Heading Level 3 - Subsection Title</bd-h>
-    <bd-h as="h4">Heading Level 4 - Card Title</bd-h>
-    <bd-h as="h5">Heading Level 5 - Small Heading</bd-h>
-    <bd-h as="h6">Heading Level 6 - Minor Heading</bd-h>
+// ============ STORIES ============
+
+export const Default = Template.bind({});
+Default.args = {
+  as     : 'h2',
+  content: 'Default Heading',
+  color  : '',
+  align  : 'left'
+};
+Default.parameters = {
+  docs: {
+    description: {
+      story: 'Default heading component with h2 level. Perfect for most section titles and content headings.'
+    }
+  }
+};
+
+export const AllHeadingLevels = () => html`
+  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h1" style="margin-bottom: 0.5rem;">Heading Level 1 - Main Title</bd-h>
+    <bd-p kind="small" style="color: #64748b; margin-bottom: 1rem;">
+      <strong>Use case:</strong> Primary page title, main hero sections<br>
+      <strong>CSS Variables:</strong> --typography-heading-h1-fontSize, --typography-heading-h1-fontWeight<br>
+      <strong>SEO:</strong> One h1 per page for optimal search engine ranking
+    </bd-p>
+
+    <bd-h as="h2" style="margin-bottom: 0.5rem;">Heading Level 2 - Section Title</bd-h>
+    <bd-p kind="small" style="color: #64748b; margin-bottom: 1rem;">
+      <strong>Use case:</strong> Major section titles, main content divisions<br>
+      <strong>CSS Variables:</strong> --typography-heading-h2-fontSize, --typography-heading-h2-fontWeight<br>
+      <strong>Structure:</strong> Used for primary content sections
+    </bd-p>
+
+    <bd-h as="h3" style="margin-bottom: 0.5rem;">Heading Level 3 - Subsection Title</bd-h>
+    <bd-p kind="small" style="color: #64748b; margin-bottom: 1rem;">
+      <strong>Use case:</strong> Sub-sections, feature titles, card headers<br>
+      <strong>CSS Variables:</strong> --typography-heading-h3-fontSize, --typography-heading-h3-fontWeight<br>
+      <strong>Hierarchy:</strong> Nested under h2 sections
+    </bd-p>
+
+    <bd-h as="h4" style="margin-bottom: 0.5rem;">Heading Level 4 - Content Heading</bd-h>
+    <bd-p kind="small" style="color: #64748b; margin-bottom: 1rem;">
+      <strong>Use case:</strong> Smaller sections, widget titles, detailed content<br>
+      <strong>CSS Variables:</strong> --typography-heading-h4-fontSize, --typography-heading-h4-fontWeight<br>
+      <strong>Usage:</strong> For content that needs less visual emphasis
+    </bd-p>
+
+    <bd-h as="h5" style="margin-bottom: 0.5rem;">Heading Level 5 - Minor Heading</bd-h>
+    <bd-p kind="small" style="color: #64748b; margin-bottom: 1rem;">
+      <strong>Use case:</strong> Sidebar titles, footer sections, minor labels<br>
+      <strong>CSS Variables:</strong> --typography-heading-h5-fontSize, --typography-heading-h5-fontWeight<br>
+      <strong>Appearance:</strong> Smaller and less prominent
+    </bd-p>
+
+    <bd-h as="h6" style="margin-bottom: 0.5rem;">Heading Level 6 - Smallest Heading</bd-h>
+    <bd-p kind="small" style="color: #64748b;">
+      <strong>Use case:</strong> Legal text, captions, fine print headings<br>
+      <strong>CSS Variables:</strong> --typography-heading-h6-fontSize, --typography-heading-h6-fontWeight<br>
+      <strong>Note:</strong> Smallest heading level available
+    </bd-p>
   </div>
 `;
-AllHeadings.parameters = {
+AllHeadingLevels.parameters = {
   docs: {
     description: {
-      story: 'All heading levels from h1 to h6 displayed together for comparison.'
+      story: 'Complete overview of all heading levels from h1 (largest) to h6 (smallest) with usage guidelines, CSS variable references, and semantic recommendations.'
     }
   }
 };
 
 export const Heading1 = Template.bind({});
 Heading1.args = {
-  kind   : 'h1',
-  content: 'Main Page Title (h1)'
+  as     : 'h1',
+  content: 'Main Page Title (H1)',
+  color  : '',
+  align  : 'left'
 };
 Heading1.parameters = {
   docs: {
     description: {
-      story: 'Primary heading level for main page titles and important sections.'
+      story: 'Primary heading level (h1) - Use as the main title for pages and major sections. There should typically be only one h1 per page for optimal SEO and accessibility.'
     }
   }
 };
 
 export const Heading2 = Template.bind({});
 Heading2.args = {
-  kind   : 'h2',
-  content: 'Section Title (h2)'
+  as     : 'h2',
+  content: 'Section Title (H2)',
+  color  : '',
+  align  : 'left'
 };
 Heading2.parameters = {
   docs: {
     description: {
-      story: 'Secondary heading level for major section titles.'
+      story: 'Secondary heading level (h2) - Perfect for major content sections and primary division titles within a page.'
     }
   }
 };
 
 export const Heading3 = Template.bind({});
 Heading3.args = {
-  kind   : 'h3',
-  content: 'Subsection Title (h3)'
+  as     : 'h3',
+  content: 'Subsection Title (H3)',
+  color  : '',
+  align  : 'left'
 };
 Heading3.parameters = {
   docs: {
     description: {
-      story: 'Tertiary heading level for subsection titles and card headers.'
+      story: 'Tertiary heading level (h3) - Ideal for subsection titles, feature headings, and card headers within h2 sections.'
     }
   }
 };
 
 export const Heading4 = Template.bind({});
 Heading4.args = {
-  kind   : 'h4',
-  content: 'Card Title (h4)'
+  as     : 'h4',
+  content: 'Content Heading (H4)',
+  color  : '',
+  align  : 'left'
 };
 Heading4.parameters = {
   docs: {
     description: {
-      story: 'Heading level for card titles, feature names, and smaller sections.'
+      story: 'Content heading level (h4) - Suitable for smaller content sections, widget titles, and detailed information headings.'
     }
   }
 };
 
 export const Heading5 = Template.bind({});
 Heading5.args = {
-  kind   : 'h5',
-  content: 'Small Heading (h5)'
+  as     : 'h5',
+  content: 'Minor Heading (H5)',
+  color  : '',
+  align  : 'left'
 };
 Heading5.parameters = {
   docs: {
     description: {
-      story: 'Small heading level for less important titles and labels.'
+      story: 'Minor heading level (h5) - Use for sidebar sections, footer headings, and less important content labels.'
     }
   }
 };
 
 export const Heading6 = Template.bind({});
 Heading6.args = {
-  kind   : 'h6',
-  content: 'Minor Heading (h6)'
+  as     : 'h6',
+  content: 'Smallest Heading (H6)',
+  color  : '',
+  align  : 'left'
 };
 Heading6.parameters = {
   docs: {
     description: {
-      story: 'Smallest heading level for minor titles and captions.'
+      story: 'Smallest heading level (h6) - Designed for legal text, captions, fine print, and the least prominent headings.'
+    }
+  }
+};
+
+export const TextAlignment = () => html`
+  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h2" style="margin-bottom: 1rem;">Text Alignment Options</bd-h>
+    
+    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="text-align: left; margin-bottom: 1rem;">Left Aligned Heading</bd-h>
+      <bd-p kind="regular" style="color: #64748b;">
+        Default alignment. Best for most content sections, articles, and body text. Provides optimal readability for long content.
+      </bd-p>
+    </div>
+
+    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="text-align: center; margin-bottom: 1rem;">Center Aligned Heading</bd-h>
+      <bd-p kind="regular" style="color: #64748b; text-align: center;">
+        Ideal for hero sections, testimonials, feature highlights, and marketing content. Creates visual balance and emphasis.
+      </bd-p>
+    </div>
+
+    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="text-align: right; margin-bottom: 1rem;">Right Aligned Heading</bd-h>
+      <bd-p kind="regular" style="color: #64748b; text-align: right;">
+        Useful for asymmetric layouts, creative designs, and specific visual compositions. Use sparingly for intentional design effects.
+      </bd-p>
+    </div>
+  </div>
+`;
+TextAlignment.parameters = {
+  docs: {
+    description: {
+      story: 'Demonstrates different text alignment options for headings with recommendations for when to use left, center, or right alignment based on content type and design context.'
     }
   }
 };
 
-export const WithParagraphs = () => html`
-  <div style="max-width: 800px; margin: 0 auto;">
-    <bd-h as="h1">Product Features</bd-h>
-    <bd-p kind="regular">Discover all the powerful features that make our product stand out from the competition.</bd-p>
+export const ColorCustomization = () => html`
+  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h2" style="margin-bottom: 1rem;">Color Customization Examples</bd-h>
     
-    <bd-h as="h2">Security Features</bd-h>
-    <bd-p kind="regular">Our advanced security features protect you from all types of online threats.</bd-p>
+    <div style="background: #1e293b; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="color: #ffffff; margin-bottom: 1rem;">White Text on Dark Background</bd-h>
+      <bd-p kind="regular" style="color: #cbd5e1;">
+        Perfect for dark theme sections, hero areas with dark backgrounds, and high-contrast designs.
+      </bd-p>
+    </div>
+
+    <div style="background: #dbeafe; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="color: #1e40af; margin-bottom: 1rem;">Primary Brand Color</bd-h>
+      <bd-p kind="regular" style="color: #374151;">
+        Using brand colors for visual consistency and emphasis. Maintains brand identity across the application.
+      </bd-p>
+    </div>
+
+    <div style="background: #f0fdf4; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="color: #166534; margin-bottom: 1rem;">Success Green Color</bd-h>
+      <bd-p kind="regular" style="color: #374151;">
+        Color coding for specific contexts like success states, positive outcomes, and confirmation messages.
+      </bd-p>
+    </div>
+
+    <div style="background: #fef2f2; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="color: #dc2626; margin-bottom: 1rem;">Error Red Color</bd-h>
+      <bd-p kind="regular" style="color: #374151;">
+        Using red for error states, warnings, critical information, and attention-requiring content.
+      </bd-p>
+    </div>
+
+    <div style="background: #f8fafc; padding: 2rem; border-radius: 8px;">
+      <bd-h as="h3" style="color: #7c3aed; margin-bottom: 1rem;">Accent Purple Color</bd-h>
+      <bd-p kind="regular" style="color: #374151;">
+        Alternative brand color for variety while maintaining visual harmony and design system consistency.
+      </bd-p>
+    </div>
+  </div>
+`;
+ColorCustomization.parameters = {
+  docs: {
+    description: {
+      story: 'Shows how heading components can be customized with different colors for various contexts, themes, and semantic meanings while maintaining readability and accessibility.'
+    }
+  }
+};
+
+export const ContentHierarchy = () => html`
+  <div style="max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h1" style="margin-bottom: 1rem;">Product Documentation</bd-h>
+    <bd-p kind="lead" style="margin-bottom: 2rem;">
+      Comprehensive guide to using our product features and capabilities effectively.
+    </bd-p>
     
-    <bd-h as="h3">Real-time Protection</bd-h>
-    <bd-p kind="regular">Continuous monitoring and protection against emerging threats.</bd-p>
+    <bd-h as="h2" style="margin-bottom: 1rem;">Getting Started</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Learn the basics and set up your account quickly and efficiently.
+    </bd-p>
     
-    <bd-h as="h4">Behavioral Detection</bd-h>
-    <bd-p kind="regular">Advanced algorithms detect suspicious behavior patterns.</bd-p>
+    <bd-h as="h3" style="margin-bottom: 1rem;">Account Setup</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Step-by-step instructions for creating and configuring your account.
+    </bd-p>
     
-    <bd-h as="h5">System Requirements</bd-h>
-    <bd-p kind="small">Windows 10/11, 2GB RAM, 2.5GB free space</bd-p>
+    <bd-h as="h4" style="margin-bottom: 1rem;">Profile Configuration</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Customize your profile settings and preferences for optimal experience.
+    </bd-p>
+    
+    <bd-h as="h2" style="margin-bottom: 1rem;">Advanced Features</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Explore powerful features to maximize your productivity and results.
+    </bd-p>
+    
+    <bd-h as="h3" style="margin-bottom: 1rem;">Automation Tools</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Set up automated workflows to save time and reduce manual tasks.
+    </bd-p>
+    
+    <bd-h as="h4" style="margin-bottom: 1rem;">Custom Scripts</bd-h>
+    <bd-p kind="regular">
+      Create and manage custom scripts for specialized automation needs.
+    </bd-p>
   </div>
 `;
-WithParagraphs.parameters = {
+ContentHierarchy.parameters = {
   docs: {
     description: {
-      story: 'Headings used in context with paragraph components to demonstrate proper hierarchy.'
+      story: 'Demonstrates proper semantic heading hierarchy in a real-world content scenario. Shows how headings should be nested logically without skipping levels for optimal accessibility and SEO.'
     }
   }
 };
 
-export const InCardLayout = () => html`
-  <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem; padding: 2rem;">
-    <div style="border: 1px solid #e2e8f0; border-radius: 8px; padding: 1.5rem;">
-      <bd-h as="h3">Advanced Protection</bd-h>
-      <bd-p kind="regular">Comprehensive security against malware, ransomware, and online threats.</bd-p>
+export const CardLayoutExample = () => html`
+  <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem; padding: 2rem; max-width: 1200px; margin: 0 auto;">
+    <div style="border: 1px solid #e2e8f0; border-radius: 12px; padding: 2rem; background: white; box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);">
+      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Advanced Security</bd-h>
+      <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+        Comprehensive protection against malware, ransomware, phishing, and online threats with real-time monitoring.
+      </bd-p>
+      <bd-h as="h5" style="color: #64748b; margin-bottom: 0.5rem;">Key Features:</bd-h>
+      <bd-p kind="small" style="color: #64748b;">
+        • Real-time threat detection<br>
+        • Behavioral analysis<br>
+        • Automatic updates
+      </bd-p>
     </div>
     
-    <div style="border: 1px solid #e2e8f0; border-radius: 8px; padding: 1.5rem;">
-      <bd-h as="h3">Privacy Features</bd-h>
-      <bd-p kind="regular">VPN, password manager, and webcam protection to keep your data safe.</bd-p>
+    <div style="border: 1px solid #e2e8f0; border-radius: 12px; padding: 2rem; background: white; box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);">
+      <bd-h as="h3" style="color: #8b5cf6; margin-bottom: 1rem;">Privacy Protection</bd-h>
+      <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+        VPN, password manager, and webcam protection to keep your personal data and privacy secure from intrusions.
+      </bd-p>
+      <bd-h as="h5" style="color: #64748b; margin-bottom: 0.5rem;">Included Tools:</bd-h>
+      <bd-p kind="small" style="color: #64748b;">
+        • Encrypted VPN<br>
+        • Password manager<br>
+        • Webcam shield
+      </bd-p>
     </div>
     
-    <div style="border: 1px solid #e2e8f0; border-radius: 8px; padding: 1.5rem;">
-      <bd-h as="h3">Performance</bd-h>
-      <bd-p kind="regular">Lightweight design with minimal impact on system resources.</bd-p>
+    <div style="border: 1px solid #e2e8f0; border-radius: 12px; padding: 2rem; background: white; box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);">
+      <bd-h as="h3" style="color: #10b981; margin-bottom: 1rem;">Performance Boost</bd-h>
+      <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+        Lightweight design with minimal impact on system resources while optimizing performance and speed.
+      </bd-p>
+      <bd-h as="h5" style="color: #64748b; margin-bottom: 0.5rem;">Benefits:</bd-h>
+      <bd-p kind="small" style="color: #64748b;">
+        • Fast scanning<br>
+        • Low resource usage<br>
+        • Quick startup
+      </bd-p>
     </div>
   </div>
 `;
-InCardLayout.parameters = {
+CardLayoutExample.parameters = {
   docs: {
     description: {
-      story: 'Headings used in card layouts to demonstrate real-world usage patterns.'
+      story: 'Real-world example showing headings used in card layouts with different colors and hierarchy levels. Demonstrates how headings work in modern UI designs and component-based layouts.'
     }
   }
 };
 
-export const AccessibilityExample = () => html`
-  <div style="max-width: 800px; margin: 0 auto;">
-    <bd-h as="h1">Accessibility Guidelines</bd-h>
-    <bd-p kind="regular">Proper heading hierarchy is essential for screen reader users and SEO.</bd-p>
+export const AccessibilityGuidelines = () => html`
+  <div style="max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h1" style="margin-bottom: 1rem;">Accessibility Best Practices</bd-h>
+    <bd-p kind="lead" style="margin-bottom: 2rem;">
+      Proper heading structure is essential for screen reader users, keyboard navigation, and search engine optimization.
+    </bd-p>
     
-    <bd-h as="h2">Semantic Structure</bd-h>
-    <bd-p kind="regular">Headings should follow a logical hierarchy without skipping levels.</bd-p>
+    <bd-h as="h2" style="margin-bottom: 1rem;">Semantic Structure</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Headings should follow a logical hierarchy without skipping levels. Screen reader users often navigate by headings to understand page structure.
+    </bd-p>
+    
+    <bd-h as="h3" style="margin-bottom: 1rem;">Proper Hierarchy Example</bd-h>
+    <div style="background: #f8fafc; padding: 1.5rem; border-radius: 8px; margin-bottom: 1.5rem;">
+      <bd-p kind="regular" style="color: #334155;">
+        <strong>✅ Correct:</strong> h1 → h2 → h3 → h2 → h3 → h4<br>
+        <strong>❌ Avoid:</strong> h1 → h3 → h4 → h2 → h5
+      </bd-p>
+    </div>
     
-    <bd-h as="h3">Best Practices</bd-h>
-    <bd-p kind="regular">Each page should have one h1, followed by h2, h3, etc. in order.</bd-p>
+    <bd-h as="h3" style="margin-bottom: 1rem;">Screen Reader Navigation</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Users can jump between headings to quickly find relevant content. Proper structure makes this navigation intuitive and efficient.
+    </bd-p>
     
-    <bd-h as="h4">Screen Readers</bd-h>
-    <bd-p kind="regular">Users can navigate by headings to understand page structure quickly.</bd-p>
+    <bd-h as="h2" style="margin-bottom: 1rem;">SEO Benefits</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
+      Search engines use heading structure to understand content importance and relevance. Proper hierarchy improves search rankings.
+    </bd-p>
     
-    <bd-h as="h5">SEO Benefits</bd-h>
-    <bd-p kind="regular">Search engines use heading structure to understand content importance.</bd-p>
+    <bd-h as="h3" style="margin-bottom: 1rem;">Keyword Placement</bd-h>
+    <bd-p kind="regular">
+      Important keywords should appear in higher-level headings (h1, h2) while supporting keywords can go in lower levels (h3, h4).
+    </bd-p>
   </div>
 `;
-AccessibilityExample.parameters = {
+AccessibilityGuidelines.parameters = {
   docs: {
     description: {
-      story: 'Demonstrates proper semantic heading hierarchy for accessibility and SEO.'
+      story: 'Comprehensive guide to accessibility and SEO best practices for heading usage. Includes semantic structure requirements, screen reader considerations, and search engine optimization tips.'
     }
   }
 };
 
-export const ResponsiveExample = () => html`
+export const ResponsiveBehavior = () => html`
   <div style="max-width: 100%; padding: 2rem;">
-    <bd-h as="h1">Responsive Design</bd-h>
-    <bd-p kind="regular">This heading will adjust its size based on the viewport and CSS variables.</bd-p>
+    <bd-h as="h2" style="margin-bottom: 1rem;">Responsive Heading Behavior</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Heading components automatically adjust based on viewport size and CSS custom properties. They maintain optimal readability across all device sizes.
+    </bd-p>
     
-    <div style="display: flex; flex-wrap: wrap; gap: 2rem; margin-top: 2rem;">
-      <div style="flex: 1; min-width: 200px;">
-        <bd-h as="h3">Mobile First</bd-h>
-        <bd-p kind="small">Optimized for small screens with appropriate font sizes.</bd-p>
-      </div>
-      <div style="flex: 1; min-width: 200px;">
-        <bd-h as="h3">Tablet Ready</bd-h>
-        <bd-p kind="small">Scales perfectly for medium-sized devices.</bd-p>
-      </div>
-      <div style="flex: 1; min-width: 200px;">
-        <bd-h as="h3">Desktop Perfect</bd-h>
-        <bd-p kind="small">Looks great on large screens and monitors.</bd-p>
+    <div style="background: #f1f5f9; padding: 2rem; border-radius: 12px;">
+      <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 2rem; margin-top: 1rem;">
+        <div style="text-align: center; padding: 1.5rem; background: white; border-radius: 8px;">
+          <bd-h as="h4" style="color: #3b82f6; margin-bottom: 1rem;">Mobile View</bd-h>
+          <bd-h as="h3" style="color: #1e293b; margin-bottom: 1rem;">Optimized for Small Screens</bd-h>
+          <bd-p kind="small" style="color: #64748b;">
+            Compact yet readable on mobile devices with appropriate font sizes and spacing.
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center; padding: 1.5rem; background: white; border-radius: 8px;">
+          <bd-h as="h4" style="color: #3b82f6; margin-bottom: 1rem;">Tablet View</bd-h>
+          <bd-h as="h3" style="color: #1e293b; margin-bottom: 1rem;">Balanced for Medium Devices</bd-h>
+          <bd-p kind="small" style="color: #64748b;">
+            Perfect balance of size and readability for tablet screens and medium breakpoints.
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center; padding: 1.5rem; background: white; border-radius: 8px;">
+          <bd-h as="h4" style="color: #3b82f6; margin-bottom: 1rem;">Desktop View</bd-h>
+          <bd-h as="h3" style="color: #1e293b; margin-bottom: 1rem;">Maximum Impact on Large Screens</bd-h>
+          <bd-p kind="small" style="color: #64748b;">
+            Full visual impact and hierarchy on desktop displays and large viewports.
+          </bd-p>
+        </div>
       </div>
     </div>
   </div>
 `;
-ResponsiveExample.parameters = {
+ResponsiveBehavior.parameters = {
   docs: {
     description: {
-      story: 'Shows how headings work in responsive layouts and different screen sizes.'
+      story: 'Demonstrates how heading typography adapts responsively across different screen sizes while maintaining visual hierarchy, readability, and design consistency through CSS variables and responsive design principles.'
     }
   }
 };
 
-export const InteractiveExample = () => {
-  const headings = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
-
-  return html`
-    <div style="max-width: 800px; margin: 0 auto;">
-      <bd-h as="h2">Interactive Heading Demo</bd-h>
-      <bd-p kind="regular">Select different heading levels to see how they look:</bd-p>
-      
-      ${headings.map(kind => html`
-        <div style="margin: 2rem 0; padding: 1rem; border-left: 4px solid #3b82f6;">
-          <bd-h as="${kind}">This is a ${kind.toUpperCase()} heading</bd-h>
-          <bd-p kind="small" style="margin-top: 0.5rem;">
-            Font size: var(--typography-heading-${kind}-fontSize)<br>
-            Font weight: var(--typography-heading-${kind}-fontWeight)
-          </bd-p>
-        </div>
-      `)}
-    </div>
-  `;
+export const InteractivePlayground = Template.bind({});
+InteractivePlayground.args = {
+  as     : 'h2',
+  content: 'Customize This Heading',
+  color  : '',
+  align  : 'left'
 };
-InteractiveExample.parameters = {
+InteractivePlayground.parameters = {
   docs: {
     description: {
-      story: 'Interactive demonstration showing all heading levels with their CSS variable values.'
+      story: 'Interactive playground where you can test all heading properties in real-time. Use the controls panel to modify the heading level, color, alignment, and content to see immediate results.'
     }
   }
 };