@etus/ui 0.1.0

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

@@ -0,0 +1,849 @@
+# Text
+
+## Visão Geral
+
+O **Text** é o componente fundamental de tipografia do Design System ETUS, usado para renderizar texto semântico com estilos consistentes. Como elemento atômico, serve de base para composições como `Heading`, `Paragraph`, `Label` e `Caption`.
+
+### Casos de Uso
+
+- Renderização de texto em interfaces
+- Títulos e subtítulos (h1-h6)
+- Parágrafos e corpo de texto
+- Labels de formulários
+- Textos de ajuda e descrições
+- Captions e textos secundários
+- Texto enfatizado ou destacado
+
+### Classificação
+
+**Categoria:** Atom (Primitive)
+**Dependências:** `@radix-ui/react-slot`, `class-variance-authority`
+**Status:** Placeholder - Implementação Pendente
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `body` | Texto padrão de corpo | `text-base`, `text-foreground` |
+| `lead` | Texto introdutório destacado | `text-xl`, `text-muted-foreground` |
+| `large` | Texto grande | `text-lg`, `font-semibold` |
+| `small` | Texto pequeno | `text-sm`, `text-muted-foreground` |
+| `muted` | Texto secundário/desabilitado | `text-sm`, `text-muted-foreground` |
+| `code` | Código inline | `font-mono`, `bg-muted`, `rounded` |
+
+### Tamanhos (`size`)
+
+| Tamanho | Classe | Line Height | Uso |
+|---------|--------|-------------|-----|
+| `xs` | `text-xs` (12px) | 1rem | Captions, footnotes |
+| `sm` | `text-sm` (14px) | 1.25rem | Labels, texto secundário |
+| `base` | `text-base` (16px) | 1.5rem | Corpo de texto padrão |
+| `lg` | `text-lg` (18px) | 1.75rem | Texto destacado |
+| `xl` | `text-xl` (20px) | 1.75rem | Subtítulos |
+| `2xl` | `text-2xl` (24px) | 2rem | Títulos pequenos |
+| `3xl` | `text-3xl` (30px) | 2.25rem | Títulos médios |
+| `4xl` | `text-4xl` (36px) | 2.5rem | Títulos grandes |
+
+### Pesos (`weight`)
+
+| Peso | Classe | Uso |
+|------|--------|-----|
+| `normal` | `font-normal` (400) | Texto regular |
+| `medium` | `font-medium` (500) | Leve ênfase |
+| `semibold` | `font-semibold` (600) | Títulos, labels |
+| `bold` | `font-bold` (700) | Forte ênfase |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparência base |
+| Muted | `text-muted-foreground` | Cor reduzida |
+| Disabled | `opacity-50` | 50% opacidade |
+| Truncate | `truncate` | Texto cortado com ellipsis |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--foreground         /* Cor principal do texto */
+--muted-foreground   /* Cor secundária */
+--primary            /* Texto de destaque */
+--destructive        /* Texto de erro */
+
+/* Tipografia */
+--font-sans          /* Inter, system-ui */
+--font-serif         /* Fonte serifada */
+--font-mono          /* Space Mono, monospace */
+
+/* Espaçamento */
+leading-none         /* line-height: 1 */
+leading-tight        /* line-height: 1.25 */
+leading-normal       /* line-height: 1.5 */
+leading-relaxed      /* line-height: 1.625 */
+
+/* Tracking */
+tracking-tight       /* letter-spacing: -0.025em */
+tracking-normal      /* letter-spacing: 0 */
+tracking-wide        /* letter-spacing: 0.025em */
+```
+
+### data-slot
+
+```html
+<span data-slot="text">...</span>
+<p data-slot="text">...</p>
+<h1 data-slot="text">...</h1>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"body" \| "lead" \| "large" \| "small" \| "muted" \| "code"` | `"body"` | Estilo visual do texto |
+| `size` | `"xs" \| "sm" \| "base" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl"` | - | Tamanho do texto |
+| `weight` | `"normal" \| "medium" \| "semibold" \| "bold"` | - | Peso da fonte |
+| `as` | `"span" \| "p" \| "div" \| "label" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"span"` | Elemento HTML a renderizar |
+| `asChild` | `boolean` | `false` | Renderiza children como elemento (polimorfismo) |
+| `truncate` | `boolean` | `false` | Trunca texto com ellipsis |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo do texto |
+| `ref` | `Ref<HTMLElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props do elemento HTML correspondente
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onClick` | `(event: MouseEvent) => void` | Disparado ao clicar |
+| `onCopy` | `(event: ClipboardEvent) => void` | Disparado ao copiar texto |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Variants exportadas
+const textVariants = cva(/* ... */)
+
+// Props do componente
+type TextElement = "span" | "p" | "div" | "label" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6"
+
+type TextProps<T extends TextElement = "span"> =
+  React.ComponentProps<T> &
+  VariantProps<typeof textVariants> & {
+    as?: T
+    asChild?: boolean
+    truncate?: boolean
+  }
+
+// Tipos derivados úteis
+type TextVariant = NonNullable<VariantProps<typeof textVariants>["variant"]>
+type TextSize = NonNullable<VariantProps<typeof textVariants>["size"]>
+type TextWeight = NonNullable<VariantProps<typeof textVariants>["weight"]>
+```
+
+### 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 | Spectrum | Park UI |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:--------:|:-------:|
+| **Componente Text** | * | - | - | ✓ | ✓ | ✓ | ✓ | - | - | - | ✓ | - | ✓ | ✓ |
+| **Variantes** | 6 | - | - | 6 | 9 | 5 | - | - | - | - | 10 | - | 7 | 6 |
+| **Tamanhos** | 8 | - | - | 6 | 14 | 7 | - | - | - | - | 12 | - | 6 | 7 |
+| **CVA/cva** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | ✓ |
+| **asChild/Slot** | ✓ | - | ✓ | - | - | - | - | - | - | ✓ | - | - | - | ✓ |
+| **as prop** | ✓ | - | - | ✓ | ✓ | ✓ | - | - | - | - | ✓ | - | ✓ | ✓ |
+| **truncate** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | - | - | - | ✓ | - | ✓ | ✓ |
+| **gradient** | - | - | - | ✓ | - | ✓ | - | - | - | - | - | - | - | - |
+| **data-slot** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | ✓ |
+
+**Legenda:** ✓ = Suportado | - = Não suportado | * = Placeholder
+
+#### Comparativo de Variantes por Design System
+
+| Design System | Variantes Disponíveis |
+|---------------|----------------------|
+| **ETUS** | `body`, `lead`, `large`, `small`, `muted`, `code` |
+| **Chakra UI** | Baseado em `textStyle` + `fontSize` + `fontWeight` |
+| **MUI** | `body1`, `body2`, `caption`, `overline`, `inherit` + headings |
+| **Mantine** | `gradient`, `dimmed`, `inherit` + size-based |
+| **Fluent UI** | `body1`, `body2`, `caption1`, `caption2`, `subtitle1`, `subtitle2`, `title1-3`, `headline`, `display`, `largeTitle` |
+| **React Spectrum** | Sem variantes - usa props individuais |
+| **Park UI** | `heading`, `body`, `label`, `caption`, `code` |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | Fluent | Spectrum | Park UI |
+|------|:----:|:------:|:---:|:-------:|:------:|:--------:|:-------:|
+| `variant` | ✓ | `textStyle` | ✓ | ✓ | ✓ | - | ✓ |
+| `size` | ✓ | `fontSize` | - | ✓ | - | `size` | ✓ |
+| `weight` | ✓ | `fontWeight` | - | ✓ | `weight` | `weight` | ✓ |
+| `as` | ✓ | ✓ | `component` | `component` | `as` | `elementType` | ✓ |
+| `truncate` | ✓ | `noOfLines` | `noWrap` | `truncate` | `truncate` | - | ✓ |
+| `align` | - | `textAlign` | `align` | `ta` | `align` | - | ✓ |
+| `color` | - | `color` | `color` | `c` | - | `color` | ✓ |
+| `lineClamp` | - | `noOfLines` | - | `lineClamp` | - | - | - |
+| `gradient` | - | `bgGradient` | - | `gradient` | - | - | - |
+| `italic` | - | `fontStyle` | - | `fs` | `italic` | - | - |
+| `underline` | - | `textDecoration` | - | `td` | `underline` | - | - |
+| `strikethrough` | - | `textDecoration` | - | `td` | `strikethrough` | - | - |
+
+#### Análise por Categoria
+
+**Sem Componente Text Dedicado:**
+- **Shadcn/ui** - Usa classes Tailwind diretamente
+- **Radix UI** - Apenas primitivos, sem tipografia
+- **NextUI** - Tipografia via Tailwind
+- **Headless UI** - Renderless, sem estilos
+- **Ariakit** - Apenas comportamento
+- **Carbon** - Usa `BodyShort`, `BodyLong`, `Label` separados
+
+**Text como Wrapper de Tipografia:**
+- **Chakra UI** - `Text` com style props
+- **MUI** - `Typography` completo
+- **Mantine** - `Text` + `Title` separados
+- **Fluent UI** - `Text` + variantes
+- **React Spectrum** - `Text` para semântica
+
+**Abordagem Moderna (CVA):**
+- **ETUS** - CVA + Tailwind + polimorfismo
+- **Park UI** - CVA + Tailwind, muito similar
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role` | Automático baseado no elemento (`heading`, etc.) |
+| `aria-level` | Para headings (1-6) |
+| `aria-hidden` | Quando texto é decorativo |
+| `aria-label` | Quando texto é truncado (tooltip) |
+| `lang` | Para texto em idioma diferente |
+
+### Semântica HTML
+
+| Elemento | Uso Semântico |
+|----------|---------------|
+| `<p>` | Parágrafos de texto |
+| `<span>` | Texto inline sem semântica |
+| `<h1>`-`<h6>` | Hierarquia de títulos |
+| `<label>` | Labels de formulários |
+| `<em>` | Ênfase |
+| `<strong>` | Forte importância |
+| `<code>` | Código inline |
+| `<mark>` | Texto destacado |
+| `<small>` | Texto de menor importância |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `Ctrl+C` / `Cmd+C` | Copiar texto selecionado |
+| `Tab` | Move foco (quando focusable) |
+
+### Legibilidade
+
+```tsx
+// Tamanho mínimo recomendado: 16px para corpo
+<Text size="base">Texto legível</Text>
+
+// Line-height adequado para leitura
+<Text className="leading-relaxed">Texto com espaçamento</Text>
+
+// Contraste mínimo 4.5:1 para texto normal
+<Text className="text-foreground">Alto contraste</Text>
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1 para texto normal, 3:1 para texto grande):
+
+| Variante | Cor | Background | Ratio |
+|----------|-----|------------|-------|
+| body | `--foreground` | `--background` | >= 7:1 |
+| muted | `--muted-foreground` | `--background` | >= 4.5:1 |
+| code | `--foreground` | `--muted` | >= 4.5:1 |
+
+### Screen Readers
+
+- Usar elementos semânticos apropriados (`<p>`, `<h1>`, etc.)
+- Evitar texto apenas visual (usar `aria-hidden` se necessário)
+- Fornecer contexto para texto truncado
+- Usar `lang` para texto em idiomas diferentes
+
+### Reduced Motion
+
+```css
+/* Animações de texto respeitam preferência */
+@media (prefers-reduced-motion: reduce) {
+  .text-animate {
+    animation: none;
+    transition: none;
+  }
+}
+```
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | Spectrum | Radix | Ariakit | Chakra | MUI | Mantine | AntD | Fluent | Carbon | Park UI |
+|---------|:----:|:--------:|:-----:|:-------:|:------:|:---:|:-------:|:----:|:------:|:------:|:-------:|
+| **Semântica automática** | ✓ | ✓ | - | - | ~ | ✓ | ~ | ~ | ✓ | ✓ | ✓ |
+| **Contraste validado** | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
+| **Truncate + tooltip** | ~ | ✓ | - | - | ✓ | ~ | ✓ | ~ | ✓ | - | ~ |
+| **RTL support** | - | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| **High contrast** | - | ✓ | - | - | - | - | - | - | ✓ | ✓ | - |
+| **Responsive text** | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | - | ✓ | - | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Text } from "@etus/ui"
+
+function Example() {
+  return <Text>Hello, World!</Text>
+}
+```
+
+### Variantes
+
+```tsx
+<Text variant="body">Texto de corpo padrão</Text>
+<Text variant="lead">Texto introdutório destacado</Text>
+<Text variant="large">Texto grande e bold</Text>
+<Text variant="small">Texto pequeno e secundário</Text>
+<Text variant="muted">Texto com cor reduzida</Text>
+<Text variant="code">console.log("code")</Text>
+```
+
+### Tamanhos
+
+```tsx
+<Text size="xs">Extra pequeno (12px)</Text>
+<Text size="sm">Pequeno (14px)</Text>
+<Text size="base">Base (16px)</Text>
+<Text size="lg">Grande (18px)</Text>
+<Text size="xl">Extra grande (20px)</Text>
+<Text size="2xl">2X grande (24px)</Text>
+<Text size="3xl">3X grande (30px)</Text>
+<Text size="4xl">4X grande (36px)</Text>
+```
+
+### Pesos
+
+```tsx
+<Text weight="normal">Peso normal (400)</Text>
+<Text weight="medium">Peso médio (500)</Text>
+<Text weight="semibold">Peso semibold (600)</Text>
+<Text weight="bold">Peso bold (700)</Text>
+```
+
+### Polimorfismo com `as`
+
+```tsx
+// Como parágrafo
+<Text as="p">
+  Este é um parágrafo completo de texto que pode conter
+  múltiplas linhas de conteúdo.
+</Text>
+
+// Como heading
+<Text as="h1" size="4xl" weight="bold">
+  Título Principal
+</Text>
+
+<Text as="h2" size="2xl" weight="semibold">
+  Subtítulo
+</Text>
+
+// Como label
+<Text as="label" size="sm" weight="medium">
+  Campo obrigatório
+</Text>
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { Link } from "@tanstack/react-router"
+
+// Renderiza como Link mantendo estilos do Text
+<Text asChild variant="body">
+  <Link to="/about">Saiba mais</Link>
+</Text>
+
+// Com elemento customizado
+<Text asChild variant="code">
+  <code>npm install @etus/ui</code>
+</Text>
+```
+
+### Truncamento
+
+```tsx
+// Truncar texto longo
+<Text truncate className="max-w-[200px]">
+  Este texto muito longo será truncado com ellipsis
+</Text>
+
+// Com line-clamp (múltiplas linhas)
+<Text className="line-clamp-2">
+  Este texto será truncado após duas linhas, mantendo
+  um preview do conteúdo para o usuário visualizar.
+</Text>
+```
+
+### Combinando Props
+
+```tsx
+// Texto de destaque
+<Text size="xl" weight="semibold" className="text-primary">
+  Promoção especial!
+</Text>
+
+// Caption de imagem
+<Text as="figcaption" size="sm" variant="muted">
+  Foto: Unsplash / John Doe
+</Text>
+
+// Texto de erro
+<Text size="sm" className="text-destructive">
+  Este campo é obrigatório
+</Text>
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo via className
+<Text className="text-sm md:text-base lg:text-lg">
+  Texto responsivo
+</Text>
+
+// Heading responsivo
+<Text as="h1" className="text-2xl md:text-3xl lg:text-4xl font-bold">
+  Título Responsivo
+</Text>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <Text className="@sm:text-lg @md:text-xl @lg:text-2xl">
+    Container Aware Text
+  </Text>
+</div>
+```
+
+### Composição com Ícones
+
+```tsx
+import { AlertCircle, CheckCircle } from "lucide-react"
+
+// Texto com ícone
+<Text className="flex items-center gap-2">
+  <CheckCircle className="size-4 text-green-500" />
+  Operação concluída com sucesso
+</Text>
+
+// Mensagem de erro
+<Text size="sm" className="flex items-center gap-1.5 text-destructive">
+  <AlertCircle className="size-3.5" />
+  Falha ao salvar alterações
+</Text>
+```
+
+### Rich Text / Composição
+
+```tsx
+<Text as="p" variant="body">
+  Você pode misturar <Text as="strong" weight="bold">texto em negrito</Text>,{" "}
+  <Text as="em" className="italic">texto itálico</Text>, e{" "}
+  <Text variant="code">código inline</Text> facilmente.
+</Text>
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Text.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Text } from "./Text"
+
+describe("Text", () => {
+  it("renders children correctly", () => {
+    render(<Text>Hello World</Text>)
+    expect(screen.getByText("Hello World")).toBeInTheDocument()
+  })
+
+  it("applies variant classes", () => {
+    render(<Text variant="muted">Muted text</Text>)
+    expect(screen.getByText("Muted text")).toHaveClass("text-muted-foreground")
+  })
+
+  it("applies size classes", () => {
+    render(<Text size="lg">Large text</Text>)
+    expect(screen.getByText("Large text")).toHaveClass("text-lg")
+  })
+
+  it("applies weight classes", () => {
+    render(<Text weight="bold">Bold text</Text>)
+    expect(screen.getByText("Bold text")).toHaveClass("font-bold")
+  })
+
+  it("renders as span by default", () => {
+    render(<Text>Default element</Text>)
+    expect(screen.getByText("Default element").tagName).toBe("SPAN")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Text>Test</Text>)
+    expect(screen.getByText("Test")).toHaveAttribute("data-slot", "text")
+  })
+
+  it("merges custom className", () => {
+    render(<Text className="custom-class">Test</Text>)
+    expect(screen.getByText("Test")).toHaveClass("custom-class")
+  })
+})
+```
+
+### Testes de Polimorfismo
+
+```tsx
+describe("Text polymorphism", () => {
+  it("renders as paragraph with as='p'", () => {
+    render(<Text as="p">Paragraph</Text>)
+    expect(screen.getByText("Paragraph").tagName).toBe("P")
+  })
+
+  it("renders as heading with as='h1'", () => {
+    render(<Text as="h1">Heading</Text>)
+    expect(screen.getByRole("heading", { level: 1 })).toBeInTheDocument()
+  })
+
+  it("renders as label with as='label'", () => {
+    render(<Text as="label" htmlFor="input">Label</Text>)
+    const label = screen.getByText("Label")
+    expect(label.tagName).toBe("LABEL")
+    expect(label).toHaveAttribute("for", "input")
+  })
+
+  it("renders child element with asChild", () => {
+    render(
+      <Text asChild>
+        <a href="/test">Link Text</a>
+      </Text>
+    )
+    const link = screen.getByRole("link", { name: "Link Text" })
+    expect(link).toBeInTheDocument()
+    expect(link).toHaveAttribute("href", "/test")
+  })
+
+  it("forwards ref correctly", () => {
+    const ref = { current: null }
+    render(<Text ref={ref}>Test</Text>)
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement)
+  })
+
+  it("forwards ref with as prop", () => {
+    const ref = { current: null }
+    render(<Text as="p" ref={ref}>Test</Text>)
+    expect(ref.current).toBeInstanceOf(HTMLParagraphElement)
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Text accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Text>Accessible text</Text>)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("heading has correct role", async () => {
+    render(<Text as="h2">Section Title</Text>)
+    expect(screen.getByRole("heading", { level: 2 })).toBeInTheDocument()
+  })
+
+  it("supports lang attribute for different languages", () => {
+    render(<Text lang="pt-BR">Texto em português</Text>)
+    expect(screen.getByText("Texto em português")).toHaveAttribute("lang", "pt-BR")
+  })
+
+  it("truncated text should have title for full content", () => {
+    const fullText = "This is a very long text that will be truncated"
+    render(
+      <Text truncate title={fullText} className="max-w-[100px]">
+        {fullText}
+      </Text>
+    )
+    expect(screen.getByText(fullText)).toHaveAttribute("title", fullText)
+  })
+})
+```
+
+### Testes de Truncamento
+
+```tsx
+describe("Text truncation", () => {
+  it("applies truncate class when truncate prop is true", () => {
+    render(<Text truncate>Long text</Text>)
+    expect(screen.getByText("Long text")).toHaveClass("truncate")
+  })
+
+  it("does not apply truncate class by default", () => {
+    render(<Text>Normal text</Text>)
+    expect(screen.getByText("Normal text")).not.toHaveClass("truncate")
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Text edge cases", () => {
+  it("handles empty children", () => {
+    const { container } = render(<Text></Text>)
+    expect(container.querySelector('[data-slot="text"]')).toBeInTheDocument()
+  })
+
+  it("handles complex children", () => {
+    render(
+      <Text>
+        <strong>Bold</strong> and <em>italic</em>
+      </Text>
+    )
+    expect(screen.getByText("Bold")).toBeInTheDocument()
+    expect(screen.getByText("italic")).toBeInTheDocument()
+  })
+
+  it("preserves whitespace correctly", () => {
+    render(<Text className="whitespace-pre">  Spaced  text  </Text>)
+    expect(screen.getByText(/Spaced.*text/)).toBeInTheDocument()
+  })
+
+  it("handles special characters", () => {
+    render(<Text>{"Price: R$ 1.999,00 <> &"}</Text>)
+    expect(screen.getByText(/Price: R\$ 1\.999,00/)).toBeInTheDocument()
+  })
+
+  it("combines multiple props correctly", () => {
+    render(
+      <Text
+        as="p"
+        variant="lead"
+        size="xl"
+        weight="semibold"
+        truncate
+        className="custom"
+      >
+        Combined
+      </Text>
+    )
+    const text = screen.getByText("Combined")
+    expect(text.tagName).toBe("P")
+    expect(text).toHaveClass("truncate", "custom")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+#### Implementação Base
+
+Criar o componente Text com API definida nesta documentação.
+
+```tsx
+// Proposta de implementação
+const textVariants = cva("", {
+  variants: {
+    variant: {
+      body: "text-base text-foreground",
+      lead: "text-xl text-muted-foreground",
+      large: "text-lg font-semibold",
+      small: "text-sm text-muted-foreground",
+      muted: "text-sm text-muted-foreground",
+      code: "relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm",
+    },
+    size: {
+      xs: "text-xs",
+      sm: "text-sm",
+      base: "text-base",
+      lg: "text-lg",
+      xl: "text-xl",
+      "2xl": "text-2xl",
+      "3xl": "text-3xl",
+      "4xl": "text-4xl",
+    },
+    weight: {
+      normal: "font-normal",
+      medium: "font-medium",
+      semibold: "font-semibold",
+      bold: "font-bold",
+    },
+  },
+  defaultVariants: {
+    variant: "body",
+  },
+})
+```
+
+**Referências:** Chakra (`Text`), MUI (`Typography`), Mantine (`Text`)
+
+### Prioridade Média
+
+#### `lineClamp`
+
+Limitar texto a número específico de linhas.
+
+```tsx
+// Proposta de API
+interface TextProps {
+  lineClamp?: 1 | 2 | 3 | 4 | 5 | 6
+}
+
+// Uso
+<Text lineClamp={2}>
+  Texto longo que será limitado a duas linhas
+  com ellipsis no final automaticamente.
+</Text>
+```
+
+**Referências:** Chakra (`noOfLines`), Mantine (`lineClamp`)
+
+#### `align`
+
+Alinhamento de texto.
+
+```tsx
+// Proposta de API
+interface TextProps {
+  align?: "left" | "center" | "right" | "justify"
+}
+
+// Uso
+<Text align="center">Texto centralizado</Text>
+```
+
+**Referências:** Chakra (`textAlign`), MUI (`align`), Mantine (`ta`)
+
+### Prioridade Baixa
+
+#### `gradient`
+
+Texto com gradiente.
+
+```tsx
+// Proposta de API
+interface TextProps {
+  gradient?: { from: string; to: string; deg?: number }
+}
+
+// Uso
+<Text gradient={{ from: "primary", to: "secondary", deg: 45 }}>
+  Texto Gradiente
+</Text>
+```
+
+**Referências:** Chakra (`bgGradient`), Mantine (`gradient`)
+
+#### `transform`
+
+Transformação de texto.
+
+```tsx
+// Proposta de API
+interface TextProps {
+  transform?: "uppercase" | "lowercase" | "capitalize" | "none"
+}
+
+// Uso
+<Text transform="uppercase">texto em maiúsculas</Text>
+```
+
+**Referências:** Chakra (`textTransform`), Mantine (`tt`)
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `lineClamp` | Implementar | Alta demanda, UX melhor que CSS manual |
+| `align` | Avaliar | `className="text-center"` funciona |
+| `gradient` | Evitar | Complexidade, uso raro |
+| `transform` | Evitar | Usar className |
+| `color` | Evitar | Usar className ou variante |
+| `italic`/`underline` | Evitar | Usar className ou `<em>` semântico |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Typography](https://ui.shadcn.com/docs/components/typography) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Chakra UI** | [Text](https://chakra-ui.com/docs/components/text) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Typography](https://mui.com/material-ui/react-typography/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Text](https://mantine.dev/core/text/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Typography](https://ant.design/components/typography) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **Fluent UI** | [Text](https://react.fluentui.dev/?path=/docs/components-text-text--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **React Spectrum** | [Text](https://react-spectrum.adobe.com/react-spectrum/Text.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Park UI** | [Text](https://park-ui.com/docs/components/text) | [cschroeter/park-ui](https://github.com/cschroeter/park-ui) |
+| **Radix UI** | [Slot](https://www.radix-ui.com/primitives/docs/utilities/slot) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **Carbon** | [Typography](https://carbondesignsystem.com/guidelines/typography/overview/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
+- [WCAG 2.1 - Text Alternatives](https://www.w3.org/WAI/WCAG21/Understanding/text-alternatives)
+- [WCAG 2.1 - Contrast Minimum](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum)
+- [MDN - Typography](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Fundamentals)
+- [HTML Spec - Text-level Semantics](https://html.spec.whatwg.org/multipage/text-level-semantics.html)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS Typography](https://tailwindcss.com/docs/font-size)
+- [Radix Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)
+- [Inter Font](https://rsms.me/inter/)
+- [Space Mono Font](https://fonts.google.com/specimen/Space+Mono)