---
title: Headline
description: Headline renders a single typographic heading with size presets that map to the design system scale.
category: Layout
---

import { meta as HeadlineMeta, Default } from '@/content/stories/headline';
import Canvas from '@/components/component-docs/canvas';
import Demo from '@/components/component-docs/demo';

export const config = {
	dependencies: {
		components: [Canvas, Demo],
		scripts: [
			'../../components/component-docs/demo.script.tsx',
			'../../components/component-docs/canvas.script.tsx',
			'../../components/component-docs/controls.script.tsx',
		],
	},
};


# Headline

<p class="docs-lede">Headline renders a single typographic heading with size presets that map to the design system scale.</p>

## Try it

<Demo of={Default} meta={HeadlineMeta} />

## Usage

Set `as` to the semantic heading level and `size` for visual weight. Use inside `RuiHeadingTitle` or standalone.

```tsx
import { RuiHeadline } from '@ecopages/radiant-ui/headline';

<RuiHeadline as="h1" size="xl">Radiant UI</RuiHeadline>
```

## Pick the right level

<p>Match `as` to the document outline: one `h1` per page, then nest `h2`–`h4` without skipping levels.</p>

## Theming

Headline text maps to the **`on-background`** role, never a palette step:

| Part | CSS roles |
| --- | --- |
| Root | `on-background`, `font-semibold`, `leading-compact` |
| Sizes | `--text-xl` (sm) · `--text-3xl` (md) · `--text-4xl` (lg/xl) |

Sizes come from `--text-*` tokens. Override at the theme layer, not in component CSS.

## Accessibility

- Use semantic heading elements (`h1`–`h6`) via `as` for proper document structure.
- Visual size can differ from semantic level when the outline requires it, but document the intent.
- Do not use headlines purely for styling body text; use paragraph styles instead.

## API

`RuiHeadline` is a presentational JSX view, no custom element.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `h1`–`h6` · `p` · `span` | `h2` | Semantic element. |
| `size` | `sm` · `md` · `lg` · `xl` · `false` | `md` | Type scale; `false` when a parent owns size. |
| `id` | `string` | | Element id. |

### CSS classes

Public BEM classes (documented via `@cssclass`):

| Class | Description |
| --- | --- |
| `.rui-headline` · `--size-sm` · `--size-md` · `--size-lg` · `--size-xl` | Root + size variants. |

### Theme roles

| Part | CSS variables consumed |
| --- | --- |
| Text | `--on-background` |
| Type scale | `--text-xl`, `--text-3xl`, `--text-4xl`, `--leading-compact` |