@etus/ui 0.1.0

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

@@ -0,0 +1,812 @@
+# Paragraph
+
+## Visão Geral
+
+O **Paragraph** é o componente fundamental de tipografia para texto corrido do Design System ETUS. Como elemento atômico de texto, serve para renderizar parágrafos semânticos com controle granular sobre tamanho, peso, cor e alinhamento.
+
+### Casos de Uso
+
+- Blocos de texto em páginas de conteúdo
+- Descrições em cards, dialogs e formulários
+- Texto introdutório em seções
+- Legendas e textos auxiliares
+- Corpo de artigos e documentação
+
+### Classificação
+
+**Categoria:** Atom (Primitive)
+**Dependências:** `@radix-ui/react-slot`, `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes de Tamanho (`size`)
+
+| Tamanho | Classes | Line Height | Uso |
+|---------|---------|-------------|-----|
+| `xs` | `text-xs` (12px) | 1.5 | Disclaimers, notas de rodapé |
+| `sm` | `text-sm` (14px) | 1.5 | Textos auxiliares, legendas |
+| `base` | `text-base` (16px) | 1.6 | Corpo de texto padrão |
+| `lg` | `text-lg` (18px) | 1.6 | Texto destacado, leads |
+| `xl` | `text-xl` (20px) | 1.5 | Introduções, destaques |
+
+### Variantes de Peso (`weight`)
+
+| Peso | Classes | Uso |
+|------|---------|-----|
+| `normal` | `font-normal` (400) | Texto corrido padrão |
+| `medium` | `font-medium` (500) | Ênfase leve |
+| `semibold` | `font-semibold` (600) | Ênfase moderada |
+| `bold` | `font-bold` (700) | Ênfase forte |
+
+### Variantes de Cor (`color`)
+
+| Cor | Token | Uso |
+|-----|-------|-----|
+| `default` | `text-foreground` | Texto principal |
+| `muted` | `text-muted-foreground` | Texto secundário |
+| `primary` | `text-primary` | Texto de destaque |
+| `destructive` | `text-destructive` | Alertas, erros |
+| `success` | `text-success` | Confirmações |
+
+### Variantes de Alinhamento (`align`)
+
+| Alinhamento | Classes | Uso |
+|-------------|---------|-----|
+| `left` | `text-left` | Padrão para LTR |
+| `center` | `text-center` | Textos centralizados |
+| `right` | `text-right` | Alinhamento especial |
+| `justify` | `text-justify` | Texto justificado |
+
+### Variantes de Espaçamento (`spacing`)
+
+| Espaçamento | Classes | Uso |
+|-------------|---------|-----|
+| `none` | `mb-0` | Sem margem inferior |
+| `tight` | `mb-2` | Espaçamento compacto |
+| `normal` | `mb-4` | Espaçamento padrão |
+| `relaxed` | `mb-6` | Espaçamento generoso |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--foreground          /* Texto padrão */
+--muted-foreground    /* Texto secundário */
+--primary             /* Texto destaque */
+--destructive         /* Texto erro */
+
+/* Tipografia */
+font-family: var(--font-sans)
+line-height: 1.5-1.6
+
+/* Espaçamento */
+letter-spacing: normal
+```
+
+### data-slot
+
+```html
+<p data-slot="paragraph">...</p>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `size` | `"xs" \| "sm" \| "base" \| "lg" \| "xl"` | `"base"` | Tamanho do texto |
+| `weight` | `"normal" \| "medium" \| "semibold" \| "bold"` | `"normal"` | Peso da fonte |
+| `color` | `"default" \| "muted" \| "primary" \| "destructive" \| "success"` | `"default"` | Cor do texto |
+| `align` | `"left" \| "center" \| "right" \| "justify"` | `"left"` | Alinhamento |
+| `spacing` | `"none" \| "tight" \| "normal" \| "relaxed"` | `"normal"` | Margem inferior |
+| `truncate` | `boolean` | `false` | Trunca texto com ellipsis |
+| `clamp` | `number` | - | Limita linhas visíveis (line-clamp) |
+| `asChild` | `boolean` | `false` | Renderiza children como elemento |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo do parágrafo |
+| `ref` | `Ref<HTMLParagraphElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"p">`
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Variants exportadas
+const paragraphVariants = cva(/* ... */)
+
+// Props do componente
+type ParagraphProps = React.ComponentProps<"p"> &
+  VariantProps<typeof paragraphVariants> & {
+    asChild?: boolean
+    clamp?: number
+  }
+
+// Tipos derivados
+type ParagraphSize = NonNullable<VariantProps<typeof paragraphVariants>["size"]>
+type ParagraphColor = NonNullable<VariantProps<typeof paragraphVariants>["color"]>
+```
+
+### 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 dedicado** | ✓ | - | - | Text | Typography | Text | Typography | - | - | - | Text | - | Text | Text |
+| **Tamanhos** | 5 | - | - | 9 | 6 | 7 | - | - | - | - | 9 | - | 6 | 7 |
+| **Pesos** | 4 | - | - | 9 | - | 9 | - | - | - | - | 6 | - | 3 | 6 |
+| **Cores semânticas** | 5 | - | - | + | - | + | - | - | - | - | + | - | + | + |
+| **CVA/cva** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | ✓ |
+| **asChild/Slot** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | ✓ |
+| **truncate** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | - | - | - | ✓ | - | ✓ | ✓ |
+| **line-clamp** | ✓ | - | - | ✓ | - | ✓ | ✓ | - | - | - | - | - | - | ✓ |
+| **align** | ✓ | - | - | ✓ | ✓ | ✓ | - | - | - | - | ✓ | - | - | ✓ |
+| **spacing/margin** | ✓ | - | - | - | ✓ | - | - | - | - | - | - | - | - | - |
+| **data-slot** | ✓ | - | - | - | - | - | - | - | - | - | - | - | - | - |
+
+**Legenda:** ✓ = Suportado | + = Via colorScheme/tokens | - = Não suportado
+
+#### Comparativo de Abordagens por Design System
+
+| Design System | Componente | Abordagem |
+|---------------|------------|-----------|
+| **ETUS** | `Paragraph` | CVA + Tailwind, semântico |
+| **Chakra UI** | `Text` | Style props, `as` polimórfico |
+| **MUI** | `Typography` | `variant` + `component` |
+| **Mantine** | `Text` | Props granulares, `component` |
+| **Fluent UI** | `Text` | Tokens + variants |
+| **Spectrum** | `Text` | Slots + T-shirt sizes |
+| **Park UI** | `Text` | CVA + Ark UI primitives |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | Fluent | Spectrum |
+|------|:----:|:------:|:---:|:-------:|:------:|:--------:|
+| `size` | ✓ | `fontSize` | `variant` | `size` | `size` | `size` |
+| `weight` | ✓ | `fontWeight` | - | `fw` | `weight` | - |
+| `color` | ✓ | `color` | `color` | `c` | - | - |
+| `align` | ✓ | `textAlign` | `align` | `ta` | `align` | - |
+| `truncate` | ✓ | `noOfLines` | `noWrap` | `truncate` | `truncate` | - |
+| `as`/`asChild` | ✓ | `as` | `component` | `component` | `as` | - |
+| `lineHeight` | via class | `lineHeight` | - | `lh` | - | - |
+
+---
+
+## Acessibilidade (A11y)
+
+### Semântica HTML
+
+- Usar `<p>` para parágrafos de texto corrido
+- Evitar `<p>` para conteúdo interativo ou estrutural
+- Não aninhar `<p>` dentro de outros `<p>` (HTML inválido)
+
+### Considerações de Leitura
+
+| Aspecto | Recomendação | Motivo |
+|---------|--------------|--------|
+| Comprimento de linha | 45-75 caracteres | Legibilidade ótima |
+| Line-height | 1.5-1.6 | Conforto de leitura |
+| Contraste | >= 4.5:1 (AA) | Visibilidade |
+| Tamanho mínimo | 16px | Acessibilidade mobile |
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1):
+
+| Variante | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| default | `--foreground` | `--background` | >= 7:1 |
+| muted | `--muted-foreground` | `--background` | >= 4.5:1 |
+| primary | `--primary` | `--background` | >= 4.5:1 |
+| destructive | `--destructive` | `--background` | >= 4.5:1 |
+
+### Screen Readers
+
+- Texto truncado deve ter `title` ou `aria-label` com texto completo
+- Usar `lang` attribute para texto em idiomas diferentes
+- Evitar texto justificado para usuários com dislexia
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Chakra | MUI | Mantine | Fluent | Carbon | Spectrum |
+|---------|:----:|:----------:|:-----:|:------:|:---:|:-------:|:------:|:------:|:--------:|
+| **Contraste AA** | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Contraste AAA** | - | ✓ | - | - | - | - | ✓ | ✓ | ✓ |
+| **RTL support** | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **lang attribute** | manual | auto | - | - | - | - | ✓ | - | ✓ |
+| **Reduced motion** | - | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **High contrast** | - | ✓ | - | - | - | - | ✓ | ✓ | ✓ |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Paragraph } from "@etus/ui"
+
+function Example() {
+  return (
+    <Paragraph>
+      Este é um parágrafo de texto simples com as configurações padrão.
+    </Paragraph>
+  )
+}
+```
+
+### Tamanhos
+
+```tsx
+<Paragraph size="xs">Extra pequeno - disclaimers</Paragraph>
+<Paragraph size="sm">Pequeno - legendas</Paragraph>
+<Paragraph size="base">Base - texto padrão</Paragraph>
+<Paragraph size="lg">Grande - leads</Paragraph>
+<Paragraph size="xl">Extra grande - destaques</Paragraph>
+```
+
+### Cores
+
+```tsx
+<Paragraph color="default">Texto principal</Paragraph>
+<Paragraph color="muted">Texto secundário</Paragraph>
+<Paragraph color="primary">Texto destacado</Paragraph>
+<Paragraph color="destructive">Texto de erro</Paragraph>
+<Paragraph color="success">Texto de sucesso</Paragraph>
+```
+
+### Pesos
+
+```tsx
+<Paragraph weight="normal">Peso normal (400)</Paragraph>
+<Paragraph weight="medium">Peso médio (500)</Paragraph>
+<Paragraph weight="semibold">Peso semi-bold (600)</Paragraph>
+<Paragraph weight="bold">Peso bold (700)</Paragraph>
+```
+
+### Alinhamento
+
+```tsx
+<Paragraph align="left">Alinhado à esquerda</Paragraph>
+<Paragraph align="center">Centralizado</Paragraph>
+<Paragraph align="right">Alinhado à direita</Paragraph>
+<Paragraph align="justify">
+  Texto justificado que ocupa toda a largura disponível do container,
+  distribuindo espaços entre palavras.
+</Paragraph>
+```
+
+### Truncamento
+
+```tsx
+// Truncar em uma linha
+<Paragraph truncate className="max-w-xs">
+  Este texto será truncado com ellipsis quando exceder a largura máxima definida.
+</Paragraph>
+
+// Line clamp (múltiplas linhas)
+<Paragraph clamp={3}>
+  Este texto será limitado a 3 linhas. Qualquer conteúdo que exceda
+  este limite será cortado e exibirá ellipsis no final da terceira linha.
+  Continue escrevendo para ver o efeito do line-clamp em ação.
+</Paragraph>
+```
+
+### Espaçamento
+
+```tsx
+<div>
+  <Paragraph spacing="none">Sem margem inferior</Paragraph>
+  <Paragraph spacing="tight">Espaçamento compacto (8px)</Paragraph>
+  <Paragraph spacing="normal">Espaçamento padrão (16px)</Paragraph>
+  <Paragraph spacing="relaxed">Espaçamento generoso (24px)</Paragraph>
+</div>
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { Link } from "@tanstack/react-router"
+
+// Renderiza como span
+<Paragraph asChild>
+  <span>Este é um span estilizado como parágrafo</span>
+</Paragraph>
+
+// Renderiza como div (quando precisa de conteúdo block)
+<Paragraph asChild size="lg" color="muted">
+  <div>
+    <strong>Nota:</strong> Conteúdo complexo aqui.
+  </div>
+</Paragraph>
+```
+
+### Composição com Card
+
+```tsx
+import { Card, Heading, Paragraph } from "@etus/ui"
+
+function ArticleCard() {
+  return (
+    <Card>
+      <Card.Header>
+        <Heading level={3}>Título do Artigo</Heading>
+      </Card.Header>
+      <Card.Content>
+        <Paragraph color="muted" size="sm">
+          Publicado em 22 de Dezembro, 2024
+        </Paragraph>
+        <Paragraph clamp={3}>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+          Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+          Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
+        </Paragraph>
+      </Card.Content>
+    </Card>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo via className
+<Paragraph className="text-sm md:text-base lg:text-lg">
+  Texto que cresce com a viewport
+</Paragraph>
+
+// Alinhamento responsivo
+<Paragraph className="text-center md:text-left">
+  Centralizado em mobile, esquerda em desktop
+</Paragraph>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <Paragraph className="@sm:text-base @md:text-lg text-sm">
+    Container Aware Text
+  </Paragraph>
+</div>
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Paragraph.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Paragraph } from "./Paragraph"
+
+describe("Paragraph", () => {
+  it("renders children correctly", () => {
+    render(<Paragraph>Hello World</Paragraph>)
+    expect(screen.getByText("Hello World")).toBeInTheDocument()
+  })
+
+  it("renders as p element by default", () => {
+    render(<Paragraph>Test</Paragraph>)
+    expect(screen.getByText("Test").tagName).toBe("P")
+  })
+
+  it("applies size classes", () => {
+    render(<Paragraph size="lg">Large text</Paragraph>)
+    expect(screen.getByText("Large text")).toHaveClass("text-lg")
+  })
+
+  it("applies color classes", () => {
+    render(<Paragraph color="muted">Muted text</Paragraph>)
+    expect(screen.getByText("Muted text")).toHaveClass("text-muted-foreground")
+  })
+
+  it("applies weight classes", () => {
+    render(<Paragraph weight="bold">Bold text</Paragraph>)
+    expect(screen.getByText("Bold text")).toHaveClass("font-bold")
+  })
+
+  it("applies align classes", () => {
+    render(<Paragraph align="center">Centered</Paragraph>)
+    expect(screen.getByText("Centered")).toHaveClass("text-center")
+  })
+
+  it("merges custom className", () => {
+    render(<Paragraph className="custom-class">Test</Paragraph>)
+    expect(screen.getByText("Test")).toHaveClass("custom-class")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Paragraph>Test</Paragraph>)
+    expect(screen.getByText("Test")).toHaveAttribute("data-slot", "paragraph")
+  })
+})
+```
+
+### Testes de Truncamento
+
+```tsx
+describe("Paragraph truncation", () => {
+  it("applies truncate class", () => {
+    render(<Paragraph truncate>Truncated text</Paragraph>)
+    expect(screen.getByText("Truncated text")).toHaveClass("truncate")
+  })
+
+  it("applies line-clamp class", () => {
+    render(<Paragraph clamp={3}>Clamped text</Paragraph>)
+    expect(screen.getByText("Clamped text")).toHaveClass("line-clamp-3")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Paragraph accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Paragraph>Accessible paragraph</Paragraph>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("meets color contrast requirements", async () => {
+    const { container } = render(
+      <div style={{ background: "white" }}>
+        <Paragraph color="default">High contrast text</Paragraph>
+        <Paragraph color="muted">Muted but readable</Paragraph>
+      </div>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
+```
+
+### Testes de Composição (asChild)
+
+```tsx
+describe("Paragraph asChild", () => {
+  it("renders as child element", () => {
+    render(
+      <Paragraph asChild>
+        <span data-testid="span">Span content</span>
+      </Paragraph>
+    )
+
+    const span = screen.getByTestId("span")
+    expect(span.tagName).toBe("SPAN")
+    expect(span).toHaveClass("text-base") // Mantém estilos
+  })
+
+  it("forwards ref to child element", () => {
+    const ref = { current: null }
+    render(
+      <Paragraph asChild ref={ref}>
+        <span>Content</span>
+      </Paragraph>
+    )
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement)
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("Paragraph edge cases", () => {
+  it("handles empty content gracefully", () => {
+    render(<Paragraph data-testid="empty" />)
+    expect(screen.getByTestId("empty")).toBeInTheDocument()
+  })
+
+  it("handles long text without breaking", () => {
+    const longText = "A".repeat(1000)
+    render(<Paragraph>{longText}</Paragraph>)
+    expect(screen.getByText(longText)).toBeInTheDocument()
+  })
+
+  it("preserves whitespace when needed", () => {
+    render(
+      <Paragraph className="whitespace-pre-wrap">
+        {"Line 1\nLine 2\nLine 3"}
+      </Paragraph>
+    )
+    expect(screen.getByText(/Line 1/)).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
+
+#### `leading` / `lineHeight`
+
+Controle granular de line-height além do padrão.
+
+```tsx
+// Proposta de API
+interface ParagraphProps {
+  leading?: "none" | "tight" | "snug" | "normal" | "relaxed" | "loose"
+}
+
+// Uso
+<Paragraph leading="relaxed">Texto com espaçamento de linha maior</Paragraph>
+```
+
+**Referências:** Mantine (`lh`), Chakra (`lineHeight`), Tailwind utilities
+
+#### `maxWidth` / `prose`
+
+Largura máxima para leitura otimizada (45-75 caracteres).
+
+```tsx
+// Proposta de API
+interface ParagraphProps {
+  prose?: boolean // Aplica max-width: 65ch
+  maxWidth?: "xs" | "sm" | "md" | "lg" | "xl" | "prose"
+}
+
+// Uso
+<Paragraph prose>Texto com largura ideal para leitura</Paragraph>
+```
+
+**Referências:** Tailwind Typography, CSS `ch` unit best practices
+
+### Prioridade Média
+
+#### `gradient`
+
+Suporte a texto com gradiente.
+
+```tsx
+// Proposta de API
+interface ParagraphProps {
+  gradient?: {
+    from: string
+    to: string
+    deg?: number
+  }
+}
+
+// Uso
+<Paragraph gradient={{ from: "primary", to: "secondary", deg: 45 }}>
+  Texto com gradiente
+</Paragraph>
+```
+
+**Referências:** Mantine (`gradient`), NextUI
+
+#### Melhorias de A11y
+
+```tsx
+// lang attribute automático para texto em outro idioma
+<Paragraph lang="en">English text</Paragraph>
+
+// Anúncio de texto truncado para screen readers
+<Paragraph truncate aria-label="Texto completo aqui...">
+  Texto truncado...
+</Paragraph>
+```
+
+**Referências:** React Aria, Fluent UI, Spectrum
+
+### Prioridade Baixa
+
+#### `firstLetter` / `dropCap`
+
+Letra capitular para início de artigos.
+
+```tsx
+// Proposta de API
+interface ParagraphProps {
+  dropCap?: boolean
+}
+
+// Uso
+<Paragraph dropCap>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+</Paragraph>
+```
+
+**Referências:** CSS `::first-letter`, editorial design patterns
+
+#### `selectable`
+
+Controle se o texto pode ser selecionado.
+
+```tsx
+// Proposta de API
+interface ParagraphProps {
+  selectable?: boolean
+}
+
+// Uso
+<Paragraph selectable={false}>Texto não selecionável</Paragraph>
+```
+
+**Referências:** Chakra (`userSelect`), CSS `user-select`
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `leading` | ✅ Implementar | Controle tipográfico essencial |
+| `prose`/`maxWidth` | ✅ Implementar | UX de leitura, acessibilidade |
+| `gradient` | ⚠️ Avaliar | Uso limitado, complexidade |
+| `dropCap` | ❌ Evitar | Nicho, CSS custom funciona |
+| `selectable` | ⚠️ Avaliar | `className` resolve |
+
+---
+
+## Implementação Proposta
+
+```tsx
+// Paragraph.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 paragraphVariants = cva(
+  "leading-relaxed",
+  {
+    variants: {
+      size: {
+        xs: "text-xs",
+        sm: "text-sm",
+        base: "text-base",
+        lg: "text-lg",
+        xl: "text-xl",
+      },
+      weight: {
+        normal: "font-normal",
+        medium: "font-medium",
+        semibold: "font-semibold",
+        bold: "font-bold",
+      },
+      color: {
+        default: "text-foreground",
+        muted: "text-muted-foreground",
+        primary: "text-primary",
+        destructive: "text-destructive",
+        success: "text-success",
+      },
+      align: {
+        left: "text-left",
+        center: "text-center",
+        right: "text-right",
+        justify: "text-justify",
+      },
+      spacing: {
+        none: "mb-0",
+        tight: "mb-2",
+        normal: "mb-4",
+        relaxed: "mb-6",
+      },
+    },
+    defaultVariants: {
+      size: "base",
+      weight: "normal",
+      color: "default",
+      align: "left",
+      spacing: "normal",
+    },
+  }
+)
+
+interface ParagraphProps
+  extends Omit<React.ComponentProps<"p">, "color">,
+    VariantProps<typeof paragraphVariants> {
+  /**
+   * Renderiza children como elemento (polimorfismo via Radix Slot)
+   * @default false
+   */
+  asChild?: boolean
+  /**
+   * Trunca texto em uma linha com ellipsis
+   * @default false
+   */
+  truncate?: boolean
+  /**
+   * Número de linhas para limitar (line-clamp)
+   */
+  clamp?: number
+}
+
+function Paragraph({
+  className,
+  size,
+  weight,
+  color,
+  align,
+  spacing,
+  truncate,
+  clamp,
+  asChild = false,
+  ref,
+  ...props
+}: ParagraphProps) {
+  const Comp = asChild ? Slot : "p"
+
+  return (
+    <Comp
+      ref={ref}
+      data-slot="paragraph"
+      className={cn(
+        paragraphVariants({
+          size,
+          weight,
+          color,
+          align,
+          spacing,
+        }),
+        truncate && "truncate",
+        clamp && `line-clamp-${clamp}`,
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Paragraph, paragraphVariants }
+export type { ParagraphProps }
+```
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Componente | Documentação |
+|---------------|------------|--------------|
+| **Shadcn/ui** | Typography (prose) | [Typography](https://ui.shadcn.com/docs/components/typography) |
+| **Chakra UI** | Text | [Text](https://chakra-ui.com/docs/components/text) |
+| **MUI** | Typography | [Typography](https://mui.com/material-ui/react-typography/) |
+| **Mantine** | Text | [Text](https://mantine.dev/core/text/) |
+| **Fluent UI** | Text | [Text](https://react.fluentui.dev/?path=/docs/components-text--default) |
+| **Carbon** | (inline styles) | [Typography](https://carbondesignsystem.com/guidelines/typography/overview/) |
+| **Spectrum** | Text | [Text](https://spectrum.adobe.com/page/text/) |
+| **Park UI** | Text | [Text](https://park-ui.com/react/docs/components/text) |
+| **Radix Themes** | Text | [Text](https://www.radix-ui.com/themes/docs/components/text) |
+| **NextUI** | (utility classes) | [Typography](https://nextui.org/docs/customization/typography) |
+| **Ant Design** | Typography.Paragraph | [Typography](https://ant.design/components/typography) |
+| **Ariakit** | - | Não possui componente dedicado |
+| **Headless UI** | - | Não possui componente dedicado |
+| **React Aria** | - | Não possui componente dedicado |
+
+### Especificações e Padrões
+
+- [MDN - The Paragraph element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p)
+- [WCAG 2.1 - Text Spacing](https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html)
+- [WCAG 2.1 - Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
+- [Web Typography Best Practices](https://www.smashingmagazine.com/2022/08/web-typography-basics/)
+
+### 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)