@repobit/dex-system-design 0.22.12 → 0.23.1

package/src/components/picture/picture.stories.js

@@ -1,620 +1,206 @@
 import { html } from 'lit';
-import '../heading/heading.js';
-import '../paragraph/paragraph.js';
 import './picture.js';
 
 export default {
-  title    : 'Atoms/Picture',
-  component: 'bd-picture',
-  tags     : ['autodocs'],
-  argTypes : {
-    sources: {
-      control    : 'object',
-      description: 'Array of source objects for responsive images with media queries and format options',
-      table      : {
-        type        : { summary: 'Array<SourceObject>' },
-        defaultValue: { summary: '[]' }
+  title     : 'Components/Picture',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdPicture** is a Lit responsive picture component that wraps \`<picture>\` with multiple \`<source>\` elements and a fallback \`<img>\`.
+
+### Usage
+\`\`\`html
+<bd-picture
+  fallback-src="/assets/product.png"
+  alt="Product screenshot"
+  width="800"
+  height="600"
+  fit="cover"
+  radius="md"
+  loading="lazy"
+  .sources="${[
+    { type: 'image/webp', srcset: '/assets/product.webp', media: '(min-width: 600px)' },
+    { type: 'image/png',  srcset: '/assets/product.png' }
+  ]}"
+></bd-picture>
+\`\`\`
+
+### Sources Array
+Each source object supports:
+- \`type\` — MIME type (e.g. \`"image/webp"\`)
+- \`srcset\` — srcset value
+- \`media\` — optional media query
+- \`sizes\` — optional sizes attribute
+
+### CSS Classes Applied
+| Prop | Class Pattern |
+|---|---|
+| \`fit\` | \`fit-{value}\` |
+| \`radius\` | \`radius-{value}\` |
+        `
       }
+    }
+  },
+  argTypes: {
+    fallbackSrc: {
+      control    : 'text',
+      description: 'Fallback `<img>` src used when no `<source>` matches',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
     alt: {
       control    : 'text',
-      description: 'Alternative text for accessibility and SEO',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '' }
-      }
+      description: 'Alt text for the fallback `<img>`',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
-    fallbackSrc: {
-      control    : 'text',
-      description: 'Fallback image source for browsers that don\'t support picture element or specific formats',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: '' }
-      }
+    sources: {
+      control    : 'object',
+      description: 'Array of source objects: `{ type, srcset, media?, sizes? }`',
+      table      : { type: { summary: 'Array<{type, srcset, media?, sizes?}>' }, defaultValue: { summary: '[]' }, category: 'Content' }
     },
     width: {
       control    : 'number',
-      description: 'Image width in pixels for layout stability',
-      table      : {
-        type        : { summary: 'number' },
-        defaultValue: { summary: 'null' }
-      }
+      description: 'Intrinsic width of the fallback image',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'null' }, category: 'Dimensions' }
     },
     height: {
       control    : 'number',
-      description: 'Image height in pixels for layout stability',
-      table      : {
-        type        : { summary: 'number' },
-        defaultValue: { summary: 'null' }
-      }
+      description: 'Intrinsic height of the fallback image',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'null' }, category: 'Dimensions' }
     },
     loading: {
       control    : { type: 'select' },
       options    : ['lazy', 'eager'],
-      description: 'Image loading strategy for performance optimization',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'lazy' }
-      }
+      description: 'Native browser loading strategy',
+      table      : { type: { summary: "'lazy'|'eager'" }, defaultValue: { summary: 'lazy' }, category: 'Performance' }
     },
     fit: {
       control    : { type: 'select' },
       options    : ['cover', 'contain', 'fill', 'none', 'scale-down'],
-      description: 'How the image should be resized to fit its container',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'cover' }
-      }
+      description: 'Object-fit class applied as `fit-{value}`',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'cover' }, category: 'Appearance' }
     },
     radius: {
       control    : { type: 'select' },
-      options    : ['none', 'sm', 'md', 'lg', 'full'],
-      description: 'Border radius for rounded corners',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'none' }
-      }
-    }
-  },
-  parameters: {
-    docs: {
-      description: {
-        component: 'A responsive picture component that supports multiple image formats, breakpoints, and modern web features. Provides optimal performance and accessibility with fallback support for older browsers.'
-      }
+      options    : ['none', 'sm', 'md', 'lg', 'xl', 'full'],
+      description: 'Border radius class applied as `radius-{value}`',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'none' }, category: 'Appearance' }
     }
   }
 };
 
