Heading
A semantic section heading whose visual size is decoupled from its document level.
Live demo
Heading renders a native <h1>–<h6> chosen by level, while size sets the visual scale independently across seven steps (xs, sm, body, lg, xl, 2xl, 3xl). That split lets the document outline stay correct (an <h2> deep in a page) while the type still reads at whatever weight the layout wants (small label, or a hero at 3xl), so a site can stop faking type with raw tags and ad-hoc font sizes.
The tone axis sets the ink: default, muted, and subtle walk down the foreground ramp for primary titles, secondary headings, and quiet labels; the full color roster (every semantic role, accent variant, or named hue) paints a colored heading in that tone's on-surface ink, derived to stay legible against the page. The display font carries every step.
When to use
How this component composes with the rest of the set.
level to keep the document outline correct, then pick size purely for the look. size="xs" or size="sm" with tone="subtle" for eyebrow labels above a larger title. --{tone}-vivid ink by contract. To pin a heading to a tone's base shade instead (a brand whose accent is --accent, say), style ::part(heading) from the consumer side: xtyle-heading::part(heading) { color: var(--accent) }. A per-instance custom property set on the host (xtyle-heading { --accent-vivid: ... }) does not reach the inner element's own token register, so ::part is the reliable seam for a one-off color. Props
3 props, straight from the manifest.
| Prop | Type | Default | Bindings | Description |
|---|---|---|---|---|
<h1>–<h6> tag. Drives the outline, not the size. | ||||
level. Unset, it derives from level (1→3xl, 2→2xl, 3→xl, 4→lg, 5→body, 6→sm); set it to override, up to the 4xl/5xl display steps for hero titles. | ||||
default/muted/subtle emphasis ramp off the foreground, or any tone in the full roster (semantic role, accent variant, or named hue) for a colored heading in that tone's on-surface ink. |
Appearance
Variants
default
Primary heading ink: full-strength foreground.
muted
Secondary ink for supporting headings.
subtle
Quiet ink for eyebrow and section labels.
accent
Accent-colored ink for a highlighted title or a metric figure; the first stop of the full tone roster, which paints any heading in a tone's on-surface --{tone}-vivid ink.
Sizes
xs
Smallest; a quiet label.
sm
Compact heading.
body
Body-scale heading; the derived default at level 5.
lg
Large; section titles.
xl
Extra large; page titles.
2xl
Display; section heroes.
3xl
Hero; page heroes.
4xl
Oversized; for hero titles.
5xl
Largest step; for landing-page headlines.
Anatomy
The named parts that make up the component. A ::part() handle is reachable from your own stylesheet; the class beside it is the component's internal selector, which a shadow boundary keeps to itself.
heading
The native heading element (<h1>–<h6>) carrying the size and tone classes; exposed as ::part(heading) for a consumer-side color override.
Tokens & coverage
What the component consumes, checked live against what the algorithm produces.
Live coverage check against the xtyle-default register
(derive(xtyleDefault, { anchors }) →
coverComponent(manifest, register)). Every token this component
consumes must be a key the algorithm produces.
--accent-2-vivid--accent-3-vivid--accent-4-vivid--accent-vivid--black-vivid--blue-vivid--brown-vivid--cyan-vivid--danger-vivid--fg-0--fg-2--fg-3--font-display--gray-vivid--green-vivid--info-vivid--leading-normal--leading-tight--neutral-vivid--orange-vivid--pink-vivid--purple-vivid--red-vivid--success-vivid--text-2xl--text-3xl--text-4xl--text-5xl--text-body--text-lg--text-sm--text-xl--text-xs--warn-vivid--weight-bold--weight-semibold--white-vivid--yellow-vividSlots
The heading text.
Accessibility
<h1>–<h6> so the document outline and screen-reader heading navigation come for free. level controls the semantic tag; size is purely visual, so headings can shrink or grow without breaking the outline. Code
Levels, sizes, and tones
Level sets the tag; size sets the look; tone sets the ink, all independent.
<xtyle-heading level="1" size="3xl">Themable derivation</xtyle-heading>
<xtyle-heading level="2" size="xl">The algorithm is the asset</xtyle-heading>
<xtyle-heading level="3" size="lg" tone="muted">A theme is the print</xtyle-heading>
<xtyle-heading level="2" size="sm" tone="danger">Breaking change</xtyle-heading><script lang="ts">
import { Heading } from "@xtyle/svelte";
</script>
<Heading level={1} size="3xl">Themable derivation</Heading>
<Heading level={2} size="xl">The algorithm is the asset</Heading>
<Heading level={3} size="lg" tone="muted">A theme is the print</Heading>
<Heading level={2} size="sm" tone="danger">Breaking change</Heading>---
import { Heading } from "@xtyle/astro";
---
<Heading level={1} size="3xl">Themable derivation</Heading>
<Heading level={2} size="xl">The algorithm is the asset</Heading>
<Heading level={3} size="lg" tone="muted">A theme is the print</Heading>
<Heading level={2} size="sm" tone="danger">Breaking change</Heading>