slidev-theme-practicum 0.2.0 → 0.3.0

package/README.md

@@ -6,8 +6,8 @@
 
 1. Откройте [example.md](example.md) и найдите слайд, похожий по задаче.
 2. Скопируйте весь блок слайда от `---` до следующего `---`.
-3. Замените заголовок, текст, пункты или числа. Технические поля лучше не трогать, пока не станет понятно, за что они отвечают.
-4. Проверьте, что смысл слайда читается без фотографии и декоративных элементов.
+3. Замените видимый заголовок и остальной текст в теле слайда, затем пункты или числа. Технические поля лучше не трогать, пока не станет понятно, за что они отвечают.
+4. Проверьте, что тезис, факт, инструкция и вывод читаются без фотографии и декоративных элементов.
 5. Если подходящего примера нет, сначала выберите задачу слайда по таблице ниже.
 
 ## Агентный скилл
@@ -46,6 +46,34 @@ npm install -D slidev-theme-practicum
 theme: practicum
 ```
 
+## Структура проекта колоды
+
+Для презентации, которая использует установленную тему, каноническая точка входа — `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 +97,8 @@ theme: practicum
 
 Заголовок должен отвечать на вопрос «что зритель должен понять сейчас?». Не называйте слайд технически вроде «Метрики» или «Композиция», если можно сразу написать вывод.
 
+В первом headmatter верхнеуровневое поле `title` разрешено: это служебное название всей колоды для HTML-документа и метаданных Slidev, а не содержимое первого слайда. Видимый заголовок всё равно пишите в теле: как `# …` для сокращённой записи или как `<Text as="h1">…</Text>` для явной композиции, включая `cover`. Со второго слайда верхнеуровневое поле `title` запрещено, чтобы метаданные не принимали за отображаемый текст. Вложенные поля `items[].title`, `comparison.from/to.title` и `person.title` остаются частью видимых моделей компонентов и не относятся к этому запрету.
+
 Поясняющий текст нужен для контекста, ограничения или критерия выбора. Если текст превращается в два разных вывода, разнесите его по двум слайдам.
 
 Список работает, когда пункты однотипны: шаги, правила, критерии, темы. Пишите пункты в одинаковой грамматической форме, чтобы их можно было быстро просканировать.
@@ -77,15 +107,19 @@ theme: practicum
 
 Цитата должна быть короткой. Авторство добавляет источник, но не должно конкурировать с самой фразой.
 
-## Семантика декоративных фотографий
+## Семантические роли изображений
 
-Фотографии в шаблонах Практикума всегда декоративные. Они не являются источником фактов, доказательством, инструкцией или объектом, который зритель должен рассматривать ради ключевой информации.
+Роль изображения определяется не форматом файла и не компонентом, а тем, что зритель должен из него понять.
 
-Смысл слайда должен полностью читаться из текста, чисел, подписей, порядка элементов и выбранной композиции. Если фотографию убрать или заменить другой фотографией, вывод слайда не должен измениться.
+| Роль | Назначение | Требование к смыслу |
+|---|---|---|
+| Декоративная фотография | Настроение, ритм, плотность, брендовый характер или пауза | Взаимозаменяема: если её убрать или заменить, вывод слайда не изменится |
+| Сюжетная фотографическая иллюстрация | Конкретная метафора, действие или сквозные персонажи | Не взаимозаменяема внутри сюжета, но не является единственным носителем факта, инструкции или вывода |
+| Информационная фигура | Схема, график, интерфейс, сравнение или доказательство, которое нужно рассмотреть | Существенные данные и вывод продублированы доступной подписью или текстом слайда |
 
-Фото может задавать настроение, визуальный ритм, плотность, брендовый характер или паузу между текстовыми блоками. Оно не должно объяснять метрику, доказывать тезис, заменять подпись или содержать единственный важный контекст.
+Встроенные фотографии темы и выбор через `decor` всегда декоративные. Колода может добавлять собственные сюжетные фотографии в `public/photos/` и размещать их через `Image` или `Slot.background`. В таком случае конкретный сюжетный смысл должен быть назван заголовком, текстом, подписью или доступным описанием: фотография поддерживает рассказ, но не заменяет его.
 
-Не пишите в примерах и документации: «на фото видно», «фото доказывает», «снимки дали контекст», «фотография объясняет число». Такие формулировки ошибочно превращают декоративный слой в информационный.
+Не пишите о декоративной фотографии: «фото доказывает» или «фотография объясняет число». Если зритель действительно должен рассмотреть данные, интерфейс или причинно-следственную схему, это информационная фигура из `public/figures/`, а не декоративный слой.
 
 ## Живая галерея
 
