Разведка перед контрактом (references/discovery.md)

Источник: ds-docs/component-contracts/skills/astra-component-contract/references/discovery.md — справочник скилла astra-component-contract

Что прочитать из Figma до того, как писать YAML. Список собран по трём компонентам — Button, Tag и Navigation Bar — и закрывает те места, где прогон обратного хода спотыкался.

Порядок важен: каждый следующий шаг опирается на предыдущий. Всё read-only, ничего не пишем.

1. Что за узел по ссылке

Ссылка из шапки карточки ведёт либо на секцию документации, либо сразу на набор. Найти все COMPONENT_SET в объемлющей секции: их может быть больше одного.

Один набор — обычный компонент (Button, Tag).
Много наборов с общим именем через слеш — семейство (Navigation Bar). Хвосты имени становятся осями in: name, см. формат.
У семейства сразу прикинуть число форм: сколько среди наборов структурно разных деревьев. Это определяет, лежит anatomy в корне или внутри forms.
Одиночные COMPONENT вне наборов — тоже часть раздела; у них своя карточка или своя строка в gaps.

2. Оси, свойства, умолчания

Из componentPropertyDefinitions набора:


`VARIANT`	`axes` с `in: variant`
`BOOLEAN`, `TEXT`, `INSTANCE_SWAP`	`props` с типами `boolean`, `text`, `instance`

Читать с набора, не с мастера: у варианта этот геттер бросает ошибку. Имена и значения переносить как есть, включая опечатки (Extral Small); опечатка идёт в gaps, а не правится.

defaultVariant набора — это masters.default. Он не обязан совпадать с первым ребёнком: у Button первый ребёнок и мастер по умолчанию разные.

3. Имена всех мастеров

Из них выводятся masters.count, counts по каждой оси и rules. Правила подбираются так, чтобы решётка давала ровно count; расхождение — знак, что правило неполное. Гадать нельзя: --grid сверит.

У семейства то же самое делается дважды — по наборам и по мастерам внутри набора.

4. Деревья

Не больше 6–8 мастеров за вызов: ответ обрезается на 20 КБ. Брать базовый мастер и по одному на каждое значение каждой оси. Для семейства — по одному мастеру на набор.

У семейства читать деревья диффом — фрагмент 5 в figma-read.js: одно дерево целиком, остальные отличиями. Так форма из трёх наборов помещается в один вызов. Без трёх приёмов дифф бесполезен: нормализовать путь там, где исчезает обёртка (иначе каждый веб-мастер выглядит полной заменой дерева), сравнивать размеры только у FIXED-узлов (у HUG и FILL они следствие), не раскрывать инстансы.

С каждого узла снимать: раскладку с привязками переменных, размеры и ограничения, обрезку, скругление, заливку и обводку, текст со стилем и привязками, ссылки на свойства (componentPropertyReferences), а для инстансов — главный компонент, свойства, переопределённые поля и проброс.

Готовые фрагменты — в scripts/figma-read.js.

5. Проброшенные инстансы

isExposedInstance у каждого прямого инстанса. Это публичный API компонента: проброшенные свойства видны в панели у того, кто вставил компонент. Пропускать нельзя — контракт требует exposed у каждого инстанса.

Проверить, что именно всплывает наружу, можно так: создать инстанс компонента, прочитать exposedInstances и их componentProperties, удалить инстанс. У Navigation Bar таких свойств одиннадцать сверх двенадцати своих.

Правило чтения: проброшено обычно то, что потребитель настраивает (кнопки, значки, отклик); не проброшено — то, что является состоянием компонента (индикатор загрузки, скелетон, системный статус-бар). Отклонение от этого правила — находка.

6. Окружение файла

Эти данные принадлежат файлу, а не компоненту, и в контракт не входят: они нужны рендеру и складываются в ENV.


id дочерних наборов по `of`	рендер создаёт инстансы	из `instanceOf.setId` при чтении деревьев
умолчания свойств подмены	`INSTANCE_SWAP` требует id компонента	`componentPropertyDefinitions` набора
точные id переменных-дублей	в файле по две `font-size-m`, `font-family` и т. д.	список локальных переменных, сгруппировать по имени-листу
начертания шрифта	текст не создать без загруженного шрифта	`listAvailableFontsAsync`
текстовые стили	`text.style` и `overrides.textStyle`	`getLocalTextStylesAsync`
auto-layout и ширина набора	без них мастера не могут быть `FILL`	`layoutMode` и `width` самого `COMPONENT_SET`

Последняя строка — не про оформление. У Navigation Bar набор вертикальный auto-layout шириной 375, и только поэтому его мастера растягиваются. Пока это не воспроизведено, любая ширина внутри поедет каскадом.

7. Чего в контракте не будет

Проверить, что эти вещи опознаны и, если нужно, записаны в gaps:

слои, которые ничего не рисуют (виброотклик) — идут в interaction, не в дерево;
значения, привязанные к удалённым переменным: по id читаются, в списке локальных их нет;
оси, которые ничего не меняют: сверить диффом все поля, а не глазами. У Button State меняет всё, у Navigation Bar та же по смыслу ось не меняет ничего в наборах с фоном;
размеры, которые являются следствием (hug от содержимого), а не решением.