Heading

Usage

• Use Heading for semantic HTML headings (<h1>–<h6>) that establish page content hierarchy.
• Prefer Heading over Text when a heading is needed — Heading provides the correct semantic tag and default typography.
• Never choose a heading level based on appearance — use level for semantics and override styles with size, weight, or text props when needed.

Appearance

• Level (level) — accepts "1" through "6", mapping to <h1>–<h6>. Defaults to "2". Levels 1–4 each have distinct typography styles; levels 5 and 6 share the same style as level 4.
• Size (size) — override the default font size independently from heading level. Accepts token values: "xxxl", "xxl", "xl", "l", "m", "s", "xs".
• Weight (weight) — override font weight. Accepts "light", "regular", "semibold", "bold".
• Color (color) — defaults to base text color. Automatically adapts to background for contrast when no explicit color is set.
• Font family (family) — defaults to sans-serif. Use "mono" for code-related contexts.
• Font style (fontStyle) — apply "italic" for visual emphasis without changing heading semantics.
• Text style (text) — apply a predefined typography style (font size, weight, line height, letter spacing) to any heading level. Auto-mapped from level by default (e.g., level "1" maps to "product-h1").

Behaviors

• Headings wrap automatically when the container resizes. The wrapping algorithm avoids widows (single words on the last line).

Content

• Limit heading text to six or fewer words. Use a Paragraph below the heading for supplemental information.
• Use sentence case.
• Omit end punctuation except for confirmation modals (e.g., "Delete this workspace?").
• Never write headings that read like full sentences.

Implementation Notes

• Heading extends Text — all Text props (size, weight, color, family, fontStyle, text) are inherited.
• level defaults to "2" when omitted.
• The text prop is auto-derived from level (level "1" uses "product-h1", etc.). Setting text explicitly overrides this mapping.
• Levels "5" and "6" both map to the "product-h4" typography style, so they render identically by default.
• React: <Heading level="2">text</Heading> — content via children.
• Ember: <PlumaHeading @level="2">text</PlumaHeading> — content via {{yield}} (default block).
• Never skip heading levels — maintain sequential order (h2 then h3, not h2 then h4).
• Limit level="1" to one per page.