slidev-theme-practicum

Тема Slidev для презентаций Практикума. Этот README в первую очередь помогает автору слайдов выбрать подходящий тип кадра и понять, что на нём писать. Технические поля и API описаны ниже, для тех, кто редактирует разметку руками.

Быстрый маршрут для автора

1. Откройте example.md и найдите слайд, похожий по задаче.
2. Скопируйте весь блок слайда от --- до следующего ---.
3. Замените заголовок, текст, пункты или числа. Технические поля лучше не трогать, пока не станет понятно, за что они отвечают.
4. Проверьте, что смысл слайда читается без фотографии и декоративных элементов.
5. Если подходящего примера нет, сначала выберите задачу слайда по таблице ниже.

Агентный скилл

Для коротких промптов вроде «сделай слайды в стиле Практикума» в репозитории есть скилл skills/slidev-practicum/SKILL.md. Он фиксирует связку: официальный Slidev-скилл отвечает за технический синтаксис и экспорт, а этот README и example.md — за публичный API и визуальные правила темы.

Для локального просмотра:

npm install
npm run dev

Для использования в другой Slidev-презентации:

npm install -D slidev-theme-practicum

theme: practicum

Как выбрать слайд

Выбирайте не по теме презентации, а по задаче кадра.

| Задача автора | Что использовать | Что писать | | --------------------------------------- | ------------------------------------------ | -------------------------------------------------- | | Открыть презентацию, курс или раздел | Обложку (cover) | Название и короткое ожидание от темы | | Остановить внимание на одной мысли | Тезисный слайд (message) | Один тезис, вопрос или вывод | | Дать внешний голос | Цитату (message, quote) | Короткую цитату и автора | | Объяснить понятие, ситуацию или решение | Поясняющий слайд (explainer) | Заголовок и связное пояснение | | Дать большой текстовый блок с разметкой | Текстовый блок (explainer, title-body) | Абзац, затем короткий список или критерий | | Показать план, правила или шаги | Коллекцию (collection) | Однотипные пункты в одном формате | | Показать события во времени | Таймлайн (collection, timeline) | Годы или месяцы и короткие подписи | | Показать несколько чисел | Метрики (collection, metrics) | Главное число и подписи, которые объясняют масштаб | | Собрать нестандартную композицию | Ручную сетку (none) | Только когда обычные типы не выражают задачу |

Что писать

Заголовок должен отвечать на вопрос «что зритель должен понять сейчас?». Не называйте слайд технически вроде «Метрики» или «Композиция», если можно сразу написать вывод.

Поясняющий текст нужен для контекста, ограничения или критерия выбора. Если текст превращается в два разных вывода, разнесите его по двум слайдам.

Список работает, когда пункты однотипны: шаги, правила, критерии, темы. Пишите пункты в одинаковой грамматической форме, чтобы их можно было быстро просканировать.

Числа должны быть самодостаточными: значение плюс подпись должны объяснять, что измерено. Если число главное, остальные числа поддерживают его: показывают масштаб, выборку, срок или сравнение.

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

Семантика декоративных фотографий

Фотографии в шаблонах Практикума всегда декоративные. Они не являются источником фактов, доказательством, инструкцией или объектом, который зритель должен рассматривать ради ключевой информации.

Смысл слайда должен полностью читаться из текста, чисел, подписей, порядка элементов и выбранной композиции. Если фотографию убрать или заменить другой фотографией, вывод слайда не должен измениться.

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

Не пишите в примерах и документации: «на фото видно», «фото доказывает», «снимки дали контекст», «фотография объясняет число». Такие формулировки ошибочно превращают декоративный слой в информационный.

Живая галерея

Рабочие примеры для авторов хранятся в example.md. README объясняет, как выбирать и писать слайды, а example.md показывает это в виде реальной колоды: обложку, повестку, текстовый блок с разметкой, цитату, определение, таймлайн, метрики, карточки и ручную сетку.

