@etus/ui 0.1.0

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

@@ -0,0 +1,816 @@
+# Label
+
+## Visão Geral
+
+O **Label** é o componente fundamental para rotular elementos de formulário no Design System ETUS. Construído sobre o `@radix-ui/react-label`, fornece associação automática com campos de input através do atributo `htmlFor`, garantindo acessibilidade e usabilidade.
+
+### Casos de Uso
+
+- Rotular campos de input, textarea e select
+- Identificar grupos de opções (checkboxes, radios)
+- Fornecer contexto para leitores de tela
+- Indicar campos obrigatórios
+- Adicionar descrições auxiliares a campos
+
+### Classificação
+
+**Categoria:** Atom (Primitivo)
+**Dependências:** `@radix-ui/react-label`
+
+---
+
+## Design Specs
+
+### Estilos Base
+
+O Label utiliza tokens de componente com Tailwind v4 arbitrary values, mantendo consistência visual em todo o sistema.
+
+| Propriedade | Classe Tailwind                               | Token/Valor                      |
+| ----------- | --------------------------------------------- | -------------------------------- |
+| Layout      | `flex items-center`                           | Hardcoded (não tokenizável)      |
+| Espaçamento | `gap-[var(--label-root-gap)]`                 | `--label-root-gap` (8px)         |
+| Tipografia  | `text-[length:var(--label-root-font-size)]`   | `--label-root-font-size` (14px)  |
+| Peso        | `font-[number:var(--label-root-font-weight)]` | `--label-root-font-weight` (500) |
+| Line Height | `leading-[var(--label-root-line-height)]`     | `--label-root-line-height` (1)   |
+| Seleção     | `select-none`                                 | Hardcoded (não tokenizável)      |
+
+### Estados
+
+| Estado           | Classes/Atributos                                | Comportamento                                      |
+| ---------------- | ------------------------------------------------ | -------------------------------------------------- |
+| Default          | -                                                | Aparência base                                     |
+| Disabled (grupo) | `group-data-[disabled=true]:opacity-50`          | 50% opacidade quando grupo pai está desabilitado   |
+| Disabled (peer)  | `peer-disabled:opacity-50`                       | 50% opacidade quando input irmão está desabilitado |
+| Pointer Events   | `group-data-[disabled=true]:pointer-events-none` | Remove interatividade quando desabilitado          |
+| Cursor           | `peer-disabled:cursor-not-allowed`               | Cursor de bloqueio quando peer está desabilitado   |
+
+### Tokens de Componente
+
+O Label utiliza tokens de componente específicos definidos em `@etus/tokens`. Os tokens seguem a convenção:
+
+```
+--label-{category}-{property}
+```
+
+#### Tokens de Layout e Tipografia
+
+```css
+/* Root */
+--label-root-gap           /* Espaçamento entre elementos (8px) */
+--label-root-font-size     /* Tamanho do texto (14px) */
+--label-root-line-height   /* Altura da linha (1) */
+--label-root-font-weight   /* Peso da fonte (500) */
+
+/* Cores */
+--label-required-color     /* Cor do indicador obrigatório (destructive) */
+--label-optional-color     /* Cor do texto opcional (muted-foreground) */
+```
+
+#### Propriedades Não-Tokenizáveis
+
+Algumas propriedades CSS não podem ser usadas como CSS variables em Tailwind e são aplicadas diretamente:
+
+| Propriedade               | Classe Tailwind       | Justificativa                               |
+| ------------------------- | --------------------- | ------------------------------------------- |
+| `display: flex`           | `flex`                | Valores de display não são tokenizáveis     |
+| `align-items: center`     | `items-center`        | Valores de alinhamento não são tokenizáveis |
+| `user-select: none`       | `select-none`         | Valores de seleção não são tokenizáveis     |
+| `opacity: 0.5` (disabled) | `opacity-50`          | Valor fixo para estado desabilitado         |
+| `cursor: not-allowed`     | `cursor-not-allowed`  | Valores de cursor não são tokenizáveis      |
+| `pointer-events: none`    | `pointer-events-none` | Valores de eventos não são tokenizáveis     |
+
+---
+
+## Padrão de Tokens com Tailwind v4
+
+Esta seção documenta como os tokens CSS são usados com Tailwind CSS v4.
+
+### 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                                       |
+| --------------- | ---------------------------- | --------------------------------------------- |
+| **Dimensões**   | `gap-[var(--token)]`         | `gap-[var(--label-root-gap)]`                 |
+| **Font Size**   | `text-[length:var(--token)]` | `text-[length:var(--label-root-font-size)]`   |
+| **Line Height** | `leading-[var(--token)]`     | `leading-[var(--label-root-line-height)]`     |
+| **Font Weight** | `font-[number:var(--token)]` | `font-[number:var(--label-root-font-weight)]` |
+| **Cores**       | `text-[color:var(--token)]`  | `text-[color:var(--label-required-color)]`    |
+
+### Implementação no Componente
+
+```tsx
+// Label.tsx
+<LabelPrimitive.Root
+  className={cn(
+    // Layout (hardcoded - não tokenizável)
+    "flex items-center",
+    // Tokens de dimensão e tipografia
+    "gap-[var(--label-root-gap)]",
+    "text-[length:var(--label-root-font-size)]",
+    "leading-[var(--label-root-line-height)]",
+    "font-[number:var(--label-root-font-weight)]",
+    // Comportamento (hardcoded - não tokenizável)
+    "select-none",
+    // Estados desabilitados (hardcoded - valores fixos)
+    "group-data-[disabled=true]:pointer-events-none",
+    "group-data-[disabled=true]:opacity-50",
+    "peer-disabled:cursor-not-allowed",
+    "peer-disabled:opacity-50",
+    className,
+  )}
+>
+  {children}
+  {required && (
+    <span className="text-[color:var(--label-required-color)]">*</span>
+  )}
+  {optional && (
+    <span className="text-[color:var(--label-optional-color)] font-normal">
+      {optionalText}
+    </span>
+  )}
+</LabelPrimitive.Root>
+```
+
+### Por que 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
+text-[color:var(--label-required-color)]
+
+// ❌ INCORRETO - Tailwind não sabe o tipo
+text-[var(--label-required-color)]
+```
+
+Para font-weight, o type hint `number:` é necessário:
+
+```tsx
+// ✅ CORRETO - Tailwind interpreta como número
+font-[number:var(--label-root-font-weight)]
+
+// ❌ INCORRETO - Tailwind pode interpretar como família de fonte
+font-[var(--label-root-font-weight)]
+```
+
+### data-slot
+
+```html
+<label data-slot="label">...</label>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop        | Tipo                    | Padrão | Descrição                              |
+| ----------- | ----------------------- | ------ | -------------------------------------- |
+| `htmlFor`   | `string`                | -      | ID do elemento de formulário associado |
+| `className` | `string`                | -      | Classes CSS adicionais                 |
+| `children`  | `ReactNode`             | -      | Conteúdo do label                      |
+| `ref`       | `Ref<HTMLLabelElement>` | -      | Referência ao elemento DOM             |
+
+> Herda todas as props de `React.ComponentProps<typeof LabelPrimitive.Root>` que por sua vez estende `React.LabelHTMLAttributes<HTMLLabelElement>`
+
+### TypeScript
+
+```typescript
+import * as LabelPrimitive from "@radix-ui/react-label";
+
+// Props do componente
+type LabelProps = React.ComponentProps<typeof LabelPrimitive.Root>;
+
+// Equivalente a
+interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  asChild?: boolean;
+}
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature                | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+| ---------------------- | :--: | :----: | :---: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: | :--------: |
+| **Radix-based**        |  ✓   |   ✓    |   ✓   |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+| **htmlFor auto**       |  ✓   |   ✓    |   ✓   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Required indicator** |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Optional indicator** |  -   |   -    |   -   |   ✓    |  -  |    ✓    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+| **Tooltip built-in**   |  -   |   -    |   -   |   -    |  -  |    ✓    |  ✓   |   -    |    -     |    -    |   ✓    |   ✓    |     -     |     ✓      |
+| **Info icon**          |  -   |   -    |   -   |   -    |  -  |    ✓    |  ✓   |   -    |    -     |    -    |   -    |   ✓    |     -     |     ✓      |
+| **Size variants**      |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    -     |    -    |   ✓    |   -    |     -     |     ✓      |
+| **Weight variants**    |  -   |   -    |   -   |   ✓    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |     -      |
+| **Color variants**     |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  -   |   ✓    |    -     |    -    |   ✓    |   -    |     -     |     ✓      |
+| **Error state**        |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |     -     |     ✓      |
+| **Disabled state**     |  ✓   |   ✓    |   ✓   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **data-slot**          |  ✓   |   ✓    |   -   |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |     -      |
+| **asChild**            |  ✓   |   ✓    |   ✓   |   -    |  -  |    -    |  -   |   -    |    -     |    ✓    |   -    |   -    |     -     |     -      |
+| **FormLabel compound** |  -   |   -    |   -   |   ✓    |  ✓  |    ✓    |  ✓   |   -    |    -     |    -    |   ✓    |   ✓    |     -     |     -      |
+
+#### Comparativo de APIs por Design System
+
+| Design System  | Componente               | Props Principais                                                  |
+| -------------- | ------------------------ | ----------------------------------------------------------------- |
+| **ETUS**       | `Label`                  | `htmlFor`, `className`                                            |
+| **Shadcn/ui**  | `Label`                  | `htmlFor`, `className`                                            |
+| **Radix UI**   | `Label.Root`             | `htmlFor`, `asChild`                                              |
+| **Chakra UI**  | `FormLabel`              | `htmlFor`, `isRequired`, `requiredIndicator`, `optionalIndicator` |
+| **MUI**        | `InputLabel`             | `htmlFor`, `required`, `error`, `disabled`, `shrink`              |
+| **Mantine**    | `Input.Label`            | `required`, `size`, `labelProps`                                  |
+| **Ant Design** | `Form.Item` (label)      | `label`, `required`, `tooltip`, `colon`                           |
+| **NextUI**     | `label` (via Input)      | Integrado ao Input, não é componente separado                     |
+| **Fluent UI**  | `Label`                  | `htmlFor`, `required`, `disabled`, `size`, `weight`               |
+| **Carbon**     | `FormLabel`              | `className`, Integrado ao FormGroup                               |
+| **Blueprint**  | `FormGroup` (label)      | `label`, `labelFor`, `labelInfo`                                  |
+| **PrimeReact** | `label` (via FloatLabel) | Integrado ao FloatLabel                                           |
+
+#### Abordagens de Label por Categoria
+
+**Standalone (componente independente):**
+
+- **ETUS/Shadcn** - Label simples, composição manual
+- **Radix** - Primitivo puro, máximo controle
+- **Fluent UI** - Componente rico com variantes
+
+**Integrado ao Form (compound components):**
+
+- **Chakra UI** - FormLabel dentro de FormControl
+- **MUI** - InputLabel + FormControl + FormHelperText
+- **Mantine** - Input.Wrapper com Label/Description/Error
+- **Ant Design** - Form.Item engloba label + input + feedback
+
+**Integrado ao Input:**
+
+- **NextUI** - Label como prop do Input
+- **PrimeReact** - FloatLabel wrapper
+
+---
+
+## Acessibilidade (A11y)
+
+### Associação Label-Input
+
+O Label deve estar associado ao seu input correspondente através do atributo `htmlFor`:
+
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+```
+
+Alternativamente, pode-se usar aninhamento (menos recomendado):
+
+```tsx
+<Label>
+  Email
+  <Input type="email" />
+</Label>
+```
+
+### ARIA Attributes
+
+| Atributo         | Uso                                                          |
+| ---------------- | ------------------------------------------------------------ |
+| `for` (htmlFor)  | Associa label ao input pelo ID                               |
+| Semântica nativa | `<label>` é reconhecido automaticamente por leitores de tela |
+
+### Suporte a Teclado
+
+| Tecla                        | Ação                             |
+| ---------------------------- | -------------------------------- |
+| Click no label               | Move foco para o input associado |
+| Não requer navegação própria | Label não é focável              |
+
+### Screen Readers
+
+- Leitores de tela anunciam o label ao focar no input associado
+- Não é necessário `aria-label` no input quando há label associado
+- O texto do label deve ser descritivo e conciso
+
+### Boas Práticas
+
+```tsx
+// BOM - Label associado via htmlFor
+<Label htmlFor="name">Nome completo</Label>
+<Input id="name" />
+
+// BOM - Campo obrigatório indicado visualmente
+<Label htmlFor="email">
+  Email <span className="text-destructive">*</span>
+</Label>
+
+// RUIM - Sem associação
+<Label>Email</Label>
+<Input />
+
+// RUIM - Texto não descritivo
+<Label htmlFor="field1">Campo 1</Label>
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature                   | ETUS | Radix | React Aria | Ariakit | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+| ------------------------- | :--: | :---: | :--------: | :-----: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: | :-------: | :--------: |
+| **htmlFor nativo**        |  ✓   |   ✓   |     ✓      |    ✓    |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Auto-ID generation**    |  -   |   -   |     ✓      |    ✓    |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     -     |     ✓      |
+| **Required announcement** |  -   |   -   |     ✓      |    ✓    |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+| **Error state a11y**      |  -   |   -   |     ✓      |    ✓    |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |   ✓    |   ✓    |     ~     |     ✓      |
+| **Description linking**   |  -   |   -   |     ✓      |    ✓    |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |     ✓     |     ✓      |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+#### Considerações de A11y por Abordagem
+
+| Abordagem                     | Vantagem                     | Desvantagem                        |
+| ----------------------------- | ---------------------------- | ---------------------------------- |
+| **Standalone (ETUS)**         | Controle total, simples      | Requer gerenciamento manual de IDs |
+| **Form Integration (Chakra)** | Auto-ID, contexto automático | Mais complexo, menos flexível      |
+| **React Aria hooks**          | Máximo a11y, testado         | Curva de aprendizado               |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Label } from "@etus/ui";
+import { Input } from "@etus/ui";
+
+function Example() {
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="email">Email</Label>
+      <Input id="email" type="email" placeholder="seu@email.com" />
+    </div>
+  );
+}
+```
+
+### Com Campo Obrigatório
+
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="name">
+    Nome <span className="text-destructive">*</span>
+  </Label>
+  <Input id="name" required />
+</div>
+```
+
+### Com Descrição Auxiliar
+
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="password">Senha</Label>
+  <Input id="password" type="password" />
+  <p className="text-sm text-muted-foreground">
+    Mínimo 8 caracteres, incluindo maiúsculas e números.
+  </p>
+</div>
+```
+
+### Com Ícone
+
+```tsx
+import { Info } from "lucide-react";
+import { Tooltip, TooltipTrigger, TooltipContent } from "@etus/ui";
+
+<div className="space-y-2">
+  <Label htmlFor="api-key">
+    API Key
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Info className="h-4 w-4 text-muted-foreground cursor-help" />
+      </TooltipTrigger>
+      <TooltipContent>
+        Encontre sua API key nas configurações da conta.
+      </TooltipContent>
+    </Tooltip>
+  </Label>
+  <Input id="api-key" type="password" />
+</div>;
+```
+
+### Estado Desabilitado
+
+```tsx
+// Via grupo
+<div className="space-y-2" data-disabled="true">
+  <Label htmlFor="disabled-input">Campo desabilitado</Label>
+  <Input id="disabled-input" disabled />
+</div>
+
+// Via peer (input irmão)
+<div className="space-y-2">
+  <Label htmlFor="peer-disabled" className="peer-disabled:opacity-50">
+    Campo desabilitado (peer)
+  </Label>
+  <Input id="peer-disabled" disabled className="peer" />
+</div>
+```
+
+### Composição com Checkbox
+
+```tsx
+import { Checkbox } from "@etus/ui";
+
+<div className="flex items-center gap-2">
+  <Checkbox id="terms" />
+  <Label htmlFor="terms">Aceito os termos e condições</Label>
+</div>;
+```
+
+### Composição com Radio Group
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@etus/ui";
+
+<RadioGroup defaultValue="option1">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="option1" value="option1" />
+    <Label htmlFor="option1">Opção 1</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="option2" value="option2" />
+    <Label htmlFor="option2">Opção 2</Label>
+  </div>
+</RadioGroup>;
+```
+
+### Composição com Switch
+
+```tsx
+import { Switch } from "@etus/ui";
+
+<div className="flex items-center gap-2">
+  <Switch id="notifications" />
+  <Label htmlFor="notifications">Receber notificações</Label>
+</div>;
+```
+
+### Uso com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form";
+import { Label } from "@etus/ui";
+import { Input } from "@etus/ui";
+
+function ContactForm() {
+  const {
+    register,
+    formState: { errors },
+  } = useForm();
+
+  return (
+    <form>
+      <div className="space-y-2">
+        <Label htmlFor="name">Nome</Label>
+        <Input
+          id="name"
+          {...register("name", { required: true })}
+          aria-invalid={errors.name ? "true" : "false"}
+        />
+        {errors.name && (
+          <p className="text-sm text-destructive">Nome é obrigatório</p>
+        )}
+      </div>
+    </form>
+  );
+}
+```
+
+### Label Inline com Input
+
+```tsx
+<div className="flex items-center gap-4">
+  <Label htmlFor="inline-input" className="whitespace-nowrap">
+    Quantidade:
+  </Label>
+  <Input id="inline-input" type="number" className="w-20" />
+</div>
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Label.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Label } from "./Label";
+
+describe("Label", () => {
+  it("renders children correctly", () => {
+    render(<Label>Email</Label>);
+    expect(screen.getByText("Email")).toBeInTheDocument();
+  });
+
+  it("has correct htmlFor attribute", () => {
+    render(<Label htmlFor="email-input">Email</Label>);
+    expect(screen.getByText("Email")).toHaveAttribute("for", "email-input");
+  });
+
+  it("merges custom className", () => {
+    render(<Label className="custom-class">Test</Label>);
+    expect(screen.getByText("Test")).toHaveClass("custom-class");
+  });
+
+  it("has data-slot attribute", () => {
+    render(<Label>Test</Label>);
+    expect(screen.getByText("Test")).toHaveAttribute("data-slot", "label");
+  });
+
+  it("has correct base classes", () => {
+    render(<Label>Test</Label>);
+    const label = screen.getByText("Test");
+    expect(label).toHaveClass(
+      "flex",
+      "items-center",
+      "gap-[var(--label-root-gap)]",
+      "text-[length:var(--label-root-font-size)]",
+      "font-[number:var(--label-root-font-weight)]",
+    );
+  });
+});
+```
+
+### Testes de Interação
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+describe("Label interactions", () => {
+  it("clicking label focuses associated input", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <>
+        <Label htmlFor="test-input">Click me</Label>
+        <input id="test-input" />
+      </>,
+    );
+
+    await user.click(screen.getByText("Click me"));
+    expect(screen.getByRole("textbox")).toHaveFocus();
+  });
+
+  it("text is not selectable", () => {
+    render(<Label>Test</Label>);
+    expect(screen.getByText("Test")).toHaveClass("select-none");
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Label accessibility", () => {
+  it("has no accessibility violations when properly associated", async () => {
+    const { container } = render(
+      <>
+        <Label htmlFor="a11y-input">Accessible Label</Label>
+        <input id="a11y-input" />
+      </>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("renders as label element", () => {
+    render(<Label>Test</Label>);
+    expect(screen.getByText("Test").tagName).toBe("LABEL");
+  });
+});
+```
+
+### Testes de Estados
+
+```tsx
+describe("Label states", () => {
+  it("applies disabled styles via group", () => {
+    render(
+      <div data-disabled="true">
+        <Label>Disabled Label</Label>
+      </div>,
+    );
+
+    const label = screen.getByText("Disabled Label");
+    expect(label).toHaveClass("group-data-[disabled=true]:opacity-50");
+  });
+
+  it("works with disabled peer input", () => {
+    render(
+      <>
+        <Label htmlFor="disabled-peer">Label</Label>
+        <input id="disabled-peer" disabled className="peer" />
+      </>,
+    );
+
+    expect(screen.getByText("Label")).toHaveClass("peer-disabled:opacity-50");
+  });
+});
+```
+
+### Testes de Composição
+
+```tsx
+describe("Label composition", () => {
+  it("works with children elements", () => {
+    render(
+      <Label htmlFor="with-icon">
+        Email
+        <span data-testid="icon">*</span>
+      </Label>,
+    );
+
+    expect(screen.getByText("Email")).toBeInTheDocument();
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+  });
+
+  it("forwards ref correctly", () => {
+    const ref = { current: null };
+    render(<Label ref={ref}>Test</Label>);
+    expect(ref.current).toBeInstanceOf(HTMLLabelElement);
+  });
+});
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Label edge cases", () => {
+  it("handles empty htmlFor gracefully", () => {
+    render(<Label htmlFor="">Empty For</Label>);
+    expect(screen.getByText("Empty For")).toHaveAttribute("for", "");
+  });
+
+  it("handles long text without breaking layout", () => {
+    const longText = "Este é um label muito longo que poderia quebrar o layout";
+    render(<Label>{longText}</Label>);
+    expect(screen.getByText(longText)).toBeInTheDocument();
+  });
+
+  it("renders correctly with special characters", () => {
+    render(<Label>Email &amp; Nome</Label>);
+    expect(screen.getByText("Email & Nome")).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+#### `required` indicator
+
+Indicador visual automático para campos obrigatórios.
+
+```tsx
+// Proposta de API
+interface LabelProps {
+  required?: boolean
+  requiredIndicator?: ReactNode
+}
+
+// Uso
+<Label htmlFor="email" required>Email</Label>
+// Renderiza: Email *
+
+<Label htmlFor="email" required requiredIndicator={<span className="text-destructive">(obrigatório)</span>}>
+  Email
+</Label>
+```
+
+**Referências:** Chakra (`isRequired`), MUI (`required`), Mantine (`required`), AntD (`required`)
+
+### Prioridade Média
+
+#### `optional` indicator
+
+Indicador para campos opcionais (inverso de required).
+
+```tsx
+// Proposta de API
+interface LabelProps {
+  optional?: boolean;
+  optionalIndicator?: ReactNode;
+}
+
+// Uso
+<Label htmlFor="nickname" optional>
+  Apelido
+</Label>;
+// Renderiza: Apelido (opcional)
+```
+
+**Referências:** Chakra (`optionalIndicator`), Mantine (via suffix)
+
+#### `size` variants
+
+Tamanhos pré-definidos para diferentes contextos.
+
+```tsx
+// Proposta de API
+interface LabelProps {
+  size?: "sm" | "default" | "lg";
+}
+
+// Uso
+<Label size="lg" htmlFor="title">
+  Título da Página
+</Label>;
+```
+
+**Referências:** Fluent UI (`size`), NextUI (`size`), PrimeReact
+
+### Prioridade Baixa
+
+#### `weight` variants
+
+Controle de peso da fonte.
+
+```tsx
+// Proposta de API
+interface LabelProps {
+  weight?: "normal" | "medium" | "semibold" | "bold";
+}
+```
+
+**Referências:** Fluent UI (`weight`), Chakra (`fontWeight`)
+
+#### Integração com Tooltip
+
+```tsx
+// Proposta de API
+interface LabelProps {
+  tooltip?: ReactNode;
+  tooltipSide?: "top" | "right" | "bottom" | "left";
+}
+
+// Uso
+<Label htmlFor="api" tooltip="Encontre nas configurações">
+  API Key
+</Label>;
+```
+
+**Referências:** Mantine (`labelProps`), AntD (`tooltip`), Carbon
+
+### Decisões de Design
+
+| Feature    | Recomendação  | Justificativa                       |
+| ---------- | ------------- | ----------------------------------- |
+| `required` | ✓ Implementar | Alta demanda, padrão de formulário  |
+| `optional` | ⚠️ Avaliar    | Menos comum, pode usar children     |
+| `size`     | ✗ Evitar      | Usar className, manter simplicidade |
+| `weight`   | ✗ Evitar      | Usar className                      |
+| `tooltip`  | ⚠️ Avaliar    | Composição manual funciona bem      |
+
+**Filosofia ETUS:** Manter o Label simples e atômico. Features complexas como required/optional podem ser implementadas via composição ou em um componente `FormField` de nível superior.
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System  | Documentação Label                                                        | GitHub                                                                        |
+| -------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**  | [Label](https://ui.shadcn.com/docs/components/label)                      | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**   | [Label](https://www.radix-ui.com/primitives/docs/components/label)        | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **React Aria** | [useLabel](https://react-spectrum.adobe.com/react-aria/useLabel.html)     | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**  | [FormLabel](https://chakra-ui.com/docs/components/form-control)           | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**        | [InputLabel](https://mui.com/material-ui/api/input-label/)                | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**    | [Input.Label](https://mantine.dev/core/input/#inputlabel)                 | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design** | [Form.Item](https://ant.design/components/form)                           | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**     | [Input (label)](https://nextui.org/docs/components/input)                 | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Ariakit**    | [FormLabel](https://ariakit.org/reference/form-label)                     | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**  | [Label](https://react.fluentui.dev/?path=/docs/components-label--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**     | [FormLabel](https://carbondesignsystem.com/components/form/usage/)        | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**  | [FormGroup](https://blueprintjs.com/docs/#core/components/form-group)     | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact** | [FloatLabel](https://primereact.org/floatlabel/)                          | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificações e Padrões
+
+- [WAI-ARIA - Labels and Descriptions](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/)
+- [WCAG 2.1 - Labels or Instructions](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html)
+- [MDN - Label Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)
+- [HTML Spec - Label](https://html.spec.whatwg.org/multipage/forms.html#the-label-element)
+
+### Ferramentas Utilizadas
+
+- [Radix UI Label](https://www.radix-ui.com/primitives/docs/components/label)
+- [Tailwind CSS](https://tailwindcss.com/docs)