Skip to content

Design system

Documentation

DesignComponents / Typography

Components / Typography

Beta

Typography

Use semantic headings, readable text, and paragraphs as small composable primitives. Keep document structure, visual scale, and meaning separate.

On this page

Examples

Basic hierarchy

Compose a heading, supporting line, and paragraph without losing their semantic roles.

Make hierarchy visible

A supporting line gives the section a clear starting point.

Paragraph keeps longer explanations readable with the same type scale and semantic color roles.

Heading, supporting text, and paragraph

Heading levels

Use the level prop for document structure and let the visual size follow the hierarchy by default.

Workspace overview

Recent activity

Invite a teammate

Delivery preferences

Heading levels from h1 through h4

Independent sizes

A heading level and its visual size are independent so a nested section can stay proportionate.

Compact heading

Default heading

Section heading

Feature heading

Display heading

Heading size comparison with one display treatment

Semantic tones

Use readable words and semantic tones together; color never carries meaning alone.

Primary text carries the main message.Muted text supports the message without competing with it.Brand text points to an important destination.Saved successfully.Review is needed before continuing.This action could not be completed.The next sync starts in a few minutes.

Text tones with readable status messages

Meaningful formatting

Use native inline elements for emphasis, changed values, highlights, and code.

Use strong for importance, emphasis for a change in voice, underline for a named reference, deleted copy for an obsolete value, mark for a relevant match, and inline code for a token.

Semantic inline formatting inside Paragraph

Readable paragraphs

Paragraph keeps body copy at the shared reading rhythm and measure.

A comfortable reading measure keeps instructions easy to scan. Keep one idea per paragraph, use sentence case, and break up dense explanations with meaningful headings or lists.

Paragraph constrained to the readable measure

Single-line ellipsis

Opt into one-line truncation for constrained rows and provide a visible way to read the full value.

North star migration workspace with a deliberately long name
View full name

North star migration workspace with a deliberately long name

Single-line truncation with a visible full-value disclosure

Multi-line ellipsis

Limit descriptions to a few lines while keeping an explicit disclosure for the complete copy.

The workspace keeps shared settings, review notes, and delivery history together so a team can understand the current state without opening several separate screens.

Read the full description

The workspace keeps shared settings, review notes, and delivery history together so a team can understand the current state without opening several separate screens.

Three-line Paragraph clamp with a visible disclosure

Inside a Card

Typography composes with existing surfaces, status labels, and actions without adding a new wrapper pattern.

North star migration

Shared delivery workspace
Operational

Keep the summary short in the list, then give people a visible path to read the complete project context.

Typography composed inside a Card with Badge and Button

Heading playground

Try the semantic level, visual size, and display font independently.

Project overview

Interactive Heading configuration

When to use

Use Heading for a named section, Text for short inline or supporting copy, and Paragraph for a complete explanation. The components keep semantic HTML intact while making PhucTech's type scale and tone choices repeatable.

Use truncate only when the surrounding layout has a real width constraint. Use lineClamp for a short preview of a longer description, and provide a visible disclosure such as <details> or a “View more” action when the full content matters.

Usage

typography-basic.tsx
import { Heading, Paragraph, Text } from "@phuctech/ui/components/typography";

export function Example() {
  return (
    <div className="grid gap-3">
      <Heading level={2}>Make hierarchy visible</Heading>
      <Text tone="muted">A supporting line gives the section a clear starting point.</Text>
      <Paragraph>
        Paragraph keeps longer explanations readable with the same type scale and semantic color roles.
      </Paragraph>
    </div>
  );
}

Composition

Keep the semantic role in the component and the visual decision in its props. Heading level controls the document outline; size can change its visual scale when a nested region needs a quieter title. Put semantic inline elements such as strong, em, mark, and code inside Text or Paragraph instead of creating a component for every formatting treatment.

Separate structure from scale

A card title can stay an h3 while using a smaller visual size than a page section.

Do not use color as meaning

Pair a semantic tone with readable words; success, warning, and danger tones are not status labels by themselves.

API

Component API
PropTypeDefaultDescriptionConstraints
HeadingHTMLHeadingElement props + typography propslevel=1Renders h1–h6 with a shared heading scale.Use one meaningful level for the document outline; size is independent.
Heading level1 | 2 | 3 | 4 | 5 | 61The semantic heading element to render.Do not choose a level only for its visual size.
Heading size"xs" | "sm" | "md" | "lg" | "xl" | "display"follows levelVisual size and leading for the heading.Override when a nested heading needs a quieter or display treatment.
Heading font / tone / weightfont: "body" | "display"; tone: TypographyTone; weight: TypographyWeightbody / default / semiboldDisplay face, semantic color, and font weight.Use display font sparingly; tone never replaces a readable label.
TextHTMLSpanElement props + typography propssize=mdShort inline or supporting copy using the shared type scale.Use Paragraph when the content is a complete block of prose.
ParagraphHTMLParagraphElement props + typography propssize=mdBlock copy with the shared body leading.Keep paragraphs short and give long copy a readable measure.
Text / Paragraph size"xs" | "sm" | "md" | "lg" | "xl"mdBody scale step.Prefer the smallest size that remains comfortable to read.
Text / Paragraph truncatebooleanfalseKeeps content on one line and applies an ellipsis when it overflows.The parent must provide a width constraint; expose the full value elsewhere.
Text / Paragraph lineClamp2 | 3—Limits content to two or three lines.Choose either lineClamp or truncate, and provide a visible disclosure for important full copy.
Shared typography propsfont, tone, weight, className, style, children—Native element props plus the shared visual options.Use className for local layout; keep product semantics in the feature.

Tokens

Component tokens
TokenRoleEffective valueUsage
--type-size-*Type scalexs through 2xlShared sizes for heading, text, and paragraph variants.
--type-leading-tightHeading leading1.2Keeps headings compact while preserving a clear outline.
--type-leading-bodyBody leading1.7Gives Text and Paragraph enough room to scan.
--color-text-*Text rolessemantic light/dark rolesKeeps default, muted, subtle, and status tones readable in both themes.
--typography-line-clampEllipsis utility2–3 linesDrives the opt-in multi-line clamp without removing the text from the accessibility tree.

Accessibility

  • Choose Heading level from the page outline, not from the size you want to see.
  • Keep important meaning in text; a tone or color must never be the only status signal.
  • Truncation is visual. Screen readers still receive the full content, and people need a visible way to open or read it when it matters.
  • Use native inline semantics: strong and em for meaning, s for no-longer-valid copy, mark for a relevant match, and code for code tokens.

Do and don’t

Do

Keep a comfortable reading measure, use sentence case, and show a full-content path next to an ellipsis preview.

Don’t

Use a giant display treatment for every heading, clamp required instructions, or hide the only copy of a value behind a tooltip.

  • Typography foundation documents fonts, scale, leading, and reading measure.
  • Card provides a bounded surface where heading and body hierarchy can stay explicit.
  • Badge adds a short readable status label next to supporting text.