@repobit/dex-system-design 0.21.1 → 0.22.0

package/src/components/image/image.stories.js

@@ -1,42 +1,86 @@
 import { html } from 'lit';
 import '../heading/heading.js';
+import '../paragraph/paragraph.js';
 import './image.js';
 
 export default {
   title    : 'Atoms/Image',
   component: 'bd-img',
+  tags     : ['autodocs'],
   argTypes : {
     src: {
       control    : 'text',
-      description: 'Image source URL'
+      description: 'Image source URL or path',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '' }
+      }
     },
     alt: {
       control    : 'text',
-      description: 'Alt text for accessibility'
+      description: 'Alternative text for accessibility and SEO',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '' }
+      }
     },
     width: {
       control    : 'number',
-      description: 'Image width'
+      description: 'Image width in pixels',
+      table      : {
+        type        : { summary: 'number' },
+        defaultValue: { summary: 'auto' }
+      }
     },
     height: {
       control    : 'number',
-      description: 'Image height'
+      description: 'Image height in pixels',
+      table      : {
+        type        : { summary: 'number' },
+        defaultValue: { summary: 'auto' }
+      }
     },
     loading: {
       control    : { type: 'select' },
       options    : ['lazy', 'eager'],
-      description: 'Loading strategy'
+      description: 'Image loading strategy',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'lazy' }
+      }
     },
     fit: {
       control    : { type: 'select' },
       options    : ['cover', 'contain', 'fill', 'none', 'scale-down'],
-      description: 'Object fit property'
+      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' }
+      }
+    },
+    shadow: {
+      control    : { type: 'select' },
+      options    : ['none', 'sm', 'md', 'lg'],
+      description: 'Box shadow for depth effect',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'none' }
+      }
     }
   },
   parameters: {
     docs: {
       description: {
-        component: 'A simple image component with enhanced styling and event handling.'
+        component: 'An enhanced image component with built-in styling options, loading strategies, and accessibility features. Provides consistent image handling across the application with performance optimizations.'
       }
     }
   }
@@ -50,196 +94,538 @@ const Template = (args) => html`
     height="${args.height}"
     loading="${args.loading}"
     fit="${args.fit}"
+    radius="${args.radius}"
+    shadow="${args.shadow}"
   ></bd-img>
 `;
 
+// ============ STORIES ============
+
 export const Default = Template.bind({});
 Default.args = {
   src    : '/assets/bd-header-us.jpg',
   alt    : 'Bitdefender Security Illustration',
-  width  : 750,
-  height : 500,
+  width  : 400,
+  height : 250,
   loading: 'lazy',
-  fit    : 'cover'
+  fit    : 'cover',
+  radius : 'none',
+  shadow : 'none'
 };
