@etus/ui 0.1.0

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

@@ -0,0 +1,1112 @@
+# Button
+
+## Visão Geral
+
+O **Button** é o componente fundamental de interação do Design System ETUS, usado para disparar ações e submeter formulários. Como elemento atômico, serve de base para composições mais complexas como `IconButton`, `ButtonGroup` e `ToggleButton`.
+
+### Casos de Uso
+
+- Submissão de formulários
+- Ações primárias e secundárias em interfaces
+- Navegação quando usado com `asChild` + Link
+- Ações destrutivas (deletar, remover)
+- Links estilizados como botões
+
+### Classificação
+
+**Categoria:** Atom
+**Dependências:** `@radix-ui/react-slot`, `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante          | Uso                       | Tokens                                          |
+| ----------------- | ------------------------- | ----------------------------------------------- |
+| `default`         | Ação primária (legacy)    | `bg-primary`, `text-primary-foreground`         |
+| `primary`         | Ação primária (Figma)     | `bg-button-primary-*`                           |
+| `secondary`       | Ação secundária (legacy)  | `bg-secondary`, `text-secondary-foreground`     |
+| `secondary-gray`  | Secundário neutro         | `bg-button-secondary-gray-*`                    |
+| `secondary-color` | Secundário colorido       | `bg-button-secondary-color-*`                   |
+| `tertiary-gray`   | Terciário neutro          | `text-button-tertiary-gray-*`                   |
+| `tertiary-color`  | Terciário colorido        | `text-button-tertiary-color-*`                  |
+| `destructive`     | Ações perigosas           | `bg-destructive`, `text-destructive-foreground` |
+| `outline`         | Baixa ênfase              | `border`, `bg-background`                       |
+| `dashed`          | Adicionar item / Builder  | `border-dashed`                                 |
+| `ghost`           | Mínima ênfase             | Transparente, hover `bg-accent`                 |
+| `link`            | Navegação inline (legacy) | `text-shadow-button`, underline                 |
+| `link-gray`       | Link neutro               | `text-button-link-gray-*`                       |
+| `link-color`      | Link colorido             | `text-button-link-color-*`                      |
+| `unstyled`        | Comportamento sem estilo  | `bg-transparent`, `p-0`                         |
+| `success`         | Estado positivo           | `bg-green-*`, `text-white`                      |
+| `warning`         | Estado de atenção         | `bg-yellow-*`, `text-white`                     |
+
+> Atalho: use `tone="gray" | "color"` com `variant="secondary" | "tertiary" | "link"` para mapear automaticamente para `*-gray` ou `*-color`.
+
+### Tamanhos (`size`)
+
+| Tamanho    | Altura               | Padding | Uso                        |
+| ---------- | -------------------- | ------- | -------------------------- |
+| `sm`       | `h-8` (32px)         | `px-3`  | Espaços compactos, tabelas |
+| `default`  | `h-9` (36px)         | `px-4`  | Uso geral                  |
+| `lg`       | `h-10` (40px)        | `px-6`  | CTAs, ações principais     |
+| `xl`       | `h-12` (48px)        | `px-8`  | Destaque com mais presença |
+| `2xl`      | `h-[60px]` (60px)    | `px-10` | CTA extra grande           |
+| `icon`     | `size-9` (36px)      | -       | Apenas ícone               |
+| `icon-sm`  | `size-8` (32px)      | -       | Ícone compacto             |
+| `icon-lg`  | `size-10` (40px)     | -       | Ícone grande               |
+| `icon-xl`  | `size-12` (48px)     | -       | Ícone extra grande         |
+| `icon-2xl` | `size-[60px]` (60px) | -       | Ícone mega                 |
+
+### Estados
+
+| Estado   | Classes/Atributos                  | Comportamento                                                                                               |
+| -------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Default  | -                                  | Aparência base                                                                                              |
+| Hover    | `hover:bg-*/90`                    | Leve escurecimento                                                                                          |
+| Focus    | `focus-visible:ring-4`             | Ring de 4px com `ring-button-ring-brand` (z-index: 10)                                                      |
+| Loading  | `data-loading`, `aria-busy="true"` | Spinner centralizado, preserva largura original (sem layout shift), `aria-label` automático se texto oculto |
+| Disabled | `disabled:opacity-50`              | 50% opacidade, sem pointer events (previne clique em links)                                                 |
+| Invalid  | `aria-invalid:ring-destructive/20` | Ring vermelho                                                                                               |
+
+### Tokens Utilizados
+
+O Button utiliza tokens de componente específicos definidos em `@etus/tokens`. Os tokens seguem a convenção:
+
+```
+--button-{variant}-{property}-{state}
+--button-size-{size}-{property}
+```
+
+#### Tokens de Variante (Cores)
+
+```css
+/* Primary */
+--button-primary-bg-DEFAULT      /* Fundo padrão */
+--button-primary-bg-hover        /* Fundo no hover */
+--button-primary-fg-DEFAULT      /* Texto padrão */
+--button-primary-border-DEFAULT  /* Borda padrão */
+--button-primary-border-hover    /* Borda no hover */
+
+/* Secondary Gray */
+--button-secondary-gray-bg-DEFAULT
+--button-secondary-gray-bg-hover
+--button-secondary-gray-fg-DEFAULT
+--button-secondary-gray-fg-hover
+--button-secondary-gray-border-DEFAULT
+--button-secondary-gray-border-hover
+
+/* Secondary Color */
+--button-secondary-color-bg-DEFAULT
+--button-secondary-color-bg-hover
+--button-secondary-color-fg-DEFAULT
+--button-secondary-color-fg-hover
+--button-secondary-color-border-DEFAULT
+--button-secondary-color-border-hover
+
+/* Tertiary Gray/Color */
+--button-tertiary-gray-fg-DEFAULT
+--button-tertiary-gray-fg-hover
+--button-tertiary-gray-bg-hover
+--button-tertiary-color-fg-DEFAULT
+--button-tertiary-color-fg-hover
+--button-tertiary-color-bg-hover
+
+/* Link Gray/Color */
+--button-link-gray-fg-DEFAULT
+--button-link-gray-fg-hover
+--button-link-color-fg-DEFAULT
+--button-link-color-fg-hover
+
+/* Disabled */
+--button-disabled-bg
+--button-disabled-fg
+--button-disabled-border
+
+/* Focus Ring */
+--button-ring-brand
+--button-ring-gray
+```
+
+#### Tokens de Tamanho (Dimensões)
+
+```css
+/* Default (36px) */
+--button-size-default-h          /* Altura */
+--button-size-default-px         /* Padding horizontal */
+--button-size-default-py         /* Padding vertical */
+--button-size-default-text       /* Font size */
+--button-size-default-leading    /* Line height */
+--button-size-default-gap        /* Gap entre elementos */
+
+/* Small, Large, XL, 2XL seguem o mesmo padrão */
+--button-size-sm-*
+--button-size-lg-*
+--button-size-xl-*
+--button-size-2xl-*
+
+/* Icon sizes */
+--button-size-icon-size          /* 36px */
+--button-size-icon-sm-size       /* 32px */
+--button-size-icon-lg-size       /* 40px */
+--button-size-icon-xl-size       /* 48px */
+--button-size-icon-2xl-size      /* 60px */
+```
+
+#### Outros Tokens
+
+```css
+/* Radius */
+--button-radius-default
+
+/* Sombras */
+--button-box-shadow-default
+--button-box-shadow-xs
+
+/* Transições (globais) */
+--duration-fast
+--easing-default
+```
+
+---
+
+## Padrão de Tokens com Tailwind v4
+
+Esta seção documenta como usar tokens CSS com Tailwind CSS v4 e CVA (Class Variance Authority). Este padrão é fundamental para manter consistência no design system.
+
+### Sintaxe de Valores Arbitrários
+
+Tailwind v4 usa **arbitrary values** com **type hints** para interpretar corretamente os tokens CSS:
+
+| Tipo de Token | Sintaxe Tailwind             | Exemplo                                         |
+| ------------- | ---------------------------- | ----------------------------------------------- |
+| **Cores**     | `bg-[color:var(--token)]`    | `bg-[color:var(--button-primary-bg-DEFAULT)]`   |
+| **Dimensões** | `h-[var(--token)]`           | `h-[var(--button-size-default-h)]`              |
+| **Font Size** | `text-[length:var(--token)]` | `text-[length:var(--button-size-default-text)]` |
+| **Sombras**   | `shadow-[var(--token)]`      | `shadow-[var(--button-box-shadow-default)]`     |
+| **Duração**   | `duration-[var(--token)]`    | `duration-[var(--duration-fast)]`               |
+| **Easing**    | `ease-[var(--token)]`        | `ease-[var(--easing-default)]`                  |
+
+### Por que usar Type Hints?
+
+Os tokens do ETUS usam **OKLCH** como espaço de cor. O Tailwind precisa do type hint `color:` para interpretar corretamente:
+
+```tsx
+// ✅ CORRETO - Tailwind interpreta como cor
+bg-[color:var(--button-primary-bg-DEFAULT)]
+
+// ❌ INCORRETO - Tailwind não sabe o tipo
+bg-[var(--button-primary-bg-DEFAULT)]
+
+// ❌ INCORRETO - Tokens OKLCH não são HSL
+bg-[hsl(var(--button-primary-bg-DEFAULT))]
+```
+
+### Exemplo Completo de CVA
+
+```tsx
+const buttonVariants = cva(
+  // Base styles com tokens globais
+  "inline-flex items-center justify-center rounded-[var(--button-radius-default)] font-medium transition-all duration-[var(--duration-fast)] ease-[var(--easing-default)]",
+  {
+    variants: {
+      variant: {
+        // Cores: sempre usar color: para bg, text, border
+        primary:
+          "bg-[color:var(--button-primary-bg-DEFAULT)] text-[color:var(--button-primary-fg-DEFAULT)] border-[color:var(--button-primary-border-DEFAULT)] hover:bg-[color:var(--button-primary-bg-hover)]",
+      },
+      size: {
+        // Dimensões: h e px não precisam de type hint
+        // Font size: PRECISA de length: para evitar conflito com text-color
+        default:
+          "h-[var(--button-size-default-h)] px-[var(--button-size-default-px)] text-[length:var(--button-size-default-text)]",
+      },
+    },
+  },
+);
+```
+
+### Regras Importantes
+
+1. **Cores (`bg-`, `text-color`, `border-`)**: Sempre usar `color:var(--token)`
+2. **Font Size (`text-size`)**: Sempre usar `length:var(--token)` para distinguir de cores
+3. **Dimensões (`h-`, `w-`, `px-`, `py-`)**: Não precisa de type hint
+4. **Sombras (`shadow-`)**: Não precisa de type hint
+5. **NUNCA usar `hsl()`**: Os tokens OKLCH são valores completos
+
+### Estados com Tokens
+
+```tsx
+// Hover
+hover:bg-[color:var(--button-primary-bg-hover)]
+hover:border-[color:var(--button-primary-border-hover)]
+
+// Disabled
+disabled:bg-[color:var(--button-disabled-bg)]
+disabled:text-[color:var(--button-disabled-fg)]
+
+// Focus
+focus-visible:ring-[color:var(--button-ring-brand)]
+```
+
+### Configuração do Tailwind v4
+
+Para que os tokens funcionem, o arquivo CSS do app deve incluir a diretiva `@source`:
+
+```css
+/* index.css */
+@import "tailwindcss";
+@import "@etus/tokens/styles/tokens.css";
+
+/* IMPORTANTE: Incluir .ts para escanear definições de CVA */
+@source "../../../packages/ui/src/**/*.{ts,tsx}";
+```
+
+### data-slot
+
+```html
+<button data-slot="button">...</button>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop          | Tipo                                                                                                                                                                                                                                                                        | Padrão      | Descrição                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------- |
+| `variant`     | `"default" \| "primary" \| "secondary" \| "secondary-gray" \| "secondary-color" \| "tertiary" \| "tertiary-gray" \| "tertiary-color" \| "destructive" \| "outline" \| "dashed" \| "ghost" \| "link" \| "link-gray" \| "link-color" \| "unstyled" \| "success" \| "warning"` | `"default"` | Estilo visual do botão                              |
+| `tone`        | `"gray" \| "color"`                                                                                                                                                                                                                                                         | -           | Atalho para variantes `secondary`/`tertiary`/`link` |
+| `size`        | `"default" \| "sm" \| "lg" \| "xl" \| "2xl" \| "icon" \| "icon-sm" \| "icon-lg" \| "icon-xl" \| "icon-2xl"`                                                                                                                                                                 | `"default"` | Tamanho do botão                                    |
+| `asChild`     | `boolean`                                                                                                                                                                                                                                                                   | `false`     | Renderiza children como elemento (polimorfismo)     |
+| `loading`     | `boolean`                                                                                                                                                                                                                                                                   | `false`     | Mostra spinner e desabilita interações              |
+| `loadingText` | `string`                                                                                                                                                                                                                                                                    | -           | Texto alternativo durante loading                   |
+| `leftIcon`    | `ReactNode`                                                                                                                                                                                                                                                                 | -           | Ícone à esquerda do texto                           |
+| `rightIcon`   | `ReactNode`                                                                                                                                                                                                                                                                 | -           | Ícone à direita do texto                            |
+| `className`   | `string`                                                                                                                                                                                                                                                                    | -           | Classes CSS adicionais                              |
+| `disabled`    | `boolean`                                                                                                                                                                                                                                                                   | `false`     | Desabilita o botão                                  |
+| `type`        | `"button" \| "submit" \| "reset"`                                                                                                                                                                                                                                           | `"submit"`  | Tipo do botão HTML                                  |
+| `children`    | `ReactNode`                                                                                                                                                                                                                                                                 | -           | Conteúdo do botão                                   |
+| `ref`         | `Ref<HTMLButtonElement>`                                                                                                                                                                                                                                                    | -           | Referência ao elemento DOM                          |
+
+> Herda todas as props de `React.ComponentProps<"button">`
+
+### Callbacks
+
+Todos os callbacks recebem o evento nativo e um `ButtonEventPayload` com metadados úteis:
+
+| Callback    | Tipo                                                          | Descrição                     |
+| ----------- | ------------------------------------------------------------- | ----------------------------- |
+| `onClick`   | `(event: MouseEvent, payload: ButtonEventPayload) => void`    | Disparado ao clicar           |
+| `onFocus`   | `(event: FocusEvent, payload: ButtonEventPayload) => void`    | Disparado ao receber foco     |
+| `onBlur`    | `(event: FocusEvent, payload: ButtonEventPayload) => void`    | Disparado ao perder foco      |
+| `onKeyDown` | `(event: KeyboardEvent, payload: ButtonEventPayload) => void` | Disparado ao pressionar tecla |
+
+#### ButtonEventPayload
+
+```typescript
+interface ButtonEventPayload {
+  id?: string; // Valor de data-id
+  timestamp: number; // Date.now() do momento do evento
+  isLoading?: boolean; // Estado de loading no momento do evento
+}
+```
+
+### TypeScript
+
+```typescript
+import type {
+  ButtonProps,
+  ButtonVariant,
+  ButtonSize,
+  ButtonEventPayload,
+} from "@etus/ui";
+
+// ButtonProps inclui:
+interface ButtonProps {
+  variant?: ButtonVariant;
+  tone?: "gray" | "color";
+  size?: ButtonSize;
+  asChild?: boolean;
+  loading?: boolean;
+  loadingText?: string;
+  leftIcon?: ReactNode;
+  rightIcon?: ReactNode;
+  "data-id"?: string;
+  // ... + todas as props de <button>
+}
+
+// Tipos derivados
+type ButtonVariant =
+  | "default"
+  | "primary"
+  | "secondary"
+  | "secondary-gray"
+  | "secondary-color"
+  | "tertiary"
+  | "tertiary-gray"
+  | "tertiary-color"
+  | "destructive"
+  | "outline"
+  | "ghost"
+  | "link"
+  | "link-gray"
+  | "link-color"
+  | "success"
+  | "warning";
+type ButtonSize =
+  | "default"
+  | "sm"
+  | "lg"
+  | "xl"
+  | "2xl"
+  | "icon"
+  | "icon-sm"
+  | "icon-lg"
+  | "icon-xl"
+  | "icon-2xl";
+
+// Payload de eventos
+interface ButtonEventPayload {
+  id?: string;
+  timestamp: number;
+  isLoading?: boolean;
+}
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature               | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon |
+| --------------------- | :--: | :----: | :---: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: |
+| **Variantes**         |  16  |   6    |   -   |   6    |  3  |    7    |  5   |   4    |    -     |    -    |   6    |   4    |
+| **Tamanhos**          |  10  |   4    |   -   |   4    |  3  |    5    |  4   |   4    |    -     |    -    |   4    |   4    |
+| **CVA/cva**           |  ✓   |   ✓    |   -   |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |
+| **asChild/Slot**      |  ✓   |   ✓    |   ✓   |   -    |  -  |    -    |  -   |   ✓    |    ✓     |    ✓    |   -    |   -    |
+| **loading**           |  ✓   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |
+| **leftIcon**          |  ✓   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |
+| **rightIcon**         |  ✓   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   -    |
+| **fullWidth**         |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   -    |   -    |
+| **data-slot**         |  ✓   |   ✓    |   -   |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |
+| **Compound variants** |  ✓   |   ✓    |   -   |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |
+| **ButtonGroup**       |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |
+| **Tooltip built-in**  |  -   |   -    |   -   |   -    |  -  |    -    |  ✓   |   ✓    |    -     |    -    |   -    |   ✓    |
+| **Ripple effect**     |  -   |   -    |   -   |   -    |  ✓  |    -    |  -   |   ✓    |    -     |    -    |   ✓    |   -    |
+
+#### Comparativo de Variantes por Design System
+
+| Design System  | Variantes Disponíveis                                                                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ETUS**       | `default`, `primary`, `secondary`, `secondary-gray/color`, `tertiary-gray/color`, `destructive`, `outline`, `ghost`, `link`, `link-gray/color`, `success`, `warning` |
+| **Shadcn/ui**  | `default`, `secondary`, `destructive`, `outline`, `ghost`, `link`                                                                                                    |
+| **Chakra UI**  | `solid`, `outline`, `ghost`, `link`, `unstyled` + colorScheme                                                                                                        |
+| **MUI**        | `contained`, `outlined`, `text` + color                                                                                                                              |
+| **Mantine**    | `filled`, `outline`, `light`, `subtle`, `default`, `transparent`, `white`                                                                                            |
+| **Ant Design** | `primary`, `default`, `dashed`, `text`, `link`                                                                                                                       |
+| **NextUI**     | `solid`, `bordered`, `light`, `flat`, `faded`, `shadow`, `ghost`                                                                                                     |
+| **Fluent UI**  | `primary`, `secondary`, `outline`, `subtle`, `transparent`                                                                                                           |
+| **Carbon**     | `primary`, `secondary`, `tertiary`, `ghost`, `danger`                                                                                                                |
+
+#### Comparativo de Props por Design System
+
+| Prop               | ETUS |    Chakra    |        MUI        |     Mantine      |   AntD    |       NextUI       |    Fluent    |
+| ------------------ | :--: | :----------: | :---------------: | :--------------: | :-------: | :----------------: | :----------: |
+| `variant`          |  ✓   |      ✓       |         ✓         |        ✓         |  `type`   |         ✓          | `appearance` |
+| `size`             |  ✓   |      ✓       |         ✓         |        ✓         |     ✓     |         ✓          |      ✓       |
+| `disabled`         |  ✓   | `isDisabled` |         ✓         |        ✓         |     ✓     |    `isDisabled`    |      ✓       |
+| `loading`          |  ✓   | `isLoading`  |     `loading`     |    `loading`     | `loading` |    `isLoading`     |      -       |
+| `loadingText`      |  ✓   |      ✓       |         -         |  `loaderProps`   |     -     |         -          |      -       |
+| `spinnerPlacement` |  -   |      ✓       | `loadingPosition` | `loaderPosition` |     -     | `spinnerPlacement` |      -       |
+| `leftIcon`         |  ✓   |      ✓       |    `startIcon`    |  `leftSection`   |  `icon`   |   `startContent`   |    `icon`    |
+| `rightIcon`        |  ✓   |      ✓       |     `endIcon`     |  `rightSection`  |     -     |    `endContent`    |      -       |
+| `fullWidth`        |  -   |      ✓       |    `fullWidth`    |   `fullWidth`    |  `block`  |    `fullWidth`     |      -       |
+| `colorScheme`      |  -   |      ✓       |      `color`      |     `color`      |     -     |      `color`       |      -       |
+| `radius`           |  -   |      -       |         -         |        ✓         |  `shape`  |         ✓          |   `shape`    |
+| `compact`          |  -   |      -       |         -         |        ✓         |     -     |         -          |      -       |
+| `gradient`         |  -   |      -       |         -         |        ✓         |     -     |         -          |      -       |
+| `asChild`/`as`     |  ✓   |     `as`     |    `component`    |   `component`    |     -     |        `as`        |     `as`     |
+| `href`             |  -   |      -       |      `href`       |        -         |  `href`   |       `href`       |    `href`    |
+
+#### Análise por Categoria
+
+**Headless/Primitivos (máxima flexibilidade):**
+
+- **Radix UI** - Apenas Slot, sem estilos
+- **Headless UI** - Renderless, focado em a11y
+- **Ariakit** - Primitivos com hooks, máxima composabilidade
+- **React Aria** - Hooks de comportamento, sem UI
+
+**Styled/Opinionated (produtividade):**
+
+- **Chakra UI** - Style props, colorScheme, muito ergonômico
+- **MUI** - Sistema de theme completo, sx prop
+- **Mantine** - Moderno, muitos utilitários, excelente DX
+- **Ant Design** - Enterprise, muito completo, ConfigProvider
+
+**Hybrid (meio-termo):**
+
+- **Shadcn/ui** - CVA + Tailwind, copiável
+- **NextUI** - Tailwind + Framer Motion
+- **ETUS** - CVA + Tailwind, baseado em Shadcn
+
+**Enterprise/Legacy:**
+
+- **Fluent UI** - Microsoft, tokens complexos
+- **Carbon** - IBM, foco em data visualization
+- **Blueprint** - Palantir, data-dense UIs
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo        | Uso                                        |
+| --------------- | ------------------------------------------ |
+| `aria-disabled` | Quando `disabled={true}`                   |
+| `aria-pressed`  | Para toggle buttons                        |
+| `aria-expanded` | Quando controla elemento expansível        |
+| `aria-haspopup` | Quando abre menu/dialog                    |
+| `aria-label`    | Quando não há texto visível (icon buttons) |
+| `aria-invalid`  | Validação de formulário                    |
+
+### Suporte a Teclado
+
+| Tecla   | Ação                    |
+| ------- | ----------------------- |
+| `Tab`   | Move foco para/do botão |
+| `Enter` | Ativa o botão           |
+| `Space` | Ativa o botão           |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegação 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 (mínimo 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 |
+
+### Screen Readers
+
+- Usar `aria-label` para icon buttons
+- Evitar "Click here" - usar texto descritivo
+- Anunciar estado de loading se implementado
+
+### Reduced Motion
+
+```tsx
+// Respeitar preferência do usuário
+@media (prefers-reduced-motion: reduce) {
+  transition: none;
+}
+```
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature                  | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+| ------------------------ | :--: | :--------: | :---: | :-----: | :------: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: |
+| **ARIA automático**      |  -   |     ✓      |   ✓   |    ✓    |    ✓     |   ~    |  ~  |    ~    |  ~   |   ~    |   ✓    |   ✓    |
+| **Focus visible**        |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |
+| **Focus trap**           |  -   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  -   |   ✓    |   ✓    |   ✓    |
+| **Keyboard nav**         |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |
+| **aria-disabled**        |  ✓   |     ✓      |   ✓   |    ✓    |    ✓     |   ✓    |  ✓  |    ✓    |  -   |   ✓    |   ✓    |   ✓    |
+| **aria-busy**            |  -   |     ✓      |   -   |    ✓    |    -     |   ✓    |  -  |    ✓    |  -   |   ✓    |   ✓    |   ✓    |
+| **aria-pressed**         |  -   |     ✓      |   -   |    ✓    |    ✓     |   -    |  -  |    -    |  -   |   -    |   ✓    |   -    |
+| **Reduced motion**       |  ~   |     ✓      |   -   |    -    |    -     |   ✓    |  ✓  |    ✓    |  -   |   ✓    |   ✓    |   ✓    |
+| **High contrast**        |  -   |     ✓      |   -   |    -    |    -     |   -    |  -  |    -    |  -   |   -    |   ✓    |   ✓    |
+| **RTL support**          |  -   |     ✓      |   -   |    -    |    -     |   ✓    |  ✓  |    ✓    |  ✓   |   -    |   ✓    |   ✓    |
+| **Screen reader tested** |  -   |     ✓      |   ✓   |    ✓    |    ✓     |   ~    |  ✓  |    ~    |  ~   |   ~    |   ✓    |   ✓    |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+#### Abordagens de Acessibilidade
+
+| Design System   | Abordagem             | Nível WCAG | Notas                                           |
+| --------------- | --------------------- | ---------- | ----------------------------------------------- |
+| **React Aria**  | Hooks comportamentais | AAA        | Padrão ouro, testado com leitores de tela reais |
+| **Radix UI**    | Primitivos acessíveis | AA         | WAI-ARIA compliant, composable                  |
+| **Ariakit**     | Hooks + componentes   | AA         | Muito flexível, ótima documentação a11y         |
+| **Headless UI** | Renderless a11y       | AA         | Foco em estados e ARIA                          |
+| **Fluent UI**   | Built-in              | AAA        | Microsoft a11y guidelines, high contrast        |
+| **Carbon**      | Built-in              | AA         | IBM Equal Access Toolkit                        |
+| **MUI**         | Built-in              | AA         | Boa base, customização via props                |
+| **Chakra UI**   | Semi-automático       | AA         | `isDisabled` etc. mapeiam para ARIA             |
+| **Mantine**     | Semi-automático       | AA         | Bom suporte básico                              |
+| **Ant Design**  | Manual                | A-AA       | Requer configuração adicional                   |
+| **NextUI**      | Baseado em React Aria | AA         | Herda de React Aria                             |
+| **ETUS**        | Manual                | AA         | Baseado em Shadcn patterns                      |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Button } from "@etus/ui";
+
+function Example() {
+  return <Button>Click me</Button>;
+}
+```
+
+### Variantes
+
+```tsx
+<Button variant="default">Primary</Button>
+<Button variant="primary">Primary (Figma)</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="secondary" tone="gray">Secondary Gray</Button>
+<Button variant="secondary" tone="color">Secondary Color</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="link">Link</Button>
+<Button variant="link" tone="gray">Link Gray</Button>
+<Button variant="link" tone="color">Link Color</Button>
+<Button variant="dashed">Add New Item</Button>
+<Button variant="unstyled">Clickable Unstyled Area</Button>
+```
+
+### Tamanhos
+
+```tsx
+<Button size="sm">Small</Button>
+<Button size="default">Default</Button>
+<Button size="lg">Large</Button>
+<Button size="xl">Extra Large</Button>
+<Button size="2xl">2XL</Button>
+```
+
+### Com Ícones
+
+```tsx
+import { Mail, ChevronRight } from "lucide-react"
+
+// Ícone à esquerda (prop dedicada)
+<Button leftIcon={<Mail />}>Send Email</Button>
+
+// Ícone à direita (prop dedicada)
+<Button rightIcon={<ChevronRight />}>Next</Button>
+
+// Ambos os ícones
+<Button leftIcon={<Mail />} rightIcon={<ChevronRight />}>
+  Action
+</Button>
+
+// Apenas ícone
+<Button size="icon" aria-label="Send email">
+  <Mail />
+</Button>
+
+// Apenas ícone (extra grande)
+<Button size="icon-xl" aria-label="Send email">
+  <Mail />
+</Button>
+
+// Apenas ícone (2XL)
+<Button size="icon-2xl" aria-label="Send email">
+  <Mail />
+</Button>
+
+// Composição manual ainda funciona
+<Button>
+  <Mail />
+  Send Email
+</Button>
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { Link } from "@tanstack/react-router"
+
+// Renderiza como Link mantendo estilos do Button
+<Button asChild>
+  <Link to="/dashboard">Go to Dashboard</Link>
+</Button>
+
+// Com elemento anchor
+<Button asChild variant="link">
+  <a href="https://example.com" target="_blank" rel="noopener">
+    External Link
+  </a>
+</Button>
+```
+
+### Estados
+
+```tsx
+// Disabled
+<Button disabled>Disabled</Button>
+
+// Form submit
+<Button type="submit">Submit Form</Button>
+
+// Loading state (built-in)
+<Button loading>Saving...</Button>
+
+// Loading com texto alternativo
+<Button loading loadingText="Processing...">Submit</Button>
+```
+
+### Callbacks com Payload
+
+```tsx
+import type { ButtonEventPayload } from "@etus/ui";
+
+function Example() {
+  const handleClick = (
+    e: React.MouseEvent<HTMLButtonElement>,
+    payload: ButtonEventPayload,
+  ) => {
+    console.log("Clicked!", {
+      buttonId: payload.id,
+      at: new Date(payload.timestamp),
+      wasLoading: payload.isLoading,
+    });
+  };
+
+  return (
+    <Button
+      data-id="submit-btn"
+      onClick={handleClick}
+      onFocus={(e, payload) => console.log("Focused", payload.id)}
+    >
+      Interactive Button
+    </Button>
+  );
+}
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo via className
+<Button className="h-8 px-3 md:h-9 md:px-4 lg:h-10 lg:px-6">
+  Responsive
+</Button>
+
+// Full width em mobile
+<Button className="w-full sm:w-auto">
+  Submit
+</Button>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <Button className="@sm:size-lg @md:w-auto w-full">Container Aware</Button>
+</div>
+```
+
+### Composição com Formulário
+
+```tsx
+import { useForm } from "react-hook-form";
+
+function ContactForm() {
+  const { handleSubmit, formState } = useForm();
+  const { isSubmitting } = formState;
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {/* campos... */}
+      <Button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? (
+          <>
+            <Loader2 className="animate-spin" />
+            Sending...
+          </>
+        ) : (
+          "Send Message"
+        )}
+      </Button>
+    </form>
+  );
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Button.test.tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Button } from "./Button";
+
+describe("Button", () => {
+  it("renders children correctly", () => {
+    render(<Button>Click me</Button>);
+    expect(
+      screen.getByRole("button", { name: "Click me" }),
+    ).toBeInTheDocument();
+  });
+
+  it("applies variant classes", () => {
+    render(<Button variant="destructive">Delete</Button>);
+    expect(screen.getByRole("button")).toHaveClass("bg-destructive");
+  });
+
+  it("applies size classes", () => {
+    render(<Button size="lg">Large</Button>);
+    expect(screen.getByRole("button")).toHaveClass("h-10");
+  });
+
+  it("merges custom className", () => {
+    render(<Button className="custom-class">Test</Button>);
+    expect(screen.getByRole("button")).toHaveClass("custom-class");
+  });
+
+  it("has data-slot attribute", () => {
+    render(<Button>Test</Button>);
+    expect(screen.getByRole("button")).toHaveAttribute("data-slot", "button");
+  });
+});
+```
+
+### Testes de Interação
+
+```tsx
+describe("Button interactions", () => {
+  it("calls onClick with event and payload", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(
+      <Button onClick={handleClick} data-id="test-btn">
+        Click
+      </Button>,
+    );
+    await user.click(screen.getByRole("button"));
+
+    expect(handleClick).toHaveBeenCalledWith(
+      expect.any(Object), // MouseEvent
+      expect.objectContaining({
+        id: "test-btn",
+        timestamp: expect.any(Number),
+        isLoading: false,
+      }),
+    );
+  });
+
+  it("does not call onClick when disabled", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(
+      <Button onClick={handleClick} disabled>
+        Click
+      </Button>,
+    );
+    await user.click(screen.getByRole("button"));
+
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it("can be activated with keyboard", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(<Button onClick={handleClick}>Click</Button>);
+    screen.getByRole("button").focus();
+    await user.keyboard("{Enter}");
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Button accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Button>Accessible</Button>);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("icon button requires aria-label", async () => {
+    const { container } = render(
+      <Button size="icon" aria-label="Close dialog">
+        <X />
+      </Button>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("is focusable", () => {
+    render(<Button>Focus me</Button>);
+    const button = screen.getByRole("button");
+    button.focus();
+    expect(button).toHaveFocus();
+  });
+
+  it("is not focusable when disabled", () => {
+    render(<Button disabled>Disabled</Button>);
+    expect(screen.getByRole("button")).toBeDisabled();
+  });
+});
+```
+
+### Testes de Composição (asChild)
+
+```tsx
+describe("Button asChild", () => {
+  it("renders as child element", () => {
+    render(
+      <Button asChild>
+        <a href="/test">Link Button</a>
+      </Button>,
+    );
+
+    const link = screen.getByRole("link", { name: "Link Button" });
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute("href", "/test");
+    expect(link).toHaveClass("bg-primary"); // Mantém estilos
+  });
+
+  it("forwards ref to child element", () => {
+    const ref = { current: null };
+    render(
+      <Button asChild ref={ref}>
+        <a href="/test">Link</a>
+      </Button>,
+    );
+    expect(ref.current).toBeInstanceOf(HTMLAnchorElement);
+  });
+});
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Button edge cases", () => {
+  it("handles rapid clicks correctly", async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(<Button onClick={handleClick}>Click</Button>);
+
+    await user.tripleClick(screen.getByRole("button"));
+    expect(handleClick).toHaveBeenCalledTimes(3);
+  });
+
+  it("works with form submission", async () => {
+    const user = userEvent.setup();
+    const handleSubmit = vi.fn((e) => e.preventDefault());
+
+    render(
+      <form onSubmit={handleSubmit}>
+        <Button type="submit">Submit</Button>
+      </form>,
+    );
+
+    await user.click(screen.getByRole("button"));
+    expect(handleSubmit).toHaveBeenCalled();
+  });
+
+  it("preserves default type as submit in forms", () => {
+    render(
+      <form>
+        <Button>Submit</Button>
+      </form>,
+    );
+    // Default type is "submit" per HTML spec when in form
+    expect(screen.getByRole("button")).toHaveAttribute("type", undefined);
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### ✅ Implementado
+
+#### `loading` + `loadingText`
+
+Estado de carregamento com spinner automático e preservação de layout (sem shift).
+
+```tsx
+// API implementada
+<Button loading>Saving...</Button>
+<Button loading loadingText="Salvando...">Save</Button>
+```
+
+#### `leftIcon` / `rightIcon`
+
+Props dedicadas para ícones.
+
+```tsx
+// API implementada
+<Button leftIcon={<Mail />}>Send Email</Button>
+<Button rightIcon={<ChevronRight />}>Next</Button>
+```
+
+#### Melhorias de A11y
+
+- `aria-busy="true"` automático quando `loading`.
+- `aria-label="Loading"` automático quando texto é ocultado pelo loading.
+- Prevenção de clique em links (`asChild`) quando `disabled`.
+
+### Prioridade Média
+
+#### `fullWidth`
+
+Botão ocupa 100% da largura do container.
+
+```tsx
+// Proposta de API
+interface ButtonProps {
+  fullWidth?: boolean
+}
+
+// Uso
+<Button fullWidth>Submit</Button>
+
+// Equivalente atual via className
+<Button className="w-full">Submit</Button>
+```
+
+**Referências:** Chakra, MUI, Mantine (`fullWidth`), AntD (`block`)
+
+#### Melhorias de A11y
+
+```tsx
+// aria-busy automático quando loading
+<Button loading /> // → aria-busy="true" automático
+
+// aria-disabled além de disabled
+<Button disabled /> // → aria-disabled="true" + disabled
+```
+
+**Referências:** React Aria, Ariakit, Fluent UI
+
+### Prioridade Baixa
+
+#### `ButtonGroup`
+
+Componente compound para agrupar botões.
+
+```tsx
+// Proposta de API
+<ButtonGroup variant="outline" size="sm">
+  <Button>Left</Button>
+  <Button>Center</Button>
+  <Button>Right</Button>
+</ButtonGroup>
+```
+
+**Referências:** Chakra, MUI, Mantine, AntD, Fluent UI, Carbon
+
+#### `radius`
+
+Controle granular de border-radius.
+
+```tsx
+// Proposta de API
+interface ButtonProps {
+  radius?: "none" | "sm" | "md" | "lg" | "full";
+}
+
+// Uso
+<Button radius="full">Pill Button</Button>;
+```
+
+**Referências:** Mantine, NextUI
+
+#### `color` / `colorScheme`
+
+Variação de cor independente da variante.
+
+```tsx
+// Proposta de API
+interface ButtonProps {
+  colorScheme?: "primary" | "success" | "warning" | "error";
+}
+
+// Uso
+<Button variant="outline" colorScheme="success">
+  Approve
+</Button>;
+```
+
+**Referências:** Chakra (`colorScheme`), MUI (`color`), Mantine (`color`)
+
+### Decisões de Design
+
+| Feature                | Recomendação   | Justificativa                 |
+| ---------------------- | -------------- | ----------------------------- |
+| `loading`              | ✅ Implementar | Alta demanda, UX melhor       |
+| `leftIcon`/`rightIcon` | ✅ Implementar | Ergonomia, type-safety        |
+| `fullWidth`            | ⚠️ Avaliar     | `className="w-full"` funciona |
+| `ButtonGroup`          | ✅ Implementar | Comum em UIs, boa composição  |
+| `radius`               | ❌ Evitar      | Usar variants ou className    |
+| `colorScheme`          | ❌ Evitar      | Complexidade, usar variants   |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System   | Documentação Button                                                                | GitHub                                                                        |
+| --------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**   | [Button](https://ui.shadcn.com/docs/components/button)                             | [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**  | [Button](https://react-spectrum.adobe.com/react-aria/Button.html)                  | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**   | [Button](https://chakra-ui.com/docs/components/button)                             | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**         | [Button](https://mui.com/material-ui/react-button/)                                | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**     | [Button](https://mantine.dev/core/button/)                                         | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design**  | [Button](https://ant.design/components/button)                                     | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**      | [Button](https://nextui.org/docs/components/button)                                | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Headless UI** | [Button](https://headlessui.com/react/button)                                      | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)         |
+| **Ariakit**     | [Button](https://ariakit.org/components/button)                                    | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**   | [Button](https://react.fluentui.dev/?path=/docs/components-button-button--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**      | [Button](https://carbondesignsystem.com/components/button/usage/)                  | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**   | [Button](https://blueprintjs.com/docs/#core/components/button)                     | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact**  | [Button](https://primereact.org/button/)                                           | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - Button Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button)
+- [HTML Spec - Button](https://html.spec.whatwg.org/multipage/form-elements.html#the-button-element)
+
+### 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/)