@repobit/dex-system-design 0.22.12 → 0.23.2

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

@@ -1,502 +1,193 @@
 import { html } from 'lit';
-import '../paragraph/paragraph.js';
 import './heading.js';
 
 export default {
-  title    : 'Atoms/Heading',
-  component: 'bd-h',
-  tags     : ['autodocs'],
-  argTypes : {
+  title     : 'Components/Heading',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdH** is a Lit heading component that renders semantic HTML heading elements (h1–h6) with configurable styling.
+
+### Usage
+\`\`\`html
+<bd-h as="h1">Page Title</bd-h>
+<bd-h as="h3" color="#026DFF" font-weight="700" padding-bottom="16px">Section Title</bd-h>
+\`\`\`
+
+### Valid Heading Tags
+\`h1\`, \`h2\`, \`h3\`, \`h4\`, \`h5\`, \`h6\` — falls back to \`h1\` for invalid values.
+
+### Style Prop Validation
+- **fontWeight**: accepts numeric strings (\`"100"\`–\`"900"\`) and keyword values (\`"normal"\`, \`"bold"\`, \`"lighter"\`, \`"bolder"\`)
+- **color**: accepts \`var(--...)\`, \`#hex\`, \`rgb(...)\`, \`hsl(...)\` — rejects bare color names
+- **padding / paddingBottom**: any valid CSS value string
+
+### Notes
+- \`ariaLevel\` can override the implicit ARIA level for accessibility
+- Styles are applied inline via \`_computeStyles()\`
+        `
+      }
+    }
+  },
+  argTypes: {
     as: {
       control    : { type: 'select' },
       options    : ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
-      description: 'Semantic HTML heading level (h1-h6)',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'h2' }
-      }
+      description: 'Which heading tag to render. Falls back to `h1` if invalid.',
+      table      : { type: { summary: "'h1'|'h2'|'h3'|'h4'|'h5'|'h6'" }, defaultValue: { summary: 'h1' }, category: 'Semantic' }
     },
-    color: {
-      control    : 'color',
-      description: 'Custom text color for the heading',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'inherit' }
-      }
+    ariaLevel: {
+      control    : 'number',
+      description: 'Overrides the implicit ARIA level (e.g. for accessibility when visual level differs from semantic level)',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'null' }, category: 'Accessibility' }
     },
-    align: {
-      control    : { type: 'select' },
-      options    : ['left', 'center', 'right'],
-      description: 'Text alignment',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'left' }
-      }
+    padding: {
+      control    : 'text',
+      description: 'CSS padding shorthand applied inline',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Spacing' }
     },
-    content: {
+    paddingBottom: {
       control    : 'text',
-      description: 'Heading text content',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'Heading Text' }
-      }
-    }
-  },
-  parameters: {
-    docs: {
-      description: {
-        component: 'A semantic heading component that provides proper HTML structure with consistent typography. Supports all heading levels from h1 to h6 with customizable styling.'
-      }
+      description: 'CSS padding-bottom applied inline',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Spacing' }
+    },
+    fontWeight: {
+      control    : { type: 'select' },
+      options    : ['', '100', '200', '300', '400', '500', '600', '700', '800', '900', 'normal', 'bold', 'lighter', 'bolder'],
+      description: 'Font weight applied inline. Invalid values are ignored.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Typography' }
+    },
+    color: {
+      control    : 'color',
+      description: 'Text color. Must be a hex, rgb, hsl, or var() value.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Typography' }
     }
   }
 };
 
-const Template = ({ as, color, align, content }) => html`
-  <bd-h 
-    as="${as}" 
-    style="${color ? `color: ${color};` : ''} ${align ? `text-align: ${align};` : ''}"
+const render = (args) => html`
+  <bd-h
+    as="${args.as}"
+    padding="${args.padding}"
+    paddingBottom="${args.paddingBottom}"
+    fontWeight="${args.fontWeight}"
+    color="${args.color}"
   >
-    ${content}
+    Sample Heading Text
   </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>
