astra-figma-doc-build — Документация компонента Astra DS в Figma

Источник: ds-skills/src/skills/astra-figma-doc-build/SKILL.md Справочники, плагин и скилл агента Figma — вложенные страницы. В вики не выложены, лежат в папке скилла: CHANGELOG.md, plugin/core.js, plugin/plugin.js, plugin/code.ts, plugin/ui.html, plugin/build.mjs, figma-agent/check.mjs.

Шапка скилла:

name: astra-figma-doc-build
description: "Собирает документацию компонента Astra DS прямо в Figma по шаблону ds-component из библиотеки «Astra DS: Docs». Вход — ссылка на сам компонент (COMPONENT_SET или COMPONENT), больше ничего не нужно. Скилл снимает варианты, свойства и структуру и строит секцию из трёх страниц: «История изменений», «Спецификация», «❖ Компонент». Работает только на новых атомах шаблона (ds-mcp-component, ds-mcp-component-state, ds-mcp-component-label), устаревшие ds-component-state и ds-anatomy-* не трогает. Вопросов почти не задаёт — рассчитан на документацию многих компонентов подряд. Использовать, когда прислана ссылка на компонент Astra DS и просят «задокументируй компонент в Figma», «собери документацию в Figma», «оформи по ds-component», «сделай секцию документации», «построй доку по шаблону Astra». Не путать с astra-figma-to-md: тот читает готовую документацию и пишет markdown. Требует Figma MCP с правом записи."

Вход — ссылка на компонент Astra DS. Выход — SECTION с тремя страницами документации, собранными из атомов библиотеки «Astra DS: Docs». Скилл ничего не рисует с нуля: он ставит инстансы шаблона ds-component и заполняет их фактами из компонента.

Страниц всегда три: «История изменений», «Спецификация», «❖ Компонент». В шаблоне ds-component их пять, но «Рекомендации» и «Редактура» из компонента не выводятся: там примеры «хорошо / плохо» и правила текста. Их дизайнер добавляет сам из того же шаблона. Решение записано в ds-internal/decisions.md от 22.10.2026.

Версия 0.4.0. Статус и история — в CHANGELOG.md.

Плагин в Figma и короткий путь

Тот же конвейер собран в плагин «Документация Astra DS»: дизайнер выделяет компонент и нажимает кнопку, Claude не нужен. Код и ссылка для запуска — plugin/README.md.

Для агента, встроенного в Figma, есть скилл astra-ds-doc-build одним файлом: команда Rossel добавляет его в Skills и вызывает /astra-ds-doc-build. Файл и как его опубликовать — figma-agent/README.md.

Ядро плагина plugin/core.js годится и для скилла: его текст плюс вызов buildDocs(set, { date, change, annotate }) укладываются в один вызов use_figma (меньше 50 000 знаков) и собирают секцию целиком. Так проверено 22.10.2026 в песочнице на наборе из 54 вариантов: первая сборка и пересборка с новой записью журнала. Это путь по умолчанию. Пошаговые рецепты (references/build-recipes.md) нужны, когда ядро упало и надо найти шаг, или когда сборку нужно поправить вручную.

Обязательный контекст

Не читается хотя бы один файл — назвать его и остановиться. Восстанавливать ключи чтением Figma «по памяти» нельзя: результат будет разным от запуска к запуску.

Как запускать

Нужны три возможности: выполнить JS в файле Figma, снять картинку узла, писать в файл. Нет хотя бы одной — остановиться и назвать, какой.

Контракт вызова:

• один вызов — один логический шаг; страница собирается за несколько вызовов;
• результат — только через return, console.log не виден;
• setCurrentPageAsync — ровно один раз за вызов;
• вызов возвращает id всех созданных и изменённых узлов;
• упавший вызов не повторять вслепую: прочитать ошибку, исправить, повторить;
• ответ MCP обрезается на 20 КБ — дерево больше 6–8 мастеров за раз не снимать;
• песочница не знает ?., ?? и structuredClone — код рецептов написан без них.

Незыблемые правила