-const Template = (args) => html`
+const placeholder = 'https://via.placeholder.com/800x450';
+
+const defaultSources = [
+  { type: 'image/webp', srcset: placeholder + '?format=webp', media: '(min-width: 600px)' },
+  { type: 'image/png',  srcset: placeholder }
+];
+
+const defaultArgs = {
+  fallbackSrc: placeholder, alt        : 'Product image',
+  sources    : defaultSources, width      : 800, height     : 450,
+  loading    : 'lazy', fit        : 'cover', radius     : 'none'
+};
+
+const render = (args) => html`
   <bd-picture
-    .sources="${args.sources}"
-    alt="${args.alt}"
     fallback-src="${args.fallbackSrc}"
+    alt="${args.alt}"
     width="${args.width}"
     height="${args.height}"
     loading="${args.loading}"
     fit="${args.fit}"
     radius="${args.radius}"
+    .sources="${args.sources}"
   ></bd-picture>
 `;
 
-// ============ STORIES ============
-
-export const Default = Template.bind({});
-Default.args = {
-  sources: [
-    {
-      type  : 'image/webp',
-      srcset: '/assets/bd-header-us-2000.webp',
-      media : '(min-width: 1200px)'
-    },
-    {
-      type  : 'image/webp',
-      srcset: '/assets/bd-header-us-1000.webp',
-      media : '(min-width: 768px)'
-    },
-    {
-      type  : 'image/webp',
-      srcset: '/assets/bd-header-us-750.webp'
-    }
-  ],
-  alt        : 'Bitdefender Security Illustration showing comprehensive protection features',
-  fallbackSrc: '/assets/bd-header-us.jpg',
-  width      : 750,
-  height     : 500,
-  loading    : 'lazy',
-  fit        : 'cover',
-  radius     : 'none'
-};
-Default.parameters = {
-  docs: {
-    description: {
-      story: 'Default picture component with responsive WebP sources and JPEG fallback. Optimized for performance with lazy loading and proper aspect ratio.'
-    }
-  }
-};
-
-export const AllSourceTypes = () => html`
-  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 1000px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Picture Source Types and Strategies</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      The picture element supports multiple image formats and responsive breakpoints for optimal performance and visual quality across different devices and browsers.
-    </bd-p>
-    
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">WebP with JPEG Fallback</bd-h>
-      <bd-picture
-        .sources="${[
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-2000.webp',
-            media : '(min-width: 1200px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-1000.webp',
-            media : '(min-width: 768px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-750.webp'
-          },
-          {
-            type  : 'image/jpeg',
-            srcset: '/assets/bd-header-us-2000.jpg',
-            media : '(min-width: 1200px)'
-          },
-          {
-            type  : 'image/jpeg',
-            srcset: '/assets/bd-header-us-1000.jpg',
-            media : '(min-width: 768px)'
-          }
-        ]}"
-        alt="Bitdefender Security with WebP and JPEG fallback support"
-        fallback-src="/assets/bd-header-us.jpg"
-        width="800"
-        height="500"
-        loading="lazy"
-        fit="cover"
-        radius="md"
-      ></bd-picture>
-      <bd-p kind="regular" style="margin-top: 1.5rem;">
-        <strong>Strategy:</strong> Modern WebP format for supported browsers with JPEG fallback for compatibility<br>
-        <strong>Benefits:</strong> Better compression + wide browser support<br>
-        <strong>Use case:</strong> Production websites requiring optimal performance
-      </bd-p>
-      <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-        💡 <strong>Best practice:</strong> Always provide JPEG fallback for maximum browser compatibility
-      </bd-p>
-    </div>
-
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Multiple Breakpoint Strategy</bd-h>
-      <bd-picture
-        .sources="${[
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-2000.webp',
-            media : '(min-width: 1440px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-1200.webp',
-            media : '(min-width: 1024px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-800.webp',
-            media : '(min-width: 768px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-600.webp',
-            media : '(min-width: 480px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-400.webp'
-          }
-        ]}"
-        alt="Bitdefender Security optimized for multiple screen sizes"
-        fallback-src="/assets/bd-header-us.jpg"
-        width="800"
-        height="500"
-        loading="lazy"
-        fit="cover"
-        radius="md"
-      ></bd-picture>
-      <bd-p kind="regular" style="margin-top: 1.5rem;">
-        <strong>Breakpoints:</strong> 1440px+ (desktop), 1024px+ (laptop), 768px+ (tablet), 480px+ (large mobile), default (mobile)<br>
-        <strong>Benefits:</strong> Optimal image size for each device, faster loading<br>
-        <strong>Use case:</strong> High-traffic websites with diverse device usage
-      </bd-p>
-      <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-        📱 <strong>Performance:</strong> Mobile users download smaller images, improving page speed
-      </bd-p>
-    </div>
-
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Single Source Simplicity</bd-h>
-      <bd-picture
-        .sources="${[
-          {
-            type  : 'image/jpeg',
-            srcset: '/assets/bd-header-us.jpg'
-          }
-        ]}"
-        alt="Simple Bitdefender Security image implementation"
-        fallback-src="/assets/bd-header-us.jpg"
-        width="600"
-        height="400"
-        loading="lazy"
-        fit="cover"
-        radius="lg"
-      ></bd-picture>
-      <bd-p kind="regular" style="margin-top: 1.5rem;">
-        <strong>Strategy:</strong> Single image source without responsive variants<br>
-        <strong>Benefits:</strong> Simpler implementation, fewer image files to manage<br>
-        <strong>Use case:</strong> Internal applications, prototypes, simple websites
-      </bd-p>
-      <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-        ⚡ <strong>Quick setup:</strong> Perfect for MVPs and projects with limited image requirements
-      </bd-p>
-    </div>
-  </div>
-`;
-AllSourceTypes.parameters = {
-  docs: {
-    description: {
-      story: 'Comprehensive demonstration of different picture source strategies including WebP with JPEG fallback, multiple breakpoint optimization, and simple single-source implementations with detailed use case recommendations.'
-    }
-  }
-};
+// ─── Stories ───────────────────────────────────────────────────────────────
 
-export const SimplePicture = Template.bind({});
-SimplePicture.args = {
-  sources: [
-    {
-      type  : 'image/jpeg',
-      srcset: '/assets/bd-header-us.jpg'
-    }
-  ],
-  alt        : 'Simple Bitdefender Security Image showing protection interface',
-  fallbackSrc: '/assets/bd-header-us.jpg',
-  width      : 600,
-  height     : 400,
-  loading    : 'eager',
-  fit        : 'cover',
-  radius     : 'none'
-};
-SimplePicture.parameters = {
-  docs: {
-    description: {
-      story: 'Simple picture implementation with single JPEG source. Ideal for prototypes, internal applications, or situations where multiple image formats and breakpoints are not required.'
-    }
-  }
+export const Default = {
+  name  : 'Default',
+  render: () => html`
+    <bd-picture fallback-src="${placeholder}" alt="Product image" width="800" height="450" .sources="${defaultSources}"></bd-picture>
+  `,
+  parameters: { docs: { description: { story: 'Default picture with WebP and PNG sources and a PNG fallback.' } } }
 };
 
-export const AdvancedResponsive = Template.bind({});
-AdvancedResponsive.args = {
-  sources: [
-    {
-      type  : 'image/avif',
-      srcset: '/assets/bd-header-us-2000.avif',
-      media : '(min-width: 1440px)'
-    },
-    {
-      type  : 'image/webp',
-      srcset: '/assets/bd-header-us-1200.webp',
-      media : '(min-width: 1024px)'
-    },
-    {
-      type  : 'image/webp',
-      srcset: '/assets/bd-header-us-800.webp',
-      media : '(min-width: 768px)'
-    },
-    {
-      type  : 'image/webp',
-      srcset: '/assets/bd-header-us-400.webp'
-    }
-  ],
-  alt        : 'Advanced Bitdefender Security with AVIF and WebP formats',
-  fallbackSrc: '/assets/bd-header-us.jpg',
-  width      : 800,
-  height     : 500,
-  loading    : 'lazy',
-  fit        : 'cover',
-  radius     : 'md'
-};
-AdvancedResponsive.parameters = {
-  docs: {
-    description: {
-      story: 'Advanced responsive picture with AVIF format for modern browsers, WebP for broader support, and multiple breakpoints for optimal performance across all device types.'
-    }
-  }
+export const NoSources = {
+  name  : 'No Sources (fallback only)',
+  render: () => html`
+    <bd-picture fallback-src="${placeholder}" alt="Fallback only" width="600" height="400" .sources="${[]}"></bd-picture>
+  `,
+  parameters: { docs: { description: { story: 'Empty `sources` array — only the fallback `<img>` is used.' } } }
 };
 
-export const ObjectFitOptions = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 1000px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Object Fit Property Examples</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      The object-fit property controls how the image content is resized to fit its container. Choose the appropriate option based on your layout requirements.
-    </bd-p>
-    
-    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem;">
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Cover</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
-          <bd-picture
-            .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-            alt="Cover fit example"
-            fallback-src="/assets/bd-header-us.jpg"
-            width="250"
-            height="200"
-            fit="cover"
-          ></bd-picture>
-        </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Hero images, profile pictures<br>
-          <strong>Behavior:</strong> Fills container, may crop edges
-        </bd-p>
-      </div>
-      
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Contain</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden; background: #f8fafc;">
-          <bd-picture
-            .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-            alt="Contain fit example"
-            fallback-src="/assets/bd-header-us.jpg"
-            width="250"
-            height="200"
-            fit="contain"
-          ></bd-picture>
+export const WithRadius = {
+  name  : 'Radius Variants',
+  render: () => html`
+    <div style="display:flex; gap:16px; flex-wrap:wrap;">
+      ${['none', 'sm', 'md', 'lg', 'full'].map(r => html`
+        <div>
+          <p style="font-size:12px; margin-bottom:4px;">radius-${r}</p>
+          <bd-picture fallback-src="${placeholder}" alt="radius ${r}" width="180" height="180" radius="${r}" fit="cover" .sources="${[]}"></bd-picture>
         </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Product images, logos<br>
-          <strong>Behavior:</strong> Fits entirely, may have empty space
-        </bd-p>
-      </div>
-      
-      <div style="text-align: center;">
-        <bd-h as="h4" style="margin-bottom: 1rem;">Fill</bd-h>
-        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
-          <bd-picture
-            .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-            alt="Fill fit example"
-            fallback-src="/assets/bd-header-us.jpg"
-            width="250"
-            height="200"
-            fit="fill"
-          ></bd-picture>
-        </div>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          <strong>Use case:</strong> Background patterns<br>
-          <strong>Behavior:</strong> Stretches to fill, may distort
-        </bd-p>
-      </div>
+      `)}
     </div>
