slidev-theme-practicum 0.2.0 → 0.4.0

package/README.md

@@ -6,8 +6,8 @@
 
 1. Откройте [example.md](example.md) и найдите слайд, похожий по задаче.
 2. Скопируйте весь блок слайда от `---` до следующего `---`.
-3. Замените заголовок, текст, пункты или числа. Технические поля лучше не трогать, пока не станет понятно, за что они отвечают.
-4. Проверьте, что смысл слайда читается без фотографии и декоративных элементов.
+3. Замените видимый заголовок и остальной текст в теле слайда, затем пункты или числа. Технические поля лучше не трогать, пока не станет понятно, за что они отвечают.
+4. Проверьте, что тезис, факт, инструкция и вывод читаются без фотографии и декоративных элементов.
 5. Если подходящего примера нет, сначала выберите задачу слайда по таблице ниже.
 
 ## Агентный скилл
@@ -36,6 +36,64 @@ npm exec -- slidev-practicum-validate path/to/slides.md
 
 В `example.md` у канонических слайдов в заметках автора (`<!-- Контракт … -->`) описано, сколько пунктов и какой вложенности ждёт каждый variant.
 
+## Строгая проверка типографики
+
+Режим включается явно. Обычная проверка и внешний вид существующих макетов сохраняются. Галерея показывает весь API темы, поэтому её варианты с `muted` и несколькими уровнями текста могут не проходить строгую политику.
+
+Правила для содержательного текста слайда:
+
+- Не более двух размеров обычного текста, включая заголовок, подписи, даты и номера шагов.
+- Третий размер разрешён только для явно отмеченных ключевых чисел: `<Text as="data" size="9">42%</Text>`. В этом режиме `as="data"` означает утверждение автора, что это ключевое число. Все такие числа на слайде должны иметь один размер. Содержимое не проверяется на наличие цифр.
+- В каждом `Slot` один цвет текста, без `muted` и токенов `text-muted*`. Между разными слотами цвета могут различаться.
+- Текст должен помещаться в границах содержимого слота. При переполнении измените текст или композицию.
+- Шапка, номер слайда в шапке, логотипы, фоновые и SVG-иллюстрации исключены. Содержательные подписи к иллюстрациям учитываются.
+
+Пример явной композиции: два обычных размера `5` и `3`, отдельный размер `7` для ключевого числа, один основной цвет слота.
+
+```md
+---
+layout: message
+variant: centered
+---
+
+<Slot role="primary">
+  <Text as="h1" size="5">Результат эксперимента</Text>
+  <Text as="data" size="7">42%</Text>
+  <Text size="3">Участники завершили практическое задание</Text>
+</Slot>
+```
+
+Проверка объявленных атрибутов:
+
+```bash
+npm exec -- slidev-practicum-validate slides.md --typography-guard
+```
+
+Она считает только явно объявленные `Text`, сравнивает токены цветов внутри `Slot` и ловит запрещённый `muted`. Диапазон `size="7-8"` считается одной политикой подбора, `max-size` — политикой `0-12`. Литеральные привязки вроде `:size="7"` и `:muted="false"` поддерживаются. Динамические размеры, цвета, теги, стили и условные ветви получают сообщение о невозможности статической проверки. Они не подменяются значениями по умолчанию.
+
+Для итоговой проверки сначала соберите эту же колоду, затем проверьте результат в Chromium:
+
+```bash
+npm install -D playwright-chromium
+npm exec -- slidev build slides.md --out dist
+npm exec -- slidev-practicum-check-typography slides.md --dist dist
+```
+
+Команда ожидает загрузки шрифтов и стабильного подбора текста, проверяет вычисленные размеры и цвета видимых текстовых фрагментов, затем их выход за границы слотов. Учитываются также вложенная разметка, ссылки и текст, созданный сокращёнными Markdown-макетами и компонентами темы. Разные токены одного вычисленного цвета в браузере объединяются. Сообщения содержат номер слайда, фрагмент текста и найденные значения. Нарушение или ошибка отображения дают код выхода `1`.
+
+Используйте свежую сборку указанного файла с корнем сайта `/`. Поддерживаются маршруты `hash` и `history`. Проверяется начальное видимое состояние каждого слайда, без перебора кликов, анимаций и интерактивных состояний. Включения слайдов через `src` пока явно отклоняются. Статический результат не заменяет браузерный. При динамических атрибутах итоговый вердикт даёт браузерная команда для показанного состояния.
+
+Порядок работы агента:
+
+1. Включайте режим, когда он выбран для колоды. При копировании примера из галереи проверяйте его по строгим правилам: сама галерея не гарантирует их соблюдение.
+2. Запустите статическую проверку, затем сборку и браузерную проверку. Если строгая статическая проверка не может вычислить динамические атрибуты, отдельно запустите обычный `slidev-practicum-validate` через `npm exec --` для проверки макетов, а типографику подтвердите браузерной командой. В отчёте укажите эту границу проверки.
+3. Исправляйте замечания в колоде. Если сокращённый макет создаёт `muted` или лишние размеры, используйте явные `Slot` и `Text` либо локальный вариант по контракту темы. Не редактируйте установленный пакет и не маскируйте замечание дополнительным мелким размером.
+4. После исправлений повторите проверку объявлений, пересоберите колоду и проверьте новую сборку. Успех — отсутствие диагностик в применимых проверках и код выхода `0`. Интерактивные состояния проверьте отдельно.
+
+Если команда или флаг отсутствуют, проверьте установленную ревизию `slidev-theme-practicum`: она должна содержать этот режим. Обновите зависимость на нужную ревизию перед проверкой. Отсутствие инструмента не означает, что колода прошла проверку.
+
+В репозитории темы доступны `npm run check-typography -- slides.md --dist dist` и `npm run test:accessibility -- --typography-guard`. Последняя команда проверяет готовую сборку галереи `example.md` с дополнительной строгой политикой. Автоматические проверки самого механизма запускаются через `npm run test:typography` и входят в `npm test`.
+
 Для использования в другой Slidev-презентации:
 
 ```bash
@@ -46,6 +104,36 @@ npm install -D slidev-theme-practicum
 theme: practicum
 ```
 
