Heading

Install and import

Heading is in @dovetail-ds/react. Install it with React, if you haven't:

Guidelines

A heading whose level and size are two props. level sets the tag, so the document outline stays honest; size sets the type role, so the page can still look the way it should.

Use it when

• Any heading on a page: a hero title, a section title, a card title that needs to be a real heading.
• A headline or a key number should be poster-sized: display-xl and display-2xl are fluid, largest on a wide screen and shrinking to fit a phone. Keep them to one per screen.
• The visual size and the outline disagree. A hero's one h1 is often set at display-md; a product name inside a card is an h3 set at heading-sm.

Don't use it when

• The text is a label, not a heading. An eyebrow above a title is Text variant="eyebrow", not a small heading.
• It sits inside Prose. Prose styles plain h2 and h3 itself.

Example

<Stack gap="sm">
  <Text variant="eyebrow">New season</Text>
  <Heading level={1} size="display-md">Built for the trail</Heading>
  <Text variant="lead">Four days, three huts, one pack.</Text>
</Stack>

One h1 per page. Do not skip levels to get a smaller size; pick the right level and pass size.

Tone

tone defaults to headline, which reads --dt-text-headline. That role is ink until a theme or Configure's Headline colour sets it to a brand colour, and then every heading follows at once. A brand, photo or dark Section re-points it for its own surface, so a heading in a band still reads correctly without a prop.

brand and brand-secondary set a single heading in a brand colour, through --dt-text-brand and --dt-text-brand-secondary, while the rest stay as they are. Both are text roles, tuned for text contrast in light and dark mode. inherit takes the parent's colour, for a heading inside a coloured block you built by hand rather than with Section.

<Heading level={1} size="display-md" tone="brand">Built for the trail</Heading>

Tokens

--dt-text-{size}-family, -size, -line, -weight, -tracking, --dt-text-headline, --dt-text-brand, --dt-text-brand-secondary, and --dt-measure-* when measure is set. A display face and a headline colour chosen in Configure reach every heading through these roles.

Props

The typed contract, from Heading.d.ts.

import * as React from "react";

/**
 * A heading whose document level and visual size are set separately, so a
 * page's outline and its scale can differ on purpose: an h2 set at display
 * size for a hero, an h3 set small inside a card.
 */
export interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
  /** Sets the tag, h1 to h6. @default 2 */
  level?: 1 | 2 | 3 | 4 | 5 | 6;
  /** The type role it is set in. Defaults by level: 1 heading-xl, 2 heading-lg, 3 heading-md, 4 heading-sm, 5 and 6 heading-xs. display-xl and display-2xl are fluid: they shrink with the screen, so a poster-sized headline or number still fits at 390px. */
  size?: "display-2xl" | "display-xl" | "display-lg" | "display-md" | "display-sm" | "heading-xl" | "heading-lg" | "heading-md" | "heading-sm" | "heading-xs";
  /**
   * headline reads --dt-text-headline: ink unless a theme sets headlines in a
   * brand colour, and re-pointed by a brand, photo or dark Section so it
   * follows the band. brand and brand-secondary set this one heading in a
   * brand text colour. inherit takes the colour of its parent, for a heading
   * inside a hand-built coloured block. @default "headline"
   */
  tone?: "headline" | "brand" | "brand-secondary" | "primary" | "secondary" | "inherit";
  align?: React.CSSProperties["textAlign"];
  /** Bounds the line length. @default "none" */
  measure?: "narrow" | "default" | "wide" | "none";
  /** Balances the lines, so a two-line heading does not end on one word. @default true */
  balance?: boolean;
  children?: React.ReactNode;
}

export declare function Heading(props: HeadingProps): React.JSX.Element;

Tokens it reads

Every custom property Heading.jsx resolves, read from the source: 150 semantic, 4 primitive. Component tier first, because that is the one to reach for.

Open the graph

• semantic Shared roles. Override one and everything using that role moves with it.
• primitive Raw values. A component reading one directly is a deliberate exception.

Source

React only, no dependencies, every value a token.

import React from "react";

const DEFAULT_SIZE = { 1: "heading-xl", 2: "heading-lg", 3: "heading-md", 4: "heading-sm", 5: "heading-xs", 6: "heading-xs" };
const SIZES = ["display-2xl", "display-xl", "display-lg", "display-md", "display-sm", "heading-xl", "heading-lg", "heading-md", "heading-sm", "heading-xs"];
const TONES = {
  headline: "var(--dt-text-headline, var(--dt-text-primary))",
  brand: "var(--dt-text-brand, var(--dt-text-link))",
  "brand-secondary": "var(--dt-text-brand-secondary, var(--dt-color-secondary-700, var(--dt-text-link)))",
  primary: "var(--dt-text-primary)",
  secondary: "var(--dt-text-secondary)",
  inherit: "inherit",
};
const MEASURES = { narrow: "var(--dt-measure-narrow)", default: "var(--dt-measure-default)", wide: "var(--dt-measure-wide)", none: "none" };

export function Heading({ level = 2, size, tone = "headline", align, measure = "none", balance = true, children, style, ...rest }) {
  const lvl = Math.min(6, Math.max(1, Number(level) || 2));
  const Tag = "h" + lvl;
  const role = SIZES.indexOf(size) !== -1 ? size : DEFAULT_SIZE[lvl];
  return (
    <Tag
      style={{
        margin: 0,
        fontFamily: `var(--dt-text-${role}-family)`,
        fontSize: `var(--dt-text-${role}-size)`,
        lineHeight: `var(--dt-text-${role}-line)`,
        fontWeight: `var(--dt-text-${role}-weight)`,
        letterSpacing: `var(--dt-text-${role}-tracking)`,
        color: TONES[tone] || TONES.headline,
        textAlign: align,
        maxWidth: MEASURES[measure] || MEASURES.none,
        textWrap: balance ? "balance" : undefined,
        ...style,
      }}
      {...rest}
    >
      {children}
    </Tag>
  );
}