1. Библиотека «Astra DS: Docs» обязательна. Шаблон и атомы берутся только импортом по ключу. Ключ не импортируется — библиотека не подключена к файлу: остановиться и попросить включить её в Assets → Libraries. Подключить библиотеку из кода нельзя.
2. По имени не искать. В библиотеке задвоены имена: ds-anatomy-padding встречается трижды, ds-anatomy-size, ds-video, ds-gradient — дважды. Поиск по имени цепляет не тот компонент. Только ключи из engine-map.md.
3. Только новые атомы. Набор атомов — ровно тот, из которого собран шаблон ds-component. Устаревшие (ds-component-state, ds-component-label, ds-component-slot, ds-anatomy-*) не ставить, даже если ими собраны соседние секции файла. Список — engine-map.md, раздел 5.
4. Вход — сам компонент. COMPONENT_SET или COMPONENT. Инстанс, фрейм, секция, группа — остановиться.
5. Исходник не трогать. Свойства, слои, имя, описание — только чтение. Одно исключение: набор вариантов переезжает на страницу «❖ Компонент» (шаг 3.3). Так устроены все живые секции документации Astra DS, и подтверждения это не требует.
6. Шапку не трогать. ds-head каждой страницы остаётся как в шаблоне: заголовок, подзаголовок и метки платформ заданы вариантом Context. Имя компонента в шапку не пишется.
7. Чисел в тексте нет. Размеры, отступы, радиусы, цвета, типографика — аннотациями на слоях (annotations.md), не прозой.
8. Визуал значениями не задавать. Никаких fills, fontSize, fontName, cornerRadius числом на созданных узлах: всё приходит из атомов. Отступы и шаг между блоками копировать с узлов шаблона. Исключение — сама SECTION (шаг 2), и та только привязкой к переменным.
9. Писать только в свою SECTION. Старые секции документации не менять и не удалять — удаление предложить в отчёте.
10. Факты — из компонента, формулировки — из texts.md. Свойства, значения, варианты, слои берутся из инвентаря, порядок — порядок объявления свойств. Всё, что скилл написал сам, перечисляется в отчёте. В каждом тексте — неразрывные пробелы (texts.md, раздел 4).

Конвейер

0 Готовность → 1 Вход и инвентарь → 2 Площадка → 3 Три страницы → 4 Сдача

Каждый шаг начинается с короткого отчёта фактами: что прочитано, что найдено, что будет записано. Отчёт — не вопрос: назвать факты и продолжать. От ссылки до готовой секции подтверждений нет. Остановки — только там, где написано «остановиться», и каждая из них тупик, а не пауза: нет библиотеки, на входе не компонент, не импортируется ключ. До конца шага 2 в файл ничего не пишется.

0. Готовность

1. Прочитать четыре файла из таблицы «Обязательный контекст».
2. Импортировать по ключу шаблон ds-component, три страницы и атомы (рецепт 2). Хотя бы один ключ не импортировался — остановиться и вернуть три списка: ожидалось, импортировано, не хватает. Вероятная причина — библиотеку перепубликовали и компонент удалён или заменён: карту надо обновить (engine-map.md, раздел 7).
3. Собрать шрифты с текстовых слоёв импортированных страниц и загрузить их (рецепт 2). Список шрифтов не хардкодить.

1. Вход и инвентарь

fileKey и node-id — из ссылки (дефис между числами меняется на двоеточие). Нет node-id — попросить ссылку на сам компонент.

Инвентарь (рецепт 1, только чтение): имя, key, description, documentationLinks, componentPropertyDefinitions в порядке объявления, варианты с variantProperties и положением на холсте, defaultVariant, дерево мастера по умолчанию на три уровня, вложенные инстансы. Отдельно — где набор лежит сейчас: страница, ближайшая SECTION-предок и фреймы в ней.

Имена — дословно, с опечатками. Замеченные опечатки идут в отчёт отдельным пунктом: находка для владельца, а не повод править документацию.

Отчёт перед шагом 2: имя, число вариантов, оси со значениями, свойства в порядке объявления, откуда возьмётся лид, первая это сборка или пересборка.

2. Площадка

Секция строится на той же странице, где лежит компонент.

Пересборка. Записи ds-log старой «Истории изменений» переносятся в новую копиями, в том же порядке. Текущая версия — версия последней записи. Новая запись добавляется, только если пользователь назвал изменение (тип — по texts.md, раздел 3). Старую секцию не трогать: после переезда набора её страница «Компонент» останется пустой — сказать об этом в отчёте и предложить удалить. Удаляет человек.

Затем один вызов (рецепт 2a): SECTION с именем компонента правее самого правого узла страницы, оформление — привязкой к переменным «Astra DS: Docs». Если на странице есть готовая секция документации, оформление копируется с неё.

Раскладка: отступ 100 от края секции со всех сторон, страницы слева направо с шагом 100, в порядке «История изменений» → «Спецификация» → «❖ Компонент». Так разложена секция Locator, самая свежая в файле.

3. Три страницы

Общий ход для каждой (рецепт 3): импорт страницы по ключу → createInstance() → detachInstance() → фрейм в секцию → имя фрейма = имя компонента страницы → очистить Content от демо-блоков → заполнить. Шапка Header остаётся инстансом ds-head. Атомы внутри страницы остаются инстансами — открепляется только обёртка страницы.

После каждой страницы — снимок и сверка: нет ли переполнений, наложений, обрезанного текста. Ошибку раскладки чинить сразу, до следующей страницы.

3.1 «История изменений»

Content содержит только записи ds-log. Порядок как в живых секциях Astra DS: старая запись сверху, новая — снизу, то есть appendChild, а не вставка в начало.

