Colour theme

Heading

  • Primitives

  • typography

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
astro
---
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

astro
---
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

astro
---
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.

astro
---
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"
/>

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

astro
---
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

astro
---
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

astro
---
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

Desktop
h1h2h3h4h5h6pspandiv
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
Mobile
h1h2h3h4h5h6pspandiv
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
Floor (≤21.25rem)
h1h2h3h4h5h6pspandiv
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

Desktop
h1h2h3h4h5h6pspandiv
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
Mobile
h1h2h3h4h5h6pspandiv
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
Floor (≤21.25rem)
h1h2h3h4h5h6pspandiv
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