@@ -107,10 +141,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`      | Контракт |
@@ -206,12 +318,14 @@ arrangement: numbered-quartet
 | `arrangement` | компактная перестановка одной модели данных      |
 | `Slot`        | область сетки, поверхность, отступы и медиа-слой |
 | `Text`        | типографика и согласованный подбор размера       |
-| `Image`       | декоративная картинка внутри ручной композиции   |
+| `Image`       | изображение внутри ручной композиции; роль задаёт автор |
 | `decor`       | семантический выбор декоративного изображения    |
-| `background`  | низкоуровневое размещение декоративной картинки  |
+| `background`  | низкоуровневое размещение изображения             |
 
 ## Метаданные слайда
 
+Первый headmatter может содержать верхнеуровневый `title` как служебное название всей колоды. На остальных слайдах валидатор отклоняет этот ключ; основной текст каждого кадра должен находиться в теле слайда.
+
 | Поле          | Значения                                              | По умолчанию    | Смысл                                    |
 | ------------- | ----------------------------------------------------- | --------------- | ---------------------------------------- |
 | `layout`      | `cover`, `message`, `explainer`, `collection`, `none` | значение Slidev | роль слайда или ручная сетка             |
@@ -293,7 +407,8 @@ Slidev парсит markdown внутри компонента только ес
 
 | Свойство или поле  | Тип                                              | По умолчанию | Смысл                             |
 | ------------------ | ------------------------------------------------ | ------------ | --------------------------------- |
-| `src`              | путь                                             | обязательно  | исходное декоративное изображение |
+| `src`              | путь                                             | обязательно  | исходное изображение               |
+| `alt`              | строка                                           | пусто        | доступное описание недекоративного изображения |
 | `fit`              | `cover`, `contain`, `fill`, `none`, `scale-down` | `cover`      | режим заполнения                  |
 | `position`         | позиция CSS                                      | `center`     | позиция изображения               |
 | `zoom`             | число                                            | `1`          | масштаб                           |
@@ -321,7 +436,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 +473,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 +494,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 явно:
 
@@ -418,6 +547,6 @@ npm test
 
 - lint и типы;
 - модульные, контрактные и архитектурные тесты;
-- продукционную сборку и состав её артефактов;
+- продукционную сборку, локальный вариант внешней презентации и состав артефактов;
 - репрезентативные слайды в Chromium, переполнение холста и загрузку медиа по `/theme/...`;
 - состав и размер npm-пакета.

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" />
     </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),
 }))

package/components/StepsGrid.vue

@@ -0,0 +1,112 @@
+<script setup lang="ts">
+import { getCurrentInstance } from 'vue'
+import Text from './Text.vue'
+import TextFitGroup from './TextFitGroup.vue'
+
+type StepItem = {
+  title: string
+  body: string
+  label: string
+  active: boolean
+}
+
+const stepsFitGroup = `steps-${getCurrentInstance()?.uid ?? 'default'}`
+
+const props = defineProps<{
+  items: StepItem[]
+  arrangement: 'linear' | 'staggered'
+}>()
+</script>
+
+<template>
+  <div class="Slide-StepsGrid"
+       :class="`Slide-StepsGrid_${props.arrangement}`"
+       :data-count="props.items.length"
+       :style="{ '--slide-steps-count': props.items.length }">
+    <article v-for="(item, index) in props.items"
+             :key="index"
+             class="Slide-Step"
+             :class="{ 'Slide-Step_active': item.active }"
+             :data-index="index + 1">
+      <Text size="4">{{ item.label }}</Text>
+      <TextFitGroup class="Slide-Step-FitGroup"
+                    :fit-group="`${stepsFitGroup}-titles`">
+        <Text size="3-5">{{ item.title }}</Text>
+      </TextFitGroup>
+      <TextFitGroup v-if="item.body"
+                    class="Slide-Step-FitGroup"
+                    :fit-group="`${stepsFitGroup}-bodies`">
+        <Text size="2-3" priority="2" muted>{{ item.body }}</Text>
+      </TextFitGroup>
+    </article>
+  </div>
+</template>
+
+<style scoped>
+.Slide-StepsGrid {
+  display: grid;
+  width: 100%;
+  max-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);
+}
+
+.Slide-Step {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  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);
+}
+
+.Slide-Step-FitGroup {
+  width: 100%;
+  height: auto;
+  min-width: 0;
+}
+
+.Slide-Step :deep(.TextFitGroup) {
+  width: 100%;
+  height: auto;
+  min-width: 0;
+}
+
+.Slide-StepsGrid_staggered {
+  grid-template-columns: repeat(6, minmax(0, 1fr));
+  grid-template-rows: repeat(2, minmax(0, 1fr));
+}
+
+.Slide-StepsGrid_staggered .Slide-Step:nth-child(1) {
+  grid-area: 1 / 1 / 2 / 3;
+}
+
+.Slide-StepsGrid_staggered .Slide-Step:nth-child(2) {
+  grid-area: 1 / 3 / 2 / 5;
+}
+
+.Slide-StepsGrid_staggered .Slide-Step:nth-child(3) {
+  grid-area: 1 / 5 / 2 / 7;
+}
+
+.Slide-StepsGrid_staggered .Slide-Step:nth-child(4) {
+  grid-area: 2 / 2 / 3 / 4;
+}
+
+.Slide-StepsGrid_staggered .Slide-Step:nth-child(5) {
+  grid-area: 2 / 4 / 3 / 6;
+}
+
+.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);
+}
+</style>

package/composables/deck-decors.ts

@@ -0,0 +1,74 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { extname, isAbsolute, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { parse as parseYaml } from 'yaml'
+import { collectDecorSources, unwrapDecorFile } from './decor-sources'
+
+export const DECK_DECORS_VIRTUAL_ID = 'virtual:practicum-deck-decors'
+export const RESOLVED_DECK_DECORS_VIRTUAL_ID = `\0${DECK_DECORS_VIRTUAL_ID}`
+export const CONVENTION_DECOR_FILES = Object.freeze([
+  'decors.yaml',
+  'decors.yml',
+  'decors.json',
+  'decors.mjs',
+])
+
+const SUPPORTED_EXTENSIONS = new Set(['.yaml', '.yml', '.json', '.mjs', '.js'])
+
+export function resolveDecorFilePath(root: string, spec: string) {
+  const base = resolve(root)
+  const resolved = resolve(base, spec)
+  const rel = relative(base, resolved)
+
+  if (!rel || rel.startsWith('..') || isAbsolute(rel))
+    throw new Error(`Decor catalog path escapes the deck root: ${spec}`)
+
+  return resolved
+}
+
+export function findConventionDecorFile(root: string) {
+  return CONVENTION_DECOR_FILES
+    .map(name => resolve(root, name))
+    .find(path => existsSync(path))
+}
+
+export function collectDeckDecorFiles(input: { decors: unknown, root: string }) {
+  const { files } = collectDecorSources(input.decors)
+
+  if (files.length)
+    return files.map(file => resolveDecorFilePath(input.root, file))
+
+  if (input.decors != null)
+    return []
+
+  const convention = findConventionDecorFile(input.root)
+  return convention ? [convention] : []
+}
+
+export async function loadDecorFile(path: string) {
+  const ext = extname(path).toLowerCase()
+  if (!SUPPORTED_EXTENSIONS.has(ext))
+    throw new Error(`Unsupported decor catalog file: ${path}`)
+
+  if (!existsSync(path))
+    throw new Error(`Decor catalog file not found: ${path}`)
+
+  if (ext === '.mjs' || ext === '.js') {
+    const loadModule = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<Record<string, unknown>>
+    const mod = await loadModule(`${pathToFileURL(path).href}?t=${Date.now()}`)
+    return unwrapDecorFile(mod.decors ?? mod.default)
+  }
+
+  const source = await readFile(path, 'utf8')
+  return unwrapDecorFile(ext === '.json' ? JSON.parse(source) : parseYaml(source))
+}
+
+export async function resolveDeckFileDecors(input: { decors: unknown, root: string }) {
+  const records: Record<string, unknown>[] = []
+
+  for (const path of collectDeckDecorFiles(input))
+    records.push(...await loadDecorFile(path))
+
+  return records
+}

package/composables/decor-sources.ts

@@ -0,0 +1,43 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function isDecorFileRef(value: unknown): value is string {
+  return typeof value === 'string' && Boolean(value.trim())
+}
+
+export function collectDecorSources(value: unknown): {
+  files: string[]
+  inline: Record<string, unknown>[]
+} {
+  if (isDecorFileRef(value))
+    return { files: [value.trim()], inline: [] }
+
+  if (!Array.isArray(value))
+    return { files: [], inline: [] }
+
+  const files: string[] = []
+  const inline: Record<string, unknown>[] = []
+
+  for (const item of value) {
+    if (isDecorFileRef(item))
+      files.push(item.trim())
+    else if (isRecord(item))
+      inline.push(item)
+  }
+
+  return { files, inline }
+}
+
+export function unwrapDecorFile(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value))
+    return value.filter(isRecord)
+
+  if (isRecord(value) && Array.isArray(value.decors))
+    return value.decors.filter(isRecord)
+
+  if (isRecord(value) && typeof value.id === 'string')
+    return [value]
+
+  return []
+}