todo/.claude/skills/vault-chart/SKILL.md
loop-uh 62e0c4bae2
Some checks failed
Published content check / validate (push) Failing after 23s
Скиллы и память агентов — в Git, и так будет всегда
Решение владелицы от 1 ноября 2026: .claude/skills/, .agents/skills/ и
.memory/ коммитятся вместе с остальными правками vault, включая сторонние
скиллы avoid-ai-writing и stop-slop. .gitignore теперь пропускает
.claude/skills/ (прочие служебные файлы .claude/ по-прежнему закрыты),
__pycache__ исключён. Репозиторий публичный, поэтому в заметках памяти
реальные адреса хостов заменены ссылкой на pve-admin/servers.md; ключей и
паролей в коммите нет.

Попутно: шаблон Forgejo-футера в vault-note берёт имя git из zapret-links
вместо вписанного git2; в памяти упоминания владельца переведены в женский
род, устаревшие заметки об именах сайта и об обложках приведены к текущим
правилам. На сайт эти папки не попадают (ignorePatterns Quartz).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 18:10:54 -05:00

33 KiB
Raw Permalink Blame History

name description
vault-chart Как строить собственные диаграммы и инфографику для статей этого vault и постов Telegram-канала: заголовок-вывод в стиле новостных редакций (РБК), один вопрос на график, подписи прямо на данных вместо легенды, человеческие названия групп, явная база сравнения для процентов, проверка «понятно за пять секунд». Рисует через HTML/SVG и headless Chromium (шрифт Inter, палитра vault, скрипт render.py с превью «как в Telegram»), а не через matplotlib. Используй каждый раз, когда рисуешь график, диаграмму, плитки, инфографику или обложку с цифрами для заметки в vault, а также когда переделываешь уже готовую диаграмму. Триггеры: «сделай график/диаграмму», «составим свои графики», «добавь инфографику», «графики непонятные», «переделай диаграмму», «графики некрасивые». Дополняет общий скилл dataviz (цвета, разметка) и vault-image (куда класть файл и как встраивать).

Диаграммы для vault и канала

Сколько диаграмм нужно

В каждой новой статье — минимум 2–3 диаграммы, это обязательно (решение владелицы от 30 сентября 2026 года). Одна диаграмма на статью — недобор, ноль — ошибка, даже если в тексте мало чисел. Рендер только через headless Chromium этим скриптом (scripts/render.py), как описано ниже.

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

  • Таймлайн — для хроники и итогов периода: месяцы или даты по вертикали, события короткими фразами, цветом выделен пик или главное событие. Образец — DPI/attachments/internet-day-2026-rkn-year-timeline.png (итоги года к Дню интернета 2026): заголовок-вывод «Пик года — февраль и март 2026…», два пиковых месяца красным, финальное событие статьи синим, остальное серым.
  • Схема «было → стало» — для законов, реформ и смены настроек: строки-параметры, две колонки, новые обязанности или потери выделены красной рамкой. Образец — DPI/attachments/internet-day-2026-antifraud-3-before-after.png.
  • Столбцы или плитки — для любого сравнения чисел, даже двух: план против текущего значения, до и после. Образец — DPI/attachments/internet-day-2026-tspu-capacity-2030.png; если одно из значений вычислено, а не взято из источника, пометь это сноской прямо на картинке.
  • Пошаговая схема механизма — для технических разборов: как идёт запрос, где его режет фильтр, что меняет обход.

Для таймлайна и схем тоже действуют все правила ниже: заголовок-вывод, цвет только у главного, кегль ключевого текста не меньше 24 CSS px, источник с датой.

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

Правило пришло из отзыва читателя канала (сентябрь 2026) на графики к статье о 27 регионах и к статье о видеохостингах. Визуально их хвалили, но смысл приходилось расшифровывать. Читатель показал графики друзьям, и те тоже сказали «непонятно». Примеры ниже взяты из этих графиков. Канал теперь больше новостной, чем технический, поэтому образец — инфографика новостных редакций, которые постоянно работают с данными (РБК и подобные): заголовок сообщает вывод, а диаграмма показывает, откуда он взялся.

Начни с вопроса и ответа, а не с данных

До первой строки кода запиши три вещи:

  1. Вопрос, на который отвечает график, обычными словами: «Кто выиграл от блокировки YouTube?», «Сколько регионов останутся без местных провайдеров?».
  2. Ответ одной фразой. Это будущий заголовок: «YouTube вырос вдвое сильнее любой российской площадки».
  3. Что глаз должен увидеть первым: один столбец, одна группа плиток, один разрыв. Этот элемент и получает цвет.

