code-ai-installer 3.0.0 → 4.0.1-a

package/domains/development/.agents/skills/design-systems/SKILL.md

@@ -1,16 +1,50 @@
 ---
 name: design-systems
-description: Интеграция дизайн-систем — shadcn/ui, Mantine, Wix Design System. Установка, кастомизация темы, component composition, wrapper pattern, UI inventory, маппинг состояний (loading/error/empty/disabled), responsive, a11y. Активируй при подключении дизайн-системы, создании новых компонентов, или при вопросах «как интегрировать X».
+description: "Интеграция дизайн-систем — shadcn/ui, Mantine, Wix Design System. Установка, кастомизация темы, component composition, wrapper pattern, UI inventory, маппинг состояний (loading/error/empty/disabled), responsive, a11y. Активируй при подключении дизайн-системы, создании новых компонентов, или при вопросах «как интегрировать X»."
+type: discretionary
+domain: development
+owners:
+  - senior_full_stack
+  - ux_ui_designer
+gates:
+  - DEV
+  - UX
+tech: []
+topic:
+  - ux
+  - design-systems
+  - general
+triggers:
+  - подключить дизайн-систему
+  - shadcn/ui
+  - Mantine компоненты
+  - Wix Design System
+  - кастомизация темы
+  - wrapper компонент
+related:
+  - ui-inventory
+  - styling-css-stack
+  - styling-css-stack-reference
+  - ux-spec
+  - a11y-baseline
+  - a11y-baseline-reference
+  - design-parity-review
+  - tailwind-beast-practices
+  - tailwind-beast-practices-reference
+  - react-beast-practices
+budget_lines: 300
+schema_version: 1
 ---
 
