@etus/ui 0.1.0

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

@@ -0,0 +1,954 @@
+# Link
+
+## Visão Geral
+
+O **Link** é o componente de navegação fundamental do Design System ETUS, usado para criar hyperlinks acessíveis e esteticamente consistentes. Como elemento atômico, serve de base para navegação interna e externa, mantendo a semântica HTML correta enquanto oferece variantes visuais flexíveis.
+
+> **Status:** Componente planejado - documentação de especificação
+
+### Casos de Uso
+
+- Navegação entre páginas da aplicação
+- Links externos para recursos e documentação
+- Navegação inline dentro de blocos de texto
+- Breadcrumbs e menus de navegação
+- Links em cards e listas
+- Âncora para seções dentro da mesma página
+
+### Classificação
+
+**Categoria:** Atom (Primitive)
+**Dependências:** `@radix-ui/react-slot`, `class-variance-authority`
+**Relacionados:** `Button` (variant="link"), `Breadcrumb`, `NavLink`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Links padrão em texto | `text-primary`, underline on hover |
+| `muted` | Links secundários, menos ênfase | `text-muted-foreground`, underline on hover |
+| `subtle` | Links discretos em contextos densos | `text-foreground`, underline on hover |
+| `nav` | Links de navegação (menu, sidebar) | `text-foreground`, sem underline, hover `text-primary` |
+| `inline` | Links dentro de parágrafos | `text-primary`, underline sempre visível |
+| `unstyled` | Reset completo para customização | Herda estilos do contexto |
+
+### Tamanhos (`size`)
+
+| Tamanho | Font Size | Line Height | Uso |
+|---------|-----------|-------------|-----|
+| `xs` | `text-xs` (12px) | 1.5 | Notas de rodapé, disclaimers |
+| `sm` | `text-sm` (14px) | 1.5 | Uso geral, UI compacta |
+| `default` | `text-base` (16px) | 1.5 | Corpo de texto, conteúdo principal |
+| `lg` | `text-lg` (18px) | 1.5 | Títulos, CTAs |
+| `inherit` | Herda do contexto | - | Uso inline em parágrafos |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparência base |
+| Hover | `hover:underline`, `hover:text-primary/80` | Underline, leve mudança de cor |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
+| Active | `active:text-primary/70` | Leve escurecimento |
+| Visited | `visited:text-muted-foreground` | Cor diferenciada (opcional) |
+| Disabled | `aria-disabled:opacity-50` | 50% opacidade, sem pointer events |
+| Current | `aria-current="page"` | Estilo diferenciado para página atual |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--primary              /* Cor padrão do link */
+--primary-foreground   /* Hover state */
+--muted-foreground     /* Variante muted */
+--foreground           /* Variante subtle/nav */
+--ring                 /* Focus ring */
+
+/* Tipografia */
+text-sm                /* 14px default */
+font-medium            /* 500 para nav */
+font-normal            /* 400 para inline */
+
+/* Espaçamento */
+underline-offset-4     /* Offset do underline */
+
+/* Transições */
+transition-colors      /* Cores suaves */
+```
+
+### data-slot
+
+```html
+<a data-slot="link" href="/page">...</a>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "muted" \| "subtle" \| "nav" \| "inline" \| "unstyled"` | `"default"` | Estilo visual do link |
+| `size` | `"xs" \| "sm" \| "default" \| "lg" \| "inherit"` | `"inherit"` | Tamanho da fonte |
+| `external` | `boolean` | `false` | Adiciona `target="_blank"` e `rel="noopener noreferrer"` |
+| `underline` | `"always" \| "hover" \| "none"` | `"hover"` | Comportamento do underline |
+| `asChild` | `boolean` | `false` | Renderiza children como elemento (polimorfismo) |
+| `className` | `string` | - | Classes CSS adicionais |
+| `disabled` | `boolean` | `false` | Desabilita o link visualmente |
+| `href` | `string` | - | URL de destino |
+| `children` | `ReactNode` | - | Conteúdo do link |
+| `ref` | `Ref<HTMLAnchorElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"a">`
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onClick` | `(event: MouseEvent) => void` | Disparado ao clicar |
+| `onFocus` | `(event: FocusEvent) => void` | Disparado ao receber foco |
+| `onBlur` | `(event: FocusEvent) => void` | Disparado ao perder foco |
+| `onKeyDown` | `(event: KeyboardEvent) => void` | Disparado ao pressionar tecla |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Variants exportadas
+const linkVariants = cva(/* ... */)
+
+// Props do componente
+type LinkProps = React.ComponentProps<"a"> &
+  VariantProps<typeof linkVariants> & {
+    asChild?: boolean
+    external?: boolean
+    underline?: "always" | "hover" | "none"
+  }
+
+// Tipos derivados úteis
+type LinkVariant = NonNullable<VariantProps<typeof linkVariants>["variant"]>
+type LinkSize = NonNullable<VariantProps<typeof linkVariants>["size"]>
+```
+
+### 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 | React Aria | Blueprint |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:----------:|:---------:|
+| **Componente Link dedicado** | * | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Variantes** | 6 | - | - | 2 | 4 | 4 | 2 | 4 | - | - | 4 | 3 | - | 2 |
+| **CVA/cva** | ✓ | - | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **asChild/Slot** | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ | - | - | - | - |
+| **external** | ✓ | - | - | ✓ | - | - | - | ✓ | - | - | ✓ | - | - | - |
+| **underline control** | ✓ | - | - | - | ✓ | ✓ | - | ✓ | - | - | - | - | - | - |
+| **isDisabled** | ✓ | - | - | - | - | - | - | ✓ | - | ✓ | ✓ | - | ✓ | - |
+| **Router integration** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - | - |
+| **Ícone externo auto** | * | - | - | ✓ | - | - | - | ✓ | - | - | ✓ | ✓ | - | - |
+| **visited state** | * | - | - | - | - | - | - | - | - | - | - | - | - | - |
+| **overlay (card links)** | - | - | - | ✓ | - | - | - | ✓ | - | - | - | - | - | - |
+
+**Legenda:** ✓ = Suportado | * = Planejado ETUS | - = Não suportado
+
+#### Comparativo de Variantes por Design System
+
+| Design System | Variantes Disponíveis |
+|---------------|----------------------|
+| **ETUS** | `default`, `muted`, `subtle`, `nav`, `inline`, `unstyled` |
+| **Chakra UI** | Não tem variantes, usa `colorScheme` + `isExternal` |
+| **MUI** | `inherit`, `primary`, `secondary`, `error` (via color prop) |
+| **Mantine** | `default`, `dimmed`, `gradient`, `unstyled` |
+| **Ant Design** | Tipo implícito: normal, disabled, danger |
+| **NextUI** | `foreground`, `primary`, `secondary`, `success`, `warning`, `danger` |
+| **Fluent UI** | `default`, `subtle`, `inline` |
+| **Carbon** | `default`, `inline`, `visited` |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | React Aria |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:----------:|
+| `variant` | ✓ | - | `color` | ✓ | - | `color` | ✓ | - | - |
+| `size` | ✓ | - | - | `size` | - | `size` | `size` | - | - |
+| `external`/`isExternal` | ✓ | ✓ | - | - | - | ✓ | - | - | - |
+| `underline` | ✓ | - | ✓ | ✓ | ✓ | `underline` | - | - | - |
+| `disabled` | ✓ | - | - | - | `disabled` | `isDisabled` | `disabled` | - | `isDisabled` |
+| `showAnchorIcon` | * | - | - | - | - | ✓ | - | - | - |
+| `isBlock` | - | - | - | - | - | ✓ | - | - | - |
+| `overlay` | - | ✓ | - | - | - | - | - | - | - |
+| `href` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `as`/`asChild` | ✓ | `as` | `component` | `component` | - | `as` | `as` | - | - |
+
+#### Abordagens de Link por Categoria
+
+**Componente Dedicado (recomendado):**
+- **Chakra UI** - `Link` + `LinkOverlay` para cards
+- **MUI** - `Link` com integração `react-router-dom`
+- **Mantine** - `Anchor` com `underline` e `gradient`
+- **NextUI** - `Link` com ícone externo automático
+
+**Via Button Variant:**
+- **Shadcn/ui** - Usa `Button variant="link"` apenas
+- **Radix UI** - Não tem Link, usa Slot
+- **Headless UI** - Não tem Link dedicado
+
+**Enterprise/Completo:**
+- **Fluent UI** - `Link` com `inline` e `subtle` variants
+- **Carbon** - `Link` com foco em inline text
+- **Blueprint** - Link básico, foco em dados
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `aria-current="page"` | Indica página atual em navegação |
+| `aria-disabled` | Quando `disabled={true}` |
+| `aria-label` | Para links com ícone apenas |
+| `aria-describedby` | Informação adicional sobre o destino |
+| `role="link"` | Apenas se usar elemento não-semântico |
+
+### Atributos de Segurança
+
+| Atributo | Uso |
+|----------|-----|
+| `rel="noopener"` | Sempre em links externos (previne tab-napping) |
+| `rel="noreferrer"` | Opcional, previne leak de referrer |
+| `target="_blank"` | Abre em nova aba |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `Tab` | Move foco para/do link |
+| `Enter` | Ativa o link |
+| `Shift + Tab` | Move foco para elemento anterior |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegação por teclado
+focus-visible:outline-none
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+focus-visible:ring-offset-2
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1):
+
+| Variante | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| default | `--primary` | qualquer | >= 4.5:1 |
+| muted | `--muted-foreground` | qualquer | >= 4.5:1 |
+| subtle | `--foreground` | qualquer | >= 4.5:1 |
+
+### Screen Readers
+
+- Texto do link deve ser descritivo (evitar "clique aqui")
+- Usar `aria-label` para contexto adicional quando necessário
+- Anunciar quando link abre em nova aba
+- Links externos devem indicar que saem do site
+
+### Indicação de Link Externo
+
+```tsx
+// Anunciar para screen readers
+<Link external href="https://external.com">
+  Documentação
+  <span className="sr-only">(abre em nova aba)</span>
+  <ExternalLinkIcon aria-hidden="true" />
+</Link>
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|:---------:|
+| **ARIA automático** | * | ✓ | - | ✓ | - | ~ | ~ | ~ | ~ | ✓ | ✓ | ✓ | ~ |
+| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **External announcement** | * | ✓ | - | - | - | ✓ | - | - | - | ✓ | ✓ | ✓ | - |
+| **aria-current support** | * | ✓ | - | ✓ | - | - | - | - | - | - | ✓ | ✓ | - |
+| **Disabled state a11y** | * | ✓ | - | ✓ | - | - | - | - | - | ✓ | ✓ | - | - |
+| **RTL support** | - | ✓ | - | - | - | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | - |
+| **High contrast** | - | ✓ | - | - | - | - | - | - | - | - | ✓ | ✓ | - |
+
+**Legenda:** ✓ = Suporte completo | * = Planejado | ~ = Parcial/Manual | - = Não suportado
+
+#### Abordagens de Acessibilidade
+
+| Design System | Abordagem | Nível WCAG | Notas |
+|---------------|-----------|------------|-------|
+| **React Aria** | Hooks comportamentais | AAA | `useLink` hook, foco em a11y |
+| **Ariakit** | Hooks + componentes | AA | Flexível, boa documentação |
+| **Fluent UI** | Built-in | AAA | Microsoft a11y guidelines |
+| **Carbon** | Built-in | AA | IBM Equal Access Toolkit |
+| **NextUI** | Baseado em React Aria | AA | Herda de React Aria |
+| **Chakra UI** | Semi-automático | AA | `isExternal` adiciona ícone |
+| **ETUS** | Manual/Planejado | AA | Baseado em melhores práticas |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Link } from "@etus/ui"
+
+function Example() {
+  return <Link href="/about">Sobre nós</Link>
+}
+```
+
+### Variantes
+
+```tsx
+<Link variant="default" href="/home">Default</Link>
+<Link variant="muted" href="/terms">Termos de Uso</Link>
+<Link variant="subtle" href="/help">Ajuda</Link>
+<Link variant="nav" href="/dashboard">Dashboard</Link>
+<Link variant="inline" href="/docs">documentação</Link>
+<Link variant="unstyled" href="/custom">Custom</Link>
+```
+
+### Link Externo
+
+```tsx
+import { ExternalLink } from "lucide-react"
+
+// Prop external adiciona target="_blank" e rel automaticamente
+<Link external href="https://github.com/org/repo">
+  GitHub
+  <ExternalLink className="ml-1 size-3" />
+</Link>
+
+// Equivalente manual
+<Link
+  href="https://external.com"
+  target="_blank"
+  rel="noopener noreferrer"
+>
+  External
+</Link>
+```
+
+### Controle de Underline
+
+```tsx
+// Underline apenas no hover (padrão)
+<Link underline="hover" href="/page">Hover para underline</Link>
+
+// Underline sempre visível
+<Link underline="always" href="/page">Sempre sublinhado</Link>
+
+// Sem underline
+<Link underline="none" href="/page">Sem underline</Link>
+```
+
+### Tamanhos
+
+```tsx
+<Link size="xs" href="/footnote">Nota de rodapé</Link>
+<Link size="sm" href="/small">Pequeno</Link>
+<Link size="default" href="/normal">Normal</Link>
+<Link size="lg" href="/large">Grande</Link>
+<Link size="inherit" href="/inherit">Herda do contexto</Link>
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { Link as RouterLink } from "@tanstack/react-router"
+
+// Renderiza como React Router Link mantendo estilos
+<Link asChild>
+  <RouterLink to="/dashboard">Go to Dashboard</RouterLink>
+</Link>
+
+// Com Next.js Link
+import NextLink from "next/link"
+
+<Link asChild variant="nav">
+  <NextLink href="/products">Products</NextLink>
+</Link>
+```
+
+### Link Inline em Texto
+
+```tsx
+<p className="text-muted-foreground">
+  Ao continuar, você concorda com nossos{" "}
+  <Link variant="inline" href="/terms">Termos de Serviço</Link>
+  {" "}e{" "}
+  <Link variant="inline" href="/privacy">Política de Privacidade</Link>.
+</p>
+```
+
+### Link em Navegação
+
+```tsx
+import { useLocation } from "@tanstack/react-router"
+
+function NavLink({ href, children }) {
+  const location = useLocation()
+  const isCurrent = location.pathname === href
+
+  return (
+    <Link
+      variant="nav"
+      href={href}
+      aria-current={isCurrent ? "page" : undefined}
+      className={cn(isCurrent && "text-primary font-medium")}
+    >
+      {children}
+    </Link>
+  )
+}
+
+// Uso
+<nav>
+  <NavLink href="/">Home</NavLink>
+  <NavLink href="/about">About</NavLink>
+  <NavLink href="/contact">Contact</NavLink>
+</nav>
+```
+
+### Com Ícones
+
+```tsx
+import { ArrowRight, ExternalLink, Download } from "lucide-react"
+
+// Ícone à direita
+<Link href="/next">
+  Próximo
+  <ArrowRight className="ml-1 size-4" />
+</Link>
+
+// Link de download
+<Link href="/file.pdf" download>
+  <Download className="mr-1 size-4" />
+  Baixar PDF
+</Link>
+```
+
+### Link Desabilitado
+
+```tsx
+// Link visualmente desabilitado
+<Link href="/premium" disabled>
+  Recurso Premium
+</Link>
+
+// Com aria-disabled
+<Link
+  href="/locked"
+  aria-disabled="true"
+  className="pointer-events-none opacity-50"
+  tabIndex={-1}
+>
+  Bloqueado
+</Link>
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo via className
+<Link className="text-sm md:text-base lg:text-lg" href="/responsive">
+  Texto Responsivo
+</Link>
+
+// Esconder em mobile, mostrar em desktop
+<Link className="hidden md:inline" href="/desktop-only">
+  Apenas Desktop
+</Link>
+```
+
+### Composição com Card
+
+```tsx
+function CardWithLink() {
+  return (
+    <article className="relative rounded-lg border p-4">
+      <h2 className="font-semibold">Título do Card</h2>
+      <p className="text-muted-foreground">Descrição...</p>
+
+      {/* Link que cobre todo o card */}
+      <Link
+        href="/article/1"
+        className="absolute inset-0"
+        aria-label="Ler artigo completo"
+      >
+        <span className="sr-only">Ler mais</span>
+      </Link>
+    </article>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Link.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { Link } from "./Link"
+
+describe("Link", () => {
+  it("renders children correctly", () => {
+    render(<Link href="/test">Click me</Link>)
+    expect(screen.getByRole("link", { name: "Click me" })).toBeInTheDocument()
+  })
+
+  it("applies variant classes", () => {
+    render(<Link variant="muted" href="/test">Muted</Link>)
+    expect(screen.getByRole("link")).toHaveClass("text-muted-foreground")
+  })
+
+  it("applies size classes", () => {
+    render(<Link size="lg" href="/test">Large</Link>)
+    expect(screen.getByRole("link")).toHaveClass("text-lg")
+  })
+
+  it("merges custom className", () => {
+    render(<Link className="custom-class" href="/test">Test</Link>)
+    expect(screen.getByRole("link")).toHaveClass("custom-class")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Link href="/test">Test</Link>)
+    expect(screen.getByRole("link")).toHaveAttribute("data-slot", "link")
+  })
+
+  it("has correct href attribute", () => {
+    render(<Link href="/destination">Go</Link>)
+    expect(screen.getByRole("link")).toHaveAttribute("href", "/destination")
+  })
+})
+```
+
+### Testes de Link Externo
+
+```tsx
+describe("Link external", () => {
+  it("adds target and rel for external links", () => {
+    render(<Link external href="https://external.com">External</Link>)
+    const link = screen.getByRole("link")
+
+    expect(link).toHaveAttribute("target", "_blank")
+    expect(link).toHaveAttribute("rel", expect.stringContaining("noopener"))
+    expect(link).toHaveAttribute("rel", expect.stringContaining("noreferrer"))
+  })
+
+  it("does not add target for internal links", () => {
+    render(<Link href="/internal">Internal</Link>)
+    expect(screen.getByRole("link")).not.toHaveAttribute("target")
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("Link interactions", () => {
+  it("calls onClick when clicked", async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn((e) => e.preventDefault())
+
+    render(<Link href="/test" onClick={handleClick}>Click</Link>)
+    await user.click(screen.getByRole("link"))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it("can be activated with keyboard", async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn((e) => e.preventDefault())
+
+    render(<Link href="/test" onClick={handleClick}>Click</Link>)
+    screen.getByRole("link").focus()
+    await user.keyboard("{Enter}")
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it("disabled link prevents navigation", async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn()
+
+    render(
+      <Link href="/test" disabled onClick={handleClick}>
+        Disabled
+      </Link>
+    )
+
+    await user.click(screen.getByRole("link"))
+    expect(handleClick).not.toHaveBeenCalled()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Link accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Link href="/test">Accessible</Link>)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("external link has accessibility attributes", async () => {
+    const { container } = render(
+      <Link external href="https://example.com">
+        External Link
+        <span className="sr-only">(abre em nova aba)</span>
+      </Link>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("is focusable", () => {
+    render(<Link href="/test">Focus me</Link>)
+    const link = screen.getByRole("link")
+    link.focus()
+    expect(link).toHaveFocus()
+  })
+
+  it("supports aria-current for current page", () => {
+    render(
+      <Link href="/current" aria-current="page">
+        Current Page
+      </Link>
+    )
+    expect(screen.getByRole("link")).toHaveAttribute("aria-current", "page")
+  })
+
+  it("disabled link is not focusable", () => {
+    render(
+      <Link href="/test" disabled tabIndex={-1}>
+        Disabled
+      </Link>
+    )
+    expect(screen.getByRole("link")).toHaveAttribute("tabIndex", "-1")
+  })
+})
+```
+
+### Testes de Composição (asChild)
+
+```tsx
+describe("Link asChild", () => {
+  it("renders as child element", () => {
+    const CustomLink = ({ href, ...props }: { href: string }) => (
+      <a href={href} data-custom="true" {...props} />
+    )
+
+    render(
+      <Link asChild>
+        <CustomLink href="/test">Custom Link</CustomLink>
+      </Link>
+    )
+
+    const link = screen.getByRole("link", { name: "Custom Link" })
+    expect(link).toBeInTheDocument()
+    expect(link).toHaveAttribute("href", "/test")
+    expect(link).toHaveAttribute("data-custom", "true")
+  })
+
+  it("forwards ref to child element", () => {
+    const ref = { current: null }
+
+    render(
+      <Link asChild ref={ref}>
+        <a href="/test">Link</a>
+      </Link>
+    )
+
+    expect(ref.current).toBeInstanceOf(HTMLAnchorElement)
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Link edge cases", () => {
+  it("handles hash links correctly", () => {
+    render(<Link href="#section">Go to section</Link>)
+    expect(screen.getByRole("link")).toHaveAttribute("href", "#section")
+  })
+
+  it("handles mailto links", () => {
+    render(<Link href="mailto:test@example.com">Email us</Link>)
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "mailto:test@example.com"
+    )
+  })
+
+  it("handles tel links", () => {
+    render(<Link href="tel:+5511999999999">Call us</Link>)
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "tel:+5511999999999"
+    )
+  })
+
+  it("handles download attribute", () => {
+    render(
+      <Link href="/file.pdf" download>
+        Download PDF
+      </Link>
+    )
+    expect(screen.getByRole("link")).toHaveAttribute("download")
+  })
+
+  it("works with empty href", () => {
+    render(<Link href="">Empty href</Link>)
+    expect(screen.getByRole("link")).toHaveAttribute("href", "")
+  })
+})
+```
+
+---
+
+## Implementação Proposta
+
+### Código do Componente
+
+```tsx
+// Link.tsx
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const linkVariants = cva(
+  "inline-flex items-center gap-1 transition-colors outline-none focus-visible:ring-ring/50 focus-visible:ring-[3px] focus-visible:ring-offset-2 aria-disabled:pointer-events-none aria-disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "text-primary hover:text-primary/80",
+        muted: "text-muted-foreground hover:text-foreground",
+        subtle: "text-foreground hover:text-primary",
+        nav: "text-foreground hover:text-primary font-medium",
+        inline: "text-primary underline underline-offset-4",
+        unstyled: "",
+      },
+      size: {
+        xs: "text-xs",
+        sm: "text-sm",
+        default: "text-base",
+        lg: "text-lg",
+        inherit: "",
+      },
+      underline: {
+        always: "underline underline-offset-4",
+        hover: "hover:underline underline-offset-4",
+        none: "no-underline",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "inherit",
+      underline: "hover",
+    },
+    compoundVariants: [
+      {
+        variant: "inline",
+        underline: "always",
+        className: "",
+      },
+      {
+        variant: "nav",
+        underline: "none",
+        className: "",
+      },
+    ],
+  }
+)
+
+interface LinkProps
+  extends React.ComponentProps<"a">,
+    VariantProps<typeof linkVariants> {
+  asChild?: boolean
+  external?: boolean
+  disabled?: boolean
+}
+
+function Link({
+  className,
+  variant,
+  size,
+  underline,
+  asChild = false,
+  external = false,
+  disabled = false,
+  ...props
+}: LinkProps) {
+  const Comp = asChild ? Slot : "a"
+
+  return (
+    <Comp
+      data-slot="link"
+      aria-disabled={disabled || undefined}
+      tabIndex={disabled ? -1 : undefined}
+      target={external ? "_blank" : undefined}
+      rel={external ? "noopener noreferrer" : undefined}
+      className={cn(linkVariants({ variant, size, underline }), className)}
+      {...props}
+    />
+  )
+}
+
+export { Link, linkVariants }
+export type { LinkProps }
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems:
+
+### Prioridade Alta
+
+#### Ícone Externo Automático
+
+```tsx
+// Proposta de API
+interface LinkProps {
+  external?: boolean
+  showExternalIcon?: boolean
+}
+
+// Uso
+<Link external showExternalIcon href="https://github.com">
+  GitHub
+</Link>
+// Renderiza automaticamente ícone de link externo
+```
+
+**Referências:** Chakra (`isExternal`), NextUI (`showAnchorIcon`), Fluent UI
+
+#### Router Integration
+
+```tsx
+// Integração nativa com routers populares
+<Link href="/page" prefetch>Dashboard</Link>
+
+// Detecção automática de rota ativa
+<Link href="/current" activeClassName="text-primary">
+  Current
+</Link>
+```
+
+**Referências:** NextUI, MUI, Mantine
+
+### Prioridade Média
+
+#### LinkOverlay para Cards
+
+```tsx
+// Card com link que cobre toda a área
+<LinkOverlay href="/article">
+  <Card>
+    <CardHeader>Título</CardHeader>
+    <CardContent>Conteúdo</CardContent>
+  </Card>
+</LinkOverlay>
+```
+
+**Referências:** Chakra UI (`LinkOverlay`), NextUI
+
+#### Visited State
+
+```tsx
+// Controle de estado visited
+<Link href="/page" showVisited>
+  Página visitada
+</Link>
+```
+
+### Prioridade Baixa
+
+#### Tooltip Automático
+
+```tsx
+// Tooltip com URL para links truncados
+<Link href="/very/long/url" showTooltip maxWidth={200}>
+  Link com texto muito longo...
+</Link>
+```
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `external` + ícone | Implementar | UX melhor, padrão comum |
+| Router integration | Implementar | Essencial para SPAs |
+| `LinkOverlay` | Avaliar | Útil para cards, pode ser separado |
+| `visited` | Evitar | Problemas de privacidade, css nativo |
+| `tooltip` | Evitar | Composição com Tooltip existente |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação Link | GitHub |
+|---------------|-------------------|--------|
+| **Chakra UI** | [Link](https://chakra-ui.com/docs/components/link) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Link](https://mui.com/material-ui/react-link/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Anchor](https://mantine.dev/core/anchor/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Typography.Link](https://ant.design/components/typography#typographylink) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Link](https://nextui.org/docs/components/link) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Fluent UI** | [Link](https://react.fluentui.dev/?path=/docs/components-link--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Link](https://carbondesignsystem.com/components/link/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **React Aria** | [useLink](https://react-spectrum.adobe.com/react-aria/useLink.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Ariakit** | [Link](https://ariakit.org/components/link) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Radix UI** | [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **Shadcn/ui** | Button variant="link" | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Blueprint** | [Text Links](https://blueprintjs.com/docs/#core/typography) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | - | [primefaces/primereact](https://github.com/primefaces/primereact) |
+| **Headless UI** | - | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Link Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)
+- [WCAG 2.1 - Link Purpose](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html)
+- [MDN - Anchor Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)
+- [HTML Spec - Links](https://html.spec.whatwg.org/multipage/links.html)
+
+### 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/)