docs(a4): add A4 design-tooling integration plan

The 8-task plan executed for the A4 epic, with the post-flight Plan Correction block (FM2 defer, #44-46 numbering, ADR-006, knowledge-work-plugins marketplace, /plugin unavailable in VSCode-extension env). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 14:07:26 +03:00
parent bcce4d9986
commit 1313d89525
1 changed files with 509 additions and 0 deletions
@@ -0,0 +1,509 @@
+# A4 Design Tooling Integration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the gaps in the `A4 «Дизайн (UI/UX, графика, бренд)»` map section by adding three tools to the current three (FD #30 / UPM #31 / 21st #32) — #41 **Figma MCP** (design source + brand tokens), #42 **Universal Icons MCP** (graphics / icons), #43 **Design plugin** (design review / a11y critique / UX writing) — so A4 grows from 3 → 6 nodes with full UI/UX + графика + бренд coverage.
+
+**Architecture:** Three tools, three install modes. **Design plugin** = Anthropic-Verified marketplace plugin (review-side, like FD — no code-gen). **Universal Icons MCP** = stdio npm MCP server, MIT, framework-neutral SVG. **Figma MCP** = official remote MCP server (`https://mcp.figma.com/mcp`), used in **extract-only** role. The two pre-identified overlaps (Figma MCP code-gen ↔ FD solver; Design plugin a11y/review ↔ FD/Pa11y/R5) are closed by **ADR-004** boundary decisions + PSR_v1 rows — not left implicit.
+
+**Tech Stack:** Figma MCP (official, remote HTTP transport, OAuth); `mcp-universal-icons` (npm, MIT, stdio); Design plugin (`anthropics/claude-plugins-official` marketplace, Anthropic Verified); adr-kit v0.13.1 (already installed #36 — used to author ADR-004); project normative docs; `docs/automation-graph.html` (vis.js).
+
+---
+
+## Plan Correction (2026-05-17, after Task 1 pre-flight)
+
+Facts verified on branch `feat/a4-design-tooling` (from `origin/main` `9b63e27`) supersede assumptions in the tasks below:
+
+- **FM2 resolved — no Figma account.** Figma MCP install (Task 4) is **deferred**, precondition «Figma account + file created». It is still registered (Task 6) as **deferred-pending** (precedent: Sentry MCP #34 «pending Б-1») and appears on the map (Task 7) marked deferred. A4 ships **5 live nodes now**; the 6th (Figma) activates later.
+- **Registry numbering.** deptrac already took #43 (Tooling §4.18, §0 counter **43**). A4 tools are therefore **#44 Figma MCP / #45 Universal Icons MCP / #46 Design plugin**, Tooling subsections **§4.19 / §4.20 / §4.21**, §0 counter **43 → 46**. Every `#41 / #42 / #43` in the tasks below reads as `#44 / #45 / #46`.
+- **Plugins / marketplace.** `~/.claude/settings.json` `enabledPlugins` holds **21** plugins (not 9); installing Design plugin → **22**. Marketplace `claude-plugins-official` is **already present** — no `/plugin marketplace add` needed.
+- **lefthook** has **10** jobs (deptrac = job 10). Task 1 baseline: all 10 green / "no staged files".
+- **ADR id — ADR-006, not ADR-004.** ADR-004/005 were already taken (project-management / deptrac epics). The A4 boundaries ADR is `docs/adr/ADR-006-a4-design-tooling-boundaries.md`. Every `ADR-004` in the tasks / self-review below reads as `ADR-006`.
+- **Design plugin marketplace — `knowledge-work-plugins`, not `claude-plugins-official`** (verified post-reload, 2026-05-17, against the marketplace manifest). The `design` plugin lives in `anthropics/knowledge-work-plugins` (same marketplace as #42 product-management); `claude-plugins-official` has only `frontend-design`. The `enabledPlugins` entry is `design@knowledge-work-plugins`. Every `design@claude-plugins-official` / `claude-plugins-official` reference to the **Design plugin** in the tasks below reads accordingly (`claude-plugins-official` for #33 claude-md-management / #40 security-guidance stays correct). The `/plugin install` path (Task 2 Steps 1-3) is unavailable in the VSCode-extension environment — the plugin is enabled by editing `enabledPlugins` directly.
+
+---
+
+## Tool Identity (verified 2026-05-17 — re-fact-check in Task 1)
+
+| # | Tool | Install mode | Source | Hooks? |
+|---|---|---|---|---|
+| 41 | **Figma MCP** | Remote MCP server → `.mcp.json` (`http` transport, `https://mcp.figma.com/mcp`) | Figma official; Figma↔Claude Code integration announced Feb 2026 | None (MCP server, no CC lifecycle hooks) |
+| 42 | **Universal Icons MCP** (`mcp-universal-icons`) | stdio MCP server → `.mcp.json` (`npx -y mcp-universal-icons`) | GitHub `awssat/mcp-universal-icons`, **MIT** | None (MCP server) |
+| 43 | **Design plugin** | Marketplace plugin → `~/.claude/settings.json` `enabledPlugins` | `anthropics/claude-plugins-official`, **Anthropic Verified** | Verify on install (DP4) |
+
+Kept from the A4 top-6 (already in the map): #30 Frontend Design, #31 UI UX Pro Max, #32 21st Magic MCP.
+
+---
+
+## Design Decisions & Conflict Audit
+
+Gap analysis behind the tool choice (the "что закрываем"):
+
+| A4 подзона | Покрыто до | Пробел → закрывает |
+|---|---|---|
+| UI/UX (компоненты, экраны, паттерны) | FD #30 + UPM #31 + 21st #32 | — (уже плотно) |
+| Графика (иконки, SVG) | 21st `logo_search` (только логотипы) | иконки/SVG → **#42 Universal Icons** |
+| Бренд (палитра, типографика, токены, источник) | handoff-доки Платона (статика) + ручной перенос в `vuetify.ts` | живой источник + извлечение токенов → **#41 Figma MCP** |
+| Сквозное: design-review / визуальный аудит | Pa11y (только технический a11y) | дизайн-критика, UX-копирайт, дизайн-a11y → **#43 Design plugin** |
+
+Conflict audit (pattern follows the AK/MK/CC audit used for A6). Verified against the project `.mcp.json`, `~/.claude/settings.json`, project `.claude/settings.json`, `lefthook.yml`, `.gitleaks.toml`.
+
+| # | Tool | Sev | Conflict | Resolution (locked) |
+|---|---|---|---|---|
+| FM1 | Figma MCP | 🔴 | Figma MCP can **generate UI code** (design-to-code) → duplicates FD #30 the UI solver → CLAUDE.md §5 п.6 (no two tools on one task). | **ADR-004 Decision 1 + PSR_v1 R10.1 row:** Figma MCP used **extract-only** (design-data + token reads, e.g. `get_variable_defs`). Its code-gen mode is **never invoked**. FD remains the sole UI solver (PSR_v1 R10.2). |
+| FM2 | Figma MCP | 🔴 | Figma MCP's value (token extraction from source) needs an **accessible live Figma file**. The handoff is currently static (`liderra_v8_handoff/` = `.md` + 13 HTML). No live file → the tool degrades to "describe screenshots". | **Hard gate in Task 1 Step 5.** If no accessible Figma file exists → STOP, surface to user: defer #41 (A4 set drops to 5 — the "в" variant) or obtain access from Платон. Do not install #41 blind. |
+| FM3 | Figma MCP | 🟡 | Remote MCP auth — if a static token is required it must not leak into the repo. | Prefer remote OAuth flow (no repo secret). If a token IS required → env-var via PowerShell User scope (same pattern as Sentry `SENTRY_AUTH_TOKEN`), referenced in `.mcp.json`, never inlined. gitleaks pre-push must stay 0. |
+| FM4 | Figma MCP | 🟡 | Figma MCP default code-gen targets React/Tailwind → wrong stack. | Sidestepped by FM1 (extract-only). The PSR_v1 row still states the R6.0 stack-filter applies if any Figma output is consumed as material. |
+| FM5 | Figma MCP | 🟡 | MCP server #41 unregistered = PSR_v1 R0.2/R10 violation on use. | Register in 4 normative homes (Task 6). |
+| FM6 | Figma MCP | 🟢 | Lifecycle-hook collision with the 6 economy + 2 ruflo + skill-discipline hooks. | None — MCP server, zero CC lifecycle hooks. Re-verify Task 4 Step 4. |
+| UI1 | Universal Icons | 🟢 | Overlap with FD #30. | None — icons are an asset-primitive (material); FD decides *which/where*, the MCP only fetches SVG (PSR_v1 R10.2). |
+| UI2 | Universal Icons | 🟡 | Slight overlap with 21st `logo_search` (logos). | Boundary in ADR-004 note: Universal Icons = UI **icons** (Lucide-first); 21st `logo_search` = brand **logos**. Both kept; no task-level duplication. |
+| UI3 | Universal Icons | 🟢 | MIT, stdio, hooks/registration footprint. | None — MCP server, zero hooks. Tailwind injection is optional; default SVG output is framework-neutral (R6.0 satisfied by default — never request `jsx`/Tailwind format). Re-verify Task 3 Step 4. |
+| UI4 | Universal Icons | 🟡 | MCP server #42 unregistered. | Register in 4 normative homes (Task 6). |
+| DP1 | Design plugin | 🟡 | "Accessibility Audit WCAG 2.1 AA" is a 3-way overlap: Design plugin audit × FD "a11y-принципы" (Tooling §4.4) × Pa11y (technical a11y SoT, CLAUDE.md §5 п.3). | **ADR-004 Decision 2:** Design plugin a11y = design-level critique, **pre-code**. **Pa11y stays the single source of truth** for technical a11y (PSR_v1 R8 — Pa11y wins). FD keeps a11y-principles during design. Three-tier, no override. |
+| DP2 | Design plugin | 🟡 | "Design Critique" overlaps PSR_v1 R5 (review-by-aspect — UI/UX aspect → FD) and `superpowers:requesting-code-review`/`receiving-code-review`. | **ADR-004 Decision 3:** Design Critique runs in **R2 phase 1** (research / pre-code planning), not phase-8 review. Phase-8 review stays R5 aspect-split + Superpowers review skills. Design plugin does not replace `requesting-code-review`. |
+| DP3 | Design plugin | 🟡 | Plugin #43 unregistered. | Register in 4 normative homes (Task 6). |
+| DP4 | Design plugin | 🟢 | May register CC lifecycle hooks → would touch the economy/ruflo chain. | Verify on install (Task 2 Step 4). If it injects a `hooks` entry → STOP, re-audit like A6 AK5. claude-md-management #33 ships zero hooks; security-guidance #40 ships one PreToolUse hook — Design plugin is unknown until installed. |
+| DP5 | Design plugin | 🟢 | R6.0 stack-filter applicability. | None — Design plugin is review/planning, produces no code → no R6.0 needed (treated like FD's review side). UX-writing output is Russian microcopy — fine. |
+| CC1 | all 3 | 🟡 | Bus-factor — Universal Icons is a single-maintainer community repo. | Figma MCP (Figma official) + Design plugin (Anthropic) are low-risk. Universal Icons is MIT and trivially replaceable (`iconify-mcp-server` is a drop-in alternative). Note in Tooling §4.x as a known risk. |
+
+**Severable scope:** Task 4 (Figma MCP) is gated on the FM2 spike. If the spike fails, **skip Task 4 entirely** — Tasks 1-3, 5-8 still deliver A4 at 5 nodes (Design plugin + Universal Icons added). Primary path below = full 6-node integration.
+
+---
+
+## File Structure
+
+| File | Created / Modified | Responsibility |
+|---|---|---|
+| `.mcp.json` | Modify | += `figma` server (Task 4) + `universal-icons` server (Task 3) |
+| `~/.claude/settings.json` | Modify | `enabledPlugins` += `design@claude-plugins-official`; `extraKnownMarketplaces` unchanged (Anthropic marketplace already present from #33/#40) |
+| `docs/adr/ADR-004-a4-design-tooling-boundaries.md` | Create | The 2 boundary decisions (FM1 / DP1 / DP2) — authored via adr-kit, no Enforcement block |
+| `docs/Tooling_v8_3.md` | Modify | Прил. Н — new §4.16/§4.17/§4.18 + §0 counter `40 → 43` |
+| `docs/Plugin_stack_rules_v1.md` | Modify | R10.1 — 3 new rows; R6/R10/R14 boundary notes for Figma MCP + Universal Icons |
+| `docs/Pravila_raboty_Claude_v1_1.md` | Modify | §13.2 — design-tooling note |
+| `CLAUDE.md` | Modify (**via claude-md-management only**) | §3 title count, §1 row 2b count, §3.3 rows #41/#42/#43, §6 integration paragraph |
+| `docs/CHANGELOG_claude_md.md` | Modify | CLAUDE.md version-bump entry |
+| `docs/automation-graph.html` | Modify | 3 new nodes (`mcp_figma`, `mcp_icons`, `design_plugin`) → `NODE_SECTION` A4 |
+
+---
+
+## Task 1: Pre-flight — branch, baseline, fact-check, FM2 spike
+
+**Files:** none modified (read-only) except branch creation
+
+- [ ] **Step 1: Resolve working-tree state and create the branch**
+
+```bash
+cd "c:/моя/проекты/портал crm/Документация"
+git status --short
+git branch --show-current
+git rev-parse --short HEAD
+```
+
+If `CLAUDE.md` or other files are modified from prior D3 work — confirm with the user whether to commit/stash before branching. With a clean tree:
+
+```bash
+git checkout -b feat/a4-design-tooling
+```
+
+Expected: on `feat/a4-design-tooling`; record HEAD SHA as the regression baseline.
+
+- [ ] **Step 2: Baseline the pre-commit chain**
+
+```bash
+npx lefthook run pre-commit
+```
+
+Expected: all 9 jobs (gitleaks, markdownlint, cspell, stylelint, pint, larastan, squawk, eslint-vue, adr-judge) green / "no staged files". Record the count.
+
+- [ ] **Step 3: Snapshot MCP + plugin state**
+
+```bash
+node -e "const c=require('./.mcp.json');console.log(Object.keys(c.mcpServers||c.servers||c))"
+```
+
+Read `~/.claude/settings.json` `enabledPlugins` — record the current plugin count (expected 11 after A6). Read the `hooks` block of both `~/.claude/settings.json` and project `.claude/settings.json` — record as the DP4 baseline.
+
+- [ ] **Step 4: Fact-check the 3 tools**
+
+Confirm assumptions still hold:
+
+- Figma MCP — remote endpoint `https://mcp.figma.com/mcp`, `http` transport, OAuth. Confirm the current Claude Code `claude mcp add --transport http` syntax and whether a token is needed (FM3). Source: `help.figma.com` "Claude Code and Figma: Set up the MCP server".
+- `https://github.com/awssat/mcp-universal-icons` — npm `mcp-universal-icons`, MIT, tools `search_icons`/`get_icon`/`health_check`, Lucide in the collection set, no CC hooks.
+- `https://claude.com/plugins/design` — confirm the exact marketplace id and plugin name (expected `anthropics/claude-plugins-official`, plugin `design`), Anthropic Verified, and whether it ships hooks.
+
+If any tool now registers CC lifecycle hooks → note it; DP4/FM6/UI3 re-audit in the install task.
+
+- [ ] **Step 5: FM2 spike — confirm an accessible live Figma file exists (HARD GATE)**
+
+```bash
+grep -ri "figma.com" liderra_v8_handoff/ docs/ 2>/dev/null
+```
+
+Then ask the user directly: **does Платон's v8 Forest design exist as a Figma file this project can open (view/inspect access)?**
+
+- **Accessible Figma file confirmed** → proceed to Task 4 (full 6-node path).
+- **No accessible Figma file** → STOP. Surface to the user: Figma MCP (#41) loses its core value; either (a) defer #41, ship A4 at 5 nodes (Design plugin + Universal Icons), or (b) obtain Figma access first. Do not proceed to Task 4 until the user decides.
+
+No repo files changed in Task 1 → no commit (branch creation aside).
+
+---
+
+## Task 2: Install the Design plugin (#43, marketplace)
+
+**Files:** Modify `~/.claude/settings.json` (the `Edit` triggers the `ask` permission — expected)
+
+- [ ] **Step 1: Add the marketplace if absent**
+
+The Anthropic marketplace is already present (used by #33 claude-md-management and #40 security-guidance). If `extraKnownMarketplaces` lacks it:
+
+```
+/plugin marketplace add anthropics/claude-plugins-official
+```
+
+- [ ] **Step 2: Install the plugin**
+
+```
+/plugin install design@claude-plugins-official
+```
+
+(Use the exact plugin id confirmed in Task 1 Step 4.)
+
+- [ ] **Step 3: Reload**
+
+```
+/reload-plugins
+```
+
+- [ ] **Step 4: Verify `enabledPlugins` and the hook baseline (DP4)**
+
+Read `~/.claude/settings.json`. `enabledPlugins` must now contain `design@claude-plugins-official: true` → **12 plugins total** (was 11). Read the `hooks` block of `~/.claude/settings.json` AND project `.claude/settings.json` — both must be **unchanged** vs the Task 1 Step 3 baseline. If the Design plugin injected a `hooks` entry → **STOP**, re-audit DP4 (the economy/ruflo chain must not be perturbed).
+
+- [ ] **Step 5: Smoke-test the plugin**
+
+Invoke a Design-plugin capability — e.g. ask for a design critique of one existing screen description, or a UX-writing pass on a short microcopy string. Confirm the plugin's skill activates and returns design-review output (not code).
+
+- [ ] **Step 6: Confirm economy/ruflo chain intact**
+
+Submit a trivial prompt; confirm the economy marker still appears, no hook errors. No repo files changed in Task 2 → no commit.
+
+---
+
+## Task 3: Install Universal Icons MCP (#42, stdio)
+
+**Files:** Modify `.mcp.json`
+
+- [ ] **Step 1: Add the MCP server**
+
+```bash
+claude mcp add universal-icons -- npx -y mcp-universal-icons
+```
+
+If `claude mcp add` writes to the user scope instead of the project `.mcp.json`, add the block manually to project `.mcp.json` alongside the existing servers:
+
+```json
+"universal-icons": {
+  "command": "npx",
+  "args": ["-y", "mcp-universal-icons"]
+}
+```
+
+- [ ] **Step 2: Reload and verify the server connects**
+
+```
+/reload-plugins
+```
+
+Confirm a `universal-icons` MCP server appears and its tools (`mcp__universal-icons__search_icons`, `mcp__universal-icons__get_icon`, `mcp__universal-icons__health_check`) are listed.
+
+- [ ] **Step 3: Smoke-test — Lucide icon search**
+
+Call `search_icons` for an icon known to exist in Лидерра's set (e.g. `bell`, `chevron-down`) restricted to the Lucide collection, then `get_icon` for one result. Confirm: a result is returned, the SVG is **framework-neutral** (no Tailwind classes, no JSX) — default `svg` format. Never request `jsx`/Tailwind output (UI3 / R6.0).
+
+- [ ] **Step 4: Verify no hooks / no settings drift (UI3)**
+
+Read the `hooks` block of `~/.claude/settings.json` and project `.claude/settings.json` — unchanged vs Task 1 baseline. `enabledPlugins` unchanged (MCP server ≠ plugin).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add .mcp.json
+git commit -m "feat(a4): add Universal Icons MCP server (#42, design graphics)"
+```
+
+---
+
+## Task 4: Install Figma MCP (#41, remote — gated on Task 1 Step 5)
+
+**Files:** Modify `.mcp.json`
+
+> Skip this entire task if the FM2 spike (Task 1 Step 5) failed and the user chose to defer #41.
+
+- [ ] **Step 1: Add the remote MCP server**
+
+Using the syntax confirmed in Task 1 Step 4:
+
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+Or manually in project `.mcp.json`:
+
+```json
+"figma": {
+  "type": "http",
+  "url": "https://mcp.figma.com/mcp"
+}
+```
+
+If Task 1 found a static token is required (FM3): set it as a PowerShell User-scope env var (e.g. `FIGMA_MCP_TOKEN`) and reference it via env in `.mcp.json` — **never inline the token**.
+
+- [ ] **Step 2: Authenticate**
+
+Complete the Figma OAuth flow (browser) when prompted on first server use. Confirm the project's Figma account has at least view/inspect access to the v8 Forest file confirmed in Task 1 Step 5.
+
+- [ ] **Step 3: Reload and verify the server connects**
+
+```
+/reload-plugins
+```
+
+Confirm the `figma` MCP server appears and its tools are listed (expect a `get_variable_defs`-class tool and design-data read tools).
+
+- [ ] **Step 4: Smoke-test — extract-only (FM1)**
+
+Point Figma MCP at a node in the Forest file and call the variable/token-extraction tool (`get_variable_defs` or equivalent). Confirm color/spacing/typography variables are returned. **Do NOT invoke any code-generation tool** — extract-only is the locked role (FM1). Verify no `hooks` drift in either `settings.json` (FM6).
+
+- [ ] **Step 5: Cross-check one token against the source of truth**
+
+Compare one extracted color against `app/resources/js/plugins/vuetify.ts` (Teal `#0F6E56` / ivory `#F6F3EC`). They should agree — this proves the Figma file is the genuine Forest source and the extraction is usable. Note any drift for the user; do not "fix" `vuetify.ts` in this plan.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add .mcp.json
+git commit -m "feat(a4): add Figma MCP server (#41, extract-only — FM1)"
+```
+
+---
+
+## Task 5: Author ADR-004 — A4 design-tooling boundaries
+
+**Files:** Create `docs/adr/ADR-004-a4-design-tooling-boundaries.md`
+
+- [ ] **Step 1: Generate the ADR via adr-kit**
+
+Preferred: run `/adr-kit:adr "A4 design-tooling boundaries"` and let the `adr-generator` agent emit the Nygard 7-section skeleton. Then fill it with the content below.
+
+- [ ] **Step 2: Write the ADR**
+
+Create `docs/adr/ADR-004-a4-design-tooling-boundaries.md`:
+
+```markdown
+# ADR-004: A4 design-tooling boundaries
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+- **Deciders:** Дмитрий
+
+## Context
+The A4 «Дизайн» map section adds three tools to the existing FD #30 / UPM #31 /
+21st #32: Figma MCP (#41), Universal Icons MCP (#42), Design plugin (#43). Two
+overlaps with Frontend Design (#30) were identified during selection and must be
+closed by explicit rule, not left implicit.
+
+## Decision
+1. **Figma MCP — extract-only.** Figma MCP is used solely for design-data and
+   design-token reads (e.g. `get_variable_defs`). Its design-to-code generation
+   capability is NOT used. Frontend Design (#30) remains the sole UI solver
+   (PSR_v1 R10.2 — external plugins are read-only for decisions). Figma MCP output
+   is material for FD/Claude, never a substitute solver.
+2. **Design plugin a11y is design-level, pre-code.** The Design plugin's
+   Accessibility Audit operates at design-critique level. Pa11y remains the single
+   source of truth for technical a11y (CLAUDE.md §5 п.3, PSR_v1 R8 — Pa11y wins on
+   conflict). FD continues to cover a11y-principles during design. Three tiers, no
+   override.
+3. **Design plugin critique runs in R2 phase 1.** The Design plugin's Design
+   Critique runs in the research / pre-code planning phase, not the phase-8 review.
+   Phase-8 review stays with the PSR_v1 R5 aspect-split (FD owns the UI/UX aspect)
+   plus the Superpowers review skills. The Design plugin does not replace
+   `superpowers:requesting-code-review`.
+
+## Consequences
+- A Figma MCP code-generation call is a process violation (CLAUDE.md §5 п.6).
+- Universal Icons (#42) covers UI icons; 21st `logo_search` covers brand logos —
+  distinct, both retained.
+- These boundaries are mirrored as PSR_v1 R10.1 rows + R6/R10/R14 notes (Task 6).
+
+## Enforcement
+None — role boundaries, verified by code review, not by a regex gate.
+```
+
+- [ ] **Step 3: Lint and validate**
+
+```bash
+npx markdownlint-cli2 "docs/adr/ADR-004-a4-design-tooling-boundaries.md"
+npx cspell --no-progress --no-summary --no-gitignore "docs/adr/ADR-004-a4-design-tooling-boundaries.md"
+```
+
+Add flagged valid terms to `cspell-words.txt`. Then `/adr-kit:lint docs/adr/` — expected: all ADRs pass structural checks.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/adr/ADR-004-a4-design-tooling-boundaries.md cspell-words.txt
+git commit -m "docs(adr): ADR-004 — A4 design-tooling boundaries (FM1/DP1/DP2)"
+```
+
+---
+
+## Task 6: Unified normative registry sync (FM5 / UI4 / DP3)
+
+**Files:** Modify `docs/Tooling_v8_3.md`, `docs/Plugin_stack_rules_v1.md`, `docs/Pravila_raboty_Claude_v1_1.md`, `CLAUDE.md`, `docs/CHANGELOG_claude_md.md`
+
+- [ ] **Step 1: Read the registry homes**
+
+Read for exact insertion points and counters: `docs/Tooling_v8_3.md` Прил. Н §0 (counter "40") + the last subsection §4.15; `docs/Plugin_stack_rules_v1.md` R10.1 (3 blocks); `docs/Pravila_raboty_Claude_v1_1.md` §13.2.
+
+- [ ] **Step 2: Add Tooling Прил. Н §4.16–§4.18**
+
+Edit `docs/Tooling_v8_3.md`: add three subsections — `§4.16 #41 Figma MCP`, `§4.17 #42 Universal Icons MCP`, `§4.18 #43 Design plugin`. Category: off-phase **design-tooling** (extends the UI-pool). Per tool:
+
+- **#41 Figma MCP** — Figma official remote MCP (`https://mcp.figma.com/mcp`, `http`), **extract-only** role per ADR-004 (FM1); R6.0 stack-filter applies to any consumed material (FM4); needs an accessible Figma file (FM2 — note the dependency).
+- **#42 Universal Icons MCP** — `mcp-universal-icons` (npm, MIT, `awssat`), stdio; UI icons (Lucide-first); default SVG framework-neutral (never request Tailwind/JSX — UI3); distinct from 21st `logo_search` (UI2); bus-factor note (CC1).
+- **#43 Design plugin** — `anthropics/claude-plugins-official`, Anthropic Verified; design review / a11y critique / UX writing / research synthesis; review-side (no R6.0, outside R14 — like FD); a11y is design-level, Pa11y stays technical SoT (DP1).
+
+State: Figma MCP + Universal Icons are material tools → R6.0/R6.1 + R14 pipeline apply (same as #32 21st); Design plugin is a review tool → treated like FD. Bump §0 counter `40 → 43`; bump the Прил. Н version header.
+
+- [ ] **Step 3: Add 3 PSR_v1 R10.1 rows + boundary notes**
+
+Edit `docs/Plugin_stack_rules_v1.md`: add Figma MCP, Universal Icons MCP, Design plugin rows to R10.1, category **design-tooling** (off-phase). Add the ADR-004 boundary references — Figma MCP extract-only (R10.2), Design plugin a11y/review positioning (R8 / R5). Confirm Figma MCP + Universal Icons fall under R6.0/R6.1/R14 (material-generators, like #32); Design plugin outside R14 (review). Bump the PSR_v1 version header.
+
+- [ ] **Step 4: Add the Pravila §13.2 note**
+
+Edit `docs/Pravila_raboty_Claude_v1_1.md` §13.2: add a one-line design-tooling note covering the three tools, alongside the existing infrastructure / architecture-tooling / audit-security notes. Re-read Pravila §0/§13 first to keep section numbering consistent. Bump the Pravila version header.
+
+- [ ] **Step 5: Update CLAUDE.md via the governed channel**
+
+Invoke `/claude-md-management:claude-md-improver`. Apply: §3 title count (`40` → `43`), §1 priority-chain row 2b count (`40` → `43`), three new §3.3 rows `#41 Figma MCP` / `#42 Universal Icons MCP` / `#43 Design plugin`, §6 integration paragraph (A4 closure). The plugin also writes the `docs/CHANGELOG_claude_md.md` entry and bumps §0 cross-ref versions (Tooling / PSR_v1 / Pravila).
+
+- [ ] **Step 6: Lint + commit**
+
+```bash
+npx markdownlint-cli2 "docs/Tooling_v8_3.md" "docs/Plugin_stack_rules_v1.md" "docs/Pravila_raboty_Claude_v1_1.md" "docs/CHANGELOG_claude_md.md"
+npx cspell --no-progress --no-summary --no-gitignore "docs/Tooling_v8_3.md" "docs/Plugin_stack_rules_v1.md" "docs/Pravila_raboty_Claude_v1_1.md"
+git add docs/Tooling_v8_3.md docs/Plugin_stack_rules_v1.md docs/Pravila_raboty_Claude_v1_1.md CLAUDE.md docs/CHANGELOG_claude_md.md cspell-words.txt
+git commit -m "docs(a4): register Figma MCP/Universal Icons/Design plugin #41-43 (FM5/UI4/DP3)"
+```
+
+---
+
+## Task 7: Reflect the 3 tools on the map (close A4 — 3→6)
+
+**Files:** Modify `docs/automation-graph.html`
+
+- [ ] **Step 1: Read the structures to replicate**
+
+In `docs/automation-graph.html` read, as templates: an existing MCP-server node — `mcp_21st` — across `NODES`, `NODE_DETAILS`, `NODE_SECTION`, the MCP-серверы group, and the "Паспорт узла" date fields; and an existing plugin node — `fd_plugin` — for the Design-plugin template. Record the current node/edge counts (expected ~106 nodes / ~109 edges after A6) and the MCP-серверы + плагины group sizes.
+
+- [ ] **Step 2: Add three nodes**
+
+Add to `NODES`, replicating the template shapes:
+
+- `mcp_figma` — label `Figma MCP`, MCP-серверы group.
+- `mcp_icons` — label `Universal Icons MCP`, MCP-серверы group.
+- `design_plugin` — label `Design plugin`, плагины group.
+
+Add matching `NODE_DETAILS`: `mcp_figma` — "MCP Figma (extract-only, ADR-004): извлечение токенов/variables из источника дизайна."; `mcp_icons` — "MCP Universal Icons: поиск/вставка SVG-иконок (Lucide-first)."; `design_plugin` — "Плагин Design (Anthropic): дизайн-критика, a11y-аудит, UX-копирайт — pre-code." Паспорт: дата внедрения `2026-05-17` for all three.
+
+- [ ] **Step 3: Map all three to section A4**
+
+In `NODE_SECTION` add:
+
+```js
+mcp_figma: 'A4', mcp_icons: 'A4', design_plugin: 'A4',
+```
+
+A4 «Дизайн (UI/UX, графика, бренд)» goes from 3 → 6 nodes.
+
+- [ ] **Step 4: Add edges + update header metrics**
+
+Add edges replicating how `fd_plugin`/`upm`/`mcp_21st` connect (e.g. to governing rules / the design-tooling cluster) — mirror the A6 pattern of 3 nodes / +3 edges. Bump the node count in the map header/legend by 3 (`106 → 109`) and the edge count accordingly. Update the MCP-серверы (+2) and плагины (+1) group-count comments in `NODE_SECTION`.
+
+- [ ] **Step 5: Smoke-test the map**
+
+```bash
+npx stylelint docs/automation-graph.html
+```
+
+Open `docs/automation-graph.html` in a browser (Playwright MCP or local `python -m http.server`): 0 JS console errors; the 3 new nodes render; clicking section `A4` highlights all six (FD/UPM/21st + Figma/Icons/Design).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add docs/automation-graph.html
+git commit -m "feat(map): add mcp_figma/mcp_icons/design_plugin nodes — closes section A4 (3→6)"
+```
+
+---
+
+## Task 8: Final regression & branch finish
+
+**Files:** none modified
+
+- [ ] **Step 1: Full pre-commit chain**
+
+```bash
+npx lefthook run pre-commit
+```
+
+Expected: all 9 jobs green.
+
+- [ ] **Step 2: Confirm app code untouched — run the suites**
+
+These tools change no `app/` code → suites must match the Task 1 baseline:
+
+```bash
+cd app && php artisan test --parallel
+npm run test:vue
+```
+
+Expected: Pest and Vitest counts unchanged vs the Task 1 baseline (0 regressions). Record exact counts; write out any failure with file:line.
+
+- [ ] **Step 3: Confirm the economy/ruflo hook chain is intact**
+
+Economy marker still appears; Stop verifier still runs; no plugin/server leaked a `hooks` entry into either `settings.json` (DP4/FM6/UI3 final check).
+
+- [ ] **Step 4: Pre-push checks**
+
+```bash
+./bin/gitleaks.exe detect --source . --no-banner --config .gitleaks.toml --redact
+./bin/lychee.exe --config .lychee.toml "docs/**/*.md" "db/**/*.md" "*.md"
+```
+
+Expected: gitleaks 0 leaks (FM3 — confirm no Figma token leaked); lychee 0 broken (the new `docs/adr/ADR-004*.md` is scanned — fix or `.lychee.toml`-exclude any link).
+
+- [ ] **Step 5: Finish the branch**
+
+Invoke `superpowers:finishing-a-development-branch` — present the standard options. Do **not** push without an explicit user choice.
+
+---
+
+## Self-Review
+
+**1. Spec coverage** — A4 gap analysis: графика → #42 (Task 3), бренд/источник → #41 (Task 4), design-review → #43 (Task 2). Conflict audit: FM1→ADR-004 D1 (Task 5) + PSR_v1 row (Task 6.3); FM2→Task 1.5 hard gate; FM3→Task 4.1; FM4→Task 6.2; FM5/UI4/DP3→Task 6; FM6/UI3/DP4→install-task verify steps; UI1→no task (no conflict); UI2→ADR-004 + Tooling note; DP1→ADR-004 D2; DP2→ADR-004 D3; DP5→no task; CC1→Tooling §4.x note. Map A4 closure→Task 7. No gaps.
+
+**2. Placeholder scan** — Task 1 Step 4/Step 5 and Task 7 Step 1 are *fact-check / decision / read-template* steps with concrete criteria, not "TBD" (exact MCP-add syntax, the FM2 prerequisite, and the live 2400-line map node shapes are not knowable without install / without reading the file). All commands exact; ADR-004 content shown in full; the `.mcp.json` blocks shown in full.
+
+**3. Consistency** — registry numbers `#41 Figma / #42 Universal Icons / #43 Design` consistent across Tasks 5-7; counter `40 → 43` consistent Task 6.2↔6.5; node ids `mcp_figma`/`mcp_icons`/`design_plugin` consistent Task 7 Steps 2-3; map count `106 → 109` consistent; ADR id `ADR-004` consistent Task 5↔6↔7; "extract-only" wording for Figma MCP consistent FM1↔ADR-004↔Tooling↔map.
+
+---
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/2026-05-17-a4-design-tooling-integration.md`. Two execution options:
+
+1. **Subagent-Driven** — fresh subagent per task, two-stage review. *Caveat:* Tasks 2-5 (slash commands `/plugin …`, `/reload-plugins`, `claude mcp add`, `/adr-kit:adr`, `/adr-kit:lint`), Task 4 Step 2 (Figma OAuth) and Task 6 Step 5 (`claude-md-management`) are main-session-bound — those steps stay with the controller.
+2. **Inline Execution** — `superpowers:executing-plans`, batch with checkpoints. **Recommended here** — the integration is install/config/docs-heavy with many interactive main-session steps and one user-decision gate (FM2).
+
+Open gate for the user: the **FM2 spike (Task 1 Step 5)** decides full 6-node (`#41` included) vs 5-node (`#41` deferred). Surface the result before Task 4.