Карта шаблона ds-component в библиотеке «Astra DS: Docs» (references/engine-map.md)

Источник: ds-skills/src/skills/astra-figma-doc-build/references/engine-map.md — справочник скилла astra-figma-doc-build

Снято 22.10.2026 из файла Astra DS (eGpqY0OqVR8l8zhmlHdfb9), к которому подключена библиотека «Astra DS: Docs». Ключи — опубликованные, работают в любом файле, где библиотека включена. Файл самой библиотеки в этой карте не нужен.

---

1. Как находить

Только импортом по ключу: figma.importComponentByKeyAsync для компонентов, figma.importComponentSetByKeyAsync для наборов. Компоненты подключённой библиотеки Plugin API не перечисляет, а имена в «Astra DS: Docs» задвоены (раздел 6) — поиск по имени не работает дважды.

Id импортированного узла живёт один вызов. В каждом вызове, который пишет, импорт повторяется — это дёшево.

Ключ не импортировался — библиотека не включена в файле или компонент удалён при перепубликации. Первое чинит человек в Assets → Libraries, второе — обновление этой карты.

---

2. Шаблон и страницы

ds-component — компонент, ключ 8f7cbc56b451e2dafa03085a38c7b28835d397fa. Внутри пять инстансов страниц. Скилл импортирует шаблон только как проверку библиотеки, а страницы — каждую своим ключом.

У страниц нет свойств и слотов, поэтому обёртка страницы открепляется (detachInstance). Ширина страницы — 640, у «❖ Компонент» — по содержимому.

2.1 Устройство страницы

<Страница>                    FRAME после открепления, вертикальный auto-layout, gap 0
├── Header                    FRAME
│   └── ds-head               INSTANCE — не трогать
└── Content                   FRAME, вертикальный auto-layout
    └── … демо-блоки шаблона  удалить и заполнить своими

Демо-блоки шаблона:

Отступы групп (itemSpacing, padding*) копируются с демо-групп до их удаления, а не пишутся числом.

2.2 Сетка «❖ Компонент»

Name                                   вертикальный auto-layout, gap 24, padding 16
├── ds-format-component-head           → вложен ds-format-component-head-title
├── Components                         GRID 2×2
│   ├── Horizontal Props               правый верхний: строки «Variable» с подписями
│   ├── Components                     правый нижний, padding 24
│   │   └── Container                  вертикальный auto-layout — сюда переезжает набор
│   └── Vertical Props                 левый нижний: столбцы «Variable» с подписями
└── ds-format-component-footer         «Версия» + .ds-log-changelog-version

В демо Horizontal Props и Vertical Props заполнены подписями-примерами (Medium, Large, Fixed, Scroll…) — их скилл удаляет и строит свои.

---

3. Атомы, которые ставит скилл

Суффиксы свойств (#814:0) меняются при перепубликации — свойства резолвить по имени до # (рецепт 0), суффиксы ниже — для сверки.

ds-head — шапка страницы

Набор, ключ 287294fb2c2358cb427985c718ccea3a27dc04c6. Не трогать.

ds-log — запись истории изменений

Набор, ключ 00d9e32bc28904a27517489b84f9f281a39b2011.

Ловушка: имена Описание (BOOLEAN) и Описание (TEXT) отличаются только пробелом. Резолвер свойств обязан сравнивать имя точно и проверять тип (рецепт 0).

Вложенные атомы — приватные (имя с точкой), не опубликованы, по ключу не импортируются. Достаются только через родителя: log.findOne(n => n.type === "INSTANCE" && n.name === "<слой>").

Скилл трогает только Версия, Дата, Тип изменения и свойства самого ds-log.

ds-paragraph — заголовок и абзац

Набор, ключ ca2f04a5efaa20c9d9ae32a396330b7a13e696e9. Type: H1, H2, H3, H4. Свойства: Title#25618:5, Description#25618:0, Show Title#25618:15, Show Description#25618:10.

ds-paragraph-dev-mode — блок «Структура»

Компонент, ключ a9e5a749b4add3badd7752e7c068489722c5d2be. Свойств нет. Внутри ds-paragraph H1 с текстом «Структура» и «Для ознакомления структурой компонента используйте DevMode (Shift+D).» Текст не меняется.

ds-mcp-component — иллюстрация

Набор, ключ f9ee550e7ecc537fc63075015db4c76d0355a619.

ds-mcp-component-state — строка значения

Набор, ключ ddafef2738b4d3183aa5e0e418da8fa23ede1cf2.

ds-mcp-component-label — подпись оси

Набор, ключ 9d9fc72e383e614ac585a65acdeb7a621e094875. Label#29891:0 — TEXT; Large: False, True — внешний уровень крупнее; Vertical: False, True — скобка сверху или слева. Размеры по умолчанию: 120×48, 120×54, 66×57, 76×57.

Шапка и подвал сетки

Заглушка ds-slot

Набор, ключ 02c2a9c417f1a8e9e3edca6f2eb731a98f4cf4f5. Type: Hug, Filled; Size: Small, Medium, Large, Max. Демо-наполнение слотов. Скилл его не ставит, только убирает.

---

4. Атомы ручных страниц

Скилл их не ставит. Нужны, чтобы узнать страницы, которые дизайнер добавит сам.

---

5. Устаревшие атомы — не ставить

Ими собраны секции документации до шаблона ds-component: на 22.10.2026 — Tag, Popover, Locator и другие. Скилл их не использует, даже если пересобирает такую секцию.

Вне шаблона, статус не определён — скилл не ставит: ds-accessibility* (страница «Доступность»), ds-device, ds-token, ds-token–tag, ds-video, ds-gradient, ds-text-line, ds-menu-item, ds-notification-*, ds-interactive-touch*, ds-doc/interaction/*.

---

6. Задвоенные имена

На 22.10.2026 в «Astra DS: Docs» опубликованы под одним именем:

Поиск по имени выбирает случайный из них. Поэтому только ключи.

---

7. Оформление секции

Снято с секций Popover и Locator. Переменные — коллекция decoration библиотеки «Astra DS: Docs».

Переменные импортируются figma.variables.importVariableByKeyAsync(key). Если на странице уже есть секция документации — проще скопировать fills, strokes, strokeWeight, strokeAlign и привязки радиуса с неё: правки владельца переедут сами.

Раскладка: отступ 100 от края секции, страницы слева направо с шагом 100, верх — 100.

---

8. Шрифты и аннотации

Атомы набраны Inter: Regular, Medium, Semi Bold, Bold. Список не хардкодить — собирать с текстовых слоёв импортированных страниц (рецепт 2) и загружать в каждом вызове, который пишет.

Категории аннотаций в файле Astra DS: Спецификация (зелёная), Интерактивность, Доступность, Рекомендации, Контент, Закон, Примечание реализации, Stark. Скилл ставит Спецификация — annotations.md.

---

9. Как обновить карту

Библиотеку перепубликовали, и ключ не импортируется:

1. В файле с подключённой библиотекой — search_design_system по имени атома с includeLibraryKeys библиотеки «Astra DS: Docs» (ключ библиотеки даёт get_libraries).
2. Из найденных взять тот, что стоит в шаблоне ds-component: импортировать шаблон по ключу и прочитать mainComponent.key нужного инстанса внутри.
3. Обновить таблицу, дату снятия наверху и запись в CHANGELOG.md.