Heading

The Heading component provides semantic headings with consistent typography and easy-to-use variants. It automatically maps variants to appropriate HTML tags while allowing customization.

When no variant is specified, the Heading uses the semantic level (h1-h6) to determine styling.

Features

Semantic heading levels (h1-h6)
Special purpose variants (display, title, subtitle, section)
Color customization
Responsive variant support
Automatic tag inference from variant
Custom tag override with as prop

Usage

import { Heading } from '@loke/design-system/heading';

export default function Example() {
  return (
    <div className="space-y-4">
      <Heading as="h1">Page Title</Heading>
      <Heading as="h2" variant="subtitle">Subtitle here</Heading>
      <Heading as="h3">Section Heading</Heading>
    </div>
  );
}

Tips:

Use semantic heading levels for proper document outline.
The variant prop controls visual appearance, as controls the HTML tag.
When variant matches a heading level (h1-h6), the tag is inferred automatically.

Props

Prop

Type

Variants

Heading Levels

Variant	Size	Weight	Usage
`h1`	4xl	Extra Bold	Main page title
`h2`	3xl	Bold	Major sections
`h3`	2xl	Semibold	Subsections
`h4`	xl	Semibold	Minor sections
`h5`	lg	Medium	Group headings
`h6`	base	Medium	Small headings

Special Variants

Variant	Size	Weight	Usage
`display`	5xl	Extra Bold	Hero sections
`title`	4xl	Bold	Feature titles
`subtitle`	2xl	Medium	Supporting titles
`section`	xl	Semibold	Section labels

Examples

Heading variants

Display Heading

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Title

Subtitle

Section

<Heading variant="display">Display Heading</Heading>
<Heading variant="h1">Heading 1</Heading>
<Heading variant="h2">Heading 2</Heading>
<Heading variant="h3">Heading 3</Heading>
<Heading variant="h4">Heading 4</Heading>
<Heading variant="title">Title</Heading>
<Heading variant="subtitle">Subtitle</Heading>
<Heading variant="section">Section</Heading>

Color variants

Foreground

Primary

Secondary

Neutral 500

Neutral 400

<Heading variant="h3" color="foreground">Foreground</Heading>
<Heading variant="h3" color="primary">Primary</Heading>
<Heading variant="h3" color="secondary">Secondary</Heading>
<Heading variant="h3" color="n-500">Neutral 500</Heading>

Semantic structure

Getting Started with Design Systems

A comprehensive guide to building consistent UIs

Introduction

Design systems help teams build consistent and high-quality user interfaces at scale...

Core Concepts

Understanding the fundamental building blocks...

Components

Reusable UI elements that form the foundation...

Tokens

Design tokens represent the visual design atoms...

<article>
  <Heading as="h1">Article Title</Heading>
  <Heading as="h2" variant="subtitle">Article Subtitle</Heading>

  <section>
    <Heading as="h2">First Section</Heading>
    <p>Content for the first section...</p>

    <Heading as="h3">Subsection</Heading>
    <p>More detailed content...</p>
  </section>
</article>

Custom tag with variant

Hero Section Title

Uses h2 tag but display variant styling for visual impact

Sidebar Section

Uses h3 tag but section variant styling for sidebars

Feature Title

Uses h1 tag with title variant for feature sections

{/* Use h2 tag but display variant styling */}
<Heading as="h2" variant="display">
  Hero Section Title
</Heading>

{/* Use h3 tag but section variant styling */}
<Heading as="h3" variant="section">
  Sidebar Section
</Heading>

Accessibility

Uses semantic heading tags (h1-h6) for proper document outline.
Maintains heading hierarchy for screen reader navigation.
Color variants ensure sufficient contrast ratios.
Supports custom tags for visual flexibility without breaking semantics.

Best practices

Maintain proper heading hierarchy (h1 → h2 → h3, etc.).
Use only one h1 per page for the main title.
Choose variants based on visual hierarchy, tags based on document structure.
Use special variants (display, title) for marketing/hero sections.
Use section variant for sidebar or secondary navigation headings.
Consider responsive variants for different screen sizes.