# Heading

## Essence

Semantic section title component for Portfolio Design System content hierarchy.

`Heading` renders one of the approved heading levels and applies the matching heading typography token with the primary text color.

## Hook

Use when content needs a page, section, or subsection title.

## Internal Rules

- Supports levels `1`, `2`, `3`, `4`, and `5`.
- Level maps directly to the semantic HTML heading element.
- Level `1` renders `h1`, level `2` renders `h2`, and so on.
- Invalid levels fall back to level `1`.
- Uses Heading typography tokens.
- Uses `--color-text`.
- Does not own spacing around itself.
- Does not replace body copy, captions, labels, or links.

## Use When

- A page needs a main title.
- A section needs a scannable heading.
- Content hierarchy needs to be explicit for humans and agents.

## Do Not Use When

- Normal reading text is needed; use `Paragraph`.
- Small supporting metadata is needed; use `Caption`.
- Text should navigate; use `Link`.
- Text is only visual emphasis without structural meaning.

## Edge Cases

- Prefer one level `1` heading per page context.
- Do not skip heading levels unless the page structure requires it.
- Long headings should wrap cleanly in narrow layouts.
- Use heading level for structure, not just visual size.

## Accessibility Notes

- Semantic heading order helps screen-reader navigation.
- Heading text should describe the section it introduces.
- Avoid empty headings.
- Do not use headings only to make text look larger.

## Related Components And Patterns

- `Paragraph`: normal body copy under headings.
- `Caption`: supporting metadata near content.
- `Link`: text navigation, not section structure.
- Typography tokens: define heading scale and line height.

## Code Paths

- `packages/design-system/src/components/Heading.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`