Картинки и иллюстрации

Правила применяются ко всему — к скриншотам в статьях, к иллюстрациям в hero, к логотипам клиентов на marketing-страницах, к SVG-схемам в справочнике.

Цель — чтобы образ работал на чтение, не ломал ритм страницы, не утяжелял загрузку и не размывал бренд.

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

Выбор формата — первое решение. Не «у меня есть PNG» → ставим PNG, а «что должно произойти у читателя» → подбираем носитель.

Что показать	Формат	Почему
Интерфейс платформы, кнопки, экран в действии	PNG-скриншот	Точность важнее веса. PNG режется хорошо, прозрачность не нужна
Графика на главной, hero, иллюстрация раздела	SVG (наш) или AVIF	SVG — масштабируется без потерь; AVIF — для фото-подобной графики
Схемы, диаграммы, таймлайны	SVG (inline или файл)	Текст внутри индексируется и читается скринридерами
Фото людей, реальный кадр производства	JPG (или AVIF)	JPG для фотографий, баланс веса и качества
Логотипы клиентов, партнёров	SVG (на сером фоне — монохром)	Бренды требуют точности линий, SVG — стандарт
Иконка	SVG inline через `<svg>` или Font Awesome через mask	Тонкая работа со штрихом, наследует currentColor

Не путать

Иллюстрация ≠ скриншот. Иллюстрация поясняет идею (нарисованный дашборд в hero, «3D-калькулятор»), скриншот документирует факт («так выглядит вкладка Сотрудники»). Не подменяем одно другим — пользователь почувствует подвох.

Пропорции

Используем только три пропорции. Это даёт согласованный ритм страниц и предсказуемое поведение в гриде.

Пропорция	Где	Пример
16:9 (1.78:1)	Hero-иллюстрации, обзорные скриншоты, видео-плейсхолдеры	720×405, 1280×720, 1920×1080
3:2 (1.5:1)	Карточки-превью разделов, средние скриншоты внутри статей	600×400, 900×600, 1200×800
1:1	Логотипы (в сетке стены), аватарки, мелкие пиктограммы	64×64, 128×128

Произвольные пропорции (например 1280×673) запрещены — они ломают аспект-боксы и заставляют браузер делать прыжок на layout shift.

Минимальные и максимальные размеры

Сценарий	Минимум	Рекомендуемо	Максимум
Иллюстрация в hero	720×405 (16:9)	1280×720	1920×1080
Скриншот в статье	600×400 (3:2)	900×600	1200×800
Иконка в фиче-карточке	24×24	48×48	64×64
Логотип в стене	96×48	128×64	160×80
Превью видео	480×270 (16:9)	720×405	1280×720

Правило «бритвы»

Если скриншот меньше 600 px по ширине — он либо слишком мелкий для статьи (читатель не прочитает текст внутри), либо должен быть SVG (если это не скриншот, а схема).

Обёртки

Все картинки в .vp-doc и .vp-home автоматически попадают в одну из трёх обёрток. Поведение настроено в custom.css:24–55.

`<img>` — markdown-картинка

Это самый частый случай — обычный ![alt](src) без подписи. VitePress оборачивает её в . CSS-правило .vp-doc p:has(> img:only-child) навешивает на этот  нашу стандартную рамку: padding 12px, border 1px brand-tinted, border-radius: var(--vp-home-radius), светлый фон.

markdown

![Так выглядит вкладка Сотрудники в админке](/img/stati/sotrudniki-tab.png)

Использовать по умолчанию для любого скриншота в статье.

`<figure>` — картинка с подписью

Когда нужна подпись:

markdown

<figure>
  <img src="/img/stati/matrica-obucheniya.png"
       alt="Матрица обучения — должность × программа"
       width="900" height="600" loading="lazy" decoding="async" />
  <figcaption>Матрица показывает, какие программы обязательны для каждой должности.</figcaption>
</figure>

Та же рамка, плюс <figcaption> снизу. Подпись — не дублируем alt, а расширяем его: даём смысл, контекст, что делать дальше.

`.vp-content-img-frame` — спец-случай

