# Heading

`Heading` composes a framed editorial title, an optional section number and optional metadata with extra space above the title.

## Usage

Load `@dg/ui/styles.css` once in the root layout.

```svelte
<script>
  import { Heading } from "@dg/ui";
</script>

<Heading title="Collection" metadata="12 works · 2026" />
<Heading title="Archive" level={2} num="01" />
```

## Notes

- Native HTML attributes, DOM callbacks, class and style are forwarded to the composed `Section`.
- Forwarding inherits `Section`'s types; unknown props are not supported. Pass class as a string. `Heading` does not render a children snippet or accept gap, which it fixes to 0.
- `Section`'s padding and crosses can also be supplied. Default padding is --space-8 on top with --layout-padding-inline on the sides and --layout-padding-block below. Crosses keep `Section`'s default, all four corners. `Heading` keeps gap=0.
- Metadata wraps below the title when necessary and stays right-aligned. Avoid another framed wrapper around `Heading`.
- The number uses `SectionHead`'s numbering style: compact monospace in the accent color, on the title's baseline at every heading size. Numbers that mirror a contents list should follow its order.

## Parameters

| Name       | Type                         | Default     | Description                                                                               |
| ---------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `title`    | `string`                     | `Required`  | Editorial heading text.                                                                   |
| `level`    | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1`         | Semantic heading level. Its shared --heading-N-size token also supplies the default size. |
| `size`     | `string`                     | `undefined` | Override the visual size independently of the heading level, for example 3rem.            |
| `metadata` | `string`                     | `""`        | Optional metadata aligned opposite the title and allowed to wrap below it.                |
| `num`      | `string`                     | `""`        | Optional section number shown before the title, such as 01. Empty renders no number.      |

## Accessibility

Choose level for semantic hierarchy. The size override changes appearance only. The number is part of the heading text, so it is included in the accessible name. Place `Heading` directly in `Main` or `Page`; it already includes `Section`.