@etus/ui 0.1.1 → 0.1.2

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

@@ -1,1112 +0,0 @@
-# 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/)