code-ai-installer 1.3.0 → 1.4.0

package/.agents/skills/tests_quality_review/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: tests_quality_review
+description: Ревью качества unit/integration тестов — покрытие сценариев, границы, устойчивость, отсутствие флейков и тестовой "магии". Чеклист с приоритетами, примеры хорошего/плохого теста, шаблон выходного отчёта. Активируй при ревью существующих тестов, при стабилизации flaky тестов, или при аудите test suite quality.
+---
+
+# Skill: Tests Quality Review
+
+Структурированное ревью качества тестов: чеклист, приоритеты, примеры плохого → хорошего, шаблон отчёта.
+
+**Разделы:**
+1. [Когда активировать](#1-когда-активировать)
+2. [Чеклист ревью](#2-чеклист-ревью)
+3. [Примеры: плохо → хорошо](#3-примеры-плохо--хорошо)
+4. [Flaky-тесты: диагностика](#4-flaky-тесты-диагностика)
+5. [Шаблон выходного отчёта](#5-шаблон-выходного-отчёта)
+
+---
+
+## 1. Когда активировать
+
+- REV gate — ревью тестов как часть code review
+- После TDD-итерации — проверить качество написанных тестов
+- При стабилизации flaky-CI — найти и починить хрупкие тесты
+- При аудите coverage — не гнаться за %, а проверить *что* покрыто
+
+---
+
+## 2. Чеклист ревью
+
+### A. Покрытие сценариев (P0)
+
+| # | Проверка | Вердикт |
+|---|---------|---------|
+| A1 | Тесты проверяют **поведение**, не детали реализации | ✅/❌ |
+| A2 | Есть **happy path** для каждого публичного метода/компонента | ✅/❌ |
+| A3 | Есть **error paths** (невалидный ввод, сетевая ошибка, пустые данные) | ✅/❌ |
+| A4 | Есть **edge cases** / boundaries (0, null, undefined, пустая строка, max) | ✅/❌ |
+| A5 | Async-логика протестирована (таймауты, reject, race conditions) | ✅/❌ |
+
+### B. Устойчивость (P0)
+
+| # | Проверка | Вердикт |
+|---|---------|---------|
+| B1 | Тесты **независимы** (нет скрытого порядка выполнения) | ✅/❌ |
+| B2 | Нет **shared mutable state** между тестами | ✅/❌ |
+| B3 | Каждый `beforeEach` / `afterEach` правильно чистит состояние | ✅/❌ |
+| B4 | Нет зависимости от **реального времени** (Date.now, setTimeout) | ✅/❌ |
+| B5 | Нет зависимости от **сети / файловой системы** (всё замокано) | ✅/❌ |
+
+### C. Качество кода тестов (P1)
+
+| # | Проверка | Вердикт |
+|---|---------|---------|
+| C1 | Названия тестов читаемые: `should [verb] when [condition]` | ✅/❌ |
+| C2 | AAA-паттерн (Arrange → Act → Assert) явно прослеживается | ✅/❌ |
+| C3 | Нет **magic numbers/strings** без пояснений | ✅/❌ |
+| C4 | Нет **дублирования** (используются фабрики, хелперы, shared fixtures) | ✅/❌ |
+| C5 | Assertions **конкретные** (не `toBeTruthy()`, а `toBe(true)` / `toEqual(...)`) | ✅/❌ |
+
+### D. Интеграционные тесты (P1)
+
+| # | Проверка | Вердикт |
+|---|---------|---------|
+| D1 | **Реально** проверяют интеграцию (API/DB/контракты) | ✅/❌ |
+| D2 | Не «пере-моканы» (моки только на внешних границах) | ✅/❌ |
+| D3 | Контрактные тесты проверяют **форму ответа**, не бизнес-логику | ✅/❌ |
+| D4 | Данные тестов **изолированы** (нет мусора от предыдущих прогонов) | ✅/❌ |
+
+### E. Snapshot-тесты (P2)
+
+| # | Проверка | Вердикт |
+|---|---------|---------|
+| E1 | Snapshot используется **осознанно** (для стабильного output) | ✅/❌ |
+| E2 | Snapshot **компактный** (не 500 строк) — inline preferred | ✅/❌ |
+| E3 | Обновление snapshot не «авто-accept» (diff ревьюится) | ✅/❌ |
+
+---
+
+## 3. Примеры: плохо → хорошо
+
+### A1. Поведение vs реализация
+
+```js
+// ❌ Тестирует реализацию: проверяет что вызван внутренний метод
+it('should call _processInternal', () => {
+  const spy = vi.spyOn(service, '_processInternal');
+  service.process(data);
+  expect(spy).toHaveBeenCalled();
+});
+
+// ✅ Тестирует поведение: проверяет результат
+it('should return processed data with status "done"', () => {
+  const result = service.process({ items: [1, 2, 3] });
+  expect(result.status).toBe('done');
+  expect(result.processedCount).toBe(3);
+});
+```
+
+### B1. Независимость тестов
+
+```js
+// ❌ Тест зависит от предыдущего — если первый упадёт, второй тоже
+let createdId;
+it('should create', () => { createdId = create(); });
+it('should read', () => { read(createdId); }); // зависимость!
+
+// ✅ Каждый тест самодостаточен
+it('should read created item', () => {
+  const id = create({ name: 'test' });
+  const item = read(id);
+  expect(item.name).toBe('test');
+});
+```
+
+### B4. Зависимость от времени
+
+```js
+// ❌ Flaky — зависит от скорости выполнения
+it('should be within 1 second', () => {
+  const start = Date.now();
+  doWork();
+  expect(Date.now() - start).toBeLessThan(1000);
+});
+
+// ✅ Мокаем время
+it('should expire after timeout', () => {
+  vi.useFakeTimers();
+  const onExpire = vi.fn();
+
+  startTimer(onExpire, 5000);
+  vi.advanceTimersByTime(5000);
+
+  expect(onExpire).toHaveBeenCalledOnce();
+  vi.useRealTimers();
+});
+```
+
+### C3. Магические значения
+
+```js
+// ❌ Что за 42?
+expect(calc(x)).toBe(42);
+
+// ✅ Значение объяснено
+const BASE = 100;
+const TAX_RATE = 0.12;
+const DISCOUNT = 50;
+const EXPECTED = (BASE - DISCOUNT) * (1 + TAX_RATE); // 56
+expect(calcTotal(BASE, TAX_RATE, DISCOUNT)).toBe(EXPECTED);
+```
+
+### C5. Конкретные assertions
+
+```js
+// ❌ toBeTruthy — undefined, 0, "" тоже falsy → ложно-позитивный тест
+expect(result).toBeTruthy();
+expect(array.length).toBeTruthy(); // 0 — falsy, тест упадёт
+
+// ✅ Конкретный assertion
+expect(result).toBe(true);
+expect(array).toHaveLength(3);
+expect(obj).toMatchObject({ name: 'test', active: true });
+```
+
+### D2. Пере-моканые интеграционные тесты
+
+```js
+// ❌ Замокано всё — это уже не интеграционный тест
+vi.mock('../db.js');
+vi.mock('../validator.js');
+vi.mock('../queue.js');
+
+it('should process order', async () => {
+  db.save.mockResolvedValue({ id: 1 });
+  validator.check.mockReturnValue(true);
+  queue.push.mockResolvedValue(undefined);
+
+  await processOrder({ item: 'X' });
+  expect(db.save).toHaveBeenCalled(); // проверяем мок, не логику
+});
+
+// ✅ Мокаем только внешнюю границу (HTTP), остальное — реальное
+vi.mock('../services/payment-gateway.js'); // единственный мок
+
+it('should process order and save to DB', async () => {
+  paymentGateway.charge.mockResolvedValue({ txnId: 'TX123' });
+
+  const result = await processOrder({ item: 'X', amount: 100 });
+
+  expect(result.status).toBe('completed');
+  const stored = await db.orders.findById(result.id);
+  expect(stored.paymentTxnId).toBe('TX123');
+});
+```
+
+---
+
+## 4. Flaky-тесты: диагностика
+
+### Частые причины
+
+| Причина | Симптом | Исправление |
+|---------|--------|-------------|
+| **Зависимость от времени** | Проходит/падает рандомно | `vi.useFakeTimers()` |
+| **Shared state** | Падает при `--shuffle` или параллельном запуске | Изолировать state в `beforeEach` |
+| **Внешние сервисы** | Падает при медленной сети / запуске offline | Мокать все HTTP |
+| **Race conditions** | Периодические таймауты | `await` / `waitFor` вместо `sleep` |
+| **Рандомные данные** | `Math.random()` в тестах даёт разные результаты | Seed или мокать random |
+| **Зависимость от порядка** | Проходит solo, падает в suite | Убрать shared state |
+| **Утечки таймеров** | `setTimeout` не очищен, влияет на следующий тест | `afterEach(() => vi.clearAllTimers())` |
+
+### Проверка на flaky
+
+```bash
+# Запустить тест 10 раз — если хотя бы 1 падение → flaky
+for i in $(seq 1 10); do npx vitest run --reporter=dot; done
+
+# Или через Vitest repeat
+npx vitest run --repeat=10
+```
+
+---
+
+## 5. Шаблон выходного отчёта
+
+```markdown
+# Tests Quality Review Report
+
+## Summary
+- **Module/Feature:** [название]
+- **Total tests:** [N]
+- **Coverage:** [X]% statements, [Y]% branches
+- **Verdict:** PASS ✅ / PASS with findings ⚠️ / FAIL ❌
+
+## Findings
+
+### P0 — Блокеры
+| # | Пункт чеклиста | Проблема | Рекомендация |
+|---|----------------|---------|-------------|
+| 1 | A3 (error paths) | Нет тестов на сетевые ошибки в fetchItems | Добавить тест с reject mock |
+
+### P1 — Важные
+| # | Пункт чеклиста | Проблема | Рекомендация |
+|---|----------------|---------|-------------|
+| 1 | C3 (magic) | `expect(result).toBe(42)` без пояснений | Вынести в const с именем |
+
+### P2 — Улучшения
+| # | Пункт чеклиста | Проблема | Рекомендация |
+|---|----------------|---------|-------------|
+| 1 | E2 (snapshot size) | Snapshot на 200 строк в ProductForm.test | Перейти на inline snapshot или RTL assertion |
+
+## Missing Test Cases
+- [ ] `fetchItems` — error path (network failure)
+- [ ] `updateRecord` — edge case (empty name)
+- [ ] `CountdownTimer` — boundary (0 seconds remaining)
+
+## Fragile Tests
+| Тест | Причина хрупкости | Рекомендация |
+|------|-------------------|-------------|
+| `pricing.test.js:42` | Зависимость от Date.now | vi.useFakeTimers |
+```
+
+---
+
+## Критерии вердикта
+
+| Вердикт | Условия |
+|---------|---------|
+| **PASS ✅** | Все P0 ✅, P1 ≤ 2 findings, нет flaky |
+| **PASS with findings ⚠️** | Все P0 ✅, но есть P1 findings или missing cases | 
+| **FAIL ❌** | Любой P0 ❌ (нет error paths, тесты зависимы, flaky) |
+
+---
+
+## См. также
+- `$testing_strategy_js` — стратегия и паттерны написания тестов
+- `$code_review_checklist` — общий чеклист code review
+- `$qa_e2e_playwright` — E2E через Playwright
+- `$dev_reference_snippets` — примеры кода

package/.agents/skills/threat_model_baseline/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: threat_model_baseline
+description: Базовая модель угроз (threat baseline) для MVP — активы, векторы атак, меры. Учитывает OWASP-риски и роли/права.
+---
+
+# Skill: Threat Model Baseline
+
+Встроить безопасность в дизайн до кода.
+
+**Разделы:**
+1. [Принципы](#1-принципы)
+2. [Assets](#2-assets)
+3. [Attack Surfaces](#3-attack-surfaces)
+4. [Threat Table](#4-threat-table)
+5. [Risk Matrix](#5-risk-matrix)
+6. [OWASP Top 10 Checklist](#6-owasp)
+7. [Security Requirements](#7-requirements)
+8. [Пример](#8-пример)
+9. [Output Template](#9-output)
+
+---
+
+## 1. Принципы
+
+| Принцип | Описание | Пример |
+|---------|---------|--------|
+| **Defense in depth** | Несколько слоёв защиты | Validation + auth + sanitization |
+| **Least privilege** | Минимальные права | DB user: readWrite only, no admin |
+| **Input validation at boundaries** | Не доверяй никакому input | Zod schema на каждый endpoint |
+| **Secure by default** | Безопасно "из коробки" | CORS whitelist, Helmet on, strict CSP |
+| **Fail securely** | Ошибка → безопасное состояние | Don't expose stack/DB errors |
+| **Audit trail** | Логируй критичные операции | Install, settings change, content create |
+
+---
+
+## 2. Assets
+
+Что мы защищаем:
+
+| Asset | Sensitivity | Impact if compromised |
+|-------|-----------|----------------------|
+| **App settings** | Medium | Widget shows incorrect data |
+| **Sensitive content** | Medium | Unauthorized access to business data |
+| **appInstanceId/tokens** | High | Unauthorized access to any installation |
+| **Wix OAuth tokens** | High | Full API access to user's Wix site |
+| **DB credentials** | Critical | Full data access + modification |
+| **Webhook secrets** | High | Spoofed install/uninstall events |
+| **User PII (email)** | High (GDPR) | Compliance violation, reputation damage |
+| **Admin access** | Critical | Full system control |
+
+---
+
+## 3. Attack Surfaces
+
+| Surface | Endpoints/Components | Risk Level |
+|---------|---------------------|-----------|
+| **Public API** | Widget endpoint (no auth) | Medium |
+| **Dashboard API** | Settings/Content CRUD | High |
+| **Webhooks** | Install/Uninstall | High |
+| **Embedded Script** | JS on Wix sites | Medium |
+| **Dashboard UI** | Wix iframe | Medium |
+| **Database** | MongoDB connection | High |
+| **Docker/Infra** | Ports, volumes, certs | Medium |
+
+---
+
+## 4. Threat Table
+
+Для каждой угрозы: описание, impact, likelihood, severity, mitigation.
+
+| # | Threat | Surface | Impact | Likelihood | Severity | Mitigation | Status |
+|---|--------|---------|--------|-----------|----------|-----------|--------|
+| T-01 | **NoSQL Injection** | Dashboard API | High | Medium | 🔴 P0 | Safe filter builder, Zod validation, `strictQuery: true` | ☐ |
+| T-02 | **XSS via settings** | Embedded Script | High | Medium | 🔴 P0 | Sanitize all user input before rendering, CSP headers | ☐ |
+| T-03 | **Webhook spoofing** | Webhook endpoint | High | Low | 🟠 P1 | Verify JWT signature, validate payload structure | ☐ |
+| T-04 | **IDOR (Insecure Direct Object Reference)** | Dashboard API | High | Medium | 🔴 P0 | Verify appInstanceId belongs to authenticated user | ☐ |
+| T-05 | **Secrets in code/logs** | All | Critical | Medium | 🔴 P0 | Env vars only, pino redact, .gitignore | ☐ |
+| T-06 | **Brute force enumeration** | Widget endpoint | Medium | Low | 🟡 P2 | Rate limiting on widget endpoint | ☐ |
+| T-07 | **CSRF** | Dashboard API | Medium | Low | 🟠 P1 | SameSite cookies, origin check | ☐ |
+| T-08 | **Dependency supply chain** | npm packages | High | Low | 🟠 P1 | `npm audit`, lockfile, minimal deps | ☐ |
+| T-09 | **Man-in-the-middle** | All HTTP | High | Low | 🟠 P1 | HTTPS everywhere (Caddy), HSTS | ☐ |
+| T-10 | **Embed script injection** | Wix site | High | Low | 🟠 P1 | Script src from trusted origin only, no eval() | ☐ |
+
+---
+
+## 5. Risk Matrix
+
+### Impact × Likelihood
+
+```
+              │ Low Likelihood │ Medium │ High
+──────────────┼────────────────┼────────┼──────
+High Impact   │ 🟠 P1          │ 🔴 P0  │ 🔴 P0
+Medium Impact │ 🟡 P2          │ 🟠 P1  │ 🔴 P0
+Low Impact    │ 🟡 P2          │ 🟡 P2  │ 🟠 P1
+```
+
+### Severity actions
+
+| Severity | Action | Timeline |
+|----------|--------|----------|
+| 🔴 **P0** | Must fix before release | This sprint |
+| 🟠 **P1** | Fix in current iteration | Next 2 sprints |
+| 🟡 **P2** | Track in backlog | When resources allow |
+
+---
+
+## 6. OWASP Top 10 Checklist
+
+| # | OWASP Category | Relevant? | Mitigation | Status |
+|---|---------------|:---------:|-----------|--------|
+| A01 | **Broken Access Control** | ✅ | Auth middleware, IDOR check, role validation | ☐ |
+| A02 | **Cryptographic Failures** | ✅ | HTTPS, bcrypt for passwords, no secrets in logs | ☐ |
+| A03 | **Injection** | ✅ | Zod validation, safe filter builder, no eval() | ☐ |
+| A04 | **Insecure Design** | ✅ | Threat model (this doc), defense in depth | ☐ |
+| A05 | **Security Misconfiguration** | ✅ | Helmet, CORS whitelist, strict CSP, no debug in prod | ☐ |
+| A06 | **Vulnerable Components** | ✅ | npm audit, lockfile, minimal dependencies | ☐ |
+| A07 | **Auth Failures** | ⬜ | Wix handles auth (OAuth flow) | N/A |
+| A08 | **Data Integrity Failures** | ✅ | Webhook signature verification, input validation | ☐ |
+| A09 | **Logging Failures** | ✅ | Structured logs, request correlation, no PII in logs | ☐ |
+| A10 | **SSRF** | ⬜ | No user-controlled URL fetching | N/A |
+
+---
+
+## 7. Security Requirements
+
+### For implementation (DEV gate)
+
+| Requirement | Where | How to verify |
+|------------|-------|--------------|
+| Input validation on every endpoint | API middleware | Unit test: invalid input → 400 |
+| Auth check on protected endpoints | Auth middleware | Test: no token → 401 |
+| IDOR prevention | Controllers | Test: wrong appInstanceId → 403 |
+| Secure error responses | Error handler | Test: 500 → no stack in response |
+| Secrets via env only | Config module | grep: no hardcoded secrets |
+| Helmet + CORS | Express setup | Integration test: check headers |
+| PII redaction in logs | Pino config | Log output: no passwords/tokens |
+
+### For review (REV gate)
+
+| Requirement | How to verify |
+|------------|--------------|
+| No `eval()`, `Function()`, `dangerouslySetInnerHTML` without sanitize | grep |
+| No `eslint-disable-next-line` for security rules | grep |
+| `npm audit` clean (no high/critical) | `npm audit --audit-level=high` |
+| No TODO/FIXME related to security | grep `TODO.*secur\|FIXME.*auth` |
+
+---
+
+## 8. Пример
+
+```markdown
+# Threat Model: SaaS Admin Panel
+
+## Key Assets
+- Admin credentials (sessions, API tokens)
+- Product/content data, user settings
+- DB credentials, external API keys
+
+## Top Threats (prioritized)
+1. 🔴 T-01: NoSQL injection via admin API → Zod + safe filter
+2. 🔴 T-04: IDOR on resources → verify ownership middleware
+3. 🔴 T-05: Secrets in code/logs → env vars + pino redact
+4. 🟠 T-03: CSRF on state-changing endpoints → SameSite + tokens
+5. 🟠 T-10: XSS in public content → sanitize user input
+
+## OWASP Coverage: 8/10 categories addressed (A07, A10 N/A)
+```
+
+---
+
+## 9. Output Template
+
+```markdown
+# Threat Model Baseline: <project-name>
+
+**Date:** YYYY-MM-DD
+**Scope:** <what's covered>
+
+## Assets
+<section 2 table>
+
+## Attack Surfaces
+<section 3 table>
+
+## Threats
+<section 4 table — prioritized by severity>
+
+## Risk Matrix
+<section 5>
+
+## OWASP Top 10
+<section 6 checklist>
+
+## Security Requirements
+<section 7 tables>
+
+## Summary
+- P0 threats: X (must fix before release)
+- P1 threats: Y (fix in current iteration)
+- P2 threats: Z (backlog)
+```
+
+---
+
+## См. также
+- `$security_baseline_dev` — implementation patterns (Zod, Helmet, bcrypt)
+- `$security_review` — AppSec review checklist
+- `$api_contracts` — auth/error conventions
+- `$observability_logging` — PII redaction, audit logging

package/.agents/skills/ui_a11y_smoke_review/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: ui_a11y_smoke_review
+description: Быстрый UI/a11y smoke review дизайнера — состояния loading/empty/error, фокус, клавиатура, aria/labels, соответствие UX Spec. Выполняется ДО передачи в QA.
+---
+
+# Skill: UI & A11y Smoke Review (Designer-Level)
+
+Быстрая designer-level проверка UI на соответствие UX Spec + a11y baseline **до передачи в QA**.
+
+> **Отличие от `$qa_ui_a11y_smoke`:** Этот скилл — дизайнерский quick check (5-10 мин, по UX Spec).
+> `$qa_ui_a11y_smoke` — формальный QA тест (25 WCAG checks, tools, report).
+
+**Разделы:**
+1. [Workflow](#1-workflow)
+2. [Checklist](#2-checklist)
+3. [UX Spec Compliance](#3-ux-compliance)
+4. [Quick A11y Scan](#4-a11y-scan)
+5. [Output Template](#5-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Input:
+   ├── Implemented UI (browser / screenshots)
+   ├── UX Spec (из $ux_spec) — source of truth
+   └── A11y Baseline (из $a11y_baseline) — requirements
+
+2. Visual walkthrough per screen:
+   a. Does layout match UX Spec?
+   b. Are all components/sections present?
+   c. Are all 4 states implemented (loading/empty/error/success)?
+   d. Quick keyboard pass (Tab through interactive elements)
+
+3. Classify issues:
+   ├── P0: Missing critical states, broken flow, inaccessible
+   ├── P1: Wrong component, missing state, inconsistency
+   └── P2: Polish, spacing, cosmetic
+
+4. Report → DEV fixes before formal QA
+
+Note: This is a QUICK check. For formal testing → $qa_ui_a11y_smoke
+```
+
+---
+
+## 2. Checklist
+
+### 2.1 Visual & Layout
+
+| # | Check | UX Spec ref | Severity | Status |
+|---|-------|------------|----------|--------|
+| UI-01 | Layout matches UX Spec (columns, sections, order) | Screen Spec → Layout | 🟠 P1 | ☐ |
+| UI-02 | All sections present (no missing panels/cards) | Screen Spec → Sections | 🟠 P1 | ☐ |
+| UI-03 | Primary CTA visible and correctly styled | Screen Spec → Actions | 🔴 P0 | ☐ |
+| UI-04 | Typography hierarchy matches (h1 > h2 > body) | UI Inventory → Tokens | 🟡 P2 | ☐ |
+| UI-05 | Colors match design tokens | Design Rules → DR-xx | 🟠 P1 | ☐ |
+
+### 2.2 UI States
+
+| # | Check | Against | Severity | Status |
+|---|-------|---------|----------|--------|
+| UI-06 | **Loading** state present (skeleton or spinner per UX Spec) | Screen Spec → States | 🟠 P1 | ☐ |
+| UI-07 | **Empty** state present (illustration + text + CTA) | Screen Spec → States | 🟠 P1 | ☐ |
+| UI-08 | **Error** state present (message + retry/action) | Screen Spec → States | 🔴 P0 | ☐ |
+| UI-09 | **Success** feedback (toast/message after action) | Screen Spec → Notifications | 🟠 P1 | ☐ |
+| UI-10 | **Disabled** state clear (visual + non-clickable) | Screen Spec → States | 🟡 P2 | ☐ |
+| UI-11 | **Saving/In-flight** state (button spinner, disabled) | Screen Spec → Actions | 🟠 P1 | ☐ |
+
+### 2.3 Forms
+
+| # | Check | Against | Severity | Status |
+|---|-------|---------|----------|--------|
+| UI-12 | All form fields have visible labels | A11y Baseline A-10 | 🔴 P0 | ☐ |
+| UI-13 | Required fields marked (asterisk or text) | A11y Baseline A-11 | 🟠 P1 | ☐ |
+| UI-14 | Error messages visible and descriptive | Screen Spec → Validation | 🟠 P1 | ☐ |
+| UI-15 | Submit button feedback (loading/disabled during save) | Screen Spec → Actions | 🟠 P1 | ☐ |
+
+### 2.4 Quick A11y
+
+| # | Check | Against | Severity | Status |
+|---|-------|---------|----------|--------|
+| UI-16 | Can Tab to all interactive elements | A11y Baseline A-01 | 🔴 P0 | ☐ |
+| UI-17 | Focus ring visible on focused elements | A11y Baseline A-05 | 🔴 P0 | ☐ |
+| UI-18 | Modal traps focus + Escape closes | A11y Baseline A-07 | 🟠 P1 | ☐ |
+| UI-19 | No obvious contrast issues (text readable) | A11y Baseline A-19 | 🟠 P1 | ☐ |
+| UI-20 | Content/buttons not cut off or overlapping | — | 🟠 P1 | ☐ |
+
+---
+
+## 3. UX Spec Compliance
+
+### Per-screen verification
+
+For each screen in UX Spec, verify implementation matches:
+
+```markdown
+### Screen: <Name>
+
+| UX Spec Element | Expected | Implemented? | Notes |
+|----------------|----------|:------------:|-------|
+| Layout: 2-column 60/40 | Config + Preview | ✅ | — |
+| Tab: General | Title, Subtitle, CTA fields | ✅ | — |
+| Tab: Design | ColorPicker × 4, FontSelect | ⚠️ | Missing overlay picker |
+| Tab: Timer | Switch + NumberInputs | ✅ | — |
+| State: Loading | Skeleton | ❌ | Shows blank page |
+| State: Error (save) | Toast + inline errors | ⚠️ | Toast only, no inline |
+| Notification: Save success | Toast, 3s auto-dismiss | ✅ | — |
+```
+
+---
+
+## 4. Quick A11y Scan
+
+### 60-second keyboard test
+
+| Step | Action | Expected | Status |
+|------|--------|----------|:------:|
+| 1 | Press Tab from page top | Focus on first interactive element | ☐ |
+| 2 | Tab through all controls | Each gets visible focus ring | ☐ |
+| 3 | Enter on buttons | Action fires | ☐ |
+| 4 | Open modal/dropdown | Focus moves inside | ☐ |
+| 5 | Escape on modal | Modal closes, focus returns | ☐ |
+
+### Quick visual checks
+
+| Check | How | Expected |
+|-------|-----|---------|
+| Contrast | Squint test — can you read all text? | All text readable |
+| Hierarchy | Scan page — is structure clear? | Clear h1 > h2 > body |
+| CTA | Is the primary action obvious? | One clear primary button |
+| Errors | Trigger an error — is it clear? | Visible, descriptive, near the field |
+
+---
+
+## 5. Output Template
+
+```markdown
+# UI & A11y Smoke Review
+
+**Date:** YYYY-MM-DD
+**Reviewer:** UX/UI Designer Agent
+**Screen(s):** <list>
+**UX Spec:** <reference>
+
+## Checklist Results
+| Section | Pass | Fail | Total |
+|---------|:----:|:----:|:-----:|
+| Visual & Layout (UI-01..05) | 4 | 1 | 5 |
+| UI States (UI-06..11) | 4 | 2 | 6 |
+| Forms (UI-12..15) | 3 | 1 | 4 |
+| Quick A11y (UI-16..20) | 4 | 1 | 5 |
+| **Total** | **15** | **5** | **20** |
+
+## UX Spec Compliance
+| Screen | Elements checked | Match | Mismatch |
+|--------|:---------------:|:-----:|:--------:|
+| Settings | 7 | 5 | 2 |
+| Items | 5 | 5 | 0 |
+
+## Findings
+| # | Severity | Check | Screen | Finding | Fix |
+|---|----------|-------|--------|---------|-----|
+| 1 | 🔴 P0 | UI-08 | Settings | No error state for failed save | Add error toast + inline errors |
+| 2 | 🟠 P1 | UI-06 | Settings | Blank page instead of skeleton | Add skeleton loader |
+| 3 | 🟠 P1 | UI-05 | Design tab | Missing overlay color picker | Add 4th ColorPicker |
+| 4 | 🟡 P2 | UI-04 | Settings | Section titles not bold enough | Increase font-weight |
+
+## Keyboard Test
+| Step | Status |
+|------|:------:|
+| Tab navigation | ✅ |
+| Focus visible | ✅ |
+| Enter activates | ✅ |
+| Modal focus trap | ⚠️ Focus escapes |
+| Escape closes | ✅ |
+
+## Verdict
+- ✅ **READY FOR QA** — no P0, minor issues tracked
+- ⚠️ **FIX FIRST** — P0/P1 issues must be fixed before QA
+- ❌ **NOT READY** — critical UX/a11y issues block QA
+
+## Next
+- If READY → pass to $qa_ui_a11y_smoke for formal testing
+- If FIX FIRST → create DEV-xx tasks, re-review after fix
+```
+
+---
+
+## См. также
+- `$qa_ui_a11y_smoke` — formal QA a11y testing (25 WCAG checks)
+- `$ux_spec` — UX Spec (source of truth)
+- `$a11y_baseline` — a11y requirements
+- `$design_parity_review` — full design comparison