Fix inconsistent image scaling, caption alignment, and dark mode compatibility

[MaheepTulsian]

Feature Request: Optimized Image Component for Documentation

Problem Statement

The current documentation suffers from critical image rendering issues that degrade user experience:

1. Inconsistent Scaling

• Large screenshots render at native resolution, consuming the entire viewport
• Disrupts reading flow and increases cognitive load
• No automatic sizing based on content context

Example A	Example B

2. Caption Inconsistencies

• Raw HTML implementation causes alignment and spacing issues
• No standardized styling across documentation

Example A	Example B

3. Dark Mode Incompatibility

• Light backgrounds make text unreadable in dark mode
• No theme-aware rendering

Example A	Example B

---

Proposed Solution

Introduce OptimizedImage - a centralized, reusable component that standardizes image rendering across all documentation.

Core Features

Intelligent Auto-Sizing

• Dynamically calculates optimal dimensions from natural width/height
• Enforces max-width and max-height constraints automatically

Consistent Layout

• Semantic <figure> and <figcaption> elements
• Uniform alignment and spacing without manual HTML

Dark Mode Support

• Leverages Docusaurus theme variables (--ifm-color-emphasis-*)
• Theme-aware caption styling

Flexible Configuration

• Optional props: width, maxWidth, align, aspectRatio
• Sensible defaults for 90% of use cases

Performance Optimized

• Lazy loading enabled
• Prevents unnecessary upscaling of small images

Usage Example

<OptimizedImage 
  src="/img/screenshot.png" 
  alt="alt-text"
  caption="Image overview"
  width="400px"
  maxWidth="800px"
  minWidth="200px"
  align="center"
  aspectRatio="16/9"
/>

---

Alternatives Considered

Approach	Verdict
Inline styles per image	❌ High duplication, maintenance burden
Global CSS overrides	❌ Doesn't handle dimensions, captions, or context
Manual image resizing	❌ Not scalable, doesn't fix dark mode

Conclusion: A reusable component provides maximum leverage with minimal long-term cost.

---

Visual Comparison

Before	After

---

Status

Are you working on this? ✅ Yes