@etus/ui 0.1.0

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

@@ -0,0 +1,804 @@
+# Spacer
+
+## Visão Geral
+
+O **Spacer** é um componente de layout atômico do Design System ETUS usado para criar espaçamento entre elementos de forma semântica e controlada. Diferente de margens ou padding inline, o Spacer é um elemento explícito que torna o espaçamento visível no código e facilita a manutenção.
+
+### Casos de Uso
+
+- Espaçamento vertical entre seções de conteúdo
+- Espaçamento horizontal entre elementos inline/flex
+- Espaçamento responsivo que muda por breakpoint
+- Espaçamento semântico em layouts complexos
+- Separação visual sem linha divisória (diferente do Separator)
+- Preenchimento de espaço em layouts flex/grid
+
+### Classificação
+
+**Categoria:** Atom (Primitive)
+**Dependências:** Nenhuma (componente puro)
+
+### Spacer vs Separator vs Gap
+
+| Componente | Propósito | Visual | Uso |
+|------------|-----------|--------|-----|
+| **Spacer** | Espaço explícito | Invisível | Entre elementos específicos |
+| **Separator** | Divisão semântica | Linha visível | Dividir seções |
+| **Gap** (CSS) | Espaço uniforme | Invisível | Entre todos os filhos |
+
+---
+
+## Design Specs
+
+### Tamanhos (`size`)
+
+| Tamanho | Valor | Pixels | Uso |
+|---------|-------|--------|-----|
+| `xs` | `0.5rem` | 8px | Micro espaçamentos |
+| `sm` | `1rem` | 16px | Espaçamentos compactos |
+| `md` | `1.5rem` | 24px | Espaçamento padrão |
+| `lg` | `2rem` | 32px | Seções relacionadas |
+| `xl` | `3rem` | 48px | Grandes seções |
+| `2xl` | `4rem` | 64px | Divisões principais |
+
+### Orientação (`axis`)
+
+| Orientação | Classes | Comportamento |
+|------------|---------|---------------|
+| `vertical` (padrão) | `h-{size} w-full` | Ocupa altura, largura 100% |
+| `horizontal` | `w-{size} h-full` | Ocupa largura, altura 100% |
+| `both` | `h-{size} w-{size}` | Quadrado (raro) |
+
+### Flexibilidade (`flex`)
+
+| Modo | Comportamento | Uso |
+|------|---------------|-----|
+| `none` (padrão) | Tamanho fixo | Espaçamento preciso |
+| `grow` | Expande para preencher | Push elements apart |
+| `shrink` | Pode encolher | Espaçamento mínimo |
+
+### Tokens Utilizados
+
+```css
+/* Espaçamento (baseado em --spacing) */
+--spacing-2     /* xs: 0.5rem */
+--spacing-4     /* sm: 1rem */
+--spacing-6     /* md: 1.5rem */
+--spacing-8     /* lg: 2rem */
+--spacing-12    /* xl: 3rem */
+--spacing-16    /* 2xl: 4rem */
+
+/* Layout */
+shrink-0        /* Impede encolhimento por padrão */
+flex-grow       /* Modo grow */
+flex-shrink     /* Modo shrink */
+```
+
+### data-slot
+
+```html
+<div data-slot="spacer" aria-hidden="true">...</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| number \| \`${number}px\` \| \`${number}rem\` \| \`${number}em\`` | `"md"` | Tamanho do espaçamento (token ou numérico) |
+| `axis` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | Direção do espaçamento |
+| `flex` | `"none" \| "grow" \| "shrink"` | `"none"` | Comportamento flex |
+| `className` | `string` | - | Classes CSS adicionais |
+| `ref` | `Ref<HTMLDivElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### TypeScript
+
+```typescript
+import type { SpacerProps, SpacerSize, SpacerTokenSize, SpacerNumericSize, SpacerAxis, SpacerFlex } from "@etus/ui"
+
+// Tipos exportados
+type SpacerTokenSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+type SpacerNumericSize = number | `${number}px` | `${number}rem` | `${number}em`
+type SpacerSize = SpacerTokenSize | SpacerNumericSize
+type SpacerAxis = "vertical" | "horizontal" | "both"
+type SpacerFlex = "none" | "grow" | "shrink"
+
+// Props do componente
+interface SpacerProps extends React.ComponentProps<"div"> {
+  size?: SpacerSize
+  axis?: SpacerAxis
+  flex?: SpacerFlex
+}
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint |
+|---------|:----:|:------:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|
+| **Spacer dedicado** | ✓ | - | - | - | ✓ | ~ | ✓ | ✓ | ✓ | - | - | - | - | - |
+| **Vertical** | ✓ | - | - | - | ✓ | - | ✓ | ✓ | ✓ | - | - | - | - | - |
+| **Horizontal** | ✓ | - | - | - | ✓ | - | ✓ | ✓ | ✓ | - | - | - | - | - |
+| **Flex grow** | ✓ | - | - | - | ✓ | - | - | - | ✓ | - | - | - | - | - |
+| **Size tokens** | ✓ | - | - | - | ~ | - | ✓ | - | - | - | - | - | - | - |
+| **aria-hidden** | ✓ | - | - | - | ✓ | - | - | - | ✓ | - | - | - | - | - |
+| **data-slot** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **CVA variants** | ✓ | - | - | - | - | - | - | - | ✓ | - | - | - | - | - |
+| **Responsive** | ✓ | - | - | - | ✓ | - | - | - | - | - | - | - | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Via className/Box | - = Não possui
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | Mantine | AntD | NextUI |
+|------|:----:|:------:|:-------:|:----:|:------:|
+| `size` | ✓ | - | `h`/`w` | `size` | - |
+| `axis` | ✓ | - | - | `direction` | - |
+| `flex` | ✓ | ✓ | - | - | - |
+| `h` (altura) | ~ | ✓ | ✓ | - | - |
+| `w` (largura) | ~ | ✓ | ✓ | - | - |
+| `x` (horizontal) | - | - | - | - | ✓ |
+| `y` (vertical) | - | - | - | - | ✓ |
+
+#### Abordagens por Design System
+
+| Design System | Abordagem | Notas |
+|---------------|-----------|-------|
+| **Chakra UI** | `<Spacer />` flex grow | Expande para preencher espaço, sem size props |
+| **Mantine** | `<Space h="md" />` | Props `h` e `w` para altura/largura |
+| **Ant Design** | `<Space direction size />` | Wrapper para filhos com gap |
+| **NextUI** | `<Spacer x={1} y={2} />` | Props numéricas para spacing scale |
+| **MUI** | Box/Stack spacing | Sem componente dedicado, usa spacing prop |
+| **Tailwind/Shadcn** | Gap utilities | Sem componente, usa classes CSS |
+| **ETUS** | `<Spacer size axis />` | Semantic tokens, CVA variants |
+
+#### Análise por Categoria
+
+**Spacer Dedicado (componente explícito):**
+
+- **Chakra UI** - Flex spacer, expande automaticamente
+- **Mantine** - Space com dimensões explícitas
+- **NextUI** - Props x/y para eixos
+- **ETUS** - Size tokens + axis + flex modes
+
+**Gap-based (espaçamento no container):**
+
+- **MUI** - Stack/Box com spacing prop
+- **Shadcn/ui** - Tailwind gap utilities
+- **Radix** - Sem solução própria
+
+**Wrapper (espaço entre filhos):**
+
+- **Ant Design** - Space wrapper com direction/size
+- **Headless UI** - Sem solução própria
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Valor | Propósito |
+|----------|-------|-----------|
+| `aria-hidden` | `"true"` | Oculta de leitores de tela |
+| `role` | Nenhum | Elemento decorativo |
+
+### Por que `aria-hidden="true"`?
+
+O Spacer é um elemento puramente visual/de layout sem significado semântico. Leitores de tela devem ignorá-lo completamente:
+
+```tsx
+// Implementação correta
+<div aria-hidden="true" data-slot="spacer" className={...} />
+```
+
+### Suporte a Teclado
+
+O Spacer não é interativo e não participa da navegação por teclado. Ele é automaticamente ignorado na ordem de tabulação.
+
+### Screen Readers
+
+- Completamente ignorado devido a `aria-hidden="true"`
+- Não adiciona ruído na leitura do conteúdo
+- Espaçamento visual não afeta a experiência auditiva
+
+### Contraste de Cores
+
+Não aplicável - o Spacer é invisível e não possui cor.
+
+### Reduced Motion
+
+Não aplicável - o Spacer não possui animações.
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | Chakra | Mantine | AntD | NextUI | MUI |
+|---------|:----:|:------:|:-------:|:----:|:------:|:---:|
+| **aria-hidden** | ✓ | ✓ | - | - | ✓ | - |
+| **role=none** | - | - | - | - | - | - |
+| **Semanticamente neutro** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Não focável** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Spacer } from "@etus/ui"
+
+function Example() {
+  return (
+    <div>
+      <h1>Título</h1>
+      <Spacer />
+      <p>Parágrafo separado por espaçamento padrão (md).</p>
+    </div>
+  )
+}
+```
+
+### Tamanhos (Tokens)
+
+```tsx
+<div className="flex flex-col">
+  <div>Item 1</div>
+  <Spacer size="xs" /> {/* 8px */}
+  <div>Item 2</div>
+  <Spacer size="sm" /> {/* 16px */}
+  <div>Item 3</div>
+  <Spacer size="md" /> {/* 24px - padrão */}
+  <div>Item 4</div>
+  <Spacer size="lg" /> {/* 32px */}
+  <div>Item 5</div>
+  <Spacer size="xl" /> {/* 48px */}
+  <div>Item 6</div>
+  <Spacer size="2xl" /> {/* 64px */}
+  <div>Item 7</div>
+</div>
+```
+
+### Tamanhos (Numéricos)
+
+```tsx
+// Número puro (interpretado como pixels)
+<Spacer size={20} />  {/* 20px */}
+<Spacer size={100} /> {/* 100px */}
+
+// Valores com unidade
+<Spacer size="24px" />   {/* 24px */}
+<Spacer size="2rem" />   {/* 2rem */}
+<Spacer size="1.5em" />  {/* 1.5em */}
+
+// Combina com axis
+<Spacer size={40} axis="horizontal" />
+<Spacer size="3rem" axis="both" />
+```
+
+### Horizontal (em Flex Row)
+
+```tsx
+<div className="flex items-center">
+  <Logo />
+  <Spacer axis="horizontal" size="lg" />
+  <nav>Navigation</nav>
+  <Spacer axis="horizontal" flex="grow" />
+  <UserMenu />
+</div>
+```
+
+### Flex Grow (Push Apart)
+
+```tsx
+// Header com logo à esquerda e menu à direita
+<header className="flex items-center px-4 h-16">
+  <Logo />
+  <Spacer axis="horizontal" flex="grow" />
+  <nav className="flex gap-4">
+    <a href="/about">About</a>
+    <a href="/contact">Contact</a>
+  </nav>
+</header>
+```
+
+### Em Cards
+
+```tsx
+import { Card, CardHeader, CardContent, CardFooter } from "@etus/ui"
+import { Spacer } from "@etus/ui"
+
+function CardExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <h3>Título do Card</h3>
+      </CardHeader>
+      <CardContent>
+        <p>Primeiro parágrafo de conteúdo.</p>
+        <Spacer size="sm" />
+        <p>Segundo parágrafo com espaçamento.</p>
+        <Spacer size="md" />
+        <ul>
+          <li>Item 1</li>
+          <li>Item 2</li>
+        </ul>
+      </CardContent>
+      <Spacer size="lg" />
+      <CardFooter>
+        <button>Ação</button>
+      </CardFooter>
+    </Card>
+  )
+}
+```
+
+### Em Formulários
+
+```tsx
+import { Input, Label, Button, Spacer } from "@etus/ui"
+
+function FormExample() {
+  return (
+    <form className="flex flex-col">
+      <div>
+        <Label htmlFor="name">Nome</Label>
+        <Input id="name" />
+      </div>
+
+      <Spacer size="md" />
+
+      <div>
+        <Label htmlFor="email">Email</Label>
+        <Input id="email" type="email" />
+      </div>
+
+      <Spacer size="lg" />
+
+      <Button type="submit">Enviar</Button>
+    </form>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+// Espaçamento que muda por breakpoint via className
+<Spacer className="h-4 md:h-8 lg:h-12" />
+
+// Ou usando size com override
+<Spacer size="sm" className="md:h-8 lg:h-12" />
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <Spacer className="h-4 @md:h-8 @lg:h-12" />
+</div>
+```
+
+### Em Layouts de Página
+
+```tsx
+function PageLayout() {
+  return (
+    <main className="flex flex-col min-h-screen">
+      <Header />
+
+      <Spacer size="xl" />
+
+      <section>
+        <h2>Seção 1</h2>
+        <p>Conteúdo...</p>
+      </section>
+
+      <Spacer size="2xl" />
+
+      <section>
+        <h2>Seção 2</h2>
+        <p>Conteúdo...</p>
+      </section>
+
+      <Spacer flex="grow" />
+
+      <Footer />
+    </main>
+  )
+}
+```
+
+### Combinado com Separator
+
+```tsx
+// Spacer para espaçamento, Separator para divisão visual
+<section>
+  <h2>Título da Seção</h2>
+  <p>Conteúdo da seção...</p>
+</section>
+
+<Spacer size="lg" />
+<Separator />
+<Spacer size="lg" />
+
+<section>
+  <h2>Próxima Seção</h2>
+  <p>Mais conteúdo...</p>
+</section>
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Spacer.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Spacer } from "./Spacer"
+
+describe("Spacer", () => {
+  it("renders correctly", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toBeInTheDocument()
+  })
+
+  it("has aria-hidden attribute", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveAttribute("aria-hidden", "true")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveAttribute("data-slot", "spacer")
+  })
+
+  it("applies default size (md) classes", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("h-6")
+  })
+
+  it("applies size variant classes", () => {
+    render(<Spacer size="lg" data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("h-8")
+  })
+
+  it("applies horizontal axis classes", () => {
+    render(<Spacer axis="horizontal" size="md" data-testid="spacer" />)
+    const spacer = screen.getByTestId("spacer")
+    expect(spacer).toHaveClass("w-6")
+    expect(spacer).toHaveClass("h-full")
+  })
+
+  it("applies flex grow class", () => {
+    render(<Spacer flex="grow" data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("flex-grow")
+  })
+
+  it("merges custom className", () => {
+    render(<Spacer className="my-custom-class" data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("my-custom-class")
+  })
+
+  it("has shrink-0 by default", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("shrink-0")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Spacer accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Spacer />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("is hidden from screen readers", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveAttribute("aria-hidden", "true")
+  })
+
+  it("is not focusable", () => {
+    render(<Spacer data-testid="spacer" />)
+    const spacer = screen.getByTestId("spacer")
+    expect(spacer).not.toHaveAttribute("tabindex")
+    spacer.focus()
+    expect(spacer).not.toHaveFocus()
+  })
+
+  it("does not have interactive role", () => {
+    render(<Spacer data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).not.toHaveAttribute("role")
+  })
+})
+```
+
+### Testes de Layout
+
+```tsx
+describe("Spacer in layout context", () => {
+  it("works in vertical flex container", () => {
+    render(
+      <div className="flex flex-col" data-testid="container">
+        <div>Item 1</div>
+        <Spacer size="md" data-testid="spacer" />
+        <div>Item 2</div>
+      </div>
+    )
+
+    expect(screen.getByTestId("spacer")).toHaveClass("h-6", "w-full")
+  })
+
+  it("works in horizontal flex container", () => {
+    render(
+      <div className="flex" data-testid="container">
+        <div>Item 1</div>
+        <Spacer axis="horizontal" size="md" data-testid="spacer" />
+        <div>Item 2</div>
+      </div>
+    )
+
+    expect(screen.getByTestId("spacer")).toHaveClass("w-6", "h-full")
+  })
+
+  it("grows to fill space when flex=grow", () => {
+    render(
+      <div className="flex" data-testid="container">
+        <div>Left</div>
+        <Spacer axis="horizontal" flex="grow" data-testid="spacer" />
+        <div>Right</div>
+      </div>
+    )
+
+    expect(screen.getByTestId("spacer")).toHaveClass("flex-grow")
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Spacer edge cases", () => {
+  it("handles ref correctly", () => {
+    const ref = { current: null }
+    render(<Spacer ref={ref} />)
+    expect(ref.current).toBeInstanceOf(HTMLDivElement)
+  })
+
+  it("renders with all size variants", () => {
+    const sizes = ["xs", "sm", "md", "lg", "xl", "2xl"] as const
+
+    sizes.forEach((size) => {
+      const { unmount } = render(
+        <Spacer size={size} data-testid="spacer" />
+      )
+      expect(screen.getByTestId("spacer")).toBeInTheDocument()
+      unmount()
+    })
+  })
+
+  it("renders with both axis", () => {
+    render(<Spacer axis="both" size="md" data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("size-6")
+  })
+
+  it("spreads additional props", () => {
+    render(<Spacer data-testid="spacer" data-custom="value" />)
+    expect(screen.getByTestId("spacer")).toHaveAttribute("data-custom", "value")
+  })
+
+  it("applies className override for responsive sizes", () => {
+    render(<Spacer className="h-4 md:h-8" data-testid="spacer" />)
+    expect(screen.getByTestId("spacer")).toHaveClass("h-4", "md:h-8")
+  })
+})
+```
+
+---
+
+## Implementação de Referência
+
+```tsx
+// Spacer.tsx
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const spacerVariants = cva("shrink-0", {
+  variants: {
+    size: {
+      xs: "",
+      sm: "",
+      md: "",
+      lg: "",
+      xl: "",
+      "2xl": "",
+    },
+    axis: {
+      vertical: "w-full",
+      horizontal: "h-full",
+      both: "",
+    },
+    flex: {
+      none: "",
+      grow: "flex-grow",
+      shrink: "flex-shrink",
+    },
+  },
+  compoundVariants: [
+    // Vertical sizes
+    { axis: "vertical", size: "xs", class: "h-2" },
+    { axis: "vertical", size: "sm", class: "h-4" },
+    { axis: "vertical", size: "md", class: "h-6" },
+    { axis: "vertical", size: "lg", class: "h-8" },
+    { axis: "vertical", size: "xl", class: "h-12" },
+    { axis: "vertical", size: "2xl", class: "h-16" },
+    // Horizontal sizes
+    { axis: "horizontal", size: "xs", class: "w-2" },
+    { axis: "horizontal", size: "sm", class: "w-4" },
+    { axis: "horizontal", size: "md", class: "w-6" },
+    { axis: "horizontal", size: "lg", class: "w-8" },
+    { axis: "horizontal", size: "xl", class: "w-12" },
+    { axis: "horizontal", size: "2xl", class: "w-16" },
+    // Both sizes
+    { axis: "both", size: "xs", class: "size-2" },
+    { axis: "both", size: "sm", class: "size-4" },
+    { axis: "both", size: "md", class: "size-6" },
+    { axis: "both", size: "lg", class: "size-8" },
+    { axis: "both", size: "xl", class: "size-12" },
+    { axis: "both", size: "2xl", class: "size-16" },
+  ],
+  defaultVariants: {
+    size: "md",
+    axis: "vertical",
+    flex: "none",
+  },
+})
+
+interface SpacerProps
+  extends React.ComponentProps<"div">,
+    VariantProps<typeof spacerVariants> {}
+
+function Spacer({
+  className,
+  size,
+  axis,
+  flex,
+  ref,
+  ...props
+}: SpacerProps) {
+  return (
+    <div
+      ref={ref}
+      aria-hidden="true"
+      data-slot="spacer"
+      className={cn(spacerVariants({ size, axis, flex }), className)}
+      {...props}
+    />
+  )
+}
+
+export { Spacer, spacerVariants, type SpacerProps }
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### ✅ Implementado
+
+#### Valor numérico para `size`
+
+Suporte a valores numéricos além dos tokens semânticos.
+
+```tsx
+// Número puro (interpretado como pixels)
+<Spacer size={20} />    {/* 20px */}
+<Spacer size={100} />   {/* 100px */}
+
+// Strings com unidade
+<Spacer size="24px" />  {/* 24px */}
+<Spacer size="2rem" />  {/* 2rem */}
+<Spacer size="1.5em" /> {/* 1.5em */}
+
+// Tokens continuam funcionando
+<Spacer size="md" />    {/* 24px via Tailwind class */}
+```
+
+**Referências:** NextUI (`x={1}`, `y={2}`), Chakra (spacing scale)
+
+### Prioridade Baixa
+
+#### `inline`
+
+Renderizar como `span` em vez de `div`.
+
+```tsx
+// Proposta de API
+interface SpacerProps {
+  inline?: boolean
+}
+
+// Uso
+<p>
+  Texto com <Spacer inline axis="horizontal" size="xs" /> espaço.
+</p>
+```
+
+#### `show` (Debug Mode)
+
+Visualizar o spacer durante desenvolvimento.
+
+```tsx
+// Proposta de API
+interface SpacerProps {
+  show?: boolean
+}
+
+// Uso (apenas dev)
+<Spacer size="lg" show />
+// Renderiza com bg-pink-200/50 para visualização
+```
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| Size tokens | ✓ Implementado | Consistência com design system |
+| Axis prop | ✓ Implementado | Flexibilidade vertical/horizontal |
+| Flex modes | ✓ Implementado | Casos de uso comuns (push apart) |
+| Numeric size | ⚠️ Avaliar | Flexibilidade vs consistência |
+| inline prop | ⚠️ Avaliar | Casos de uso limitados |
+| show/debug | ❌ Evitar | DevTools resolve melhor |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Componente | Documentação | GitHub |
+|---------------|------------|--------------|--------|
+| **Chakra UI** | Spacer | [Spacer](https://chakra-ui.com/docs/components/spacer) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Mantine** | Space | [Space](https://mantine.dev/core/space/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | Space | [Space](https://ant.design/components/space) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | Spacer | [Spacer](https://nextui.org/docs/components/spacer) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **MUI** | Stack spacing | [Stack](https://mui.com/material-ui/react-stack/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Tailwind CSS** | Gap utilities | [Gap](https://tailwindcss.com/docs/gap) | [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss) |
+| **Radix UI** | - | Sem componente dedicado | - |
+| **React Aria** | - | Sem componente dedicado | - |
+| **Fluent UI** | Stack | [Stack](https://react.fluentui.dev/?path=/docs/components-stack) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | - | Spacing tokens | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | - | Sem componente dedicado | - |
+
+### Especificações e Padrões
+
+- [CSS Box Model](https://www.w3.org/TR/css-box-3/)
+- [CSS Flexbox](https://www.w3.org/TR/css-flexbox-1/)
+- [Tailwind Spacing Scale](https://tailwindcss.com/docs/customizing-spacing)
+- [ARIA Hidden](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [cn utility](https://ui.shadcn.com/docs/installation#add-a-cn-helper)