@etus/ui 0.1.0

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

@@ -0,0 +1,914 @@
+# AspectRatio
+
+## Visão Geral
+
+O **AspectRatio** e um componente primitivo do Design System ETUS que mantem uma proporcao de aspecto (aspect ratio) consistente para seu conteudo filho. Baseado no Radix UI, ele garante que elementos como imagens, videos e embeds mantenham suas proporcoes independentemente do tamanho do container.
+
+### Casos de Uso
+
+- Exibicao de imagens responsivas com proporcao fixa
+- Players de video (16:9, 4:3, 21:9)
+- Thumbnails e cards de midia
+- Embeds de mapas e iframes
+- Avatares e imagens de perfil (1:1)
+- Banners e hero images
+- Galerias de fotos com grid uniforme
+
+### Classificacao
+
+**Categoria:** Atom (Primitive)
+**Dependencias:** `@radix-ui/react-aspect-ratio`
+
+---
+
+## Design Specs
+
+### Proporcoes Comuns (Presets)
+
+O componente oferece 18 presets pre-definidos que correspondem ao Figma Design System:
+
+| Preset | Ratio | Valor | Uso |
+|--------|-------|-------|-----|
+| `square` | 1:1 | 1 | Avatares, thumbnails quadrados |
+| `landscape` | 4:3 | 1.333 | Fotos tradicionais, embeds |
+| `portrait` | 3:4 | 0.75 | Retratos verticais |
+| `video` | 16:9 | 1.778 | Videos, YouTube, banners |
+| `vertical` | 9:16 | 0.5625 | Stories, Reels, TikTok |
+| `photo` | 3:2 | 1.5 | Fotografias 35mm DSLR |
+| `photoPortrait` | 2:3 | 0.667 | Retratos, posters |
+| `display` | 16:10 | 1.6 | Laptops, monitores |
+| `displayPortrait` | 10:16 | 0.625 | Display vertical |
+| `photo5x4` | 5:4 | 1.25 | Medium format |
+| `photo4x5` | 4:5 | 0.8 | Instagram portrait |
+| `panoramic` | 2:1 | 2 | Panoramicas landscape |
+| `panoramicPortrait` | 1:2 | 0.5 | Panoramicas portrait |
+| `golden` | 1.618:1 | 1.618 | Golden ratio (φ) |
+| `goldenPortrait` | 1:1.618 | 0.618 | Golden ratio invertido |
+| `wide` | 21:9 | 2.333 | Cinema ultrawide |
+| `widePortrait` | 9:21 | 0.429 | Ultrawide vertical |
+| `ultrawide` | 32:9 | 3.556 | Super ultrawide |
+
+### Comportamento
+
+| Aspecto | Descricao |
+|---------|-----------|
+| Responsivo | Mantem proporcao em qualquer largura |
+| Overflow | Conteudo filho preenche o container |
+| Escalabilidade | Redimensiona baseado na largura do pai |
+| Object-fit | Controle via CSS no elemento filho |
+
+### Tokens Utilizados
+
+```css
+/* O AspectRatio nao aplica estilos visuais diretos */
+/* Tokens sao aplicados no conteudo filho */
+
+/* Bordas (no container pai) */
+rounded-md         /* var(--radius) */
+rounded-lg         /* Maior arredondamento */
+
+/* Overflow */
+overflow-hidden    /* Corta conteudo excedente */
+
+/* Object Fit (na imagem/video filho) */
+object-cover       /* Preenche mantendo proporcao */
+object-contain     /* Contem sem cortar */
+object-fill        /* Estica para preencher */
+```
+
+### data-slot
+
+```html
+<div data-slot="aspect-ratio">
+  <img src="..." />
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `ratio` | `number` | `1` | Proporcao de aspecto (largura/altura) |
+| `asChild` | `boolean` | `false` | Renderiza children como elemento |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteudo a ser exibido |
+| `ref` | `Ref<HTMLDivElement>` | - | Referencia ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Callbacks
+
+O AspectRatio e um componente de layout puro e nao possui callbacks especificos. Eventos podem ser adicionados ao conteudo filho:
+
+| Callback | Uso |
+|----------|-----|
+| `onLoad` | No elemento `<img>` filho para detectar carregamento |
+| `onError` | No elemento `<img>` filho para tratar erros |
+| `onClick` | No container ou filho para interatividade |
+
+### TypeScript
+
+```typescript
+import type * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio"
+
+// Props do componente
+type AspectRatioProps = React.ComponentProps<typeof AspectRatioPrimitive.Root>
+
+// Presets disponiveis
+type AspectRatioPreset =
+  | "square"           // 1:1
+  | "landscape"        // 4:3
+  | "portrait"         // 3:4
+  | "video"            // 16:9
+  | "vertical"         // 9:16
+  | "photo"            // 3:2
+  | "photoPortrait"    // 2:3
+  | "display"          // 16:10
+  | "displayPortrait"  // 10:16
+  | "photo5x4"         // 5:4
+  | "photo4x5"         // 4:5
+  | "panoramic"        // 2:1
+  | "panoramicPortrait"// 1:2
+  | "golden"           // 1.618:1
+  | "goldenPortrait"   // 1:1.618
+  | "wide"             // 21:9
+  | "widePortrait"     // 9:21
+  | "ultrawide"        // 32:9
+
+// Uso com presets
+import { aspectRatios } from "@etus/ui"
+const ratio = aspectRatios.video // 1.7778 (16/9)
+
+// Helper para calcular ratio
+import { calculateRatio } from "@etus/ui"
+const customRatio = calculateRatio(1920, 1080) // 1.7778
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:------:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| **ratio prop** | ✓ | ✓ | ✓ | - | ✓ | - | - | - | - | - | - | - | - | - | - |
+| **CSS nativo** | - | - | - | - | - | - | ✓ | - | - | - | - | - | - | - | - |
+| **asChild/Slot** | ✓ | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **maxW prop** | - | - | - | - | ✓ | - | - | - | - | - | - | - | - | - | - |
+| **Componente dedicado** | ✓ | ✓ | ✓ | - | ✓ | - | - | - | - | - | - | - | - | - | - |
+
+#### Abordagens por Design System
+
+| Design System | Abordagem | Implementacao |
+|---------------|-----------|---------------|
+| **ETUS** | Componente Radix | `<AspectRatio ratio={16/9}>` |
+| **Shadcn/ui** | Componente Radix | `<AspectRatio ratio={16/9}>` |
+| **Radix UI** | Primitivo dedicado | `<AspectRatio.Root ratio={16/9}>` |
+| **Chakra UI** | Componente Box | `<AspectRatio ratio={16/9} maxW="400px">` |
+| **MUI** | CSS via sx prop | `<Box sx={{ aspectRatio: '16/9' }}>` |
+| **Mantine** | CSS nativo | `className="aspect-video"` ou `aspectRatio` style |
+| **Tailwind** | Utility class | `className="aspect-video"` ou `aspect-[16/9]` |
+| **CSS Moderno** | Propriedade nativa | `aspect-ratio: 16 / 9` |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Shadcn | Radix | Chakra | MUI | Mantine |
+|------|:----:|:------:|:-----:|:------:|:---:|:-------:|
+| `ratio` | ✓ | ✓ | ✓ | ✓ | - | - |
+| `maxW`/`maxWidth` | - | - | - | ✓ | ✓ | ✓ |
+| `asChild` | ✓ | ✓ | ✓ | - | - | - |
+| `className` | ✓ | ✓ | ✓ | - | - | ✓ |
+| `sx` | - | - | - | - | ✓ | - |
+
+#### Analise: Componente vs CSS Nativo
+
+**Vantagens do Componente (ETUS/Shadcn/Radix):**
+- API declarativa e consistente
+- Compatibilidade cross-browser garantida
+- Integracao com sistema de componentes
+- data-slot para estilizacao externa
+
+**Vantagens do CSS Nativo (Tailwind/CSS):**
+- Zero JavaScript
+- Performance maxima
+- Suporte nativo em browsers modernos
+- Utilities como `aspect-video`, `aspect-square`
+
+> **Nota:** O CSS `aspect-ratio` tem suporte em 95%+ dos browsers modernos (Chrome 88+, Firefox 89+, Safari 15+). O componente oferece API consistente e integracao com o design system.
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+O AspectRatio e um componente de layout puro e nao requer atributos ARIA especificos. Entretanto, o conteudo filho deve seguir as diretrizes:
+
+| Elemento | Atributo | Uso |
+|----------|----------|-----|
+| `<img>` | `alt` | **Obrigatorio** - Descricao da imagem |
+| `<img>` decorativa | `alt=""` + `aria-hidden="true"` | Imagem decorativa |
+| `<video>` | `aria-label` | Descricao do video |
+| `<iframe>` | `title` | **Obrigatorio** - Titulo do iframe |
+
+### Suporte a Teclado
+
+Como componente de layout, o AspectRatio nao e interativo por padrao. Quando o conteudo e clicavel:
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para elemento interativo filho |
+| `Enter` | Ativa link ou botao filho |
+| `Space` | Ativa botao filho |
+
+### Focus Management
+
+```tsx
+// Se o AspectRatio contem conteudo interativo
+<AspectRatio ratio={16/9}>
+  <button className="w-full h-full focus-visible:ring-2 focus-visible:ring-ring">
+    <img src="..." alt="Thumbnail do video" />
+    <span className="sr-only">Reproduzir video</span>
+  </button>
+</AspectRatio>
+```
+
+### Contraste de Cores
+
+Nao aplicavel diretamente ao AspectRatio. Garantir contraste no conteudo filho:
+
+| Elemento | Requisito WCAG |
+|----------|----------------|
+| Texto sobre imagem | 4.5:1 (AA) |
+| Texto grande sobre imagem | 3:1 (AA) |
+| Controles de UI | 3:1 (AA) |
+
+### Screen Readers
+
+```tsx
+// Imagem com descricao
+<AspectRatio ratio={16/9}>
+  <img src="banner.jpg" alt="Banner promocional: 50% de desconto em todos os produtos" />
+</AspectRatio>
+
+// Video com descricao
+<AspectRatio ratio={16/9}>
+  <video aria-label="Tutorial de introducao ao produto">
+    <track kind="captions" src="captions.vtt" />
+  </video>
+</AspectRatio>
+
+// Imagem decorativa
+<AspectRatio ratio={1}>
+  <img src="pattern.svg" alt="" aria-hidden="true" />
+</AspectRatio>
+```
+
+### Reduced Motion
+
+```tsx
+// Se houver animacoes no conteudo
+<AspectRatio ratio={16/9}>
+  <video
+    autoPlay
+    muted
+    className="motion-reduce:pause"
+    aria-label="Animacao de fundo"
+  />
+</AspectRatio>
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| **Layout puro** | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | - | - |
+| **Nao interfere a11y** | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | - | - |
+| **Docs de a11y** | ~ | ✓ | - | ✓ | ~ | ~ | - | - | - | - | ✓ | ✓ | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial | - = Nao aplicavel/Nao possui
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { AspectRatio } from "@etus/ui"
+
+function Example() {
+  return (
+    <AspectRatio ratio={16 / 9}>
+      <img
+        src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd"
+        alt="Paisagem com montanhas"
+        className="h-full w-full object-cover"
+      />
+    </AspectRatio>
+  )
+}
+```
+
+### Usando Presets
+
+```tsx
+import { AspectRatio, aspectRatios } from "@etus/ui"
+
+// Usando presets pre-definidos
+<AspectRatio ratio={aspectRatios.video}>
+  <img src="thumbnail.jpg" alt="Video thumbnail" className="object-cover size-full" />
+</AspectRatio>
+
+// Golden ratio para composicoes artisticas
+<AspectRatio ratio={aspectRatios.golden}>
+  <img src="art.jpg" alt="Arte" className="object-cover size-full" />
+</AspectRatio>
+
+// Instagram portrait (4:5)
+<AspectRatio ratio={aspectRatios.photo4x5}>
+  <img src="instagram.jpg" alt="Post Instagram" className="object-cover size-full" />
+</AspectRatio>
+
+// Ultrawide cinema (21:9)
+<AspectRatio ratio={aspectRatios.wide}>
+  <img src="cinematic.jpg" alt="Banner cinematico" className="object-cover size-full" />
+</AspectRatio>
+```
+
+### Proporcoes Comuns
+
+```tsx
+// Quadrado (1:1) - Avatares, thumbnails
+<AspectRatio ratio={aspectRatios.square}>
+  <img src="avatar.jpg" alt="Avatar do usuario" className="rounded-full object-cover" />
+</AspectRatio>
+
+// Video padrao (16:9) - YouTube, videos
+<AspectRatio ratio={aspectRatios.video}>
+  <iframe
+    src="https://www.youtube.com/embed/..."
+    title="Video tutorial"
+    allowFullScreen
+  />
+</AspectRatio>
+
+// Fotografia (4:3) - Fotos tradicionais
+<AspectRatio ratio={aspectRatios.landscape}>
+  <img src="photo.jpg" alt="Fotografia de natureza" className="object-cover" />
+</AspectRatio>
+
+// Retrato (2:3) - Posters, capas
+<AspectRatio ratio={aspectRatios.photoPortrait}>
+  <img src="poster.jpg" alt="Poster do filme" className="object-cover" />
+</AspectRatio>
+
+// Ultrawide (21:9) - Banners cinematicos
+<AspectRatio ratio={aspectRatios.wide}>
+  <img src="banner.jpg" alt="Banner promocional" className="object-cover" />
+</AspectRatio>
+
+// Vertical Stories (9:16) - TikTok, Reels
+<AspectRatio ratio={aspectRatios.vertical}>
+  <video src="story.mp4" className="object-cover size-full" />
+</AspectRatio>
+
+// Panoramica (2:1) - Hero banners
+<AspectRatio ratio={aspectRatios.panoramic}>
+  <img src="hero.jpg" alt="Hero banner" className="object-cover size-full" />
+</AspectRatio>
+```
+
+### Com Estilos e Bordas
+
+```tsx
+// Com borda arredondada e sombra
+<div className="w-[400px] overflow-hidden rounded-lg shadow-lg">
+  <AspectRatio ratio={16 / 9}>
+    <img
+      src="landscape.jpg"
+      alt="Paisagem"
+      className="h-full w-full object-cover"
+    />
+  </AspectRatio>
+</div>
+
+// Com overlay de texto
+<div className="relative w-[400px] overflow-hidden rounded-lg">
+  <AspectRatio ratio={16 / 9}>
+    <img
+      src="hero.jpg"
+      alt=""
+      aria-hidden="true"
+      className="h-full w-full object-cover"
+    />
+  </AspectRatio>
+  <div className="absolute inset-0 flex items-center justify-center bg-black/50">
+    <h2 className="text-2xl font-bold text-white">Titulo do Banner</h2>
+  </div>
+</div>
+```
+
+### Com Video
+
+```tsx
+// Video nativo
+<AspectRatio ratio={16 / 9}>
+  <video
+    controls
+    className="h-full w-full object-cover"
+    poster="thumbnail.jpg"
+  >
+    <source src="video.mp4" type="video/mp4" />
+    <track kind="captions" src="captions.vtt" srcLang="pt" label="Portugues" />
+    Seu navegador nao suporta video HTML5.
+  </video>
+</AspectRatio>
+
+// Embed do YouTube
+<AspectRatio ratio={16 / 9}>
+  <iframe
+    src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+    title="Video do YouTube"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+    allowFullScreen
+    className="h-full w-full"
+  />
+</AspectRatio>
+```
+
+### Com Mapa
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <iframe
+    src="https://www.google.com/maps/embed?..."
+    title="Localizacao no Google Maps"
+    className="h-full w-full border-0"
+    loading="lazy"
+    referrerPolicy="no-referrer-when-downgrade"
+  />
+</AspectRatio>
+```
+
+### Responsividade
+
+```tsx
+// Largura responsiva
+<div className="w-full md:w-1/2 lg:w-1/3">
+  <AspectRatio ratio={16 / 9}>
+    <img src="responsive.jpg" alt="Imagem responsiva" className="object-cover" />
+  </AspectRatio>
+</div>
+
+// Grid de imagens com proporcao uniforme
+<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+  {images.map((image) => (
+    <AspectRatio key={image.id} ratio={4 / 3}>
+      <img
+        src={image.src}
+        alt={image.alt}
+        className="h-full w-full rounded-lg object-cover"
+      />
+    </AspectRatio>
+  ))}
+</div>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <AspectRatio ratio={16 / 9} className="@sm:rounded-lg @md:rounded-xl">
+    <img
+      src="container-aware.jpg"
+      alt="Imagem com container queries"
+      className="h-full w-full object-cover"
+    />
+  </AspectRatio>
+</div>
+```
+
+### Composicao com Card
+
+```tsx
+import { Card, CardContent, CardHeader, CardTitle } from "@etus/ui"
+
+function MediaCard({ title, image, description }: MediaCardProps) {
+  return (
+    <Card className="overflow-hidden">
+      <AspectRatio ratio={16 / 9}>
+        <img
+          src={image}
+          alt={`Imagem de ${title}`}
+          className="h-full w-full object-cover"
+        />
+      </AspectRatio>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p className="text-muted-foreground">{description}</p>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### Loading State com Skeleton
+
+```tsx
+import { Skeleton } from "@etus/ui"
+
+function ImageWithSkeleton({ src, alt }: { src: string; alt: string }) {
+  const [loaded, setLoaded] = useState(false)
+
+  return (
+    <AspectRatio ratio={16 / 9}>
+      {!loaded && <Skeleton className="h-full w-full" />}
+      <img
+        src={src}
+        alt={alt}
+        onLoad={() => setLoaded(true)}
+        className={cn(
+          "h-full w-full object-cover transition-opacity",
+          loaded ? "opacity-100" : "opacity-0"
+        )}
+      />
+    </AspectRatio>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// AspectRatio.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { AspectRatio } from "./AspectRatio"
+
+describe("AspectRatio", () => {
+  it("renders children correctly", () => {
+    render(
+      <AspectRatio ratio={16 / 9}>
+        <img src="test.jpg" alt="Test image" />
+      </AspectRatio>
+    )
+    expect(screen.getByRole("img", { name: "Test image" })).toBeInTheDocument()
+  })
+
+  it("applies data-slot attribute", () => {
+    render(
+      <AspectRatio ratio={16 / 9} data-testid="aspect-ratio">
+        <div>Content</div>
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("aspect-ratio")).toHaveAttribute("data-slot", "aspect-ratio")
+  })
+
+  it("applies default ratio of 1", () => {
+    const { container } = render(
+      <AspectRatio>
+        <div>Square content</div>
+      </AspectRatio>
+    )
+    // Radix aplica padding-bottom baseado no ratio
+    const wrapper = container.firstChild
+    expect(wrapper).toBeInTheDocument()
+  })
+
+  it("merges custom className", () => {
+    render(
+      <AspectRatio ratio={16 / 9} className="custom-class" data-testid="aspect-ratio">
+        <div>Content</div>
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("aspect-ratio")).toHaveClass("custom-class")
+  })
+
+  it("forwards additional props", () => {
+    render(
+      <AspectRatio ratio={16 / 9} data-custom="value" data-testid="aspect-ratio">
+        <div>Content</div>
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("aspect-ratio")).toHaveAttribute("data-custom", "value")
+  })
+})
+```
+
+### Testes de Renderizacao
+
+```tsx
+describe("AspectRatio rendering", () => {
+  it("renders with 16:9 ratio", () => {
+    const { container } = render(
+      <AspectRatio ratio={16 / 9}>
+        <img src="video-thumb.jpg" alt="Video thumbnail" />
+      </AspectRatio>
+    )
+    expect(container.querySelector("img")).toBeInTheDocument()
+  })
+
+  it("renders with 1:1 ratio for square content", () => {
+    const { container } = render(
+      <AspectRatio ratio={1}>
+        <img src="avatar.jpg" alt="User avatar" />
+      </AspectRatio>
+    )
+    expect(container.querySelector("img")).toBeInTheDocument()
+  })
+
+  it("renders iframe content", () => {
+    render(
+      <AspectRatio ratio={16 / 9}>
+        <iframe src="https://example.com" title="Embedded content" />
+      </AspectRatio>
+    )
+    expect(screen.getByTitle("Embedded content")).toBeInTheDocument()
+  })
+
+  it("renders video content", () => {
+    render(
+      <AspectRatio ratio={16 / 9}>
+        <video data-testid="video">
+          <source src="video.mp4" type="video/mp4" />
+        </video>
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("video")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("AspectRatio accessibility", () => {
+  it("has no accessibility violations with alt text", async () => {
+    const { container } = render(
+      <AspectRatio ratio={16 / 9}>
+        <img src="test.jpg" alt="Descricao da imagem" />
+      </AspectRatio>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with decorative image", async () => {
+    const { container } = render(
+      <AspectRatio ratio={16 / 9}>
+        <img src="decorative.jpg" alt="" aria-hidden="true" />
+      </AspectRatio>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with iframe title", async () => {
+    const { container } = render(
+      <AspectRatio ratio={16 / 9}>
+        <iframe src="https://example.com" title="Conteudo incorporado" />
+      </AspectRatio>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("image without alt fails accessibility", async () => {
+    const { container } = render(
+      <AspectRatio ratio={16 / 9}>
+        <img src="test.jpg" />
+      </AspectRatio>
+    )
+    const results = await axe(container)
+    expect(results.violations.length).toBeGreaterThan(0)
+  })
+})
+```
+
+### Testes de Integracao
+
+```tsx
+describe("AspectRatio integration", () => {
+  it("works with loading state", async () => {
+    const { rerender } = render(
+      <AspectRatio ratio={16 / 9}>
+        <div data-testid="skeleton">Loading...</div>
+      </AspectRatio>
+    )
+
+    expect(screen.getByTestId("skeleton")).toBeInTheDocument()
+
+    rerender(
+      <AspectRatio ratio={16 / 9}>
+        <img src="loaded.jpg" alt="Loaded image" />
+      </AspectRatio>
+    )
+
+    expect(screen.getByRole("img", { name: "Loaded image" })).toBeInTheDocument()
+  })
+
+  it("maintains aspect ratio in different container widths", () => {
+    const { container, rerender } = render(
+      <div style={{ width: "400px" }}>
+        <AspectRatio ratio={16 / 9} data-testid="aspect">
+          <div>Content</div>
+        </AspectRatio>
+      </div>
+    )
+
+    const aspect1 = screen.getByTestId("aspect")
+    expect(aspect1).toBeInTheDocument()
+
+    rerender(
+      <div style={{ width: "800px" }}>
+        <AspectRatio ratio={16 / 9} data-testid="aspect">
+          <div>Content</div>
+        </AspectRatio>
+      </div>
+    )
+
+    const aspect2 = screen.getByTestId("aspect")
+    expect(aspect2).toBeInTheDocument()
+  })
+})
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("AspectRatio edge cases", () => {
+  it("handles very wide ratios", () => {
+    render(
+      <AspectRatio ratio={21 / 9} data-testid="ultrawide">
+        <img src="ultrawide.jpg" alt="Ultrawide banner" />
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("ultrawide")).toBeInTheDocument()
+  })
+
+  it("handles very tall ratios", () => {
+    render(
+      <AspectRatio ratio={9 / 16} data-testid="portrait">
+        <img src="portrait.jpg" alt="Portrait image" />
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("portrait")).toBeInTheDocument()
+  })
+
+  it("handles fractional ratios", () => {
+    render(
+      <AspectRatio ratio={1.5} data-testid="fractional">
+        <div>Content</div>
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("fractional")).toBeInTheDocument()
+  })
+
+  it("handles zero ratio gracefully", () => {
+    // Comportamento do Radix com ratio 0
+    render(
+      <AspectRatio ratio={0} data-testid="zero">
+        <div>Content</div>
+      </AspectRatio>
+    )
+    expect(screen.getByTestId("zero")).toBeInTheDocument()
+  })
+
+  it("handles multiple children (only first rendered)", () => {
+    render(
+      <AspectRatio ratio={16 / 9} data-testid="multi">
+        <img src="first.jpg" alt="First image" />
+      </AspectRatio>
+    )
+    expect(screen.getByRole("img", { name: "First image" })).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### Tailwind Utilities Integration
+
+Considerar se o componente deve ser substituido por classes Tailwind nativas em casos simples.
+
+```tsx
+// Alternativa via Tailwind (CSS nativo)
+<div className="aspect-video">
+  <img src="..." className="object-cover" />
+</div>
+
+// vs Componente (API consistente)
+<AspectRatio ratio={16 / 9}>
+  <img src="..." className="object-cover" />
+</AspectRatio>
+```
+
+**Recomendacao:** Manter ambas opcoes documentadas. Componente para API consistente, classes para simplicidade.
+
+### Prioridade Media
+
+#### `maxWidth` / `maxW` prop
+
+Limitar largura maxima mantendo a proporcao.
+
+```tsx
+// Proposta de API (inspirado no Chakra)
+interface AspectRatioProps {
+  maxW?: string | number
+}
+
+// Uso
+<AspectRatio ratio={16 / 9} maxW="600px">
+  <img src="..." />
+</AspectRatio>
+```
+
+**Referencias:** Chakra UI (`maxW`)
+
+#### Loading State Integrado
+
+Skeleton automatico durante carregamento de imagem.
+
+```tsx
+// Proposta de API
+interface AspectRatioProps {
+  loading?: boolean
+  skeleton?: ReactNode
+}
+
+// Uso
+<AspectRatio ratio={16 / 9} loading={!imageLoaded}>
+  <img src="..." onLoad={() => setImageLoaded(true)} />
+</AspectRatio>
+```
+
+### Prioridade Baixa
+
+#### Presets de Ratio ✅ IMPLEMENTADO
+
+Valores pre-definidos para ratios comuns. **Implementado com 18 presets** que correspondem ao Figma Design System.
+
+```tsx
+import { AspectRatio, aspectRatios } from "@etus/ui"
+
+// Uso com presets
+<AspectRatio ratio={aspectRatios.video}>...</AspectRatio>
+<AspectRatio ratio={aspectRatios.golden}>...</AspectRatio>
+<AspectRatio ratio={aspectRatios.photo4x5}>...</AspectRatio>
+```
+
+### Decisoes de Design
+
+| Feature | Status | Justificativa |
+|---------|--------|---------------|
+| Tailwind classes | Documentar | CSS nativo e mais simples para casos basicos |
+| `maxW` | Avaliar | Pode ser feito via wrapper com className |
+| Loading state | Composicao | Manter simples, usuario compoe com Skeleton |
+| Presets | ✅ Implementado | 18 presets disponiveis via `aspectRatios` |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentacao | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Aspect Ratio](https://ui.shadcn.com/docs/components/aspect-ratio) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Aspect Ratio](https://www.radix-ui.com/primitives/docs/components/aspect-ratio) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **Chakra UI** | [Aspect Ratio](https://chakra-ui.com/docs/components/aspect-ratio) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Box (aspectRatio)](https://mui.com/system/getting-started/the-sx-prop/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Tailwind CSS** | [Aspect Ratio](https://tailwindcss.com/docs/aspect-ratio) | [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss) |
+
+### Especificacoes e Padroes
+
+- [MDN - aspect-ratio CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio)
+- [CSS Tricks - Aspect Ratio Boxes](https://css-tricks.com/aspect-ratio-boxes/)
+- [Can I Use - aspect-ratio](https://caniuse.com/mdn-css_properties_aspect-ratio)
+- [WCAG 2.1 - Images](https://www.w3.org/WAI/tutorials/images/)
+
+### Ferramentas Utilizadas
+
+- [Radix Aspect Ratio](https://www.radix-ui.com/primitives/docs/components/aspect-ratio)
+- [Tailwind CSS](https://tailwindcss.com/docs)