+Тема не загружает шрифты из сети. Если `YS Text` установлен в системе, браузер использует его локально. Иначе стек последовательно переходит к локальному `Inter`, системному интерфейсному шрифту и `sans-serif`. Поэтому сборка и показ остаются офлайн-воспроизводимыми, но метрики текста без `YS Text` могут немного отличаться. Перед выпуском проверяйте галерею тем же окружением Chromium, которым сформированы пиксельные эталоны.
+
+## Структура проекта колоды
+
+Для презентации, которая использует установленную тему, каноническая точка входа — `slides.md`, а локальные медиа лежат в `public/` и подключаются абсолютным путём от корня сайта:
+
+```text
+<deck>/
+├── slides.md
+├── decors.yaml            # необязательный внешний каталог декора
+├── package.json
+├── package-lock.json
+├── pages/                 # разделы большой колоды
+├── components/            # только компоненты этой колоды
+│   └── layout-variants/   # локальные варианты тематических layout
+├── layouts/               # новые нативные layout самой презентации
+├── snippets/              # импортируемые примеры кода
+├── styles/index.css       # локальные глобальные переопределения
+├── public/
+│   ├── decor/             # графический декор
+│   ├── photos/            # фотографии
+│   ├── illustrations/     # контурные предметы, парные PNG/SVG
+│   └── figures/           # схемы, графики и снимки интерфейса
+└── reference/             # исходники и источники, не входящие в сборку
+```
+
+Создавайте необязательные каталоги только при появлении содержимого. Не заводите параллельные `assets/`, `images/` или `img/`. Фотография остаётся в `photos`, даже если служит фоном; контурный предмет остаётся в `illustrations`, даже если используется как декор. Для файла колоды пишите `/photos/team-workshop.webp`, а не `public/photos/...` и не `/theme/photos/...`. Префикс `/theme` принадлежит только встроенным файлам темы.
+
+Полный контракт структуры, классификации, именования и проверки закреплён в агентном справочнике [deck-project-structure.md](skills/slidev-practicum/references/deck-project-structure.md). Производственный контур сюжетных фотографий описан в [photographic-illustrations.md](skills/slidev-practicum/references/photographic-illustrations.md), а протокол создания парных PNG/SVG для контурных предметов — в [contour-illustrations.md](skills/slidev-practicum/references/contour-illustrations.md).
+
 ## Как выбрать слайд
 
 Выбирайте не по теме презентации, а по задаче кадра.
@@ -69,6 +157,8 @@ theme: practicum
 
 Заголовок должен отвечать на вопрос «что зритель должен понять сейчас?». Не называйте слайд технически вроде «Метрики» или «Композиция», если можно сразу написать вывод.
 
