@etus/ui 0.1.0

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

@@ -0,0 +1,739 @@
+# HelpText
+
+## Visão Geral
+
+O **HelpText** e um componente atomico que fornece texto auxiliar contextual para elementos de formulario. Como elemento atom, ele complementa inputs, selects e outros controles de formulario, comunicando informacoes adicionais, dicas de preenchimento, mensagens de validacao ou estados do campo.
+
+### Casos de Uso
+
+- Exibir instrucoes de preenchimento abaixo de campos de formulario
+- Mostrar mensagens de erro de validacao com destaque visual
+- Comunicar limites de caracteres ou formatos esperados
+- Fornecer dicas contextuais que auxiliam o usuario
+- Indicar estados de sucesso apos validacao
+
+### Classificacao
+
+**Categoria:** Atom
+**Dependencias:** `class-variance-authority`, `@radix-ui/react-slot`
+
+> **Status:** Componente proposto. Esta documentacao define a API e especificacoes para implementacao futura.
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Texto auxiliar neutro, instrucoes gerais | `text-muted-foreground` |
+| `info` | Informacoes adicionais destacadas | `text-info-foreground` |
+| `success` | Confirmacao de validacao bem-sucedida | `text-success-foreground` |
+| `warning` | Alertas e avisos nao-bloqueantes | `text-warning-foreground` |
+| `error` | Mensagens de erro de validacao | `text-destructive` |
+
+### Tamanhos (`size`)
+
+| Tamanho | Font Size | Line Height | Uso |
+|---------|-----------|-------------|-----|
+| `sm` | `text-xs` (12px) | `leading-tight` | Textos compactos, formularios densos |
+| `default` | `text-sm` (14px) | `leading-normal` | Uso padrao em formularios |
+| `lg` | `text-base` (16px) | `leading-relaxed` | Maior legibilidade, acessibilidade |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparencia base com cor da variante |
+| Disabled | `data-disabled`, `opacity-50` | 50% opacidade, acompanha estado do campo |
+| Hidden | `sr-only` | Visivel apenas para screen readers |
+| With Icon | `data-has-icon` | Gap adicional para icone |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--color-muted-foreground: oklch(0.556 0 0);
+--color-destructive: oklch(0.577 0.245 27.325);
+--color-success-foreground: oklch(0.627 0.194 149.214);
+--color-warning-foreground: oklch(0.681 0.162 75.834);
+--color-info-foreground: oklch(0.623 0.214 259.815);
+
+/* Espacamento */
+--spacing-0-5: 0.125rem; /* gap com icone */
+--spacing-1: 0.25rem;    /* margin-top padrao */
+--spacing-1-5: 0.375rem; /* gap interno */
+
+/* Tipografia */
+--font-size-xs: 0.75rem;
+--font-size-sm: 0.875rem;
+--font-size-base: 1rem;
+--line-height-tight: 1.25;
+--line-height-normal: 1.5;
+--line-height-relaxed: 1.625;
+
+/* Transicoes */
+--transition-colors: color 150ms ease;
+```
+
+### data-slot
+
+```html
+<p data-slot="help-text">
+  <span data-slot="help-text-icon">...</span>
+  <span data-slot="help-text-content">Texto auxiliar</span>
+</p>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "info" \| "success" \| "warning" \| "error"` | `"default"` | Estilo visual e semantico |
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Tamanho do texto |
+| `asChild` | `boolean` | `false` | Renderiza children como elemento |
+| `className` | `string` | - | Classes CSS adicionais |
+| `icon` | `ReactNode` | - | Icone exibido antes do texto |
+| `showIcon` | `boolean` | `false` | Exibe icone padrao da variante |
+| `srOnly` | `boolean` | `false` | Visivel apenas para screen readers |
+| `children` | `ReactNode` | - | Conteudo do texto auxiliar |
+| `ref` | `Ref<HTMLParagraphElement>` | - | Referencia ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"p">`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| - | - | Componente estatico, sem callbacks |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Variants exportadas
+const helpTextVariants = cva(
+  "text-sm leading-normal font-normal transition-colors",
+  {
+    variants: {
+      variant: {
+        default: "text-muted-foreground",
+        info: "text-info-foreground",
+        success: "text-success-foreground",
+        warning: "text-warning-foreground",
+        error: "text-destructive",
+      },
+      size: {
+        sm: "text-xs leading-tight",
+        default: "text-sm leading-normal",
+        lg: "text-base leading-relaxed",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+// Props do componente
+type HelpTextProps = React.ComponentProps<"p"> &
+  VariantProps<typeof helpTextVariants> & {
+    asChild?: boolean
+    icon?: React.ReactNode
+    showIcon?: boolean
+    srOnly?: boolean
+  }
+
+// Tipos derivados uteis
+type HelpTextVariant = NonNullable<VariantProps<typeof helpTextVariants>["variant"]>
+type HelpTextSize = NonNullable<VariantProps<typeof helpTextVariants>["size"]>
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:------:|:-----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|:----------:|
+| Variantes semanticas | ✓ | ~ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| Icone integrado | ✓ | - | - | - | ✓ | - | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | - | ✓ |
+| Tamanhos | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | - | ✓ |
+| asChild/Slot | ✓ | ✓ | ✓ | - | - | - | - | - | - | - | ✓ | - | - | - | - |
+| sr-only mode | ✓ | - | - | ✓ | - | - | - | - | - | - | - | - | - | - | - |
+| aria-live | ✓ | - | - | ✓ | - | - | - | - | - | - | ✓ | ✓ | ✓ | - | - |
+| data-slot | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| Associacao via id | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `variant` | ✓ | `status` | `error` | `error` | `status` | `color` | `validationState` |
+| `size` | ✓ | `fontSize` | `size` | `size` | - | `size` | `size` |
+| `icon` | ✓ | - | - | `icon` | - | `startContent` | `icon` |
+| `disabled` | ✓ | - | `disabled` | - | - | `isDisabled` | `disabled` |
+
+#### Nomenclatura nos Design Systems
+
+| Design System | Nome do Componente | Localizacao |
+|---------------|-------------------|-------------|
+| **Shadcn/ui** | `FormDescription` | Parte do Form |
+| **Chakra UI** | `FormHelperText` | Componente dedicado |
+| **MUI** | `FormHelperText` | Componente dedicado |
+| **Mantine** | `Input.Description` | Compound component |
+| **Ant Design** | `Form.Item` + `extra` | Prop do wrapper |
+| **NextUI** | `description` prop | Prop do Input |
+| **Fluent UI** | `Field` + `validationMessage` | Prop do Field |
+| **Carbon** | `helperText` prop | Prop do TextInput |
+| **Blueprint** | `helperText` prop | Prop do FormGroup |
+| **PrimeReact** | `Message` | Componente separado |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `id` | Identificador unico para associacao via `aria-describedby` |
+| `aria-live="polite"` | Anuncia mudancas para variantes `error`/`warning` |
+| `aria-atomic="true"` | Anuncia conteudo completo em mudancas |
+| `role="status"` | Para variantes `success`/`info` (opcional) |
+| `role="alert"` | Para variante `error` (anuncio imediato) |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| - | Componente nao-interativo, sem interacoes de teclado |
+
+> O HelpText e um componente de apresentacao. A navegacao por teclado ocorre nos elementos associados (inputs, selects, etc.).
+
+### Focus Management
+
+```tsx
+// HelpText nao recebe foco diretamente
+// Associacao com campo via aria-describedby:
+<Input aria-describedby="help-text-id" />
+<HelpText id="help-text-id">Texto auxiliar</HelpText>
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Variante | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| `default` | `muted-foreground` | `background` | 4.5:1+ |
+| `info` | `info-foreground` | `background` | 4.5:1+ |
+| `success` | `success-foreground` | `background` | 4.5:1+ |
+| `warning` | `warning-foreground` | `background` | 4.5:1+ |
+| `error` | `destructive` | `background` | 4.5:1+ |
+
+### Screen Readers
+
+- **Associacao obrigatoria:** Sempre use `aria-describedby` no campo para associar o HelpText
+- **Anuncios dinamicos:** Variante `error` usa `role="alert"` para anuncio imediato
+- **Modo sr-only:** Use `srOnly` para textos visiveis apenas para leitores de tela
+- **Contexto semantico:** Icones decorativos devem ter `aria-hidden="true"`
+
+### Reduced Motion
+
+```tsx
+// Transicoes respeitam preferencia do usuario
+motion-reduce:transition-none
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:---------:|:----------:|
+| aria-describedby | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | ~ |
+| aria-live | ✓ | ✓ | - | ✓ | - | - | ~ | - | - | - | ✓ | ✓ | - | - |
+| role="alert" | ✓ | ✓ | - | ✓ | - | - | - | - | - | - | ✓ | ✓ | - | - |
+| sr-only mode | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - | - | - |
+| Contraste AA | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Reduced motion | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { HelpText } from "@etus/ui"
+
+function Example() {
+  return <HelpText>Insira seu email corporativo</HelpText>
+}
+```
+
+### Variantes
+
+```tsx
+import { HelpText } from "@etus/ui"
+
+function VariantsExample() {
+  return (
+    <div className="flex flex-col gap-2">
+      <HelpText variant="default">
+        Texto auxiliar padrao
+      </HelpText>
+
+      <HelpText variant="info">
+        Dica: Use letras e numeros
+      </HelpText>
+
+      <HelpText variant="success">
+        Email valido!
+      </HelpText>
+
+      <HelpText variant="warning">
+        Senha fraca, considere adicionar caracteres especiais
+      </HelpText>
+
+      <HelpText variant="error">
+        Este campo e obrigatorio
+      </HelpText>
+    </div>
+  )
+}
+```
+
+### Tamanhos
+
+```tsx
+import { HelpText } from "@etus/ui"
+
+function SizesExample() {
+  return (
+    <div className="flex flex-col gap-2">
+      <HelpText size="sm">Texto pequeno (12px)</HelpText>
+      <HelpText size="default">Texto padrao (14px)</HelpText>
+      <HelpText size="lg">Texto grande (16px)</HelpText>
+    </div>
+  )
+}
+```
+
+### Com Icones
+
+```tsx
+import { HelpText } from "@etus/ui"
+import { Info, CheckCircle, AlertTriangle, XCircle } from "lucide-react"
+
+function IconsExample() {
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Icone customizado */}
+      <HelpText variant="info" icon={<Info className="size-4" />}>
+        Informacao adicional
+      </HelpText>
+
+      {/* Icone padrao da variante */}
+      <HelpText variant="success" showIcon>
+        Operacao concluida
+      </HelpText>
+
+      <HelpText variant="warning" showIcon>
+        Atencao ao prazo
+      </HelpText>
+
+      <HelpText variant="error" showIcon>
+        Erro de validacao
+      </HelpText>
+    </div>
+  )
+}
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { HelpText } from "@etus/ui"
+
+function AsChildExample() {
+  return (
+    <HelpText asChild variant="info">
+      <span className="flex items-center gap-1">
+        <CustomIcon />
+        Texto customizado
+      </span>
+    </HelpText>
+  )
+}
+```
+
+### Estados
+
+```tsx
+import { HelpText } from "@etus/ui"
+
+function StatesExample() {
+  return (
+    <div className="flex flex-col gap-2">
+      {/* Padrao */}
+      <HelpText>Texto auxiliar visivel</HelpText>
+
+      {/* Apenas screen reader */}
+      <HelpText srOnly>
+        Este texto e visivel apenas para leitores de tela
+      </HelpText>
+
+      {/* Desabilitado (acompanha campo) */}
+      <HelpText data-disabled>
+        Campo desabilitado
+      </HelpText>
+    </div>
+  )
+}
+```
+
+### Integracao com Formularios
+
+```tsx
+import { Field, FieldLabel, TextInput, HelpText } from "@etus/ui"
+import { useId } from "react"
+
+function FormIntegrationExample() {
+  const helpTextId = useId()
+
+  return (
+    <Field>
+      <FieldLabel htmlFor="email">Email</FieldLabel>
+      <TextInput
+        id="email"
+        type="email"
+        aria-describedby={helpTextId}
+      />
+      <HelpText id={helpTextId}>
+        Usaremos seu email apenas para comunicacoes importantes
+      </HelpText>
+    </Field>
+  )
+}
+```
+
+### Validacao Dinamica
+
+```tsx
+import { Field, FieldLabel, TextInput, HelpText } from "@etus/ui"
+import { useState } from "react"
+
+function DynamicValidationExample() {
+  const [email, setEmail] = useState("")
+  const [touched, setTouched] = useState(false)
+
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+  const showError = touched && !isValid && email.length > 0
+  const showSuccess = touched && isValid
+
+  return (
+    <Field data-invalid={showError}>
+      <FieldLabel>Email</FieldLabel>
+      <TextInput
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        onBlur={() => setTouched(true)}
+        aria-invalid={showError}
+        aria-describedby="email-help"
+      />
+
+      {!touched && (
+        <HelpText id="email-help">
+          Digite seu email corporativo
+        </HelpText>
+      )}
+
+      {showError && (
+        <HelpText id="email-help" variant="error" showIcon>
+          Formato de email invalido
+        </HelpText>
+      )}
+
+      {showSuccess && (
+        <HelpText id="email-help" variant="success" showIcon>
+          Email valido!
+        </HelpText>
+      )}
+    </Field>
+  )
+}
+```
+
+### Composicao com FieldDescription
+
+```tsx
+import { Field, FieldLabel, FieldDescription, TextInput, HelpText } from "@etus/ui"
+
+function CompositionExample() {
+  return (
+    <Field>
+      <FieldLabel>Senha</FieldLabel>
+      <FieldDescription>
+        Crie uma senha forte para proteger sua conta
+      </FieldDescription>
+      <TextInput type="password" aria-describedby="password-help" />
+      <HelpText id="password-help" variant="info" size="sm">
+        Minimo 8 caracteres, incluindo letras e numeros
+      </HelpText>
+    </Field>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// HelpText.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { HelpText } from "./HelpText"
+
+describe("HelpText", () => {
+  it("renders children correctly", () => {
+    render(<HelpText>Texto auxiliar</HelpText>)
+    expect(screen.getByText("Texto auxiliar")).toBeInTheDocument()
+  })
+
+  it("applies variant classes", () => {
+    render(<HelpText variant="error">Erro</HelpText>)
+    expect(screen.getByText("Erro")).toHaveClass("text-destructive")
+  })
+
+  it("applies size classes", () => {
+    render(<HelpText size="sm">Pequeno</HelpText>)
+    expect(screen.getByText("Pequeno")).toHaveClass("text-xs")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<HelpText>Test</HelpText>)
+    expect(screen.getByText("Test")).toHaveAttribute("data-slot", "help-text")
+  })
+
+  it("renders with custom id for aria-describedby", () => {
+    render(<HelpText id="my-help-text">Help</HelpText>)
+    expect(screen.getByText("Help")).toHaveAttribute("id", "my-help-text")
+  })
+
+  it("applies sr-only class when srOnly prop is true", () => {
+    render(<HelpText srOnly>Screen reader only</HelpText>)
+    expect(screen.getByText("Screen reader only")).toHaveClass("sr-only")
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("HelpText interactions", () => {
+  it("renders icon when showIcon is true", () => {
+    render(<HelpText variant="error" showIcon>Error message</HelpText>)
+    expect(screen.getByRole("img", { hidden: true })).toBeInTheDocument()
+  })
+
+  it("renders custom icon when provided", () => {
+    const CustomIcon = () => <span data-testid="custom-icon">!</span>
+    render(<HelpText icon={<CustomIcon />}>With icon</HelpText>)
+    expect(screen.getByTestId("custom-icon")).toBeInTheDocument()
+  })
+
+  it("uses role='alert' for error variant", () => {
+    render(<HelpText variant="error">Error</HelpText>)
+    expect(screen.getByRole("alert")).toBeInTheDocument()
+  })
+
+  it("renders as different element with asChild", () => {
+    render(
+      <HelpText asChild>
+        <span data-testid="custom-element">Custom</span>
+      </HelpText>
+    )
+    expect(screen.getByTestId("custom-element")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("HelpText accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<HelpText>Accessible</HelpText>)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with error variant", async () => {
+    const { container } = render(
+      <HelpText variant="error">Error message</HelpText>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("works correctly with aria-describedby association", async () => {
+    const { container } = render(
+      <>
+        <input aria-describedby="help-id" />
+        <HelpText id="help-id">Help text</HelpText>
+      </>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has aria-live='polite' for dynamic updates", () => {
+    render(<HelpText variant="error">Dynamic error</HelpText>)
+    expect(screen.getByRole("alert")).toHaveAttribute("aria-live", "assertive")
+  })
+
+  it("screen reader only text is still in DOM", () => {
+    render(<HelpText srOnly>Hidden text</HelpText>)
+    expect(screen.getByText("Hidden text")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Composicao
+
+```tsx
+describe("HelpText composition", () => {
+  it("integrates with Field component", () => {
+    render(
+      <Field>
+        <FieldLabel htmlFor="test">Label</FieldLabel>
+        <input id="test" aria-describedby="test-help" />
+        <HelpText id="test-help">Help text</HelpText>
+      </Field>
+    )
+
+    const input = screen.getByRole("textbox")
+    expect(input).toHaveAttribute("aria-describedby", "test-help")
+  })
+
+  it("inherits disabled state from parent Field", () => {
+    render(
+      <Field data-disabled>
+        <HelpText>Disabled help</HelpText>
+      </Field>
+    )
+
+    expect(screen.getByText("Disabled help").closest("[data-slot='field']"))
+      .toHaveAttribute("data-disabled")
+  })
+
+  it("shows correct variant based on field validation state", () => {
+    const { rerender } = render(
+      <Field>
+        <HelpText variant="default">Default</HelpText>
+      </Field>
+    )
+
+    expect(screen.getByText("Default")).toHaveClass("text-muted-foreground")
+
+    rerender(
+      <Field data-invalid>
+        <HelpText variant="error">Error</HelpText>
+      </Field>
+    )
+
+    expect(screen.getByText("Error")).toHaveClass("text-destructive")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+- [ ] **Icones padrao por variante:** Mapear icones automaticos (Info, Check, AlertTriangle, XCircle) para cada variante
+- [ ] **Integracao com react-hook-form:** Hook `useFormHelpText` para exibir mensagens de validacao automaticamente
+- [ ] **Animacao de entrada:** Transicao suave ao aparecer/desaparecer (com respeito a `prefers-reduced-motion`)
+
+### Prioridade Media
+
+- [ ] **Character counter:** Variante ou prop para exibir contagem de caracteres (`32/100`)
+- [ ] **HelpText.List:** Subcomponente para multiplas mensagens em lista
+- [ ] **Tooltip mode:** Exibir como tooltip em vez de inline
+
+### Prioridade Baixa
+
+- [ ] **HelpText.Link:** Subcomponente para links de ajuda contextuais
+- [ ] **Collapse/Expand:** Expandir texto longo sob demanda
+- [ ] **Rich text support:** Suporte a formatacao basica (bold, links)
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| Nome do componente | `HelpText` | Mais explicito que `FormHelperText` (Chakra/MUI), alinhado com Carbon |
+| Variantes semanticas | Adotar | 10/14 DS implementam, essencial para feedback visual |
+| Icone integrado | Adotar com `showIcon` | 8/14 DS implementam, melhora reconhecimento visual |
+| Prop `icon` customizado | Adotar | Flexibilidade para casos especificos |
+| `asChild` pattern | Adotar | Consistencia com outros componentes ETUS (Shadcn pattern) |
+| `role="alert"` para error | Adotar | Best practice a11y, React Aria e Fluent implementam |
+| Componente separado vs prop | Componente separado | Mais flexivel, permite composicao, facilita testes |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentacao | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [FormDescription](https://ui.shadcn.com/docs/components/form) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Form](https://www.radix-ui.com/primitives/docs/components/form) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [FormHelperText](https://chakra-ui.com/docs/components/form-control) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [FormHelperText](https://mui.com/material-ui/api/form-helper-text/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Input.Description](https://mantine.dev/core/input/) | [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](https://nextui.org/docs/components/input) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | [Description](https://headlessui.com/react/description) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [FormDescription](https://ariakit.org/components/form) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Field](https://react.fluentui.dev/?path=/docs/components-field) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [TextInput](https://carbondesignsystem.com/components/text-input/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** | [Message](https://primereact.org/message/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Forms](https://www.w3.org/WAI/ARIA/apg/patterns/forms/)
+- [WCAG 2.1 - 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
+- [WCAG 2.1 - 3.3.1 Error Identification](https://www.w3.org/WAI/WCAG21/Understanding/error-identification)
+- [MDN - aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [Radix Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)
+- [Lucide Icons](https://lucide.dev/icons/)