-`;
-AllHeadingLevels.parameters = {
-  docs: {
-    description: {
-      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 = {
-  as     : 'h1',
-  content: 'Main Page Title (H1)',
-  color  : '',
-  align  : 'left'
-};
-Heading1.parameters = {
-  docs: {
-    description: {
-      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 = {
-  as     : 'h2',
-  content: 'Section Title (H2)',
-  color  : '',
-  align  : 'left'
-};
-Heading2.parameters = {
-  docs: {
-    description: {
-      story: 'Secondary heading level (h2) - Perfect for major content sections and primary division titles within a page.'
-    }
-  }
-};
-
-export const Heading3 = Template.bind({});
-Heading3.args = {
-  as     : 'h3',
-  content: 'Subsection Title (H3)',
-  color  : '',
-  align  : 'left'
-};
-Heading3.parameters = {
-  docs: {
-    description: {
-      story: 'Tertiary heading level (h3) - Ideal for subsection titles, feature headings, and card headers within h2 sections.'
-    }
-  }
-};
-
-export const Heading4 = Template.bind({});
-Heading4.args = {
-  as     : 'h4',
-  content: 'Content Heading (H4)',
-  color  : '',
-  align  : 'left'
-};
-Heading4.parameters = {
-  docs: {
-    description: {
-      story: 'Content heading level (h4) - Suitable for smaller content sections, widget titles, and detailed information headings.'
-    }
-  }
-};
-
-export const Heading5 = Template.bind({});
-Heading5.args = {
-  as     : 'h5',
-  content: 'Minor Heading (H5)',
-  color  : '',
-  align  : 'left'
-};
-Heading5.parameters = {
-  docs: {
-    description: {
-      story: 'Minor heading level (h5) - Use for sidebar sections, footer headings, and less important content labels.'
-    }
-  }
-};
-
-export const Heading6 = Template.bind({});
-Heading6.args = {
-  as     : 'h6',
-  content: 'Smallest Heading (H6)',
-  color  : '',
-  align  : 'left'
-};
-Heading6.parameters = {
-  docs: {
-    description: {
-      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 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>
-    
-    <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>
+const defaultArgs = { as: 'h2', padding: '', paddingBottom: '', fontWeight: '', color: '' };
 
-    <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.'
-    }
-  }
-};
+// ─── Stories ───────────────────────────────────────────────────────────────
 
-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="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="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="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>
-`;
-ContentHierarchy.parameters = {
-  docs: {
-    description: {
-      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 Default = {
+  name      : 'Default (h1)',
+  render    : () => html`<bd-h as="h1">Page Title</bd-h>`,
+  parameters: { docs: { description: { story: 'Default `h1` heading with no inline styles.' } } }
 };
 
-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>
+export const AllLevels = {
+  name  : 'All Heading Levels',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:8px;">
+      <bd-h as="h1">Heading 1</bd-h>
+      <bd-h as="h2">Heading 2</bd-h>
+      <bd-h as="h3">Heading 3</bd-h>
+      <bd-h as="h4">Heading 4</bd-h>
+      <bd-h as="h5">Heading 5</bd-h>
+      <bd-h as="h6">Heading 6</bd-h>
     </div>
-    
-    <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>
+  `,
+  parameters: { docs: { description: { story: 'All six heading levels rendered for typographic scale comparison.' } } }
+};
+
+export const CustomColor = {
+  name  : 'Custom Color',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:12px;">
+      <bd-h as="h2" color="#026DFF">Blue Heading</bd-h>
+      <bd-h as="h2" color="#E53935">Red Heading</bd-h>
+      <bd-h as="h2" color="#43A047">Green Heading</bd-h>
+      <bd-h as="h2" color="var(--color-neutral-1000)">Token Color</bd-h>
     </div>
-    
-    <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>
+  `,
+  parameters: { docs: { description: { story: 'Headings with hex colors and a CSS variable token. Bare color names like "blue" are rejected by `_getValidColor()`.' } } }
+};
+
+export const FontWeights = {
+  name  : 'Font Weights',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:8px;">
+      <bd-h as="h3" fontWeight="300">Light (300)</bd-h>
+      <bd-h as="h3" fontWeight="400">Regular (400)</bd-h>
+      <bd-h as="h3" fontWeight="600">Semibold (600)</bd-h>
+      <bd-h as="h3" fontWeight="700">Bold (700)</bd-h>
+      <bd-h as="h3" fontWeight="800">Extrabold (800)</bd-h>
+      <bd-h as="h3" fontWeight="900">Black (900)</bd-h>
     </div>
-  </div>
-`;
-CardLayoutExample.parameters = {
-  docs: {
-    description: {
-      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.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Various font weights from light (300) to black (900). Invalid weights like "purple" are silently ignored.' } } }
 };
 
-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" 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>
+export const CustomPadding = {
+  name  : 'Custom Padding',
+  render: () => html`
+    <div style="outline:1px solid #eee; display:inline-block;">
+      <bd-h as="h3" padding="24px 40px">With Full Padding</bd-h>
     </div>
-    
-    <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="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="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>
-`;
-AccessibilityGuidelines.parameters = {
-  docs: {
-    description: {
-      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 ResponsiveBehavior = () => html`
-  <div style="max-width: 100%; padding: 2rem;">
-    <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="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 style="outline:1px solid #eee; display:inline-block; margin-top:16px;">
+      <bd-h as="h3" paddingBottom="32px">With Padding Bottom Only</bd-h>
     </div>
-  </div>
-`;
-ResponsiveBehavior.parameters = {
-  docs: {
-    description: {
-      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 InteractivePlayground = Template.bind({});
-InteractivePlayground.args = {
-  as     : 'h2',
-  content: 'Customize This Heading',
-  color  : '',
-  align  : 'left'
-};
-InteractivePlayground.parameters = {
-  docs: {
-    description: {
-      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.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Demonstrates `padding` shorthand and `paddingBottom` applied inline.' } } }
+};
+
+export const AriaLevelOverride = {
+  name  : 'ARIA Level Override',
+  render: () => html`
+    <p style="font-size:14px; margin-bottom:8px;">
+      Visually renders as <code>h4</code> but has <code>aria-level="2"</code>.
+    </p>
+    <bd-h as="h4" aria-level="2" color="#026DFF">
+      Visually h4, semantically level 2
+    </bd-h>
+  `,
+  parameters: { docs: { description: { story: '`ariaLevel` overrides the implicit ARIA heading level for accessibility without changing the visual rendering.' } } }
+};
+
+export const InvalidTag = {
+  name  : 'Invalid Tag (fallback to h1)',
+  render: () => html`
+    <bd-h as="div">This falls back to h1</bd-h>
+  `,
+  parameters: { docs: { description: { story: '`as="div"` is not a valid heading tag — component falls back to rendering `<h1>`.' } } }
+};
+
+export const InvalidColor = {
+  name  : 'Invalid Color (silently ignored)',
+  render: () => html`
+    <bd-h as="h3" color="blue">This uses the default color (blue is rejected)</bd-h>
+    <bd-h as="h3" color="#026DFF">This uses valid hex color</bd-h>
+  `,
+  parameters: { docs: { description: { story: 'Bare color name `"blue"` is rejected by `_getValidColor()` and falls back to the default color. `"#026DFF"` is accepted.' } } }
+};
+
+export const Combined = {
+  name  : 'Combined Props',
+  render: () => html`
+    <bd-h as="h2" color="#026DFF" fontWeight="800" paddingBottom="16px">
+      World-class security software
+    </bd-h>
+  `,
+  parameters: { docs: { description: { story: 'h2 with color, bold font weight, and bottom padding combined.' } } }
+};
+
+export const Playground = {
+  name      : '🛝 Playground',
+  args      : { ...defaultArgs },
+  render,
+  parameters: { docs: { description: { story: 'Interactive playground. Adjust `as`, `color`, `fontWeight`, `padding`, and `paddingBottom` via Controls.' } } }
 };