Если ответ не укладывается в одну фразу, график пытается сказать слишком много: раздели его на два. Если ответа нет вообще («просто показываю данные»), то и график не нужен, хватит таблицы в тексте.

Заголовок — это вывод

Заголовок называет результат, а не тему.

Плохо (тема) Хорошо (вывод)
Сколько прибыли съедает взнос 1 млн ₽ в год Самым мелким провайдерам взнос обойдётся в 7 годовых прибылей
Кто вырос, а кто просел: 2026 к 2025 году YouTube вырос вдвое сильнее любой российской площадки
Качели рынка: YouTube тянет всё видеопотребление Без YouTube рынок видео в 2026 году упал бы на 5%
Минут в день на одного зрителя площадки На YouTube смотрят дольше, чем на любой российской площадке

Подзаголовок отвечает на вопросы «что измерено, в чём, за какой период и по сравнению с чем», короткой фразой без терминов: «Сколько минут в день смотрит один зритель площадки. Первое полугодие 2026 года по сравнению с первым полугодием 2025-го». Строка источника с датой идёт внизу мелко: «Источник: Future Lab / Mediascope, «Коммерсантъ», 22.09.2026».

Вывод в заголовке подчиняется тем же правилам точности, что и текст статьи (см. vault-note, «Точность важнее авторского акцента»): никаких абсолютизмов сверх данных, оценка подписывается как оценка («по оценке АСТО»), число на картинке совпадает с числом в тексте.

Подписи прямо на данных, легенда — крайний случай

  • Подписывай группу рядом с ней: у столбца, у блока плиток, в конце линии. Легенда в углу заставляет глаз бегать туда-обратно, поэтому ставь её только когда прямая подпись физически не помещается.
  • Группы называй по смыслу, а не диапазоном. «30–49%» — это данные, а читателю нужен вывод: «потеряют больше половины рынка — 21 регион». Каждая выделенная группа должна отвечать на «и что?». Если у группы нет своего вывода, она не заслуживает отдельного цвета: слей её с соседними в серое «остальные».
  • Цвет только у главного. Цветом выделяй то, о чём говорит заголовок, остальное делай нейтрально-серым. Пять цветов на одной картинке — это пять вопросов к читателю.
  • Ключевой вывод пиши текстом на самой диаграмме: короткая аннотация у главного элемента («в 7 раз больше годовой прибыли», «единственный рост больше 20%»).

Проценты и индексы: всегда «от чего»

Голый процент или ноль на оси — главный источник вопроса «а что это вообще значит?». Про график видеохостингов читатель спросил: «0% — а что такое 0, от чего считаются прошлые и текущие показатели?».

  • По возможности показывай абсолютные величины в понятных единицах: минуты в день, рубли, регионы, люди. «80 → 99 минут» понятнее, чем «+24%». Процент изменения при этом можно дописать подписью.
  • Если без процентов не обойтись, назови базу прямо на графике: не «0», а «0 = как в I полугодии 2025», не «100%», а «100% = вся годовая прибыль». Эта подпись идёт на саму линию, а не только в подзаголовок.
  • Отношения переводи в бытовую форму: «в 7 раз больше годовой прибыли» вместо «714% медианной прибыли». Слово «медианная» на картинке заменяй на «типичная» или выноси в сноску.
  • Не смешивай на одном графике разные базы (рост к прошлому году и доля от рынка, «на зрителя» и «на население»). Нужны обе — рисуй два графика.

Язык картинки

  • Без жаргона: «встроенный плеер», а не «эмбедированный просмотр»; «типичный оператор», а не «медианный». Если точный термин важен, дай его в сноске, а на графике оставь понятное слово.
  • Единицы измерения всегда словами рядом с числом или в подзаголовке: «мин в день», «млн ₽», «регионов».
  • Сноски только для оговорок (возможная опечатка в источнике, особенность методики). Если без сноски график не понять, это не сноска, а недостающая подпись.

Как рисовать: HTML → PNG через Chromium

С настройками по умолчанию matplotlib выглядит устаревшим: DejaVu Sans, грубое сглаживание, заголовок и подписи приходится расставлять координатами. Поэтому диаграмма собирается как веб-страница (HTML + SVG, шрифт Inter), а в PNG её переводит headless Chromium. Браузер даёт нормальную типографику с кириллицей, субпиксельное сглаживание и обычный CSS для заголовка, подзаголовка и сносок. matplotlib и PIL для новых диаграмм не используй.

