# Text

**Maturity:** experimental

Render styled body, heading, caption, and label text with SwiftUI-grade typographic fidelity.

## Import

```tsx
import { Text } from "@liquidify/react/text"
```

## Props

- `as`: `As | undefined`; default ``"span"``. The rendered HTML element — polymorphic over the inline/block typographic set, so Text carries the right semantics (`<p>`, `<strong>`, `<code>`, …). Drives the {@link TextProps.ref} target type: `<Text as="p">` narrows `ref` to `Ref<HTMLParagraphElement>`, not a bare `Ref<HTMLElement>`.
- `children`: `ReactNode`. The content to render with the resolved typography.
- `className`: `string | undefined`. Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.
- `color`: `TextColor | undefined`; default ``"primary"``. Apple label-colour hierarchy — `"primary"` (default), `"secondary"`, `"tertiary"`, or `"quaternary"` (increasing de-emphasis) — or `"inherit"` to take the colour of the surrounding host. Theme-aware via `light-dark()`; the `-ic` increased-contrast variants apply automatically through the token cascade. Ignored when {@link TextProps.tint} is set. `"inherit"` is the seam for a Text nested inside a colour-bearing element (an accent picker trigger, a state-recoloured toggle-button label): it emits `data-color="inherit"` so the type inherits the host's colour instead of forcing a label-hierarchy colour (ADR-0028).
- `italic`: `boolean | undefined`; default ``false``. Italic styling (SwiftUI `.italic()`) — `font-style: italic` via `data-italic`.
- `lineHeight`: `TextLineHeight | undefined`. Line height — a named leading scale (the SwiftUI `.lineSpacing(_:)` analogue). Overrides the variant's baked line-height via `data-leading` → `--lq-line-height-*`. When omitted, the variant's own leading applies.
- `ref`: `Ref<HTMLElementFor<As>> | undefined`. Forwarded ref to the rendered element — its type is conditional on {@link TextProps.as} via {@link HTMLElementFor}: `HTMLSpanElement` by default, `HTMLParagraphElement` for `as="p"`, `HTMLPreElement` for `as="pre"`, `HTMLDivElement` for `as="div"`, and `HTMLElement` for the remaining inline tags (`b · strong · i · em · code · sup · sub`) — never a bare `Ref<HTMLElement>` (charter §4).
- `tint`: `"red" | "orange" | "yellow" | "green" | "mint" | "teal" | "cyan" | "blue" | "indigo" | "purple" | "pink" | "brown" | "gray" | undefined`. Optional system-colour text — the SwiftUI `.foregroundStyle(Color.<hue>)` analogue, drawn from the restricted thirteen-hue {@link LiquidColor} palette and resolved via the shared `[data-tint]` → `--lq-tint-current` map. When set, it overrides {@link TextProps.color}.
- `tracking`: `TextTracking | undefined`. Letter-spacing — a named tracking scale (the SwiftUI `.tracking(_:)` analogue). Overrides the variant's baked tracking via `data-tracking` → `--lq-letter-spacing-*`. When omitted, the variant's own tracking applies.
- `transform`: `TextTransform | undefined`. Text case — the SwiftUI `.textCase(_:)` analogue; CSS `text-transform` via `data-transform`. When omitted, the text renders as authored.
- `variant`: `TextStyle | undefined`; default ``"body"``. The Apple Dynamic Type style — the primary typographic axis (SwiftUI `Font.TextStyle`). Resolves size + line-height + letter-spacing together via the `data-variant` selector.
- `weight`: `TextWeight | undefined`. Font weight (SwiftUI `Font.Weight`), resolved to `--lq-font-weight-*` via `data-weight`. When omitted, the weight baked into {@link TextProps.variant} applies (e.g. `headline` is semibold); an explicit value overrides it.
- `wrap`: `TextWrap | undefined`. Wrapping behaviour via `data-wrap`: `"nowrap"` (single line), `"balance"` / `"pretty"` (CSS `text-wrap`), or `"breakWord"` (break long unbreakable strings). When omitted, text wraps normally.

## SwiftUI mapping

- ``Font.TextStyle` / `.font(_:)`` → ``variant`` (direct): Charter §6 canonical — the primary typographic axis; KEEP.
- ``Font.Weight` / `.fontWeight(_:)`` → ``weight`` (direct): KEEP.
- ``.foregroundStyle(.secondary)` (hierarchical)` → ``color`` (direct): Idiomatic; KEEP (Phase 3 fixes only the exported `TextColor` type to include `inherit`, already emitted at runtime).
- ``.foregroundStyle(Color.<hue>)`` → ``tint`` (direct): Catalog-consistent system-hue name; KEEP.
- ``.italic()`` → ``italic`` (direct): KEEP.
- ``.lineSpacing(_:)`` → ``lineHeight`` (direct): Kept as the idiomatic React/CSS name — SwiftUI `.lineSpacing` is additive point spacing, semantically distinct; `lineHeight` is more truthful to the CSS mechanic. KEEP.
- ``.tracking(_:)`` → ``tracking`` (direct): `tracking` IS Apple's term; KEEP.
- ``.textCase(_:)`` → ``transform`` (renamed): Deliberately NOT renamed to `textCase`: the value set (`uppercase|lowercase|capitalize`) is broader than SwiftUI's two-value `.textCase`, so no clean 1:1 mapping exists; `transform` maps to the CSS `text-transform` mechanic it drives. KEEP.
- ``.lineLimit` / `.truncationMode`` → ``wrap`` (direct): No clean SwiftUI noun; kept as the CSS `text-wrap` idiom. KEEP.
- `*(no analogue — web-only)*` → ``as`` (web-only): Element polymorphism; idiomatic React. KEEP.
- `*(no analogue — web-only)*` → ``children` / `className`` (web-only): KEEP.