Excalidraw

Рисованные JSON-диаграммы Excalidraw (архитектура, схемы, последовательности).

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

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

Навык диаграмм Excalidraw

Создавайте диаграммы, описывая элементы в стандартном JSON-формате Excalidraw и сохраняя их в файлы .excalidraw. Такие файлы можно перетащить прямо в excalidraw.com для просмотра и редактирования. Никаких аккаунтов, ключей API и библиотек рендеринга — только JSON.

Когда использовать

Генерируйте файлы .excalidraw для диаграмм архитектуры, блок-схем, диаграмм последовательностей, концептуальных карт и не только. Файлы открываются на excalidraw.com или загружаются для получения ссылки, которой можно поделиться.

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

1. Загрузите этот навык (вы уже это сделали)
2. Опишите элементы в JSON — массив объектов-элементов Excalidraw
3. Сохраните файл с помощью write_file, создав файл .excalidraw
4. При желании загрузите файл для получения ссылки через scripts/upload.py в terminal

Сохранение диаграммы

Оберните массив элементов в стандартный конверт .excalidraw и сохраните через write_file:

{
  "type": "excalidraw",
  "version": 2,
  "source": "hermes-agent",
  "elements": [ ...your elements array here... ],
  "appState": {
    "viewBackgroundColor": "#ffffff"
  }
}

Сохраняйте по любому пути, например ~/diagrams/my_diagram.excalidraw.

Загрузка для получения ссылки

Запустите скрипт загрузки (находится в каталоге scripts/ этого навыка) через terminal:

python skills/creative/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw

Скрипт загружает файл на excalidraw.com (аккаунт не нужен) и выводит ссылку для доступа. Требуется pip-пакет cryptography (pip install cryptography).

---

Справочник по формату элементов

Обязательные поля (для всех элементов)

type, id (уникальная строка), x, y, width, height

Значения по умолчанию (их можно не указывать — применяются автоматически)

• strokeColor: "#1e1e1e"
• backgroundColor: "transparent"
• fillStyle: "solid"
• strokeWidth: 2
• roughness: 1 (рисованный стиль)
• opacity: 100

Фон холста — белый.

Типы элементов

Прямоугольник:

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }

• roundness: { "type": 3 } для скруглённых углов
• backgroundColor: "#a5d8ff", fillStyle: "solid" для заливки

Эллипс:

{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }

Ромб:

{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }

Фигура с подписью (привязка контейнера) — создайте текстовый элемент, привязанный к фигуре:

ВНИМАНИЕ: НЕ используйте "label": { "text": "..." } для фигур. Это НЕ валидное свойство Excalidraw — оно молча игнорируется, и фигура остаётся пустой. Нужно использовать привязку контейнера, как показано ниже.

Фигуре нужен boundElements со ссылкой на текст, а тексту — containerId, указывающий обратно на фигуру:

{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
  "boundElements": [{ "id": "t_r1", "type": "text" }] },
{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "r1", "originalText": "Hello", "autoResize": true }

• Работает для прямоугольника, эллипса, ромба
• Excalidraw автоматически центрирует текст, когда задан containerId
• Значения x/y/width/height текста примерные — Excalidraw пересчитывает их при загрузке
• originalText должен совпадать с text
• Всегда указывайте fontFamily: 1 (шрифт Virgil, рисованный стиль)

Стрелка с подписью — та же схема привязки контейнера:

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
  "boundElements": [{ "id": "t_a1", "type": "text" }] },
{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
  "textAlign": "center", "verticalAlign": "middle",
  "containerId": "a1", "originalText": "connects", "autoResize": true }

Отдельный текст (только для заголовков и аннотаций — без контейнера):

{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
  "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }

• x — это ЛЕВЫЙ край. Чтобы центрировать по позиции cx: x = cx - (text.length * fontSize * 0.5) / 2
• НЕ полагайтесь на textAlign или width при позиционировании

Стрелка:

{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
  "points": [[0,0],[200,0]], "endArrowhead": "arrow" }

• points: смещения [dx, dy] относительно x, y элемента
• endArrowhead: null | "arrow" | "bar" | "dot" | "triangle"
• strokeStyle: "solid" (по умолчанию) | "dashed" | "dotted"

Привязка стрелок (соединение стрелок с фигурами)

{
  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
  "points": [[0,0],[150,0]], "endArrowhead": "arrow",
  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
}

Координаты fixedPoint: top=[0.5,0], bottom=[0.5,1], left=[0,0.5], right=[1,0.5]

Порядок отрисовки (z-order)

• Порядок в массиве = z-order (первый элемент — сзади, последний — спереди)
• Формируйте последовательно: фоновые зоны → фигура → её привязанный текст → её стрелки → следующая фигура
• ПЛОХО: сначала все прямоугольники, потом весь текст, потом все стрелки
• ХОРОШО: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → …
• Всегда размещайте привязанный текстовый элемент сразу после его фигуры-контейнера

Рекомендации по размерам

Размер шрифта:

• Минимальный fontSize: 16 для основного текста, подписей, описаний
• Минимальный fontSize: 20 для заголовков
• Минимальный fontSize: 14 только для второстепенных аннотаций (и то по минимуму)
• НИКОГДА не используйте fontSize меньше 14

Размер элементов:

• Минимальный размер фигуры: 120x60 для прямоугольников/эллипсов с подписью
• Оставляйте между элементами минимум 20–30 px
• Лучше меньше элементов покрупнее, чем много мелких

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

Полные цветовые таблицы — в references/colors.md. Краткая шпаргалка:

Советы

• Используйте цветовую палитру единообразно по всей диаграмме
• Контраст текста КРИТИЧЕН — никогда не используйте светло-серый на белом фоне. Минимальный цвет текста на белом: #757575
• НЕ используйте эмодзи в тексте — шрифт Excalidraw их не отображает
• Для диаграмм в тёмном режиме см. references/dark-mode.md
• Более крупные примеры — в references/examples.md