Всё нужное уже есть на хосте, ставить ничего не надо: Node 22, Chromium из playwright в ~/.cache/ms-playwright/, шрифт Inter Variable в ~/.local/share/fonts/inter/ (копия лежит в assets/fonts/ скилла, скрипт рендера сам её доставит, если шрифт пропадёт).

Порядок работы

  1. Скопируй template.html из папки скилла в scratchpad под говорящим именем. Шаблон — это готовая диаграмма «Динамика видеохостингов», переделанная по правилам выше: токены палитры, Inter, заголовок-вывод, подзаголовок, подписи на данных, подпись базы у нулевой линии, аннотация у главного столбца, сноска и источник; холст 16:9. Меняй данные и тексты, а не каркас. Раскраску каждый раз выбирай заново по заголовку (см. «Что красить»), а не копируй из шаблона.

  2. Для столбцов, линий и плиток рисуй SVG руками в <script> страницы, как в шаблоне: так проще контролировать каждую подпись. Если нужна сложная форма (тепловая карта, области с накоплением, карта), подключи библиотеку с jsdelivr с закреплённой версией: https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js, https://cdn.jsdelivr.net/npm/@observablehq/plot@0.6.17/dist/plot.umd.min.js, ECharts. Их стили по умолчанию перекрой токенами палитры и кеглем из этого раздела.

  3. Отрендери:

    python3 /home/codex-pve/Privacy/.claude/skills/vault-chart/scripts/render.py chart.html chart.png
    

    Скрипт сам находит Chromium, меряет страницу, подгоняет высоту холста под содержимое (--height auto по умолчанию; для строгих 16:9 — --height 675), снимает PNG с --force-device-scale-factor=2 и кладёт рядом превью chart.tg400.png шириной 400 px. Если он пишет «ВНИМАНИЕ» (содержимое шире холста, заходит на поле или обрезается снизу), исправь вёрстку и отрендери заново: такие предупреждения не игнорируются.

  4. Открой через Read и chart.png, и chart.tg400.png, пройди чек-лист ниже.

  5. Готовый PNG клади в attachments раздела по правилам vault-image (без пережатия, байт в байт). Превью .tg400.png и HTML в vault не копируй: они остаются в scratchpad.

Холст и кегль

  • Холст 1200 CSS px в ширину, на выходе PNG 2400 px (масштаб ×2), поэтому картинка остаётся чёткой при любом масштабе в статье. Высота по содержимому; для одиночной картинки в посте лучше 675 CSS px (16:9, файл 2400×1350). Размер обложки 1672 × 941 из vault-image к диаграммам не относится.
  • Все размеры считай в CSS px холста 1200, а не в пикселях готового файла. Лента Telegram сжимает картинку примерно до 400 px, то есть втрое от CSS-ширины. Отсюда минимумы:
    • заголовок 36–44 px, жирный (в шаблоне 40);
    • подзаголовок ~22 px;
    • всё, без чего не понять вывод (подписи групп, названия, ключевые числа) — не меньше 24 px;
    • подпись базы у линии 0 или 100% — не меньше 20 px;
    • мелким (16 px) может быть только источник и сноски.
  • Поля: padding: 56px 64px 44px. Подписи и аннотации не заходят на правое поле: скрипт рендера это проверяет.
  • Шрифт называй только "Inter Variable". Так он зарегистрирован в fontconfig. Имя Inter на хосте не находится, и Chromium молча рисует запасным шрифтом (serif или DejaVu). Библиотеки ставят свой шрифт поверх body: в Observable Plot передавай style: {fontFamily: '"Inter Variable"'}, в ECharts — textStyle: {fontFamily: '"Inter Variable"'}; D3 и ручной SVG наследуют шрифт от body. Скрипт рендера проверяет font-family у всего текста и предупреждает, если первым стоит не Inter Variable.
  • font-variant-numeric: tabular-nums ставь только на текст внутри SVG (числа в столбцах выравниваются), но не на body: в прозе он разрежает дефисы («2025 - го»).
  • Числа форматируй по-русски: toLocaleString("ru-RU") (пробел в разрядах, запятая в дробях), минус — знак −, а не дефис.

Палитра

