A small type system on the theme's tokens. Heading separates the semantic level from the visual size, Text covers body copy in sizes, tones and weights, and Prose styles raw HTML or MDX with no plugin.
import { Code, Heading, Lead, Small, Text } from "@/components/ui/typography";export default function TypographyDemo() { return ( <article className="flex w-full max-w-xl flex-col gap-4"> <Small className="font-medium text-brand uppercase tracking-wider"> Engineering </Small> <Heading level={1}>Shipping a design system people actually use</Heading> <Lead> Components are the easy part. Adoption comes from docs, defaults and a migration path that respects the code teams already have. </Lead> <Text tone="subtle"> We started by auditing every button in the product and found 41 variations. Six months later there are three, all imported from{" "} <Code>@/components/ui/button</Code>, and nobody had to stop shipping to get there. </Text> <Small>Maya Chen · 6 min read · Updated March 12</Small> </article> );}
<Heading level={1}>Billing</Heading><Lead>Plans, invoices and payment methods for your workspace.</Lead><Text tone="muted">Changes apply at the start of the next billing cycle.</Text>
None of these are client components, so they render in server components with no JavaScript.
Heading — every title in an app screen or page. Pick level for the document outline and size for the look.
Text, Lead, Small, Code — body copy you write in JSX, where you want the scale and tones without repeating class strings.
Prose — content you don't write as JSX: MDX, Markdown rendered to HTML, CMS rich text, release notes from an API. It styles plain <h2>, <p>, <ul> and friends.
Inside components such as Card or Dialog, use their own title and description parts; they already follow this scale.
Body text runs xs 12/20, sm 14/24, md 16/28 (default) and lg 18/32. Headings are font-semibold with tighter tracking from md up; all sizes are standard Tailwind steps, so they follow your theme's --text-* values if you've changed them.
The outline and the look are separate decisions. A settings card might hold an h2 that should look small; a stat might be an h3 that should look huge. Set level for screen readers and the page outline, size for the eye. Don't skip levels to get a smaller heading.
import { Heading, Text } from "@/components/ui/typography";export default function TypographyLevels() { return ( <div className="grid w-full max-w-2xl gap-6 sm:grid-cols-2"> <section className="flex flex-col gap-2 rounded-xl border bg-card p-5"> {/* An h2 in the outline, sized for a compact card. */} <Heading level={2} size="sm"> Billing </Heading> <Text size="sm" tone="muted"> Rendered as <code><h2></code> with the <code>sm</code> size, so the card stays compact without skipping a level in the outline. </Text> </section> <section className="flex flex-col gap-2 rounded-xl border bg-card p-5"> <Heading level={3} size="display" className="text-brand"> 99.98% </Heading> <Text size="sm" tone="muted"> Rendered as <code><h3></code> with the <code>display</code>{" "} size: a big number that's still a small heading. </Text> </section> </div> );}
tone sets the color from the theme: default for primary reading, subtle for softer body copy, muted for captions and helper text, plus brand, danger and success. default, subtle and muted all meet WCAG AA contrast for body text in light and dark mode.
import { Text } from "@/components/ui/typography";export default function TypographyText() { return ( <div className="grid w-full max-w-2xl gap-8 sm:grid-cols-2"> <div className="flex flex-col gap-3"> <Text size="xs" tone="muted" weight="medium" className="uppercase tracking-wider" > Sizes </Text> <Text size="lg">lg — Intro copy and roomy layouts.</Text> <Text size="md">md — The default for reading.</Text> <Text size="sm">sm — Dense UI, cards and tables.</Text> <Text size="xs">xs — Captions and footnotes.</Text> </div> <div className="flex flex-col gap-3"> <Text size="xs" tone="muted" weight="medium" className="uppercase tracking-wider" > Tones </Text> <Text>default — Primary reading color.</Text> <Text tone="subtle">subtle — Softer body copy.</Text> <Text tone="muted">muted — Metadata and helper text.</Text> <Text tone="brand" weight="medium"> brand — Emphasis that matches links. </Text> <Text tone="danger" weight="medium"> danger — Something went wrong. </Text> <Text tone="success" weight="medium"> success — Saved and synced. </Text> </div> </div> );}
List keeps native list semantics and uses muted markers. marker="none" removes the bullets but keeps it announced as a list. Blockquote with attribution becomes a <figure> with a caption, the recommended markup for a quote with a source.
import { Blockquote, Heading, List } from "@/components/ui/typography";export default function TypographyQuoteAndList() { return ( <div className="grid w-full max-w-2xl gap-8 sm:grid-cols-2"> <div className="flex flex-col gap-3"> <Heading level={3} size="xs"> Before you launch </Heading> <List ordered> <li>Point your domain at the new deploy.</li> <li>Invite your team and assign roles.</li> <li>Turn on two-factor authentication.</li> </List> <Heading level={3} size="xs" className="mt-2"> Included in Pro </Heading> <List spacing="sm"> <li>Unlimited projects</li> <li>Audit log with 1-year retention</li> <li>SAML single sign-on</li> </List> </div> <Blockquote attribution="Priya Raman, Head of Design at Northwind"> We replaced three internal libraries with one. New hires ship their first screen in a day instead of a week. </Blockquote> </div> );}
Wrap rendered HTML or MDX in Prose. It styles headings (h1–h4), paragraphs, links, bold text, lists (nested too), inline code, code blocks, blockquotes, horizontal rules, tables, images, figures and kbd. The first and last child lose their outer margin so the article sits flush in its container. Cap the line length with max-w-prose (65 characters).
import { Prose } from "@/components/ui/typography";export default function TypographyProse() { return ( <Prose className="w-full max-w-prose"> <h1>Migrating to the new billing API</h1> <p> The v2 billing API replaces per-seat line items with{" "} <strong>usage records</strong>. Existing subscriptions keep working until <a href="#timeline">June 30</a>, but new features only ship on v2. </p> <h2 id="timeline">Timeline</h2> <ol> <li> <strong>Now:</strong> v2 is available behind the{" "} <code>billing_v2</code> flag. </li> <li> <strong>April 15:</strong> new workspaces default to v2. </li> <li> <strong>June 30:</strong> v1 endpoints return <code>410 Gone</code>. </li> </ol> <h2>Updating your client</h2> <p>Swap the subscription item call for a usage record:</p> <pre> <code>{`await billing.usage.create({ subscription: "sub_42", quantity: seats.length, timestamp: Date.now(),});`}</code> </pre> <blockquote> <p> Usage records are idempotent per timestamp, so retries never double charge. </p> </blockquote> <h3>Field changes</h3> <table> <thead> <tr> <th>v1 field</th> <th>v2 field</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td> <code>seats</code> </td> <td> <code>quantity</code> </td> <td>Now reported, not set.</td> </tr> <tr> <td> <code>plan</code> </td> <td> <code>price</code> </td> <td>Prices are versioned.</td> </tr> </tbody> </table> <ul> <li>Webhooks keep the same signatures.</li> <li> Invoices show usage per day. <ul> <li>Totals are unchanged.</li> </ul> </li> </ul> <hr /> <p> Questions? Reply to the migration email or open a ticket from{" "} <a href="#support">Settings → Support</a>. </p> </Prose> );}
size sets the base font size; every margin and heading inside is in em, so the whole article scales together. Use sm in side panels and comments, lg for long-form reading.
import { useState } from "react";import { ToggleButton } from "@/components/ui/toggle-button";import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";import { Prose } from "@/components/ui/typography";type Size = "sm" | "md" | "lg";export default function TypographyProseSizes() { const [size, setSize] = useState<Size>("sm"); return ( <div className="flex w-full max-w-prose flex-col gap-5"> <ToggleButtonGroup aria-label="Text size" selectionMode="single" disallowEmptySelection selectedKeys={[size]} onSelectionChange={(keys) => setSize([...keys][0] as Size)} variant="segmented" size="sm" className="self-start" > <ToggleButton id="sm">Small</ToggleButton> <ToggleButton id="md">Medium</ToggleButton> <ToggleButton id="lg">Large</ToggleButton> </ToggleButtonGroup> <Prose size={size}> <h3>Release notes · 4.2</h3> <p> Comments now support <strong>threads</strong> and{" "} <a href="#mentions">@mentions</a>. Everything else scales with the size you pick, because the article measures in <code>em</code>. </p> <ul> <li>Resolve a thread to collapse it.</li> <li>Mentions notify by email after five minutes.</li> </ul> </Prose> </div> );}
For HTML from a CMS, sanitize it first and render it with dangerouslySetInnerHTML on the Prose element. To drop a styled component into an article (a Card, a chart) without the article styles reaching it, close Prose before it and open a new one after.
To change a Prose rule, edit the matching line in proseVariants (they're grouped by element), or add a descendant class at the call site: <Prose className="[&_a]:no-underline">.
Components are the easy part. Adoption comes from docs, defaults and a migration path that respects the code teams already have.
We started by auditing every button in the product and found 41 variations. Six months later there are three, all imported from @/components/ui/button, and nobody had to stop shipping to get there.
Maya Chen · 6 min read · Updated March 12
display48px / 1.05
Quarterly planning
Hero titles, marketing
xl36px / 1.25
Quarterly planning
Page titles (h1)
lg24px / 1.375
Quarterly planning
Section titles (h2)
md20px / 1.375
Quarterly planning
Card and subsection titles (h3)
sm18px / 1.375
Quarterly planning
Small groups (h4)
xs16px / 1.5
Quarterly planning
Inline headings (h5, h6)
Billing
Rendered as <h2> with the sm size, so the card stays compact without skipping a level in the outline.
99.98%
Rendered as <h3> with the display size: a big number that's still a small heading.
Sizes
lg — Intro copy and roomy layouts.
md — The default for reading.
sm — Dense UI, cards and tables.
xs — Captions and footnotes.
Tones
default — Primary reading color.
subtle — Softer body copy.
muted — Metadata and helper text.
brand — Emphasis that matches links.
danger — Something went wrong.
success — Saved and synced.
Run npx shadcn@latest add @desyne/typography, then import Heading and Text wherever you'd reach for a raw <h2> or <p>. Press ⌘K to search the docs.
We replaced three internal libraries with one. New hires ship their first screen in a day instead of a week.
— Priya Raman, Head of Design at Northwind
Migrating to the new billing API
The v2 billing API replaces per-seat line items with usage records. Existing subscriptions keep working until June 30, but new features only ship on v2.
Timeline
Now: v2 is available behind the billing_v2 flag.
April 15: new workspaces default to v2.
June 30: v1 endpoints return 410 Gone.
Updating your client
Swap the subscription item call for a usage record: