gennady 0.6.1 → 0.7.0

package/dist/ai/directives/coding/uikit-component-svelte.xml

@@ -0,0 +1,344 @@
+<!--
+@file: Svelte component conventions for uikit — data attributes, CSS tokens, file structure, a11y, token overrides.
+@consumers: SDD agents (implementation phase of uikit-component tasks)
+@tasks: TSK-26
+-->
+<UiKitComponentSvelte keywords="uikit, svelte-component, data-attributes, css-tokens, file-structure, a11y, token-overrides" type="coding-rules" ver="1.0">
+  <Directive_Context>
+    <Mission>
+      Canonical rules for implementing a uikit Svelte component. Every execution-agent MUST apply these conventions when creating or modifying a Svelte component for the uikit library. These rules are LAYERED ON TOP of `svelte5-runes.xml` — the base Svelte 5 rules are prerequisites; this directive adds uikit-specific structural, styling, and accessibility constraints derived from the first component (Button).
+
+      **Base axiom:** A uikit component is a closed-world artifact — four files in kebab-case, data-attribute selectors (never `:host()`), VKUI CSS custom properties inherited through `:root`, `data-state` for testable pseudo-states, and WAI-ARIA accessibility. Deviating from any of these breaks the automated verification pipeline (no `:host()` in headless Chromium, no pseudo-class triggers in programmatic tests).
+
+      You are NOT in charge of:
+      - Enforcing Svelte 5 runes syntax (delegated to `svelte5-runes.xml`);
+      - Storybook conventions (delegated to `uikit-component-storybook.xml`);
+      - Deriving the component spec (that is `uikit-spec` territory).
+    </Mission>
+  </Directive_Context>
+
+  <Depends_On>
+    - ai/directives/coding/svelte5-runes.xml
+    - ai/directives/coding/uikit-spec-drafting.xml
+  </Depends_On>
+
+  <Belief_State>
+    <Axiom id="AX_DATA_ATTRS_NOT_HOST">
+      CSS selectors use `data-*` attributes on an inner wrapper element, NOT `:host()` pseudo-class selectors. The outer host element is a simple `display: inline-block` container; all styling and testable selectors target the inner element.
+
+      Reasoning (D-UC01): `:host([attr="value"])` compound selectors fail in headless Chromium — `getComputedStyle` returns `0px` for padding. The inner-wrapper approach with `data-*` attributes is proven in the Button PoC and works consistently across all test environments.
+
+      Correct pattern:
+      ```css
+      .btn[data-mode="primary"] { ... }
+      .btn[data-appearance="accent"] { ... }
+      .btn[data-size="s"] { height: var(--vkui--size_button_small_height--compact); }
+      .btn[data-state="hover"] { /* hover styles */ }
+      ```
+
+      Forbidden: `:host([mode="primary"])`, `:host(.primary)`, any `:host()` usage.
+    </Axiom>
+
+    <Axiom id="AX_CSS_TOKENS_VIA_ROOT">
+      CSS custom properties (design tokens) are inherited through `:root` in `<name>.tokens.css`. Shadow DOM is NOT used for token inheritance — the component relies on the global CSS cascade.
+
+      The tokens file has two mandatory blocks:
+      1. `:root { ... }` — the token declarations block.
+      2. Override block — tokens where the SVG value differs from the VKUI default, each with a `/* override: was Xpx */` comment.
+
+      The CSS module (`<name>.module.css`) consumes these tokens via `var(--vkui--...)` functions. No hardcoded pixel values in `.module.css` — every dimension, color, and spacing comes from a token.
+
+      Counter element: `box-sizing: border-box` is mandatory (prevents overflow when the counter number grows).
+    </Axiom>
+
+    <Axiom id="AX_FILE_STRUCTURE_KEBAB_CASE">
+      Every uikit component consists of EXACTLY four files, all in kebab-case, all in a single directory `src/ui/<name>/`:
+
+      | File                     | Purpose                                        |
+      |--------------------------|------------------------------------------------|
+      | `<name>.svelte`           | Svelte component (data-attributes, a11y)       |
+      | `<name>.module.css`       | CSS module (data-attribute selectors)          |
+      | `<name>.tokens.css`       | `:root` + override tokens                      |
+      | `<name>.stories.ts`       | Storybook stories (mirror of spec)             |
+
+      No PascalCase (`Button.svelte`), no camelCase (`buttonModule.css`), no additional files (`button.utils.ts` belongs elsewhere or doesn't exist). The four-file set is the closed-world contract per `ComponentArtefact`.
+    </Axiom>
+
+    <Axiom id="AX_DATA_STATE_FOR_TESTABILITY">
+      Every interactive state that is normally expressed through a CSS pseudo-class (`:hover`, `:active`, `:disabled`) MUST also be expressed through a `data-state` attribute on the inner wrapper element. CSS pseudo-classes cannot be triggered programmatically in headless test environments — `data-state` provides the testable channel.
+
+      States: `normal`, `hover`, `active`, `disabled`. The `data-state` attribute is always present, never conditionally omitted. The component derives `data-state` from the `state` prop, not from browser events.
+
+      For test assertions: `expect(element).toHaveAttribute('data-state', 'hover')` — NOT `expect(element).toHaveStyle(...)` for pseudo-class-triggered styles (that won't work in headless).
+    </Axiom>
+
+    <Axiom id="AX_A11Y_REQUIREMENTS">
+      Every interactive uikit component MUST declare:
+      - `role` — WAI-ARIA role (button, checkbox, etc.).
+      - `aria-label` — computed from label + counter (when present).
+      - `aria-disabled` — bound to the disabled state.
+      - `tabindex` — `0` when interactive, `-1` when disabled.
+      - Keyboard support — Enter and Space for activation.
+
+      For Button specifically:
+      - `role="button"`
+      - `aria-label={label}` (plus counter if present: `` `${label} ${counter}` ``)
+      - `aria-disabled={disabled}`
+      - `aria-pressed={state === 'active'}` (optional, for toggle mode)
+      - `tabindex={disabled ? -1 : 0}`
+
+      Focus styles use `:focus-visible` with appearance-dependent styling. No custom focus ring that overrides the browser default without providing equivalent visual feedback.
+    </Axiom>
+
+    <Axiom id="AX_ICON_SVG_TIGHT_VIEWBOX">
+      SVG icons have their viewBox cropped to the tight bounding box of the path — NOT the 20×20 Figma container. This prevents unwanted whitespace around icons and ensures consistent spacing within the button.
+
+      The icon SVG is inlined (not an `<img>` tag) so its fill color can be controlled via CSS. Icon fill inherits from the button's current appearance/mode color.
+    </Axiom>
+
+    <Axiom id="AX_TOKEN_OVERRIDE_COMMENT">
+      Every token override (where `diff > 1px` between SVG measurement and VKUI default) MUST carry a comment in `.tokens.css`:
+
+      ```css
+      /* override: was 8px */
+      --vkui--size_button_tertiary_small_padding_horizontal_icon--regular: 14px;
+      ```
+
+      The comment format is: `/* override: was <original-value> */`. This preserves the audit trail — an operator or SpecValidator can verify that the override was intentional and trace it back to the Token Mapping table in the spec.
+    </Axiom>
+
+    <Axiom id="AX_COMPONENT_PROPS_CONTRACT">
+      A uikit component receives its variant configuration through Svelte 5 `$props()` destructuring. The prop surface matches the spec's Variants table columns:
+
+      ```typescript
+      let {
+          appearance = 'accent',
+          mode = 'primary',
+          size = 's',
+          state = 'normal',
+          icon = false,
+          label = '',
+          counter = undefined,
+          indicator = false,
+          disabled = false,
+      }: Props = $props();
+      ```
+
+      The `disabled` prop takes precedence over `state` — when `disabled={true}`, `data-state` is `disabled` regardless of the `state` prop value. The component derives `aria-disabled` and `tabindex` from `disabled`.
+    </Axiom>
+
+    <Axiom id="AX_CSS_MODULE_SELECTOR_CONVENTIONS">
+      CSS module selectors follow the data-attribute pattern consistently:
+      - `.btn[data-size="s"]` for size-dependent styles.
+      - `.btn[data-mode="primary"][data-appearance="accent"]` for mode × appearance combinations.
+      - `.btn[data-state="hover"]` for state-dependent styles.
+      - Child elements use class selectors: `.icon`, `.label`, `.counter`, `.indicator`.
+
+      No ID selectors, no tag selectors (except `:root` in tokens), no descendant selectors deeper than 2 levels. Every selector is scoped to the component's root class (`.btn`).
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_COMPONENT_ARTEFACT">
+      The closed-world set of four files that constitute one uikit component: `<name>.svelte`, `<name>.module.css`, `<name>.tokens.css`, `<name>.stories.ts`. All in `src/ui/<name>/`, all in kebab-case.
+    </Definition>
+    <Definition id="DEF_DATA_ATTRIBUTE_SELECTOR">
+      A CSS selector that targets a `data-*` HTML attribute on the component's inner wrapper: `.btn[data-mode="primary"]`. Preferred over class-based selectors because `data-*` attributes are machine-verifiable in tests via `toHaveAttribute`.
+    </Definition>
+    <Definition id="DEF_TOKEN_OVERRIDE">
+      A CSS custom property declaration in `.tokens.css` whose value differs from the VKUI default. Must carry a `/* override: was ... */` comment. Originates from the Token Mapping table in the component's `.ui.spec.md`.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_COMPONENT_SVELTE_TEMPLATE">
+      <Intent>Canonical structure of a uikit Svelte component file.</Intent>
+      <Snippet language="svelte">
+        ```svelte
+        <!-- @file: Button component — uikit conventions: data-attributes, a11y, CSS tokens. -->
+        <script lang="ts">
+          let {
+              appearance = 'accent',
+              mode = 'primary',
+              size = 's',
+              state = 'normal',
+              icon = false,
+              label = '',
+              counter = undefined,
+              indicator = false,
+              disabled = false,
+          }: Props = $props();
+
+          let resolvedState = $derived(disabled ? 'disabled' : state);
+        </script>
+
+        <div
+          class="btn"
+          data-appearance={appearance}
+          data-mode={mode}
+          data-size={size}
+          data-state={resolvedState}
+          role="button"
+          aria-label={label}
+          aria-disabled={disabled}
+          tabindex={disabled ? -1 : 0}
+        >
+          {#if icon}
+            <span class="icon">
+              <!-- Inlined SVG with tight viewBox -->
+            </span>
+          {/if}
+          {#if label}
+            <span class="label">{label}</span>
+          {/if}
+          {#if counter !== undefined}
+            <span class="counter">{counter}</span>
+          {/if}
+          {#if indicator}
+            <span class="indicator">
+              <!-- Chevron SVG -->
+            </span>
+          {/if}
+        </div>
+        ```
+      </Snippet>
+      <Why>Single `$props()` destructure with all variant props; `$derived` resolves state vs disabled; inner wrapper carries all data-attributes and ARIA; child elements conditionally rendered; no `:host()`, no `<slot>`, no legacy patterns.</Why>
+    </Pattern>
+
+    <Pattern id="PT_TOKENS_CSS_TEMPLATE">
+      <Intent>Canonical structure of a uikit `.tokens.css` file.</Intent>
+      <Snippet language="css">
+        ```css
+        :root {
+          --vkui--size_button_small_height--compact: 28px;
+          --vkui--size_button_base_small_padding_horizontal_icon--regular: 14px;
+          /* override: was 8px */
+          --vkui--size_button_tertiary_small_padding_horizontal_icon--regular: 14px;
+          /* override: was rgba(0,0,0,0.12) */
+          --vkui--color_background_tertiary_alpha--active: rgba(0, 16, 61, 0.14);
+        }
+        ```
+      </Snippet>
+      <Why>Single `:root` block with all token declarations; override tokens carry `/* override: was ... */` comments; token names match the VKUI naming convention; no shadow DOM, no `@import`, no extra blocks.</Why>
+    </Pattern>
+
+    <Pattern id="PT_MODULE_CSS_TEMPLATE">
+      <Intent>Canonical structure of a uikit `.module.css` file.</Intent>
+      <Snippet language="css">
+        ```css
+        .btn[data-size='s'] {
+          height: var(--vkui--size_button_small_height--compact);
+        }
+
+        .btn[data-mode='primary'][data-appearance='accent'] {
+          background: var(--vkui--color_background_accent);
+        }
+
+        .btn[data-state='hover'] {
+          /* hover styles via data-state, not :hover pseudo-class */
+        }
+
+        .counter {
+          width: 18px;
+          height: 18px;
+          box-sizing: border-box;
+        }
+        ```
+      </Snippet>
+      <Why>Data-attribute selectors for variant-dependent styles; CSS custom properties for all values; `box-sizing: border-box` on counter; no `:host()`, no hardcoded values, no deep nesting.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_HOST_SELECTOR">
+      <Bad>`.module.css` containing `:host([mode="primary"]) { background: blue; }`.</Bad>
+      <Why_Bad>`:host()` compound selectors fail in headless Chromium (`AX_DATA_ATTRS_NOT_HOST`). Padding returns `0px` from `getComputedStyle`, breaking visual tests. The inner-wrapper approach is the proven alternative.</Why_Bad>
+      <Good>Inner wrapper with data-attribute: `.btn[data-mode="primary"] { background: var(--vkui--color_background_accent); }`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_MISSING_DATA_STATE">
+      <Bad>Component relies on CSS `:hover` pseudo-class for hover styling, with no `data-state` attribute.</Bad>
+      <Why_Bad>Headless test environments cannot trigger `:hover` programmatically (`AX_DATA_STATE_FOR_TESTABILITY`). The hover variant is untestable — visual regression tests pass trivially without actually verifying hover appearance.</Why_Bad>
+      <Good>Add `data-state={resolvedState}` attribute and use `.btn[data-state="hover"]` selectors. Tests assert `toHaveAttribute('data-state', 'hover')`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_HARDCODED_PIXELS">
+      <Bad>`.module.css` with `height: 28px;` instead of `var(--vkui--size_button_small_height--compact)`.</Bad>
+      <Why_Bad>Token not consumed via custom property (`AX_CSS_TOKENS_VIA_ROOT`). The value cannot be overridden, themed, or traced back to the VKUI token system. When the design system updates the token, this component silently stays at the old value.</Why_Bad>
+      <Good>`height: var(--vkui--size_button_small_height--compact);` — the token from `.tokens.css` flows through.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_PASCAL_CASE_FILENAME">
+      <Bad>Component file named `Button.svelte` or `Button.module.css`.</Bad>
+      <Why_Bad>Violates kebab-case convention (`AX_FILE_STRUCTURE_KEBAB_CASE`, D-UC03). Inconsistent with existing project files (`app.svelte`, `app.stories.ts`). Breaks the closed-world `ComponentArtefact` contract.</Why_Bad>
+      <Good>`button.svelte`, `button.module.css`, `button.tokens.css`, `button.stories.ts`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_MISSING_ARIA">
+      <Bad>Button component with `<div class="btn" onclick={handler}>` and no ARIA attributes.</Bad>
+      <Why_Bad>A11y contract not fulfilled (`AX_A11Y_REQUIREMENTS`). Screen readers cannot identify the element as a button, cannot announce its label, cannot report its disabled state. Keyboard users cannot focus or activate it.</Why_Bad>
+      <Good>`<div class="btn" role="button" aria-label={label} aria-disabled={disabled} tabindex={disabled ? -1 : 0}>`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_OVERRIDE_WITHOUT_COMMENT">
+      <Bad>`.tokens.css` with `--vkui--size_button_tertiary_small_padding_horizontal_icon--regular: 14px;` and no override comment.</Bad>
+      <Why_Bad>Override without audit trail (`AX_TOKEN_OVERRIDE_COMMENT`). Cannot distinguish intentional override from accidental drift. SpecValidator cannot trace the value back to the Token Mapping table.</Why_Bad>
+      <Good>`/* override: was 8px */` on the line above the declaration.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_IMG_TAG_ICON">
+      <Bad>Icon rendered as `<img src="icon.svg" alt="" />`.</Bad>
+      <Why_Bad>Icon fill cannot be controlled via CSS when using `<img>` (`AX_ICON_SVG_TIGHT_VIEWBOX`). Each appearance/mode combination would need a separate SVG file with hardcoded fill. Inlined SVG with `fill: currentColor` or CSS variable solves this.</Why_Bad>
+      <Good>Inline the SVG with tight viewBox; control fill via CSS on the `.icon` container or the SVG paths directly.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_NO_HOST_SELECTOR">
+      <Purpose>Detect forbidden `:host()` pseudo-class usage in component CSS.</Purpose>
+      <Command>find . -name '*.module.css' -not -path '*/node_modules/*' -print0 | xargs -0 grep -n ':host' || true</Command>
+      <Expected>Empty output. Any match is a violation of `AX_DATA_ATTRS_NOT_HOST`.</Expected>
+    </Hook>
+    <Hook id="HOOK_DATA_STATE_PRESENT">
+      <Purpose>Verify every uikit component exposes `data-state` attribute.</Purpose>
+      <Command>find src/ui -name '*.svelte' -not -path '*/node_modules/*' -print0 | xargs -0 grep -l 'data-state=' || echo MISSING</Command>
+      <Expected>Every `.svelte` file in `src/ui/` must appear in output. `MISSING` means at least one component lacks `data-state`.</Expected>
+    </Hook>
+    <Hook id="HOOK_ARIA_ATTRIBUTES_PRESENT">
+      <Purpose>Verify every uikit component has ARIA role and label.</Purpose>
+      <Command>find src/ui -name '*.svelte' -not -path '*/node_modules/*' -print0 | xargs -0 grep -lE 'role="button"|role="checkbox"|role="radio"' || echo MISSING</Command>
+      <Expected>Every `.svelte` file must appear. `MISSING` means a component lacks ARIA role.</Expected>
+    </Hook>
+    <Hook id="HOOK_KEBAB_CASE_FILES">
+      <Purpose>Verify all component files are in kebab-case.</Purpose>
+      <Command>find src/ui -type f \( -name '*.svelte' -o -name '*.module.css' -o -name '*.tokens.css' -o -name '*.stories.ts' \) -not -path '*/node_modules/*' | while read f; do basename "$f"; done | grep -E '[A-Z]' || true</Command>
+      <Expected>Empty output. Any match is a PascalCase/camelCase filename violation.</Expected>
+    </Hook>
+    <Hook id="HOOK_OVERRIDE_COMMENTS_PRESENT">
+      <Purpose>Verify every override token has its audit comment.</Purpose>
+      <Command>find src/ui -name '*.tokens.css' -not -path '*/node_modules/*' -print0 | xargs -0 grep -c 'override: was' || true</Command>
+      <Expected>Count should match the number of OVERRIDE rows in the component's Token Mapping table. Zero when the spec has zero overrides; positive otherwise.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ Component uses `data-*` attribute selectors on inner wrapper; no `:host()` anywhere.
+    ✅ CSS custom properties inherited through `:root` in `.tokens.css`; consumed via `var()` in `.module.css`.
+    ✅ Four files per component, all kebab-case: `<name>.svelte`, `<name>.module.css`, `<name>.tokens.css`, `<name>.stories.ts`.
+    ✅ `data-state` attribute present and used in CSS selectors for all interactive states.
+    ✅ ARIA role, label, disabled, and tabindex correctly wired.
+    ✅ SVG icons inlined with tight viewBox; fill controlled via CSS.
+    ✅ Override tokens carry `/* override: was ... */` comment.
+    ✅ Props match the spec's Variants table; `disabled` takes precedence over `state`.
+    ✅ Counter element has `box-sizing: border-box`.
+
+    ❌ `:host()` selector in any CSS file.
+    ❌ Hardcoded pixel/color values in `.module.css` (must use `var()`).
+    ❌ PascalCase or camelCase component filenames.
+    ❌ Missing `data-state` attribute.
+    ❌ Missing ARIA role or label on interactive component.
+    ❌ Override token without audit comment.
+    ❌ Icon as `<img>` tag (not inlined SVG).
+    ❌ `disabled` and `state` props conflicting without clear precedence.
+  </Reward_Criteria>
+</UiKitComponentSvelte>

package/dist/ai/directives/coding/uikit-spec-drafting.xml

@@ -0,0 +1,243 @@
+<!--
+@file: Drafting rules for converting ExtractionResult JSON to a draft .ui.spec.md UI component spec.
+@consumers: SDD agents (drafting phase of uikit-component tasks)
+@tasks: TSK-25
+-->
+<UiKitSpecDrafting keywords="uikit, spec-drafting, extraction-result, ui-spec, token-mapping, variant-grouping, bdd-generation, a11y-defaults" type="drafting-rules" ver="1.0">
+  <Directive_Context>
+    <Mission>
+      Convert an ExtractionResult — the JSON output of `figma-utils extract &lt;component&gt;` — 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).
+    </Mission>
+  </Directive_Context>
+
+  <Belief_State>
+    <Axiom id="AX_EXTRACTION_INPUT">
+      The input is an `ExtractionResult` object with shape:
+      ```json
+      {
+        "component": "button",
+        "svg": "<path-to-svg>",
+        "variants": [ /* SvgVariant[] */ ],
+        "elements": [ "icon", "label", "counter", "indicator" ],
+        "tokenOverrides": [ /* TokenCandidate[] where match=false */ ]
+      }
+      ```
+      Every `SvgVariant` carries: `id`, `size`, `appearance`, `mode`, `state`, and `measurements` (MeasurementSet with height, width, leftPad, rightPad, borderRadius, rectFill, elements).
+      Every `TokenCandidate` carries: `metric`, `svgValue`, `token`, `tokenValue`, `diff`, `match`.
+    </Axiom>
+
+    <Axiom id="AX_VARIANT_GROUPING">
+      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.
+    </Axiom>
+
+    <Axiom id="AX_TOKEN_SECTION_GENERATION">
+      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: &lt;svgValue&gt;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.
+    </Axiom>
+
+    <Axiom id="AX_BDD_GENERATION">
+      BDD scenarios are generated for each `(appearance, mode, state)` combination.
+
+      Procedure:
+      1. For each group from variant grouping: heading `### &lt;Appearance&gt; / &lt;Mode&gt;`.
+      2. For each state (normal, hover, active, disabled): sub-heading `#### &lt;State&gt;`.
+      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 = &lt;rectFill&gt;` (hex color from the variant's background rect)
+           - `text = &lt;label fill&gt;` (if label element exists)
+           - `height = &lt;height&gt;px`, `borderRadius = &lt;borderRadius&gt;px`
+           - For hover/active states: background color from the corresponding variant
+           - For disabled: `opacity = &lt;rectOpacity&gt;`
+
+      Minimum coverage: one scenario per state per (appearance, mode) group. All scenarios must reference real measurement data from the extraction.
+    </Axiom>
+
+    <Axiom id="AX_A11Y_DEFAULTS">
+      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.
+    </Axiom>
+
+    <Axiom id="AX_ELEMENT_STRUCTURE_FROM_EXTRACTION">
+      The Element Structure section is derived from `ExtractionResult.elements` — the list of element names discovered in the SVG.
+
+      Procedure:
+      1. Map each element name to a semantic description:
+         - `icon` → "SVG-иконка (обрезанный viewBox до tight path bounds)"
+         - `label` → "текстовая метка"
+         - `counter` → "числовой счётчик (box-sizing: border-box)"
+         - `indicator` → "шеврон (стрелка вправо)"
+      2. For unknown element names: infer from context, mark with `⚠️ requires clarification`.
+      3. Order elements: icon, label, counter, indicator (visual left-to-right).
+    </Axiom>
+
+    <Axiom id="AX_NO_DATA_LOSS">
+      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.
+    </Axiom>
+
+    <Axiom id="AX_DRAFT_READY_FOR_REVIEW">
+      The output is a DRAFT — marked with a header comment:
+      ```markdown
+      &lt;!-- DRAFT: generated from figma-utils extract. Review and finalise before scaffold. --&gt;
+      ```
+      This signals to the operator that the spec is machine-generated and requires human approval.
+    </Axiom>
+  </Belief_State>
+
+  <Drafting_Procedure>
+    <Step id="STEP_1_LOAD_EXTRACTION">
+      <Goal>Receive and validate the ExtractionResult.</Goal>
+      <Action>
+        1. Confirm `ExtractionResult.variants` is non-empty.
+        2. Confirm `ExtractionResult.elements` is non-empty.
+        3. If either is empty → abort with diagnostic: «ExtractionResult пуст — запустите figma:extract &lt;component&gt; сначала».
+      </Action>
+    </Step>
+
+    <Step id="STEP_2_BUILD_VISION">
+      <Goal>Write the Vision section.</Goal>
+      <Action>
+        Format: `&lt;ComponentName&gt; — &lt;brief description&gt;. &lt;count&gt; size × &lt;appearances&gt; × &lt;states&gt;.`
+
+        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 `/`
+      </Action>
+    </Step>
+
+    <Step id="STEP_3_BUILD_VARIANTS">
+      <Goal>Build the closed-world Variants table.</Goal>
+      <Action>
+        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 `⚠️`.
+      </Action>
+    </Step>
+
+    <Step id="STEP_4_BUILD_TOKEN_MAPPING">
+      <Goal>Build the Token Mapping table.</Goal>
+      <Action>
+        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`.
+      </Action>
+    </Step>
+
+    <Step id="STEP_5_BUILD_ELEMENT_STRUCTURE">
+      <Goal>Build the Element Structure section.</Goal>
+      <Action>
+        Per `AX_ELEMENT_STRUCTURE_FROM_EXTRACTION`: map element names to semantic descriptions.
+      </Action>
+    </Step>
+
+    <Step id="STEP_6_BUILD_A11Y">
+      <Goal>Build the A11y Requirements section.</Goal>
+      <Action>
+        Per `AX_A11Y_DEFAULTS`: apply the template for the component type.
+      </Action>
+    </Step>
+
+    <Step id="STEP_7_BUILD_BDD">
+      <Goal>Build BDD scenarios for every state.</Goal>
+      <Action>
+        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`.
+      </Action>
+    </Step>
+
+    <Step id="STEP_8_EMIT_DRAFT">
+      <Goal>Write the draft file.</Goal>
+      <Action>
+        1. Prepend draft header: `&lt;!-- DRAFT: generated from figma-utils extract. Review and finalise before scaffold. --&gt;`.
+        2. Write all 6 sections in order: Vision, Variants, Token Mapping, Element Structure, A11y Requirements, BDD Scenarios.
+        3. Save as `specs/uikit/components/&lt;component&gt;.ui.spec.md`.
+      </Action>
+    </Step>
+  </Drafting_Procedure>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_DROPPED_VARIANTS">
+      <Bad>Пропуск строки в таблице Variants, потому что «этот вариант не в extraction».</Bad>
+      <Why_Bad>Closed-world нарушен. Последующий SpecValidator не сможет отличить «пропущен осознанно» от «забыли».</Why_Bad>
+      <Good>Строка присутствует, но состояния помечены `⚠️ not in extraction`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SILENT_MISSING_TOKEN">
+      <Bad>Пропуск строки в Token Mapping, когда токен не найден.</Bad>
+      <Why_Bad>Измерение теряется. SpecValidator не может проверить, что все измерения покрыты.</Why_Bad>
+      <Good>Строка с `⚠️ no token` в колонке Token и `Action = ⚠️`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_DUPLICATE_BDD_GROUP">
+      <Bad>Один BDD-заголовок на несколько размеров: `### Primary / Accent (все размеры)`.</Bad>
+      <Why_Bad>Разные размеры имеют разные ожидаемые значения (height, pads). Сгруппированные BDD нельзя верифицировать.</Why_Bad>
+      <Good>Отдельный BDD-заголовок на каждый (appearance, mode), внутри указывается representative size и конкретные значения.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_FABRICATED_MEASUREMENTS">
+      <Bad>BDD-сценарий с выдуманными значениями: `background = #0077FF`, когда в extraction нет такого цвета.</Bad>
+      <Why_Bad>SpecValidator обнаружит расхождение. Фабрикация данных подрывает доверие к спекам.</Why_Bad>
+      <Good>Все Then-значения берутся из `MeasurementSet` соответствующего варианта: `rectFill`, `height`, `borderRadius`, etc.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Reward_Criteria>
+    ✅ 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`.
+  </Reward_Criteria>
+</UiKitSpecDrafting>