@etus/ui 0.1.0 → 0.1.2

package/src/components/layout/Flex/README.md

@@ -1,812 +0,0 @@
-# Flex
-
-## Visão Geral
-
-O **Flex** é um componente utilitário de layout que fornece uma API declarativa para CSS Flexbox. Como componente de layout, simplifica a criação de layouts flexíveis e responsivos sem necessidade de escrever classes CSS manualmente.
-
-### Casos de Uso
-
-- Layouts de header com logo à esquerda e navegação à direita
-- Centralização de conteúdo vertical e horizontalmente
-- Stacks verticais e horizontais com espaçamento consistente
-- Navegação com items igualmente espaçados
-- Card layouts com alinhamento flexível
-- Toolbars e action bars
-
-### Classificação
-
-**Categoria:** Layout
-**Dependências:** `class-variance-authority`
-
----
-
-## Design Specs
-
-### Display (`inline`)
-
-| Modo | Prop | Classes | Uso |
-|------|------|---------|-----|
-| Block | `inline={false}` | `flex` | Container de bloco (padrão) |
-| Inline | `inline={true}` | `inline-flex` | Container inline |
-
-### Direção (`direction`)
-
-| Valor | Classes | Uso |
-|-------|---------|-----|
-| `row` | `flex-row` | Items em linha (padrão) |
-| `row-reverse` | `flex-row-reverse` | Items em linha reversa |
-| `col` | `flex-col` | Items em coluna |
-| `col-reverse` | `flex-col-reverse` | Items em coluna reversa |
-
-### Alinhamento Principal (`justify`)
-
-| Valor | Classes | CSS | Uso |
-|-------|---------|-----|-----|
-| `start` | `justify-start` | `justify-content: flex-start` | Items no início (padrão) |
-| `center` | `justify-center` | `justify-content: center` | Items no centro |
-| `end` | `justify-end` | `justify-content: flex-end` | Items no final |
-| `between` | `justify-between` | `justify-content: space-between` | Espaço entre items |
-| `around` | `justify-around` | `justify-content: space-around` | Espaço ao redor |
-| `evenly` | `justify-evenly` | `justify-content: space-evenly` | Espaço igual |
-
-### Alinhamento Cruzado (`align`)
-
-| Valor | Classes | CSS | Uso |
-|-------|---------|-----|-----|
-| `start` | `items-start` | `align-items: flex-start` | Items no início |
-| `center` | `items-center` | `align-items: center` | Items centralizados |
-| `end` | `items-end` | `align-items: flex-end` | Items no final |
-| `baseline` | `items-baseline` | `align-items: baseline` | Alinhamento por baseline |
-| `stretch` | `items-stretch` | `align-items: stretch` | Items esticados (padrão) |
-
-### Quebra de Linha (`wrap`)
-
-| Valor | Classes | Uso |
-|-------|---------|-----|
-| `false` / `nowrap` | `flex-nowrap` | Sem quebra (padrão) |
-| `true` / `wrap` | `flex-wrap` | Permite quebra |
-| `wrap-reverse` | `flex-wrap-reverse` | Quebra reversa |
-
-### Espaçamento (`gap`)
-
-| Valor | Classes | Pixels | Uso |
-|-------|---------|--------|-----|
-| `0` | `gap-0` | 0px | Sem espaço |
-| `1` | `gap-1` | 4px | Espaço mínimo |
-| `2` | `gap-2` | 8px | Espaço pequeno |
-| `3` | `gap-3` | 12px | Espaço médio-pequeno |
-| `4` | `gap-4` | 16px | Espaço médio |
-| `6` | `gap-6` | 24px | Espaço grande |
-| `8` | `gap-8` | 32px | Espaço extra grande |
-
-### data-slot
-
-```html
-<div data-slot="flex">...</div>
-```
-
----
-
-## API
-
-### Props
-
-| Prop | Tipo | Padrão | Descrição |
-|------|------|--------|-----------|
-| `as` | `FlexElement` | `"div"` | Elemento HTML a renderizar |
-| `inline` | `boolean` | `false` | Usar `inline-flex` ao invés de `flex` |
-| `direction` | `"row" \| "row-reverse" \| "col" \| "col-reverse"` | `"row"` | Direção do flex |
-| `justify` | `"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"` | `"start"` | Alinhamento no eixo principal |
-| `align` | `"start" \| "center" \| "end" \| "baseline" \| "stretch"` | `"stretch"` | Alinhamento no eixo cruzado |
-| `wrap` | `boolean \| "wrap" \| "nowrap" \| "wrap-reverse"` | `false` | Comportamento de quebra |
-| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 6 \| 8` | - | Espaçamento entre items |
-| `className` | `string` | - | Classes CSS adicionais |
-| `children` | `ReactNode` | - | Conteúdo |
-
-> Herda todas as props de `React.HTMLAttributes<HTMLElement>`
-
-### Elementos Permitidos (`as`)
-
-```typescript
-type FlexElement =
-  | "article"
-  | "aside"
-  | "div"
-  | "footer"
-  | "header"
-  | "main"
-  | "nav"
-  | "ol"
-  | "section"
-  | "span"
-  | "ul"
-```
-
-### TypeScript
-
-```typescript
-import type { VariantProps } from "class-variance-authority"
-
-// Variants exportadas
-const flexVariants = cva(/* ... */)
-
-// Props do componente
-interface FlexProps
-  extends Omit<HTMLAttributes<HTMLElement>, "wrap">,
-    Omit<VariantProps<typeof flexVariants>, "display"> {
-  as?: FlexElement
-  inline?: boolean
-}
-
-// Tipos derivados úteis
-type FlexDirection = "row" | "row-reverse" | "col" | "col-reverse"
-type FlexJustify = "start" | "center" | "end" | "between" | "around" | "evenly"
-type FlexAlign = "start" | "center" | "end" | "baseline" | "stretch"
-type FlexWrap = boolean | "wrap" | "nowrap" | "wrap-reverse"
-type FlexGap = 0 | 1 | 2 | 3 | 4 | 6 | 8
-```
-
-### Comparativo com Design Systems de Referência
-
-#### Matriz de Features (12 Design Systems)
-
-| Feature | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Radix | Styled System | Theme UI | Rebass |
-|---------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:-----:|:-------------:|:--------:|:------:|
-| **Flex Component** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | ✓ | ✓ |
-| **direction prop** | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - | - | ✓ | ✓ | ✓ |
-| **justify prop** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | ✓ | ✓ | ✓ |
-| **align prop** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | ✓ | ✓ | ✓ |
-| **wrap prop** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | ✓ | ✓ | ✓ |
-| **gap prop** | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | - | - | ✓ | ✓ | - |
-| **as/component** | ✓ | ✓ | ✓ | ✓ | - | - | - | - | - | ✓ | ✓ | ✓ |
-| **inline variant** | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - |
-| **CVA variants** | ✓ | - | - | - | - | - | - | - | - | - | - | - |
-| **data-slot** | ✓ | - | - | - | - | - | - | - | - | - | - | - |
-| **Style props** | - | ✓ | ✓ | - | - | - | - | - | - | ✓ | ✓ | ✓ |
-| **Responsive props** | - | ✓ | ✓ | - | - | - | - | - | - | ✓ | ✓ | ✓ |
-
-#### Comparativo de Props por Design System
-
-| Prop ETUS | Chakra | MUI Stack | Mantine Flex | Fluent | Theme UI |
-|-----------|:------:|:---------:|:------------:|:------:|:--------:|
-| `direction` | `direction` | `direction` | `direction` | `direction` | `flexDirection` |
-| `justify` | `justify` | `justifyContent` | `justify` | `justifyContent` | `justifyContent` |
-| `align` | `align` | `alignItems` | `align` | `alignItems` | `alignItems` |
-| `wrap` | `wrap` | `flexWrap` | `wrap` | `wrap` | `flexWrap` |
-| `gap` | `gap` / `spacing` | `spacing` | `gap` | `gap` | `gap` / `gridGap` |
-| `as` | `as` | `component` | `component` | - | `as` |
-| `inline` | - | - | - | `inline` | - |
-
-#### Abordagens de Layout por Design System
-
-| Design System | Abordagem | Tipo | Características |
-|---------------|-----------|------|-----------------|
-| **ETUS** | CVA + Tailwind | Variants | Props mapeiam para classes, tipagem forte |
-| **Chakra UI** | Style Props | Runtime | `<Flex direction="row" p={4}>` |
-| **MUI Stack** | sx + spacing | Runtime | Sistema de grid com spacing numérico |
-| **Mantine Flex** | Props + Styles API | Hybrid | Props simples + styles API para casos complexos |
-| **Styled System** | Style Props | Runtime | Primitivo base para sistemas de design |
-| **Theme UI** | sx prop | Runtime | Baseado em Styled System + theme-aware |
-| **Rebass** | Style Props | Runtime | Minimal, baseado em Styled System |
-| **Fluent UI** | Tokens | Styled | Design tokens do Microsoft Design |
-| **Ant Design** | Row/Col + Flex | Class-based | Sistema de grid tradicional |
-| **Carbon** | CSS Grid | Class-based | Foco em grid 16 colunas |
-
----
-
-## Acessibilidade (A11y)
-
-### Semântica com `as` prop
-
-O Flex suporta elementos semânticos via prop `as`:
-
-| Elemento | Role | Uso Recomendado |
-|----------|------|-----------------|
-| `nav` | `navigation` | Navegação principal ou secundária |
-| `header` | `banner` | Cabeçalho da página |
-| `footer` | `contentinfo` | Rodapé da página |
-| `main` | `main` | Conteúdo principal |
-| `section` | `region` | Seções de conteúdo (com `aria-label`) |
-| `aside` | `complementary` | Conteúdo lateral |
-| `article` | `article` | Conteúdo independente |
-| `ul`/`ol` | `list` | Listas de items |
-
-### ARIA Attributes
-
-| Atributo | Uso |
-|----------|-----|
-| `aria-label` | Descrição para `<nav>` e `<section>` |
-| `role="list"` | Quando usar `as="ul"` ou `as="ol"` com estilos que removem bullets |
-| `role="listitem"` | Nos filhos de listas estilizadas |
-
-### Focus Management
-
-Flex é um componente de layout e não recebe foco diretamente. O foco é gerenciado pelos elementos filhos interativos.
-
-### Screen Readers
-
-- Use elementos semânticos (`nav`, `header`, etc.) quando apropriado
-- Adicione `aria-label` para seções sem título visível
-- Mantenha ordem lógica do DOM mesmo com `direction="row-reverse"`
-
-### Conformidade WCAG
-
-- **Critério 1.3.2 - Sequência Significativa**: Evitar reordenação visual (`*-reverse`) que não reflita ordem do DOM
-- **Critério 2.4.3 - Ordem do Foco**: Foco deve seguir sequência lógica
-
-### Comparativo A11y (12 Design Systems)
-
-| Feature | ETUS | Chakra | MUI | Mantine | Fluent | Carbon | Theme UI |
-|---------|:----:|:------:|:---:|:-------:|:------:|:------:|:--------:|
-| **Polymorphic** | ✓ | ✓ | ✓ | ✓ | - | - | ✓ |
-| **Semantic HTML** | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ |
-| **ARIA support** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| **Role inheritance** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-
-**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
-
----
-
-## Exemplos
-
-### Uso Básico
-
-```tsx
-import { Flex } from "@etus/ui"
-
-function Example() {
-  return (
-    <Flex gap={4}>
-      <div>Item 1</div>
-      <div>Item 2</div>
-      <div>Item 3</div>
-    </Flex>
-  )
-}
-```
-
-### Centralização
-
-```tsx
-// Centralização completa (horizontal e vertical)
-<Flex justify="center" align="center" className="h-screen">
-  <div>Centralizado</div>
-</Flex>
-
-// Apenas horizontal
-<Flex justify="center">
-  <div>Horizontalmente centralizado</div>
-</Flex>
-
-// Apenas vertical
-<Flex align="center" className="h-64">
-  <div>Verticalmente centralizado</div>
-</Flex>
-```
-
-### Direções
-
-```tsx
-// Linha (padrão)
-<Flex direction="row" gap={4}>
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-</Flex>
-
-// Coluna
-<Flex direction="col" gap={4}>
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-</Flex>
-
-// Linha reversa
-<Flex direction="row-reverse" gap={4}>
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-</Flex>
-
-// Coluna reversa
-<Flex direction="col-reverse" gap={4}>
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-</Flex>
-```
-
-### Distribuição de Espaço
-
-```tsx
-// Espaço entre items
-<Flex justify="between">
-  <div>Esquerda</div>
-  <div>Direita</div>
-</Flex>
-
-// Espaço ao redor
-<Flex justify="around">
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-</Flex>
-
-// Espaço igual
-<Flex justify="evenly">
-  <div>1</div>
-  <div>2</div>
-  <div>3</div>
-</Flex>
-```
-
-### Header Layout
-
-```tsx
-<Flex
-  as="header"
-  justify="between"
-  align="center"
-  className="p-4 border-b"
->
-  <div>Logo</div>
-  <Flex as="nav" gap={4} aria-label="Main Navigation">
-    <a href="/">Home</a>
-    <a href="/about">About</a>
-    <a href="/contact">Contact</a>
-  </Flex>
-  <Button>Login</Button>
-</Flex>
-```
-
-### Card com Footer
-
-```tsx
-<Flex direction="col" className="rounded-lg border p-4 h-64">
-  <div className="flex-1">
-    <h3>Card Title</h3>
-    <p>Card content goes here.</p>
-  </div>
-  <Flex justify="end" gap={2}>
-    <Button variant="outline">Cancel</Button>
-    <Button>Save</Button>
-  </Flex>
-</Flex>
-```
-
-### Navigation
-
-```tsx
-<Flex
-  as="nav"
-  aria-label="Main navigation"
-  justify="center"
-  gap={6}
->
-  <a href="/" className="text-sm font-medium">Home</a>
-  <a href="/products" className="text-sm font-medium">Products</a>
-  <a href="/about" className="text-sm font-medium">About</a>
-  <a href="/contact" className="text-sm font-medium">Contact</a>
-</Flex>
-```
-
-### Lista com Flex
-
-```tsx
-<Flex as="ul" direction="col" gap={2}>
-  <li>Item 1</li>
-  <li>Item 2</li>
-  <li>Item 3</li>
-</Flex>
-```
-
-### Wrap para Responsividade
-
-```tsx
-<Flex wrap gap={4}>
-  <div className="w-48 h-32 bg-muted rounded" />
-  <div className="w-48 h-32 bg-muted rounded" />
-  <div className="w-48 h-32 bg-muted rounded" />
-  <div className="w-48 h-32 bg-muted rounded" />
-</Flex>
-```
-
-### Inline Flex
-
-```tsx
-<p>
-  Texto com{" "}
-  <Flex inline align="center" gap={1}>
-    <Icon name="star" size={16} />
-    <span>ícone inline</span>
-  </Flex>{" "}
-  no meio.
-</p>
-```
-
-### Toolbar
-
-```tsx
-<Flex
-  justify="between"
-  align="center"
-  className="p-2 bg-muted rounded"
->
-  <Flex gap={2}>
-    <Button size="icon-sm" variant="ghost">
-      <BoldIcon />
-    </Button>
-    <Button size="icon-sm" variant="ghost">
-      <ItalicIcon />
-    </Button>
-    <Button size="icon-sm" variant="ghost">
-      <UnderlineIcon />
-    </Button>
-  </Flex>
-  <Flex gap={2}>
-    <Button size="sm" variant="outline">Cancel</Button>
-    <Button size="sm">Save</Button>
-  </Flex>
-</Flex>
-```
-
-### Responsivo via className
-
-```tsx
-<Flex
-  direction="col"
-  className="sm:flex-row"
-  gap={4}
->
-  <div className="flex-1 bg-muted p-4 rounded">Coluna 1</div>
-  <div className="flex-1 bg-muted p-4 rounded">Coluna 2</div>
-  <div className="flex-1 bg-muted p-4 rounded">Coluna 3</div>
-</Flex>
-```
-
-### Composição com Outros Componentes
-
-```tsx
-import { Flex, Card, Avatar, Badge, Button } from "@etus/ui"
-
-function UserCard({ user }) {
-  return (
-    <Card>
-      <Flex gap={4} align="center">
-        <Avatar src={user.avatar} name={user.name} />
-        <Flex direction="col" gap={1} className="flex-1">
-          <Flex gap={2} align="center">
-            <span className="font-medium">{user.name}</span>
-            <Badge variant="secondary">{user.role}</Badge>
-          </Flex>
-          <span className="text-sm text-muted-foreground">{user.email}</span>
-        </Flex>
-        <Button variant="outline" size="sm">View Profile</Button>
-      </Flex>
-    </Card>
-  )
-}
-```
-
----
-
-## Testes
-
-### Testes Unitários
-
-```tsx
-// Flex.test.tsx
-import { render, screen } from "@testing-library/react"
-import { describe, expect, it } from "vitest"
-import { Flex } from "./Flex"
-
-describe("Flex", () => {
-  it("renders children correctly", () => {
-    render(<Flex>Flex Content</Flex>)
-    expect(screen.getByText("Flex Content")).toBeInTheDocument()
-  })
-
-  it("applies flex display by default", () => {
-    render(<Flex data-testid="flex">Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("flex")
-  })
-
-  it("applies direction classes", () => {
-    render(<Flex data-testid="flex" direction="col">Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("flex-col")
-  })
-
-  it("has data-slot attribute", () => {
-    render(<Flex data-testid="flex">Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveAttribute("data-slot", "flex")
-  })
-})
-```
-
-### Testes de Variantes
-
-```tsx
-describe("Flex variants", () => {
-  it("applies justify-center", () => {
-    render(<Flex data-testid="flex" justify="center">Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("justify-center")
-  })
-
-  it("applies items-center", () => {
-    render(<Flex data-testid="flex" align="center">Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("items-center")
-  })
-
-  it("applies gap classes", () => {
-    render(<Flex data-testid="flex" gap={4}>Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("gap-4")
-  })
-
-  it("applies wrap classes", () => {
-    render(<Flex data-testid="flex" wrap>Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("flex-wrap")
-  })
-
-  it("applies inline-flex when inline", () => {
-    render(<Flex data-testid="flex" inline>Content</Flex>)
-    expect(screen.getByTestId("flex")).toHaveClass("inline-flex")
-  })
-})
-```
-
-### Testes de Polimorfismo
-
-```tsx
-describe("Flex as prop", () => {
-  it("renders as div by default", () => {
-    render(<Flex data-testid="flex">Content</Flex>)
-    expect(screen.getByTestId("flex").tagName).toBe("DIV")
-  })
-
-  it("renders as nav element", () => {
-    render(<Flex as="nav">Navigation</Flex>)
-    expect(screen.getByRole("navigation")).toBeInTheDocument()
-  })
-
-  it("renders as header element", () => {
-    render(<Flex as="header">Header</Flex>)
-    expect(screen.getByRole("banner")).toBeInTheDocument()
-  })
-
-  it("renders as ul element", () => {
-    render(<Flex as="ul" data-testid="flex"><li>Item</li></Flex>)
-    expect(screen.getByTestId("flex").tagName).toBe("UL")
-  })
-})
-```
-
-### Testes de Acessibilidade
-
-```tsx
-import { axe, toHaveNoViolations } from "jest-axe"
-
-expect.extend(toHaveNoViolations)
-
-describe("Flex accessibility", () => {
-  it("has no accessibility violations", async () => {
-    const { container } = render(
-      <Flex gap={4}>
-        <div>Item 1</div>
-        <div>Item 2</div>
-      </Flex>
-    )
-    const results = await axe(container)
-    expect(results).toHaveNoViolations()
-  })
-
-  it("has no violations as navigation", async () => {
-    const { container } = render(
-      <Flex as="nav" aria-label="Main Navigation" gap={4}>
-        <a href="/home">Home</a>
-        <a href="/about">About</a>
-      </Flex>
-    )
-    const results = await axe(container)
-    expect(results).toHaveNoViolations()
-  })
-})
-```
-
-### Testes de Composição
-
-```tsx
-describe("Flex composition", () => {
-  it("combines multiple variants", () => {
-    render(
-      <Flex
-        data-testid="flex"
-        direction="col"
-        justify="center"
-        align="center"
-        gap={4}
-      >
-        Content
-      </Flex>
-    )
-    const flex = screen.getByTestId("flex")
-    expect(flex).toHaveClass("flex-col", "justify-center", "items-center", "gap-4")
-  })
-
-  it("merges custom className with variants", () => {
-    render(
-      <Flex data-testid="flex" className="w-full p-4" gap={4}>
-        Content
-      </Flex>
-    )
-    expect(screen.getByTestId("flex")).toHaveClass("w-full", "p-4", "gap-4")
-  })
-})
-```
-
----
-
-## Roadmap / Features Futuras
-
-Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
-
-### Prioridade Alta
-
-#### `gapX` / `gapY`
-
-Controle independente de gap horizontal e vertical.
-
-```tsx
-// Proposta de API
-interface FlexProps {
-  gapX?: 0 | 1 | 2 | 3 | 4 | 6 | 8
-  gapY?: 0 | 1 | 2 | 3 | 4 | 6 | 8
-}
-
-// Uso
-<Flex gapX={4} gapY={2}>
-  <div>Item 1</div>
-  <div>Item 2</div>
-</Flex>
-
-// Equivalente atual via className
-<Flex className="gap-x-4 gap-y-2">
-  <div>Item 1</div>
-  <div>Item 2</div>
-</Flex>
-```
-
-**Referências:** Chakra (`columnGap`, `rowGap`), MUI (`spacing` object), Tailwind (`gap-x-*`, `gap-y-*`)
-
-#### Valores de Gap Adicionais
-
-```tsx
-// Proposta: Adicionar gap 5, 10, 12, 16
-gap: {
-  5: "gap-5",   // 20px
-  10: "gap-10", // 40px
-  12: "gap-12", // 48px
-  16: "gap-16", // 64px
-}
-```
-
-**Referências:** Tailwind spacing scale, Chakra space scale
-
-### Prioridade Média
-
-#### `basis` / `grow` / `shrink`
-
-Props para controle de flex items.
-
-```tsx
-// Proposta de API
-interface FlexProps {
-  basis?: "auto" | "0" | "full" | "1/2" | "1/3" | "1/4"
-  grow?: boolean | 0 | 1
-  shrink?: boolean | 0 | 1
-}
-
-// Uso
-<Flex>
-  <Flex.Item grow>Expande</Flex.Item>
-  <Flex.Item basis="1/3">33%</Flex.Item>
-</Flex>
-```
-
-**Referências:** Chakra (`flex`, `flexGrow`, `flexShrink`, `flexBasis`)
-
-#### Responsive Props
-
-Props responsivas para breakpoints.
-
-```tsx
-// Proposta de API
-interface FlexProps {
-  direction?: FlexDirection | { base?: FlexDirection; sm?: FlexDirection; md?: FlexDirection; lg?: FlexDirection }
-  gap?: FlexGap | { base?: FlexGap; sm?: FlexGap; md?: FlexGap; lg?: FlexGap }
-}
-
-// Uso
-<Flex direction={{ base: "col", md: "row" }} gap={{ base: 2, md: 4 }}>
-  <div>Item 1</div>
-  <div>Item 2</div>
-</Flex>
-
-// Equivalente atual via className
-<Flex className="flex-col md:flex-row gap-2 md:gap-4">
-  <div>Item 1</div>
-  <div>Item 2</div>
-</Flex>
-```
-
-**Referências:** Chakra (responsive arrays), MUI (breakpoint objects), Mantine (responsive values)
-
-### Prioridade Baixa
-
-#### `order`
-
-Controle de ordem visual dos items.
-
-```tsx
-// Proposta de API (via Flex.Item)
-<Flex>
-  <Flex.Item order={2}>Segundo visualmente</Flex.Item>
-  <Flex.Item order={1}>Primeiro visualmente</Flex.Item>
-</Flex>
-```
-
-**Referências:** Chakra (`order`), Theme UI (`order`)
-
-#### `alignSelf`
-
-Alinhamento individual de items.
-
-```tsx
-// Proposta de API (via Flex.Item)
-<Flex align="start">
-  <Flex.Item>Normal</Flex.Item>
-  <Flex.Item alignSelf="end">Alinhado no final</Flex.Item>
-</Flex>
-```
-
-**Referências:** Chakra (`alignSelf`), Styled System
-
-### Decisões de Design
-
-| Feature | Recomendação | Justificativa |
-|---------|--------------|---------------|
-| `gapX`/`gapY` | ✅ Implementar | Comum, útil para wrap layouts |
-| Gap values (5, 10, 12, 16) | ✅ Implementar | Segue escala Tailwind |
-| Responsive props | ⚠️ Avaliar | `className` responsivo funciona |
-| `Flex.Item` compound | ⚠️ Avaliar | Adiciona complexidade |
-| Style props (`p`, `m`, etc.) | ❌ Evitar | Não segue padrão ETUS/Shadcn |
-
----
-
-## Referências
-
-### Design Systems Analisados
-
-| Design System | Documentação | GitHub |
-|---------------|--------------|--------|
-| **Chakra UI** | [Flex](https://chakra-ui.com/docs/components/flex) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
-| **MUI** | [Stack](https://mui.com/material-ui/react-stack/) | [mui/material-ui](https://github.com/mui/material-ui) |
-| **Mantine** | [Flex](https://mantine.dev/core/flex/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
-| **Ant Design** | [Flex](https://ant.design/components/flex) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
-| **Fluent UI** | [Flex](https://react.fluentui.dev/?path=/docs/components-flex) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
-| **Carbon** | [Grid](https://carbondesignsystem.com/guidelines/2x-grid/overview/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
-| **Styled System** | [Flexbox](https://styled-system.com/api#flexbox) | [styled-system/styled-system](https://github.com/styled-system/styled-system) |
-| **Theme UI** | [Flex](https://theme-ui.com/components/flex) | [system-ui/theme-ui](https://github.com/system-ui/theme-ui) |
-| **Rebass** | [Flex](https://rebassjs.org/flex) | [rebassjs/rebass](https://github.com/rebassjs/rebass) |
-
-### Especificações e Padrões
-
-- [CSS Flexbox - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout)
-- [A Complete Guide to Flexbox - CSS-Tricks](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)
-- [Flexbox Froggy - Interactive Learning](https://flexboxfroggy.com/)
-- [WCAG 2.1 - Meaningful Sequence](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence.html)
-
-### Ferramentas Utilizadas
-
-- [CVA - Class Variance Authority](https://cva.style/docs)
-- [Tailwind CSS - Flexbox](https://tailwindcss.com/docs/flex)
-- [tailwind-merge](https://github.com/dcastil/tailwind-merge)