@etus/ui 0.1.0

package/src/components/forms/Checkbox/README.md

@@ -0,0 +1,861 @@
+# Checkbox
+
+## Visão Geral
+
+O **Checkbox** e um controle de formulario que permite ao usuario selecionar uma ou mais opcoes de um conjunto. Como elemento de formulario atomico, ele trabalha em conjunto com `Label` para fornecer feedback visual claro e acessivel sobre o estado de selecao.
+
+### Casos de Uso
+
+- Selecionar multiplas opcoes em formularios (preferencias, permissoes)
+- Aceitar termos e condicoes
+- Filtrar listas com multiplos criterios
+- Marcar itens como concluidos em listas de tarefas
+- Alternar configuracoes on/off em paineis de settings
+
+### Classificacao
+
+**Categoria:** Atom (Formulario)
+**Dependencias:** `@radix-ui/react-checkbox`, `lucide-react`
+
+---
+
+## Design Specs
+
+### Variantes
+
+O componente atual nao possui variantes via CVA. A implementacao segue o padrao Shadcn/ui com estilo unico baseado em tokens semanticos.
+
+| Variante  | Uso                                 | Tokens                              |
+| --------- | ----------------------------------- | ----------------------------------- |
+| `default` | Checkbox padrao para todos os casos | `--primary`, `--primary-foreground` |
+
+> **Nota:** Variantes como `error`, `success` podem ser adicionadas futuramente baseado na comparacao com outros design systems.
+
+### Tamanhos
+
+| Tamanho   | Dimensao        | Icone             | Uso                |
+| --------- | --------------- | ----------------- | ------------------ |
+| `default` | `size-4` (16px) | `size-3.5` (14px) | Formularios padrao |
+
+> **Roadmap:** Considerar adicionar `sm` (12px) e `lg` (20px) baseado em padroes de MUI, Mantine e Chakra.
+
+### Estados
+
+| Estado   | Classes/Atributos                                                  | Comportamento                                |
+| -------- | ------------------------------------------------------------------ | -------------------------------------------- |
+| Default  | `border-input`                                                     | Borda cinza, fundo transparente              |
+| Checked  | `data-[state=checked]:bg-primary`                                  | Fundo primary, icone check branco            |
+| Hover    | -                                                                  | Nao implementado explicitamente              |
+| Focus    | `focus-visible:ring-[3px]`                                         | Ring com `ring-ring/50`, borda `border-ring` |
+| Disabled | `disabled:opacity-50 disabled:cursor-not-allowed`                  | 50% opacidade, cursor bloqueado              |
+| Invalid  | `aria-invalid:ring-destructive/20 aria-invalid:border-destructive` | Ring e borda vermelhos                       |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input          /* Borda default */
+--primary        /* Background quando checked */
+--primary-foreground  /* Cor do icone */
+--ring           /* Focus ring */
+--destructive    /* Estado de erro */
+
+/* Espacamento */
+size-4           /* 16px - dimensao do checkbox */
+size-3.5         /* 14px - dimensao do icone */
+
+/* Bordas */
+rounded-[4px]    /* Border radius fixo */
+border           /* 1px solid */
+
+/* Sombras */
+shadow-xs        /* Sombra sutil */
+
+/* Transicoes */
+transition-shadow  /* Animacao do focus ring */
+```
+
+### data-slot
+
+```html
+<button data-slot="checkbox">
+  <span data-slot="checkbox-indicator">
+    <svg><!-- CheckIcon --></svg>
+  </span>
+</button>
+```
+
+### Padrão de Tokens com Tailwind v4
+
+O componente Checkbox utiliza tokens de design definidos em `@etus/tokens`. No Tailwind v4, variáveis CSS que contêm cores OKLCH precisam do prefixo `color:` para serem interpretadas corretamente.
+
+#### Tokens Disponíveis
+
+```css
+/* Gerados em packages/tokens/styles/tokens.css */
+--checkbox-root-bg-default
+--checkbox-root-bg-checked
+--checkbox-root-bg-disabled
+--checkbox-root-border-default
+--checkbox-root-border-checked
+--checkbox-root-border-focus
+--checkbox-root-radius
+--checkbox-indicator-color
+--checkbox-size-sm
+--checkbox-size-md
+--checkbox-size-lg
+```
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - cores precisam do prefixo color:
+bg-[color:var(--checkbox-root-bg-default)]
+bg-[color:var(--checkbox-root-bg-checked)]
+border-[color:var(--checkbox-root-border-default)]
+text-[color:var(--checkbox-indicator-color)]
+
+// ✅ CORRETO - dimensões não precisam de prefixo
+size-[var(--checkbox-size-md)]
+rounded-[var(--checkbox-root-radius)]
+
+// ❌ INCORRETO - nunca usar hsl() ou omitir color:
+bg-[hsl(var(--checkbox-root-bg-default))]
+bg-[var(--checkbox-root-bg-default)]
+```
+
+#### Por que usar `color:`?
+
+Os tokens de cor do Seven usam OKLCH (e.g., `oklch(81.06% 0.2032 150.12)`). O Tailwind v4 precisa do type hint `color:` para interpretar corretamente esses valores como cores em propriedades como `background-color` e `border-color`.
+
+---
+
+## API
+
+### Props
+
+| Prop              | Tipo                                            | Padrao  | Descricao                       |
+| ----------------- | ----------------------------------------------- | ------- | ------------------------------- |
+| `checked`         | `boolean \| "indeterminate"`                    | -       | Estado controlado               |
+| `defaultChecked`  | `boolean`                                       | `false` | Estado inicial (nao controlado) |
+| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | -       | Callback de mudanca             |
+| `disabled`        | `boolean`                                       | `false` | Desabilita o componente         |
+| `required`        | `boolean`                                       | `false` | Marca como obrigatorio          |
+| `name`            | `string`                                        | -       | Nome para form submission       |
+| `value`           | `string`                                        | `"on"`  | Valor para form submission      |
+| `className`       | `string`                                        | -       | Classes CSS adicionais          |
+| `ref`             | `Ref<HTMLButtonElement>`                        | -       | Referencia ao elemento DOM      |
+
+> Herda todas as props de `React.ComponentProps<typeof CheckboxPrimitive.Root>`
+
+### Callbacks
+
+| Callback          | Tipo                                            | Descricao                    |
+| ----------------- | ----------------------------------------------- | ---------------------------- |
+| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | Chamado quando o estado muda |
+
+### TypeScript
+
+```typescript
+import type { ComponentProps } from "react"
+import type * as CheckboxPrimitive from "@radix-ui/react-checkbox"
+
+// Props do componente (React 19 - ref como prop regular)
+type CheckboxProps = ComponentProps<typeof CheckboxPrimitive.Root>
+
+// Estado do checkbox
+type CheckedState = boolean | "indeterminate"
+
+// Uso
+function MyForm() {
+  const [checked, setChecked] = useState<CheckedState>(false)
+
+  return (
+    <Checkbox
+      checked={checked}
+      onCheckedChange={setChecked}
+    />
+  )
+}
+```
+
+### 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 | PrimeReact |
+| ---------------- | :--: | :----: | :---: | :--------: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: | :--------: |
+| Indeterminate    |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Controlled       |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Uncontrolled     |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Tamanhos         |  -   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    -     |    -    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Cores/Variantes  |  -   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    -     |    -    |   -    |   -    |     ✓     |     ✓      |
+| Label integrado  |  -   |   -    |   -   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Descricao/Helper |  -   |   -    |   -   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     -     |     ✓      |
+| Grupo            |  -   |   -    |   -   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Read-only        |  -   |   -    |   -   |     ✓      |   -    |  ✓  |    -    |  -   |   ✓    |    -     |    -    |   ✓    |   ✓    |     -     |     ✓      |
+| Icone custom     |  -   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |     -      |
+| data-slot        |  ✓   |   ✓    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop            |       ETUS        |      Chakra       |   MUI   |     Mantine     |      AntD       |      NextUI       | Fluent |   Carbon    |
+| --------------- | :---------------: | :---------------: | :-----: | :-------------: | :-------------: | :---------------: | :----: | :---------: |
+| `checked`       |         ✓         |    `isChecked`    |    ✓    |        ✓        |        ✓        |   `isSelected`    |   ✓    |      ✓      |
+| `disabled`      |         ✓         |   `isDisabled`    |    ✓    |        ✓        |        ✓        |   `isDisabled`    |   ✓    |      ✓      |
+| `indeterminate` |    via checked    | `isIndeterminate` |    ✓    | `indeterminate` | `indeterminate` | `isIndeterminate` |   -    |      ✓      |
+| `size`          |         -         |         ✓         |    ✓    |        ✓        |        -        |         ✓         |   ✓    |      ✓      |
+| `color`         |         -         |   `colorScheme`   | `color` |     `color`     |        -        |      `color`      |   -    |      -      |
+| `onChange`      | `onCheckedChange` |         ✓         |    ✓    |        ✓        |        ✓        |  `onValueChange`  |   ✓    |      ✓      |
+| `label`         |     separado      |         ✓         |    ✓    |        ✓        |   `children`    |    `children`     |   ✓    | `labelText` |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo          | Uso                                        |
+| ----------------- | ------------------------------------------ |
+| `role="checkbox"` | Aplicado automaticamente pelo Radix        |
+| `aria-checked`    | `true`, `false` ou `mixed` (indeterminate) |
+| `aria-disabled`   | Quando `disabled={true}`                   |
+| `aria-required`   | Quando `required={true}`                   |
+| `aria-invalid`    | Para estados de erro (estilizado via CSS)  |
+| `aria-labelledby` | Conexao com Label via `htmlFor`            |
+
+### Suporte a Teclado
+
+| Tecla         | Acao                               |
+| ------------- | ---------------------------------- |
+| `Space`       | Alterna o estado checked/unchecked |
+| `Tab`         | Move foco para o proximo elemento  |
+| `Shift + Tab` | Move foco para o elemento anterior |
+
+### 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):
+
+| Estado          | Foreground             | Background     | Ratio   |
+| --------------- | ---------------------- | -------------- | ------- |
+| Checked (Light) | `--primary-foreground` | `--primary`    | > 4.5:1 |
+| Checked (Dark)  | `--primary-foreground` | `--primary`    | > 4.5:1 |
+| Focus Ring      | `--ring`               | `--background` | > 3:1   |
+| Invalid         | `--destructive`        | `--background` | > 4.5:1 |
+
+### Screen Readers
+
+- O estado e anunciado como "checked", "not checked" ou "partially checked"
+- Use sempre com um `<Label>` associado para contexto
+- O nome acessivel vem do label conectado via `htmlFor`/`id`
+
+### Reduced Motion
+
+```tsx
+// Respeitar preferencia do usuario
+motion-reduce:transition-none
+```
+
+> **Nota:** Adicionar `motion-reduce:` ao componente para desabilitar `transition-shadow`.
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature       | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+| ------------- | :--: | :--------: | :---: | :-----: | :------: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: | :-------: | :--------: |
+| ARIA completo |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ~      |
+| Keyboard nav  |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Focus visible |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ~      |
+| Screen reader |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ~      |
+| High contrast |  -   |     ✓      |   -   |    -    |    -     |   -    |  -  |    -    |  -   |   -    |   ✓    |   ✓    |     -     |     -      |
+| RTL support   |  -   |     ✓      |   -   |    -    |    -     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     -     |     ✓      |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Checkbox } from "@etus/ui";
+
+function Example() {
+  return <Checkbox />;
+}
+```
+
+### Com Label
+
+```tsx
+import { Checkbox, Label } from "@etus/ui";
+
+function Example() {
+  return (
+    <div className="flex items-center gap-2">
+      <Checkbox id="terms" />
+      <Label htmlFor="terms">Aceito os termos e condicoes</Label>
+    </div>
+  );
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+import { Checkbox, Label } from "@etus/ui";
+
+function ControlledCheckbox() {
+  const [checked, setChecked] = useState(false);
+
+  return (
+    <div className="flex items-center gap-2">
+      <Checkbox
+        id="newsletter"
+        checked={checked}
+        onCheckedChange={setChecked}
+      />
+      <Label htmlFor="newsletter">
+        Receber newsletter ({checked ? "Sim" : "Nao"})
+      </Label>
+    </div>
+  );
+}
+```
+
+### Estado Indeterminate
+
+```tsx
+import { useState } from "react";
+import { Checkbox, Label } from "@etus/ui";
+import type { CheckedState } from "@radix-ui/react-checkbox";
+
+function IndeterminateExample() {
+  const [items, setItems] = useState([
+    { id: 1, label: "Item 1", checked: false },
+    { id: 2, label: "Item 2", checked: true },
+    { id: 3, label: "Item 3", checked: false },
+  ]);
+
+  const allChecked = items.every((item) => item.checked);
+  const someChecked = items.some((item) => item.checked);
+  const parentState: CheckedState = allChecked
+    ? true
+    : someChecked
+      ? "indeterminate"
+      : false;
+
+  const handleParentChange = (checked: CheckedState) => {
+    if (checked === "indeterminate") return;
+    setItems(items.map((item) => ({ ...item, checked })));
+  };
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-2">
+        <Checkbox
+          id="parent"
+          checked={parentState}
+          onCheckedChange={handleParentChange}
+        />
+        <Label htmlFor="parent" className="font-medium">
+          Selecionar todos
+        </Label>
+      </div>
+      <div className="ml-6 space-y-2">
+        {items.map((item) => (
+          <div key={item.id} className="flex items-center gap-2">
+            <Checkbox
+              id={`item-${item.id}`}
+              checked={item.checked}
+              onCheckedChange={(checked) => {
+                setItems(
+                  items.map((i) =>
+                    i.id === item.id ? { ...i, checked: !!checked } : i,
+                  ),
+                );
+              }}
+            />
+            <Label htmlFor={`item-${item.id}`}>{item.label}</Label>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Estados
+
+```tsx
+import { Checkbox, Label } from "@etus/ui";
+
+function StatesExample() {
+  return (
+    <div className="space-y-4">
+      {/* Default */}
+      <div className="flex items-center gap-2">
+        <Checkbox id="default" />
+        <Label htmlFor="default">Default</Label>
+      </div>
+
+      {/* Checked */}
+      <div className="flex items-center gap-2">
+        <Checkbox id="checked" defaultChecked />
+        <Label htmlFor="checked">Checked</Label>
+      </div>
+
+      {/* Disabled */}
+      <div className="flex items-center gap-2">
+        <Checkbox id="disabled" disabled />
+        <Label htmlFor="disabled" className="opacity-50">
+          Disabled
+        </Label>
+      </div>
+
+      {/* Disabled + Checked */}
+      <div className="flex items-center gap-2">
+        <Checkbox id="disabled-checked" disabled defaultChecked />
+        <Label htmlFor="disabled-checked" className="opacity-50">
+          Disabled Checked
+        </Label>
+      </div>
+
+      {/* Invalid */}
+      <div className="flex items-center gap-2">
+        <Checkbox id="invalid" aria-invalid="true" />
+        <Label htmlFor="invalid" className="text-destructive">
+          Obrigatorio
+        </Label>
+      </div>
+    </div>
+  );
+}
+```
+
+### Com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import {
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+} from "@etus/ui";
+import { Checkbox } from "@etus/ui";
+import { Button } from "@etus/ui";
+
+const formSchema = z.object({
+  marketing: z.boolean().default(false),
+  terms: z.boolean().refine((val) => val === true, {
+    message: "Voce deve aceitar os termos",
+  }),
+});
+
+function FormExample() {
+  const form = useForm<z.infer<typeof formSchema>>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      marketing: false,
+      terms: false,
+    },
+  });
+
+  function onSubmit(data: z.infer<typeof formSchema>) {
+    console.log(data);
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+        <FormField
+          control={form.control}
+          name="marketing"
+          render={({ field }) => (
+            <FormItem className="flex items-start gap-3">
+              <FormControl>
+                <Checkbox
+                  checked={field.value}
+                  onCheckedChange={field.onChange}
+                />
+              </FormControl>
+              <div className="space-y-1 leading-none">
+                <FormLabel>Emails de marketing</FormLabel>
+                <FormDescription>
+                  Receba novidades sobre produtos e ofertas.
+                </FormDescription>
+              </div>
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="terms"
+          render={({ field }) => (
+            <FormItem className="flex items-start gap-3">
+              <FormControl>
+                <Checkbox
+                  checked={field.value}
+                  onCheckedChange={field.onChange}
+                />
+              </FormControl>
+              <div className="space-y-1 leading-none">
+                <FormLabel>Termos e condicoes</FormLabel>
+                <FormDescription>
+                  Concordo com os termos de uso.
+                </FormDescription>
+                <FormMessage />
+              </div>
+            </FormItem>
+          )}
+        />
+
+        <Button type="submit">Enviar</Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+### Lista de Checkboxes
+
+```tsx
+import { useState } from "react";
+import {
+  Checkbox,
+  Label,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@etus/ui";
+
+const permissions = [
+  { id: "read", label: "Leitura", description: "Visualizar conteudo" },
+  { id: "write", label: "Escrita", description: "Criar e editar" },
+  { id: "delete", label: "Exclusao", description: "Remover conteudo" },
+  { id: "admin", label: "Admin", description: "Acesso total" },
+];
+
+function PermissionsExample() {
+  const [selected, setSelected] = useState<string[]>(["read"]);
+
+  const togglePermission = (id: string) => {
+    setSelected((prev) =>
+      prev.includes(id) ? prev.filter((p) => p !== id) : [...prev, id],
+    );
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Permissoes</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        {permissions.map((permission) => (
+          <div key={permission.id} className="flex items-start gap-3">
+            <Checkbox
+              id={permission.id}
+              checked={selected.includes(permission.id)}
+              onCheckedChange={() => togglePermission(permission.id)}
+            />
+            <div className="grid gap-0.5">
+              <Label htmlFor={permission.id}>{permission.label}</Label>
+              <p className="text-sm text-muted-foreground">
+                {permission.description}
+              </p>
+            </div>
+          </div>
+        ))}
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Checkbox.test.tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Checkbox } from "./Checkbox";
+
+describe("Checkbox", () => {
+  it("renderiza corretamente", () => {
+    render(<Checkbox />);
+    expect(screen.getByRole("checkbox")).toBeInTheDocument();
+  });
+
+  it("possui data-slot attribute", () => {
+    render(<Checkbox />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute(
+      "data-slot",
+      "checkbox",
+    );
+  });
+
+  it("inicia desmarcado por padrao", () => {
+    render(<Checkbox />);
+    expect(screen.getByRole("checkbox")).not.toBeChecked();
+  });
+
+  it("inicia marcado com defaultChecked", () => {
+    render(<Checkbox defaultChecked />);
+    expect(screen.getByRole("checkbox")).toBeChecked();
+  });
+
+  it("aplica classes customizadas", () => {
+    render(<Checkbox className="custom-class" />);
+    expect(screen.getByRole("checkbox")).toHaveClass("custom-class");
+  });
+});
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Checkbox interactions", () => {
+  it("alterna estado ao clicar", async () => {
+    const user = userEvent.setup();
+    render(<Checkbox />);
+
+    const checkbox = screen.getByRole("checkbox");
+    expect(checkbox).not.toBeChecked();
+
+    await user.click(checkbox);
+    expect(checkbox).toBeChecked();
+
+    await user.click(checkbox);
+    expect(checkbox).not.toBeChecked();
+  });
+
+  it("alterna estado ao pressionar Space", async () => {
+    const user = userEvent.setup();
+    render(<Checkbox />);
+
+    const checkbox = screen.getByRole("checkbox");
+    checkbox.focus();
+
+    await user.keyboard(" ");
+    expect(checkbox).toBeChecked();
+  });
+
+  it("chama onCheckedChange ao mudar", async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(<Checkbox onCheckedChange={handleChange} />);
+
+    await user.click(screen.getByRole("checkbox"));
+    expect(handleChange).toHaveBeenCalledWith(true);
+
+    await user.click(screen.getByRole("checkbox"));
+    expect(handleChange).toHaveBeenCalledWith(false);
+  });
+
+  it("nao alterna quando disabled", async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(<Checkbox disabled onCheckedChange={handleChange} />);
+
+    await user.click(screen.getByRole("checkbox"));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it("suporta estado controlado", async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    const { rerender } = render(
+      <Checkbox checked={false} onCheckedChange={handleChange} />,
+    );
+
+    expect(screen.getByRole("checkbox")).not.toBeChecked();
+
+    await user.click(screen.getByRole("checkbox"));
+    expect(handleChange).toHaveBeenCalledWith(true);
+
+    // Simula re-render com novo estado
+    rerender(<Checkbox checked={true} onCheckedChange={handleChange} />);
+    expect(screen.getByRole("checkbox")).toBeChecked();
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Checkbox accessibility", () => {
+  it("nao tem violacoes de acessibilidade", async () => {
+    const { container } = render(
+      <div>
+        <Checkbox id="accessible" />
+        <label htmlFor="accessible">Label</label>
+      </div>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("tem role checkbox", () => {
+    render(<Checkbox />);
+    expect(screen.getByRole("checkbox")).toBeInTheDocument();
+  });
+
+  it("possui aria-checked correto", async () => {
+    const user = userEvent.setup();
+    render(<Checkbox />);
+
+    const checkbox = screen.getByRole("checkbox");
+    expect(checkbox).toHaveAttribute("aria-checked", "false");
+
+    await user.click(checkbox);
+    expect(checkbox).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("possui aria-disabled quando disabled", () => {
+    render(<Checkbox disabled />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("data-disabled");
+  });
+
+  it("e focavel via teclado", () => {
+    render(<Checkbox />);
+    const checkbox = screen.getByRole("checkbox");
+    checkbox.focus();
+    expect(document.activeElement).toBe(checkbox);
+  });
+
+  it("conecta com label via id", () => {
+    render(
+      <>
+        <Checkbox id="my-checkbox" />
+        <label htmlFor="my-checkbox">My Label</label>
+      </>,
+    );
+
+    const checkbox = screen.getByRole("checkbox");
+    expect(checkbox).toHaveAttribute("id", "my-checkbox");
+    expect(screen.getByText("My Label")).toHaveAttribute("for", "my-checkbox");
+  });
+});
+```
+
+### Testes de Estado Indeterminate
+
+```tsx
+describe("Checkbox indeterminate state", () => {
+  it("suporta estado indeterminate", () => {
+    render(<Checkbox checked="indeterminate" />);
+    const checkbox = screen.getByRole("checkbox");
+    expect(checkbox).toHaveAttribute("aria-checked", "mixed");
+    expect(checkbox).toHaveAttribute("data-state", "indeterminate");
+  });
+
+  it("transiciona de indeterminate para checked", async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(<Checkbox checked="indeterminate" onCheckedChange={handleChange} />);
+
+    await user.click(screen.getByRole("checkbox"));
+    expect(handleChange).toHaveBeenCalledWith(true);
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+- [x] **Tamanhos (size)**: Adicionar `sm`, `md`, `lg` como Chakra, MUI, Mantine
+- [x] **CheckboxGroup**: Componente para gerenciar grupo de checkboxes
+- [ ] **Reduced motion**: Adicionar `motion-reduce:transition-none`
+
+### Prioridade Media
+
+- [ ] **Variantes de cor**: `success`, `warning`, `error` como NextUI
+- [ ] **Label integrado**: Prop `label` como Mantine/AntD para simplificar uso
+- [ ] **Descricao/Helper**: Prop `description` para texto auxiliar
+- [ ] **Icone customizado**: Permitir trocar o CheckIcon padrao
+
+### Prioridade Baixa
+
+- [ ] **Read-only**: Estado visual sem interacao (diferente de disabled)
+- [ ] **RTL support**: Suporte para right-to-left
+- [ ] **High contrast mode**: Suporte para modo alto contraste (Fluent UI pattern)
+
+### Decisoes de Design
+
+| Feature                  | Recomendacao            | Justificativa                                            |
+| ------------------------ | ----------------------- | -------------------------------------------------------- |
+| `size`                   | Implementar             | 10/14 DS suportam; alta demanda em formularios complexos |
+| `color`/`colorScheme`    | Nao implementar         | Conflita com design tokens semanticos; usar variantes    |
+| `CheckboxGroup`          | Implementar             | 12/14 DS suportam; padrao essencial para formularios     |
+| Label integrado          | Implementar com cuidado | Manter compatibilidade com Label separado                |
+| `isChecked` vs `checked` | Manter `checked`        | Consistente com HTML nativo e Radix                      |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System   | Documentacao                                                             | GitHub                                                                        |
+| --------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**   | [Checkbox](https://ui.shadcn.com/docs/components/checkbox)               | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**    | [Checkbox](https://www.radix-ui.com/primitives/docs/components/checkbox) | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **React Aria**  | [Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html)    | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**   | [Checkbox](https://chakra-ui.com/docs/components/checkbox)               | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**         | [Checkbox](https://mui.com/material-ui/react-checkbox/)                  | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**     | [Checkbox](https://mantine.dev/core/checkbox/)                           | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design**  | [Checkbox](https://ant.design/components/checkbox)                       | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**      | [Checkbox](https://nextui.org/docs/components/checkbox)                  | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Headless UI** | [Checkbox](https://headlessui.com/react/checkbox)                        | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)         |
+| **Ariakit**     | [Checkbox](https://ariakit.org/components/checkbox)                      | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**   | [Checkbox](https://react.fluentui.dev/?path=/docs/components-checkbox)   | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**      | [Checkbox](https://carbondesignsystem.com/components/checkbox/usage/)    | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**   | [Checkbox](https://blueprintjs.com/docs/#core/components/checkbox)       | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact**  | [Checkbox](https://primereact.org/checkbox/)                             | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - input type="checkbox"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [Radix Checkbox](https://www.radix-ui.com/primitives/docs/components/checkbox)
+- [Lucide Icons](https://lucide.dev/icons/)