@etus/ui 0.1.0

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

@@ -0,0 +1,792 @@
+# Skeleton
+
+## Visão Geral
+
+O **Skeleton** é um componente de feedback visual que indica áreas de conteúdo em carregamento. Como elemento atômico, serve de base para criar estados de loading consistentes em toda a aplicação, melhorando a percepção de performance e reduzindo a ansiedade do usuário durante carregamentos.
+
+### Casos de Uso
+
+- Placeholder para texto em carregamento
+- Placeholder para imagens e avatares
+- Estados de loading em cards e listas
+- Substituição de conteúdo durante fetch de dados
+- Composição de layouts de loading complexos
+
+### Classificação
+
+**Categoria:** Atom (Primitive)
+**Dependências:** Nenhuma (apenas `cn` utility)
+
+---
+
+## Design Specs
+
+### Estilos Base
+
+O Skeleton utiliza um estilo minimalista com animação pulse para indicar carregamento:
+
+| Propriedade | Valor | Descrição |
+|-------------|-------|-----------|
+| Background | `bg-accent` | Cor neutra que funciona em light/dark mode |
+| Animação | `animate-pulse` | Efeito de pulsação suave (2s ease-in-out) |
+| Border Radius | `rounded-md` | Cantos arredondados padrão |
+
+### Estados
+
+| Estado | Comportamento |
+|--------|---------------|
+| Default | Animação pulse contínua |
+| Loaded | Componente é substituído pelo conteúdo real |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--accent           /* Fundo do skeleton */
+
+/* Animação */
+animate-pulse      /* keyframes: 0%,100% opacity:1, 50% opacity:0.5 */
+
+/* Bordas */
+rounded-md         /* var(--radius) */
+```
+
+### data-slot
+
+```html
+<div data-slot="skeleton">...</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `shape` | `"rectangle" \| "circle" \| "text" \| "heading" \| "square" \| "pill"` | `"rectangle"` | Forma do skeleton |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | - | Tamanho pré-definido por forma |
+| `animation` | `"pulse" \| "shimmer" \| "none"` | `"pulse"` | Tipo de animação |
+| `className` | `string` | - | Classes CSS adicionais para customização |
+| `children` | `ReactNode` | - | Conteúdo opcional (geralmente não usado) |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### TypeScript
+
+```typescript
+import type { SkeletonLoaderProps, SkeletonLoaderShape, SkeletonLoaderSize, SkeletonLoaderAnimation } from "@etus/ui"
+
+// Tipos exportados
+type SkeletonLoaderShape = "rectangle" | "circle" | "text" | "heading" | "square" | "pill"
+type SkeletonLoaderSize = "xs" | "sm" | "md" | "lg" | "xl" | "full"
+type SkeletonLoaderAnimation = "pulse" | "shimmer" | "none"
+
+// Props do componente
+interface SkeletonLoaderProps extends React.ComponentProps<"div"> {
+  shape?: SkeletonLoaderShape
+  size?: SkeletonLoaderSize
+  animation?: SkeletonLoaderAnimation
+}
+```
+
+### 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 | Blueprint | PrimeReact |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| **Componente base** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | - | ✓ |
+| **animate-pulse** | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - | - | - |
+| **wave animation** | - | - | - | - | ✓ | - | ✓ | - | - | - | ✓ | - | - | ✓ |
+| **Variantes** | - | - | - | - | 3 | - | ✓ | - | - | - | ✓ | - | - | ✓ |
+| **Circle/Avatar** | - | - | - | ✓ | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ | - | ✓ |
+| **Text lines** | - | - | - | ✓ | - | ✓ | ✓ | - | - | - | - | ✓ | - | - |
+| **isLoaded** | - | - | - | ✓ | - | - | - | ✓ | - | - | - | - | - | - |
+| **Composable** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | - | ✓ |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **Fade transition** | - | - | - | ✓ | - | - | - | ✓ | - | - | - | - | - | - |
+| **Speed control** | - | - | - | ✓ | ✓ | - | - | - | - | - | - | - | - | - |
+| **Color custom** | ~ | ~ | - | ✓ | - | ✓ | - | - | - | - | ✓ | - | - | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Via className | - = Não suportado
+
+#### Comparativo de Animações por Design System
+
+| Design System | Tipo de Animação | Duração | Descrição |
+|---------------|------------------|---------|-----------|
+| **ETUS** | Pulse (opacity) | 2s | Opacidade 1 → 0.5 → 1 |
+| **Shadcn/ui** | Pulse (opacity) | 2s | Mesmo que ETUS |
+| **MUI** | Wave (shimmer) | 1.6s | Gradiente deslizante |
+| **Ant Design** | Wave (shimmer) | 1.4s | Gradiente com brilho |
+| **Chakra UI** | Fade | 0.8s | Transição suave de opacidade |
+| **Mantine** | Pulse | 1.5s | Similar ao Tailwind |
+| **NextUI** | Shimmer | 2s | Efeito de brilho |
+| **Fluent UI** | Wave | 2s | Shimmer horizontal |
+| **Carbon** | Pulse | 1s | Opacidade suave |
+| **PrimeReact** | Wave | 1.2s | Gradiente animado |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `className` | ✓ | ✓ | `sx` | ✓ | ✓ | ✓ | ✓ |
+| `variant` | - | - | ✓ | - | - | - | `shape` |
+| `animation` | - | - | ✓ | - | ✓ | - | - |
+| `width` | ~ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| `height` | ~ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| `circle` | ~ | - | - | ✓ | - | - | - |
+| `isLoaded` | - | ✓ | - | - | - | ✓ | - |
+| `fadeDuration` | - | ✓ | - | - | - | ✓ | - |
+| `startColor` | - | ✓ | - | - | - | - | - |
+| `endColor` | - | ✓ | - | - | - | - | - |
+| `speed` | - | ✓ | - | - | - | - | - |
+| `borderRadius` | ~ | - | - | ✓ | - | - | - |
+
+#### Abordagens de Implementação
+
+| Design System | Abordagem | Notas |
+|---------------|-----------|-------|
+| **ETUS/Shadcn** | Minimal | Div com classe, máxima flexibilidade |
+| **Chakra UI** | Feature-rich | Props para tudo, isLoaded com transição |
+| **MUI** | Variants | text, rectangular, circular, wave animation |
+| **Mantine** | Simple | Similar Shadcn, com animate prop |
+| **Ant Design** | Configurable | active, avatar, title, paragraph shapes |
+| **NextUI** | Wrapper | isLoaded para transição automática |
+| **Fluent UI** | Shape-based | Diferente por tipo de conteúdo |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso | Quando Aplicar |
+|----------|-----|----------------|
+| `aria-busy="true"` | Indica conteúdo em carregamento | Em containers com skeleton |
+| `aria-hidden="true"` | Esconde de leitores de tela | No skeleton visual |
+| `role="status"` | Anuncia mudança de estado | No container pai |
+| `aria-label` | Descrição do loading | Quando contextualmente necessário |
+
+### Screen Readers
+
+O Skeleton é puramente visual e deve ser tratado como decorativo para tecnologias assistivas:
+
+```tsx
+// Padrão recomendado
+<div role="status" aria-busy="true" aria-label="Carregando conteúdo">
+  <Skeleton className="h-4 w-full" aria-hidden="true" />
+  <Skeleton className="h-4 w-3/4" aria-hidden="true" />
+</div>
+```
+
+### Reduced Motion
+
+```tsx
+// Respeitar preferência do usuário
+@media (prefers-reduced-motion: reduce) {
+  .animate-pulse {
+    animation: none;
+  }
+}
+```
+
+### Considerações de UX Acessível
+
+- Não usar skeleton por tempo excessivo (> 10s sugere problema)
+- Fornecer texto alternativo para contexto
+- Garantir transição suave quando conteúdo carrega
+- Manter proporções similares ao conteúdo final
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **aria-busy auto** | - | ✓ | - | - | - | ✓ | ✓ | ✓ |
+| **aria-hidden** | ~ | - | - | - | - | - | ✓ | - |
+| **role="status"** | ~ | - | - | - | - | - | ✓ | - |
+| **Reduced motion** | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Screen reader tested** | - | ~ | ✓ | - | - | ~ | ✓ | ✓ |
+| **Live regions** | - | - | - | - | - | - | ✓ | ✓ |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Skeleton } from "@etus/ui"
+
+function Example() {
+  return <Skeleton className="h-4 w-[250px]" />
+}
+```
+
+### Skeleton para Texto
+
+```tsx
+// Múltiplas linhas de texto
+function TextSkeleton() {
+  return (
+    <div className="space-y-2">
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-3/4" />
+    </div>
+  )
+}
+```
+
+### Skeleton para Avatar
+
+```tsx
+// Avatar circular
+function AvatarSkeleton() {
+  return <Skeleton className="h-12 w-12 rounded-full" />
+}
+
+// Avatar com nome
+function UserSkeleton() {
+  return (
+    <div className="flex items-center gap-3">
+      <Skeleton className="h-10 w-10 rounded-full" />
+      <div className="space-y-2">
+        <Skeleton className="h-4 w-[150px]" />
+        <Skeleton className="h-3 w-[100px]" />
+      </div>
+    </div>
+  )
+}
+```
+
+### Skeleton para Card
+
+```tsx
+function CardSkeleton() {
+  return (
+    <div className="rounded-lg border p-4 space-y-4">
+      {/* Imagem */}
+      <Skeleton className="h-[200px] w-full rounded-lg" />
+
+      {/* Título */}
+      <Skeleton className="h-6 w-3/4" />
+
+      {/* Descrição */}
+      <div className="space-y-2">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-2/3" />
+      </div>
+
+      {/* Botão */}
+      <Skeleton className="h-10 w-[120px]" />
+    </div>
+  )
+}
+```
+
+### Skeleton para Tabela
+
+```tsx
+function TableRowSkeleton() {
+  return (
+    <tr>
+      <td className="p-4">
+        <Skeleton className="h-4 w-[80px]" />
+      </td>
+      <td className="p-4">
+        <Skeleton className="h-4 w-[150px]" />
+      </td>
+      <td className="p-4">
+        <Skeleton className="h-4 w-[100px]" />
+      </td>
+      <td className="p-4">
+        <Skeleton className="h-8 w-[60px]" />
+      </td>
+    </tr>
+  )
+}
+
+function TableSkeleton({ rows = 5 }: { rows?: number }) {
+  return (
+    <table className="w-full">
+      <tbody>
+        {Array.from({ length: rows }).map((_, i) => (
+          <TableRowSkeleton key={i} />
+        ))}
+      </tbody>
+    </table>
+  )
+}
+```
+
+### Skeleton com Transição (Composição)
+
+```tsx
+import { Skeleton } from "@etus/ui"
+import { useState, useEffect } from "react"
+
+function DataWithSkeleton() {
+  const [isLoading, setIsLoading] = useState(true)
+  const [data, setData] = useState(null)
+
+  useEffect(() => {
+    fetchData().then((result) => {
+      setData(result)
+      setIsLoading(false)
+    })
+  }, [])
+
+  if (isLoading) {
+    return (
+      <div role="status" aria-busy="true" aria-label="Carregando dados">
+        <Skeleton className="h-6 w-[200px]" aria-hidden="true" />
+      </div>
+    )
+  }
+
+  return <h1>{data.title}</h1>
+}
+```
+
+### Skeleton para Lista
+
+```tsx
+function ListSkeleton({ items = 3 }: { items?: number }) {
+  return (
+    <ul className="space-y-3">
+      {Array.from({ length: items }).map((_, i) => (
+        <li key={i} className="flex items-center gap-3">
+          <Skeleton className="h-8 w-8 rounded" />
+          <Skeleton className="h-4 flex-1" />
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Skeleton Responsivo
+
+```tsx
+function ResponsiveSkeleton() {
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+      {Array.from({ length: 6 }).map((_, i) => (
+        <div key={i} className="space-y-3">
+          <Skeleton className="h-[150px] w-full" />
+          <Skeleton className="h-4 w-3/4" />
+          <Skeleton className="h-4 w-1/2" />
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <div className="@sm:flex-row flex flex-col gap-4">
+    <Skeleton className="@sm:h-24 @sm:w-24 h-40 w-full" />
+    <div className="flex-1 space-y-2">
+      <Skeleton className="h-5 w-full" />
+      <Skeleton className="h-4 w-3/4" />
+    </div>
+  </div>
+</div>
+```
+
+### Formas (via prop)
+
+```tsx
+// Retângulo (padrão)
+<Skeleton shape="rectangle" size="md" />
+
+// Círculo (aspect-square, rounded-full)
+<Skeleton shape="circle" size="md" />
+
+// Texto (h-4, para linhas de texto)
+<Skeleton shape="text" size="full" />
+
+// Heading (h-7, para títulos)
+<Skeleton shape="heading" size="lg" />
+
+// Quadrado (aspect-square)
+<Skeleton shape="square" size="md" />
+
+// Pill (rounded-full, para tags/badges)
+<Skeleton shape="pill" size="sm" />
+```
+
+### Animações
+
+```tsx
+// Pulse (padrão) - opacidade pulsante
+<Skeleton animation="pulse" />
+
+// Shimmer - gradiente deslizante
+<Skeleton animation="shimmer" />
+
+// Sem animação
+<Skeleton animation="none" />
+```
+
+### Tamanhos por Forma
+
+```tsx
+// Rectangle: xs=h-2, sm=h-4, md=h-8, lg=h-16, xl=h-32
+<Skeleton shape="rectangle" size="lg" />
+
+// Circle: xs=size-6, sm=size-8, md=size-12, lg=size-16, xl=size-24
+<Skeleton shape="circle" size="md" />
+
+// Text: xs=h-3, sm=h-3.5, md=h-4, lg=h-5, xl=h-6
+<Skeleton shape="text" size="md" />
+
+// Full width para qualquer forma
+<Skeleton shape="rectangle" size="full" />
+```
+
+### Diferentes Formatos (via className)
+
+```tsx
+// Retângulo (padrão)
+<Skeleton className="h-20 w-full" />
+
+// Círculo
+<Skeleton className="h-16 w-16 rounded-full" />
+
+// Pill/Badge
+<Skeleton className="h-6 w-20 rounded-full" />
+
+// Quadrado
+<Skeleton className="h-12 w-12 rounded-none" />
+
+// Arredondado grande
+<Skeleton className="h-32 w-full rounded-xl" />
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Skeleton.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Skeleton } from "./SkeletonLoader"
+
+describe("Skeleton", () => {
+  it("renders correctly", () => {
+    render(<Skeleton data-testid="skeleton" />)
+    expect(screen.getByTestId("skeleton")).toBeInTheDocument()
+  })
+
+  it("has correct base classes", () => {
+    render(<Skeleton data-testid="skeleton" />)
+    const skeleton = screen.getByTestId("skeleton")
+
+    expect(skeleton).toHaveClass("bg-accent")
+    expect(skeleton).toHaveClass("animate-pulse")
+    expect(skeleton).toHaveClass("rounded-md")
+  })
+
+  it("merges custom className", () => {
+    render(<Skeleton data-testid="skeleton" className="h-4 w-full" />)
+    const skeleton = screen.getByTestId("skeleton")
+
+    expect(skeleton).toHaveClass("h-4")
+    expect(skeleton).toHaveClass("w-full")
+    expect(skeleton).toHaveClass("animate-pulse") // Mantém classes base
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Skeleton data-testid="skeleton" />)
+    expect(screen.getByTestId("skeleton")).toHaveAttribute(
+      "data-slot",
+      "skeleton"
+    )
+  })
+
+  it("passes through additional props", () => {
+    render(<Skeleton data-testid="skeleton" id="my-skeleton" role="status" />)
+    const skeleton = screen.getByTestId("skeleton")
+
+    expect(skeleton).toHaveAttribute("id", "my-skeleton")
+    expect(skeleton).toHaveAttribute("role", "status")
+  })
+})
+```
+
+### Testes de Composição
+
+```tsx
+describe("Skeleton composition", () => {
+  it("renders multiple skeletons for text placeholder", () => {
+    render(
+      <div data-testid="text-skeleton">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-3/4" />
+      </div>
+    )
+
+    const container = screen.getByTestId("text-skeleton")
+    const skeletons = container.querySelectorAll('[data-slot="skeleton"]')
+
+    expect(skeletons).toHaveLength(3)
+  })
+
+  it("renders circular skeleton for avatar", () => {
+    render(<Skeleton data-testid="avatar" className="rounded-full h-12 w-12" />)
+    const skeleton = screen.getByTestId("avatar")
+
+    expect(skeleton).toHaveClass("rounded-full")
+    expect(skeleton).toHaveClass("h-12")
+    expect(skeleton).toHaveClass("w-12")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Skeleton accessibility", () => {
+  it("has no accessibility violations when properly labeled", async () => {
+    const { container } = render(
+      <div role="status" aria-busy="true" aria-label="Carregando conteúdo">
+        <Skeleton aria-hidden="true" />
+      </div>
+    )
+
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("can be hidden from screen readers", () => {
+    render(<Skeleton data-testid="skeleton" aria-hidden="true" />)
+    expect(screen.getByTestId("skeleton")).toHaveAttribute(
+      "aria-hidden",
+      "true"
+    )
+  })
+})
+```
+
+### Testes de Estilo
+
+```tsx
+describe("Skeleton styling", () => {
+  it("allows custom dimensions", () => {
+    render(<Skeleton data-testid="skeleton" className="h-[200px] w-[300px]" />)
+    const skeleton = screen.getByTestId("skeleton")
+
+    expect(skeleton).toHaveClass("h-[200px]")
+    expect(skeleton).toHaveClass("w-[300px]")
+  })
+
+  it("allows custom border radius", () => {
+    render(<Skeleton data-testid="skeleton" className="rounded-full" />)
+    expect(screen.getByTestId("skeleton")).toHaveClass("rounded-full")
+  })
+
+  it("allows removing animation", () => {
+    render(<Skeleton data-testid="skeleton" className="animate-none" />)
+    // Note: animate-none pode não sobrescrever animate-pulse dependendo da ordem
+    // Isso é um edge case que pode precisar de compound variants
+    expect(screen.getByTestId("skeleton")).toHaveClass("animate-none")
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Skeleton edge cases", () => {
+  it("renders without any props", () => {
+    render(<Skeleton data-testid="skeleton" />)
+    expect(screen.getByTestId("skeleton")).toBeInTheDocument()
+  })
+
+  it("handles empty className", () => {
+    render(<Skeleton data-testid="skeleton" className="" />)
+    expect(screen.getByTestId("skeleton")).toHaveClass("animate-pulse")
+  })
+
+  it("can render children if needed", () => {
+    render(<Skeleton data-testid="skeleton">Hidden content</Skeleton>)
+    expect(screen.getByTestId("skeleton")).toHaveTextContent("Hidden content")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### ✅ Implementado
+
+#### Variantes de Forma
+
+Props `shape`, `size` e `animation` para controle via CVA.
+
+```tsx
+// Formas disponíveis
+<Skeleton shape="rectangle" />  {/* Retângulo padrão */}
+<Skeleton shape="circle" />     {/* Círculo (avatar) */}
+<Skeleton shape="text" />       {/* Linha de texto */}
+<Skeleton shape="heading" />    {/* Título/heading */}
+<Skeleton shape="square" />     {/* Quadrado */}
+<Skeleton shape="pill" />       {/* Pill/badge */}
+
+// Tamanhos pré-definidos por forma
+<Skeleton shape="circle" size="md" />  {/* 48px */}
+<Skeleton shape="text" size="full" />  {/* 100% width */}
+
+// Animações
+<Skeleton animation="pulse" />    {/* Padrão */}
+<Skeleton animation="shimmer" />  {/* Gradiente deslizante */}
+<Skeleton animation="none" />     {/* Sem animação */}
+```
+
+**Referências:** MUI (`variant`), Fluent UI (`shape`)
+
+### Prioridade Alta
+
+#### `isLoaded` com Transição
+
+```tsx
+// Proposta de API
+interface SkeletonProps {
+  isLoaded?: boolean
+  fadeDuration?: number
+}
+
+// Uso
+<Skeleton isLoaded={!loading}>
+  <ActualContent />
+</Skeleton>
+```
+
+**Referências:** Chakra UI (`isLoaded`), NextUI (`isLoaded`)
+
+### Prioridade Média
+
+#### Animação Wave/Shimmer
+
+```tsx
+// Proposta de API
+interface SkeletonProps {
+  animation?: "pulse" | "wave" | "none"
+}
+
+// Uso
+<Skeleton animation="wave" />
+```
+
+**Referências:** MUI (`animation`), AntD (`active`)
+
+#### SkeletonText (Compound Component)
+
+```tsx
+// Proposta de API
+interface SkeletonTextProps {
+  lines?: number
+  lastLineWidth?: string
+}
+
+// Uso
+<SkeletonText lines={3} lastLineWidth="75%" />
+```
+
+**Referências:** Chakra UI (`SkeletonText`), AntD (`Skeleton.Paragraph`)
+
+### Prioridade Baixa
+
+#### Speed Control
+
+```tsx
+// Proposta de API
+interface SkeletonProps {
+  speed?: number // em segundos
+}
+
+// Uso
+<Skeleton speed={1.5} />
+```
+
+**Referências:** Chakra UI (`speed`)
+
+#### Cores Customizáveis
+
+```tsx
+// Proposta de API
+interface SkeletonProps {
+  startColor?: string
+  endColor?: string
+}
+
+// Uso
+<Skeleton startColor="gray.100" endColor="gray.300" />
+```
+
+**Referências:** Chakra UI (`startColor`, `endColor`)
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `variant` | Avaliar | Pode simplificar casos comuns |
+| `isLoaded` | Implementar | Melhora DX significativamente |
+| `animation` | Avaliar | Wave é popular, mas aumenta bundle |
+| `SkeletonText` | Implementar | Muito útil para casos de texto |
+| `speed` | Evitar | className funciona |
+| Custom colors | Evitar | Usar CSS variables ou className |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação Skeleton | GitHub |
+|---------------|----------------------|--------|
+| **Shadcn/ui** | [Skeleton](https://ui.shadcn.com/docs/components/skeleton) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Chakra UI** | [Skeleton](https://chakra-ui.com/docs/components/skeleton) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Skeleton](https://mui.com/material-ui/react-skeleton/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Skeleton](https://mantine.dev/core/skeleton/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Skeleton](https://ant.design/components/skeleton) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Skeleton](https://nextui.org/docs/components/skeleton) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Fluent UI** | [Skeleton](https://react.fluentui.dev/?path=/docs/components-skeleton--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Skeleton](https://carbondesignsystem.com/components/skeleton-states/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **PrimeReact** | [Skeleton](https://primereact.org/skeleton/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificações e Padrões
+
+- [MDN - CSS animation](https://developer.mozilla.org/en-US/docs/Web/CSS/animation)
+- [Tailwind CSS - Animation](https://tailwindcss.com/docs/animation)
+- [WCAG 2.1 - 2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html)
+- [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
+
+### Artigos e Recursos
+
+- [Skeleton Screens - UX Collective](https://uxdesign.cc/what-you-should-know-about-skeleton-screens-a820c45a571a)
+- [Everything you need to know about skeleton screens](https://uxdesign.cc/everything-you-need-to-know-about-skeleton-screens-e81f7ddcb1ab)
+- [Building Skeleton Components with React](https://css-tricks.com/building-skeleton-components-with-react/)
+
+### Ferramentas Utilizadas
+
+- [Tailwind CSS - animate-pulse](https://tailwindcss.com/docs/animation#pulse)
+- [cn utility (clsx + tailwind-merge)](https://ui.shadcn.com/docs/installation/manual#add-a-cn-helper)