+В первом headmatter верхнеуровневое поле `title` разрешено: это служебное название всей колоды для HTML-документа и метаданных Slidev, а не содержимое первого слайда. Видимый заголовок всё равно пишите в теле: как `# …` для сокращённой записи или как `<Text as="h1">…</Text>` для явной композиции, включая `cover`. Со второго слайда верхнеуровневое поле `title` запрещено, чтобы метаданные не принимали за отображаемый текст. Вложенные поля `items[].title`, `comparison.from/to.title` и `person.title` остаются частью видимых моделей компонентов и не относятся к этому запрету.
+
 Поясняющий текст нужен для контекста, ограничения или критерия выбора. Если текст превращается в два разных вывода, разнесите его по двум слайдам.
 
 Список работает, когда пункты однотипны: шаги, правила, критерии, темы. Пишите пункты в одинаковой грамматической форме, чтобы их можно было быстро просканировать.
@@ -77,15 +167,19 @@ theme: practicum
 
 Цитата должна быть короткой. Авторство добавляет источник, но не должно конкурировать с самой фразой.
 
-## Семантика декоративных фотографий
+## Семантические роли изображений
 
-Фотографии в шаблонах Практикума всегда декоративные. Они не являются источником фактов, доказательством, инструкцией или объектом, который зритель должен рассматривать ради ключевой информации.
+Роль изображения определяется не форматом файла и не компонентом, а тем, что зритель должен из него понять.
 
-Смысл слайда должен полностью читаться из текста, чисел, подписей, порядка элементов и выбранной композиции. Если фотографию убрать или заменить другой фотографией, вывод слайда не должен измениться.
+| Роль | Назначение | Требование к смыслу |
+|---|---|---|
+| Декоративная фотография | Настроение, ритм, плотность, брендовый характер или пауза | Взаимозаменяема: если её убрать или заменить, вывод слайда не изменится |
+| Сюжетная фотографическая иллюстрация | Конкретная метафора, действие или сквозные персонажи | Не взаимозаменяема внутри сюжета, но не является единственным носителем факта, инструкции или вывода |
+| Информационная фигура | Схема, график, интерфейс, сравнение или доказательство, которое нужно рассмотреть | Существенные данные и вывод продублированы доступной подписью или текстом слайда |
 
-Фото может задавать настроение, визуальный ритм, плотность, брендовый характер или паузу между текстовыми блоками. Оно не должно объяснять метрику, доказывать тезис, заменять подпись или содержать единственный важный контекст.
+Встроенные фотографии темы и выбор через `decor` всегда декоративные. Колода может добавлять собственные сюжетные фотографии в `public/photos/` и размещать их через `Image` или `Slot.background`. В таком случае конкретный сюжетный смысл должен быть назван заголовком, текстом, подписью или доступным описанием: фотография поддерживает рассказ, но не заменяет его.
 
-Не пишите в примерах и документации: «на фото видно», «фото доказывает», «снимки дали контекст», «фотография объясняет число». Такие формулировки ошибочно превращают декоративный слой в информационный.
+Не пишите о декоративной фотографии: «фото доказывает» или «фотография объясняет число». Если зритель действительно должен рассмотреть данные, интерфейс или причинно-следственную схему, это информационная фигура из `public/figures/`, а не декоративный слой.
 
 ## Живая галерея
 
@@ -107,10 +201,88 @@ layout: cover | message | explainer | collection | none
 
 Для `layout: message`, `explainer` и `collection` часть `variant` принимает markdown в default slot слайда (`#` заголовок, списки, blockquote, frontmatter) — тема разворачивает его в `Slot` / `Text`. Реестр: `composables/layout-shorthands.ts`.
 
+Для `message:centered` тема выбирает самый крупный помещающийся размер заголовка в диапазоне крупных токенов `7-12`.
+
 Для `message:closing` обязателен один заголовок `# …`; под ним можно добавить один необязательный абзац. Дополнительные абзацы, списки и изображения не поддерживаются.
 
 `layout: cover` markdown shorthand **не** имеет: для всех `cover:*` нужны явные `<Slot role="...">` и `<Text>` (см. обложки в [example.md](example.md)).
 
