@etus/ui 0.1.0

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

@@ -0,0 +1,812 @@
+# 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)