-  </div>
-`;
-ObjectFitOptions.parameters = {
-  docs: {
-    description: {
-      story: 'Demonstration of different object-fit properties (cover, contain, fill) with visual examples and recommendations for when to use each option based on layout requirements and image content.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Five radius values applied to equal-dimension images.' } } }
 };
 
-export const LoadingStrategies = () => 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;">Loading Strategy Comparison</bd-h>
-    
-    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(350px, 1fr)); gap: 2rem;">
-      <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
-        <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Lazy Loading</bd-h>
-        <bd-picture
-          .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-          alt="Lazy loaded security image"
-          fallback-src="/assets/bd-header-us.jpg"
-          width="300"
-          height="200"
-          loading="lazy"
-          fit="cover"
-          radius="md"
-        ></bd-picture>
-        <bd-p kind="regular" style="margin-top: 1.5rem;">
-          <strong>When to use:</strong> Images below the fold, gallery items, non-critical content<br>
-          <strong>Performance:</strong> Improves initial page load time<br>
-          <strong>User experience:</strong> Images load as user scrolls near them
-        </bd-p>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          ✅ <strong>Best practice:</strong> Use for all non-essential images
-        </bd-p>
-      </div>
-      
-      <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
-        <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Eager Loading</bd-h>
-        <bd-picture
-          .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-          alt="Eager loaded security image"
-          fallback-src="/assets/bd-header-us.jpg"
-          width="300"
-          height="200"
-          loading="eager"
-          fit="cover"
-          radius="md"
-        ></bd-picture>
-        <bd-p kind="regular" style="margin-top: 1.5rem;">
-          <strong>When to use:</strong> Hero images, above-the-fold content, LCP elements<br>
-          <strong>Performance:</strong> Loads immediately, may impact initial load<br>
-          <strong>User experience:</strong> Critical images ready when page renders
-        </bd-p>
-        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-          ⚠️ <strong>Use sparingly:</strong> Only for images essential to initial rendering
-        </bd-p>
-      </div>
+export const FitVariants = {
+  name  : 'Fit Variants',
+  render: () => html`
+    <div style="display:flex; gap:16px; flex-wrap:wrap;">
+      ${['cover', 'contain', 'fill', 'none'].map(fit => html`
+        <div>
+          <p style="font-size:12px; margin-bottom:4px;">${fit}</p>
+          <bd-picture fallback-src="${placeholder}" alt="${fit}" width="200" height="150" fit="${fit}" .sources="${[]}"></bd-picture>
+        </div>
+      `)}
     </div>