+Сокращённая Markdown-запись и явные `<Slot role="...">` — два взаимоисключающих режима авторинга одного встроенного варианта. Если в основном слоте есть явный ролевой `Slot`, тема использует ролевые компоненты как готовое содержимое и не разворачивает `items`, `comparison` и другие поля сокращённой записи. Исключение — `collection:agenda`, где разрешён один явный `Slot role="media"` как переопределение иллюстрации. Чтобы `items[].title` или `comparison.from/to.title` попали в визуальный результат, оставьте во входе только поля front matter и канонический Markdown-заголовок; не дублируйте те же данные в `<Text>`.
+
+### Локальные варианты презентации
+
+Slidev уже автоматически подключает Vue-компоненты из `components/` конечной презентации. Их можно использовать тегами прямо в `slides.md`. Локальный вариант нужен для другого случая: повторяющаяся композиция, или архетип, выбирается привычной парой `layout` + `variant`, а содержимое слайда остаётся обычным Markdown без Vue-тегов.
+
+Файл лежит внутри каталога тематического `layout`. Например, `components/layout-variants/explainer/lesson-summary.vue` соответствует `layout: explainer` и `variant: lesson-summary`:
+
+```text
+<deck>/
+├── slides.md
+├── components/
+│   ├── CourseBadge.vue
+│   └── layout-variants/
+│       └── explainer/
+│           └── lesson-summary.vue
+└── layouts/
+    └── workshop.vue
+```
+
+```md
+---
+layout: explainer
+variant: lesson-summary
+badge:
+  text: Практика
+---
+
+# Что запомнить
+
+- Компоненты принадлежат презентации
+- Локальный вариант выбирается через `layout` и `variant`
+```
+
+Vue-файл получает отдельную копию `frontmatter`, защищённую от записи на верхнем уровне, значения `layout` и `variant`, а также разобранный Markdown через основной слот:
+
+```vue
+<script setup lang="ts">
+import type {
+  DeckLayoutVariantProps,
+  DeckLayoutVariantSlots,
+} from 'slidev-theme-practicum/composables/local-layout-variants'
+
+type LessonSummaryFrontmatter = {
+  badge?: {
+    text?: string
+  }
+}
+
+defineProps<DeckLayoutVariantProps<LessonSummaryFrontmatter>>()
+defineSlots<DeckLayoutVariantSlots>()
+</script>
+
+<template>
+  <Slot area="1 / 1 / 9 / 9" surface="light" margin="4" gap="3">
+    <slot />
+  </Slot>
+
+  <Slot area="9 / 9 / -1 / -1" surface="color" margin="3">
+    <CourseBadge :text="frontmatter.badge?.text ?? variant" />
+  </Slot>
+</template>
+```
+
+Компоненты темы (`Slot`, `Text`, `Image`, `Person` и другие) и остальные компоненты презентации внутри такого файла доступны по обычным правилам автоматического подключения Slidev. Корневые `Slot` локального варианта используют ручные `area`, `col` или `row`: поле `role` принадлежит только встроенным рецептам темы.
+
+Правила выбора намеренно строгие:
+
+- первый каталог — один из тематических `cover`, `message`, `explainer` или `collection`, а имя Vue-файла и значение `variant` пишутся в `kebab-case`;
+- встроенный вариант темы нельзя затереть локальным файлом: для локального архетипа выбирайте новое имя `variant`;
+- `arrangement` нельзя добавлять к локальному варианту — дополнительные параметры получают собственные поля front matter;
+- неизвестный `variant` останавливает просмотр, сборку и экспорт с подсказкой до ожидаемого файла;
+- для принципиально нового типа слайда используйте нативный механизм Slidev: `layouts/workshop.vue` и `layout: workshop`. Такой layout не проходит через варианты темы.
+
+`slidev-practicum-validate` проверяет имя, наличие локального варианта и допустимое сочетание полей front matter. Типы и шаблон конкретного Vue-файла дополнительно проверяются обычной типизацией и сборкой презентации.
+
 ### Варианты collection P0
 
 | `variant`     | `arrangement`      | Контракт |
@@ -118,7 +290,7 @@ layout: cover | message | explainer | collection | none
 | `comparison`  | `before-after`     | Markdown heading; `comparison.from` и `comparison.to` с обязательным `title`; необязательные `kicker`, `body` и `relation.label` |
 | `comparison`  | `stable-variable`  | Тот же контракт; вертикальное направление задаёт arrangement |
 | `steps`       | `linear`           | Markdown heading; `items` из 3–6 объектов с обязательным `title`, необязательными `body`, `label`; не больше одного `active: true` |
