code-ai-installer 1.3.0 → 1.4.0

package/.agents/skills/ui_inventory/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: ui_inventory
+description: Составить инвентарь UI компонентов и правила переиспользования — базовые компоненты, композиционные компоненты, паттерны (forms, tables, dialogs), дизайн-токены (минимум).
+---
+
+# Skill: UI Components Inventory
+
+Каталог UI компонентов с variants, states, a11y notes.
+
+**Разделы:**
+1. [Workflow](#1-workflow)
+2. [Component Card Template](#2-card)
+3. [Component Catalog](#3-catalog)
+4. [Design Tokens](#4-tokens)
+5. [Design System Mapping](#5-mapping)
+6. [Пример: Button Card](#6-пример)
+7. [Output Template](#7-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Input: UX Spec (из $ux_spec)
+2. Extract все упомянутые компоненты из Screen Specs
+3. Classify: atom / molecule / organism / pattern
+4. For each → Component Card (section 2)
+5. Map to design system (section 5) если есть
+6. Define design tokens (section 4)
+7. Validate: каждый компонент в UI Spec покрыт
+```
+
+### Decision: Use existing vs Build custom
+
+```
+Компонент нужен ← UX Spec
+    ├── Есть в дизайн-системе? (WDS / shadcn / Mantine)
+    │   ├── Да, подходит → USE (указать import + variant)
+    │   ├── Да, но нужна кастомизация → CUSTOMIZE (wrapper component)
+    │   └── Нет → BUILD CUSTOM (с a11y baseline)
+    └── Уже есть в проекте?
+        ├── Да → REUSE (указать путь)
+        └── Нет → CREATE (по template)
+```
+
+---
+
+## 2. Component Card Template
+
+```markdown
+### Component: <Name>
+
+**Category:** Atom / Molecule / Organism
+**Source:** WDS | shadcn | Custom | Existing (<path>)
+**Used in:** <screens list>
+
+#### Variants
+| Variant | Visual | Use case |
+|---------|--------|----------|
+| primary | Filled, accent color | Main CTA |
+| secondary | Outlined | Secondary actions |
+| ghost | Text only | Tertiary actions |
+| destructive | Red filled | Delete/remove |
+
+#### Props
+| Prop | Type | Required | Default | Description |
+|------|------|:--------:|---------|-------------|
+| label | string | ✅ | — | Button text |
+| variant | enum | ❌ | "primary" | Visual style |
+| size | "sm" | "md" | "lg" | ❌ | "md" | Dimensions |
+| disabled | boolean | ❌ | false | Disable interaction |
+| loading | boolean | ❌ | false | Show spinner |
+| onClick | function | ✅ | — | Click handler |
+
+#### States
+| State | Visual | Behavior |
+|-------|--------|----------|
+| Default | Normal appearance | Clickable |
+| Hover | Darker bg / lighter bg | Cursor pointer |
+| Active/Pressed | Slight scale down | Processing |
+| Focused | Focus ring visible | Keyboard nav |
+| Disabled | 50% opacity | Not clickable |
+| Loading | Spinner replaces label | Not clickable |
+
+#### A11y Notes
+- Uses `<button>` element (not div)
+- `aria-disabled` when disabled
+- `aria-busy` when loading
+- Focus visible via `:focus-visible`
+```
+
+---
+
+## 3. Component Catalog
+
+### 3.1 Atoms (base elements)
+
+| Component | Variants | Source | A11y |
+|-----------|---------|--------|------|
+| **Button** | primary / secondary / ghost / destructive | WDS / Custom | `<button>`, focus-visible |
+| **TextInput** | default / error / disabled | WDS / Custom | `<label>` linked, aria-invalid |
+| **Textarea** | default / error / disabled | WDS / Custom | `<label>` linked |
+| **Select** | default / error / disabled | WDS / Custom | aria-expanded, listbox role |
+| **Checkbox** | unchecked / checked / indeterminate | WDS | `<input type="checkbox">` |
+| **Switch** | off / on / disabled | WDS | role="switch", aria-checked |
+| **ColorPicker** | — | Custom | aria-label, keyboard nav |
+| **NumberInput** | default / error / disabled | WDS / Custom | min/max, step |
+| **Badge** | success / warn / error / info / neutral | WDS | aria-label for icon-only |
+| **Spinner** | sm / md / lg | WDS | aria-busy on parent |
+| **Skeleton** | text / rect / circle | Custom | aria-hidden |
+| **Icon** | varies (Material Symbols) | Custom | aria-hidden (decorative) or aria-label |
+| **Tooltip** | top / bottom / left / right | WDS | role="tooltip", aria-describedby |
+
+### 3.2 Molecules (composed)
+
+| Component | Contains | Source | Notes |
+|-----------|---------|--------|-------|
+| **FormField** | Label + Control + HelpText + Error | Custom | Standard form pattern |
+| **Toast** | Icon + Message + Close | WDS | Auto-dismiss, aria-live |
+| **EmptyState** | Icon/Illustration + Text + CTA | Custom | Call-to-action button |
+| **ErrorState** | Icon + Message + Retry button | Custom | — |
+| **Card** | Header + Body + Actions | Custom | — |
+| **TabBar** | Tab × N | WDS | role="tablist", arrow keys |
+
+### 3.3 Organisms (complex)
+
+| Component | Contains | Source | Notes |
+|-----------|---------|--------|-------|
+| **ConfigPanel** | TabBar + FormFields + SaveButton | Custom | Main settings form |
+| **LivePreview** | PopupTemplate (rendered) | Custom | Updates on config change |
+| **DataTable** | Table + Pagination + EmptyState | Custom | CRUD actions |
+| **ConfirmDialog** | Modal + Message + Confirm/Cancel buttons | WDS | Focus trap |
+
+### 3.4 Patterns (behavioral)
+
+| Pattern | Rule | Components used |
+|---------|------|----------------|
+| **Loading strategy** | Skeleton for initial, spinner for actions | Skeleton, Spinner |
+| **Empty state** | Illustration + text + CTA | EmptyState |
+| **Error recovery** | Message + retry button | ErrorState, Toast |
+| **Destructive confirm** | Modal before delete | ConfirmDialog |
+| **Optimistic update** | Show change → revert on error | Toast (undo) |
+| **Form validation** | Inline on blur + all on submit | FormField (error state) |
+
+---
+
+## 4. Design Tokens
+
+### Spacing
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--space-xs` | 4px | Dense padding |
+| `--space-sm` | 8px | Default gap |
+| `--space-md` | 16px | Section padding |
+| `--space-lg` | 24px | Card padding |
+| `--space-xl` | 32px | Section spacing |
+| `--space-2xl` | 48px | Page margins |
+
+### Typography
+
+| Token | Size | Weight | Use |
+|-------|------|--------|-----|
+| `--text-xs` | 12px | 400 | Captions, help text |
+| `--text-sm` | 14px | 400 | Body, form labels |
+| `--text-md` | 16px | 400 | Default body |
+| `--text-lg` | 18px | 500 | Section headers |
+| `--text-xl` | 24px | 600 | Page headers |
+| `--text-2xl` | 32px | 700 | Title |
+
+### Border Radius
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--radius-sm` | 4px | Inputs, badges |
+| `--radius-md` | 8px | Cards, buttons |
+| `--radius-lg` | 12px | Modals, panels |
+| `--radius-full` | 9999px | Avatars, pills |
+
+### Status Colors
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--color-success` | `#22c55e` | Success states |
+| `--color-warning` | `#f59e0b` | Warnings |
+| `--color-error` | `#ef4444` | Errors |
+| `--color-info` | `#3b82f6` | Info |
+
+### Shadows
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Cards |
+| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Dropdowns |
+| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.15)` | Modals |
+
+---
+
+## 5. Design System Mapping
+
+### Wix Design System (WDS) mapping
+
+| UI Inventory | WDS component | Import | Notes |
+|-------------|--------------|--------|-------|
+| Button | `<Button>` | `@wix/design-system` | Supports priority prop |
+| TextInput | `<Input>` | `@wix/design-system` | — |
+| Switch | `<ToggleSwitch>` | `@wix/design-system` | — |
+| Toast | `Toast` (imperative) | `@wix/design-system` | Use with `<Notification>` |
+| Modal | `<Modal>` + `<MessageModalLayout>` | `@wix/design-system` | — |
+| Tabs | `<Tabs>` | `@wix/design-system` | — |
+| Table | `<Table>` | `@wix/design-system` | — |
+| ColorPicker | — | Custom build | WDS doesn't have one |
+| LivePreview | — | Custom build | App-specific |
+
+---
+
+## 6. Пример: Button Card
+
+```markdown
+### Component: Button
+
+**Category:** Atom
+**Source:** WDS `<Button>` (customized)
+**Used in:** Settings (Save, Reset), Items (Create, Delete)
+
+#### Variants
+| Variant | WDS `priority` | Visual |
+|---------|:-------------:|--------|
+| primary | `primary` | Filled blue (#116DFF) |
+| secondary | `secondary` | Outlined |
+| destructive | N/A (custom) | Filled red (#D32F2F) |
+
+#### States
+| Default | Hover | Loading | Disabled |
+|---------|-------|---------|----------|
+| Normal | Darker bg | Spinner, no text | 50% opacity |
+
+#### A11y: `<button>`, focus-visible, aria-disabled, aria-busy
+```
+
+---
+
+## 7. Output Template
+
+```markdown
+# UI Components Inventory
+
+**Date:** YYYY-MM-DD
+**Author:** UX/UI Designer Agent
+**Design System:** <WDS / shadcn / Custom>
+**UX Spec:** <reference>
+
+## Component Summary
+| Category | Count | Custom | From DS |
+|----------|:-----:|:------:|:-------:|
+| Atoms | 13 | 3 | 10 |
+| Molecules | 6 | 4 | 2 |
+| Organisms | 4 | 4 | 0 |
+| Patterns | 6 | — | — |
+
+## Component Cards
+<section 2 format × N components>
+
+## Design Tokens
+<section 4>
+
+## Design System Mapping
+<section 5>
+```
+
+---
+
+## См. также
+- `$ux_spec` — Screen specs (input for inventory)
+- `$a11y_baseline` — a11y requirements per component
+- `$design_systems` — integration guide for design systems
+- `$design_intake` — analyze design materials

package/.agents/skills/ux_discovery/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: ux_discovery
+description: Уточнить UX вводные по PRD — роли, основные потоки, навигация, платформы (responsive), бренд/референсы, локализация, edge cases.
+---
+
+# Skill: UX Discovery
+
+Собрать недостающий UX контекст перед UX Spec.
+
+**Разделы:**
+1. [Workflow](#1-workflow)
+2. [Question Bank](#2-questions)
+3. [Priority Matrix](#3-priority)
+4. [Assumptions Framework](#4-assumptions)
+5. [Пример](#5-пример)
+6. [Output Template](#6-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Прочитай PRD (из $pm_prd)
+   └── Выдели: цели, user stories, acceptance criteria, constraints
+
+2. Проверь: что уже известно vs что нужно уточнить
+   ├── Известно → отметь как факт
+   └── Неизвестно → добавь в список вопросов
+
+3. Приоритизируй вопросы (section 3):
+   ├── 🔴 Blocking: без ответа нельзя выбрать подход
+   ├── 🟠 Important: влияет на UX Spec, но можно допустить
+   └── 🟡 Nice-to-know: полезно, но не критично
+
+4. Если ответ критичен → задай вопрос пользователю
+   Если можно допустить → зафиксируй допущение + отметь "ASSUMPTION"
+
+5. Сформируй Discovery Report (section 6)
+
+6. Передай в → $ux_spec
+```
+
+### Когда НЕ нужен discovery
+
+| Ситуация | Действие |
+|----------|---------|
+| PRD уже содержит все ответы | Пропустить discovery → сразу $ux_spec |
+| Итерация над существующим UI | Минимальный discovery (только новые вопросы) |
+| Bugfix / hotfix | Не нужен |
+
+---
+
+## 2. Question Bank
+
+### A) Платформа и layout
+
+| # | Вопрос | Зачем |
+|---|--------|-------|
+| Q-01 | Desktop-first, mobile-first или responsive? | Определяет breakpoints и layout strategy |
+| Q-02 | Минимальные поддерживаемые разрешения? | Влияет на grid и responsive rules |
+| Q-03 | Встраивается в iframe или standalone? | Критично для размеров, scrolling, navigation |
+| Q-04 | Есть ли dark mode / theme switching? | Влияет на design tokens и CSS strategy |
+
+### B) Роли и права
+
+| # | Вопрос | Зачем |
+|---|--------|-------|
+| Q-05 | Какие роли пользователей? | Определяет navigation и permissions logic |
+| Q-06 | Что каждая роль может / не может делать? | Влияет на UI visibility и server-side auth |
+| Q-07 | Нужна ли админка / модерация? | Может потребовать отдельный layout |
+| Q-08 | Есть ли onboarding для new users? | Дополнительные экраны/flow |
+
+### C) Навигация и структура
+
+| # | Вопрос | Зачем |
+|---|--------|-------|
+| Q-09 | Основные разделы / tabs / pages? | Определяет IA (Information Architecture) |
+| Q-10 | Есть ли deep linking (URL sharing)? | Влияет на routing strategy |
+| Q-11 | Breadcrumbs / back navigation нужны? | UX navigation pattern |
+| Q-12 | Single page or multi-page? | Routing, state management |
+
+### D) Бренд и визуал
+
+| # | Вопрос | Зачем |
+|---|--------|-------|
+| Q-13 | Есть ли Figma / mockup / дизайн-система? | Определяет «источник правды» по UI |
+| Q-14 | Есть визуальные референсы / вдохновение? | Direction для дизайн-решений |
+| Q-15 | Логотип / фирменные цвета / шрифты? | Brand compliance |
+| Q-16 | Тёмная / светлая тема? | Design tokens scope |
+
+### E) Данные и состояния
+
+| # | Вопрос | Зачем |
+|---|--------|-------|
+| Q-17 | Что показываем при пустых данных? | Empty state design |
+| Q-18 | Какие операции потенциально долгие? | Loading/skeleton strategy |
+| Q-19 | Что делаем при ошибках сети/сервера? | Error state design |
+| Q-20 | Есть ли real-time updates? | WebSocket / polling strategy |
+| Q-21 | Максимальные объёмы данных (списки/таблицы)? | Pagination/virtualization |
+
+### F) Локализация и i18n
+
+| # | Вопрос | Зачем |
+|---|--------|-------|
+| Q-22 | Один язык или несколько? | i18n setup |
+| Q-23 | RTL поддержка? | CSS direction strategy |
+| Q-24 | Формат дат / времени / валют? | Locale-specific formatting |
+
+---
+
+## 3. Priority Matrix
+
+| Priority | Meaning | Action |
+|----------|---------|--------|
+| 🔴 **Blocking** | Без ответа нельзя начать UX Spec | Обязательно спросить пользователя |
+| 🟠 **Important** | Влияет на UX, но можно сделать допущение | Спросить или зафиксировать ASSUMPTION |
+| 🟡 **Nice-to-know** | Полезно для polish, не для MVP | Отложить или допустить |
+
+### Типичная приоритизация
+
+| Категория | Типичный приоритет |
+|-----------|:------------------:|
+| Platform (iframe / responsive) | 🔴 |
+| Roles & permissions | 🔴 |
+| Navigation / IA | 🟠 |
+| Brand / design system | 🟠 |
+| Empty / error states | 🟠 |
+| Localization | 🟡 |
+| Real-time updates | 🟡 |
+
+---
+
+## 4. Assumptions Framework
+
+Когда нет ответа, зафиксируй допущение:
+
+```markdown
+### ASSUMPTION-01: Desktop-first layout
+**Вопрос:** Q-01 — responsive strategy
+**Допущение:** Desktop-first, min-width 1024px
+**Обоснование:** PRD описывает dashboard, типичный use case — десктоп
+**Риск:** Low — легко добавить mobile breakpoints позже
+**Нужно подтвердить:** До v1.0
+```
+
+---
+
+## 5. Пример
+
+```markdown
+# UX Discovery: SaaS Admin Panel
+
+## Факты из PRD
+- Admin dashboard для настройки контента
+- Roles: Admin (полный доступ), Viewer (только чтение)
+- Features: Settings, Content CRUD, Preview
+
+## Уточнено
+- Q-01: Desktop-first, responsive later → 🔴 confirmed
+- Q-13: Дизайн-система — shadcn/ui → 🟠 confirmed
+- Q-17: Empty state — показать "Create your first item" CTA → 🟠 confirmed
+
+## Допущения
+- ASSUMPTION-01: Desktop-first (admin panel = десктоп) → Low risk
+- ASSUMPTION-02: Один язык (english) для MVP → Low risk
+- ASSUMPTION-03: Нет real-time updates (static config) → Low risk
+```
+
+---
+
+## 6. Output Template
+
+```markdown
+# UX Discovery Report
+
+**PRD:** <reference>
+**Date:** YYYY-MM-DD
+**Author:** UX/UI Designer Agent
+
+## Facts (confirmed from PRD)
+| # | Fact | Source |
+|---|------|--------|
+| F-01 | Desktop-first, standalone app | PRD §1 |
+| F-02 | Two roles: Admin, Viewer | PRD §2.1 |
+
+## Questions
+| # | Question | Priority | Answer | Status |
+|---|----------|:--------:|--------|:------:|
+| Q-01 | Responsive or desktop only? | 🔴 | Desktop-first | ✅ Answered |
+| Q-13 | Design system? | 🟠 | shadcn/ui | ✅ Answered |
+| Q-20 | Real-time? | 🟡 | — | ASSUMED: No |
+
+## Assumptions
+| ID | Assumption | Risk | Confirm by |
+|----|-----------|:----:|-----------:|
+| ASSUMPTION-01 | Desktop-first | Low | v1.0 |
+| ASSUMPTION-02 | English only | Low | v1.0 |
+
+## Screen / Flow Inventory (draft)
+1. Admin Panel → Settings (tabs: General, Appearance, Notifications)
+2. Admin Panel → Items list (CRUD)
+3. Public UI → Content display (end-user facing)
+
+## Next Step
+→ Proceed to $ux_spec with confirmed facts + assumptions
+```
+
+---
+
+## См. также
+- `$pm_prd` — PRD (input for discovery)
+- `$ux_spec` — UX Spec (output of discovery)
+- `$design_intake` — design materials analysis