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

Генерация плоских минималистичных SVG-диаграмм с адаптацией под светлую/тёмную тему в виде автономных HTML-файлов, использующих единый образовательный визуальный язык с 9 семантическими цветовыми шкалами, типографикой в предложном падеже и автоматическим тёмным режимом. Лучше всего подходит для образовательных и нетехнических визуализаций: физические установки, механизмы химических реакций, математические кривые, физические объекты (самолёты, турбины, смартфоны, механические часы), анатомия, планы этажей, поперечные сечения, повествовательные путешествия (жизненный цикл X, процесс Y), интеграции систем типа «звезда» (умный город, Интернет вещей) и взрыв-схемы слоёв. Если для данной темы существует более специализированный навык (специализированное ПО/облачная архитектура, рисунки от руки, анимированные объяснения и т.д.), используйте его — в противном случае этот навык может служить универсальным запасным вариантом для SVG-диаграмм с чистым образовательным видом. Поставляется с 15 примерами диаграмм.

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

Источник	Опционально — установка с помощью vibeos skills install official/creative/concept-diagrams
Путь	optional-skills/creative/concept-diagrams
Версия	0.1.0
Автор	v1k22 (оригинальный PR), портировано в vibeos-agent
Лицензия	MIT
Платформы	linux, macos, windows
Теги	diagrams, svg, visualization, education, physics, chemistry, engineering
Связанные навыки	architecture-diagram, excalidraw, generative-widgets

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

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

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

Генерация 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 шаблона обработает оба режима.

Класс	50 (самый светлый)	100	200	400	600	800	900 (самый тёмный)
c-purple	#EEEDFE	#CECBF6	#AFA9EC	#7F77DD	#534AB7	#3C3489	#26215C
c-teal	#E1F5EE	#9FE1CB	#5DCAA5	#1D9E75	#0F6E56	#085041	#04342C
c-coral	#FAECE7	#F5C4B3	#F0997B	#D85A30	#993C1D	#712B13	#4A1B0C
c-pink	#FBEAF0	#F4C0D1	#ED93B1	#D4537E	#993556	#72243E	#4B1528
c-gray	#F1EFE8	#D3D1C7	#B4B2A9	#888780	#5F5E5A	#444441	#2C2C2A
c-blue	#E6F1FB	#B5D4F4	#85B7EB	#378ADD	#185FA5	#0C447C	#042C53
c-green	#EAF3DE	#C0DD97	#97C459	#639922	#3B6D11	#27500A	#173404
c-amber	#FAEEDA	#FAC775	#EF9F27	#BA7517	#854F0B	#633806	#412402
c-red	#FCEBEB	#F7C1C1	#F09595	#E24B4A	#A32D2D	#791F1F	#501313

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

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

• Группируйте узлы по категориям — все узлы одного типа используют один цвет.
• Используйте 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

Типографика

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

Класс	Размер	Насыщенность	Использование
th	14px	500	Заголовки узлов, метки областей
ts	12px	400	Подзаголовки, описания, метки стрелок
t	14px	400	Общий текст

• Всегда предложный падеж. Никогда не используйте Заглавный Регистр или ВСЕ ПРОПИСНЫЕ.
• Каждый <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>

  <!-- Содержимое диаграммы здесь -->

</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">Имя сервиса</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">Имя сервиса</text>
  <text class="ts" x="200" y="56" text-anchor="middle" dominant-baseline="central">Краткое описание</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">Метка контейнера</text>
  <text class="ts" x="66" y="134">Информация подзаголовка</text>
</g>

---

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

Выберите макет, который соответствует теме:

1. Блок-схема — CI/CD пайплайны, жизненные циклы запросов, процессы согласования, обработка данных. Однонаправленный поток (сверху вниз или слева направо). Максимум 4-5 узлов в строке.
2. Структурная / Вложенная — Вложенность облачной инфраструктуры, системная архитектура с уровнями. Большие внешние контейнеры с внутренними областями. Пунктирные прямоугольники для логических группировок.
3. Карта API / Эндпоинтов — REST маршруты, GraphQL схемы. Дерево от корня, ветвление к группам ресурсов, каждая содержит узлы эндпоинтов.
4. Топология микросервисов — Сервисная сетка, событийно-ориентированные системы. Сервисы как узлы, стрелки для шаблонов коммуникации, очереди сообщений между ними.
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 >= (длина_самой_длинной_метки × 8) + 48 для текста 14px.
6. box_width >= (длина_самой_длинной_метки × 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"
).replace(
    "<!-- OPTIONAL SUBTITLE HERE -->", "Бимолекулярное нуклеофильное замещение"
).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...

