Skip to main content

Typography

Text that declares its place in the document: a heading level, body copy or a caption. Pick the variant for the structure, not for the size, and style the text some other way if it is not a heading.

Contract 1.2.0No kit page

Live preview

Rendered by the component itself from the same generated tokens as the rest of the site.

Variant

Weight

<Typography variant="heading-2">
  One source color becomes every ramp and role.
</Typography>

Installation

Install it with the shadcn CLI, along with everything it uses. New project? Set it up first, as Quick start shows.

npx shadcn@latest add https://www.graphite-ui.com/r/typography.json

import { Typography } from '@/components/ui/typography'

Anatomy

One slot, the text. The variant picks the element and the type step; the component sets no margin, so spacing stays with the layout around it.

Text content

Text contentRequired

Variants

Seven variants, each a real element. The headings sit on the kit’s title ladder, the UI scale; only display reaches into the editorial heading ladder. Weight is a separate prop.

Variant: Display (h1)

Variant: Heading 1 (h1)

Variant: Heading 2 (h2)

Variant: Heading 3 (h3)

Variant: Heading 4 (h4)

Variant: Body (p, default)

One source color becomes every ramp and role.

Variant: Caption (span)

One source color becomes every ramp and role.

Weight: Regular (default)

One source color becomes every ramp and role.

Weight: Medium

One source color becomes every ramp and role.

Weight: Semibold

One source color becomes every ramp and role.

Inverted, on a primary fill

One source color becomes every ramp and role.

API reference

Generated from the contract, versioned with it, and checked by drift-check. This table cannot describe props the component does not have.

Typography props
Prop	Type	Default	Notes
variant	'display' \| 'heading-1' \| 'heading-2' \| 'heading-3' \| 'heading-4' \| 'body' \| 'caption'	—
weight	—	—
inverted	boolean	false	Sets the text in the surface role for a surface-inverted context, such as text on a filled primary surface. The one color override this contract permits, and the only way to make it.

Design tokens

Every swatch is live. Change the source color in the header and this table repaints, because it reads the same roles the component does.

on-surfaceDefault text color.
surfaceExplicit color override permitted only for `surface`-inverted contexts (e.g. text on a filled primary surface).
textSize, line height and weight per variant, from the kit's Typography collection. Variants sit on the kit's title ladder (UI scale); only `display` uses the heading ladder.
fontFamily per variant — font-1 for display and headings 1-2, font-2 for headings 3-4, body and caption, matching the kit's own role split.

Usage

The contract's prohibitions, written as the choices you will actually face.

Do

Choose the heading level from the outline of the page: h2 under h1, h3 under h2.
Use body for paragraphs and caption for short supporting text beside something else.
Set spacing in the layout that composes the text. The component carries no margin on purpose.
Use inverted only for text on a filled primary surface. It is the one colour override the contract allows.

Don’t

Pick heading-3 because it looks the right size. The variant is a statement about structure.
Skip a level (h1 straight to h3). The component cannot see its neighbours, so this rule is yours to keep.
Use display for a second h1 on a page that already has one. It renders an h1 too.
Pass a colour through className to make text stand out. Use weight, or a different variant.

Accessibility

What the component does for you, and what it leaves to you.

Roles: Display and heading-1 render h1, heading-2 to heading-4 render h2 to h4, body renders p and caption renders span. Screen reader users navigate by those headings.
Structure: The no-skipped-levels rule is the page composer’s. The component renders what it is told and cannot check the outline.
Contrast: Text is on-surface, which is measured against the surface roles at the theme’s target, AA or AAA.
Inverted: Inverted text is surface, which is near-white in light themes and near-black in dark ones: the right direction against primary in both.
Resizing: Sizes are rem-based tokens, so they follow the reader’s browser font size. Body steps down one size below 672px, as the kit’s Mobile mode does.