@etus/ui 0.1.0

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

@@ -0,0 +1,832 @@
+# RadioButton
+
+## Visao Geral
+
+O **RadioButton** e um componente de selecao exclusiva do Design System ETUS, usado para permitir que usuarios escolham uma unica opcao de um grupo de opcoes mutuamente exclusivas. Construido sobre o elemento nativo `<input type="radio">`, oferece acessibilidade nativa completa com estilos customizaveis.
+
+### Casos de Uso
+
+- Selecao de uma opcao entre varias alternativas
+- Formularios com escolha unica obrigatoria
+- Configuracoes com opcoes mutuamente exclusivas
+- Questionarios e pesquisas
+- Filtros de selecao unica
+
+### Classificacao
+
+**Categoria:** Atom (Form Control)
+**Dependencias:** `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Tamanhos (`size`)
+
+| Tamanho | Dimensao | Indicador | Label | Uso |
+|---------|----------|-----------|-------|-----|
+| `sm` | `size-3.5` (14px) | `size-1.5` (6px) | `text-sm ml-2` | Espacos compactos, listas densas |
+| `md` | `size-4` (16px) | `size-2` (8px) | `text-sm ml-2` | Uso geral |
+| `lg` | `size-5` (20px) | `size-2.5` (10px) | `text-base ml-2.5` | Maior visibilidade, touch targets |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Borda input, fundo background |
+| Hover | Herdado do input nativo | Cursor pointer |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50`, borda `border-ring` |
+| Checked | `checked:border-primary checked:bg-primary` | Fundo primary, indicador visivel |
+| Disabled | `disabled:opacity-50` | 50% opacidade, cursor not-allowed |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho, borda destructive |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input             /* Borda default */
+--background        /* Fundo default */
+--primary           /* Fundo/borda checked */
+--primary-foreground /* Indicador checked */
+--ring              /* Focus ring */
+--destructive       /* Estado invalido */
+
+/* Espacamento */
+ml-2               /* Gap label sm/md */
+ml-2.5             /* Gap label lg */
+
+/* Tipografia */
+text-sm            /* Label sm/md */
+text-base          /* Label lg */
+
+/* Bordas */
+rounded-full       /* Radio circular */
+
+/* Transicoes */
+transition-[color,box-shadow]  /* Estados */
+transition-transform           /* Indicador scale */
+```
+
+### data-slot
+
+```html
+<div data-slot="radio-button">
+  <span> <!-- wrapper -->
+    <input type="radio" />
+    <span data-slot="radio-button-indicator" />
+  </span>
+  <label data-slot="radio-button-label">...</label>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho visual do radio button |
+| `label` | `string` | - | Texto do label associado |
+| `id` | `string` | auto-generated | ID do input (gerado automaticamente se nao fornecido) |
+| `name` | `string` | - | Nome do grupo de radios (obrigatorio para agrupamento) |
+| `value` | `string` | - | Valor do radio quando selecionado |
+| `checked` | `boolean` | - | Estado controlado de selecao |
+| `defaultChecked` | `boolean` | - | Estado inicial nao-controlado |
+| `disabled` | `boolean` | `false` | Desabilita o radio button |
+| `required` | `boolean` | `false` | Marca como obrigatorio |
+| `className` | `string` | - | Classes CSS adicionais para o input |
+| `ref` | `Ref<HTMLInputElement>` | - | Referencia ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"input">` exceto `type` e `size`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | Disparado ao mudar selecao |
+| `onFocus` | `(event: FocusEvent<HTMLInputElement>) => void` | Disparado ao receber foco |
+| `onBlur` | `(event: FocusEvent<HTMLInputElement>) => void` | Disparado ao perder foco |
+
+### TypeScript
+
+```typescript
+import type { RadioButtonProps, RadioButtonSize } from "@etus/ui"
+
+// RadioButtonProps inclui:
+interface RadioButtonProps extends Omit<ComponentProps<"input">, "type" | "size"> {
+  size?: RadioButtonSize
+  label?: string
+}
+
+// Tipos derivados
+type RadioButtonSize = "sm" | "md" | "lg"
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|
+| **Native input** | Yes | - | - | - | - | - | - | - | - | - | - | - |
+| **Radix primitive** | - | Yes | Yes | - | - | - | - | - | - | - | - | - |
+| **Tamanhos** | 3 | 1 | - | 3 | 3 | 4 | 3 | 3 | - | - | 2 | 1 |
+| **CVA/cva** | Yes | Yes | - | - | - | - | - | Yes | - | - | - | - |
+| **Label integrado** | Yes | - | - | - | - | Yes | - | - | - | - | - | - |
+| **RadioGroup** | - | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Controlled** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Uncontrolled** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **data-slot** | Yes | Yes | - | - | - | - | - | Yes | - | - | - | - |
+| **Description** | - | - | - | Yes | - | Yes | - | Yes | - | Yes | - | - |
+| **Error state** | Yes | - | - | Yes | Yes | Yes | - | Yes | - | Yes | Yes | Yes |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `size` | Yes | Yes | Yes | Yes | - | Yes | - |
+| `label` | Yes | - | `label` | Yes | - | - | `label` |
+| `disabled` | Yes | `isDisabled` | Yes | Yes | Yes | `isDisabled` | Yes |
+| `checked` | Yes | `isChecked` | Yes | Yes | Yes | `isSelected` | Yes |
+| `value` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `name` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `description` | - | - | - | Yes | - | `description` | - |
+| `colorScheme` | - | Yes | `color` | `color` | - | `color` | - |
+| `isInvalid` | Yes* | Yes | `error` | `error` | - | `isInvalid` | - |
+
+*Via `aria-invalid`
+
+#### Abordagens de Implementacao
+
+| Design System | Abordagem | Notas |
+|---------------|-----------|-------|
+| **ETUS** | Native HTML input | Maximo de acessibilidade nativa |
+| **Shadcn/ui** | Radix RadioGroup | Compound components |
+| **Radix UI** | Custom primitives | Composable, headless |
+| **Chakra UI** | Custom + context | RadioGroup provider |
+| **MUI** | Custom + FormControl | Integrado com formularios |
+| **Mantine** | Custom + hooks | Radio.Group compound |
+| **NextUI** | React Aria based | useRadio hook |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `type="radio"` | Semantica nativa de radio button |
+| `aria-invalid` | Quando em estado de erro |
+| `aria-disabled` | Herdado de `disabled` |
+| `aria-checked` | Gerenciado nativamente pelo browser |
+| `aria-hidden="true"` | No indicador visual (decorativo) |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para/do grupo de radios |
+| `Space` | Seleciona o radio focado |
+| `Arrow Up/Down` | Move entre radios do mesmo grupo* |
+| `Arrow Left/Right` | Move entre radios do mesmo grupo* |
+
+*Comportamento nativo quando radios compartilham o mesmo `name`
+
+### 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 |
+|--------|------------|------------|-------|
+| Unchecked | `--input` (border) | `--background` | >= 3:1 (UI) |
+| Checked | `--primary-foreground` | `--primary` | >= 4.5:1 |
+| Focus | `--ring` | - | >= 3:1 (UI) |
+
+### Screen Readers
+
+- Label automaticamente associado via `htmlFor`/`id`
+- Indicador visual tem `aria-hidden="true"`
+- Estado checked anunciado nativamente
+- Usar `name` para agrupar radios logicamente
+
+### Reduced Motion
+
+```css
+/* Indicador respeita preferencia do usuario */
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="radio-button-indicator"] {
+    transition: none;
+  }
+}
+```
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **Native semantics** | Yes | - | - | - | - | - | - | - | - | - | - | - |
+| **ARIA automatico** | Yes | Yes | Yes | Yes | Yes | ~ | ~ | ~ | ~ | Yes | Yes | Yes |
+| **Focus visible** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Keyboard nav** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **aria-invalid** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | - | Yes | Yes | Yes |
+| **Label association** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| **Reduced motion** | ~ | Yes | - | - | - | Yes | Yes | Yes | - | Yes | Yes | Yes |
+| **RTL support** | - | Yes | - | - | - | Yes | Yes | Yes | Yes | - | Yes | Yes |
+
+**Legenda:** Yes = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { RadioButton } from "@etus/ui"
+
+function Example() {
+  return <RadioButton name="option" value="1" label="Option 1" />
+}
+```
+
+### Grupo de Radio Buttons
+
+```tsx
+function RadioGroup() {
+  return (
+    <fieldset>
+      <legend className="text-sm font-medium mb-2">Select your plan</legend>
+      <div className="space-y-2">
+        <RadioButton name="plan" value="free" label="Free" />
+        <RadioButton name="plan" value="pro" label="Pro" defaultChecked />
+        <RadioButton name="plan" value="enterprise" label="Enterprise" />
+      </div>
+    </fieldset>
+  )
+}
+```
+
+### Tamanhos
+
+```tsx
+<RadioButton size="sm" name="size" value="sm" label="Small" />
+<RadioButton size="md" name="size" value="md" label="Medium (default)" />
+<RadioButton size="lg" name="size" value="lg" label="Large" />
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react"
+
+function ControlledExample() {
+  const [selected, setSelected] = useState("option1")
+
+  return (
+    <div className="space-y-2">
+      <RadioButton
+        name="controlled"
+        value="option1"
+        label="Option 1"
+        checked={selected === "option1"}
+        onChange={(e) => setSelected(e.target.value)}
+      />
+      <RadioButton
+        name="controlled"
+        value="option2"
+        label="Option 2"
+        checked={selected === "option2"}
+        onChange={(e) => setSelected(e.target.value)}
+      />
+      <p className="text-sm text-muted-foreground">Selected: {selected}</p>
+    </div>
+  )
+}
+```
+
+### Estados
+
+```tsx
+// Disabled
+<RadioButton name="state" value="disabled" label="Disabled option" disabled />
+
+// Checked disabled
+<RadioButton
+  name="state"
+  value="checked-disabled"
+  label="Checked and disabled"
+  defaultChecked
+  disabled
+/>
+
+// Required
+<RadioButton name="required" value="yes" label="Required option" required />
+
+// Invalid state
+<RadioButton
+  name="invalid"
+  value="error"
+  label="Invalid option"
+  aria-invalid="true"
+/>
+```
+
+### Sem Label (apenas visual)
+
+```tsx
+// Use aria-label quando nao houver label visivel
+<RadioButton
+  name="visual-only"
+  value="1"
+  aria-label="First option"
+/>
+```
+
+### Com Descricao Customizada
+
+```tsx
+function RadioWithDescription() {
+  return (
+    <div className="flex items-start gap-2">
+      <RadioButton name="plan" value="pro" id="plan-pro" />
+      <div className="grid gap-1.5 leading-none">
+        <label htmlFor="plan-pro" className="text-sm font-medium cursor-pointer">
+          Pro Plan
+        </label>
+        <p className="text-sm text-muted-foreground">
+          $15/month - Includes all features
+        </p>
+      </div>
+    </div>
+  )
+}
+```
+
+### Inline Layout
+
+```tsx
+<div className="flex items-center gap-4">
+  <RadioButton name="inline" value="yes" label="Yes" />
+  <RadioButton name="inline" value="no" label="No" />
+  <RadioButton name="inline" value="maybe" label="Maybe" />
+</div>
+```
+
+### Com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+
+interface FormData {
+  subscription: string
+}
+
+function FormExample() {
+  const { register, handleSubmit, formState: { errors } } = useForm<FormData>()
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <fieldset>
+        <legend className="text-sm font-medium mb-2">Subscription</legend>
+        <div className="space-y-2">
+          <RadioButton
+            {...register("subscription", { required: "Please select an option" })}
+            value="monthly"
+            label="Monthly"
+            aria-invalid={!!errors.subscription}
+          />
+          <RadioButton
+            {...register("subscription")}
+            value="yearly"
+            label="Yearly (save 20%)"
+          />
+        </div>
+        {errors.subscription && (
+          <p className="text-sm text-destructive mt-1">
+            {errors.subscription.message}
+          </p>
+        )}
+      </fieldset>
+      <button type="submit" className="mt-4">Submit</button>
+    </form>
+  )
+}
+```
+
+### Card Radio (composicao avancada)
+
+```tsx
+function CardRadio() {
+  const [selected, setSelected] = useState("starter")
+
+  const plans = [
+    { value: "starter", title: "Starter", price: "Free", features: ["1 user", "5GB storage"] },
+    { value: "pro", title: "Pro", price: "$15/mo", features: ["5 users", "50GB storage"] },
+    { value: "team", title: "Team", price: "$30/mo", features: ["Unlimited users", "500GB storage"] },
+  ]
+
+  return (
+    <div className="grid gap-4 sm:grid-cols-3">
+      {plans.map((plan) => (
+        <label
+          key={plan.value}
+          className={cn(
+            "relative flex cursor-pointer rounded-lg border p-4 focus-within:ring-2 focus-within:ring-ring",
+            selected === plan.value ? "border-primary bg-primary/5" : "border-input"
+          )}
+        >
+          <RadioButton
+            name="plan"
+            value={plan.value}
+            checked={selected === plan.value}
+            onChange={(e) => setSelected(e.target.value)}
+            className="sr-only"
+          />
+          <div className="flex flex-col">
+            <span className="font-medium">{plan.title}</span>
+            <span className="text-lg font-bold">{plan.price}</span>
+            <ul className="mt-2 text-sm text-muted-foreground">
+              {plan.features.map((f) => <li key={f}>{f}</li>)}
+            </ul>
+          </div>
+          {selected === plan.value && (
+            <CheckCircle className="absolute top-4 right-4 h-5 w-5 text-primary" />
+          )}
+        </label>
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// RadioButton.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { RadioButton } from "./RadioButton"
+
+describe("RadioButton", () => {
+  it("renders with label correctly", () => {
+    render(<RadioButton name="test" value="1" label="Test Label" />)
+    expect(screen.getByRole("radio")).toBeInTheDocument()
+    expect(screen.getByText("Test Label")).toBeInTheDocument()
+  })
+
+  it("renders without label", () => {
+    render(<RadioButton name="test" value="1" aria-label="Test" />)
+    expect(screen.getByRole("radio")).toBeInTheDocument()
+  })
+
+  it("applies size classes", () => {
+    render(<RadioButton name="test" value="1" size="lg" />)
+    expect(screen.getByRole("radio")).toHaveClass("size-5")
+  })
+
+  it("generates unique id when not provided", () => {
+    render(<RadioButton name="test" value="1" label="Label" />)
+    const radio = screen.getByRole("radio")
+    expect(radio).toHaveAttribute("id")
+    expect(screen.getByText("Label")).toHaveAttribute("for", radio.id)
+  })
+
+  it("uses provided id", () => {
+    render(<RadioButton name="test" value="1" id="custom-id" label="Label" />)
+    expect(screen.getByRole("radio")).toHaveAttribute("id", "custom-id")
+  })
+
+  it("has data-slot attribute", () => {
+    const { container } = render(<RadioButton name="test" value="1" />)
+    expect(container.querySelector("[data-slot='radio-button']")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+import userEvent from "@testing-library/user-event"
+import { vi } from "vitest"
+
+describe("RadioButton interactions", () => {
+  it("calls onChange when clicked", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<RadioButton name="test" value="1" label="Test" onChange={handleChange} />)
+    await user.click(screen.getByRole("radio"))
+
+    expect(handleChange).toHaveBeenCalledTimes(1)
+  })
+
+  it("does not call onChange when disabled", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<RadioButton name="test" value="1" label="Test" onChange={handleChange} disabled />)
+    await user.click(screen.getByRole("radio"))
+
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("can be selected via label click", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<RadioButton name="test" value="1" label="Click me" onChange={handleChange} />)
+    await user.click(screen.getByText("Click me"))
+
+    expect(handleChange).toHaveBeenCalled()
+  })
+
+  it("can be activated with Space key", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<RadioButton name="test" value="1" label="Test" onChange={handleChange} />)
+    screen.getByRole("radio").focus()
+    await user.keyboard(" ")
+
+    expect(handleChange).toHaveBeenCalled()
+  })
+
+  it("navigates between group members with arrow keys", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <div>
+        <RadioButton name="group" value="1" label="First" />
+        <RadioButton name="group" value="2" label="Second" />
+      </div>
+    )
+
+    const [first, second] = screen.getAllByRole("radio")
+    first.focus()
+
+    await user.keyboard("{ArrowDown}")
+    expect(second).toHaveFocus()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("RadioButton accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <RadioButton name="test" value="1" label="Accessible Radio" />
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations in a group", async () => {
+    const { container } = render(
+      <fieldset>
+        <legend>Select option</legend>
+        <RadioButton name="group" value="1" label="Option 1" />
+        <RadioButton name="group" value="2" label="Option 2" />
+      </fieldset>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("associates label with input", () => {
+    render(<RadioButton name="test" value="1" label="My Label" />)
+    const radio = screen.getByLabelText("My Label")
+    expect(radio).toBeInTheDocument()
+  })
+
+  it("is focusable", () => {
+    render(<RadioButton name="test" value="1" label="Test" />)
+    const radio = screen.getByRole("radio")
+    radio.focus()
+    expect(radio).toHaveFocus()
+  })
+
+  it("is not focusable when disabled", () => {
+    render(<RadioButton name="test" value="1" label="Test" disabled />)
+    expect(screen.getByRole("radio")).toBeDisabled()
+  })
+
+  it("supports aria-invalid", () => {
+    render(<RadioButton name="test" value="1" aria-invalid="true" />)
+    expect(screen.getByRole("radio")).toHaveAttribute("aria-invalid", "true")
+  })
+})
+```
+
+### Testes de Grupo
+
+```tsx
+describe("RadioButton group behavior", () => {
+  it("only allows one selection in a group", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <div>
+        <RadioButton name="exclusive" value="1" label="Option 1" />
+        <RadioButton name="exclusive" value="2" label="Option 2" />
+      </div>
+    )
+
+    const [radio1, radio2] = screen.getAllByRole("radio")
+
+    await user.click(radio1)
+    expect(radio1).toBeChecked()
+    expect(radio2).not.toBeChecked()
+
+    await user.click(radio2)
+    expect(radio1).not.toBeChecked()
+    expect(radio2).toBeChecked()
+  })
+
+  it("allows multiple selections with different names", async () => {
+    const user = userEvent.setup()
+
+    render(
+      <div>
+        <RadioButton name="group1" value="1" label="Group 1 Option" />
+        <RadioButton name="group2" value="1" label="Group 2 Option" />
+      </div>
+    )
+
+    const [radio1, radio2] = screen.getAllByRole("radio")
+
+    await user.click(radio1)
+    await user.click(radio2)
+
+    expect(radio1).toBeChecked()
+    expect(radio2).toBeChecked()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### `RadioGroup` Component
+
+Componente compound para gerenciar grupos de radios.
+
+```tsx
+// Proposta de API
+<RadioGroup value={selected} onValueChange={setSelected} name="plan">
+  <RadioGroup.Item value="free" label="Free" />
+  <RadioGroup.Item value="pro" label="Pro" />
+  <RadioGroup.Item value="enterprise" label="Enterprise" />
+</RadioGroup>
+```
+
+**Referencias:** Shadcn/ui, Radix UI, Chakra UI, MUI, Mantine
+
+#### `description` Prop
+
+Texto descritivo abaixo do label.
+
+```tsx
+// Proposta de API
+<RadioButton
+  name="plan"
+  value="pro"
+  label="Pro Plan"
+  description="$15/month - Includes all features"
+/>
+```
+
+**Referencias:** Chakra UI, Mantine, NextUI, Ariakit
+
+### Prioridade Media
+
+#### `orientation` Prop (para RadioGroup)
+
+Direcao do layout do grupo.
+
+```tsx
+// Proposta de API
+<RadioGroup orientation="horizontal">
+  <RadioGroup.Item value="1" label="Option 1" />
+  <RadioGroup.Item value="2" label="Option 2" />
+</RadioGroup>
+```
+
+**Referencias:** Radix UI, React Aria, Chakra UI
+
+#### `error` / `isInvalid` Prop
+
+Estado de erro com mensagem.
+
+```tsx
+// Proposta de API
+<RadioButton
+  name="required"
+  value="yes"
+  label="Accept terms"
+  isInvalid
+  errorMessage="This field is required"
+/>
+```
+
+**Referencias:** Chakra UI, NextUI, MUI
+
+### Prioridade Baixa
+
+#### `colorScheme` Prop
+
+Variacao de cor para o estado checked.
+
+```tsx
+// Proposta de API
+<RadioButton colorScheme="success" name="status" value="active" label="Active" />
+```
+
+**Referencias:** Chakra UI, NextUI
+
+#### Custom Indicator
+
+Permitir indicador customizado.
+
+```tsx
+// Proposta de API
+<RadioButton
+  name="custom"
+  value="1"
+  indicator={<CheckIcon />}
+/>
+```
+
+**Referencias:** Mantine, NextUI
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `RadioGroup` | Implementar | Padrao em todos os DS, melhora DX |
+| `description` | Implementar | Comum, melhora UX |
+| `orientation` | Implementar com RadioGroup | Util para layouts horizontais |
+| `error`/`isInvalid` | Avaliar | `aria-invalid` ja funciona |
+| `colorScheme` | Evitar | Complexidade, usar CSS vars |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao Radio | GitHub |
+|---------------|-------------------|--------|
+| **Shadcn/ui** | [Radio Group](https://ui.shadcn.com/docs/components/radio-group) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Radio Group](https://www.radix-ui.com/primitives/docs/components/radio-group) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [RadioGroup](https://react-spectrum.adobe.com/react-aria/RadioGroup.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Radio](https://chakra-ui.com/docs/components/radio) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Radio](https://mui.com/material-ui/react-radio-button/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Radio](https://mantine.dev/core/radio/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Radio](https://ant.design/components/radio) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Radio](https://nextui.org/docs/components/radio) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | [RadioGroup](https://headlessui.com/react/radio-group) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Radio](https://ariakit.org/components/radio) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Radio](https://react.fluentui.dev/?path=/docs/components-radio--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [RadioButton](https://carbondesignsystem.com/components/radio-button/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [Radio](https://blueprintjs.com/docs/#core/components/radio) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [RadioButton](https://primereact.org/radiobutton/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - Input type="radio"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio)
+- [HTML Spec - Radio Button State](https://html.spec.whatwg.org/multipage/input.html#radio-button-state-(type=radio))
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)