Палитра зашита токенами в :root шаблона. Цвета проверены валидатором из скилла dataviz на фоне #101418 (все проверки пройдены, включая различимость при нарушениях цветовосприятия):

Токен Цвет Роль
--bg #101418 фон, тёмный, как у прежних диаграмм vault
--ink / --ink-2 #f1f3f5 / #b9c0c7 заголовок и главные подписи / подзаголовок и подписи групп
--muted #8a929b оси, линия нуля, источник, сноски
--grid #262c33 сетка, разделители
--neutral #5c6570 «остальные»: всё, о чём не говорит заголовок (контраст 3,1:1 к фону)
--accent #3987e5 главное, нейтральный тон (рост, лидер)
--alarm #f0555a падение, потеря, угроза, когда это часть вывода
--warn #c98500 вторая выделенная группа

Что красить: решай по заголовку каждый раз

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

  1. Что называет заголовок, то и цветное. Заголовок про лидера («YouTube вырос вдвое сильнее…») — лидер получает --accent. Заголовок про потери («27 регионов останутся без местных провайдеров») — потери получают --alarm.
  2. Вторая цветная группа — только если у неё есть свой вывод, который читатель должен унести, даже если он не в заголовке. Проверка: можешь ли ты сказать про группу одну фразу «и что?». «Четыре площадки из восьми просели, Premier на 20%» — вывод есть, падения красим красным. «Три площадки немного выросли» — вывода нет, они серые.
  3. Всё остальное — --neutral, даже если значения отрицательные. Минус сам по себе не повод для красного: если просадка на 1–2% ничего не меняет в выводе, серый столбец со знаком «−» в подписи честнее.
  4. Больше двух цветов не бывает. Если хочется третий, график отвечает на два вопроса: раздели его.

Красный --alarm — для падения, потери, угрозы, блокировки, то есть для плохих новостей, которые читатель должен заметить. Синий --accent — для главного без оценки «плохо»: лидер, рост, наш случай. Янтарный --warn — вторая ступень тревоги рядом с красным («потеряют всех» красным, «потеряют больше половины» янтарным).

Примеры:

Заголовок Цветное Серое
YouTube вырос вдвое сильнее российских площадок (шаблон) YouTube синим; просевшие площадки красным: падение Premier на 20% — второй вывод статьи выросшие, кроме YouTube
Premier потерял пятую часть зрительского времени Premier красным все остальные, включая YouTube
27 регионов останутся без местных провайдеров 27 регионов красным, 21 регион янтарным остальные регионы
Без YouTube рынок видео упал бы на 5% столбец «без YouTube» красным «все площадки»
  • Пара красный + янтарный для дальтоников различима плохо (валидатор даёт WARN). Она допустима только с прямыми подписями у каждой группы, а это здесь и так обязательно.

  • Новый цвет не подбирай на глаз: проверь набор валидатором для тёмного фона.

    node "$(find /tmp/claude-1000/bundled-skills -name validate_palette.js | head -1)" "#f0555a,#3987e5,#c98500" --mode dark --surface "#101418"
    

