# Heading: Руководства

## Паттерны

### Заголовок раздела

Когда использовать:

- странице или панели нужен видимый структурный заголовок

Заметки о композиции:

- сначала выберите `as` по структуре документа
- затем выберите `size` по визуальному ритму

Компромиссы:

- сохраняет и семантику, и визуальную гибкость
- требует дисциплины, когда заголовков несколько

```tsx
import { Heading, Text } from '@vega-ui/react';

export default function DocumentOutline() {
  return (
    <article style={{ display: 'grid', gap: 'var(--spacing-12)', width: '100%', maxWidth: '60ch' }}>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Heading as='h1'>Getting started</Heading>
        <Text size={3} style={{ color: 'var(--label-secondary)' }}>Set up your workspace in three steps.</Text>
      </div>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Heading as='h2'>Invite your team</Heading>
        <Text size={3}>Members get access to every public project.</Text>
      </div>
      <div style={{ display: 'grid', gap: 'var(--spacing-3)' }}>
        <Heading as='h3'>Roles and permissions</Heading>
        <Text size={3}>Admins manage billing; editors can create projects.</Text>
      </div>
    </article>
  );
}
```

### Компактная иерархия в плотных панелях

Когда использовать:

- плотной странице настроек нужны визуально меньшие заголовки без смены семантического уровня

Заметки о композиции:

- сохраняйте правильный `as`
- уменьшайте `size`, только если иерархия остаётся понятной

Компромиссы:

- экономит место
- при злоупотреблении может ослабить визуальную иерархию

```tsx
import { Card, Heading, Text } from '@vega-ui/react';

const keys = [
  { name: 'Production', created: 'Created Jan 12', lastUsed: 'Used 2 minutes ago' },
  { name: 'CI pipeline', created: 'Created Feb 3', lastUsed: 'Used yesterday' },
];

export default function CompactHierarchyInDensePanels() {
  return (
    <Card asChild size='sm' style={{ display: 'grid', gap: 'var(--spacing-6)', width: '100%' }}>
      <section aria-labelledby='api-keys-title'>
        <Heading as='h3' size={4} id='api-keys-title'>API keys</Heading>
        {keys.map((key) => (
          <div key={key.name} style={{ display: 'grid', gap: 'var(--spacing-1)' }}>
            <Heading as='h4' size={3} fontWeight={500}>{key.name}</Heading>
            <Text size={2} style={{ color: 'var(--label-secondary)' }}>{key.created} · {key.lastUsed}</Text>
          </div>
        ))}
      </section>
    </Card>
  );
}
```

### Заголовок с поясняющим текстом

Когда использовать:

- заголовку раздела нужно короткое описание

Заметки о композиции:

- оставляйте в `Heading` только заголовок
- поясняющий текст размещайте в `Text`

Компромиссы:

- чёткое разделение ролей
- нужен один дополнительный текстовый элемент

`<hgroup>` связывает описание с заголовком, не делая его частью текста заголовка.

```tsx
import { Heading, Text } from '@vega-ui/react';
import type { CSSProperties } from 'react';

export default function HeadingWithSupportingCopy() {
  return (
    <hgroup style={{ display: 'grid', gap: 'var(--spacing-2)', width: '100%', margin: 0 }}>
      <Heading as='h2' size={6}>Billing contacts</Heading>
      <Text asChild size={3} style={{ '--t-color': 'var(--label-secondary)' } as CSSProperties}>
        <p>Invoices and payment reminders are sent to these people.</p>
      </Text>
    </hgroup>
  );
}
```

## Сравнение

### Быстрое правило выбора

Используйте `Heading`, когда текст задаёт структуру документа или раздела. Используйте `Text` для основного текста и `Label` для полей формы.

### `Heading` и `Text`

- Используйте `Heading` для навигируемой структуры разделов.
- Используйте `Text` для основного текста.

### `Heading` и `Label`

- Используйте `Heading` для разделов или страниц.
- Используйте `Label` для одного элемента управления.

### `Heading` и `FieldsetLegend`

- Используйте `Heading` для структуры документа.
- Используйте `FieldsetLegend` для подписи нативной группы полей формы.

### Выбирайте этот компонент, когда

- содержимое должно попасть в структуру страницы или раздела
- визуальный размер и семантический уровень должны оставаться независимыми

### Не выбирайте этот компонент, когда

- текст подписывает поле формы
- содержимое — просто описательный текст

## Решение проблем

### Интерфейс выглядит структурированным, но скринридеры не видят заголовков

#### Симптом

Крупный стилизованный текст визуально выглядит как заголовки разделов, но вспомогательные технологии не объявляют заголовки.

#### Вероятная причина

Вместо `Heading` использован `Text` или обычный элемент.

#### Как проверить

- изучите отрендеренный элемент
- убедитесь, что это не `h1`–`h6`

#### Исправление

Используйте `Heading` и выберите правильный уровень `as`.

### Иерархия заголовков выглядит сломанной

#### Симптом

Пользователи видят заголовки, но структура документа скачет непредсказуемо.

#### Вероятная причина

Уровни заголовков выбраны по желаемому размеру шрифта, а не по структуре.

#### Как проверить

- прочитайте по порядку только уровни заголовков
- убедитесь, что они образуют логичную структуру

#### Исправление

Сначала задайте `as` по иерархии документа, затем подстройте `size` под внешний вид.

### Заголовки и подписи перепутаны

#### Симптом

И разделы формы, и отдельные поля используют один и тот же примитив заголовка, из-за чего семантика неясна.

#### Вероятная причина

`Heading` используется там, где нужны `Label` или `FieldsetLegend`.

#### Как проверить

- выясните, называет ли текст одно поле или целый раздел

#### Исправление

Используйте `Label` для отдельных элементов управления и `FieldsetLegend` для групп.