+
 # Skill: Design Systems Integration
 
 Конкретные паттерны интеграции дизайн-систем: от выбора до wrapper-компонентов.
 
 **Разделы:**
 1. [Выбор дизайн-системы](#1-выбор-дизайн-системы)
-2. [shadcn/ui: setup и кастомизация](#2-shadcnui)
-3. [Wix Design System (WDS)](#3-wix-design-system)
+2. [shadcn/ui](#2-shadcnui)
+3. [Wix Design System](#3-wix-design-system)
 4. [Mantine](#4-mantine)
 5. [Wrapper Pattern](#5-wrapper-pattern)
 6. [UI Inventory](#6-ui-inventory)
@@ -24,15 +58,18 @@ description: Интеграция дизайн-систем — shadcn/ui, Manti
 | Критерий | shadcn/ui | Mantine | WDS |
 |---------|-----------|---------|-----|
 | **Стек** | React + Tailwind + Radix | React | React + Wix |
-| **Кастомизация** | Полная (copy-paste) | Через theme | Через CSS overrides |
-| **Bundle size** | Минимальный (no dep) | ~50KB | Включён в Wix |
+| **Кастомизация** | Copy-paste (полная) | Через theme | CSS overrides |
+| **Bundle** | Минимальный | ~50KB | В Wix |
 | **a11y** | Radix (excellent) | Good | Good |
-| **Dark mode** | CSS variables | Built-in theme | Ограничен |
-| **Когда** | Новые SPA, нужен полный контроль | SPA с rich UI | Wix экосистема |
-| **Когда НЕ** | Нет Tailwind в проекте | Нужен minimal bundle | Вне Wix |
+| **Dark mode** | CSS variables | Built-in | Ограничен |
 
 > [!TIP]
-> **Простое правило:** Wix-проект → WDS. Новый SPA с Tailwind → shadcn/ui. Нужно много ready-made компонентов → Mantine.
+> Wix → WDS. SPA + Tailwind → shadcn/ui. Много ready-made компонентов → Mantine.
+
+**Migration triage:**
+- Greenfield → DDS по таблице.
+- Existing с собственной UI-библиотекой → wrap (см. §5), мигрируй модульно (1 экран = 1 PR).
+- Legacy с inline-стилями → сначала tokens (`styling-css-stack`), потом DDS.
 
 ---
 
@@ -41,68 +78,40 @@ description: Интеграция дизайн-систем — shadcn/ui, Manti
 ### Setup
 
 ```bash
-# Инициализация (Vite + React + Tailwind)
 npx shadcn@latest init
-
-# Добавление компонентов (copy-paste, не dependency)
 npx shadcn@latest add button dialog input toast
 ```
 
-### ✅ DO: кастомизация через CSS variables
+> [!NOTE]
+> shadcn = copy-paste, не dependency. Pin commit/version в README — иначе drift между `init` и follow-up `add`.
+
+### CSS variables (essentials)
 
 ```css
-/* globals.css — переопределение темы shadcn/ui */
+/* globals.css */
 @layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
-    --primary: 220 90% 56%;
-    --primary-foreground: 210 40% 98%;
-    --secondary: 280 70% 50%;
-    --muted: 210 40% 96%;
-    --muted-foreground: 215.4 16.3% 46.9%;
-    --accent: 210 40% 96%;
-    --border: 214.3 31.8% 91.4%;
-    --radius: 0.5rem;
-  }
-
-  .dark {
-    --background: 222.2 84% 4.9%;
-    --foreground: 210 40% 98%;
-    --primary: 220 90% 65%;
-    /* ... */
-  }
+  :root { --background: 0 0% 100%; --primary: 220 90% 56%; --radius: 0.5rem; }
+  .dark { --background: 222.2 84% 4.9%; --foreground: 210 40% 98%; }
 }
 ```
 
-### ✅ DO: composition с shadcn/ui
+> Полная token-стратегия (naming, dark switching, system-preference detect) — `styling-css-stack`.
+
+### Composition
 
 ```jsx
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
 
-/**
- * Форма создания купона в модальном окне.
- * @param {{ onSubmit: (code: string) => void }} props
- */
 function CreateCouponDialog({ onSubmit }) {
   const [code, setCode] = useState('');
-
   return (
     <Dialog>
-      <DialogTrigger asChild>
-        <Button>New Coupon</Button>
-      </DialogTrigger>
+      <DialogTrigger asChild><Button>New Coupon</Button></DialogTrigger>
       <DialogContent>
-        <DialogHeader>
-          <DialogTitle>Create Coupon</DialogTitle>
-        </DialogHeader>
-        <Input
-          placeholder="Coupon code"
-          value={code}
-          onChange={(e) => setCode(e.target.value)}
-        />
+        <DialogHeader><DialogTitle>Create Coupon</DialogTitle></DialogHeader>
+        <Input placeholder="Coupon code" value={code} onChange={(e) => setCode(e.target.value)} />
         <Button onClick={() => onSubmit(code)}>Create</Button>
       </DialogContent>
     </Dialog>
@@ -110,167 +119,68 @@ function CreateCouponDialog({ onSubmit }) {
 }
 ```
 
-### Структура файлов
-
-```
-src/
-├── components/
-│   ├── ui/                    # shadcn/ui компоненты (auto-generated)
-│   │   ├── button.jsx
-│   │   ├── dialog.jsx
-│   │   └── input.jsx
-│   └── domain/                # Бизнес-компоненты (composition)
-│       ├── CouponCard.jsx
-│       └── CreateCouponDialog.jsx
-├── lib/
-│   └── utils.js               # cn() helper (clsx + tailwind-merge)
-└── components.json            # shadcn/ui config
-```
+Структура: `src/components/ui/` (shadcn auto-generated) + `src/components/domain/` (composition) + `src/lib/utils.js` (`cn()`) + `components.json` (config).
 
 ---
 
 ## 3. Wix Design System
 
-### ✅ DO: использовать WDS-компоненты вместо кастомных
+### Composition (WDS)
 
 ```jsx
-import {
-  Card,
-  Text,
-  Button,
-  Input,
-  Loader,
-  EmptyState,
-  FormField,
-  ToggleSwitch,
-  ColorInput,
-  Tooltip,
-  Badge,
-} from '@wix/design-system';
+import { Card, Button, Badge } from '@wix/design-system';
 
-/**
- * Карточка купона на WDS.
- * @param {{ coupon: Coupon, onDelete: (id: string) => void }} props
- */
 function CouponCard({ coupon, onDelete }) {
   return (
     <Card>
       <Card.Header
         title={coupon.code}
         subtitle={`${coupon.discount}% discount`}
-        suffix={
-          <Badge skin={coupon.active ? 'success' : 'neutral'}>
-            {coupon.active ? 'Active' : 'Inactive'}
-          </Badge>
-        }
+        suffix={<Badge skin={coupon.active ? 'success' : 'neutral'}>{coupon.active ? 'Active' : 'Inactive'}</Badge>}
       />
-      <Card.Divider />
-      <Card.Content>
-        <Text size="small" secondary>
-          Used {coupon.usageCount} times
-        </Text>
-      </Card.Content>
-      <Card.Divider />
       <Card.Content>
-        <Button
-          size="small"
-          skin="destructive"
-          onClick={() => onDelete(coupon.id)}
-        >
-          Delete
-        </Button>
+        <Button size="small" skin="destructive" onClick={() => onDelete(coupon.id)}>Delete</Button>
       </Card.Content>
     </Card>
   );
 }
 ```
 
-### ✅ DO: WDS FormField для форм
-
-```jsx
-function CouponForm({ onSave }) {
-  const [code, setCode] = useState('');
-  const [discount, setDiscount] = useState('');
-
-  return (
-    <form onSubmit={() => onSave({ code, discount: Number(discount) })}>
-      <FormField label="Coupon Code" required>
-        <Input value={code} onChange={(e) => setCode(e.target.value)} />
-      </FormField>
-
-      <FormField label="Discount (%)" required>
-        <Input
-          type="number"
-          min={1}
-          max={100}
-          value={discount}
-          onChange={(e) => setDiscount(e.target.value)}
-        />
-      </FormField>
-
-      <Button type="submit">Save</Button>
-    </form>
-  );
-}
-```
-
-### WDS Component Mapping (частые компоненты)
+### WDS Component Mapping
 
 | UI задача | WDS компонент | Props |
-|-----------|-------------|-------|
-| Кнопка | `Button` | `skin`, `size`, `priority`, `disabled` |
-| Ввод текста | `Input` | `status`, `statusMessage`, `prefix`, `suffix` |
-| Формы | `FormField` + `Input` | `label`, `required`, `infoContent` |
-| Карточка | `Card` + subcomponents | `Card.Header`, `Card.Content`, `Card.Divider` |
-| Таблица | `Table` | columns, data, onRowClick |
+|-----------|---------------|-------|
+| Кнопка | `Button` | `skin`, `size`, `priority` |
+| Ввод | `Input` | `status`, `statusMessage`, `prefix`, `suffix` |
+| Форма | `FormField` + `Input` | `label`, `required`, `infoContent` |
+| Карточка | `Card` (+ `Header/Content/Divider`) | composition |
+| Таблица | `Table` | `columns`, `data`, `onRowClick` |
 | Модалка | `Modal` / `MessageBoxFunctionalLayout` | `title`, `primaryButtonText` |
-| Пустое состояние | `EmptyState` | `title`, `subtitle`, `image` |
+| Empty | `EmptyState` | `title`, `subtitle`, `image` |
 | Лоадер | `Loader` | `size`, `text` |
-| Тоггл | `ToggleSwitch` | `checked`, `onChange`, `size` |
-| Цвет | `ColorInput` | `value`, `onChange` |
-| Тултип | `Tooltip` | `content`, `placement` |
-| Бейдж | `Badge` | `skin`, `size`, `type` |
+| Тоггл | `ToggleSwitch` | `checked`, `onChange` |
+| Цвет / Тултип / Бейдж | `ColorInput` / `Tooltip` / `Badge` | см. WDS docs |
 
 ---
 
 ## 4. Mantine
 
-### Setup
-
 ```bash
 npm install @mantine/core @mantine/hooks @mantine/form
 ```
 
-### ✅ DO: Mantine theme
-
 ```jsx
-// theme.js
-import { createTheme } from '@mantine/core';
+import { createTheme, MantineProvider } from '@mantine/core';
 
-export const theme = createTheme({
+const theme = createTheme({
   primaryColor: 'blue',
   fontFamily: 'Inter, sans-serif',
   radius: { sm: '4px', md: '8px', lg: '12px' },
-  components: {
-    Button: {
-      defaultProps: { radius: 'md' },
-    },
-    Input: {
-      defaultProps: { radius: 'md' },
-    },
-  },
+  components: { Button: { defaultProps: { radius: 'md' } }, Input: { defaultProps: { radius: 'md' } } },
 });
 
-// App.jsx
-import { MantineProvider } from '@mantine/core';
-import { theme } from './theme';
-
-function App() {
-  return (
-    <MantineProvider theme={theme}>
-      <MyApp />
-    </MantineProvider>
-  );
+export default function App() {
+  return <MantineProvider theme={theme}><MyApp /></MantineProvider>;
 }
 ```
 
@@ -278,109 +188,62 @@ function App() {
 
 ## 5. Wrapper Pattern
 
-### ✅ DO: обёртки над библиотечными компонентами
+### DO: проектная обёртка над DDS
 
 ```jsx
-// components/AppButton.jsx
+// components/AppButton.jsx — замена DDS правится в одном файле, а не в 50.
 import { Button as WDSButton } from '@wix/design-system';
 
-/**
- * Обёртка над WDS Button с проектными дефолтами.
- * Позволяет заменить WDS на другую систему без правок всего кода.
- * @param {Object} props - WDS Button props.
- * @param {React.ReactNode} props.children - Текст кнопки.
- * @param {'primary' | 'secondary' | 'destructive'} [props.variant='primary']
- */
+/** @param {{ variant?: 'primary'|'secondary'|'destructive', children: React.ReactNode }} props */
 export function AppButton({ variant = 'primary', children, ...rest }) {
-  const skinMap = {
-    primary: 'standard',
-    secondary: 'light',
-    destructive: 'destructive',
-  };
-
-  return (
-    <WDSButton skin={skinMap[variant]} {...rest}>
-      {children}
-    </WDSButton>
-  );
+  const skinMap = { primary: 'standard', secondary: 'light', destructive: 'destructive' };
+  return <WDSButton skin={skinMap[variant]} {...rest}>{children}</WDSButton>;
 }
 ```
 
-### Зачем wrapper?
+### Когда оборачивать
 
 | Причина | Объяснение |
 |---------|------------|
-| **Миграция** | Замена WDS → shadcn/ui в одном файле, а не в 50 |
-| **Единообразие** | Проектные дефолты (size, skin) в одном месте |
-| **API упрощение** | Скрыть ненужные props от domain-компонентов |
-| **Тестируемость** | Mock одного wrapper, а не всей DDS |
+| Миграция | Замена WDS → shadcn/ui в одном файле |
+| Единообразие | Проектные дефолты (size, skin) в одном месте |
+| API упрощение | Скрыть лишние props от domain-кода |
+| Тестируемость | Mock одного wrapper, а не всей DDS |
+
+### Когда НЕ оборачивать
+- Компонент используется в 1–2 местах (overhead > польза).
+- Wrapper дублирует 80%+ props (стал прозрачным — бесполезен).
+- Композиционный компонент (`Card.Header/Content/Divider`) — оборачивай корень, не subcomponents.
 
 > [!WARNING]
-> Wrapper ≠ копировать 100% API библиотеки. Wrapper — тонкая прослойка с проектными дефолтами. Если wrapper дублирует 80%+ props — он бесполезен.
+> Wrapper — тонкая прослойка, не копия. Растёт > 30 строк → это уже domain-компонент, переименуй.
 
 ---
 
 ## 6. UI Inventory
 
-### ✅ DO: таблица всех используемых компонентов
-
-```markdown
-# UI Inventory
-
-| Компонент | DDS Source | Варианты | Используется в |
-|-----------|-----------|---------|----------------|
-| Button | WDS `Button` | primary, secondary, destructive, icon-only | Все формы, toolbar |
-| Input | WDS `Input` | text, number, search, password | Формы |
-| Card | WDS `Card` | with header, with divider | Coupons, Templates |
-| EmptyState | WDS `EmptyState` | with image, with action | Lists |
-| Loader | WDS `Loader` | inline, fullscreen | Async operations |
-| ColorPicker | WDS `ColorInput` | single color | Widget config |
-| Modal | WDS `Modal` | confirm, form | Delete confirm, create |
-| Badge | WDS `Badge` | success, warning, neutral | Status indicators |
-| Table | Custom (WDS) | sortable, selectable | Coupons list |
-| Toast | WDS `Notification` | success, error, info | After actions |
-```
+Каталог используемых компонентов с variants / states / a11y notes — отдельный артефакт.
 
-> [!TIP]
-> UI Inventory создаётся на UX gate и обновляется на DEV gate. Каждый новый компонент → сначала добавить в inventory.
+→ Полный шаблон, methodology и output-формат: **`ui-inventory`**.
+
+**Когда:** создаётся на **UX gate** (по `ux-spec`), обновляется на **DEV gate** при добавлении нового компонента.
 
 ---
 
 ## 7. Состояния компонентов
 
-### ✅ DO: каждый компонент поддерживает 5 состояний
+### DO: каждый интерактивный компонент поддерживает 5 состояний
 
 ```jsx
 /**
- * Универсальный список с поддержкой всех состояний.
- * @param {Object} props
- * @param {any[]} props.items - данные.
- * @param {boolean} props.isLoading - загрузка.
- * @param {string|null} props.error - ошибка.
- * @param {(item: any) => JSX.Element} props.renderItem - рендер элемента.
- * @param {{ title: string, action?: JSX.Element }} props.emptyState - empty state config.
+ * @param {{ items: any[], isLoading: boolean, error: string|null, renderItem: (i: any) => JSX.Element, emptyState: { title: string, action?: JSX.Element }, onRetry?: () => void }} props
  */
-function DataList({ items, isLoading, error, renderItem, emptyState }) {
-  // Loading
+function DataList({ items, isLoading, error, renderItem, emptyState, onRetry }) {
   if (isLoading) return <Loader size="medium" />;
-
-  // Error
   if (error) return <ErrorState message={error} onRetry={onRetry} />;
-
-  // Empty
   if (!items?.length) {
-    return (
-      <EmptyState
-        title={emptyState.title}
-        subtitle="Try adjusting your filters"
-        image={<EmptyStateImage />}
-      >
-        {emptyState.action}
-      </EmptyState>
-    );
+    return <EmptyState title={emptyState.title} subtitle="Try adjusting your filters">{emptyState.action}</EmptyState>;
   }
-
-  // Data (happy path)
   return <ul>{items.map(renderItem)}</ul>;
 }
 ```
@@ -388,13 +251,15 @@ function DataList({ items, isLoading, error, renderItem, emptyState }) {
 ### Чеклист состояний
 
 | Состояние | Обязательно? | Что показывать |
-|-----------|-------------|---------------|
-| **Loading** | ✅ Always | Skeleton / Spinner / Progress |
-| **Error** | ✅ Always | Сообщение + Retry action |
-| **Empty** | ✅ Always | Illustration + Message + Action |
-| **Data** | ✅ Always | Основной контент |
-| **Disabled** | ⚠️ If interactive | Визуальная индикация + курсор |
-| **Partial error** | ⚠️ If applicable | Inline error на отдельных элементах |
+|-----------|--------------|----------------|
+| **Loading** | ✅ | Skeleton / Spinner |
+| **Error** | ✅ | Сообщение + Retry |
+| **Empty** | ✅ | Illustration + Message + Action |
+| **Data** | ✅ | Основной контент |
+| **Disabled** | ⚠️ если интерактивный | Визуальный stub + cursor |
+| **Partial error** | ⚠️ если применимо | Inline error на элементах |
+
+> Контракт состояний per-screen задаётся в `ux-spec` (state-matrix). Здесь — реализация.
 
 ---
 
@@ -402,31 +267,31 @@ function DataList({ items, isLoading, error, renderItem, emptyState }) {
 
 | ❌ Anti-pattern | ✅ Решение |
 |----------------|-----------|
-| Смешивать несколько DDS в проекте | Одна DDS + wrappers |
-| Кастомная кнопка рядом с DDS Button | Использовать DDS, кастомизировать через theme |
-| Override DDS стилей через `!important` | Wrapper + props + CSS variables |
-| Нет empty/loading/error state | Чеклист 5 состояний для каждого компонента |
-| DDS-компоненты напрямую в domain-коде | Wrapper pattern для portability |
-| «Свой DatePicker» когда есть в DDS | Всегда проверять DDS каталог сначала |
-| Стилизация через className override | Props-first (skin, variant, size) |
+| Смешивать несколько DDS | Одна DDS + wrappers |
+| Кастомная кнопка рядом с DDS Button | DDS + theme customization |
+| Override через `!important` | Wrapper + props + CSS variables |
+| Нет empty/loading/error | Чеклист 5 состояний |
+| DDS напрямую в domain-коде | Wrapper pattern |
 
 ---
 
-## Definition of Done (интеграция DDS)
+## Definition of Done
 
-- [ ] DDS выбрана и обоснована
-- [ ] Theme/tokens кастомизированы
-- [ ] UI Inventory создан
+- [ ] DDS выбрана и обоснована (см. §1)
+- [ ] Theme/tokens кастомизированы (`styling-css-stack` для doctrine)
+- [ ] UI Inventory создан (`ui-inventory`)
 - [ ] Wrappers для ключевых компонентов
-- [ ] Все компоненты поддерживают loading/error/empty/disabled
-- [ ] Dark mode (если требуется)
-- [ ] a11y: focus management, screen reader labels
+- [ ] Все интерактивные компоненты: loading/error/empty/disabled
+- [ ] Dark mode (если требуется) — `prefers-color-scheme`
+- [ ] a11y: focus + screen reader labels (`a11y-baseline`)
 
 ---
 
 ## См. также
-- `$ui-inventory` — полный формат UI inventory
-- `$styling-css-stack` — CSS токены и naming
-- `$ux-spec` — UX спецификация (определяет состояния)
-- `$a11y-baseline` — accessibility чеклист
-- `$design-parity-review` — сравнение реализации с дизайном
+- `ui-inventory` — формат и methodology UI инвентаря
+- `styling-css-stack` — CSS токены, naming, dark mode
+- `ux-spec` — UX спецификация (state-matrix контракт)
+- `a11y-baseline` — accessibility чеклист
+- `design-parity-review` — сравнение реализации с дизайном
+- `tailwind-beast-practices` → utility-first styling + cva variant patterns
+- `react-beast-practices` → компонентные паттерны (composition, wrapper-стиль)

package/domains/development/.agents/skills/design-systems/agents/kimi.yaml

@@ -1,14 +1,14 @@
-name: "design-systems"
-display_name: "Интеграция дизайн-системы"
-description: "Интеграция дизайн-систем — shadcn/ui, Mantine, Wix Design System. Установка, кастомизация темы, component composition, wrapper pattern, UI inventory, маппинг состояний (loading/error/empty/disabled), responsive, a11y. Активируй при подключении дизайн-системы, создании новых компонентов, или при вопросах «как интегрировать X»."
-default_prompt: "Используй $design-systems, когда задача относится к навыку \"Интеграция дизайн-системы\"."
-triggers:
-  - "design-systems"
-  - "design systems"
-  - "Интеграция дизайн-системы"
-  - "Интеграция дизайн-систем — shadcn/ui, Mantine, Wix Design System"
-capabilities:
-  - "design"
-  - "systems"
-tools: []
-implicit_invocation: true
+name: "design-systems"
+display_name: "Интеграция дизайн-системы"
+description: "Интеграция дизайн-систем — shadcn/ui, Mantine, Wix Design System. Установка, кастомизация темы, component composition, wrapper pattern, UI inventory, маппинг состояний (loading/error/empty/disabled), responsive, a11y. Активируй при подключении дизайн-системы, создании новых компонентов, или при вопросах «как интегрировать X»."
+default_prompt: "Используй $design-systems, когда задача относится к навыку \"Интеграция дизайн-системы\"."
+triggers:
+  - "design-systems"
+  - "design systems"
+  - "Интеграция дизайн-системы"
+  - "Интеграция дизайн-систем — shadcn/ui, Mantine, Wix Design System"
+capabilities:
+  - "design"
+  - "systems"
+tools: []
+implicit_invocation: true