Heading + subtitle pair

Quick implementation

.heading-pair {
  display: flex;
  flex-direction: column;
}

.heading-pair .heading {
  font-family: var(--font-display);
  font-size: clamp(1.4rem, 3vw, 2rem);
  font-weight: 800;
  color: var(--text);
  margin-block: 0;
  line-height: 1.1;
  letter-spacing: -0.02em;
}

.heading-pair .subtitle {
  font-family: var(--font-body);
  font-size: 1rem;
  font-weight: 400;
  color: var(--muted);
  margin-block: 0.5em 0;
  line-height: 1.5;
}

/* Hero variant — larger type scale */
.heading-pair--hero .heading {
  font-size: clamp(2rem, 5vw, 3.5rem);
}
.heading-pair--hero .subtitle {
  font-size: clamp(1rem, 2vw, 1.25rem);
  margin-block-start: 0.6em;
}

/* Card variant — tighter scale */
.heading-pair--card .heading {
  font-size: 1.125rem;
}
.heading-pair--card .subtitle {
  font-size: 0.875rem;
  margin-block-start: 0.35em;
}

Prompt this to your LLM

Includes role, goal, constraints, variants, and edge cases for a complete heading+subtitle system.

You are a senior frontend engineer building a typography system for a
dark-mode design system.

Goal: A reusable .heading-pair component that pairs a heading element
with a subtitle at multiple size scales (hero, section, card) — no
JavaScript, no layout frameworks.

Technical constraints:
- Use a flex column container (.heading-pair) with margin-block on the
  subtitle (not the heading) to control the gap between them. This
  avoids margin collapse surprises and keeps spacing relative to the
  subtitle's font size.
- heading uses font-family: var(--font-display), subtitle uses
  font-family: var(--font-body). Never swap them.
- The size ratio between heading and subtitle should be approximately
  1.6:1 at each scale (hero: 3.5rem / 1.25rem, section: 2rem / 1rem,
  card: 1.125rem / 0.875rem).
- Use clamp() for the hero and section heading to allow fluid scaling.
- heading color: var(--text) (bright). subtitle color: var(--muted)
  (secondary). Use oklch() if defining custom colors — no hex or rgba.
- margin-block: 0 on both elements so the container controls all spacing.
- line-height: 1.1 on the heading (tight for display type), 1.5 on
  the subtitle (open for readability).
- letter-spacing: -0.02em on the heading to tighten display sizes.

Variants to generate:
A) .heading-pair--hero — hero section at the top of a page.
B) .heading-pair--section — mid-page content section heading.
C) .heading-pair--card — compact card or widget header.

Edge cases to handle:
- If the subtitle wraps to multiple lines, margin-block-start: 0.5em
  keeps the gap proportional regardless of subtitle length.
- Avoid using <hgroup> unless the subtitle is a true document subtitle;
  two <p> elements inside .heading-pair are semantically safer for
  most UI patterns where the subtitle is descriptive, not structural.
- When the heading color changes (e.g. an accent variant), the subtitle
  color should stay muted — never inherit the heading color.

Return CSS only.

Spacing: why margin-block on the subtitle

The gap between a heading and its subtitle looks simple but has a subtle trap: margin collapse. If you set margin-bottom on the heading and margin-top on the subtitle inside a block container, the two margins collapse into one — whichever is larger wins. The result is unpredictable spacing that shifts when the font size changes.

The fix is to make .heading-pair a flex container with flex-direction: column. Flex containers suppress margin collapse entirely. Set margin-block: 0 on both the heading and subtitle, then add only margin-block-start on the subtitle. This puts full control in one place: the subtitle's top margin controls the gap, the heading's block margins are both zero, and nothing collapses.

Using margin-block-start: 0.5em (an em unit, not rem) on the subtitle is intentional. It scales relative to the subtitle's own font-size, so a 1.25rem subtitle gets a slightly larger gap than a 0.875rem card subtitle — proportional spacing at every scale without writing separate gap values for each variant.

The size ratio

A reliable heading-to-subtitle ratio is roughly 1.6:1 — the same proportion as the golden ratio. At the hero scale that looks like clamp(2rem, 5vw, 3.5rem) for the heading and clamp(1rem, 2vw, 1.25rem) for the subtitle. At the card scale it looks like 1.125rem heading to 0.875rem subtitle — a 1.3:1 ratio, slightly tighter because small type needs less contrast to read as two levels.

The color split reinforces the hierarchy: heading in var(--text) (full brightness) and subtitle in var(--muted) (reduced contrast). Even if both were the same size, the color alone would signal which is primary. Combined with the size ratio, the visual hierarchy is immediately readable without any extra weight, border, or separator needed.

When to use hgroup

The HTML <hgroup> element groups a heading with one or more paragraphs of supplementary content — but its semantics are narrower than they look. According to the HTML spec, <hgroup> is appropriate when the subtitle is a document-level subtitle that modifies the heading's rank in the outline, such as a chapter subtitle in a book or a tagline for a page title.

For most UI patterns — a card header, a section intro, a feature block — the "subtitle" is a descriptive blurb, not a structural document subtitle. Two <p> elements inside .heading-pair are semantically safer: they carry no implied outline relationship, they don't confuse screen readers that expect <hgroup> children to modify heading rank, and they're easier to style independently.

Use <hgroup> when you genuinely have a page-level heading like "Moby Dick" paired with a subtitle like "Or, the Whale" — where the subtitle is inseparable from the heading's identity. Use .heading-pair with two <p> elements everywhere else.