@etus/ui 0.1.0

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

@@ -0,0 +1,814 @@
+# Badge
+
+## Visão Geral
+
+O **Badge** e um componente de rotulagem visual do Design System ETUS, usado para exibir status, categorias, contagens ou metadados em formato compacto. Como elemento atomico, serve de base para composicoes como `StatusBadge`, `CountBadge` e notificacoes inline.
+
+### Casos de Uso
+
+- Indicar status (ativo, pendente, erro)
+- Categorizar conteudo (tags, labels)
+- Exibir contagens (notificacoes, mensagens nao lidas)
+- Destacar informacoes importantes (novo, beta, pro)
+- Labels em tabelas e listas
+
+### Classificacao
+
+**Categoria:** Atom
+**Dependencias:** `@radix-ui/react-slot`, `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante      | Uso                                 | Tokens                                      |
+| ------------- | ----------------------------------- | ------------------------------------------- |
+| `default`     | Status primario, destaque principal | `bg-primary`, `text-primary-foreground`     |
+| `secondary`   | Informacao secundaria, tags neutras | `bg-secondary`, `text-secondary-foreground` |
+| `destructive` | Erros, alertas, status critico      | `bg-destructive`, `text-white`              |
+| `outline`     | Baixa enfase, estilo minimalista    | `border`, `text-foreground`                 |
+
+### Dimensoes
+
+O Badge possui tamanho unico otimizado para legibilidade:
+
+| Propriedade | Valor               | Descricao                  |
+| ----------- | ------------------- | -------------------------- |
+| Altura      | `py-0.5` (4px)      | Padding vertical           |
+| Largura     | `px-2` (8px)        | Padding horizontal         |
+| Fonte       | `text-xs` (12px)    | Tamanho do texto           |
+| Peso        | `font-medium` (500) | Peso da fonte              |
+| Borda       | `rounded-full`      | Pill shape                 |
+| Icone       | `size-3` (12px)     | Tamanho de icones internos |
+| Gap         | `gap-1` (4px)       | Espaco entre icone e texto |
+
+### Estados
+
+| Estado       | Classes/Atributos                  | Comportamento                             |
+| ------------ | ---------------------------------- | ----------------------------------------- |
+| Default      | -                                  | Aparencia base                            |
+| Hover (link) | `[a&]:hover:bg-*/90`               | Leve escurecimento quando usado como link |
+| Focus        | `focus-visible:ring-[3px]`         | Ring de 3px com `ring-ring/50`            |
+| Invalid      | `aria-invalid:ring-destructive/20` | Ring vermelho para validacao              |
+
+### Padrão de Tokens com Tailwind v4
+
+O Badge utiliza tokens de componente de `@etus/tokens`. A sintaxe do Tailwind v4 com valores arbitrários requer **type hints** para cores e font-sizes.
+
+#### Tokens Disponíveis
+
+| Token                          | Tipo      | Uso                           |
+| ------------------------------ | --------- | ----------------------------- |
+| `--badge-radius-pill`          | dimension | Border radius para tipo pill  |
+| `--badge-radius-default`       | dimension | Border radius para tipo badge |
+| `--badge-size-sm-h`            | dimension | Altura tamanho small          |
+| `--badge-size-sm-px`           | dimension | Padding horizontal small      |
+| `--badge-size-sm-text`         | font-size | Tamanho texto small           |
+| `--badge-size-md-h`            | dimension | Altura tamanho medium         |
+| `--badge-size-md-px`           | dimension | Padding horizontal medium     |
+| `--badge-size-md-text`         | font-size | Tamanho texto medium          |
+| `--badge-size-lg-h`            | dimension | Altura tamanho large          |
+| `--badge-size-lg-px`           | dimension | Padding horizontal large      |
+| `--badge-size-lg-text`         | font-size | Tamanho texto large           |
+| `--badge-color-primary-bg`     | color     | Background primary            |
+| `--badge-color-primary-fg`     | color     | Texto primary                 |
+| `--badge-color-secondary-bg`   | color     | Background secondary          |
+| `--badge-color-secondary-fg`   | color     | Texto secondary               |
+| `--badge-color-destructive-bg` | color     | Background destructive        |
+| `--badge-color-destructive-fg` | color     | Texto destructive             |
+
+#### Sintaxe Correta
+
+```tsx
+// ✅ CORRETO - cores com color:
+bg-[color:var(--badge-color-primary-bg)]
+text-[color:var(--badge-color-primary-fg)]
+
+// ✅ CORRETO - dimensões sem prefixo
+h-[var(--badge-size-md-h)]
+px-[var(--badge-size-md-px)]
+rounded-[var(--badge-radius-pill)]
+
+// ✅ CORRETO - font-size com length:
+text-[length:var(--badge-size-md-text)]
+
+// ❌ INCORRETO - nunca usar sem type hint para cores
+bg-[var(--badge-color-primary-bg)]
+text-[var(--badge-color-primary-fg)]
+```
+
+#### Tokens Semânticos (Tailwind)
+
+Além dos tokens de componente, o Badge também usa tokens semânticos do Tailwind:
+
+```css
+/* Cores semânticas */
+bg-primary, text-primary-foreground
+bg-destructive, text-white
+bg-warning, text-warning-foreground
+bg-success, text-success-foreground
+bg-muted, text-muted-foreground
+
+/* Focus */
+ring-ring
+
+/* Bordas */
+border-border
+```
+
+### data-slot
+
+```html
+<span data-slot="badge">...</span>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop        | Tipo                                                     | Padrao      | Descricao                                       |
+| ----------- | -------------------------------------------------------- | ----------- | ----------------------------------------------- |
+| `variant`   | `"default" \| "secondary" \| "destructive" \| "outline"` | `"default"` | Estilo visual do badge                          |
+| `asChild`   | `boolean`                                                | `false`     | Renderiza children como elemento (polimorfismo) |
+| `className` | `string`                                                 | -           | Classes CSS adicionais                          |
+| `children`  | `ReactNode`                                              | -           | Conteudo do badge                               |
+| `ref`       | `Ref<HTMLSpanElement>`                                   | -           | Referencia ao elemento DOM                      |
+
+> Herda todas as props de `React.ComponentProps<"span">`
+
+### Callbacks
+
+| Callback  | Tipo                          | Descricao                               |
+| --------- | ----------------------------- | --------------------------------------- |
+| `onClick` | `(event: MouseEvent) => void` | Disparado ao clicar (quando interativo) |
+| `onFocus` | `(event: FocusEvent) => void` | Disparado ao receber foco               |
+| `onBlur`  | `(event: FocusEvent) => void` | Disparado ao perder foco                |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority";
+
+// Variants exportadas
+const badgeVariants = cva(/* ... */);
+
+// Props do componente
+type BadgeProps = React.ComponentProps<"span"> &
+  VariantProps<typeof badgeVariants> & {
+    asChild?: boolean;
+  };
+
+// Tipos derivados uteis
+type BadgeVariant = NonNullable<VariantProps<typeof badgeVariants>["variant"]>;
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature          | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+| ---------------- | :--: | :----: | :---: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: | :--------: |
+| **Variantes**    |  4   |   4    |   -   |   2    |  4  |    6    |  5   |   4    |    -     |    -    |   4    |   3    |     2     |     4      |
+| **Tamanhos**     |  1   |   1    |   -   |   3    |  3  |    4    |  3   |   3    |    -     |    -    |   3    |   3    |     2     |     3      |
+| **CVA/cva**      | sim  |  sim   |   -   |   -    |  -  |    -    |  -   |  sim   |    -     |    -    |   -    |   -    |     -     |     -      |
+| **asChild/Slot** | sim  |  sim   |  sim  |   -    |  -  |    -    |  -   |  sim   |    -     |    -    |   -    |   -    |     -     |     -      |
+| **Dot mode**     |  -   |   -    |   -   |   -    | sim |   sim   | sim  |  sim   |    -     |    -    |  sim   |   -    |     -     |    sim     |
+| **Contador**     |  -   |   -    |   -   |   -    | sim |    -    | sim  |   -    |    -     |    -    |  sim   |   -    |     -     |    sim     |
+| **Animacao**     |  -   |   -    |   -   |   -    |  -  |    -    | sim  |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+| **Removivel**    |  -   |   -    |   -   |   -    |  -  |    -    | sim  |   -    |    -     |    -    |   -    |   -    |     -     |    sim     |
+| **data-slot**    | sim  |  sim   |   -   |   -    |  -  |    -    |  -   |  sim   |    -     |    -    |   -    |   -    |     -     |     -      |
+| **colorScheme**  |  -   |   -    |   -   |  sim   | sim |   sim   | sim  |  sim   |    -     |    -    |   -    |   -    |     -     |    sim     |
+
+#### Comparativo de Variantes por Design System
+
+| Design System  | Variantes Disponiveis                                         |
+| -------------- | ------------------------------------------------------------- |
+| **ETUS**       | `default`, `secondary`, `destructive`, `outline`              |
+| **Shadcn/ui**  | `default`, `secondary`, `destructive`, `outline`              |
+| **Chakra UI**  | `solid`, `subtle`, `outline` + colorScheme                    |
+| **MUI**        | `filled`, `outlined` + color                                  |
+| **Mantine**    | `filled`, `light`, `outline`, `dot`, `default`, `transparent` |
+| **Ant Design** | `success`, `processing`, `error`, `default`, `warning`        |
+| **NextUI**     | `solid`, `bordered`, `light`, `flat`, `faded`, `shadow`       |
+| **Fluent UI**  | `filled`, `ghost`, `outline`, `tint`                          |
+| **Carbon**     | `gray`, `red`, `green`, `blue`, `purple`, etc.                |
+
+#### Comparativo de Props por Design System
+
+| Prop           | ETUS |    Chakra     |      MUI       |   Mantine   |      AntD       |    NextUI     |    Fluent    |
+| -------------- | :--: | :-----------: | :------------: | :---------: | :-------------: | :-----------: | :----------: |
+| `variant`      | sim  |      sim      |      sim       |     sim     |        -        |      sim      | `appearance` |
+| `size`         |  -   |      sim      |      sim       |     sim     |       sim       |      sim      |     sim      |
+| `color`        |  -   | `colorScheme` |      sim       |     sim     |     `color`     |      sim      |     sim      |
+| `dot`          |  -   |       -       |       -        |     sim     |        -        |      sim      |      -       |
+| `count`        |  -   |       -       | `badgeContent` |      -      |     `count`     |       -       |      -       |
+| `max`          |  -   |       -       |     `max`      |      -      | `overflowCount` |       -       |      -       |
+| `showZero`     |  -   |       -       |      sim       |      -      |       sim       |       -       |      -       |
+| `invisible`    |  -   |       -       |      sim       |      -      |        -        | `isInvisible` |      -       |
+| `asChild`/`as` | sim  |     `as`      |  `component`   | `component` |        -        |     `as`      |     `as`     |
+
+#### Analise por Categoria
+
+**Headless/Primitivos (maxima flexibilidade):**
+
+- **Radix UI** - Nao possui Badge nativo, usar Slot
+- **Headless UI** - Nao possui Badge
+- **Ariakit** - Nao possui Badge nativo
+- **React Aria** - Nao possui Badge
+
+**Styled/Opinionated (produtividade):**
+
+- **Chakra UI** - Simples, colorScheme flexivel
+- **MUI** - Badge com contador, posicionamento
+- **Mantine** - Muitas variantes, dot mode
+- **Ant Design** - Foco em status e contadores
+
+**Hybrid (meio-termo):**
+
+- **Shadcn/ui** - CVA + Tailwind, minimalista
+- **NextUI** - Tailwind + muitas variantes
+- **ETUS** - CVA + Tailwind, baseado em Shadcn
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo        | Uso                                           |
+| --------------- | --------------------------------------------- |
+| `role="status"` | Quando badge indica status dinamico           |
+| `aria-label`    | Quando texto nao e suficientemente descritivo |
+| `aria-hidden`   | Badges decorativos (icons sem texto)          |
+| `aria-invalid`  | Validacao de formulario                       |
+
+### Suporte a Teclado
+
+| Tecla   | Acao                                     |
+| ------- | ---------------------------------------- |
+| `Tab`   | Move foco para/do badge (quando focavel) |
+| `Enter` | Ativa o badge (quando usado como link)   |
+| `Space` | Ativa o badge (quando usado como botao)  |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Variante    | Foreground               | Background      | Ratio    |
+| ----------- | ------------------------ | --------------- | -------- |
+| default     | `--primary-foreground`   | `--primary`     | >= 4.5:1 |
+| secondary   | `--secondary-foreground` | `--secondary`   | >= 4.5:1 |
+| destructive | white                    | `--destructive` | >= 4.5:1 |
+| outline     | `--foreground`           | transparent     | >= 4.5:1 |
+
+### Screen Readers
+
+- Usar `aria-label` quando badge tem apenas icone
+- Evitar badges puramente decorativos sem `aria-hidden`
+- Incluir contexto quando badge indica status
+
+### Reduced Motion
+
+```css
+/* Respeitar preferencia do usuario */
+@media (prefers-reduced-motion: reduce) {
+  transition: none;
+}
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature                  | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+| ------------------------ | :--: | :--------: | :---: | :-----: | :------: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: | :-------: | :--------: |
+| **Focus visible**        | sim  |    sim     |  sim  |   sim   |   sim    |  sim   | sim |   sim   | sim  |  sim   |  sim   |  sim   |    sim    |    sim     |
+| **aria-invalid**         | sim  |    sim     |   -   |   sim   |    -     |   ~    |  ~  |    ~    |  -   |   ~    |  sim   |  sim   |     -     |     -      |
+| **Keyboard nav**         | sim  |    sim     |  sim  |   sim   |   sim    |  sim   | sim |   sim   | sim  |  sim   |  sim   |  sim   |    sim    |    sim     |
+| **High contrast**        |  -   |    sim     |   -   |    -    |    -     |   -    |  -  |    -    |  -   |   -    |  sim   |  sim   |     -     |     -      |
+| **RTL support**          |  -   |    sim     |   -   |    -    |    -     |  sim   | sim |   sim   | sim  |   -    |  sim   |  sim   |     -     |     -      |
+| **Screen reader tested** |  -   |    sim     |  sim  |   sim   |   sim    |   ~    | sim |    ~    |  ~   |   ~    |  sim   |  sim   |     -     |     ~      |
+
+**Legenda:** sim = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Badge } from "@etus/ui";
+
+function Example() {
+  return <Badge>New</Badge>;
+}
+```
+
+### Variantes
+
+```tsx
+<Badge variant="default">Primary</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Outline</Badge>
+```
+
+### Com Icones
+
+```tsx
+import { Check, X, AlertCircle, Info } from "lucide-react"
+
+// Icone a esquerda
+<Badge variant="default">
+  <Check />
+  Approved
+</Badge>
+
+// Icone a direita
+<Badge variant="destructive">
+  Error
+  <X />
+</Badge>
+
+// Apenas icone (requer aria-label)
+<Badge variant="outline" aria-label="Information">
+  <Info />
+</Badge>
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { Link } from "@tanstack/react-router"
+
+// Renderiza como Link mantendo estilos do Badge
+<Badge asChild>
+  <Link to="/category/react">React</Link>
+</Badge>
+
+// Com elemento anchor
+<Badge asChild variant="secondary">
+  <a href="https://example.com" target="_blank" rel="noopener">
+    External
+  </a>
+</Badge>
+```
+
+### Status Indicators
+
+```tsx
+// Status de usuario
+<div className="flex items-center gap-2">
+  <Avatar />
+  <span>John Doe</span>
+  <Badge variant="default">Online</Badge>
+</div>
+
+// Status de tarefa
+<Badge variant="secondary">In Progress</Badge>
+<Badge variant="default">Completed</Badge>
+<Badge variant="destructive">Failed</Badge>
+```
+
+### Em Tabelas
+
+```tsx
+<Table>
+  <TableBody>
+    <TableRow>
+      <TableCell>Order #1234</TableCell>
+      <TableCell>
+        <Badge variant="default">Paid</Badge>
+      </TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell>Order #1235</TableCell>
+      <TableCell>
+        <Badge variant="outline">Pending</Badge>
+      </TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Tags e Categorias
+
+```tsx
+// Lista de tags
+<div className="flex flex-wrap gap-2">
+  <Badge variant="secondary">React</Badge>
+  <Badge variant="secondary">TypeScript</Badge>
+  <Badge variant="secondary">Tailwind</Badge>
+</div>
+```
+
+### Composicao com Card
+
+```tsx
+<Card>
+  <CardHeader className="flex flex-row items-center justify-between">
+    <CardTitle>Feature Request</CardTitle>
+    <Badge variant="outline">Open</Badge>
+  </CardHeader>
+  <CardContent>{/* content */}</CardContent>
+</Card>
+```
+
+### Responsividade
+
+```tsx
+// Badge visivel apenas em telas maiores
+<Badge className="hidden sm:inline-flex">
+  Desktop Only
+</Badge>
+
+// Tamanho responsivo via className
+<Badge className="text-[10px] px-1.5 md:text-xs md:px-2">
+  Responsive
+</Badge>
+```
+
+### Acessibilidade
+
+```tsx
+// Badge com role status para conteudo dinamico
+<Badge role="status" aria-live="polite">
+  {notificationCount} new messages
+</Badge>
+
+// Badge decorativo
+<Badge aria-hidden="true">
+  <Star />
+</Badge>
+<span className="sr-only">Featured item</span>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Badge.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Badge } from "./Badge";
+
+describe("Badge", () => {
+  it("renders children correctly", () => {
+    render(<Badge>New</Badge>);
+    expect(screen.getByText("New")).toBeInTheDocument();
+  });
+
+  it("applies variant classes", () => {
+    render(<Badge variant="destructive">Error</Badge>);
+    expect(screen.getByText("Error")).toHaveClass("bg-destructive");
+  });
+
+  it("uses default variant when not specified", () => {
+    render(<Badge>Default</Badge>);
+    expect(screen.getByText("Default")).toHaveClass("bg-primary");
+  });
+
+  it("merges custom className", () => {
+    render(<Badge className="custom-class">Test</Badge>);
+    expect(screen.getByText("Test")).toHaveClass("custom-class");
+  });
+
+  it("has data-slot attribute", () => {
+    render(<Badge>Test</Badge>);
+    expect(screen.getByText("Test")).toHaveAttribute("data-slot", "badge");
+  });
+
+  it("renders as span by default", () => {
+    render(<Badge>Test</Badge>);
+    expect(screen.getByText("Test").tagName).toBe("SPAN");
+  });
+});
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Badge interactions", () => {
+  it("renders with icon", () => {
+    render(
+      <Badge>
+        <svg data-testid="icon" />
+        With Icon
+      </Badge>,
+    );
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+    expect(screen.getByText("With Icon")).toBeInTheDocument();
+  });
+
+  it("supports onClick when used as interactive element", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(
+      <Badge asChild>
+        <button onClick={handleClick}>Clickable</button>
+      </Badge>,
+    );
+
+    await user.click(screen.getByRole("button"));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Badge accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Badge>Accessible</Badge>);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("icon-only badge with aria-label passes a11y", async () => {
+    const { container } = render(
+      <Badge aria-label="Success status">
+        <Check />
+      </Badge>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("supports aria-invalid", () => {
+    render(<Badge aria-invalid="true">Invalid</Badge>);
+    expect(screen.getByText("Invalid")).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("can have role status for dynamic content", () => {
+    render(<Badge role="status">5 new</Badge>);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+  });
+});
+```
+
+### Testes de Composicao (asChild)
+
+```tsx
+describe("Badge asChild", () => {
+  it("renders as child element", () => {
+    render(
+      <Badge asChild>
+        <a href="/test">Link Badge</a>
+      </Badge>,
+    );
+
+    const link = screen.getByRole("link", { name: "Link Badge" });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute("href", "/test");
+    expect(link).toHaveClass("bg-primary"); // Mantem estilos
+  });
+
+  it("forwards ref to child element", () => {
+    const ref = { current: null };
+    render(
+      <Badge asChild ref={ref}>
+        <a href="/test">Link</a>
+      </Badge>,
+    );
+    expect(ref.current).toBeInstanceOf(HTMLAnchorElement);
+  });
+
+  it("renders as button when asChild with button", () => {
+    render(
+      <Badge asChild>
+        <button type="button">Button Badge</button>
+      </Badge>,
+    );
+
+    expect(
+      screen.getByRole("button", { name: "Button Badge" }),
+    ).toBeInTheDocument();
+  });
+});
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("Badge edge cases", () => {
+  it("handles empty children", () => {
+    const { container } = render(<Badge />);
+    expect(container.querySelector('[data-slot="badge"]')).toBeInTheDocument();
+  });
+
+  it("handles long text with overflow", () => {
+    render(
+      <Badge>This is a very long badge text that should be handled</Badge>,
+    );
+    expect(screen.getByText(/This is a very long/)).toHaveClass(
+      "overflow-hidden",
+    );
+  });
+
+  it("preserves whitespace-nowrap", () => {
+    render(<Badge>No Wrap</Badge>);
+    expect(screen.getByText("No Wrap")).toHaveClass("whitespace-nowrap");
+  });
+
+  it("all variants render correctly", () => {
+    const variants = [
+      "default",
+      "secondary",
+      "destructive",
+      "outline",
+    ] as const;
+
+    variants.forEach((variant) => {
+      const { unmount } = render(<Badge variant={variant}>{variant}</Badge>);
+      expect(screen.getByText(variant)).toBeInTheDocument();
+      unmount();
+    });
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### `size`
+
+Tamanhos adicionais para diferentes contextos.
+
+```tsx
+// Proposta de API
+interface BadgeProps {
+  size?: "sm" | "default" | "lg"
+}
+
+// Uso
+<Badge size="sm">Small</Badge>
+<Badge size="lg">Large</Badge>
+```
+
+**Referencias:** MUI, Mantine, AntD, NextUI (`size`)
+
+#### Variantes Adicionais
+
+Novas variantes para casos de uso comuns.
+
+```tsx
+// Proposta de API
+interface BadgeProps {
+  variant?: "default" | "secondary" | "destructive" | "outline" | "success" | "warning"
+}
+
+// Uso
+<Badge variant="success">Approved</Badge>
+<Badge variant="warning">Attention</Badge>
+```
+
+**Referencias:** AntD, Mantine, Fluent UI
+
+### Prioridade Media
+
+#### `dot`
+
+Modo dot para indicadores minimalistas.
+
+```tsx
+// Proposta de API
+interface BadgeProps {
+  dot?: boolean;
+}
+
+// Uso
+<Badge dot variant="destructive" />;
+```
+
+**Referencias:** MUI, Mantine, AntD (`dot`)
+
+#### `removable`
+
+Badge com botao de remocao para tags.
+
+```tsx
+// Proposta de API
+interface BadgeProps {
+  removable?: boolean;
+  onRemove?: () => void;
+}
+
+// Uso
+<Badge removable onRemove={() => handleRemove()}>
+  Tag
+</Badge>;
+```
+
+**Referencias:** AntD, PrimeReact
+
+### Prioridade Baixa
+
+#### `count` / `max`
+
+Modo contador para notificacoes.
+
+```tsx
+// Proposta de API
+interface BadgeProps {
+  count?: number;
+  max?: number;
+  showZero?: boolean;
+}
+
+// Uso
+<Badge count={99} max={99}>
+  99+
+</Badge>;
+```
+
+**Referencias:** MUI (`badgeContent`, `max`), AntD (`count`, `overflowCount`)
+
+#### `colorScheme`
+
+Variacao de cor independente da variante.
+
+```tsx
+// Proposta de API
+interface BadgeProps {
+  colorScheme?: "blue" | "green" | "yellow" | "red" | "purple";
+}
+
+// Uso
+<Badge variant="outline" colorScheme="green">
+  Custom
+</Badge>;
+```
+
+**Referencias:** Chakra (`colorScheme`), Mantine (`color`)
+
+### Decisoes de Design
+
+| Feature             | Recomendacao | Justificativa                    |
+| ------------------- | ------------ | -------------------------------- |
+| `size`              | Implementar  | Alta demanda, contextos diversos |
+| `success`/`warning` | Implementar  | Casos de uso comuns              |
+| `dot`               | Avaliar      | `className` pode resolver        |
+| `removable`         | Implementar  | Tags interativas                 |
+| `count`             | Evitar       | Criar componente separado        |
+| `colorScheme`       | Evitar       | Usar variants ou className       |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System   | Documentacao Badge                                                        | GitHub                                                                        |
+| --------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**   | [Badge](https://ui.shadcn.com/docs/components/badge)                      | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**    | [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)           | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **React Aria**  | N/A                                                                       | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**   | [Badge](https://chakra-ui.com/docs/components/badge)                      | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**         | [Badge](https://mui.com/material-ui/react-badge/)                         | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**     | [Badge](https://mantine.dev/core/badge/)                                  | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design**  | [Badge](https://ant.design/components/badge)                              | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**      | [Chip](https://nextui.org/docs/components/chip)                           | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Headless UI** | N/A                                                                       | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)         |
+| **Ariakit**     | N/A                                                                       | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**   | [Badge](https://react.fluentui.dev/?path=/docs/components-badge--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**      | [Tag](https://carbondesignsystem.com/components/tag/usage/)               | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**   | [Tag](https://blueprintjs.com/docs/#core/components/tag)                  | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact**  | [Badge](https://primereact.org/badge/)                                    | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificacoes e Padroes
+
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - ARIA: status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Radix Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)
+- [Lucide Icons](https://lucide.dev/icons/)