Heading
A responsive heading renderer that maps a visual size scale onto the correct semantic HTML heading element. Supports fluid typography, colour, alignment, weight, and ellipsis truncation.
Keyboard interaction
diwa-heading is a non-interactive display component. It receives no keyboard focus.
| Key | Action |
|---|---|
| — | No keyboard interaction. diwa-heading is a display-only element. |
Screen reader behaviour
The component adds no ARIA attributes of its own. Semantic meaning comes entirely from the rendered HTML heading tag. Screen readers announce headings with their level (e.g. "Heading level 2 — Section title").
| Attribute / Property | Value / Behaviour |
|---|---|
Rendered tag | The size prop controls the HTML heading element rendered inside the shadow root (h1–h6). Screen readers interpret the native heading semantics and level. |
tag override | When tag is set, the rendered HTML element changes. Changing tag changes the announced heading level — this is intentional and expected when decoupling visual from semantic level. |
Auto-div fallback | When a direct child is an h1–h6 element, the host renders as <div>. The child heading's semantics are preserved. Screen readers announce the child heading level correctly. |
Heading document outline
A well-formed heading outline is critical for screen reader users who navigate pages by jumping between headings. Follow these rules to maintain a logical outline:
- One h1 per page — the page title should always be the single top-level heading.
- Do not skip levels — jumping from h2 to h5 creates gaps in the outline that confuse screen reader navigation. Use consecutive levels.
- Use tag to fix outline conflicts — if a card component must be h4 for outline reasons but needs h2 visual size, use
tag="h4"withsize="h2".
CSS custom properties and contrast
When using --diwa-heading-color to override the heading colour, ensure the custom value meets WCAG 2.2 AA contrast requirements of at least 4.5:1 against the background for normal text, or 3:1 for large text (18px+ regular or 14px+ bold — both thresholds are always met by heading sizes).
/* Override heading colour — verify contrast before deployment */
diwa-heading {
--diwa-heading-color: var(--diwa-brand-500); /* at least 3:1 on dark bg */
}
WCAG 2.2 compliance
Heading structure is conveyed through semantic HTML element (h1–h6). Visual hierarchy matches document outline.
color="primary" and color="secondary" aliases meet 4.5:1 contrast on the Diwa dark theme background.
Fluid font-size tokens use CSS clamp() — text scales with browser zoom and user font-size preferences.
Non-interactive component. No keyboard interaction required or expected.
Auto-div fallback prevents invalid heading nesting. Shadow DOM encapsulation ensures well-formed output.