раздел 05

Типовые проблемы

Почти всё, что ломается в HTML-презентации, ломается одинаково у всех и чинится одним промптом. Здесь десять самых частых случаев: как выглядит, почему, что сказать агенту.

Слайд выезжает за экран, виден кусок, приходится скроллить
Нет масштабирования: слайд свёрстан на холсте 1920x1080, а окно меньше, и браузер показывает его в натуральную величину. Промпт: Добавь масштабирование: базовый холст 1920x1080, при загрузке и при изменении размера окна считай коэффициент как минимум из ширина_окна/1920 и высота_окна/1080 и применяй transform: scale к контейнеру слайда. Центрируй холст. Скролл страницы отключи.
Текст не помещается на слайде, последние строки уходят под край
Слишком много текста или слишком крупный шрифт для этого объёма. Уменьшать шрифт ниже 24px нельзя, значит резать текст. Промпт: Слайд 7: текст выходит за границы холста. Сократи до 5 тезисов по одной строке, не уменьшая шрифт. Если не влезает - раздели на два слайда 7 и 7а. Если это повторяется на многих слайдах, попросите пройти по всем сразу.
На другом компьютере шрифты разъехались, раскладка поехала
Агент подключил шрифт из сети (Google Fonts), а на том компьютере нет интернета или шрифт не успел загрузиться. Или указан шрифт, которого там нет. Промпт: Убери все шрифты из сети. Используй системный стек: font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif. Проверь, что раскладка не зависит от конкретного шрифта: заголовки не должны переноситься на вторую строку при замене.
Картинки не грузятся, вместо них пустые рамки или значок битого файла
Картинки вставлены ссылками на файлы в папке или на сайты. Файл переслали без папки, или сайт недоступен. Промпт: Все картинки встрой в файл: растровые как data-URI (base64), схемы и иконки перерисуй как inline-SVG. Внешних ссылок на изображения быть не должно. После правки покажи список всех img и svg с указанием, откуда взят каждый.
В PDF всё на одной странице или слайды обрезаны
Нет блока @media print, или в нём не отключён transform и скрыты все секции кроме активной. Промпт: Сделай режим печати @media print: все секции видимы, каждая на отдельной странице (page-break-after: always), transform снят, размер страницы 1920px на 1080px альбомный с нулевыми полями через @page, print-color-adjust: exact для фонов. Навигацию и счётчик скрыть. После этого в диалоге печати выбрать альбомную ориентацию, поля «нет», фон включить.
Презентация тормозит, слайды переключаются с задержкой
Тяжёлые data-URI: агент встроил фотографии по несколько мегабайт каждая, и файл вырос до 30-50 МБ. Промпт: Файл весит [размер]. Найди самые тяжёлые data-URI и сожми: уменьши картинки до 1600px по длинной стороне, JPEG качество 80. Где картинка декоративная - замени на SVG. Цель: файл не больше 5 МБ. Покажи размер до и после. Если в презентации видео, вынесите его ссылкой.
На телефоне не листается, свайп не работает
Скрипт слушает только клавиатуру. Промпт: Добавь навигацию касанием: свайп влево - следующий слайд, вправо - предыдущий, порог 50px. Тап по правой трети экрана - вперёд, по левой - назад. Проверь, что свайп не конфликтует со скроллом страницы (скролл отключён). И напомните получателям открывать в альбомной ориентации.
Агент сделал пять файлов вместо одного: html, css, js, папка с картинками
Агент по привычке разложил проект по папкам, как для сайта. Промпт: Собери всё в один файл deck.html: содержимое style.css внутрь тега style, script.js внутрь тега script в конце body, картинки из папки встрой как data-URI или inline-SVG. Остальные файлы удали. В результате в папке должен остаться один html.
Нужно поменять цвет (или шрифт) сразу везде
Если цвета в переменных CSS - одна строка. Если нет, сначала рефакторинг. Промпт: Вынеси все цвета и шрифт в переменные CSS в :root (bg, fg, accent, muted, font). Затем поменяй accent на #f59e0b. Ничего кроме цвета не должно измениться.
После правки пропала половина слайдов или всё съехало в одну колонку
Агент не закрыл тег или сломал скрипт, и браузер дальше не понимает разметку. В консоли браузера будет ошибка. Промпт: Файл сломался после последней правки: после слайда [N] ничего не показывается. Проверь, что все теги section закрыты, скрипт без синтаксических ошибок, число секций совпадает с числом слайдов в плане. Прогони файл через валидатор и исправь. Если есть git, проще откатить на предыдущий коммит и повторить правку меньшими шагами.

Как не доводить до этого

Большинство пунктов выше - это пропущенная строка в ТЗ. Список технических требований из главы Из чего состоит HTML-презентация, положенный в AGENTS.md / CLAUDE.md проекта, снимает семь из десяти. Проверка в браузере после каждой правки ловит оставшиеся три до того, как их увидит зал.

Есть смысл попросить агента проверять файл самому, если в IDE подключён браузер. Промпт для регулярной проверки:

После каждой правки deck.html: открой файл в браузере, пройди все слайды,
проверь консоль на ошибки, сузь окно до 800px и убедись, что холст
уменьшился целиком. Если что-то не так - исправь и проверь снова,
потом отчитайся одной строкой.

Как настроить такую проверку - в курсе Проверка результата.