<!-- Protocore Design System — Heading -->
# Heading

- **Category:** Typography (`typography`)
- **Slug:** `typography/heading`
- **Status:** stable
- **Platforms:** web, mobile
- **Import:** `import { Heading } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/typography/heading

> Section heading — sharp, medium-weight, with a tokenised type ramp and matched tracking.

## When to use it

Use `Heading` for every section and subsection title inside a page's content. It is the bridge between the oversized `Display` statement type and ordinary `Text` body copy.

Reach for `Display` instead when you need a single hero statement at the top of a landing view — it is heavier and fluid, and there should be at most one per screen. For the small uppercase kicker that sits *above* a heading, use `Eyebrow`. Always keep the `as` level sequential (an `h2` section, then `h3` subsections) even when you override `size` for visual weight.

## Mobile (React Native)

**Preview.** `@protocore/pds-mobile` ships the React Native sibling of **Heading**. It mirrors the web API where React Native allows; the package is a **preview** with no device-level QA yet, so pin it and expect small changes.

Import it from the mobile package (not `@protocore/pds`), inside a `<PdsProvider>` — there is no stylesheet, so `style` (a `ViewStyle`) replaces `className` and every value comes from the theme:

```tsx
import { Heading } from "@protocore/pds-mobile";
```

**Parity with web.** Same `size` ramp (`title` / `h3` / `h2` / `h1`) as web.

- The web `as` (`h1`–`h6`) prop has no RN analog; heading semantics come from `accessibilityRole="header"`.

```tsx
<Heading size="h2">Deployments</Heading>
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `as` | `enum` | no | `h2` | Heading level element. Defaults to `h2`. |
| `className` | `string` | no | — | — |
| `size` | `enum` | no | `h2` | Type ramp: `title` 24 · `h3` 28 · `h2` 36 · `h1` 56. Default `h2`. |
| `style` | `CSSProperties` | no | — | — |

## Examples

### Basics

`Heading` renders an `h2` at the `h2` scale by default — the workhorse section title.

```tsx
import { Heading, Text } from "@protocore/pds";

export default function HeadingBasics() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
      <Heading>Consensus &amp; finality</Heading>
      <Text color="secondary">How the protocol agrees on a single canonical history.</Text>
    </div>
  );
}
```

### Type ramp

Four steps: `title` (24), `h3` (28), `h2` (36), `h1` (56). Tracking tightens as size grows so large headings stay optically even.

```tsx
import { Heading } from "@protocore/pds";

export default function HeadingRamp() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 20 }}>
      <Heading as="h1" size="h1">
        Ledger 56
      </Heading>
      <Heading as="h2" size="h2">
        Block production 36
      </Heading>
      <Heading as="h3" size="h3">
        Mempool policy 28
      </Heading>
      <Heading as="h4" size="title">
        Gas accounting 24
      </Heading>
    </div>
  );
}
```

## Guidelines

**Do**

- Keep `as` levels sequential for a valid document outline.
- Override `size` (not the element) when you want a different visual weight.
- Pair a `Heading` with an `Eyebrow` above and `Text` lead below for section intros.
- Use `title` size for card and panel headers.

**Don't**

- Don't skip heading levels (`h2` straight to `h4`) to get a size.
- Don't use `Heading` for the page's hero statement — that is `Display`.
- Don't put more than one `h1` in a page.
- Don't restyle a `Heading` with a custom `font-size`; pick the nearest ramp step.

## Accessibility

**Notes**

- Renders a real `h1`–`h6` element, so screen-reader heading navigation and the document outline work as expected.
- `as` (semantic level) is independent of `size` (visual scale) — set the level for meaning, the scale for rhythm.
- Ensure exactly one `h1` per page and no skipped levels in the sequence.

## Related

`display`, `text`, `eyebrow`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/