@etus/ui 0.1.0

package/src/components/primitives/Image/README.md

@@ -0,0 +1,863 @@
+# Image
+
+## Visão Geral
+
+O **Image** é o componente fundamental para exibição de imagens no Design System ETUS, oferecendo suporte a lazy loading, fallback, aspect ratio e otimização de performance. Como elemento atômico, serve de base para composições mais complexas como `Avatar`, `Thumbnail`, `Gallery` e `MediaCard`.
+
+### Casos de Uso
+
+- Exibição de fotos de produtos e conteúdo
+- Thumbnails em listas e grids
+- Imagens de perfil e avatares
+- Banners e hero images
+- Galerias de imagens
+- Placeholders durante carregamento
+
+### Classificação
+
+**Categoria:** Atom (Primitive)
+**Dependências:** Nenhuma (componente nativo)
+**Status:** ✅ Implementado
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Imagem padrão sem bordas | Sem estilos adicionais |
+| `rounded` | Cantos arredondados | `rounded-md` |
+| `circle` | Imagem circular | `rounded-full` |
+| `square` | Proporção 1:1 forçada | `aspect-square` |
+
+### Tamanhos (`size`)
+
+| Tamanho | Dimensões | Uso |
+|---------|-----------|-----|
+| `xs` | `size-8` (32px) | Ícones, avatares mínimos |
+| `sm` | `size-12` (48px) | Thumbnails compactos |
+| `md` | `size-16` (64px) | Uso geral |
+| `lg` | `size-24` (96px) | Previews maiores |
+| `xl` | `size-32` (128px) | Destaque, hero |
+| `full` | `w-full` | Responsivo, ocupa container |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Loading | `animate-pulse bg-muted` | Placeholder pulsante |
+| Loaded | - | Imagem visível |
+| Error | Fallback renderizado | Placeholder ou ícone de erro |
+| Lazy | `loading="lazy"` | Carrega quando entra no viewport |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--muted             /* Background do placeholder */
+--muted-foreground  /* Ícone de fallback */
+--border            /* Borda opcional */
+
+/* Espaçamento */
+--radius            /* Border radius padrão */
+
+/* Transições */
+transition-opacity  /* Fade-in ao carregar */
+duration-300        /* 300ms de animação */
+```
+
+### data-slot
+
+```html
+<img data-slot="image" />
+<div data-slot="image-fallback">...</div>
+<div data-slot="image-skeleton">...</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `src` | `string` | - | URL da imagem |
+| `alt` | `string` | `""` | Texto alternativo (obrigatório para a11y) |
+| `variant` | `"default" \| "rounded" \| "circle" \| "square"` | `"default"` | Estilo visual |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | `"full"` | Tamanho predefinido |
+| `fallback` | `ReactNode` | - | Conteúdo exibido em caso de erro |
+| `placeholder` | `ReactNode` | - | Conteúdo durante carregamento |
+| `loading` | `"lazy" \| "eager"` | `"lazy"` | Estratégia de carregamento |
+| `aspectRatio` | `"auto" \| "square" \| "video" \| "portrait" \| number` | `"auto"` | Proporção da imagem |
+| `objectFit` | `"cover" \| "contain" \| "fill" \| "none"` | `"cover"` | Como a imagem preenche o container |
+| `objectPosition` | `string` | `"center"` | Posição da imagem no container |
+| `className` | `string` | - | Classes CSS adicionais |
+| `onLoad` | `() => void` | - | Callback quando imagem carrega |
+| `onError` | `() => void` | - | Callback quando ocorre erro |
+| `ref` | `Ref<HTMLImageElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"img">`
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onLoad` | `(event: SyntheticEvent) => void` | Disparado quando imagem carrega |
+| `onError` | `(event: SyntheticEvent) => void` | Disparado quando ocorre erro |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Variants exportadas
+const imageVariants = cva(/* ... */)
+
+// Props do componente
+type ImageProps = React.ComponentProps<"img"> &
+  VariantProps<typeof imageVariants> & {
+    fallback?: ReactNode
+    placeholder?: ReactNode
+    aspectRatio?: "auto" | "square" | "video" | "portrait" | number
+    objectFit?: "cover" | "contain" | "fill" | "none"
+  }
+
+// Tipos derivados úteis
+type ImageVariant = NonNullable<VariantProps<typeof imageVariants>["variant"]>
+type ImageSize = NonNullable<VariantProps<typeof imageVariants>["size"]>
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Spectrum | PrimeReact |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:--------:|:----------:|
+| **Variantes** | ✅ 4 | - | - | - | - | - | - | 4 | - | - | - | - | - | - |
+| **Tamanhos** | ✅ 6 | - | - | - | - | - | - | 5 | - | - | - | - | - | - |
+| **CVA/cva** | ✅ | - | - | - | - | - | - | * | - | - | - | - | - | - |
+| **Lazy loading** | ✅ | - | - | * | - | * | * | * | - | - | - | - | - | * |
+| **Fallback** | ✅ | - | - | * | - | * | * | * | - | - | * | - | - | * |
+| **Placeholder** | ✅ | - | - | * | - | * | * | * | - | - | - | - | - | * |
+| **Aspect Ratio** | ✅ | * | * | - | - | * | - | - | - | - | - | - | - | - |
+| **Skeleton** | ✅ | - | - | * | * | * | * | * | - | - | * | * | * | * |
+| **Blur placeholder** | - | - | - | - | - | * | - | * | - | - | - | - | - | - |
+| **Zoom/Preview** | - | - | - | - | - | - | * | * | - | - | - | - | - | * |
+| **Responsive srcSet** | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **data-slot** | ✅ | * | - | - | - | - | - | * | - | - | - | - | - | - |
+
+**Legenda:** ✅ = Implementado no ETUS | * = Disponível | - = Não disponível
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Next/Image |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:----------:|
+| `src` | ✅ | * | * | * | * | * | * |
+| `alt` | ✅ | * | * | * | * | * | * |
+| `fallback` | ✅ | `fallbackSrc` | - | `withPlaceholder` | `fallback` | `fallbackSrc` | - |
+| `loading` | ✅ | `loading` | `loading` | - | `loading` | `loading` | `loading` |
+| `placeholder` | ✅ | - | - | `placeholder` | `placeholder` | - | `placeholder` |
+| `aspectRatio` | ✅ | - | - | - | - | - | - |
+| `objectFit` | ✅ | `objectFit` | - | `fit` | - | - | `objectFit` |
+| `objectPosition` | ✅ | `objectPosition` | - | - | - | - | `objectPosition` |
+| `width` | ✅ | * | * | `w` | `width` | `width` | * |
+| `height` | ✅ | * | * | `h` | `height` | `height` | * |
+| `fill` | - | - | - | - | - | - | * |
+| `priority` | - | - | - | - | - | - | * |
+| `blur` | - | - | - | - | - | `isBlurred` | `blurDataURL` |
+| `preview` | - | - | - | - | * | - | - |
+| `srcSet` | - | - | - | - | - | - | auto |
+| `sizes` | - | - | - | - | - | - | * |
+| `onLoad` | ✅ | `onLoad` | `onLoad` | `onLoad` | `onLoad` | `onLoad` | `onLoad` |
+| `onError` | ✅ | `onError` | `onError` | `onError` | `onError` | `onError` | `onError` |
+
+#### Análise por Categoria
+
+**Frameworks com Image Nativo Otimizado:**
+- **Next.js Image** - Otimização automática, blur placeholder, srcSet automático
+- **Gatsby Image** - GraphQL-based, blur-up, art direction
+- **Astro Image** - Build-time optimization, zero JS
+
+**Design Systems com Componente Image:**
+- **Chakra UI** - `fallbackSrc`, `loading`, style props
+- **Mantine** - `withPlaceholder`, `placeholder`, `fit`
+- **Ant Design** - `preview`, `fallback`, `placeholder`
+- **NextUI** - `isBlurred`, `fallbackSrc`, `disableSkeleton`
+- **PrimeReact** - `preview`, `imageStyle`, templates
+
+**Design Systems sem Componente Image Dedicado:**
+- **Shadcn/ui** - Usa AspectRatio + img nativo
+- **MUI** - Usa Avatar ou Box + img
+- **Radix** - Apenas AspectRatio como wrapper
+- **Fluent UI** - Image básico, foco em Avatar
+- **Carbon** - Sem componente dedicado
+
+**Abordagem Recomendada para ETUS:**
+- Combinar simplicidade do Shadcn com features do Chakra/Mantine
+- Suporte a lazy loading nativo
+- Fallback e placeholder flexíveis
+- Integração com AspectRatio existente
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `alt` | Texto alternativo descritivo (obrigatório) |
+| `role="img"` | Implícito no elemento `<img>` |
+| `role="presentation"` | Para imagens decorativas com `alt=""` |
+| `aria-hidden="true"` | Alternativa para imagens decorativas |
+| `aria-describedby` | Referência a descrição longa |
+
+### Imagens Decorativas vs Informativas
+
+```tsx
+// Imagem informativa - alt descritivo obrigatório
+<Image
+  src="/product.jpg"
+  alt="Camiseta azul com logo da marca no peito"
+/>
+
+// Imagem decorativa - alt vazio
+<Image
+  src="/divider.svg"
+  alt=""
+  aria-hidden="true"
+/>
+
+// Imagem com descrição longa
+<Image
+  src="/chart.png"
+  alt="Gráfico de vendas Q4 2024"
+  aria-describedby="chart-description"
+/>
+<p id="chart-description">
+  O gráfico mostra crescimento de 25% nas vendas...
+</p>
+```
+
+### Focus Management
+
+```tsx
+// Imagens clicáveis devem ser focáveis
+<button type="button" aria-label="Ampliar imagem do produto">
+  <Image src="/product.jpg" alt="Produto XYZ" />
+</button>
+
+// Ou usando link
+<a href="/produto/123" aria-label="Ver detalhes do produto">
+  <Image src="/product.jpg" alt="Produto XYZ" />
+</a>
+```
+
+### Contraste e Visibilidade
+
+| Cenário | Recomendação |
+|---------|--------------|
+| Texto sobre imagem | Overlay escuro + texto claro ou vice-versa |
+| Placeholder/Skeleton | Contraste suficiente com fundo |
+| Fallback icon | Ícone com contraste mínimo 3:1 |
+| Borda de foco | Visível em qualquer background |
+
+### Screen Readers
+
+- Sempre fornecer `alt` descritivo para imagens informativas
+- Usar `alt=""` para imagens puramente decorativas
+- Evitar textos como "Imagem de..." - descreva o conteúdo
+- Fornecer contexto adicional via `aria-describedby` quando necessário
+- Anunciar estado de carregamento para imagens importantes
+
+### Reduced Motion
+
+```css
+/* Desabilitar animações de fade-in */
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="image"] {
+    transition: none;
+  }
+
+  [data-slot="image-skeleton"] {
+    animation: none;
+  }
+}
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Spectrum | Next/Image |
+|---------|:----:|:----------:|:-----:|:-------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:--------:|:----------:|
+| **alt obrigatório** | ✅ | - | - | - | - | - | - | - | - | - | - | * | * |
+| **role="presentation"** | ✅ | - | - | - | * | - | - | - | * | - | - | * | - |
+| **aria-describedby** | ✅ | - | - | - | - | - | - | - | - | - | - | * | - |
+| **Reduced motion** | ✅ | * | - | - | * | * | * | - | * | * | * | * | - |
+| **Loading announcement** | - | - | - | - | - | - | - | - | - | * | - | * | - |
+| **Error announcement** | - | - | - | - | - | - | - | - | - | * | - | * | - |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Image } from "@etus/ui"
+
+function Example() {
+  return (
+    <Image
+      src="/photo.jpg"
+      alt="Descrição da imagem"
+    />
+  )
+}
+```
+
+### Variantes
+
+```tsx
+<Image variant="default" src="/photo.jpg" alt="Padrão" />
+<Image variant="rounded" src="/photo.jpg" alt="Arredondada" />
+<Image variant="circle" src="/photo.jpg" alt="Circular" />
+<Image variant="square" src="/photo.jpg" alt="Quadrada" />
+```
+
+### Tamanhos
+
+```tsx
+<Image size="xs" src="/avatar.jpg" alt="Avatar XS" />
+<Image size="sm" src="/avatar.jpg" alt="Avatar SM" />
+<Image size="md" src="/avatar.jpg" alt="Avatar MD" />
+<Image size="lg" src="/avatar.jpg" alt="Avatar LG" />
+<Image size="xl" src="/avatar.jpg" alt="Avatar XL" />
+<Image size="full" src="/banner.jpg" alt="Banner Full" />
+```
+
+### Com Fallback
+
+```tsx
+import { ImageOff } from "lucide-react"
+
+// Fallback com ícone
+<Image
+  src="/photo.jpg"
+  alt="Foto do produto"
+  fallback={
+    <div className="flex items-center justify-center bg-muted">
+      <ImageOff className="size-6 text-muted-foreground" />
+    </div>
+  }
+/>
+
+// Fallback com imagem alternativa
+<Image
+  src="/photo.jpg"
+  alt="Foto do produto"
+  fallback={<img src="/placeholder.svg" alt="" />}
+/>
+```
+
+### Com Placeholder/Skeleton
+
+```tsx
+// Skeleton durante carregamento
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  placeholder={
+    <div className="animate-pulse bg-muted size-full" />
+  }
+/>
+
+// Blur placeholder (requer base64)
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  placeholder={
+    <img
+      src="data:image/jpeg;base64,..."
+      alt=""
+      className="blur-lg scale-110"
+    />
+  }
+/>
+```
+
+### Lazy Loading
+
+```tsx
+// Lazy loading (padrão)
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  loading="lazy"
+/>
+
+// Eager loading (above the fold)
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  loading="eager"
+/>
+```
+
+### Aspect Ratio
+
+```tsx
+// Proporção quadrada
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  aspectRatio="square"
+/>
+
+// Proporção de vídeo (16:9)
+<Image
+  src="/thumbnail.jpg"
+  alt="Thumbnail"
+  aspectRatio="video"
+/>
+
+// Proporção customizada
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  aspectRatio={4/3}
+/>
+```
+
+### Object Fit
+
+```tsx
+// Cover (padrão) - preenche o container, corta se necessário
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  objectFit="cover"
+  className="size-48"
+/>
+
+// Contain - mostra imagem inteira, pode ter espaços
+<Image
+  src="/logo.png"
+  alt="Logo"
+  objectFit="contain"
+  className="size-48"
+/>
+
+// Com posicionamento
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  objectFit="cover"
+  objectPosition="top"
+/>
+```
+
+### Callbacks
+
+```tsx
+function Example() {
+  const [isLoaded, setIsLoaded] = useState(false)
+  const [hasError, setHasError] = useState(false)
+
+  return (
+    <Image
+      src="/photo.jpg"
+      alt="Foto"
+      onLoad={() => setIsLoaded(true)}
+      onError={() => setHasError(true)}
+      className={cn(
+        "transition-opacity",
+        isLoaded ? "opacity-100" : "opacity-0"
+      )}
+    />
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo via className
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  className="size-24 md:size-32 lg:size-48"
+/>
+
+// Full width responsivo
+<Image
+  src="/banner.jpg"
+  alt="Banner"
+  size="full"
+  aspectRatio="video"
+/>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <Image
+    src="/photo.jpg"
+    alt="Foto"
+    className="@sm:size-24 @md:size-32 @lg:size-48"
+  />
+</div>
+```
+
+### Composição com Gallery
+
+```tsx
+function Gallery({ images }: { images: string[] }) {
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-3 gap-4">
+      {images.map((src, index) => (
+        <Image
+          key={src}
+          src={src}
+          alt={`Imagem ${index + 1} da galeria`}
+          variant="rounded"
+          aspectRatio="square"
+          objectFit="cover"
+          loading="lazy"
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+### Imagem Decorativa
+
+```tsx
+// Imagem puramente decorativa - sem alt
+<Image
+  src="/decoration.svg"
+  alt=""
+  aria-hidden="true"
+/>
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Image.test.tsx
+import { render, screen, waitFor } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+import { Image } from "./Image"
+
+describe("Image", () => {
+  it("renders with src and alt", () => {
+    render(<Image src="/test.jpg" alt="Test image" />)
+    const img = screen.getByRole("img", { name: "Test image" })
+    expect(img).toBeInTheDocument()
+    expect(img).toHaveAttribute("src", "/test.jpg")
+  })
+
+  it("applies variant classes", () => {
+    render(<Image src="/test.jpg" alt="Test" variant="rounded" />)
+    expect(screen.getByRole("img")).toHaveClass("rounded-md")
+  })
+
+  it("applies size classes", () => {
+    render(<Image src="/test.jpg" alt="Test" size="lg" />)
+    expect(screen.getByRole("img")).toHaveClass("size-24")
+  })
+
+  it("merges custom className", () => {
+    render(<Image src="/test.jpg" alt="Test" className="custom-class" />)
+    expect(screen.getByRole("img")).toHaveClass("custom-class")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Image src="/test.jpg" alt="Test" />)
+    expect(screen.getByRole("img")).toHaveAttribute("data-slot", "image")
+  })
+
+  it("sets loading attribute", () => {
+    render(<Image src="/test.jpg" alt="Test" loading="lazy" />)
+    expect(screen.getByRole("img")).toHaveAttribute("loading", "lazy")
+  })
+})
+```
+
+### Testes de Carregamento
+
+```tsx
+describe("Image loading", () => {
+  it("calls onLoad when image loads", async () => {
+    const handleLoad = vi.fn()
+    render(<Image src="/test.jpg" alt="Test" onLoad={handleLoad} />)
+
+    const img = screen.getByRole("img")
+    fireEvent.load(img)
+
+    expect(handleLoad).toHaveBeenCalledTimes(1)
+  })
+
+  it("calls onError when image fails to load", async () => {
+    const handleError = vi.fn()
+    render(<Image src="/invalid.jpg" alt="Test" onError={handleError} />)
+
+    const img = screen.getByRole("img")
+    fireEvent.error(img)
+
+    expect(handleError).toHaveBeenCalledTimes(1)
+  })
+
+  it("shows fallback on error", async () => {
+    render(
+      <Image
+        src="/invalid.jpg"
+        alt="Test"
+        fallback={<div data-testid="fallback">Error</div>}
+      />
+    )
+
+    const img = screen.getByRole("img")
+    fireEvent.error(img)
+
+    expect(screen.getByTestId("fallback")).toBeInTheDocument()
+  })
+
+  it("shows placeholder while loading", () => {
+    render(
+      <Image
+        src="/test.jpg"
+        alt="Test"
+        placeholder={<div data-testid="placeholder">Loading</div>}
+      />
+    )
+
+    expect(screen.getByTestId("placeholder")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Image accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Image src="/test.jpg" alt="Descriptive alt text" />
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("decorative image has empty alt", async () => {
+    const { container } = render(
+      <Image src="/decorative.svg" alt="" aria-hidden="true" />
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("requires alt attribute", () => {
+    // TypeScript should enforce alt prop
+    // @ts-expect-error - alt is required
+    render(<Image src="/test.jpg" />)
+  })
+})
+```
+
+### Testes de Aspect Ratio
+
+```tsx
+describe("Image aspect ratio", () => {
+  it("applies square aspect ratio", () => {
+    render(<Image src="/test.jpg" alt="Test" aspectRatio="square" />)
+    expect(screen.getByRole("img")).toHaveClass("aspect-square")
+  })
+
+  it("applies video aspect ratio", () => {
+    render(<Image src="/test.jpg" alt="Test" aspectRatio="video" />)
+    expect(screen.getByRole("img")).toHaveClass("aspect-video")
+  })
+
+  it("applies custom aspect ratio", () => {
+    render(<Image src="/test.jpg" alt="Test" aspectRatio={4/3} />)
+    expect(screen.getByRole("img")).toHaveStyle({ aspectRatio: "1.333" })
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Image edge cases", () => {
+  it("handles missing src gracefully", () => {
+    const handleError = vi.fn()
+    render(
+      <Image
+        src=""
+        alt="Empty src"
+        onError={handleError}
+        fallback={<div data-testid="fallback">No image</div>}
+      />
+    )
+
+    const img = screen.getByRole("img")
+    fireEvent.error(img)
+
+    expect(screen.getByTestId("fallback")).toBeInTheDocument()
+  })
+
+  it("handles src change", async () => {
+    const { rerender } = render(
+      <Image src="/first.jpg" alt="First" />
+    )
+
+    expect(screen.getByRole("img")).toHaveAttribute("src", "/first.jpg")
+
+    rerender(<Image src="/second.jpg" alt="Second" />)
+
+    expect(screen.getByRole("img")).toHaveAttribute("src", "/second.jpg")
+  })
+
+  it("forwards ref to img element", () => {
+    const ref = { current: null }
+    render(<Image src="/test.jpg" alt="Test" ref={ref} />)
+    expect(ref.current).toBeInstanceOf(HTMLImageElement)
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, segue o status de implementação:
+
+### ✅ Implementado (Prioridade Alta)
+
+#### Implementação Base
+
+```tsx
+// API implementada
+interface ImageProps {
+  src: string
+  alt: string
+  variant?: "default" | "rounded" | "circle" | "square"
+  size?: "xs" | "sm" | "md" | "lg" | "xl" | "full"
+  loading?: "lazy" | "eager"
+  fallback?: ReactNode
+  placeholder?: ReactNode
+  aspectRatio?: "auto" | "square" | "video" | "portrait" | number
+  objectFit?: "cover" | "contain" | "fill" | "none"
+  objectPosition?: string
+  onLoad?: () => void
+  onError?: () => void
+}
+```
+
+#### ✅ Lazy Loading Nativo
+
+```tsx
+// Implementado com atributo nativo
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  loading="lazy"
+/>
+```
+
+### ✅ Implementado (Prioridade Média)
+
+#### ✅ Aspect Ratio Integrado
+
+```tsx
+// Proporções predefinidas - IMPLEMENTADO
+<Image aspectRatio="square" />    // 1:1
+<Image aspectRatio="video" />     // 16:9
+<Image aspectRatio="portrait" />  // 3:4
+<Image aspectRatio={4/3} />       // Custom
+```
+
+### Pendente (Prioridade Média)
+
+#### Blur Placeholder
+
+```tsx
+// Placeholder com blur durante carregamento
+<Image
+  src="/photo.jpg"
+  alt="Foto"
+  blurDataURL="data:image/jpeg;base64,..."
+  placeholder="blur"
+/>
+```
+
+**Referências:** Next/Image, NextUI, Mantine
+**Status:** Não implementado - requer infra para gerar base64
+
+### ❌ Não Planejado (Prioridade Baixa)
+
+#### Preview/Zoom
+
+Recomendação: **Evitar** - Complexo, usar lib dedicada se necessário
+
+#### Responsive srcSet
+
+Recomendação: **Evitar** - Framework-specific, usar Next/Image em projetos Next.js
+
+### Resumo de Decisões
+
+| Feature | Status | Justificativa |
+|---------|--------|---------------|
+| Base (src, alt, loading) | ✅ Implementado | Fundamento do componente |
+| Fallback/Placeholder | ✅ Implementado | Essencial para UX |
+| Aspect Ratio | ✅ Implementado | Comum em UIs, CVA friendly |
+| objectFit/Position | ✅ Implementado | Controle de layout |
+| Blur placeholder | ⏳ Pendente | Requer infra para gerar base64 |
+| Preview/Zoom | ❌ Não planejado | Complexo, usar lib dedicada |
+| srcSet automático | ❌ Não planejado | Framework-specific |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação Image | GitHub |
+|---------------|-------------------|--------|
+| **Chakra UI** | [Image](https://chakra-ui.com/docs/components/image) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Mantine** | [Image](https://mantine.dev/core/image/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Image](https://ant.design/components/image) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Image](https://nextui.org/docs/components/image) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **PrimeReact** | [Image](https://primereact.org/image/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+| **Fluent UI** | [Image](https://react.fluentui.dev/?path=/docs/components-image--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Next.js** | [next/image](https://nextjs.org/docs/app/api-reference/components/image) | [vercel/next.js](https://github.com/vercel/next.js) |
+| **Radix UI** | [AspectRatio](https://www.radix-ui.com/primitives/docs/components/aspect-ratio) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **Shadcn/ui** | [Aspect Ratio](https://ui.shadcn.com/docs/components/aspect-ratio) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+
+### Especificações e Padrões
+
+- [MDN - img Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)
+- [HTML Spec - Images](https://html.spec.whatwg.org/multipage/images.html)
+- [WCAG - Images Tutorial](https://www.w3.org/WAI/tutorials/images/)
+- [WebAIM - Alternative Text](https://webaim.org/techniques/alttext/)
+- [web.dev - Lazy Loading](https://web.dev/browser-level-image-lazy-loading/)
+- [web.dev - Responsive Images](https://web.dev/responsive-images/)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)