-
-export const HeaderImageExample = Template.bind({});
-HeaderImageExample.args = {
-  src    : '/assets/bd-header-us.jpg',
-  alt    : 'Bitdefender Ultimate Security Header',
-  width  : 750,
-  height : 500,
-  loading: 'eager',
-  fit    : 'cover'
+Default.parameters = {
+  docs: {
+    description: {
+      story: 'Default image component with standard configuration. Uses lazy loading and cover fit for optimal performance and appearance.'
+    }
+  }
 };
 
-export const ObjectFitExamples = () => html`
-  <div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 2rem; max-width: 800px;">
-    <div>
-      <bd-h as="h4">Cover</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Cover fit example"
-        width="200"
-        height="200"
-        fit="cover"
-      ></bd-img>
-      <p style="font-size: 0.875rem; color: #666; margin-top: 0.5rem;">
-        Fills container, may crop - perfect for headers
-      </p>
-    </div>
-    
-    <div>
-      <bd-h as="h4">Contain</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Contain fit example"
-        width="200"
-        height="200"
-        fit="contain"
-      ></bd-img>
-      <p style="font-size: 0.875rem; color: #666; margin-top: 0.5rem;">
-        Fits entirely, may have empty space
-      </p>
-    </div>
+export const AllObjectFitOptions = () => html`
+  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 900px; 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 defines how an image should be resized to fit its container. Each option has specific use cases and behaviors.
+    </bd-p>
     
-    <div>
-      <bd-h as="h4">Fill</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Fill fit example"
-        width="200"
-        height="200"
-        fit="fill"
-      ></bd-img>
-      <p style="font-size: 0.875rem; color: #666; margin-top: 0.5rem;">
-        Stretches to fill container - may distort
-      </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-img
+            src="/assets/bd-header-us.jpg"
+            alt="Cover fit example"
+            width="250"
+            height="200"
+            fit="cover"
+          ></bd-img>
+        </div>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          <strong>Use case:</strong> Hero images, profile pictures<br>
+          <strong>Behavior:</strong> Fills entire container, may crop edges<br>
+          <strong>Best for:</strong> Maintaining aspect ratio while filling space
+        </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-img
+            src="/assets/bd-header-us.jpg"
+            alt="Contain fit example"
+            width="250"
+            height="200"
+            fit="contain"
+          ></bd-img>
+        </div>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          <strong>Use case:</strong> Product images, logos<br>
+          <strong>Behavior:</strong> Fits entirely within container, may have empty space<br>
+          <strong>Best for:</strong> Showing complete image without cropping
+        </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-img
+            src="/assets/bd-header-us.jpg"
+            alt="Fill fit example"
+            width="250"
+            height="200"
+            fit="fill"
+          ></bd-img>
+        </div>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          <strong>Use case:</strong> Background patterns, decorative images<br>
+          <strong>Behavior:</strong> Stretches to fill container, may distort<br>
+          <strong>Best for:</strong> When aspect ratio preservation isn't important
+        </bd-p>
+      </div>
+      
+      <div style="text-align: center;">
+        <bd-h as="h4" style="margin-bottom: 1rem;">None</bd-h>
+        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="None fit example"
+            width="250"
+            height="200"
+            fit="none"
+          ></bd-img>
+        </div>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          <strong>Use case:</strong> Icons, small graphics<br>
+          <strong>Behavior:</strong> Original size, may overflow container<br>
+          <strong>Best for:</strong> When you need the original image dimensions
+        </bd-p>
+      </div>
+      
+      <div style="text-align: center;">
+        <bd-h as="h4" style="margin-bottom: 1rem;">Scale Down</bd-h>
+        <div style="width: 250px; height: 200px; margin: 0 auto; border: 2px solid #e2e8f0; border-radius: 8px; overflow: hidden; background: #f8fafc;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Scale down fit example"
+            width="250"
+            height="200"
+            fit="scale-down"
+          ></bd-img>
+        </div>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          <strong>Use case:</strong> Responsive images, variable content<br>
+          <strong>Behavior:</strong> Like contain, but never scales up<br>
+          <strong>Best for:</strong> Preventing pixelation on large containers
+        </bd-p>
+      </div>
     </div>
+  </div>
+`;
+AllObjectFitOptions.parameters = {
+  docs: {
+    description: {
+      story: 'Comprehensive demonstration of all object-fit property options with detailed explanations of when to use each option and their specific behaviors in different layout scenarios.'
+    }
+  }
+};
+
+export const LoadingStrategies = () => html`
+  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h2" style="margin-bottom: 1rem;">Image Loading Strategies</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Choose the right loading strategy based on image importance and position on the page to optimize performance and user experience.
+    </bd-p>
     
-    <div>
-      <bd-h as="h4">Scale Down</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Scale down fit example"
-        width="200"
-        height="200"
-        fit="scale-down"
-      ></bd-img>
-      <p style="font-size: 0.875rem; color: #666; margin-top: 0.5rem;">
-        Like contain, but never scales up
-      </p>
+    <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-img
+          src="/assets/bd-header-us.jpg"
+          alt="Lazy loaded security image"
+          width="300"
+          height="200"
+          loading="lazy"
+          fit="cover"
+          radius="md"
+        ></bd-img>
+        <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 page load time by deferring off-screen images<br>
+          <strong>User experience:</strong> Smooth scrolling with images loading as needed
+        </bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          💡 <strong>Best practice:</strong> Use for all images that aren't immediately visible
+        </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-img
+          src="/assets/bd-header-us.jpg"
+          alt="Eager loaded security image"
+          width="300"
+          height="200"
+          loading="eager"
+          fit="cover"
+          radius="md"
+        ></bd-img>
+        <bd-p kind="regular" style="margin-top: 1.5rem;">
+          <strong>When to use:</strong> Hero images, above-the-fold content, critical visuals<br>
+          <strong>Performance:</strong> Loads immediately, may impact initial page load<br>
+          <strong>User experience:</strong> Important images are 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 page 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 page position.'
+    }
+  }
+};
 
 export const StylingVariants = () => html`
-  <div style="display: flex; flex-wrap: wrap; gap: 2rem; align-items: start;">
-    <div style="text-align: center;">
-      <bd-h as="h4">Rounded</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Rounded security image"
-        width="150"
-        height="100"
-        fit="cover"
-        class="rounded"
-      ></bd-img>
-    </div>
+  <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;">Styling and Appearance Variants</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Customize the appearance of images with border radius and shadow options to match your design system and create visual hierarchy.
+    </bd-p>
     
-    <div style="text-align: center;">
-      <bd-h as="h4">With Shadow</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Image with shadow"
-        width="150"
-        height="100"
-        fit="cover"
-        class="shadow-lg"
-      ></bd-img>
+    <div>
+      <bd-h as="h3" style="margin-bottom: 2rem; color: #3b82f6;">Border Radius Options</bd-h>
+      <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 2rem;">
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="No border radius"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="none"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>None</strong><br>
+            Square corners
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Small border radius"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="sm"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Small</strong><br>
+            Subtle rounding
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Medium border radius"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="md"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Medium</strong><br>
+            Balanced rounding
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Large border radius"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="lg"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Large</strong><br>
+            Prominent rounding
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Full border radius"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="full"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Full</strong><br>
+            Circular/oval shape
+          </bd-p>
+        </div>
+      </div>
     </div>
     
-    <div style="text-align: center;">
-      <bd-h as="h4">Bordered</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Bordered image"
-        width="150"
-        height="100"
-        fit="cover"
-        class="bordered-primary"
-      ></bd-img>
+    <div>
+      <bd-h as="h3" style="margin-bottom: 2rem; color: #3b82f6;">Shadow Options</bd-h>
+      <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 2rem;">
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="No shadow"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="md"
+            shadow="none"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>None</strong><br>
+            Flat appearance
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Small shadow"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="md"
+            shadow="sm"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Small</strong><br>
+            Subtle elevation
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Medium shadow"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="md"
+            shadow="md"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Medium</strong><br>
+            Noticeable depth
+          </bd-p>
+        </div>
+        
+        <div style="text-align: center;">
+          <bd-img
+            src="/assets/bd-header-us.jpg"
+            alt="Large shadow"
+            width="150"
+            height="100"
+            fit="cover"
+            radius="md"
+            shadow="lg"
+          ></bd-img>
+          <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+            <strong>Large</strong><br>
+            Prominent elevation
+          </bd-p>
+        </div>
+      </div>
     </div>
   </div>
 `;