Когда добавляете публичный layout, variant или arrangement, обновляйте сначала example.md: пример должен объяснять, в какой ситуации нужен паттерн, а не только демонстрировать YAML.

Техническая модель

layout: cover | message | explainer | collection | none

cover, message, explainer, collection задают роль слайда. none оставляет ручную сетку 12x12.

Для канонических макетов внутри layout: cover|message|explainer|collection используйте Slot role="..."; внутри layout-слайда не задавайте area, col и row. Для ручного режима используйте Slot area, Slot col или Slot row.

| Слой | Для чего | | ------------- | ------------------------------------------------ | | layout | семантика слайда на уровне Slidev | | variant | устойчивый вариант внутри роли | | arrangement | компактная перестановка одной модели данных | | Slot | область сетки, поверхность, отступы и медиа-слой | | Text | типографика и согласованный подбор размера | | Image | декоративная картинка внутри ручной композиции | | decor | семантический выбор декоративного изображения | | background | низкоуровневое размещение декоративной картинки |

Метаданные слайда

| Поле | Значения | По умолчанию | Смысл | | ------------- | ----------------------------------------------------- | --------------- | ---------------------------------------- | | layout | cover, message, explainer, collection, none | значение Slidev | роль слайда или ручная сетка | | variant | зависит от layout | задаёт макет | форма внутри роли | | arrangement | зависит от variant | задаёт рецепт | перестановка одной модели данных | | mode | light, dark, color | light | базовый цветовой контекст | | tone | blue, orange, green, red, yellow | blue | акцентный тон | | header | default, cover, none | задаёт макет | служебный верхний слой | | decor | объект: id или семантический запрос | нет | декоративный слой для сокращённой записи |

Slot API

| Свойство | Тип | По умолчанию | Смысл | | ------------------------------------------------------------ | ------------------------------------------ | ------------- | --------------------------------------------- | | role | primary, secondary, support, media | нет | слот из выбранного рецепта макета | | area | строка области сетки CSS | автоматически | ручное размещение в layout: none | | col, row | строка линий сетки CSS | автоматически | ручное размещение по осям | | surface | light, dark, color, tint | нет | локальная контрастная поверхность | | tone | цветовой токен | тон слайда | цвет для поверхностей color и tint | | margin | 1..8 | нет | общий внутренний отступ | | margin-top, margin-right, margin-bottom, margin-left | 1..8 | margin | отступ отдельной стороны | | gap | 0..7 | 0 | расстояние между прямыми дочерними элементами | | centered | boolean | false | центрирование содержимого | | decor | объект | нет | семантический декоративный слой | | background | объект или строка изображения | нет | явно заданное фоновое изображение |

Slot согласует размер до трёх прямых Text-детей с диапазонами size и priority. Атрибуты потока принадлежат дочерним элементам: Text align="end" прибивает строку внутри потока. Отдельный flow-атрибут есть у Person, когда блок автора используется как прямой ребёнок Slot.

Text API

| Свойство | Тип | По умолчанию | Смысл | | ---------- | --------------------------------- | ------------ | ---------------------------------------------- | | as | тег HTML | div | семантический тег | | size | 0..12 или диапазон вроде 7-12 | 2 | токен или диапазон подбора | | max-size | boolean | false | подбор от максимального токена вниз | | priority | 1, 2, 3 | 1 | визуальная иерархия для согласованного подбора | | color | цветовой токен | current | явный цвет | | muted | boolean | false | вторичный цвет с учётом поверхности | | align | start, middle, end | start | положение в потоке |

max-size выбирает самый крупный помещающийся токен; muted является булевым сокращением для color="text-muted" и учитывает текущую поверхность.

