Концептуальные диаграммы

Создаёт плоские минималистичные учебные SVG-изображения в виде HTML.

Метаданные навыка

Справочник: полный SKILL.md

Концептуальные диаграммы

Создаёт SVG-диаграммы производственного качества в единой плоской минималистичной дизайн-системе. На выходе — один самодостаточный HTML-файл, который одинаково отображается в любом современном браузере и сам переключается между светлой и тёмной темой.

Область применения

Лучше всего подходит для:

• Схемы физических установок, химические механизмы, математические кривые, биология
• Физические объекты (самолёты, турбины, смартфоны, механические часы, клетки)
• Анатомия, разрезы, послойные взрыв-схемы
• Планы помещений, перепланировки
• Сюжетные истории («жизненный цикл X», «процесс Y»)
• Интеграции систем по схеме «центр — лучи» (умный город, сети IoT, электросети)
• Учебные материалы в стиле учебника в любой области
• Количественные графики (сгруппированные столбцы, энергетические профили)

Сначала поищите другой навык, если речь о:

• Архитектуре ПО или облачной инфраструктуры в тёмной техноэстетике (попробуйте architecture-diagram, если он есть)
• Набросках от руки в стиле маркерной доски (попробуйте excalidraw, если он есть)
• Анимированных роликах или видео (попробуйте навык для анимации)

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

Рабочий процесс

1. Определитесь с типом диаграммы (см. раздел «Типы диаграмм» ниже).
2. Расположите компоненты по правилам дизайн-системы.
3. Соберите полную HTML-страницу, взяв templates/template.html как обёртку — вставьте свой SVG туда, где в шаблоне стоит <!-- PASTE SVG HERE -->.
4. Сохраните как самостоятельный .html-файл (например, ~/my-diagram.html или ./my-diagram.html).
5. Пользователь открывает его прямо в браузере — без сервера, без зависимостей.

Дополнительно: если пользователю нужна листаемая галерея из нескольких диаграмм, см. «Локальный сервер предпросмотра» в конце.

Загрузите HTML-шаблон:

skill_view(name="concept-diagrams", file_path="templates/template.html")

Шаблон содержит всю CSS-систему дизайна (цветовые классы c-*, текстовые классы, переменные для светлой и тёмной темы, стили маркеров-стрелок). Сгенерированный SVG требует, чтобы эти классы были на странице-носителе.

Дизайн-система

Философия

• Плоско: никаких градиентов, теней, размытия, свечения или неона.
• Минимально: только суть. Никаких декоративных иконок внутри блоков.
• Согласованно: одни и те же цвета, отступы, типографика и толщины обводки во всех диаграммах.
• Готово к тёмной теме: все цвета подстраиваются через CSS-классы — отдельный SVG для каждого режима не нужен.

Цветовая палитра

9 цветовых шкал, по 7 ступеней в каждой. Имя класса ставится на элемент <g> или фигуру; CSS шаблона обрабатывает оба режима.

Правила назначения цветов

Цвет кодирует смысл, а не порядок. Никогда не перебирайте цвета как радугу.

• Группируйте узлы по категориям — все узлы одного типа делят один цвет.
• Берите c-gray для нейтральных и структурных узлов (начало, конец, обычные шаги, пользователи).
• Используйте 2–3 цвета на диаграмму, не 6 и больше.
• Для общих категорий предпочитайте c-purple, c-teal, c-coral, c-pink.
• Оставьте c-blue, c-green, c-amber, c-red под семантику (информация, успех, предупреждение, ошибка).

Сопоставление ступеней со светлой и тёмной темой (обрабатывает CSS шаблона — просто примените класс):

• Светлая тема: заливка 50 + обводка 600 + заголовок 800 / подзаголовок 600
• Тёмная тема: заливка 800 + обводка 200 + заголовок 100 / подзаголовок 200

Типографика

Только два размера шрифта. Без исключений.

• Всегда как в предложении. Никогда Title Case, никогда ВЕРХНИЙ РЕГИСТР.
• У каждого <text> ОБЯЗАТЕЛЬНО должен быть класс (t, ts или th). Текста без класса не бывает.
• dominant-baseline="central" на всём тексте внутри блоков.
• text-anchor="middle" для текста, центрированного в блоках.

Оценка ширины (приблизительно):

