Convert an ExtractionResult — the JSON output of `figma-utils extract <component>` — into a draft `.ui.spec.md` (per `spec-format.md`). The draft is a starting point for operator refinement; it must preserve ALL data from the extraction (all variants, all token candidates, all elements) without loss.
The format of the output spec is defined in `specs/uikit/spec-format.md`. This directive governs the TRANSFORMATION logic: how to group variants, populate token mappings, generate BDD, and apply a11y defaults.
You are NOT in charge of:
- Running `figma-utils extract` (that is a prior step, TSK-24);
- Validating the draft (SpecValidator is a separate check);
- Finalising the spec (operator approves after review).
Variants are grouped hierarchically: `size → appearance → mode`. Each leaf group contains all 4 states (normal, hover, active, disabled). The result is a closed-world table — every combination is listed explicitly, no «и т.д.» allowed.
Procedure:
1. Collect all unique triples `(size, appearance, mode)` from `ExtractionResult.variants`.
2. Sort: size (s, m, l) → appearance (accent, neutral, contrary) → mode (primary, secondary, tertiary, outline).
3. For each triple, list states: `normal, hover, active, disabled`.
4. If a state is missing from the extraction data, mark it as `⚠️ not in extraction` — do NOT omit the row.
The Token Mapping section populates measurements from `ExtractionResult.variants[].measurements` and maps them to VKUI tokens from `TokenCandidate[]`.
Procedure:
1. Collect all unique `(element, metric)` pairs across all variants. The `element` prefix is derived from `MeasurementSet` fields: `icon-padding-left` (from leftPad of icon element), `height`, `border-radius`, etc.
2. For each pair, find the corresponding `TokenCandidate` where exists. If not found → mark as `⚠️ no token`.
3. Compute `diff = |svgValue - tokenValue|`.
4. If `diff ≤ 1` → Action = `OK`. If `diff > 1` → Action = `OVERRIDE: <svgValue>px`.
5. Sort rows: element name alphabetically.
Note: `ExtractionResult.tokenOverrides` contains only candidates where `match: false`. For the full Token Mapping table, you need ALL measurements — both matched and unmatched. If `tokenOverrides` is the only source, the table will be incomplete. Prefer deriving measurements from `variants[].measurements` and cross-referencing with token mappings.
BDD scenarios are generated for each `(appearance, mode, state)` combination.
Procedure:
1. For each group from variant grouping: heading `### <Appearance> / <Mode>`.
2. For each state (normal, hover, active, disabled): sub-heading `#### <State>`.
3. Write Given/When/Then:
- **Given:** component with `appearance=...`, `mode=...`, `state=...`, `size=...` (pick representative size, note size parameter)
- **When:** rendered
- **Then:** visual expectations derived from `Measurements` of the corresponding variant:
- `background = <rectFill>` (hex color from the variant's background rect)
- `text = <label fill>` (if label element exists)
- `height = <height>px`, `borderRadius = <borderRadius>px`
- For hover/active states: background color from the corresponding variant
- For disabled: `opacity = <rectOpacity>`
Minimum coverage: one scenario per state per (appearance, mode) group. All scenarios must reference real measurement data from the extraction.
Default a11y requirements for common component types. Apply the template matching the component type.
For **button:**
- **Role:** button
- **aria-label:** формируется из label + counter (если есть)
- **aria-disabled:** при state=disabled
- **Keyboard:** Enter, Space активируют кнопку
For **other interactive components** (checkbox, radio, link, input): infer role from component name and visual structure; apply standard WAI-ARIA patterns.
The draft MUST preserve ALL data from `ExtractionResult`:
- All `variants[]` are reflected in the Variants table.
- All unique `(element, metric)` pairs from all `Measurements` are reflected in Token Mapping.
- All `elements[]` are listed in Element Structure.
- Every state for every (size, appearance, mode) combination has a BDD scenario.
Missing data (state not in extraction, token not found) → mark explicitly with `⚠️`, never silently omit.
The output is a DRAFT — marked with a header comment:
```markdown
<!-- DRAFT: generated from figma-utils extract. Review and finalise before scaffold. -->
```
This signals to the operator that the spec is machine-generated and requires human approval.
Write the Vision section.
Format: `<ComponentName> — <brief description>. <count> size × <appearances> × <states>.`
Example: `Кнопка с иконкой — Primary CTA. 3 size × accent/neutral/contrary × normal/hover/active/disabled.`
Derive:
- `count` = number of unique sizes
- `appearances` = unique appearance values, joined by `/`
- `states` = unique state values, joined by `/`
Build the closed-world Variants table.
Per `AX_VARIANT_GROUPING`:
1. Group variants by `(size, appearance, mode)`.
2. Sort hierarchically.
3. For each group, list states as comma-separated.
4. Flag missing states with `⚠️`.
Build the Token Mapping table.
Per `AX_TOKEN_SECTION_GENERATION`:
1. Extract all unique `(element, metric, svgValue)` from all variants.
2. Cross-reference with token candidates.
3. Compute diff and action.
4. Flag missing tokens with `⚠️ no token`.
Build the Element Structure section.
Per `AX_ELEMENT_STRUCTURE_FROM_EXTRACTION`: map element names to semantic descriptions.
Build the A11y Requirements section.
Per `AX_A11Y_DEFAULTS`: apply the template for the component type.
Build BDD scenarios for every state.
Per `AX_BDD_GENERATION`:
1. For each (appearance, mode) group, write a heading.
2. For each state, write a sub-heading and Given/When/Then.
3. Derive expected values from the variant's `Measurements`.
Write the draft file.
1. Prepend draft header: `<!-- DRAFT: generated from figma-utils extract. Review and finalise before scaffold. -->`.
2. Write all 6 sections in order: Vision, Variants, Token Mapping, Element Structure, A11y Requirements, BDD Scenarios.
3. Save as `specs/uikit/components/<component>.ui.spec.md`.
Пропуск строки в таблице Variants, потому что «этот вариант не в extraction».
Closed-world нарушен. Последующий SpecValidator не сможет отличить «пропущен осознанно» от «забыли».
Строка присутствует, но состояния помечены `⚠️ not in extraction`.
Пропуск строки в Token Mapping, когда токен не найден.
Измерение теряется. SpecValidator не может проверить, что все измерения покрыты.
Строка с `⚠️ no token` в колонке Token и `Action = ⚠️`.
Один BDD-заголовок на несколько размеров: `### Primary / Accent (все размеры)`.
Разные размеры имеют разные ожидаемые значения (height, pads). Сгруппированные BDD нельзя верифицировать.
Отдельный BDD-заголовок на каждый (appearance, mode), внутри указывается representative size и конкретные значения.
BDD-сценарий с выдуманными значениями: `background = #0077FF`, когда в extraction нет такого цвета.
SpecValidator обнаружит расхождение. Фабрикация данных подрывает доверие к спекам.
Все Then-значения берутся из `MeasurementSet` соответствующего варианта: `rectFill`, `height`, `borderRadius`, etc.
✅ Draft содержит все 6 обязательных секций (Vision, Variants, Token Mapping, Element Structure, A11y, BDD).
✅ Variants — closed-world таблица, все комбинации size × appearance × mode перечислены.
✅ Token Mapping — каждая строка имеет валидный VKUI токен или явную пометку `⚠️ no token`.
✅ Element Structure — все элементы из `ExtractionResult.elements` перечислены с семантическим описанием.
✅ A11y — role, aria-атрибуты, keyboard navigation для типа компонента.
✅ BDD — минимум один сценарий на каждое состояние, все значения из реальных измерений.
✅ Нет потери данных: все variants[], все метрики, все элементы отражены в спеке.
❌ Пропущена строка в Variants (нарушение closed-world).
❌ Пропущено измерение в Token Mapping.
❌ BDD без реальных данных (фабрикация).
❌ Отсутствует a11y-секция.
❌ Draft без пометки `DRAFT`.