-| `steps`       | `staggered`        | Тот же контракт, но ровно 5 элементов |
+| `steps`       | `staggered`        | Тот же контракт, но от 2 до 6 элементов; label сверху, title и body снизу |
 | `metrics`     | `dashboard`        | Markdown heading; ровно 5 `metrics` с обязательными `value` и одним из `body`, `label`, `title`; без `media` и произвольных spans |
 | `facts`       | `numbered-quartet` | Markdown heading; ровно 4 пункта вида «значение → вложенная подпись»; номера 1–4 добавляет тема |
 
@@ -206,12 +378,14 @@ arrangement: numbered-quartet
 | `arrangement` | компактная перестановка одной модели данных      |
 | `Slot`        | область сетки, поверхность, отступы и медиа-слой |
 | `Text`        | типографика и согласованный подбор размера       |
-| `Image`       | декоративная картинка внутри ручной композиции   |
+| `Image`       | изображение внутри ручной композиции; роль задаёт автор |
 | `decor`       | семантический выбор декоративного изображения    |
-| `background`  | низкоуровневое размещение декоративной картинки  |
+| `background`  | низкоуровневое размещение изображения             |
 
 ## Метаданные слайда
 
+Первый headmatter может содержать верхнеуровневый `title` как служебное название всей колоды. На остальных слайдах валидатор отклоняет этот ключ; основной текст каждого кадра должен находиться в теле слайда.
+
 | Поле          | Значения                                              | По умолчанию    | Смысл                                    |
 | ------------- | ----------------------------------------------------- | --------------- | ---------------------------------------- |
 | `layout`      | `cover`, `message`, `explainer`, `collection`, `none` | значение Slidev | роль слайда или ручная сетка             |
@@ -222,6 +396,10 @@ arrangement: numbered-quartet
 | `header`      | `default`, `cover`, `none`                            | задаёт макет    | служебный верхний слой                   |
 | `decor`       | объект: `id` или семантический запрос                 | нет             | декоративный слой для сокращённой записи |
 
+Пакет объявляет `slidev.colorSchema: light`: системное переключение светлой и тёмной темы не поддерживается. Значения `mode: dark` и `mode: color` — проверенные семантические варианты отдельных слайдов внутри одной цветовой схемы, а не альтернативные карты для `prefers-color-scheme`. Тёмный и акцентный варианты используют светлый текст, логотип и служебные элементы.
+
+Белый текст на ярких фирменных фонах сохраняется как осознанное визуальное правило. На оранжевом, зелёном и особенно жёлтом тоне отдельные пары не достигают порогов WCAG. Автоматическая проверка продолжает измерять их и выводит число `акцентные исключения`, но разрешает низкий контраст только внутри `mode: color`, `surface: color` и активного шага. Во всех остальных контекстах недостаточный контраст остаётся ошибкой.
+
 ## Slot API
 
 | Свойство                                                     | Тип                                        | По умолчанию  | Смысл                                         |
@@ -259,7 +437,7 @@ arrangement: numbered-quartet
 
 В `Text` можно писать блочный Markdown темы (списки, абзацы, цитаты) — не полный GFM Slidev. Это не layout shorthand: на `cover:*` по-прежнему нужны явные `Slot` / `Text`.
 
