@repobit/dex-system-design 0.21.2 → 0.22.0

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

@@ -1,41 +1,85 @@
 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'
+      description: 'Array of source objects for responsive images with media queries and format options',
+      table      : {
+        type        : { summary: 'Array<SourceObject>' },
+        defaultValue: { summary: '[]' }
+      }
     },
     alt: {
       control    : 'text',
-      description: 'Alt text for accessibility'
+      description: 'Alternative text for accessibility and SEO',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '' }
+      }
     },
     fallbackSrc: {
       control    : 'text',
-      description: 'Fallback image source for older browsers'
+      description: 'Fallback image source for browsers that don\'t support picture element or specific formats',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '' }
+      }
     },
     width: {
       control    : 'number',
-      description: 'Image width attribute'
+      description: 'Image width in pixels for layout stability',
+      table      : {
+        type        : { summary: 'number' },
+        defaultValue: { summary: 'null' }
+      }
     },
     height: {
       control    : 'number',
-      description: 'Image height attribute'
+      description: 'Image height in pixels for layout stability',
+      table      : {
+        type        : { summary: 'number' },
+        defaultValue: { summary: 'null' }
+      }
     },
     loading: {
       control    : { type: 'select' },
       options    : ['lazy', 'eager'],
-      description: 'Image loading strategy'
+      description: 'Image loading strategy for performance optimization',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'lazy' }
+      }
+    },
+    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' }
+      }
+    },
+    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 and breakpoints.'
+        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.'
       }
     }
   }
@@ -49,9 +93,13 @@ const Template = (args) => html`
     width="${args.width}"
     height="${args.height}"
     loading="${args.loading}"
+    fit="${args.fit}"
+    radius="${args.radius}"
   ></bd-picture>
 `;
 
+// ============ STORIES ============
+
 export const Default = Template.bind({});
 Default.args = {
   sources: [
@@ -70,11 +118,157 @@ Default.args = {
       srcset: '/assets/bd-header-us-750.webp'
     }
   ],
-  alt        : 'Bitdefender Security Illustration',
+  alt        : 'Bitdefender Security Illustration showing comprehensive protection features',
   fallbackSrc: '/assets/bd-header-us.jpg',
   width      : 750,
   height     : 500,
-  loading    : 'lazy'
+  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.'
+    }
+  }
 };
 
 export const SimplePicture = Template.bind({});
@@ -85,191 +279,342 @@ SimplePicture.args = {
       srcset: '/assets/bd-header-us.jpg'
     }
   ],
-  alt        : 'Simple Bitdefender Security Image',
+  alt        : 'Simple Bitdefender Security Image showing protection interface',
   fallbackSrc: '/assets/bd-header-us.jpg',
-  width      : 750,
-  height     : 500,
-  loading    : 'eager'
+  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 WebPWithJPEGFallback = () => html`
-  <div style="max-width: 800px; margin: 0 auto;">
-    <bd-h as="h4">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"
-      fallback-src="/assets/bd-header-us.jpg"
-      width="750"
-      height="500"
-      loading="eager"
-    ></bd-picture>
-    <p style="margin-top: 1rem; font-size: 0.875rem; color: #666;">
-      Modern WebP format with JPEG fallback for maximum browser compatibility.
-    </p>
-  </div>
-`;
+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 DifferentBreakpoints = () => html`
-  <div style="max-width: 1000px; margin: 0 auto;">
-    <bd-h as="h4">Multiple Breakpoints</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 with multiple breakpoints"
-      fallback-src="/assets/bd-header-us.jpg"
-      width="750"
-      height="500"
-    ></bd-picture>
-    <p style="margin-top: 1rem; font-size: 0.875rem; color: #666;">
-      This image loads different sizes at: 1440px+, 1024px+, 768px+, 480px+, and mobile.
-    </p>
+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>
+        </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.'
+    }
+  }
+};
 
-export const HeaderImageExample = () => html`
-  <div style="background: #f8fafc; padding: 2rem; border-radius: 8px; border: 1px solid #e2e8f0;">
-    <bd-h as="h4">Header Image Example</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'
-        }
-      ]}"
-      alt="Bitdefender Security Header Illustration"
-      fallback-src="/assets/bd-header-us.jpg"
-      width="800"
-      height="400"
-      loading="eager"
-    ></bd-picture>
-    <div style="margin-top: 1rem; padding: 1rem; background: white; border-radius: 4px;">
-      <bd-h as="h4" style="margin: 0 0 0.5rem 0;">Bitdefender Ultimate Security</bd-h>
-      <p style="margin: 0; color: #666;">Complete protection for your digital life</p>
+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>
     </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.'
+    }
+  }
+};
 
-export const SingleSourceExample = () => html`
-  <div style="max-width: 600px; margin: 0 auto;">
-    <bd-h as="h4">Single Source Picture</bd-h>
-    <bd-picture
-      .sources="${[
-        {
-          type  : 'image/jpeg',
-          srcset: '/assets/bd-header-us.jpg'
-        }
-      ]}"
-      alt="Simple Bitdefender Security Image"
-      fallback-src="/assets/bd-header-us.jpg"
-      width="600"
-      height="400"
-      loading="lazy"
-    ></bd-picture>
-    <p style="margin-top: 1rem; font-size: 0.875rem; color: #666;">
-      Simple picture with single JPEG source - perfect when you don't need multiple formats.
-    </p>
+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 WithFixedDimensions = () => html`
-  <div>
-    <bd-h as="h4">Fixed Dimensions</bd-h>
-    <bd-picture
-      .sources="${[
-        {
-          type  : 'image/jpeg',
-          srcset: '/assets/bd-header-us.jpg'
-        }
-      ]}"
-      alt="Bitdefender Security with fixed dimensions"
-      fallback-src="/assets/bd-header-us.jpg"
-      width="400"
-      height="300"
-      loading="lazy"
-    ></bd-picture>
-    <p style="margin-top: 1rem; font-size: 0.875rem; color: #666;">
-      Fixed 400x300 dimensions prevent layout shifts during loading.
-    </p>
+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>
+      </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.'
+    }
+  }
+};
 
-export const AccessibilityExample = () => html`
-  <div style="max-width: 600px; margin: 0 auto;">
-    <bd-h as="h4">Accessible Picture</bd-h>
-    <bd-picture
-      .sources="${[
-        {
-          type  : 'image/jpeg',
-          srcset: '/assets/bd-header-us.jpg'
-        }
-      ]}"
-      alt="Bitdefender Security Suite showing advanced protection features including real-time scanning, firewall protection, and privacy tools for comprehensive digital security"
-      fallback-src="/assets/bd-header-us.jpg"
-      width="600"
-      height="400"
-      loading="lazy"
-    ></bd-picture>
-    <p style="margin-top: 1rem; font-size: 0.875rem; color: #666;">
-      Always provide meaningful alt text for screen readers and SEO.
-    </p>
-  </div>
-`;
+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.'
+    }
+  }
+};