Typography
One component renders every row of the type scale (h1–h6, body, long-form, UI, caption, code) through a single `variant`, plus an orthogonal semantic `tone`. The reading-vs-UI distinction (TYPOGRAPHY_PHILOSOPHY "Reading mode vs UI mode") is encoded in the…
Preview
Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.
Install
Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.
npx shadcn@latest add https://ds.interlace.tools/r/typography.jsonnpx shadcn@latest add @interlace/typographyBehavior
What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.
Measured contrast
packages/ui/__tests__/theme-contract-lock.test.ts ↗Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is destructive on background at 7.60:1 (harbor · light), against a floor of 3:1.
| Pair | interlacelight | interlacedark | harborlight | harbordark | Floor |
|---|---|---|---|---|---|
| destructive on backgrounddestructive tint on the page surface | 8.31:1 | 10.43:1 | 7.60:1 | 10.03:1 | 3.0:1SC 1.4.11 |
| muted-foreground on backgroundsecondary copy | 9.41:1 | 11.32:1 | 7.82:1 | 9.52:1 | 4.5:1SC 1.4.3 |
| destructive on carddestructive tint inside a card | 8.31:1 | 9.66:1 | 8.02:1 | 9.09:1 | 3.0:1SC 1.4.11 |
| muted-foreground on cardsecondary copy in a card | 9.41:1 | 10.48:1 | 8.25:1 | 8.64:1 | 4.5:1SC 1.4.3 |
| primary on backgroundprimary tint on the page surface | 8.80:1 | 11.79:1 | 8.39:1 | 10.03:1 | 3.0:1SC 1.4.11 |
| primary on cardprimary tint inside a card | 8.80:1 | 10.92:1 | 8.86:1 | 9.10:1 | 3.0:1SC 1.4.11 |
| foreground on backgroundbody copy | 19.65:1 | 16.97:1 | 17.74:1 | 16.19:1 | 4.5:1SC 1.4.3 |
Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.
Runtime contract
packages/ui/vitest.config.ts ↗Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.
- Render boundary
server componentRenders during SSR / RSC with no hydration cost. It can be imported from a server component without pulling the page into the client.
- Minimum viewport
none declaredNo width floor: it takes the width it is given. Its container owns the layout question.
- Coverage gate
100% × 4Inside the v8 gate: lines 100, statements 100, functions 100, branches 100. A threshold under 100 only records how much you stopped caring, so there isn't one.
History
This component is at v1.0.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.
No release note names this component yet. It shipped with the release above and has not changed since — see the full changelog for what moved elsewhere in the DS.
Import
2 named exports — pull the parts you need.
import { Typography, typographyVariants } from '@/components/ui/typography';Variants
Closed prop unions enforced by class-variance-authority. See Storybook's Variants story for the rendered matrix.
- variant
- h1
- h2
- h3
- h4
- h5
- h6
- bodydefault
- long
- ui
- ui-sm
- caption
- code
- tone
- defaultdefault
- foreground
- muted
- primary
- destructive
- align
- start
- center
- end
API reference
Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.
TypographyProps
Also accepts every <p> attribute. Plus the variant props listed above.
| Prop | Type | Description |
|---|---|---|
| as | React.ElementType | Override the rendered element. Defaults to the variant's natural tag (h1→`h1`, body→`p`, code→`code`). Use this to keep the document outline correct when the visual level differs from the semantic level. |
| lineClamp | 1 | 2 | 3 | 4 | 5 | 6 | Clamp to N lines with an ellipsis (single truncation contract). @default none |
| children | React.ReactNode | — |
Accessibility
Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.
What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.
- Focus + keyboard behaviour
- Native element semantics — no interaction layer to get wrong.
- Focus ring (WCAG 2.2 SC 2.4.13)
- Not focusable — no focus indicator required.
- Reduced motion
- No animation to gate.
- ARIA in the source
- None — semantics come from the element or the Base UI primitive rather than hand-written ARIA.
Examples
3 more states from the same story file.
R-rule compliance
Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.
| Rule | Concept | Where |
|---|---|---|
| R4 | Extends native el + VariantProps | `React.ComponentProps<'p'> & VariantProps<...>` |
| R6 | data-slot on the part | `data-slot="typography"` + data-variant/data-tone |
| R7 | className merged + ...rest + ref | `cn(typographyVariants(...), clamp, className)` + `{...props}` |
| R8 | No `isXxx`; enum if >2 | variant/tone/align are enums |
| R11 | One variable (size), ReactNode | `children: ReactNode`; one truncation contract (lineClamp) |
| R18 | Tailwind only | zero inline style; classes from cva + static clamp map |
| R19 | Tokens only | text-h1/text-body… from foundation --text-*; no raw px |
| R20 | AA contrast | tone maps to AA-cleared semantic text tokens |
| R25 | Server component | no hooks → no 'use client' (as-prop seam, like Section) |
Dependencies
- Base UI primitive
- Native / no Base UI dependency
- Lucide icons
- none
- NPM dependencies
class-variance-authority
- Registry dependencies
Source
The full implementation — components/ui/typography.tsx once installed.
import * as React from 'react';
// @interlace/typography v1.0.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/typography
// What changed since: https://ds.interlace.tools/c/typography#history
// Generated banner — keep it, the upgrade diff reads this version.
// Typography — the single text primitive for the whole type scale.
// Mirrors MUI <Typography> (variant + polymorphic element), adapted to the
// Interlace floor: cva over the foundation --text-* tokens (no inline style),
// the server-safe `as`-prop seam (like Section — NOT useRender, so it stays a
// server component), semantic `tone` colors. See TYPOGRAPHY_PHILOSOPHY.md.
/**
* @interlace/ui — Typography
*
* One component renders every row of the type scale (h1–h6, body, long-form,
* UI, caption, code) through a single `variant`, plus an orthogonal semantic
* `tone`. The reading-vs-UI distinction (TYPOGRAPHY_PHILOSOPHY "Reading mode vs
* UI mode") is encoded in the variant set, not a second axis (R11: one
…138 more lines…Registry JSON
The raw registry record — what the shadcn CLI fetches.