-Inline-разметка `**жирный**` сохраняется как `<strong>` и отображается начертанием YS Text Bold с весом `600`.
+Inline-разметка `**жирный**` сохраняется как `<strong>` и отображается доступным локальным полужирным начертанием с весом `600`.
 
 Slidev парсит markdown внутри компонента только если контент **отделён пустой строкой** от открывающего и закрывающего тега (как в [доке Slidev](https://sli.dev/builtin/components)). Без пустых строк список схлопнется в одну строку и сломается. Не добавляйте лишний отступ в 4 пробела у пунктов — Slidev превратит блок в code.
 
@@ -293,7 +471,8 @@ Slidev парсит markdown внутри компонента только ес
 
 | Свойство или поле  | Тип                                              | По умолчанию | Смысл                             |
 | ------------------ | ------------------------------------------------ | ------------ | --------------------------------- |
-| `src`              | путь                                             | обязательно  | исходное декоративное изображение |
+| `src`              | путь                                             | обязательно  | исходное изображение               |
+| `alt`              | строка                                           | пусто        | доступное описание недекоративного изображения |
 | `fit`              | `cover`, `contain`, `fill`, `none`, `scale-down` | `cover`      | режим заполнения                  |
 | `position`         | позиция CSS                                      | `center`     | позиция изображения               |
 | `zoom`             | число                                            | `1`          | масштаб                           |
@@ -321,7 +500,7 @@ Slidev парсит markdown внутри компонента только ес
 
 Встроенные файлы темы доступны по префиксу `/theme`: например, `/theme/photos/photo-6.webp` и `/theme/decor/decor-10.svg`. Файлы из `public` самой колоды остаются пользовательскими и задаются от корня, например `/decor/custom-data.png`; префикс `/theme` к ним добавлять не нужно.
 
-Даже когда используется `Image` или `Slot.background`, фотография остаётся декоративной. Ключевые факты, различия, инструкции и выводы должны быть записаны текстом или числом.
+`Image` и `Slot.background` не определяют семантическую роль. Встроенные `/theme/photos/...` и выбор через `decor` остаются декоративными; собственная фотография колоды из `/photos/...` может быть сюжетной. Для сюжетного `Image` заполняйте `alt`. Фон `Slot.background` скрыт от вспомогательных технологий, поэтому его смысл обязательно дублируется видимым заголовком, текстом или подписью. Ключевые факты, различия, инструкции и выводы в любом случае должны быть записаны текстом, числом или доступной подписью.
 
 ### Decor
 
@@ -358,11 +537,18 @@ themeConfig:
       tone: blue
 ```
 
+```yaml
+themeConfig:
+  decors: ./decors.yaml
+```
+
 ```yaml
 themeConfig:
   deckTitle: 'Название колоды'
   debugGrid: false
   decors:
+    - ./decors/clocks.yaml
+    - ./decors/photos.yaml
     - id: decor-custom-data
       src: /decor/custom-data.png
       meaning: data
@@ -372,14 +558,21 @@ themeConfig:
       ratio: [1.2, 2.7]
 ```
 
+`decors` принимает список записей, путь к файлу или смешанный список путей и записей. Файл может быть YAML, JSON или ESM (`decors.yaml`, `.yml`, `.json`, `.mjs`) и содержать массив записей, объект `{ decors: [...] }` или одну запись. Если `decors` не задан, тема подхватывает `decors.yaml` / `.yml` / `.json` / `.mjs` в корне колоды, если такой файл есть. Позже идущие записи с тем же `id` переопределяют более ранние.
+
+Файл каталога по умолчанию **заменяет** встроенный каталог темы: слоты видят только записи колоды. Короткие inline-записи по умолчанию по-прежнему добавляются к встроенному каталогу. Явный `replaceDecors` перекрывает оба случая.
+
 В записи каталога `cols` и `rows` описывают допустимый размер слота в сетке 12x12, а `ratio` ограничивает соотношение `cols / rows` для ориентации. Вместо `ratio` можно использовать более явный алиас `aspectRatio`.
 
-| Поле              | Тип             | По умолчанию       | Смысл                                                    |
-| ----------------- | --------------- | ------------------ | -------------------------------------------------------- |
-| `deckTitle`       | строка          | заголовок слайда   | заголовок в шапке                                        |
-| `debugGrid`       | boolean         | `false`            | отладочная сетка 12x12                                   |
-| `decors`          | записи каталога | встроенный каталог | добавляет или переопределяет записи декора по `decor.id` |
-| `decorSaveOrigin` | origin URL      | origin dev-сервера | разрешённый origin для сохранения настроек декора         |
+| Поле              | Тип                               | По умолчанию       | Смысл                                                    |
+| ----------------- | --------------------------------- | ------------------ | -------------------------------------------------------- |
+| `deckTitle`       | строка                            | пустая строка      | служебное название колоды в шапке                        |
+| `debugGrid`       | boolean                           | `false`            | отладочная сетка 12x12                                   |
+| `decors`          | записи, путь или список путей     | встроенный каталог | файл заменяет встроенный каталог; inline-записи добавляют или переопределяют по `decor.id` |
+| `replaceDecors`   | boolean                           | `true` для файла каталога | не подмешивать встроенные картинки темы |
+| `decorSaveOrigin` | origin URL                        | origin dev-сервера | разрешённый origin для сохранения настроек декора         |
+
+`themeConfig.deckTitle` задаётся явно и отвечает только за повторяющееся служебное название в шапке. Он не заменяет видимый заголовок конкретного слайда и не берётся из верхнеуровневого `title`.
 
 Если dev-сервер работает за reverse proxy с завершением TLS, задайте внешний origin явно:
 
@@ -398,7 +591,7 @@ Endpoint сохранения принимает только точное зн
 | `light-1`  | `#f0f0f0` |
 | `dark-0`   | `#1e1e1e` |
 | `dark-1`   | `#3c3c3c` |
-| `dark-2`   | `#969696` |
+| `dark-2`   | `#646464` |
 | `blue-0`   | `#027ef2` |
 | `blue-1`   | `#98d2fe` |
 | `orange-0` | `#ff6c26` |
@@ -418,6 +611,16 @@ npm test
 
 - lint и типы;
 - модульные, контрактные и архитектурные тесты;
-- продукционную сборку и состав её артефактов;
+- продукционную сборку, локальный вариант внешней презентации и состав артефактов;
 - репрезентативные слайды в Chromium, переполнение холста и загрузку медиа по `/theme/...`;
-- состав и размер npm-пакета.
+- контраст всех видимых текстовых пар, семантику медиа и `alt`, видимый фокус, `prefers-reduced-motion` и отсутствие внешних запросов;
+- точное совпадение всех 47 слайдов `example.md` с PNG-эталонами при зафиксированных Chromium, viewport, DPR, sRGB и доступности локальных шрифтов;
+- состав и размер npm-пакета, затем установку созданного локального архива во временную внешнюю презентацию, её сборку, показ без внешних запросов и ресурсы `/theme/...`.
+
+## Обновление пиксельных эталонов
+
+Пиксельные эталоны меняются только осознанно после визуального просмотра результата:
+
+```bash
+npm run test:pixels:update
+```

package/components/Slide.vue

@@ -1,11 +1,13 @@
 <script setup lang="ts">
 import { computed, defineComponent, h, isVNode, onBeforeUnmount, onMounted, onUpdated, shallowRef, unref, useSlots, type PropType, type VNode } from 'vue'
 import { useSlideContext } from '@slidev/client'
+import { DECK_LAYOUT_VARIANTS } from 'virtual:practicum-deck-layout-variants'
 import DebugGrid from './DebugGrid.vue'
 import Header from './Header.vue'
 import Image from './Image.vue'
 import Person from './Person.vue'
 import Slot from './Slot.vue'
+import StepsGrid from './StepsGrid.vue'
 import Text from './Text.vue'
 import Timeline from './Timeline.vue'
 import { createSlideLayout } from '../composables/slide-layout'
@@ -47,9 +49,11 @@ const slideLayout = createSlideLayout({
     Image,
     Person,
     Slot,
+    StepsGrid,
     Text,
     Timeline,
   },
+  layoutVariants: DECK_LAYOUT_VARIANTS,
 })
 
 const layoutContractLabel = computed(() => {
@@ -60,12 +64,14 @@ const layoutContractLabel = computed(() => {
 
 function reportLayoutContractError(error: SlideMarkdownContractError) {
   const lines = [
-    `[Slidev] Слайд ${$page ?? '?'}: ${layoutContractLabel.value}`,
+    `[Slidev] Слайд ${unref($page) ?? '?'}: ${layoutContractLabel.value}`,
     error.message,
   ]
   if (error.hint)
     lines.push(`  Подсказка: ${error.hint}`)
-  lines.push('  См. example.md в slidev-theme-practicum (блоки «Контракт»).')
+  lines.push(error.hint?.includes('components/layout-variants/')
+    ? '  См. README.md в slidev-theme-practicum, раздел «Локальные варианты презентации».'
+    : '  См. example.md в slidev-theme-practicum (блоки «Контракт»).')
   console.error(lines.join('\n'))
 }
 
@@ -89,6 +95,7 @@ function compileCurrentAuthoring(children?: readonly VNode[]) {
 const authored = computed(() => compileCurrentAuthoring())
 const resolvedLayout = computed(() => authored.value.layout)
 const isLayoutMode = computed(() => authored.value.mode === 'layout')
+const isCompiledMode = computed(() => authored.value.mode !== 'manual')
 const resolvedVariant = computed(() => authored.value.variant)
 const resolvedHeader = computed(() => authored.value.header)
 const resolvedTheme = computed(() => authored.value.theme)
@@ -187,14 +194,14 @@ const slideClass = computed(() => ({
              :class="slideClass"
              :style="slideStyle">
     <div class="Slide-Header">
-      <slot v-if="!isLayoutMode && slots.header" name="header" />
+      <slot v-if="!isCompiledMode && slots.header" name="header" />
       <Header v-else-if="resolvedHeader !== 'none'"
               :variant="resolvedHeader === 'cover' ? 'cover' : 'default'"
-              :inverted="isContrast" />
+              :inverted="resolvedTheme.foreground === 'light'" />
     </div>
     <DebugGrid v-if="showDebugGrid" />
     <div class="Slide-Grid">
-      <slot v-if="!isLayoutMode" />
+      <slot v-if="!isCompiledMode" />
       <LayoutBody v-else>
         <slot />
       </LayoutBody>
@@ -382,59 +389,6 @@ const slideClass = computed(() => ({
   line-height: var(--theme-text-line-5);
 }
 
-:deep(.Slide-StepsGrid) {
-  display: grid;
-  width: 100%;
-  height: 100%;
-  min-width: 0;
-  min-height: 0;
-  grid-template-columns: repeat(var(--slide-steps-count), minmax(0, 1fr));
-  gap: var(--theme-grid-gap);
-}
-
-:deep(.Slide-Step) {
-  display: flex;
-  min-width: 0;
-  min-height: 0;
-  flex-direction: column;
-  gap: calc(var(--theme-grid-module) * 2);
-  padding: var(--theme-slot-margin-3);
-  border-radius: var(--theme-panel-radius);
-  background: var(--theme-surface-light);
-}
-
-:deep(.Slide-StepsGrid_staggered) {
-  grid-template-columns: repeat(6, minmax(0, 1fr));
-  grid-template-rows: repeat(2, minmax(0, 1fr));
-}
-
-:deep(.Slide-StepsGrid_staggered .Slide-Step:nth-child(1)) {
-  grid-area: 1 / 1 / 2 / 3;
-}
-
-:deep(.Slide-StepsGrid_staggered .Slide-Step:nth-child(2)) {
-  grid-area: 1 / 3 / 2 / 5;
-}
-
-:deep(.Slide-StepsGrid_staggered .Slide-Step:nth-child(3)) {
-  grid-area: 1 / 5 / 2 / 7;
-}
-
-:deep(.Slide-StepsGrid_staggered .Slide-Step:nth-child(4)) {
-  grid-area: 2 / 2 / 3 / 4;
-}
-
-:deep(.Slide-StepsGrid_staggered .Slide-Step:nth-child(5)) {
-  grid-area: 2 / 4 / 3 / 6;
-}
-
-:deep(.Slide-Step_active) {
-  background: var(--theme-current-color);
-  color: var(--theme-text-on-dark);
-  --theme-text: var(--theme-text-on-dark);
-  --theme-text-muted: var(--theme-text-muted-on-contrast);
-}
-
 :deep(.Slide-Quote) {
   max-width: var(--theme-grid-span-11-width);
   font-size: var(--theme-text-size-7);

package/components/Slot.vue

@@ -96,7 +96,7 @@ const props = withDefaults(defineProps<{
 const slotId = `theme-slot-${Math.random().toString(36).slice(2, 10)}`
 const instance = getCurrentInstance()
 const placementSession = useSlotPlacementSession()
-const { defaultTone, deckTitle, decors } = useThemeConfig()
+const { defaultTone, deckTitle, decors, replaceDecors } = useThemeConfig()
 const { $slidev } = useSlideContext()
 const resolvedRect = shallowRef<ResolvedSlotPlacement['rect'] | null>(null)
 const resolvedFootprint = shallowRef<ResolvedSlotPlacement['footprint'] | null>(null)
@@ -208,6 +208,7 @@ const decorSeed = computed(() => [
 ].filter(Boolean).join('|'))
 
 const media = computed(() => createThemeMedia({
+  ...(replaceDecors.value ? { baseCatalog: [] } : {}),
   themeCatalog: decors.value,
   warn: (message: string) => console.warn(message),
 }))
@@ -333,8 +334,8 @@ const surfaceClass = computed(() => {
 
 .Slot_surface_color {
   background: var(--theme-slot-color, var(--theme-current-color));
-  --theme-text: var(--theme-text-on-dark);
-  --theme-text-muted: var(--theme-text-muted-on-contrast);
+  --theme-text: var(--theme-text-on-color);
+  --theme-text-muted: var(--theme-text-muted-on-color);
   --theme-inline-code-text: var(--theme-text);
   color: var(--theme-text);
 }