• 14px насыщенность 500: ~8px на символ
• 12px насыщенность 400: ~6.5px на символ
• Всегда проверяйте: box_width >= (char_count × px_per_char) + 48 (отступ 24px с каждой стороны)

Отступы и компоновка

• ViewBox: viewBox="0 0 680 H", где H = высота содержимого + 40px запаса.
• Безопасная область: от x=40 до x=640, от y=40 до y=(H-40).
• Между блоками: минимум 60px зазора.
• Внутри блоков: 24px горизонтального отступа, 12px вертикального.
• Зазор у стрелки: 10px между остриём и краем блока.
• Однострочный блок: высота 44px.
• Двухстрочный блок: высота 56px, 18px между базовыми линиями заголовка и подзаголовка.
• Отступ контейнера: минимум 20px внутри каждого контейнера.
• Максимальная вложенность: 2–3 уровня. Глубже — нечитаемо при ширине 680px.

Обводка и фигуры

• Толщина обводки: 0.5px на всех границах узлов. Не 1px, не 2px.
• Скругление прямоугольников: rx="8" для узлов, rx="12" для внутренних контейнеров, от rx="16" до rx="20" для внешних контейнеров.
• Пути-соединители: ОБЯЗАТЕЛЬНО fill="none". Иначе SVG по умолчанию заливает чёрным (fill: black).

Маркер-стрелка

Добавляйте этот блок <defs> в начало каждого SVG:

<defs>
  <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
          markerWidth="6" markerHeight="6" orient="auto-start-reverse">
    <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
          stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
  </marker>
</defs>

Применяйте marker-end="url(#arrow)" к линиям. Остриё наследует цвет линии через context-stroke.

CSS-классы (предоставляет шаблон)

Страница-шаблон даёт:

• Текст: .t, .ts, .th
• Нейтральные: .box, .arr, .leader, .node
• Цветовые шкалы: .c-purple, .c-teal, .c-coral, .c-pink, .c-gray, .c-blue, .c-green, .c-amber, .c-red (все с автоматическим переключением светлой и тёмной темы)

Переопределять их не нужно — просто применяйте в своём SVG. Файл шаблона содержит все CSS-определения.

SVG-заготовка

Каждый SVG внутри страницы-шаблона начинается ровно с этой структуры:

<svg width="100%" viewBox="0 0 680 {HEIGHT}" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
            markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke"
            stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
    </marker>
  </defs>

  <!-- Diagram content here -->

</svg>

Замените {HEIGHT} на реально рассчитанную высоту (низ последнего элемента + 40px).

Шаблоны узлов

Однострочный узел (44px):

<g class="node c-blue">
  <rect x="100" y="20" width="180" height="44" rx="8" stroke-width="0.5"/>
  <text class="th" x="190" y="42" text-anchor="middle" dominant-baseline="central">Service name</text>
</g>

Двухстрочный узел (56px):

<g class="node c-teal">
  <rect x="100" y="20" width="200" height="56" rx="8" stroke-width="0.5"/>
  <text class="th" x="200" y="38" text-anchor="middle" dominant-baseline="central">Service name</text>
  <text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Short description</text>
</g>

Соединитель (без подписи):

<line x1="200" y1="76" x2="200" y2="120" class="arr" marker-end="url(#arrow)"/>

Контейнер (пунктирный или сплошной):

<g class="c-purple">
  <rect x="40" y="92" width="600" height="300" rx="16" stroke-width="0.5"/>
  <text class="th" x="66" y="116">Container label</text>
  <text class="ts" x="66" y="134">Subtitle info</text>
</g>

Типы диаграмм

Выбирайте компоновку под тему:

1. Блок-схема — конвейеры CI/CD, жизненные циклы запросов, рабочие процессы согласования, обработка данных. Поток в одном направлении (сверху вниз или слева направо). Максимум 4–5 узлов в ряду.
2. Структура / вложенность — вложенность облачной инфраструктуры, многослойная архитектура систем. Крупные внешние контейнеры с внутренними областями. Пунктирные прямоугольники для логических групп.
3. Карта API / эндпойнтов — REST-маршруты, схемы GraphQL. Дерево от корня с ветвлением к группам ресурсов, в каждой — узлы-эндпойнты.
4. Топология микросервисов — service mesh, событийно-ориентированные системы. Сервисы как узлы, стрелки для схем взаимодействия, очереди сообщений между ними.
5. Поток данных — ETL-конвейеры, потоковые архитектуры. Движение слева направо: от источников через обработку к приёмникам.
6. Физика / структура — транспорт, здания, железо, анатомия. Используйте фигуры под физическую форму — <path> для изогнутых корпусов, <polygon> для сужающихся форм, <ellipse>/<circle> для цилиндрических деталей, вложенные <rect> для отсеков. См. references/physical-shape-cookbook.md.
7. Инфраструктура / интеграция систем — умные города, сети IoT, многодоменные системы. Компоновка «центр — лучи»: центральная платформа соединяет подсистемы. Семантические стили линий (.data-line, .power-line, .water-pipe, .road). См. references/infrastructure-patterns.md.
8. Макеты UI / дашбордов — админ-панели, дашборды мониторинга. Рамка экрана с вложенными графиками, индикаторами и шкалами. См. references/dashboard-patterns.md.

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

Контрольный список проверки

Прежде чем финализировать SVG, проверьте ВСЁ перечисленное:

1. У каждого <text> есть класс t, ts или th.
2. У каждого <text> внутри блока есть dominant-baseline="central".
3. У каждого <path> или <line> в роли стрелки есть fill="none".
4. Ни одна линия-стрелка не проходит сквозь посторонний блок.
5. box_width >= (longest_label_chars × 8) + 48 для текста 14px.
6. box_width >= (longest_label_chars × 6.5) + 48 для текста 12px.
7. Высота ViewBox = самый нижний элемент + 40px.
8. Всё содержимое остаётся в пределах от x=40 до x=640.
9. Цветовые классы (c-*) стоят на <g> или фигурах, никогда на путях-соединителях <path>.
10. Блок <defs> со стрелкой присутствует.
11. Никаких градиентов, теней, размытия или свечения.
12. Толщина обводки 0.5px на всех границах узлов.

Вывод и предпросмотр

По умолчанию: самостоятельный HTML-файл

Запишите один .html-файл, который пользователь откроет напрямую. Без сервера, без зависимостей, работает офлайн. Схема:

# 1. Загрузить шаблон
template = skill_view("concept-diagrams", "templates/template.html")

# 2. Подставить заголовок, подзаголовок и вставить свой SVG
html = template.replace(
    "<!-- DIAGRAM TITLE HERE -->", "SN2 reaction mechanism"
).replace(
    "<!-- OPTIONAL SUBTITLE HERE -->", "Bimolecular nucleophilic substitution"
).replace(
    "<!-- PASTE SVG HERE -->", svg_content
)

# 3. Записать по выбранному пользователем пути (или ./ по умолчанию)
write_file("./sn2-mechanism.html", html)

Подскажите пользователю, как открыть файл:

# macOS
open ./sn2-mechanism.html
# Linux
xdg-open ./sn2-mechanism.html

Дополнительно: локальный сервер предпросмотра (галерея из нескольких диаграмм)

Используйте это, только если пользователь прямо просит листаемую галерею из нескольких диаграмм.

Правила:

• Слушайте только 127.0.0.1. Никогда 0.0.0.0. Выставлять диаграммы на все сетевые интерфейсы опасно в общих сетях.
• Берите свободный порт (НЕ зашивайте его жёстко) и сообщите пользователю выбранный URL.
• Сервер необязателен и включается по желанию — сначала предпочитайте самостоятельный HTML-файл.

Рекомендуемая схема (пусть ОС сама выберет свободный эфемерный порт):

# Каждую диаграмму положить в свою папку внутри .diagrams/
mkdir -p .diagrams/sn2-mechanism
# ...записать .diagrams/sn2-mechanism/index.html...

# Отдавать только на петлевом интерфейсе, на свободном порту
cd .diagrams && python -c "
import http.server, socketserver
with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
    print(f'Serving at http://127.0.0.1:{s.server_address[1]}/')
    s.serve_forever()
" &

Если пользователь настаивает на фиксированном порте, используйте 127.0.0.1:<port> — но всё равно никогда 0.0.0.0. Опишите, как остановить сервер (kill %1 или pkill -f "http.server").

Справочник примеров

В каталоге examples/ поставляется 15 готовых протестированных диаграмм. Прежде чем создавать новую диаграмму похожего типа, изучите их: там собраны рабочие образцы.

Загрузить любой пример:

skill_view(name="concept-diagrams", file_path="examples/<filename>")

Краткая шпаргалка: что когда использовать