# Обслуживайте только на loopback, свободный порт
cd .diagrams && python3 -c "
import http.server, socketserver
with socketserver.TCPServer(('127.0.0.1', 0), http.server.SimpleHTTPRequestHandler) as s:
    print(f'Сервер запущен на 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 полных протестированных диаграмм. Просмотрите их для поиска рабочих шаблонов перед написанием новой диаграммы аналогичного типа:

Файл	Тип	Демонстрирует
hospital-emergency-department-flow.md	Блок-схема	Маршрутизация по приоритету с семантическими цветами
feature-film-production-pipeline.md	Блок-схема	Поэтапный рабочий процесс, горизонтальные подпотоки
automated-password-reset-flow.md	Блок-схема	Поток аутентификации с ветвями ошибок
autonomous-llm-research-agent-flow.md	Блок-схема	Стрелки обратной связи, ветви принятия решений
place-order-uml-sequence.md	Последовательность	Стиль UML диаграммы последовательности
commercial-aircraft-structure.md	Физическая	Пути, полигоны, эллипсы для реалистичных форм
wind-turbine-structure.md	Физическое поперечное сечение	Разделение подземной/надземной частей, цветовое кодирование
smartphone-layer-anatomy.md	Взрыв-схема	Чередующиеся левые/правые метки, слоистые компоненты
apartment-floor-plan-conversion.md	План этажа	Стены, двери, предлагаемые изменения пунктирным красным
banana-journey-tree-to-smoothie.md	Повествовательное путешествие	Извилистый путь, прогрессивные изменения состояния
cpu-ooo-microarchitecture.md	Аппаратный конвейер	Разветвление, боковая панель иерархии памяти
sn2-reaction-mechanism.md	Химия	Молекулы, изогнутые стрелки, энергетический профиль
smart-city-infrastructure.md	Звезда	Семантические стили линий для каждой системы
electricity-grid-flow.md	Многоступенчатый поток	Иерархия напряжений, маркеры потока
ml-benchmark-grouped-bar-chart.md	Диаграмма	Сгруппированные столбцы, двойная ось

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

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

---

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

Пользователь говорит	Тип диаграммы	Рекомендуемые цвета
«покажи пайплайн»	Блок-схема	серый начало/конец, фиолетовый шаги, красный ошибки, бирюзовый развёртывание
«нарисуй поток данных»	Пайплайн данных (слева направо)	серый источники, фиолетовый обработка, бирюзовый приёмники
«визуализируй систему»	Структурная (вложенная)	фиолетовый контейнер, бирюзовый сервисы, коралловый данные
«отобрази эндпоинты»	Дерево API	фиолетовый корень, одна шкала на группу ресурсов
«покажи сервисы»	Топология микросервисов	серый входящий трафик, бирюзовый сервисы, фиолетовый шина, коралловый воркеры
«нарисуй самолёт/транспорт»	Физическая	пути, полигоны, эллипсы для реалистичных форм
«умный город / IoT»	Интеграция звезда	семантические стили линий для каждой подсистемы
«покажи дашборд»	Макет UI	тёмный экран, цвета диаграмм: бирюзовый, фиолетовый, коралловый для оповещений
«электросеть / электричество»	Многоступенчатый поток	иерархия напряжений (толщина линий ВН/СН/НН)
«ветряная турбина / турбина»	Физическое поперечное сечение	фундамент + разрез башни + цветовое кодирование гондолы
«путешествие X / жизненный цикл»	Повествовательное путешествие	извилистый путь, прогрессивные изменения состояния
«слои X / взрыв-схема»	Взрыв-схема слоёв	вертикальный стек, чередующиеся метки
«ЦП / конвейер»	Аппаратный конвейер	вертикальные стадии, разветвление к портам выполнения
«план этажа / квартира»	План этажа	стены, двери, предлагаемые изменения пунктирным красным
«механизм реакции»	Химия	атомы, связи, изогнутые стрелки, переходное состояние, энергетический профиль