Heading

Position in the document outline. Controls the semantic element, not the visual size. Canonical values are strings; generated components also accept the number — the exported `HeadingLevel` type is the string union, and the prop or property type adds `1 | 2 | 3 | 4 | 5 | 6`. A missing, out-of-range or non-numeric level (untyped JavaScript, `level="7"`) is treated as `2` on every platform: an <h2> on web and Lit, the 3xl default size everywhere, and one development warning per element for its lifetime. The warning is developer-facing, not copy, so it has no copy key; it names the received value and the level-2 fallback (`Heading: level 7 is not one of 1–6; rendering as level 2.`), printing the value as `String(level)`, so a missing level reads `level undefined`. The warning is issued once per element whatever later values arrive (a later, different invalid value does not warn again), and on web from an effect behind a ref guard rather than during render, so StrictMode cannot send it twice. Behavior scenarios take only canonical values, so each platform's own test file covers a numeric level and the fallback with its single warning; neither gets a story. On Lit the property holds `undefined` until set, and the fallback renders. The Default story renders level `2` with "Account settings" and no other args.

Accessibility: Screen-reader users navigate by heading level; levels must not skip (h1 → h3).

Visual size, independent of level. There is no single default; the default is read from `level` by this exact map — 1 → 4xl, 2 → 3xl, 3 → 2xl, 4 → xl, 5 → lg, 6 → md — and an explicit `size` always wins over it. On Lit the resolved default is never written back to the `size` attribute, so `[size]` selectors match only explicit sizes; web exposes no size attribute at all, only the `ds-heading--size-*` modifier class, which carries the resolved size. Heading takes the large end of the shared size vocabulary; the exported type is its own, since Text takes the small end. Enum stories keep the literal `<Prop><Value>` casing: `Size4xl`, `Size2xl`, `Level1`.

The heading text. Keep it short and descriptive; it is what appears in the page outline.

Horizontal text alignment. It has no style binding on purpose — alignment is a layout choice, not a themed value — so it maps straight to the platform's text-align. `start` and `end` are logical on web and Lit; React Native has no logical values and resolves them through I18nManager.isRTL at render, so a writing-direction change mid-session does not re-align an already-rendered heading, the same limit Text has. The value set is Text's, so every platform reuses Text's exported `TextAlign` type and exports no separate HeadingAlign, with no deprecated alias; Text exports no mapping helper on web or Lit, so Heading keeps its own `ds-heading--align-*` classes there and its own `:host([align])` selectors on Lit. On web every value, `start` included, emits its `ds-heading--align-<value>` class.