Остальное

  • Только линейная шкала. Логарифмическую не используй: владелица канала (23.09.2026) отметила, что она прячет масштаб разрыва. Если мелкие значения пропадают рядом с крупными, переформулируй показатель, но шкалу не сжимай.
  • Числа на картинке строго совпадают с текстом статьи. Если в источнике неопределённость (спорный подсчёт, вероятная опечатка), не рисуй её как точный факт: пометь или не выводи.
  • Все диаграммы одной статьи в одном стиле. Старые графики в DPI/attachments/ нарисованы matplotlib (DejaVu Sans, холст 1672 px). Если добавляешь новую диаграмму в статью, где такие уже есть, спроси владелицы, переделать ли остальные, а не смешивай два стиля молча.
  • Обложку 1672 × 941 тем же скриптом: render.py cover.html cover.png --width 1672 --height 941 --scale 1, а в body задай width:1672px;height:941px. Это запасной вариант: если владелица присылает свою иллюстрацию, типографскую обложку замени на неё (см. vault-image).
  • Запас справа под подпись у столбца. Число и пояснение стоят правее конца столбца, поэтому домен шкалы бери с запасом 20–40% сверх наибольшего значения, иначе рендер ругается «элементы SVG заходят на правое поле». Длинное пояснение рядом с самым длинным столбцом переноси в строку названия.
  • Порядковые числительные в SVG пиши без дефиса: из-за tabular-nums «15-е место» рендерится как «15 - е». Пиши «15 место» или вынеси числительное в HTML-подпись.
  • Когда нужно показать несоразмерность меры, сравнивай с тем, что читатель знает сам: цена месяца связи, минимальная зарплата, та же услуга в прошлом году, та же ситуация в другой стране. База — на самой картинке: «100% = МРОТ, 27 093 ₽», «в рублях по курсу 85,5 ₽ за доллар». Не убирай столбцы, которые тезис ослабляют (страны, где дороже): картинка, которая говорит больше данных, подводит и статью, и канал. Если сравниваются величины разной природы (цена сверх лимита и средняя цена в пакете), это пишется в сноске.
  • Расчётные числа помечай на картинке: «расчёт wiki2.zapret.moe» (имя вики — рабочее на сегодня, zapret-links link wiki; заблокированное имя render.py сам заменит и предупредит, потому что впечатанное в пиксели имя потом не исправить заменой текста) и формула в сноске, если столбцы получены умножением, а не взяты из источника. Цену, которую официально не объявляли, подписывай как обсуждавшуюся.
  • Схема из блоков и стрелок (путь пакета, «кто что видит») проще собирается обычным HTML на flex, чем в SVG: браузер сам раскладывает текст переменной длины. Кегль и палитра те же.
  • HTML-исходник держи в scratchpad; в vault он не попадает. Файл встраивается после абзаца, который разбирает эти данные. Обложка статьи — отдельная задача: обычно это авторский арт владелицы, а не диаграмма.

Проверка перед сдачей

Открой через Read готовый PNG и его превью .tg400.png и ответь на вопросы честно, не опираясь на то, что знаешь из статьи:

  • Заголовок сообщает вывод, а не тему. Прочитав только его, можно пересказать главное.
  • За пять секунд, не читая легенду, сноски и оси, понятно, что главное на картинке и почему оно важно.
  • Цветом выделено то, о чём говорит заголовок, остальное нейтральное.
  • У каждой цветной группы есть подпись со смыслом рядом с ней. Диапазонов без вывода нет.
  • У каждого процента и у каждой нулевой или стопроцентной линии прямо на графике написано, от чего считается.
  • Нет жаргона; единицы подписаны словами.
  • На превью .tg400.png читаются заголовок, подписи групп и ключевые числа.
  • Рендер прошёл без единого «ВНИМАНИЕ»: весь текст в Inter Variable, ничего не обрезано и не заходит на поля.
  • Картинка понятна без статьи: есть что измерено, период и источник с датой.
  • Числа совпадают с текстом, шкала линейная, подписи не наезжают друг на друга.

Если хоть один пункт не выполнен, переделай график, а не дописывай пояснение в текст статьи: в посте Telegram этого текста рядом не будет.

Разбор на реальных графиках

Плитки «27 регионов» (DPI/attachments/isp-licensing-27-regions-chart.png). Главное число работает: 27 регионов крупно, красные плитки. Но рядом ещё четыре цвета с легендой «1–29%», «30–49%», «50–69%», «70–96%», и для двух последних групп вывода нет вообще. Как надо: три группы с человеческими подписями у самих плиток — «27 регионов потеряют всех местных провайдеров» (красный), «21 регион потеряет больше половины» (оранжевый), «остальные сохранят большую часть» (серый).

Взнос против прибыли (isp-licensing-27-regions-fee-vs-profit.png). Ось в процентах, линия 100%, числа 714, 71, 20, <1. Чтобы понять, что сравнивается, нужно прочитать подзаголовок, осмыслить ось и догадаться, что 100% — вся годовая прибыль. Как надо: заголовок «Самым мелким провайдерам взнос обойдётся в 7 годовых прибылей», а на графике для каждой группы два столбца в рублях рядом, «типичная прибыль за год» и «взнос 1 млн ₽», либо проценты с подписью на линии «100% = вся прибыль за год».

Динамика видеохостингов (youtube-h1-2026-dynamics.png). Заголовок «Кто вырос, а кто просел» называет тему, у оси голый «0», все столбцы одинаково яркие. Как надо: «YouTube вырос вдвое сильнее российских площадок», YouTube синий, просевшие площадки красные (падение Premier на 20% — второй вывод статьи), остальные серые, у нулевой линии подпись «столько же, сколько в 2025 году». Именно эта переделка лежит в template.html: отрендери его, чтобы увидеть эталон.