Section Header

A section header opens a region of content. It draws a top border, pads itself above and below, and holds a heading on the left — with room for an action on the right, most often a learn-more link. The header owns the seam between one region and the next, so the content below it starts flush. The .section-header class is required; .section-header-title and the optional .section-header-actions are its two slots.

It is not a Page Header, which names the whole page once, and not a Bar, which is persistent chrome. A section header is content: it repeats down a page, one per region.

Basic usage

Wrap the row in a <header> inside its section. The heading takes .section-header-title, which removes the element's document-flow margins — the row's padding owns that rhythm.

<header class="section-header">
  <h2 class="section-header-title">Recent work</h2>
  <div class="section-header-actions">
    <a class="button" data-variant="text" href="#">Learn more</a>
  </div>
</header>

The actions slot is optional. Without it, the title sits flush left and the row keeps its border and padding.

<header class="section-header">
  <h2 class="section-header-title">Design tokens</h2>
</header>

Heading levels

The heading element sets the size. Choose h2, h3 or h4 for the document outline — the type scale follows the element, so the level is a structural decision, never a styling one.

<header class="section-header">
  <h2 class="section-header-title">Case studies</h2>
  ...
</header>

<header class="section-header">
  <h3 class="section-header-title">Display advertising</h3>
  ...
</header>

<header class="section-header">
  <h4 class="section-header-title">Specifications</h4>
  ...
</header>

Actions

The right-hand slot takes any component. A learn-more link is the common case; a filled button, a pair of buttons, or another compact component all sit the same way. Use an <a> for navigation and a <button> for in-page actions.

<header class="section-header">
  <h3 class="section-header-title">Brand assets</h3>
  <div class="section-header-actions">
    <button class="button" data-variant="outline" data-size="small">Request access</button>
    <button class="button" data-size="small">Download all</button>
  </div>
</header>

On narrow viewports a long title and its actions wrap, keeping --section-header-gap between them; wrapped actions stay right-aligned on their own line, which is intended — the slot holds trailing controls. Keep actions compact — one or two controls. A row that needs more chrome than that is a Bar.

Accessibility

• Pick the heading level from the document outline — one h1 per page, then descend without skipping levels
• Use <a> for actions that navigate and <button class="button"> for actions that do something on the page
• When several generic links ("Learn more") appear on one page, give each an aria-label naming its destination, e.g. aria-label="Learn more about case studies" — screen-reader users browse links out of context
• The <header> element is optional semantics; a <div> is acceptable when the row is not the header of a sectioning element. Inside main or a section, <header> carries no landmark role — but directly under body it becomes a second banner landmark, so never place a section header at body level

Usage rules

Do:

• Use one section header per region of content, inside the section's normal layout hierarchy — section → padding-global → container → the header, with the region's block below it
• Let the heading element (h2/h3/h4) set the size
• Keep the actions slot to one or two compact controls

Don't:

• Don't use a section header as the page's own title — that is the Page Header
• Don't add margins to the title or actions — the row's padding and gap own the spacing
• Don't fill the actions slot with dense chrome (filters, search, toggles) — that is a Bar

CSS reference

This section documents how the component is built. For usage, see the sections above.

Tokens

Selectors

Key rules

• The title's size comes from the heading element itself — the class only zeroes the margins, so h2/h3/h4 each render at their own scale
• Actions align right via margin-inline-start: auto on .section-header-actions, not justify-content: space-between — with no actions present, the title stays flush left with no stray justification behaviour
• flex-wrap: wrap lets title and actions stack on narrow viewports, separated by --section-header-gap; the actions slot also wraps internally so paired buttons never force horizontal scroll
• The title takes min-width: 0 and overflow-wrap: anywhere, so one long unbroken word wraps inside the row instead of overflowing it

Use in another product

The design system installs once per product:

npm install github:bydefaultstudio/design-system-dist#semver:^4.7.0

This component's styles ship in design-system.css. No JavaScript, nothing else to include.