+StylingVariants.parameters = {
+  docs: {
+    description: {
+      story: 'Comprehensive showcase of styling options including border radius variations (none, small, medium, large, full) and shadow effects (none, small, medium, large) to create different visual appearances and depth effects.'
+    }
+  }
+};
 
-export const LoadingExamples = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 600px;">
-    <div>
-      <bd-h as="h4">Lazy Loading</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Lazy loaded security image"
-        width="400"
-        height="250"
-        loading="lazy"
-        fit="cover"
-      ></bd-img>
-      <p style="font-size: 0.875rem; color: #666; margin-top: 0.5rem;">
-        Loads when image enters viewport - better for performance
-      </p>
+export const AccessibilityExamples = () => html`
+  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h2" style="margin-bottom: 1rem;">Accessibility Best Practices</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Proper image accessibility ensures that all users, including those using screen readers, can understand and interact with your content effectively.
+    </bd-p>
+    
+    <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(350px, 1fr)); gap: 2rem;">
+      <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</bd-h>
+        <bd-img
+          src="/assets/bd-header-us.jpg"
+          alt="Bitdefender security software interface showing real-time threat protection dashboard"
+          width="300"
+          height="200"
+          fit="cover"
+          radius="md"
+        ></bd-img>
+        <bd-p kind="regular" style="margin-top: 1.5rem;">
+          <strong>Descriptive:</strong> Clearly describes the image content and context<br>
+          <strong>Concise:</strong> Brief but meaningful (125 characters or less)<br>
+          <strong>Relevant:</strong> Relates to the surrounding content
+        </bd-p>
+        <bd-p kind="small" style="color: #059669; margin-top: 1rem;">
+          ✅ Screen readers will read: "Bitdefender security software interface showing real-time threat protection dashboard"
+        </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</bd-h>
+        <bd-img
+          src="/assets/bd-header-us.jpg"
+          alt="image123.jpg"
+          width="300"
+          height="200"
+          fit="cover"
+          radius="md"
+        ></bd-img>
+        <bd-p kind="regular" style="margin-top: 1.5rem;">
+          <strong>File names:</strong> Never use file names as alt text<br>
+          <strong>Placeholders:</strong> Avoid generic text like "image" or "photo"<br>
+          <strong>Redundancy:</strong> Don't start with "image of" or "picture of"
+        </bd-p>
+        <bd-p kind="small" style="color: #dc2626; margin-top: 1rem;">
+          ❌ Screen readers will read: "image123.jpg" - meaningless to users
+        </bd-p>
+      </div>
     </div>
     
-    <div>
-      <bd-h as="h4">Eager Loading</bd-h>
+    <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-img
         src="/assets/bd-header-us.jpg"
-        alt="Eager loaded security image"
-        width="400"
-        height="250"
-        loading="eager"
+        alt=""
+        width="300"
+        height="100"
         fit="cover"
+        radius="md"
       ></bd-img>
-      <p style="font-size: 0.875rem; color: #666; margin-top: 0.5rem;">
-        Loads immediately - use for header images
-      </p>
+      <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 ResponsiveSizes = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px;">
-    <div>
-      <bd-h as="h4">Small (400px)</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Small security image"
-        width="400"
-        height="250"
-        fit="cover"
-      ></bd-img>
-    </div>
-    
-    <div>
-      <bd-h as="h4">Medium (600px)</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Medium security image"
-        width="600"
-        height="375"
-        fit="cover"
-      ></bd-img>
-    </div>
+  <div style="display: flex; flex-direction: column; gap: 3rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h2" style="margin-bottom: 1rem;">Responsive Size Examples</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Images should adapt to different screen sizes and layout requirements. Here are common size patterns for various use cases.
+    </bd-p>
     
-    <div>
-      <bd-h as="h4">Large (750px - Original)</bd-h>
-      <bd-img
-        src="/assets/bd-header-us.jpg"
-        alt="Large security image"
-        width="750"
-        height="500"
-        fit="cover"
-      ></bd-img>
+    <div style="display: flex; flex-direction: column; gap: 2rem;">
+      <div>
+        <bd-h as="h4" style="margin-bottom: 1rem;">Small (400px) - Thumbnails & Icons</bd-h>
+        <bd-img
+          src="/assets/bd-header-us.jpg"
+          alt="Small security image for thumbnails"
+          width="400"
+          height="250"
+          fit="cover"
+          radius="md"
+        ></bd-img>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          Ideal for product thumbnails, user avatars, and icon-sized images in lists and grids.
+        </bd-p>
+      </div>
+      
+      <div>
+        <bd-h as="h4" style="margin-bottom: 1rem;">Medium (600px) - Content Images</bd-h>
+        <bd-img
+          src="/assets/bd-header-us.jpg"
+          alt="Medium security image for content"
+          width="600"
+          height="375"
+          fit="cover"
+          radius="md"
+        ></bd-img>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          Perfect for blog posts, article content, and feature sections within page layouts.
+        </bd-p>
+      </div>
+      
+      <div>
+        <bd-h as="h4" style="margin-bottom: 1rem;">Large (750px) - Hero & Header Images</bd-h>
+        <bd-img
+          src="/assets/bd-header-us.jpg"
+          alt="Large security image for hero sections"
+          width="750"
+          height="500"
+          fit="cover"
+          radius="none"
+        ></bd-img>
+        <bd-p kind="small" style="color: #64748b; margin-top: 1rem;">
+          Designed for hero sections, header images, and prominent visual elements that need maximum impact.
+        </bd-p>
+      </div>
     </div>
   </div>
-`;
+`;
+ResponsiveSizes.parameters = {
+  docs: {
+    description: {
+      story: 'Common image size patterns for different use cases including thumbnails (small), content images (medium), and hero images (large) with recommendations for when to use each size category.'
+    }
+  }
+};
+
+export const HeaderImageExample = Template.bind({});
+HeaderImageExample.args = {
+  src    : '/assets/bd-header-us.jpg',
+  alt    : 'Bitdefender Ultimate Security Header - Advanced threat protection dashboard with real-time monitoring',
+  width  : 750,
+  height : 500,
+  loading: 'eager',
+  fit    : 'cover',
+  radius : 'none',
+  shadow : 'none'
+};
+HeaderImageExample.parameters = {
+  docs: {
+    description: {
+      story: 'Example of a header image configuration with eager loading (for above-the-fold content), cover fit to fill the container, and descriptive alt text for accessibility.'
+    }
+  }
+};
+
+export const InteractivePlayground = Template.bind({});
+InteractivePlayground.args = {
+  src    : '/assets/bd-header-us.jpg',
+  alt    : 'Customizable image example',
+  width  : 400,
+  height : 250,
+  loading: 'lazy',
+  fit    : 'cover',
+  radius : 'none',
+  shadow : 'none'
+};
+InteractivePlayground.parameters = {
+  docs: {
+    description: {
+      story: 'Interactive playground where you can test all image properties in real-time. Use the controls panel to modify the image source, dimensions, loading strategy, fit behavior, and styling options.'
+    }
+  }
+};