Если по разметке <img> без  (например, в кастомных Vue-блоках) — оборачиваем в <div class="vp-content-img-frame">. CSS подхватит ту же рамку.

html

<div class="vp-content-img-frame">
  <img src="/img/main.avif" alt="Главная панель Профстандарт"
       width="1280" height="720" loading="eager" decoding="async" />
</div>

Без обёртки — когда

Логотипы в стене клиентов — у каждого свой бордер.
Аватары и круглые миниатюры — оборачиваем сами, рамка темы тут лишняя.
Иконки SVG в кнопках/фичах — это иконки, а не «контентные» картинки.

Загрузка и атрибуты

Каждый <img> должен иметь:

Атрибут	Зачем	Пример
`alt`	Доступность + SEO	`alt="Вкладка Сотрудники в админке"`
`width` `height`	Зарезервировать место — нет layout shift	`width="900" height="600"`
`loading`	`eager` для hero, `lazy` для остального	`loading="lazy"`
`decoding`	`async` всегда — браузер декодирует параллельно	`decoding="async"`

Markdown-синтаксис ![alt](src) не позволяет указать width/height/loading/decoding — поэтому для скриншотов в статьях писать HTML, если важна оптимизация. Для проходных кадров — допустим обычный markdown.

Hero-картинка — loading="eager"

Hero — первое, что видит читатель. Если на ней loading="lazy", она грузится после первого экрана — пустое место. Только eager для hero и lazy для всего остального.

Alt-тексты

Alt — не «alt text», не имя файла, не повторение заголовка.

markdown

<!-- ❌ -->
![alt text](../documentation/upravlenie-strukturoi-10.png)
![](screen.png)
![image-10](../documentation/upravlenie-strukturoi-10.png)

<!-- ✅ -->
![Вкладка «Сотрудники» с фильтром по подразделению](/img/sotrudniki-filter.png)
![Дашборд платформы Профстандарт с тремя статусами обучения](/img/main.avif)

Правило: «что бы я сказал, описывая картинку человеку по телефону».

Для декоративных SVG (фоновая иллюстрация, орнамент) — aria-hidden="true" и пустой alt: alt="".

Цветовое решение

Картинки на маркетинговых страницах часто требуют тонировки — иначе разрозненные стоковые иллюстрации не складываются в одну стилистику.

Сценарий	Что делать
Иллюстрация с брендовым акцентом	Использовать только цвета `#5681c8` и `#4566a0` плюс прозрачности через `color-mix()`
Логотипы клиентов в стене	Все в монохроме — `color-mix(in srgb, var(--vp-c-text-2) 60%, transparent)`; на hover проявляются сильнее
Скриншот реального интерфейса	Без правок — реальный продукт говорит сам за себя
Фото человека / производства	Не правим цвет; если очень нужно — лёгкая sepia/desaturation в JPEG, не CSS-фильтр

CSS-фильтры — не панацея

filter: grayscale(1) на <img> ломает скринридер-поведение и не даёт hover-перехода. Для логотипов лучше готовый монохромный SVG.

Размещение в статьях

Не больше одной картинки на смысловой блок (≈300–500 слов). Картинка идёт после абзаца, который её вводит, не до.

markdown

Вкладка «Сотрудники» — стартовая точка работы с матрицей. Здесь
видны все записи, отфильтрованные по подразделению, должности
и статусу обучения.

![Вкладка «Сотрудники» с фильтром по подразделению](/img/sotrudniki-tab.png)

После открытия вкладки система сразу подгружает список последних
изменений…

Между двумя картинками подряд — запрещено. Если их две, разделите смысловым абзацем («дальше», «затем», «обратите внимание»).

Размещение на маркетинг-страницах

Здесь правила относительно статей слабее:

Hero-иллюстрация — обязательна, занимает 40–50% ширины hero-блока.
В каждой смысловой секции — хотя бы одна графическая опора (иконка, мини-иллюстрация, SVG-схема).
Иллюстрации тариф-карточек, шагов автоматизации, callout-блоков — могут идти подряд, если между ними есть текст и заголовки.

