@etus/ui 0.1.0

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

@@ -0,0 +1,785 @@
+# Switch
+
+## Visão Geral
+
+O **Switch** e um componente de controle binario que permite ao usuario alternar entre dois estados mutuamente exclusivos (ligado/desligado, ativo/inativo). Como elemento atom, e a unidade fundamental para construcao de formularios e configuracoes interativas.
+
+### Casos de Uso
+
+- Ativar/desativar funcionalidades ou configuracoes
+- Alternar preferencias do usuario (modo escuro, notificacoes)
+- Controlar estados on/off em paineis de administracao
+- Toggle de visibilidade ou disponibilidade de recursos
+
+### Classificacao
+
+**Categoria:** Atom (elemento de formulario)
+**Dependencias:** `@radix-ui/react-switch`
+
+---
+
+## Design Specs
+
+### Estados (via data-state)
+
+| Estado    | Atributo                 | Classes                         | Comportamento                   |
+| --------- | ------------------------ | ------------------------------- | ------------------------------- |
+| Unchecked | `data-[state=unchecked]` | `bg-input`                      | Fundo neutro, thumb a esquerda  |
+| Checked   | `data-[state=checked]`   | `bg-primary`                    | Fundo primario, thumb a direita |
+| Focus     | `focus-visible:*`        | `ring-[3px] ring-ring/50`       | Ring de foco visivel            |
+| Disabled  | `disabled`               | `opacity-50 cursor-not-allowed` | 50% opacidade, sem interacao    |
+
+### Dimensoes
+
+| Propriedade   | Valor             | Token CSS      |
+| ------------- | ----------------- | -------------- |
+| Altura        | `1.15rem` (~18px) | Customizado    |
+| Largura       | `2rem` (32px)     | `w-8`          |
+| Thumb         | `1rem` (16px)     | `size-4`       |
+| Border Radius | `full`            | `rounded-full` |
+
+### Tokens Utilizados
+
+```css
+/* Cores - Estado Unchecked */
+--color-input             /* Fundo do track */
+--color-background        /* Cor do thumb */
+
+/* Cores - Estado Checked */
+--color-primary           /* Fundo do track */
+--color-primary-foreground /* Cor do thumb (dark mode) */
+
+/* Cores - Focus */
+--color-ring              /* Ring de foco */
+--color-ring/50           /* Ring com opacidade */
+
+/* Dark Mode */
+--color-input/80          /* Track unchecked (dark) */
+--color-foreground        /* Thumb unchecked (dark) */
+
+/* Transicoes */
+transition-all            /* Track */
+transition-transform      /* Thumb */
+```
+
+### data-slot
+
+```html
+<button data-slot="switch">
+  <span data-slot="switch-thumb">...</span>
+</button>
+```
+
+### Padrão de Tokens com Tailwind v4
+
+O componente Switch 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 */
+/* Track */
+--switch-track-bg-off
+--switch-track-bg-on
+--switch-track-bg-disabled
+--switch-track-radius
+
+/* Thumb */
+--switch-thumb-bg
+--switch-thumb-radius
+
+/* Tamanhos */
+--switch-size-sm-h
+--switch-size-sm-w
+--switch-size-md-h
+--switch-size-md-w
+--switch-size-lg-h
+--switch-size-lg-w
+--switch-thumb-size-sm
+--switch-thumb-size-md
+--switch-thumb-size-lg
+```
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - cores precisam do prefixo color:
+bg-[color:var(--switch-track-bg-off)]
+bg-[color:var(--switch-track-bg-on)]
+bg-[color:var(--switch-thumb-bg)]
+data-[state=checked]:bg-[color:var(--switch-track-bg-on)]
+
+// ✅ CORRETO - dimensões não precisam de prefixo
+h-[var(--switch-size-md-h)]
+w-[var(--switch-size-md-w)]
+size-[var(--switch-thumb-size-md)]
+rounded-[var(--switch-track-radius)]
+
+// ❌ INCORRETO - nunca usar hsl() ou omitir prefixo para cores
+bg-[hsl(var(--switch-track-bg-off))]
+bg-[var(--switch-track-bg-off)]
+```
+
+#### 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`.
+
+---
+
+## API
+
+### Props
+
+| Prop              | Tipo                         | Padrao  | Descricao                       |
+| ----------------- | ---------------------------- | ------- | ------------------------------- |
+| `checked`         | `boolean`                    | -       | Estado controlado do switch     |
+| `defaultChecked`  | `boolean`                    | `false` | Estado inicial (nao-controlado) |
+| `onCheckedChange` | `(checked: boolean) => void` | -       | Callback quando o estado muda   |
+| `disabled`        | `boolean`                    | `false` | Desabilita o componente         |
+| `required`        | `boolean`                    | `false` | Campo obrigatorio               |
+| `name`            | `string`                     | -       | Nome do campo para formularios  |
+| `value`           | `string`                     | `"on"`  | Valor enviado no formulario     |
+| `className`       | `string`                     | -       | Classes CSS adicionais          |
+| `ref`             | `Ref<HTMLButtonElement>`     | -       | Referencia ao elemento DOM      |
+
+> Herda todas as props de `React.ComponentProps<typeof SwitchPrimitive.Root>`
+
+### Callbacks
+
+| Callback          | Tipo                         | Descricao                         |
+| ----------------- | ---------------------------- | --------------------------------- |
+| `onCheckedChange` | `(checked: boolean) => void` | Disparado quando o estado alterna |
+
+### TypeScript
+
+```typescript
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+
+// Props do componente
+type SwitchProps = React.ComponentProps<typeof SwitchPrimitive.Root>;
+
+// Exemplo de uso tipado
+interface SettingSwitchProps {
+  label: string;
+  checked: boolean;
+  onCheckedChange: (checked: boolean) => void;
+  disabled?: boolean;
+}
+```
+
+### 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 |
+| ---------------- | :--: | :----: | :---: | :--------: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: | :--------: |
+| Controlled       |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Uncontrolled     |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Disabled         |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Required         |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    ✓     |    ✓    |   ✓    |   -    |     -     |     -      |
+| Size variants    |  -   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Color variants   |  -   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |     ✓      |
+| Label integrado  |  -   |   -    |   -   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Loading state    |  -   |   -    |   -   |     -      |   -    |  -  |    -    |  ✓   |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+| Icons on/off     |  -   |   -    |   -   |     -      |   -    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   -    |   -    |     -     |     ✓      |
+| data-slot        |  ✓   |   ✓    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+| Form integration |  ✓   |   ✓    |   ✓   |     ✓      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop ETUS         |    Chakra     |    MUI     |  Mantine   |    AntD    |     NextUI      |   Fluent   |   Carbon   |
+| ----------------- | :-----------: | :--------: | :--------: | :--------: | :-------------: | :--------: | :--------: |
+| `checked`         |  `isChecked`  | `checked`  | `checked`  | `checked`  |  `isSelected`   | `checked`  | `toggled`  |
+| `onCheckedChange` |  `onChange`   | `onChange` | `onChange` | `onChange` | `onValueChange` | `onChange` | `onToggle` |
+| `disabled`        | `isDisabled`  | `disabled` | `disabled` | `disabled` |  `isDisabled`   | `disabled` | `disabled` |
+| `name`            |    `name`     |   `name`   |   `name`   |     -      |     `name`      |   `name`   |   `name`   |
+| -                 |    `size`     |   `size`   |   `size`   |   `size`   |     `size`      |   `size`   |   `size`   |
+| -                 | `colorScheme` |  `color`   |  `color`   |     -      |     `color`     |     -      |     -      |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo          | Valor           | Uso                                         |
+| ----------------- | --------------- | ------------------------------------------- |
+| `role`            | `"switch"`      | Identifica como controle de alternancia     |
+| `aria-checked`    | `true \| false` | Indica estado atual (gerenciado pelo Radix) |
+| `aria-disabled`   | `true \| false` | Indica se esta desabilitado                 |
+| `aria-required`   | `true \| false` | Indica se e obrigatorio                     |
+| `aria-labelledby` | `string`        | Referencia ao label externo                 |
+
+### Suporte a Teclado
+
+| Tecla   | Acao                       |
+| ------- | -------------------------- |
+| `Space` | Alterna o estado do switch |
+| `Enter` | Alterna o estado do switch |
+| `Tab`   | Move o foco para/do switch |
+
+### 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 para texto, 3:1 para UI):
+
+| Estado     | Foreground           | Background   | Ratio  |
+| ---------- | -------------------- | ------------ | ------ |
+| Unchecked  | `background`         | `input`      | >= 3:1 |
+| Checked    | `primary-foreground` | `primary`    | >= 3:1 |
+| Focus Ring | `ring`               | `background` | >= 3:1 |
+
+### Screen Readers
+
+- O componente usa `role="switch"` nativo do Radix UI
+- O estado e anunciado automaticamente via `aria-checked`
+- Deve ser associado a um `<Label>` para contexto semantico
+- Mudancas de estado sao anunciadas automaticamente
+
+### Reduced Motion
+
+```tsx
+// O componente respeita preferencias de movimento reduzido
+// via classes Tailwind quando necessario
+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 |
+| -------------------- | :--: | :--------: | :---: | :-----: | :------: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: | :-------: | :--------: |
+| role="switch"        |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ~      |
+| aria-checked         |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Keyboard nav         |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Focus visible        |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ✓     |     ~      |
+| Label association    |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| Screen reader tested |  ~   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ~    |  ~   |   ~    |   ✓    |   ✓    |     ~     |     ~      |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Switch } from "@etus/ui";
+
+function Example() {
+  return <Switch />;
+}
+```
+
+### Controlado com Estado
+
+```tsx
+import { useState } from "react";
+import { Switch } from "@etus/ui";
+
+function ControlledSwitch() {
+  const [enabled, setEnabled] = useState(false);
+
+  return <Switch checked={enabled} onCheckedChange={setEnabled} />;
+}
+```
+
+### Com Label
+
+```tsx
+import { Switch, Label } from "@etus/ui";
+
+function SwitchWithLabel() {
+  return (
+    <div className="flex items-center gap-2">
+      <Switch id="airplane-mode" />
+      <Label htmlFor="airplane-mode">Modo Aviao</Label>
+    </div>
+  );
+}
+```
+
+### Estado Desabilitado
+
+```tsx
+import { Switch, Label } from "@etus/ui";
+
+function DisabledSwitch() {
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-2">
+        <Switch id="disabled-off" disabled />
+        <Label htmlFor="disabled-off" className="text-muted-foreground">
+          Desabilitado (off)
+        </Label>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <Switch id="disabled-on" disabled defaultChecked />
+        <Label htmlFor="disabled-on" className="text-muted-foreground">
+          Desabilitado (on)
+        </Label>
+      </div>
+    </div>
+  );
+}
+```
+
+### Em Formulario
+
+```tsx
+import { Switch, Label } from "@etus/ui";
+import { useForm } from "react-hook-form";
+
+interface FormData {
+  notifications: boolean;
+  marketing: boolean;
+}
+
+function FormWithSwitch() {
+  const { register, handleSubmit, watch, setValue } = useForm<FormData>({
+    defaultValues: {
+      notifications: true,
+      marketing: false,
+    },
+  });
+
+  const onSubmit = (data: FormData) => {
+    console.log(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+      <div className="flex items-center justify-between">
+        <Label htmlFor="notifications">Notificacoes</Label>
+        <Switch
+          id="notifications"
+          checked={watch("notifications")}
+          onCheckedChange={(checked) => setValue("notifications", checked)}
+        />
+      </div>
+
+      <div className="flex items-center justify-between">
+        <Label htmlFor="marketing">E-mails de marketing</Label>
+        <Switch
+          id="marketing"
+          checked={watch("marketing")}
+          onCheckedChange={(checked) => setValue("marketing", checked)}
+        />
+      </div>
+
+      <button type="submit">Salvar</button>
+    </form>
+  );
+}
+```
+
+### Lista de Configuracoes
+
+```tsx
+import { Switch, Label } from "@etus/ui";
+
+interface Setting {
+  id: string;
+  label: string;
+  description: string;
+  defaultValue: boolean;
+}
+
+const settings: Setting[] = [
+  {
+    id: "dark-mode",
+    label: "Modo Escuro",
+    description: "Usar tema escuro na interface",
+    defaultValue: false,
+  },
+  {
+    id: "notifications",
+    label: "Notificacoes",
+    description: "Receber notificacoes push",
+    defaultValue: true,
+  },
+  {
+    id: "sounds",
+    label: "Sons",
+    description: "Reproduzir sons de feedback",
+    defaultValue: true,
+  },
+];
+
+function SettingsList() {
+  return (
+    <div className="divide-y divide-border rounded-lg border">
+      {settings.map((setting) => (
+        <div key={setting.id} className="flex items-center justify-between p-4">
+          <div className="space-y-0.5">
+            <Label htmlFor={setting.id}>{setting.label}</Label>
+            <p className="text-sm text-muted-foreground">
+              {setting.description}
+            </p>
+          </div>
+          <Switch id={setting.id} defaultChecked={setting.defaultValue} />
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Com Callback
+
+```tsx
+import { Switch } from "@etus/ui";
+import { toast } from "sonner";
+
+function SwitchWithCallback() {
+  const handleChange = (checked: boolean) => {
+    toast.success(checked ? "Ativado" : "Desativado");
+  };
+
+  return <Switch onCheckedChange={handleChange} />;
+}
+```
+
+### Responsividade
+
+```tsx
+import { Switch, Label } from "@etus/ui";
+
+function ResponsiveSwitch() {
+  return (
+    <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+      <div>
+        <Label htmlFor="feature" className="text-base font-medium">
+          Nova Funcionalidade
+        </Label>
+        <p className="text-sm text-muted-foreground">
+          Ativar funcionalidade experimental
+        </p>
+      </div>
+      <Switch id="feature" className="self-start sm:self-center" />
+    </div>
+  );
+}
+```
+
+### Ref com React 19
+
+```tsx
+import { useRef, useEffect } from "react";
+import { Switch } from "@etus/ui";
+
+function SwitchWithRef() {
+  const switchRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    // Foco automatico no mount
+    switchRef.current?.focus();
+  }, []);
+
+  return <Switch ref={switchRef} aria-label="Auto-focado" />;
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Switch.test.tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Switch } from "./Switch";
+
+describe("Switch", () => {
+  it("renderiza corretamente", () => {
+    render(<Switch aria-label="Test switch" />);
+    expect(screen.getByRole("switch")).toBeInTheDocument();
+  });
+
+  it("possui data-slot attribute", () => {
+    render(<Switch aria-label="Test switch" />);
+    expect(screen.getByRole("switch")).toHaveAttribute("data-slot", "switch");
+  });
+
+  it("inicia no estado unchecked por padrao", () => {
+    render(<Switch aria-label="Test switch" />);
+    expect(screen.getByRole("switch")).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+  });
+
+  it("aceita defaultChecked", () => {
+    render(<Switch aria-label="Test switch" defaultChecked />);
+    expect(screen.getByRole("switch")).toHaveAttribute("data-state", "checked");
+  });
+
+  it("aplica className customizado", () => {
+    render(<Switch aria-label="Test switch" className="custom-class" />);
+    expect(screen.getByRole("switch")).toHaveClass("custom-class");
+  });
+});
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Switch interactions", () => {
+  it("alterna estado ao clicar", async () => {
+    const user = userEvent.setup();
+    render(<Switch aria-label="Test switch" />);
+
+    const switchEl = screen.getByRole("switch");
+
+    expect(switchEl).toHaveAttribute("data-state", "unchecked");
+    await user.click(switchEl);
+    expect(switchEl).toHaveAttribute("data-state", "checked");
+    await user.click(switchEl);
+    expect(switchEl).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("alterna estado com Space", async () => {
+    const user = userEvent.setup();
+    render(<Switch aria-label="Test switch" />);
+
+    const switchEl = screen.getByRole("switch");
+    switchEl.focus();
+
+    await user.keyboard(" ");
+    expect(switchEl).toHaveAttribute("data-state", "checked");
+  });
+
+  it("alterna estado com Enter", async () => {
+    const user = userEvent.setup();
+    render(<Switch aria-label="Test switch" />);
+
+    const switchEl = screen.getByRole("switch");
+    switchEl.focus();
+
+    await user.keyboard("{Enter}");
+    expect(switchEl).toHaveAttribute("data-state", "checked");
+  });
+
+  it("chama onCheckedChange ao alternar", async () => {
+    const handleChange = vi.fn();
+    const user = userEvent.setup();
+
+    render(<Switch aria-label="Test switch" onCheckedChange={handleChange} />);
+
+    await user.click(screen.getByRole("switch"));
+    expect(handleChange).toHaveBeenCalledWith(true);
+
+    await user.click(screen.getByRole("switch"));
+    expect(handleChange).toHaveBeenCalledWith(false);
+  });
+
+  it("nao alterna quando disabled", async () => {
+    const handleChange = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <Switch
+        aria-label="Test switch"
+        disabled
+        onCheckedChange={handleChange}
+      />,
+    );
+
+    await user.click(screen.getByRole("switch"));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Switch accessibility", () => {
+  it("nao possui violacoes de acessibilidade", async () => {
+    const { container } = render(
+      <div>
+        <label htmlFor="a11y-switch">Label</label>
+        <Switch id="a11y-switch" />
+      </div>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("possui role switch", () => {
+    render(<Switch aria-label="Test switch" />);
+    expect(screen.getByRole("switch")).toBeInTheDocument();
+  });
+
+  it("atualiza aria-checked ao alternar", async () => {
+    const user = userEvent.setup();
+    render(<Switch aria-label="Test switch" />);
+
+    const switchEl = screen.getByRole("switch");
+
+    expect(switchEl).toHaveAttribute("aria-checked", "false");
+    await user.click(switchEl);
+    expect(switchEl).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("possui aria-disabled quando disabled", () => {
+    render(<Switch aria-label="Test switch" disabled />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-disabled", "true");
+  });
+
+  it("e focavel via teclado", async () => {
+    const user = userEvent.setup();
+    render(<Switch aria-label="Test switch" />);
+
+    await user.tab();
+    expect(screen.getByRole("switch")).toHaveFocus();
+  });
+
+  it("nao e focavel quando disabled", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <button>Before</button>
+        <Switch aria-label="Test switch" disabled />
+        <button>After</button>
+      </>,
+    );
+
+    await user.tab(); // Focus on Before
+    await user.tab(); // Should skip Switch, go to After
+    expect(screen.getByText("After")).toHaveFocus();
+  });
+});
+```
+
+### Testes de Controlado vs Nao-Controlado
+
+```tsx
+describe("Switch controlled vs uncontrolled", () => {
+  it("funciona no modo nao-controlado", async () => {
+    const user = userEvent.setup();
+    render(<Switch aria-label="Test switch" defaultChecked={false} />);
+
+    const switchEl = screen.getByRole("switch");
+
+    expect(switchEl).toHaveAttribute("data-state", "unchecked");
+    await user.click(switchEl);
+    expect(switchEl).toHaveAttribute("data-state", "checked");
+  });
+
+  it("funciona no modo controlado", async () => {
+    const user = userEvent.setup();
+    let checked = false;
+    const handleChange = vi.fn((value: boolean) => {
+      checked = value;
+    });
+
+    const { rerender } = render(
+      <Switch
+        aria-label="Test switch"
+        checked={checked}
+        onCheckedChange={handleChange}
+      />,
+    );
+
+    await user.click(screen.getByRole("switch"));
+    expect(handleChange).toHaveBeenCalledWith(true);
+
+    // Simula re-render com novo estado
+    rerender(
+      <Switch
+        aria-label="Test switch"
+        checked={true}
+        onCheckedChange={handleChange}
+      />,
+    );
+
+    expect(screen.getByRole("switch")).toHaveAttribute("data-state", "checked");
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+- [x] **Size variants** (`sm`, `md`, `lg`) - Implementado em 10/14 DS
+- [ ] **Label integrado** - Componente SwitchField com label + description
+
+### Prioridade Media
+
+- [ ] **Color variants** - Cores semanticas (success, warning, danger)
+- [ ] **Icons on/off** - Icones dentro do thumb para estados
+- [ ] **Loading state** - Animacao de carregamento durante operacoes async
+
+### Prioridade Baixa
+
+- [ ] **LabelPosition** - Label a esquerda ou direita
+- [ ] **Gradient support** - Gradientes customizados no track
+
+### Decisoes de Design
+
+| Feature         | Recomendacao | Justificativa                                                      |
+| --------------- | ------------ | ------------------------------------------------------------------ |
+| Size variants   | Implementar  | Alta demanda, 10+ DS implementam                                   |
+| Color variants  | Avaliar      | Util para estados semanticos, mas pode conflitar com design system |
+| Label integrado | Implementar  | Melhora DX, padrao comum em 11+ DS                                 |
+| Icons           | Adiar        | Complexidade vs beneficio baixo                                    |
+| Loading         | Adiar        | Caso de uso especifico, AntD unico a implementar                   |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System   | Documentacao                                                         | GitHub                                                                        |
+| --------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**   | [Switch](https://ui.shadcn.com/docs/components/switch)               | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**    | [Switch](https://www.radix-ui.com/primitives/docs/components/switch) | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **React Aria**  | [Switch](https://react-spectrum.adobe.com/react-aria/Switch.html)    | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**   | [Switch](https://chakra-ui.com/docs/components/switch)               | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**         | [Switch](https://mui.com/material-ui/react-switch/)                  | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**     | [Switch](https://mantine.dev/core/switch/)                           | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design**  | [Switch](https://ant.design/components/switch)                       | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**      | [Switch](https://nextui.org/docs/components/switch)                  | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Headless UI** | [Switch](https://headlessui.com/react/switch)                        | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)         |
+| **Ariakit**     | [Checkbox](https://ariakit.org/components/checkbox)                  | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**   | [Switch](https://react.fluentui.dev/?path=/docs/components-switch)   | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**      | [Toggle](https://carbondesignsystem.com/components/toggle/usage/)    | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**   | [Switch](https://blueprintjs.com/docs/#core/components/switch)       | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact**  | [InputSwitch](https://primereact.org/inputswitch/)                   | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - ARIA: switch role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role)
+
+### Ferramentas Utilizadas
+
+- [Radix UI Switch](https://www.radix-ui.com/primitives/docs/components/switch)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [cn() utility](https://ui.shadcn.com/docs/installation#add-cn-utility)