-  </div>
-`;
-LoadingStrategies.parameters = {
-  docs: {
-    description: {
-      story: 'Comparison of lazy vs eager loading strategies with performance implications and guidelines for when to use each approach based on image importance and position in the page layout.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Fit variants: cover, contain, fill, none.' } } }
 };
 
-export const AccessibilityExamples = () => 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;">Accessibility Best Practices</bd-h>
-    
-    <div style="border: 2px solid #10b981; padding: 2rem; border-radius: 12px; background: #f0fdf4;">
-      <bd-h as="h3" style="color: #059669; margin-bottom: 1rem;">✅ Good Alt Text Examples</bd-h>
-      
-      <bd-picture
-        .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-        alt="Bitdefender security software dashboard showing real-time threat protection, firewall status, and privacy tools with green status indicators"
-        fallback-src="/assets/bd-header-us.jpg"
-        width="600"
-        height="400"
-        loading="lazy"
-        fit="cover"
-        radius="md"
-      ></bd-picture>
-      
-      <bd-p kind="regular" style="margin-top: 1.5rem;">
-        <strong>Descriptive:</strong> Clearly describes the image content and context<br>
-        <strong>Concise:</strong> Meaningful but not overly verbose<br>
-        <strong>Relevant:</strong> Relates to the surrounding content and purpose
-      </bd-p>
-      <bd-p kind="small" style="color: #059669; margin-top: 1rem;">
-        ✅ Screen readers will provide meaningful context about the image content
-      </bd-p>
-    </div>
-    
-    <div style="border: 2px solid #ef4444; padding: 2rem; border-radius: 12px; background: #fef2f2;">
-      <bd-h as="h3" style="color: #dc2626; margin-bottom: 1rem;">❌ Poor Alt Text Examples</bd-h>
-      
-      <bd-picture
-        .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-        alt="image123.jpg"
-        fallback-src="/assets/bd-header-us.jpg"
-        width="600"
-        height="400"
-        loading="lazy"
-        fit="cover"
-        radius="md"
-      ></bd-picture>
-      
-      <bd-p kind="regular" style="margin-top: 1.5rem;">
-        <strong>Avoid:</strong> File names, placeholder text, or generic descriptions<br>
-        <strong>Don't:</strong> Start with "image of" or "picture of"<br>
-        <strong>Never:</strong> Leave alt text empty for meaningful images
-      </bd-p>
-      <bd-p kind="small" style="color: #dc2626; margin-top: 1rem;">
-        ❌ Screen readers will announce meaningless file names to users
-      </bd-p>
-    </div>
-    
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
-      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Decorative Images</bd-h>
-      <bd-p kind="regular" style="margin-bottom: 1.5rem;">
-        For purely decorative images that don't convey meaningful content, use empty alt text to prevent screen readers from announcing them.
-      </bd-p>
-      <bd-picture
-        .sources="${[{ type: 'image/jpeg', srcset: '/assets/bd-header-us.jpg' }]}"
-        alt=""
-        fallback-src="/assets/bd-header-us.jpg"
-        width="400"
-        height="200"
-        loading="lazy"
-        fit="cover"
-        radius="md"
-      ></bd-picture>
-      <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
-        ✅ Empty alt attribute: <code>alt=""</code> - Screen readers will skip this image entirely
-      </bd-p>
-    </div>
-  </div>
-`;
-AccessibilityExamples.parameters = {
-  docs: {
-    description: {
-      story: 'Accessibility guidelines and examples showing proper alt text usage, common mistakes to avoid, and how to handle decorative images. Essential for creating inclusive experiences for screen reader users.'
-    }
-  }
+export const ResponsiveSources = {
+  name  : 'Responsive Sources (media queries)',
+  render: () => html`
+    <bd-picture
+      fallback-src="${placeholder}"
+      alt="Responsive product image"
+      width="800" height="450"
+      .sources="${[
+        { type: 'image/webp', srcset: placeholder + '?w=800', media: '(min-width: 600px)' },
+        { type: 'image/webp', srcset: placeholder + '?w=400', media: '' },
+        { type: 'image/png',  srcset: placeholder }
+      ]}"
+    ></bd-picture>
+  `,
+  parameters: { docs: { description: { story: 'Three sources: large WebP for desktop, small WebP for mobile, PNG fallback.' } } }
 };
 
-export const HeaderImageExample = () => html`
-  <div style="max-width: 1000px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 2rem; text-align: center;">Bitdefender Ultimate Security</bd-h>
-    
-    <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 3rem; border-radius: 12px; color: white;">
-      <bd-picture
-        .sources="${[
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-2000.webp',
-            media : '(min-width: 1200px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-1000.webp',
-            media : '(min-width: 768px)'
-          },
-          {
-            type  : 'image/webp',
-            srcset: '/assets/bd-header-us-750.webp'
-          }
-        ]}"
-        alt="Bitdefender Security Suite dashboard showing comprehensive protection features including antivirus, firewall, and privacy tools"
-        fallback-src="/assets/bd-header-us.jpg"
-        width="800"
-        height="400"
-        loading="eager"
-        fit="cover"
-        radius="lg"
-      ></bd-picture>
-      
-      <div style="margin-top: 2rem; text-align: center;">
-        <bd-h as="h3" style="color: white; margin-bottom: 1rem;">Complete Digital Protection</bd-h>
-        <bd-p kind="lead" style="color: white; opacity: 0.9;">
-          Enterprise-grade security solutions for home and business users. 
-          Real-time threat detection, advanced firewall, and privacy protection in one package.
-        </bd-p>
+export const LazyVsEager = {
+  name  : 'Lazy vs Eager Loading',
+  render: () => html`
+    <div style="display:flex; gap:16px; flex-wrap:wrap;">
+      <div>
+        <p style="font-size:12px; margin-bottom:4px;">loading="lazy"</p>
+        <bd-picture fallback-src="${placeholder}" alt="Lazy" width="300" height="200" loading="lazy" .sources="${[]}"></bd-picture>
+      </div>
+      <div>
+        <p style="font-size:12px; margin-bottom:4px;">loading="eager"</p>
+        <bd-picture fallback-src="${placeholder}" alt="Eager" width="300" height="200" loading="eager" .sources="${[]}"></bd-picture>
       </div>
     </div>
-  </div>
-`;
-HeaderImageExample.parameters = {
-  docs: {
-    description: {
-      story: 'Real-world example of a hero section using the picture component with responsive images, eager loading for above-the-fold content, and proper accessibility attributes in a marketing context.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Comparison of `loading="lazy"` and `loading="eager"` side by side.' } } }
 };
 
-export const InteractivePlayground = Template.bind({});
-InteractivePlayground.args = {
-  sources: [
-    {
-      type  : 'image/jpeg',
-      srcset: '/assets/bd-header-us.jpg'
-    }
-  ],
-  alt        : 'Customizable picture component example',
-  fallbackSrc: '/assets/bd-header-us.jpg',
-  width      : 400,
-  height     : 300,
-  loading    : 'lazy',
-  fit        : 'cover',
-  radius     : 'none'
-};
-InteractivePlayground.parameters = {
-  docs: {
-    description: {
-      story: 'Interactive playground where you can test all picture properties in real-time. Use the controls panel to modify the image sources, dimensions, loading strategy, fit behavior, and styling options.'
-    }
-  }
+export const Playground = {
+  name      : '🛝 Playground',
+  args      : { ...defaultArgs },
+  render,
+  parameters: { docs: { description: { story: 'Interactive playground. Adjust all props via Controls.' } } }
 };