pagecraft-schema-block

⚡ Этот скилл — для вызова через тул Skill(pagecraft-schema-block), не через Read .../SKILL.md. Если ты сюда попал через Read — остановись, вызови Skill(pagecraft-schema-block). Содержимое то же, но система правильно учтёт делегирование.

PageCraft Schema Block

Ядро: блок с полями в схеме. Контент редактируется через fields в schema.json, шаблон обращается к ним через {{ props.* }}. Альтернатива — markdown-блок (контент через WYSIWYG), там основной текст приходит как {{ content }} — это pagecraft-markdown-block.

Установка

npm install --prefix .claude/skills/pagecraft-schema-block

Структура блока

blocks/{slug}/
├── block.json       — метаданные (description, tags, version, id, …)
├── schema.json      — fields + bindingSlots (если SSR) + slots (если контейнер)
├── template.liquid  — LiquidJS шаблон (доступ {{ props.* }}, {{ data.* }})
├── style.css        — изолированные стили
├── script.js        — JS (только если нужна интерактивность)
├── preview.html     — превью (генерируется pagecraft-block/scripts/build-preview.js)
└── doc.md           — документация

Скоупы Liquid

• props.* — поля схемы. title → {{ props.title }}. Внутри циклов — {% for item in props.items %}{{ item.title }}{% endfor %} (item без префикса).
• data.* — серверные данные, появляется только при объявленном bindingSlots (pagecraft-block-ssr).
• slots.* — HTML вложенных блоков, появляется только при объявленном slots: блок с ним становится контейнером (две колонки, табы, аккордеон). Формат и правила — references/block-format.md. Не путать с bindingSlots: те дают данные, эти — вложенную вёрстку.
• content — точка вставки страницы у лэйаута (role: "layout" в block.json): обязательна в его шаблоне, иначе блок не сохранится. Вместе с ней обязателен {{ cms_assets_head }} внутри <head> — точка вставки ассетов витрины; ещё две необязательные, {{ cms_assets_body_start }} и {{ cms_assets_body_end }}. Лэйаут — обёртка документа-макета целиком, а не блок внутри страницы; отличие от контейнера — в references/block-format.md.
• content — только для markdown-блоков (pagecraft-markdown-block).

Никогда не используй переменные без префикса ({{ title }}, {{ bg_color }}). Префикс (props./data./content) говорит движку, откуда брать значение — без него подстановка не сработает и блок отрендерится пустым. Старый формат не поддерживается.

Скрипты

Скрипт	Что делает
scripts/sync-schema.js	Стянуть block-schema.json (мета-схему AJV) из API в references/. [--quiet]
scripts/validate-schema.js	Проверить schema.json блока против references/block-schema.json. <block-dir>

Порядок валидации

Мета-схема живёт на сервере и меняется вместе с бэкендом, а архив скилла выпускается отдельно — копия в references/ по определению отстаёт. Поэтому:

1. node scripts/sync-schema.js --quiet — всегда перед первой валидацией в проекте, не «если что-то не так».
2. node scripts/validate-schema.js <block-dir> — перед публикацией и после каждой правки схемы.

⚠️ Ошибка вида / — must NOT have additional properties { additionalProperty: 'slots' } означает устаревшую мета-схему, а не запрет поля. Корень мета-схемы закрыт additionalProperties: false, поэтому любой ключ, появившийся на сервере позже твоей копии, выглядит как несуществующий. Не удаляй поле из схемы — прогони шаг 1 и повтори шаг 2.

Справочники

Файл	Когда открывать	Тема
references/schema-block.md	Пишешь template.liquid или JS блока	Liquid-паттерны (заголовок, изображение, кнопка, switch, цикл, full-width, цвет inline), JS-шаблон с IIFE и data-initialized, a11y
references/field-types.md	Описываешь поля в schema.json	Все типы полей: text, textarea, url, image, icon, color, switch, select, radio, object, array, и др. С форматами и дефолтами
references/block-format.md	Собираешь block.json / структуру блока	Формат block.json, schema.json корня, вкладки (tab), формула prefix {author}-{slug}-vX-Y
references/block-schema.json	Валидируешь schema.json через AJV	Мета-схема AJV (обновляется через sync-schema.js)

Ключевые правила template.liquid

• Поля схемы — под props.*: {{ props.title }}. Никогда {{ title }}.
• Запрещено: {% render %}, {% include %}, {% layout %}, {% block %}.
• Пустые строки: {% if props.title != '' %}.
• Switch без == true: {% if props.show_button %}.
• Select/Radio через модификатор класса: {author}-{slug}--align-{{ props.text_align }}.
• В циклах — {% for item in props.items %}{{ item.title }}{% endfor %}.
• Шрифты — через <link> в начале шаблона, не @import в CSS.

Ключевые правила style.css

• BEM: .{author}-{slug}__element, .{author}-{slug}--modifier. Никаких глобальных селекторов.
• container-type: inline-size на корневом элементе — обязательно.
• Цвета только через CSS custom properties (--{author}-{slug}-color-bg и т.п.).
• Breakpoints только @container (+ fallback @supports not (container-type: inline-size) через @media).
• font-size заголовков и padding блока — только clamp() с cqi.
• Без @import.

Полный CSS-гайд: pagecraft-block-design/references/css-guide.md.

Ключевые правила script.js

• Только если нужна интерактивность. Статичные блоки JS не имеют.
• Без import/require. Один файл, IIFE.
• data-initialized обязателен — блок может быть вставлен в DOM многократно.
• Только el.querySelector внутри initBlock — никогда document.querySelector.

Пример

examples/hero-section/ — schema-блок со всеми основными паттернами: поля всех типов, full-width, a11y, IIFE-скрипт.

Что не делает этот скилл

• Не публикует блок — pagecraft-block-publish.
• Не работает с серверными данными — pagecraft-block-ssr (если у блока есть bindingSlots).
• Не подбирает стиль / каталог — pagecraft-block-design.
• Не генерирует preview.html — pagecraft-block/scripts/build-preview.js (вызывается из orchestrator после реализации).
• Не ходит в API за блоками / тегами / источниками — pagecraft-api, pagecraft-block-ssr.

Типичные ошибки

• Переменная без префикса ({{ title }}) — поле схемы не подхватится.
• pb-{slug} как prefix вместо {author}-{slug}-v1-0.
• image или icon без default — блок вставляется пустым.
• bg_color без text_color — тёмный фон с тёмным текстом по умолчанию нечитаем.
• Главный контент (title, subtitle) внутри tab — он должен быть первым без вкладки.
• Все поля без tab когда их больше 5 — редактор превращается в простыню.
• script.js для статичного блока без логики.
• description к полю «для красоты» — пиши только когда лейбл реально не объясняет: формат значения, зависимость от другого поля, поведение блока, технические ограничения. Если из лейбла всё ясно — description не нужен, иначе форма превращается в стену текста (см. references/field-types.md → раздел description).
• required: true без default — валидация падает сразу при вставке блока. Обязательное поле всегда с дефолтом.
• Поле с ключом size / first / last — зарезервированные аксессоры Liquid: {{ props.size }} без значения вернёт число, а не дефолт (на бэке, фронте и SSR). Переименуй (box_size, first_item). Валидация отклонит такой ключ. См. references/block-format.md.