slidev-theme-practicum 0.3.0 → 0.4.0

package/README.md

@@ -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,8 @@ npm install -D slidev-theme-practicum
 theme: practicum
 ```
 
+Тема не загружает шрифты из сети. Если `YS Text` установлен в системе, браузер использует его локально. Иначе стек последовательно переходит к локальному `Inter`, системному интерфейсному шрифту и `sans-serif`. Поэтому сборка и показ остаются офлайн-воспроизводимыми, но метрики текста без `YS Text` могут немного отличаться. Перед выпуском проверяйте галерею тем же окружением Chromium, которым сформированы пиксельные эталоны.
+
 ## Структура проекта колоды
 
 Для презентации, которая использует установленную тему, каноническая точка входа — `slides.md`, а локальные медиа лежат в `public/` и подключаются абсолютным путём от корня сайта:
@@ -230,7 +290,7 @@ defineSlots<DeckLayoutVariantSlots>()
 | `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 добавляет тема |
 
@@ -336,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
 
 | Свойство                                                     | Тип                                        | По умолчанию  | Смысл                                         |
@@ -373,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.
 
@@ -527,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` |
@@ -549,4 +613,14 @@ npm test
 - модульные, контрактные и архитектурные тесты;
 - продукционную сборку, локальный вариант внешней презентации и состав артефактов;
 - репрезентативные слайды в 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

@@ -197,7 +197,7 @@ const slideClass = computed(() => ({
       <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">

package/components/Slot.vue

@@ -334,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);
 }

package/components/StepsGrid.vue

@@ -29,7 +29,7 @@ const props = defineProps<{
              :class="{ 'Slide-Step_active': item.active }"
              :data-index="index + 1">
       <Text size="4">{{ item.label }}</Text>
-      <TextFitGroup class="Slide-Step-FitGroup"
+      <TextFitGroup class="Slide-Step-FitGroup Slide-Step-TitleFitGroup"
                     :fit-group="`${stepsFitGroup}-titles`">
         <Text size="3-5">{{ item.title }}</Text>
       </TextFitGroup>
@@ -78,35 +78,40 @@ const props = defineProps<{
   min-width: 0;
 }
 
+.Slide-StepsGrid_staggered .Slide-Step-TitleFitGroup {
+  margin-top: auto;
+}
+
 .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 {
+  grid-column: span 2;
 }
 
-.Slide-StepsGrid_staggered .Slide-Step:nth-child(2) {
-  grid-area: 1 / 3 / 2 / 5;
+.Slide-StepsGrid_staggered[data-count='2'] .Slide-Step {
+  grid-column: 2 / 6;
 }
 
-.Slide-StepsGrid_staggered .Slide-Step:nth-child(3) {
-  grid-area: 1 / 5 / 2 / 7;
+.Slide-StepsGrid_staggered[data-count='3'] .Slide-Step,
+.Slide-StepsGrid_staggered[data-count='4'] .Slide-Step {
+  grid-column: span 3;
 }
 
-.Slide-StepsGrid_staggered .Slide-Step:nth-child(4) {
-  grid-area: 2 / 2 / 3 / 4;
+.Slide-StepsGrid_staggered[data-count='3'] .Slide-Step:nth-child(3) {
+  grid-column: 2 / 6;
 }
 
-.Slide-StepsGrid_staggered .Slide-Step:nth-child(5) {
-  grid-area: 2 / 4 / 3 / 6;
+.Slide-StepsGrid_staggered[data-count='5'] .Slide-Step:nth-child(4) {
+  grid-column: 2 / 4;
 }
 
 .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);
+  color: var(--theme-text-on-color);
+  --theme-text: var(--theme-text-on-color);
+  --theme-text-muted: var(--theme-text-muted-on-color);
 }
 </style>

package/components/Text.vue

@@ -16,7 +16,9 @@ type TextColorToken =
   | 'text'
   | 'text-muted'
   | 'text-on-dark'
+  | 'text-on-color'
   | 'text-muted-on-contrast'
+  | 'text-muted-on-color'
   | 'link'
   | 'light-0'
   | 'light-1'
@@ -37,7 +39,9 @@ const TEXT_COLOR_MAP: Record<TextColorToken, string> = {
   'text': 'var(--theme-text)',
   'text-muted': 'var(--theme-text-muted)',
   'text-on-dark': 'var(--theme-text-on-dark)',
+  'text-on-color': 'var(--theme-text-on-color)',
   'text-muted-on-contrast': 'var(--theme-text-muted-on-contrast)',
+  'text-muted-on-color': 'var(--theme-text-muted-on-color)',
   'link': 'var(--theme-link)',
   'light-0': 'var(--theme-color-light-0)',
   'light-1': 'var(--theme-color-light-1)',
@@ -119,6 +123,7 @@ const textStyle = computed(() => ({
   <component :is="as"
              ref="textElement"
              class="Text"
+             :data-text-color="resolvedColor"
              :class="[
                `Text_size_${normalizedSize}`,
                {

package/composables/deck-slot-markup.cjs

@@ -7,7 +7,7 @@ const { parse } = require('vue/compiler-sfc')
  * @typedef {(
  *   | { kind: 'comment' }
  *   | { kind: 'text', content: string }
- *   | { kind: 'element', tag: string, props: Record<string, unknown>, children: DeckLiveNode[] }
+ *   | { kind: 'element', tag: string, props: Record<string, unknown>, dynamicProps?: string[], children: DeckLiveNode[] }
  * )} DeckLiveNode
  */
 /** @typedef {{ children: DeckLiveNode[], intents: ExplicitSlotIntent[] }} DeckLiveStructure */
@@ -26,6 +26,11 @@ function formatCompilerError(error) {
  * @returns {unknown}
  */
 function readLiteralBinding(prop) {
+  const source = prop.exp?.loc.source.trim()
+  if (source === 'true' || source === 'false')
+    return source === 'true'
+  if (source === 'null')
+    return null
   const ast = prop.exp?.ast
   if (!ast)
     return undefined
@@ -75,11 +80,12 @@ function containsSlot(node) {
 
 /**
  * @param {import('@vue/compiler-core').ElementNode} node
- * @returns {Record<string, unknown>}
+ * @returns {{ props: Record<string, unknown>, dynamicProps?: string[] }}
  */
 function elementProps(node) {
   /** @type {Record<string, unknown>} */
   const props = {}
+  const dynamicProps = []
 
   for (const prop of node.props) {
     if (prop.type === 6) {
@@ -87,8 +93,11 @@ function elementProps(node) {
       continue
     }
 
-    if (prop.name !== 'bind')
+    if (prop.name !== 'bind') {
+      if (SLOT_CONTROL_FLOW_DIRECTIVES.has(prop.name))
+        dynamicProps.push(`v-${prop.name}`)
       continue
+    }
 
     const key = prop.arg?.type === 4 && prop.arg.isStatic
       ? prop.arg.content
@@ -96,6 +105,11 @@ function elementProps(node) {
 
     if (node.tag !== 'Slot'
       || (!SLOT_CONTRACT_PROPS.has(key) && key !== 'label' && key)) {
+      const value = readLiteralBinding(prop)
+      if (key && value !== undefined)
+        props[key] = value
+      else
+        dynamicProps.push(key ? `v-bind:${key}` : 'v-bind')
       continue
     }
 
@@ -118,7 +132,7 @@ function elementProps(node) {
     props[key] = value
   }
 
-  return props
+  return dynamicProps.length ? { props, dynamicProps } : { props }
 }
 
 /**
@@ -134,7 +148,7 @@ function liveNode(node) {
     return {
       kind: 'element',
       tag: node.tag,
-      props: elementProps(node),
+      ...elementProps(node),
       children: node.children
         .map(liveNode)
         .filter(isLiveNode),