Типографика

text() рисует кусок текста одним из размеров библиотеки. Вариант подбирает разумный элемент: variant: 'h2' даёт настоящий <h2>, — поэтому заголовки попадают в структуру документа, и думать об этом никому не нужно.

Варианты

Заголовок 1

Заголовок 2

Заголовок 3

Заголовок 4

Заголовок 5

Заголовок 6

Lead — на ступень крупнее основного текста, для фразы под заголовком.

Body — значение по умолчанию.

Small — подписи, которые всё ещё остаются предложениями.

Caption — мелкий шрифт.Overline

stack({ gap: 'sm' },
  text({ variant: 'h1' }, 'Заголовок 1'),
  text({ variant: 'h2' }, 'Заголовок 2'),
  text({ variant: 'h3' }, 'Заголовок 3'),
  text({ variant: 'h4' }, 'Заголовок 4'),
  text({ variant: 'h5' }, 'Заголовок 5'),
  text({ variant: 'h6' }, 'Заголовок 6'),
  text({ variant: 'lead' }, 'Lead — на ступень крупнее основного текста, для фразы под заголовком.'),
  text({ variant: 'body' }, 'Body — значение по умолчанию.'),
  text({ variant: 'small' }, 'Small — подписи, которые всё ещё остаются предложениями.'),
  text({ variant: 'caption' }, 'Caption — мелкий шрифт.'),
  text({ variant: 'overline' }, 'Overline'),
)

Заголовки

heading() принимает level структуры и подбирает соответствующий кегль. size разводит эти две вещи: <h1>, выглядящий как h3, для скринридера остаётся h1.

Заголовок второго уровня со своим кеглем

Заголовок второго уровня с кеглем h5

stack({ gap: 'sm' },
  heading({ level: 2 }, 'Заголовок второго уровня со своим кеглем'),
  heading({ level: 2, size: 'h5' }, 'Заголовок второго уровня с кеглем h5'),
)

Тон

Три степени выразительности — от полного контраста до самого тихого читаемого серого.

По умолчанию — цвет, которым набран основной текст.

Приглушённый — второстепенный текст, всё ещё комфортный для чтения.

Тихий — подписи и метаданные.

stack({ gap: 'xs' },
  text('По умолчанию — цвет, которым набран основной текст.'),
  text({ tone: 'muted' }, 'Приглушённый — второстепенный текст, всё ещё комфортный для чтения.'),
  text({ tone: 'subtle' }, 'Тихий — подписи и метаданные.'),
)

Выравнивание

По началу

По центру

По концу

stack({ gap: 'xs' },
  text({ align: 'start' }, 'По началу'),
  text({ align: 'center' }, 'По центру'),
  text({ align: 'end' }, 'По концу'),
)

Обрезка и ограничение строк

truncate обрезает одну строку многоточием. lines вместо этого ограничивает число строк — обычно именно это и нужно описанию в карточке.

Одна строка, которая тянется далеко за ширину контейнера и обрезается многоточием, вместо того чтобы переноситься.

Ограничено двумя строками. Этот абзац тянется какое-то время, чтобы ограничению было что обрезать, а потом идёт ещё немного дальше — за ту точку, где началась бы третья строка.

stack({ gap: 'md' },
  card({ variant: 'flat' }, cardBody(
    text({ truncate: true }, 'Одна строка, которая тянется далеко за ширину контейнера и обрезается многоточием, вместо того чтобы переноситься.'),
  )),
  card({ variant: 'flat' }, cardBody(
    text({ lines: 2, tone: 'muted' }, 'Ограничено двумя строками. Этот абзац тянется какое-то время, чтобы ограничению было что обрезать, а потом идёт ещё немного дальше — за ту точку, где началась бы третья строка.'),
  )),
)

Код в строке и клавиши

Выполните sitelo build или нажмите ⌘ K для поиска.

text(
  'Выполните ', code('sitelo build'), ' или нажмите ', kbd('⌘'), ' ', kbd('K'), ' для поиска.',
)

Потомки рендерятся как HTML — именно это и позволяет вкладывать что угодно во всей библиотеке, и code() не исключение. Поэтому примеру с тегами нужен проп text, который их экранирует:

<em>Привет</em> — text: показано как написано

Привет — потомки: разобраны как разметка

stack({ gap: 'sm' },
  text(code({ text: '<em>Привет</em>' }), ' — text: показано как написано'),
  text(code('<em>Привет</em>'), ' — потомки: разобраны как разметка'),
)

Полезны оба варианта. text — для примера кода, где тег нужно прочитать, а не построить. Потомки — для уже подсвеченного вывода, где разметка и есть смысл: результат Prism или Shiki попадает туда напрямую.

sitelo build --root docs

sitelo build

stack({ gap: 'sm' },
  text(code({ text: 'sitelo build --root docs' })),
  text(code('<span style="color: var(--su-primary-soft-fg)">sitelo</span> build')),
)

Составление

Text принимает потомков, а не только строку, — поэтому ссылки, код и выделение вкладываются в него ровно так же, как в HTML.

Страницы — это функции, возвращающие HTML. См. руководство написание страниц.

text({ variant: 'lead' },
  'Страницы — это функции, возвращающие ',
  code('HTML'),
  '. См. руководство ',
  link({ href: '/ru/docs/pages' }, 'написание страниц'),
  '.',
)

Смена элемента

as подменяет элемент, не меняя вида, — для визуального заголовка, которому нельзя попадать в структуру, или для <span> внутри строки текста.

Выглядит как заголовок, а это div

Оформление caption на абзаце

stack({ gap: 'xs' },
  text({ variant: 'h4', as: 'div' }, 'Выглядит как заголовок, а это div'),
  text({ variant: 'caption', as: 'p' }, 'Оформление caption на абзаце'),
)

Визуально скрытое

visuallyHidden() оставляет содержимое в дереве доступности, но убирает с экрана: подпись, нужная скринридеру там, где зрячий читатель берёт смысл из контекста.

Состояние сборки: проходит — последняя сборка прошла успешно 4 минуты назад

text(
  'Состояние сборки: ',
  chip({ color: 'success', dot: true }, 'проходит'),
  visuallyHidden(' — последняя сборка прошла успешно 4 минуты назад'),
)

Пропсы

Проп	Тип	По умолчанию	Описание
`variant`	`'h1'…'h6' \| 'lead' \| 'body' \| 'small' \| 'caption' \| 'overline'`	`'body'`	Размер, насыщенность и элемент по умолчанию.
`tone`	`'default' \| 'muted' \| 'subtle'`	`'default'`	Насколько контрастен текст.
`align`	`'start' \| 'center' \| 'end'`	`'start'`	Выравнивание текста.
`truncate`	`boolean`	`false`	Одна строка, обрезанная многоточием.
`lines`	`number`	—	Ограничить таким числом строк.
`as`	`string`	—	Заменяет элемент, который выбрал бы вариант.

heading() принимает level (1–6) и необязательный size; всё остальное так же.