Visual Hierarchy

Use heading levels sequentially (H1 → H2 → H3 → H4) to establish a clear content hierarchy. Each page should have exactly one TypographyH1. Pair headings with TypographyLead for introductory paragraphs that provide context below page titles.

Spacing & Layout

Typography components include built-in spacing via scroll-m-20 on headings and mt-6 on paragraphs. Avoid adding extra wrapper margins that conflict with these defaults. For article-style layouts, wrap content in a max-w-prose container for optimal line length (roughly 65 characters per line).

Responsive Behavior

TypographyH1 scales from text-4xl to lg:text-5xl for larger screens and uses text-balance for better line wrapping. Typography tables are wrapped in an overflow container so they scroll horizontally on narrow viewports rather than breaking the layout.

Color & Contrast

Headings and body text use text-foreground for maximum readability. De-emphasised text such as TypographyMuted and TypographyLead use text-muted-foreground, which meets WCAG 2.1 AA contrast requirements against both light and dark backgrounds. Inline code uses bg-muted for subtle visual distinction.

Semantic Structure

• Each heading component renders its native HTML element (<h1> through <h4>), creating an accessible document outline for screen readers
• Never skip heading levels (e.g., H1 → H3) — this breaks the heading hierarchy that assistive technologies rely on for page navigation
• TypographyBlockquote renders a <blockquote> element, announced by screen readers as a quotation
• TypographyList renders a <ul> element; screen readers announce the number of items

Screen Reader Support

• Headings are navigable via the screen reader's heading navigation shortcuts (e.g., H in NVDA/JAWS)
• TypographyInlineCode renders as <code>, which some screen readers announce as "code" before the content
• Table components use proper <thead>, <th>, and <td> elements so screen readers can announce row/column headers when navigating cells
• Add a <caption> (visible or sr-only) to tables for additional context

Keyboard Navigation

• Headings with scroll-m-20 provide proper scroll margin when navigated to via anchor links, preventing content from hiding behind sticky headers
• Tab navigation skips non-interactive typography elements as expected; only links within text are focusable
• Table cells can be navigated with arrow keys when using screen reader table navigation mode

ARIA Attributes

{/* Headings create an accessible document outline */}
<TypographyH1>Page Title</TypographyH1>
<TypographyH2>Section Title</TypographyH2>

{/* Blockquote with attribution */}
<figure>
  <TypographyBlockquote>
    "Everyone enjoys a good joke."
  </TypographyBlockquote>
  <figcaption className="text-sm text-muted-foreground mt-2">
    — The King
  </figcaption>
</figure>

{/* Table with caption for context */}
<TypographyTable>
  <caption className="sr-only">
    Joke tax rates by category
  </caption>
  <TypographyThead>
    <TypographyTr>
      <TypographyTh scope="col">Category</TypographyTh>
      <TypographyTh scope="col">Rate</TypographyTh>
    </TypographyTr>
  </TypographyThead>
  ...
</TypographyTable>

{/* Inline code with lang attribute for screen readers */}
<TypographyInlineCode lang="en">npm install</TypographyInlineCode>