Первая сборка — одна запись (рецепт 4):

Пересборка — копии старых записей плюс, если пользователь назвал изменение, одна новая запись внизу. Версия новой записи считается от последней по типу (texts.md, раздел 3).

3.2 «Спецификация»

Блоки сверху вниз:

1. Лид — ds-paragraph Type=H1, Show Title = false. Текст — description компонента дословно. Пусто — шаблон лида из texts.md.
2. Структура — группа шаблона: ds-paragraph-dev-mode (неизменный текст про Dev Mode) и ds-mcp-component View=Anatomy, Show Title = false. В слот Slot Container — инстанс мастера по умолчанию. На слои инстанса — аннотации по annotations.md.
3. Блок на каждое свойство VARIANT и собственное BOOLEAN — в порядке componentPropertyDefinitions, без сортировки. Блок — группа из двух узлов:
   • ds-paragraph Type=H1: заголовок из глоссария, иначе имя свойства дословно; описание по шаблону;
   • ds-mcp-component View=State, Show Title = false, Show Desciption = false; в слот Slot Container State — по строке ds-mcp-component-state на значение.

Строка ds-mcp-component-state (рецепт 5):

Если в наборе нет варианта «по умолчанию, кроме одного свойства», берётся вариант с этим значением, ближайший к мастеру по умолчанию по остальным свойствам. Такую строку назвать в отчёте: набор разрежен.

Свойства TEXT, INSTANCE_SWAP и SLOT блоков не получают — у них нет перечислимых значений. Проброшенные свойства вложенных инстансов — тоже. Всё это идёт в отчёт списком «свойства без блока».

3.3 «❖ Компонент»

Страница показывает сам набор вариантов с подписями осей (рецепт 6):

Оси — по геометрии набора, а не по порядку объявления. Варианты группируются в столбцы по x и в строки по y. Свойство, постоянное внутри каждого столбца, — ось столбцов; постоянное внутри каждой строки — ось строк. Чем меньше подписей у оси, тем она внешнее; у внешнего уровня Large=True. Подпись растягивается на всю группу своих вариантов. Ось, которая не легла ни в столбцы, ни в строки, подписи не получает и идёт в отчёт.

Перенос набора безусловный. Меняются родитель и место на холсте. Ключ компонента, свойства и все его инстансы в макетах не меняются. В отчёте назвать, откуда набор уехал.

4. Сдача

1. Подогнать секцию последней, когда высоты страниц окончательные: размер = границы содержимого плюс 100 с каждой стороны, resizeWithoutConstraints. SECTION сама не обтягивает.
2. Снять секцию целиком и проверить по чек-листу.
3. Отчёт (подписи — texts.md, раздел 5): ссылка на секцию, три страницы, число блоков и строк, список сгенерированных текстов, свойства без блока, оси без подписи, разреженные строки, опечатки исходника, что осталось незаполненным, откуда уехал набор, что делать со старой секцией при пересборке.

Тексты

Скилл пишет формулировки сам — только по шаблонам texts.md. Тон сухой, описательный, без оценок и советов. Язык — русский: вся документация Astra DS на русском.

Не генерировать никогда — оставить пустым и назвать в отчёте:

• когда какой вариант применять;
• чем стили отличаются по смыслу, а не по виду;
• правила текста и микрокопирайтинг;
• рекомендации «делать / не делать»;
• назначение слоя, если оно не следует из имени слоя.

Пустой блок лучше правдоподобной выдумки: сгенерированный текст пересказывает инвентарь и проверяется по нему.

Слой, назначение которого не выводится из имени, всё равно получает аннотацию: labelMarkdown — имя слоя жирным, без пояснения, properties — как обычно. Сам слой идёт в отчёт: смысл добавит владелец.

Чек-лист

1. componentPropertyDefinitions исходника совпадают до и после сборки.
2. Собраны ровно три страницы, все внутри одной SECTION.
3. Шапки ds-head не тронуты; имя фрейма каждой страницы = имя её компонента в шаблоне.
4. На страницах нет ни одного устаревшего атома (engine-map.md, раздел 5).
5. На созданных узлах нет визуала, заданного числом.
6. Чисел в тексте нет; неразрывные пробелы стоят.
7. Аннотации на каждом слое с раскладкой, категория и properties заданы.
8. Блоки «Спецификации» идут в порядке объявления свойств.
9. «❖ Компонент»: в Container один узел — набор; подписи дословно совпадают со значениями свойств; скобки подписей совпадают с группами вариантов.
10. «История изменений»: версия и тип по правилу, дата с ведущими нулями, новая запись внизу.
11. Снимок каждой страницы просмотрен: нет переполнений и наложений.
12. SECTION оформлена привязками и подогнана с отступом 100.
13. В отчёте: сгенерированные тексты, свойства без блока, опечатки, незаполненное.