@etus/ui 0.1.0

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

@@ -0,0 +1,839 @@
+# Separator (Divider)
+
+## Visão Geral
+
+O **Separator** (tambem conhecido como Divider) e um componente atomico do Design System ETUS usado para separar visualmente conteudo em secoes distintas. Baseado no primitivo `@radix-ui/react-separator`, oferece suporte completo a acessibilidade e orientacao flexivel.
+
+### Casos de Uso
+
+- Separacao de secoes em layouts
+- Divisao de itens em listas e menus
+- Delimitacao visual entre grupos de conteudo
+- Separadores decorativos em headers e footers
+- Divisorias em sidebars e navegacao
+
+### Classificacao
+
+**Categoria:** Atom (Primitive)
+**Dependencias:** `@radix-ui/react-separator`
+
+---
+
+## Design Specs
+
+### Orientacoes (`orientation`)
+
+| Orientacao   | Classes       | Uso                                         |
+| ------------ | ------------- | ------------------------------------------- |
+| `horizontal` | `h-px w-full` | Separacao de linhas, secoes empilhadas      |
+| `vertical`   | `h-full w-px` | Separacao de colunas, elementos lado a lado |
+
+### Dimensoes
+
+| Orientacao   | Altura          | Largura         | Comportamento           |
+| ------------ | --------------- | --------------- | ----------------------- |
+| `horizontal` | `1px` (h-px)    | `100%` (w-full) | Expande horizontalmente |
+| `vertical`   | `100%` (h-full) | `1px` (w-px)    | Expande verticalmente   |
+
+### Estados
+
+| Estado     | Classes/Atributos    | Comportamento                 |
+| ---------- | -------------------- | ----------------------------- |
+| Default    | -                    | Linha solida com cor de borda |
+| Decorative | `decorative={true}`  | Ignorado por leitores de tela |
+| Semantic   | `decorative={false}` | Anunciado como separador      |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--divider-color-default           /* Cor padrao do separador */
+--divider-color-dual              /* Cor da linha dupla */
+
+/* Content Divider - Background */
+--divider-content-bg-default      /* Fundo do conteudo (background) */
+--divider-content-bg-fill         /* Fundo do conteudo preenchido */
+
+/* Content Divider - Text */
+--divider-content-text-default    /* Cor do texto padrao */
+--divider-content-text-heading    /* Cor do texto de titulo */
+
+/* Layout */
+shrink-0              /* Impede encolhimento em flex */
+
+/* Dimensoes via data-attributes */
+data-[orientation=horizontal]:h-px
+data-[orientation=horizontal]:w-full
+data-[orientation=vertical]:h-full
+data-[orientation=vertical]:w-px
+```
+
+### data-slot
+
+```html
+<div data-slot="separator" role="separator">...</div>
+```
+
+### Data Attributes (Radix)
+
+| Atributo           | Valores                      | Descricao                     |
+| ------------------ | ---------------------------- | ----------------------------- |
+| `data-orientation` | `"horizontal" \| "vertical"` | Orientacao atual do separador |
+
+---
+
+## API
+
+### Props
+
+| Prop            | Tipo                         | Padrao          | Descricao                                                                                    |
+| --------------- | ---------------------------- | --------------- | -------------------------------------------------------------------------------------------- |
+| `orientation`   | `"horizontal" \| "vertical"` | `"horizontal"`  | Direcao do separador                                                                         |
+| `decorative`    | `boolean`                    | `true`          | Se `true`, oculta de leitores de tela                                                        |
+| `type`          | `DividerType`                | `"line"`        | Tipo de conteudo (line, heading, text, button, button-icon, button-group, button-group-icon) |
+| `visualStyle`   | `DividerVisualStyle`         | `"single-line"` | Estilo visual (single-line, dual-line, background-fill)                                      |
+| `labelPosition` | `DividerLabelPosition`       | `"center"`      | Posicao do conteudo (left, center, right)                                                    |
+| `children`      | `ReactNode`                  | -               | Conteudo a ser exibido no separador                                                          |
+| `className`     | `string`                     | -               | Classes CSS adicionais                                                                       |
+| `ref`           | `Ref<HTMLDivElement>`        | -               | Referencia ao elemento DOM                                                                   |
+
+> Herda todas as props de `React.ComponentProps<typeof SeparatorPrimitive.Root>` (exceto `children`)
+
+### TypeScript
+
+```typescript
+import * as SeparatorPrimitive from "@radix-ui/react-separator";
+
+// Tipos do componente
+type DividerOrientation = "horizontal" | "vertical";
+
+type DividerType =
+  | "line" // Linha simples (padrao)
+  | "heading" // Texto de titulo
+  | "text" // Texto regular
+  | "button" // Botao unico
+  | "button-icon" // Botao de icone
+  | "button-group" // Grupo de botoes
+  | "button-group-icon"; // Grupo de botoes de icone
+
+type DividerVisualStyle =
+  | "single-line" // Linha unica (padrao)
+  | "dual-line" // Linha dupla
+  | "background-fill"; // Fundo preenchido
+
+type DividerLabelPosition = "left" | "center" | "right";
+
+// Props do componente
+interface DividerProps extends Omit<SeparatorPrimitive.Root, "children"> {
+  children?: ReactNode;
+  type?: DividerType;
+  visualStyle?: DividerVisualStyle;
+  labelPosition?: DividerLabelPosition;
+}
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature              | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint |
+| -------------------- | :--: | :----: | :---: | :--------: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: |
+| **Horizontal**       |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |
+| **Vertical**         |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |
+| **Decorative**       |  ✓   |   ✓    |   ✓   |     ✓      |   -    |  -  |    -    |  -   |   -    |    -     |    ✓    |   -    |   -    |     -     |
+| **Text/Label**       |  ✓   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  ✓   |   -    |    -     |    -    |   -    |   -    |     ✓     |
+| **Visual Styles**    |  ✓   |   -    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **Button Content**   |  ✓   |   -    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **Label Position**   |  ✓   |   -    |   -   |     -      |   -    |  -  |    ✓    |  ✓   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **Dashed**           |  -   |   -    |   -   |     -      |   -    |  -  |    -    |  ✓   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **Inset**            |  -   |   -    |   -   |     -      |   -    |  ✓  |    -    |  -   |   -    |    -     |    -    |   ✓    |   -    |     -     |
+| **Spacing**          |  -   |   -    |   -   |     -      |   -    |  ✓  |    -    |  -   |   -    |    -     |    -    |   ✓    |   ✓    |     -     |
+| **Color**            |  ~   |   ~    |   -   |     -      |   ✓    |  ✓  |    ✓    |  -   |   -    |    -     |    -    |   ✓    |   -    |     -     |
+| **data-slot**        |  ✓   |   ✓    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **aria-orientation** |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    -    |  -   |   -    |    -     |    ✓    |   ✓    |   -    |     -     |
+
+**Legenda:** ✓ = Suporte completo | ~ = Via className | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop            | ETUS | Radix | Chakra | MUI | Mantine |  AntD  | Fluent |
+| --------------- | :--: | :---: | :----: | :-: | :-----: | :----: | :----: |
+| `orientation`   |  ✓   |   ✓   |   ✓    |  ✓  |    ✓    | `type` |   ✓    |
+| `decorative`    |  ✓   |   ✓   |   -    |  -  |    -    |   -    |   -    |
+| `type`          |  ✓   |   -   |   -    |  -  |    -    |   -    |   -    |
+| `visualStyle`   |  ✓   |   -   |   -    |  -  |    -    |   -    |   -    |
+| `children`      |  ✓   |   -   |   ✓    |  ✓  |    ✓    |   ✓    |   -    |
+| `labelPosition` |  ✓   |   -   |   -    |  -  |    ✓    |   ✓    |   -    |
+| `variant`       |  -   |   -   |   ✓    |  ✓  |    ✓    |   -    |   -    |
+| `label`         |  -   |   -   |   -    |  -  |    ✓    |   ✓    |   -    |
+| `inset`         |  -   |   -   |   -    |  ✓  |    -    |   -    |   ✓    |
+| `flexItem`      |  -   |   -   |   -    |  ✓  |    -    |   -    |   -    |
+| `textAlign`     |  -   |   -   |   -    |  ✓  |    -    |   -    |   -    |
+| `color`         |  ~   |   -   |   ✓    |  ✓  |    ✓    |   -    |   -    |
+| `size`          |  -   |   -   |   -    |  -  |    ✓    |   -    |   -    |
+| `dashed`        |  -   |   -   |   -    |  -  |    -    |   ✓    |   -    |
+| `plain`         |  -   |   -   |   -    |  -  |    -    |   ✓    |   -    |
+
+#### Nomenclatura por Design System
+
+| Design System  | Nome do Componente |
+| -------------- | ------------------ |
+| **ETUS**       | `Separator`        |
+| **Shadcn/ui**  | `Separator`        |
+| **Radix UI**   | `Separator`        |
+| **React Aria** | `Separator`        |
+| **Chakra UI**  | `Divider`          |
+| **MUI**        | `Divider`          |
+| **Mantine**    | `Divider`          |
+| **Ant Design** | `Divider`          |
+| **NextUI**     | `Divider`          |
+| **Fluent UI**  | `Divider`          |
+| **Carbon**     | `Divider` (HR)     |
+| **Blueprint**  | `Divider`          |
+| **PrimeReact** | `Divider`          |
+
+#### Analise por Categoria
+
+**Headless/Primitivos (maxima flexibilidade):**
+
+- **Radix UI** - Primitivo com acessibilidade, `decorative` prop
+- **React Aria** - Hook-based, `useSeparator`
+- **Ariakit** - Primitivo acessivel, composavel
+
+**Styled/Opinionated (produtividade):**
+
+- **Chakra UI** - `borderColor`, `variant` (solid/dashed)
+- **MUI** - `variant`, `textAlign`, `inset`, muito completo
+- **Mantine** - `label`, `labelPosition`, `size`, `color`
+- **Ant Design** - `type`, `dashed`, `plain`, texto embutido
+
+**Hybrid (meio-termo):**
+
+- **Shadcn/ui** - Baseado em Radix, Tailwind
+- **ETUS** - Baseado em Shadcn, Tailwind v4
+- **NextUI** - Tailwind, minimal
+
+**Enterprise:**
+
+- **Fluent UI** - `inset`, `vertical`, tokens complexos
+- **Carbon** - HR semantico, minimal
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo           | Uso                                     |
+| ------------------ | --------------------------------------- |
+| `role="separator"` | Quando `decorative={false}`             |
+| `role="none"`      | Quando `decorative={true}`              |
+| `aria-orientation` | Define orientacao para leitores de tela |
+
+### Prop `decorative`
+
+| Valor           | Role        | Comportamento                      |
+| --------------- | ----------- | ---------------------------------- |
+| `true` (padrao) | `none`      | Ignorado por leitores de tela      |
+| `false`         | `separator` | Anunciado como separador semantico |
+
+**Quando usar `decorative={false}`:**
+
+- Separando grupos de conteudo relacionado
+- Em navegacao para dividir secoes
+- Quando a divisao tem significado semantico
+
+**Quando usar `decorative={true}` (padrao):**
+
+- Separadores puramente visuais
+- Decoracao entre elementos
+- Quando ja existe outra indicacao de secoes
+
+### Suporte a Teclado
+
+O Separator nao e um elemento interativo e nao requer navegacao por teclado. Ele e ignorado na ordem de tabulacao.
+
+### Contraste de Cores
+
+| Elemento  | Token      | Requisito WCAG                        |
+| --------- | ---------- | ------------------------------------- |
+| Separator | `--border` | 3:1 contra background (UI components) |
+
+### Screen Readers
+
+- Quando `decorative={true}`: Ignorado completamente
+- Quando `decorative={false}`: Anunciado como "separator" com orientacao
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature              | ETUS | Radix | React Aria | Ariakit | Chakra | MUI | Mantine | AntD | Fluent | Carbon |
+| -------------------- | :--: | :---: | :--------: | :-----: | :----: | :-: | :-----: | :--: | :----: | :----: |
+| **role="separator"** |  ✓   |   ✓   |     ✓      |    ✓    |   ✓    |  ~  |    -    |  -   |   ✓    |   ~    |
+| **role="none"**      |  ✓   |   ✓   |     ✓      |    ✓    |   -    |  -  |    -    |  -   |   -    |   -    |
+| **decorative prop**  |  ✓   |   ✓   |     ✓      |    ✓    |   -    |  -  |    -    |  -   |   -    |   -    |
+| **aria-orientation** |  ✓   |   ✓   |     ✓      |    ✓    |   ✓    |  -  |    -    |  -   |   ✓    |   -    |
+| **Semantico HR**     |  -   |   -   |     -      |    -    |   -    |  ✓  |    -    |  ✓   |   -    |   ✓    |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+#### Abordagens de Acessibilidade
+
+| Design System  | Abordagem          | Nivel WCAG | Notas                            |
+| -------------- | ------------------ | ---------- | -------------------------------- |
+| **Radix UI**   | Primitivo WAI-ARIA | AA         | Decorative prop, role automatico |
+| **React Aria** | Hook useSeparator  | AAA        | Comportamento hook-based         |
+| **Ariakit**    | Primitivo a11y     | AA         | Composavel                       |
+| **MUI**        | HR semantico       | AA         | Usa `<hr>` quando apropriado     |
+| **ETUS**       | Baseado em Radix   | AA         | Herda comportamentos Radix       |
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Separator } from "@etus/ui";
+
+function Example() {
+  return (
+    <div>
+      <p>Conteudo acima</p>
+      <Separator />
+      <p>Conteudo abaixo</p>
+    </div>
+  );
+}
+```
+
+### Orientacoes
+
+```tsx
+// Horizontal (padrao)
+<Separator orientation="horizontal" />
+
+// Vertical (requer altura no container)
+<div className="flex h-10 items-center gap-4">
+  <span>Item 1</span>
+  <Separator orientation="vertical" />
+  <span>Item 2</span>
+  <Separator orientation="vertical" />
+  <span>Item 3</span>
+</div>
+```
+
+### Decorativo vs Semantico
+
+```tsx
+// Decorativo (padrao) - ignorado por screen readers
+<Separator decorative />
+
+// Semantico - anunciado por screen readers
+<nav>
+  <a href="/home">Home</a>
+  <Separator decorative={false} />
+  <a href="/about">About</a>
+</nav>
+```
+
+### Content Divider com Texto
+
+```tsx
+import { Divider } from "@etus/ui"
+
+// Texto simples no centro
+<Divider type="text">ou</Divider>
+
+// Texto alinhado a esquerda
+<Divider type="text" labelPosition="left">Secao 1</Divider>
+
+// Titulo com estilo dual-line
+<Divider type="heading" visualStyle="dual-line">
+  Informacoes Pessoais
+</Divider>
+
+// Texto com background
+<Divider type="text" visualStyle="background-fill">
+  Mais opcoes
+</Divider>
+```
+
+### Content Divider com Botoes
+
+```tsx
+import { Divider, Button } from "@etus/ui"
+
+// Botao unico
+<Divider type="button">
+  <Button variant="ghost" size="sm">Ver mais</Button>
+</Divider>
+
+// Botao de icone
+<Divider type="button-icon">
+  <Button variant="ghost" size="icon-sm">
+    <PlusIcon className="size-4" />
+  </Button>
+</Divider>
+
+// Grupo de botoes
+<Divider type="button-group" visualStyle="background-fill">
+  <Button variant="ghost" size="sm">Opcao A</Button>
+  <Button variant="ghost" size="sm">Opcao B</Button>
+  <Button variant="ghost" size="sm">Opcao C</Button>
+</Divider>
+
+// Grupo de botoes de icone
+<Divider type="button-group-icon">
+  <Button variant="ghost" size="icon-sm"><HomeIcon /></Button>
+  <Button variant="ghost" size="icon-sm"><SettingsIcon /></Button>
+  <Button variant="ghost" size="icon-sm"><UserIcon /></Button>
+</Divider>
+```
+
+### Visual Styles
+
+```tsx
+// Single line (padrao) - linha simples de cada lado
+<Divider type="text" visualStyle="single-line">Conteudo</Divider>
+
+// Dual line - efeito de linha dupla
+<Divider type="heading" visualStyle="dual-line">Titulo</Divider>
+
+// Background fill - fundo preenchido
+<Divider type="button-group" visualStyle="background-fill">
+  <Button variant="ghost" size="sm">A</Button>
+  <Button variant="ghost" size="sm">B</Button>
+</Divider>
+```
+
+### Em Listas e Menus
+
+```tsx
+import { Separator } from "@etus/ui";
+
+function MenuExample() {
+  return (
+    <div className="w-64 rounded-md border p-2">
+      <div className="px-2 py-1.5 text-sm font-semibold">Minha Conta</div>
+      <Separator className="my-2" />
+      <div className="space-y-1">
+        <button className="w-full rounded px-2 py-1.5 text-left hover:bg-accent">
+          Perfil
+        </button>
+        <button className="w-full rounded px-2 py-1.5 text-left hover:bg-accent">
+          Configuracoes
+        </button>
+      </div>
+      <Separator className="my-2" />
+      <button className="w-full rounded px-2 py-1.5 text-left text-destructive hover:bg-destructive/10">
+        Sair
+      </button>
+    </div>
+  );
+}
+```
+
+### Em Sidebars
+
+```tsx
+function SidebarExample() {
+  return (
+    <aside className="w-64 border-r p-4">
+      <nav className="space-y-2">
+        <a href="#" className="block">
+          Dashboard
+        </a>
+        <a href="#" className="block">
+          Projetos
+        </a>
+        <a href="#" className="block">
+          Tarefas
+        </a>
+      </nav>
+
+      <Separator className="my-4" />
+
+      <nav className="space-y-2">
+        <a href="#" className="block">
+          Configuracoes
+        </a>
+        <a href="#" className="block">
+          Ajuda
+        </a>
+      </nav>
+    </aside>
+  );
+}
+```
+
+### Com Espacamento Customizado
+
+```tsx
+// Espacamento via margin
+<Separator className="my-4" />
+
+// Espacamento via padding no container
+<div className="py-4">
+  <Separator />
+</div>
+
+// Espacamento em flex
+<div className="flex flex-col gap-4">
+  <div>Secao 1</div>
+  <Separator />
+  <div>Secao 2</div>
+</div>
+```
+
+### Cores Customizadas
+
+```tsx
+// Cor customizada
+<Separator className="bg-primary" />
+
+// Cor com opacidade
+<Separator className="bg-border/50" />
+
+// Cor destrutiva
+<Separator className="bg-destructive" />
+```
+
+### Em Cards
+
+```tsx
+import { Card, CardHeader, CardContent, CardFooter } from "@etus/ui";
+import { Separator } from "@etus/ui";
+
+function CardExample() {
+  return (
+    <Card>
+      <CardHeader>
+        <h3 className="text-lg font-semibold">Titulo do Card</h3>
+      </CardHeader>
+      <Separator />
+      <CardContent className="py-4">Conteudo principal do card.</CardContent>
+      <Separator />
+      <CardFooter>
+        <button>Acao</button>
+      </CardFooter>
+    </Card>
+  );
+}
+```
+
+### Responsividade
+
+```tsx
+// Ocultar em mobile
+<Separator className="hidden md:block" />
+
+// Mudar orientacao por breakpoint
+<div className="flex flex-col md:flex-row md:items-center gap-4">
+  <span>Item 1</span>
+  <Separator className="md:hidden" orientation="horizontal" />
+  <Separator className="hidden md:block h-6" orientation="vertical" />
+  <span>Item 2</span>
+</div>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <div className="flex flex-col @md:flex-row @md:items-center gap-4">
+    <span>Item 1</span>
+    <Separator className="@md:hidden" orientation="horizontal" />
+    <Separator className="hidden @md:block h-6" orientation="vertical" />
+    <span>Item 2</span>
+  </div>
+</div>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Separator.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Separator } from "./Divider";
+
+describe("Separator", () => {
+  it("renders correctly", () => {
+    render(<Separator data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toBeInTheDocument();
+  });
+
+  it("has horizontal orientation by default", () => {
+    render(<Separator data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-orientation",
+      "horizontal",
+    );
+  });
+
+  it("applies vertical orientation", () => {
+    render(<Separator orientation="vertical" data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-orientation",
+      "vertical",
+    );
+  });
+
+  it("has data-slot attribute", () => {
+    render(<Separator data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-slot",
+      "separator",
+    );
+  });
+
+  it("merges custom className", () => {
+    render(<Separator className="my-4" data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveClass("my-4");
+  });
+
+  it("applies base classes", () => {
+    render(<Separator data-testid="separator" />);
+    const separator = screen.getByTestId("separator");
+    expect(separator).toHaveClass("bg-border", "shrink-0");
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Separator accessibility", () => {
+  it("has no accessibility violations when decorative", async () => {
+    const { container } = render(<Separator decorative />);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("has no accessibility violations when semantic", async () => {
+    const { container } = render(<Separator decorative={false} />);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("has role=none when decorative is true", () => {
+    render(<Separator decorative data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute("role", "none");
+  });
+
+  it("has role=separator when decorative is false", () => {
+    render(<Separator decorative={false} data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "role",
+      "separator",
+    );
+  });
+
+  it("has aria-orientation when semantic", () => {
+    render(
+      <Separator
+        decorative={false}
+        orientation="vertical"
+        data-testid="separator"
+      />,
+    );
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "aria-orientation",
+      "vertical",
+    );
+  });
+});
+```
+
+### Testes de Integracao
+
+```tsx
+describe("Separator in context", () => {
+  it("renders correctly in a flex container", () => {
+    render(
+      <div className="flex items-center gap-4">
+        <span>Item 1</span>
+        <Separator orientation="vertical" data-testid="separator" />
+        <span>Item 2</span>
+      </div>,
+    );
+
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-orientation",
+      "vertical",
+    );
+    expect(screen.getByText("Item 1")).toBeInTheDocument();
+    expect(screen.getByText("Item 2")).toBeInTheDocument();
+  });
+
+  it("renders correctly in a menu", () => {
+    render(
+      <div role="menu">
+        <div role="menuitem">Item 1</div>
+        <Separator decorative={false} data-testid="separator" />
+        <div role="menuitem">Item 2</div>
+      </div>,
+    );
+
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "role",
+      "separator",
+    );
+  });
+});
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("Separator edge cases", () => {
+  it("handles ref correctly", () => {
+    const ref = { current: null };
+    render(<Separator ref={ref} />);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it("renders with empty className", () => {
+    render(<Separator className="" data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toBeInTheDocument();
+  });
+
+  it("spreads additional props", () => {
+    render(<Separator data-testid="separator" data-custom="value" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-custom",
+      "value",
+    );
+  });
+});
+```
+
+---
+
+## Roadmap / Features
+
+### Implementado ✓
+
+As seguintes features foram implementadas baseado no design Figma Content Divider:
+
+#### `children` / Text Label ✓
+
+Texto ou conteudo embutido no separador.
+
+```tsx
+<Divider type="text">ou</Divider>
+<Divider type="heading">Secao 2</Divider>
+```
+
+#### `type` ✓
+
+Tipo de conteudo a ser exibido.
+
+```tsx
+<Divider type="line" />           // Linha simples (padrao)
+<Divider type="heading">Titulo</Divider>
+<Divider type="text">texto</Divider>
+<Divider type="button"><Button>Acao</Button></Divider>
+<Divider type="button-icon"><IconButton /></Divider>
+<Divider type="button-group">...</Divider>
+<Divider type="button-group-icon">...</Divider>
+```
+
+#### `visualStyle` ✓
+
+Estilos visuais do separador baseados no Figma.
+
+```tsx
+<Divider type="text" visualStyle="single-line">texto</Divider>
+<Divider type="text" visualStyle="dual-line">texto</Divider>
+<Divider type="text" visualStyle="background-fill">texto</Divider>
+```
+
+#### `labelPosition` ✓
+
+Posicao do conteudo quando `children` esta presente.
+
+```tsx
+<Divider type="text" labelPosition="left">Secao</Divider>
+<Divider type="text" labelPosition="center">Secao</Divider>
+<Divider type="text" labelPosition="right">Secao</Divider>
+```
+
+### Possiveis Features Futuras
+
+#### `variant` (dashed/dotted)
+
+Estilos de linha tracejada/pontilhada.
+
+```tsx
+// Proposta de API futura
+<Divider variant="dashed" />
+<Divider variant="dotted" />
+```
+
+**Referencias:** Chakra, MUI, AntD (`dashed`)
+
+#### `inset`
+
+Separador com recuo lateral.
+
+```tsx
+// Proposta de API futura
+<Divider inset />
+<Divider inset="start" />
+```
+
+**Referencias:** MUI, Fluent UI
+
+### Decisoes de Design
+
+| Feature            | Status         | Justificativa                          |
+| ------------------ | -------------- | -------------------------------------- |
+| `children`         | ✓ Implementado | Alta demanda, UX melhor                |
+| `type`             | ✓ Implementado | Suporte a diferentes tipos de conteudo |
+| `visualStyle`      | ✓ Implementado | Alinhamento com Figma design           |
+| `labelPosition`    | ✓ Implementado | Flexibilidade de posicionamento        |
+| `variant` (dashed) | Avaliar        | `className` pode resolver              |
+| `inset`            | Evitar         | `className` resolve                    |
+| `spacing`          | Evitar         | `className` resolve                    |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System  | Documentacao                                                               | GitHub                                                                        |
+| -------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**  | [Separator](https://ui.shadcn.com/docs/components/separator)               | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**   | [Separator](https://www.radix-ui.com/primitives/docs/components/separator) | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **React Aria** | [Separator](https://react-spectrum.adobe.com/react-aria/Separator.html)    | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**  | [Divider](https://chakra-ui.com/docs/components/divider)                   | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**        | [Divider](https://mui.com/material-ui/react-divider/)                      | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**    | [Divider](https://mantine.dev/core/divider/)                               | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design** | [Divider](https://ant.design/components/divider)                           | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**     | [Divider](https://nextui.org/docs/components/divider)                      | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Ariakit**    | [Separator](https://ariakit.org/components/separator)                      | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**  | [Divider](https://react.fluentui.dev/?path=/docs/components-divider)       | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**     | [Divider](https://carbondesignsystem.com/components/divider/usage/)        | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**  | [Divider](https://blueprintjs.com/docs/#core/components/divider)           | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact** | [Divider](https://primereact.org/divider/)                                 | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA - Separator Role](https://www.w3.org/TR/wai-aria-1.2/#separator)
+- [MDN - role="separator"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role)
+- [WCAG 2.1 - Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)
+
+### Ferramentas Utilizadas
+
+- [Radix Separator](https://www.radix-ui.com/primitives/docs/components/separator)
+- [Tailwind CSS](https://tailwindcss.com/docs)