| Размер | Шрифт | Интерлиньяж | | ------ | ------- | ----------- | | 0 | 16px | 1.2 | | 1 | 20px | 1.2 | | 2 | 24px | 1.2 | | 3 | 36px | 1.2 | | 4 | 46px | 1.2 | | 5 | 56px | 1.2 | | 6 | 80px | 1.1 | | 7 | 124px | 1.1 | | 8 | 160px | 0.95 | | 9 | 200px | 0.95 | | 10 | 280px | 0.95 | | 11 | 340px | 0.95 | | 12 | 400px | 0.95 |

Image API

| Свойство или поле | Тип | По умолчанию | Смысл | | ------------------ | ------------------------------------------------ | ------------ | --------------------------------- | | src | путь | обязательно | исходное декоративное изображение | | fit | cover, contain, fill, none, scale-down | cover | режим заполнения | | position | позиция CSS | center | позиция изображения | | zoom | число | 1 | масштаб | | x, y | длина CSS | 0 | смещение | | anchor | позиция CSS | center | точка масштабирования | | rotate | CSS-угол или число градусов | 0deg | поворот изображения | | color | цвет CSS | нет | цвет заливки или маски | | background-color | цвет CSS | нет | фон медиаблока | | opacity | число | 1 | прозрачность слоя |

<Slot area="6 / 7 / -1 / 10">
  <Image src="/photos/photo-4.png" fit="cover" position="50% 42%" zoom="1.12" />
</Slot>

Для фона слота используйте Slot.background:

<Slot
  area="1 / 7 / -1 / -1"
  :background="{ src: '/photos/photo-6.png', fit: 'cover', position: '50% 40%', zoom: 1.04 }"
/>

Даже когда используется Image или Slot.background, фотография остаётся декоративной. Ключевые факты, различия, инструкции и выводы должны быть записаны текстом или числом.

Decor

decor выбирает декоративный медиа-слой по смыслу, размеру слота, тону и цветовому контексту. background остаётся низкоуровневым контрактом изображения для случаев, когда автор сам выбирает картинку и все параметры размещения.

| Поле | Тип | По умолчанию | Смысл | | -------------------------------------------------------- | ---------------- | -------------------- | ------------------------------- | | id | decor.id | нет | точный выбор записи | | meaning | строка | нет | семантический запрос | | tone | цветовой токен | тон слайда | цветовой запрос | | fit, position, zoom, x, y, anchor, rotate, color, background-color, opacity | поля изображения | значение из каталога | переопределение полей отрисовки |

decor:
  id: decor-rules-wide-01

decor:
  meaning: agenda
  tone: orange

На одном Slot нельзя одновременно использовать decor и background.

themeConfig

themeConfig:
  decors:
    - id: decor-custom-data
      src: /decor/custom-data.png
      meaning: data
      tone: blue

themeConfig:
  deckTitle: 'Название колоды'
  debugGrid: false
  decors:
    - id: decor-custom-data
      src: /decor/custom-data.png
      meaning: data
      tone: blue
      cols: [5, 8]
      rows: [3, 6]
      ratio: [1.2, 2.7]

В записи каталога cols и rows описывают допустимый размер слота в сетке 12x12, а ratio ограничивает соотношение cols / rows для ориентации. Вместо ratio можно использовать более явный алиас aspectRatio.

| Поле | Тип | По умолчанию | Смысл | | ----------- | --------------- | ------------------ | -------------------------------------------------------- | | deckTitle | строка | заголовок слайда | заголовок в шапке | | debugGrid | boolean | false | отладочная сетка 12x12 | | decors | записи каталога | встроенный каталог | добавляет или переопределяет записи декора по decor.id |

Цветовые токены

| Токен | Значение | | ---------- | --------- | | light-0 | #ffffff | | light-1 | #f0f0f0 | | dark-0 | #1e1e1e | | dark-1 | #3c3c3c | | dark-2 | #969696 | | blue-0 | #027ef2 | | blue-1 | #98d2fe | | orange-0 | #ff6c26 | | orange-1 | #ffd2bd | | green-0 | #07ab4b | | green-1 | #9cddb7 | | red-0 | #e84033 | | yellow-0 | #ffd20a |

Проверка

npm run test