Documentation

Documentation

Heading

Responsive typography headings with semantic size control and breakpoint-aware scaling.

The <dsgn-heading> component renders headings with responsive font sizing, so type scales fluidly across breakpoints.

Usage

<dsgn-heading heading-size="h2">Section title</dsgn-heading>

Import the component module in your application entrypoint:

import '@ds-gn/ui/heading';

Playground

Props

Prop Type Default Description
heading-size 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'hero' 'h1' Heading level or hero style.
heading-weight 'normal' | 'semibold' | 'bold' | 'extrabold' 'normal' Font weight for the heading text.
surface 'light' | 'dark' 'light' Surface tone for heading color styling.
words string[] undefined Optional word list to cycle through in place of static text.
word-interval number undefined Milliseconds between word changes when words is set.
word-cycles number 1 How many times to cycle the word list.

heading-size, heading-weight, word-interval, and word-cycles are the attribute names; the matching JavaScript properties are headingSize, headingWeight, wordInterval, and wordCycles.

Slots

Slot Description
(default) Heading text content.

heading-size picks both the type scale and the rendered element: h1 through h6 render the matching tag, and hero renders an <h1> at the largest scale.

Word cycling

Set words to animate a swapping word after the slotted text. The list is cycled every word-interval milliseconds (default 1000) and stops after word-cycles passes.

<dsgn-heading
  heading-size="hero"
  words='["faster", "safer", "together"]'
  word-interval="1400"
  word-cycles="3"
>
  Ship
</dsgn-heading>
const heading = document.querySelector('dsgn-heading');
heading.words = ['faster', 'safer', 'together'];
heading.wordInterval = 1400;

The cycle needs at least two words. It pauses while the heading is off-screen and does not run at all when the user prefers reduced motion — the first word stays in place.

Examples

Sizes

<dsgn-heading heading-size="hero">Hero</dsgn-heading>
<dsgn-heading heading-size="h1">Heading 1</dsgn-heading>
<dsgn-heading heading-size="h2">Heading 2</dsgn-heading>
<dsgn-heading heading-size="h3">Heading 3</dsgn-heading>
<dsgn-heading heading-size="h4">Heading 4</dsgn-heading>
<dsgn-heading heading-size="h5">Heading 5</dsgn-heading>
<dsgn-heading heading-size="h6">Heading 6</dsgn-heading>

Weight

<dsgn-heading heading-size="h2" heading-weight="bold"
  >Bold section title</dsgn-heading
>

Dark surface

<dsgn-heading heading-size="h1" surface="dark"
  >Dark background title</dsgn-heading
>

Accessibility

  • Use heading-size to match the document outline and avoid skipping levels. hero renders an <h1>, so use it once per page.
  • Ensure heading text is descriptive of the section content.
  • Word cycling honors prefers-reduced-motion: the heading renders the first word statically instead of animating. Keep the slotted text meaningful on its own so the heading reads correctly with any word showing.

Usage patterns

  • Use heading-size="hero" for page-level titles only.
  • Apply surface="dark" when the heading is rendered on dark backgrounds to maintain contrast.
Esc