headings

Heading Scale

VB provides six heading levels, each mapped to a font-size token. All headings share font-weight: 600, text-wrap: balance, lining numerals, and disabled hyphenation.

h1 and h2 get tighter letter-spacing (tracking) because large text has more apparent whitespace between characters. h6 uses font-weight: 700 instead of 600 for visual differentiation at body-text size.

Document Hierarchy

Headings create the document outline. Use them in order without skipping levels — an <h3> should always follow an <h2>, never an <h1> directly.

Rule of thumb: Each page should have exactly one <h1>. Sections use <h2>. Subsections use <h3>. Levels 4–6 are for fine-grained structure within long documents.

Heading Links

Wrap content in the <heading-links> web component to add hover-reveal anchor links to headings. It auto-generates id attributes from heading text and supports click-to-copy URL.

By default, <heading-links> processes h2 and h3. Use levels="h2,h3,h4" to include additional levels.

Table of Contents

The <page-toc> web component auto-generates a table of contents from headings with scroll-spy highlighting. It pairs with <heading-links> which provides the heading IDs.

Both components default to h2 and h3 because h1 is the page title (not a section) and h4–h6 are too granular for most navigation.

Theme Ornament Hooks

Themes can add decorative glyphs before or after headings using CSS custom properties. These tokens are theme-controlled — the base VB stylesheet sets them to none.

Typography Features

Headings include several typographic refinements applied automatically:

• font-variant-numeric: lining-nums — Numbers align with capital letters rather than descending like oldstyle numerals
• hyphens: none — Headings are never hyphenated, even when the parent has hyphens: auto
• text-wrap: balance — Text distributes evenly across lines, preventing short orphan lines
• letter-spacing — h1 and h2 get tighter tracking at large sizes for better visual density

Heading Groups

Use <hgroup> to pair a heading with a subtitle, eyebrow label, byline, or other secondary text. Only the heading contributes to the document outline.

See the hgroup documentation for all variants including .eyebrow, .byline, .section-header, and .display.

Accessibility

• One h1 per page — The page title. Screen readers use it as the primary landmark
• Sequential levels — Never skip levels (h1 → h3). Screen reader users navigate by heading level
• Descriptive text — Headings should summarize the section content. Avoid generic text like "Section 1"
• Don't use for styling — Choose heading level by hierarchy, not visual size. Use CSS to adjust appearance
• heading-links — The anchor links added by <heading-links> include descriptive aria-label attributes
• Heading count — Screen readers can list all headings on a page. Well-structured headings serve as an alternative navigation method

Related

• <hgroup> — Pair headings with subtitles, eyebrow labels, or bylines
• <heading-links> — Add anchor links to headings with auto-generated IDs
• <page-toc> — Auto-generate table of contents from headings with scroll-spy
• <article> — Self-contained content that typically starts with a heading
• <section> — Thematic grouping identified by its heading
• Typography — Lining numerals, letter-spacing, and other typographic refinements