Heading
The heading primitive. Two voices — heading and display — on the heading-shaped elements, the text shapes and the captions. The element is the outline, the size is the visual step, and the two are independent. A heading that should read like text is Text on an h-element (ADR-0023).
Sizes
The heading voice has six steps. By default the element decides the size: h1 is 1, h6 is 6.
Size 1 — the page title
Size 2 — a section
Size 3 — a subsection
Size 4 — a group
Size 5 — a caption-level heading
Size 6 — the smallest step
---
import Heading from "tsugite/Heading/Heading.astro";
---
<Heading text="Size 1 — the page title" element="h1" size="1" />
<Heading text="Size 2 — a section" element="h2" size="2" />
<Heading text="Size 3 — a subsection" element="h3" size="3" />
<Heading text="Size 4 — a group" element="h4" size="4" />
<Heading text="Size 5 — a caption-level heading" element="h5" size="5" />
<Heading text="Size 6 — the smallest step" element="h6" size="6" />Element and size are independent
The element belongs to the document outline; the size to the layout. Override the size when the composition asks for it, never the element.
An h2 at size 2 (the default: element decides size)
An h2 at size 4 — same outline level, quieter
An h3 at size 1 — a deep heading that leads a hero
---
import Heading from "tsugite/Heading/Heading.astro";
---
{/* The element is the document outline; the size is the visual step.
They are independent: an h2 can look like size 4 when the layout asks for it. */}
<Heading text="An h2 at size 2 (the default: element decides size)" element="h2" />
<Heading text="An h2 at size 4 — same outline level, quieter" element="h2" size="4" />
<Heading text="An h3 at size 1 — a deep heading that leads a hero" element="h3" size="1" />Display voice
Three steps of the loud voice, for heroes and covers.
Display 1 — the loudest voice
Display 2
Display 3
---
import Heading from "tsugite/Heading/Heading.astro";
---
<Heading text="Display 1 — the loudest voice" element="h1" voice="display" size="1" />
<Heading text="Display 2" element="h2" voice="display" size="2" />
<Heading text="Display 3" element="h2" voice="display" size="3" />Highlight
Comma-separated words to mark, and a style for the marking: mark by default, or a wavy underline. The list is open, one row in the table and one rule in the CSS per style; the mark always inherits the run's metrics. Bold is not on it: a loud voice flattens inline emphasis (ADR-0012).
A deterministic system is built from closed branches, not clever ones.
A deterministic system is built from closed branches, not clever ones.
---
import Heading from "tsugite/Heading/Heading.astro";
---
{/* highlight marks the listed words (comma-separated); highlightStyle says how.
The list of styles is open: a value is a row in the table and a rule in Heading.css. */}
<Heading
text="A deterministic system is built from closed branches, not clever ones."
highlight="deterministic, closed branches"
/>
<Heading
text="A deterministic system is built from closed branches, not clever ones."
highlight="deterministic, closed branches"
highlightStyle="underline"
/>As a link
href makes the run a link. Size and trim apply to it exactly as to plain text.
---
import Heading from "tsugite/Heading/Heading.astro";
---
{/* href wraps the text in a link inside the heading — the link is the run,
so trim and size apply to it exactly as to plain text. */}
<Heading text="A heading that is also a link" href="/map" element="h2" size="2" />Alignment and wrapping
align-inline sets the inline alignment with logical values, start | center | end; wrap chooses the line-breaking strategy, balance by default.
Centered, balanced across two lines when the space runs out
Right-aligned and set to wrap pretty, so no orphan word ends the block
Never wraps — nowrap lets the line overflow instead of breaking
---
import Heading from "tsugite/Heading/Heading.astro";
---
{/* align: left | center | right. wrap: balance (default) | pretty | stable | nowrap. */}
<Heading text="Centered, balanced across two lines when the space runs out" element="h2" size="3" alignInline="center" />
<Heading text="Right-aligned and set to wrap pretty, so no orphan word ends the block" element="h2" size="3" alignInline="end" wrap="pretty" />
<Heading text="Never wraps — nowrap lets the line overflow instead of breaking" element="h2" size="3" wrap="nowrap" />Line length
Every block run is capped at its stop's line length, in ch, on by default (ADR-0021). capInline turns the ceiling off; align moves the capped box; an instance may claim another stop through the ownership chain.
A headline is capped at its own stop's line length, thirty-four characters of its own face here
Centred: the box moves to the middle of the column, not only the words inside it
With the ceiling off the headline runs the whole column, as every heading did before
An instance claiming the h5 ceiling for a longer measure, through the chain
---
import Heading from "tsugite/Heading/Heading.astro";
---
{/* Every block run is capped at its stop's line length (--lineLength-h1 … h6, in ch), on by default.
capInline={false} lets the run take the column. The instance may claim the ceiling through the
ownership chain — a pointer to another stop, never a number in the markup. */}
<Heading element="h2" size="2" text="A headline is capped at its own stop's line length, thirty-four characters of its own face here" />
<Heading element="h2" size="2" alignInline="center" text="Centred: the box moves to the middle of the column, not only the words inside it" />
<Heading element="h2" size="2" capInline={false} text="With the ceiling off the headline runs the whole column, as every heading did before" />
<Heading element="h2" size="2" style="--custom-heading-lineLength: var(--lineLength-h5);" text="An instance claiming the h5 ceiling for a longer measure, through the chain" />Emphasis is flattened
Child content runs through the same engine as prop text. In the loud voices strong and em inherit the run's font — partial bolding of a heading is drift (ADR-0012).
Partial bolding and italics are flattened here
---
import Heading from "tsugite/Heading/Heading.astro";
---
{/* Child content passes through the same engine as prop text. In the loud
voices emphasis is FLATTENED: a heading with one bold word is drift, so
<strong> and <em> inherit the run's font (ADR-0012, law b). */}
<Heading element="h2" size="2">
Partial <strong>bolding</strong> and <em>italics</em> are flattened here
</Heading>Test bench
The typography fixture — every voice × element × size the family allows, mounted unchanged.
Heading
voice: heading, size: 1–6
| h1 | h2 | h3 | h4 | h5 | h6 | p | span | div | |
|---|---|---|---|---|---|---|---|---|---|
| size 1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 |
| size 2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 |
| size 3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 |
| size 4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 |
| size 5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 |
| size 6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 |
| h1 | h2 | h3 | h4 | h5 | h6 | p | span | div | |
|---|---|---|---|---|---|---|---|---|---|
| size 1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 |
| size 2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 |
| size 3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 |
| size 4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 |
| size 5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 |
| size 6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 |
| h1 | h2 | h3 | h4 | h5 | h6 | p | span | div | |
|---|---|---|---|---|---|---|---|---|---|
| size 1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 | h1 |
| size 2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 | h2 |
| size 3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 | h3 |
| size 4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 | h4 |
| size 5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 | h5 |
| size 6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 | h6 |
Display
voice: display, size: 1–3
| h1 | h2 | h3 | h4 | h5 | h6 | p | span | div | |
|---|---|---|---|---|---|---|---|---|---|
| size 1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 |
| size 2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 |
| size 3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 |
| h1 | h2 | h3 | h4 | h5 | h6 | p | span | div | |
|---|---|---|---|---|---|---|---|---|---|
| size 1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 |
| size 2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 |
| size 3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 |
| h1 | h2 | h3 | h4 | h5 | h6 | p | span | div | |
|---|---|---|---|---|---|---|---|---|---|
| size 1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 | d1 |
| size 2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 | d2 |
| size 3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 | d3 |