См. design-system/colors.md про брендовый цвет.

Анти-паттерны

Не делать

Маленький скриншот

markdown

<!-- ❌ 320×180 — мелко, ничего не разобрать -->
![alt text](/img/tiny.png)

Если меньше 600px — либо в SVG-схему, либо переснять побольше.

Картинка без alt

Каждый <img> обязан описывать содержимое. Пустой alt — только для декоративных.

Картинка без рамки в `<img>` — не нужно «отключать»

CSS .vp-doc p:has(> img:only-child) уже даёт рамку. Не пытайтесь её перебить inline-стилями — ломаете консистентность.

Размер заданный через `style="width: 800px"`

html

<!-- ❌ -->
<img src="/img/screen.png" style="width: 800px" />

<!-- ✅ -->
<img src="/img/screen.png" width="800" height="450" />

Атрибуты width/height дают аспект-бокс, inline-style — нет. На медленных соединениях это даёт layout shift.

Картинка с прозрачностью на не-белом фоне

PNG с прозрачным фоном на брендовой плашке = превратится в кривой край. Либо непрозрачный фон, либо рисуем SVG со своими цветами.

Чек-лист перед публикацией

✓	Что проверить
☐	Пропорция — 16:9, 3:2 или 1:1, не произвольная
☐	Минимальная ширина выдержана (см. таблицу выше)
☐	Указаны `width` и `height`
☐	`loading="lazy"` (или `eager` для hero)
☐	`decoding="async"`
☐	`alt` — описательный, не повтор заголовка
☐	Один скриншот на смысловой блок
☐	Если декоративная — `aria-hidden="true"` и `alt=""`
☐	Логотипы — монохром
☐	Картинка идёт после вводящего её абзаца

Связанные документы

colors.md — палитра и токены, чтобы тонировать иллюстрации
buttons.md — кнопки на иллюстрациях и поверх них
Редполитика базы знаний — раздел про оформление статей

Картинки и иллюстрации

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

Пропорции

Минимальные и максимальные размеры

Обёртки

`<p><img></p>` — markdown-картинка

`<figure>` — картинка с подписью

`.vp-content-img-frame` — спец-случай

Без обёртки — когда

Загрузка и атрибуты

Alt-тексты

Цветовое решение

Размещение в статьях

Размещение на маркетинг-страницах

Анти-паттерны

Маленький скриншот

Картинка без alt

Картинка без рамки в `<p><img></p>` — не нужно «отключать»

Размер заданный через `style="width: 800px"`

Картинка с прозрачностью на не-белом фоне

Чек-лист перед публикацией

Связанные документы

Картинки и иллюстрации ​

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

Пропорции ​

Минимальные и максимальные размеры ​

Обёртки ​

<p><img></p> — markdown-картинка ​

<figure> — картинка с подписью ​

.vp-content-img-frame — спец-случай ​

Без обёртки — когда ​

Загрузка и атрибуты ​

Alt-тексты ​

Цветовое решение ​

Размещение в статьях ​

Размещение на маркетинг-страницах ​

Анти-паттерны ​

Маленький скриншот ​

Картинка без alt ​

Картинка без рамки в <p><img></p> — не нужно «отключать» ​

Размер заданный через style="width: 800px" ​

Картинка с прозрачностью на не-белом фоне ​

Чек-лист перед публикацией ​

Связанные документы ​

Картинки и иллюстрации

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

Пропорции

Минимальные и максимальные размеры

Обёртки

`<p><img></p>` — markdown-картинка

`<figure>` — картинка с подписью

`.vp-content-img-frame` — спец-случай

Без обёртки — когда

Загрузка и атрибуты

Alt-тексты

Цветовое решение

Размещение в статьях

Размещение на маркетинг-страницах

Анти-паттерны

Маленький скриншот

Картинка без alt

Картинка без рамки в `<p><img></p>` — не нужно «отключать»

Размер заданный через `style="width: 800px"`

Картинка с прозрачностью на не-белом фоне

Чек-лист перед публикацией

Связанные документы