# SKILL: Watchover Design System — як користуватись > **Для агентів (Claude Code / design agents).** Операційні інструкції: коли і як > регенерувати систему, як створити новий екран, як додати компонент. > Перед будь-якою роботою прочитай: > 1. [readme.md](readme.md) — бренд, токени, тон голосу, правила компонентів > 2. [DESIGN-SYSTEM-OVERVIEW.md](DESIGN-SYSTEM-OVERVIEW.md) — контракт: структура, > 47 компонентів у 8 групах, мапінг на екрани прототипу --- ## Ролі файлів | Файл | Роль | |---|---| | `generator-prompt.md` | **Промпт-генератор** — вхід для design-агента при повній (ре)генерації (колишній design.md з кореня) | | `DESIGN-SYSTEM-OVERVIEW.md` | **Контракт компонентів** — що система МАЄ містити; чекліст приймання після генерації | | `readme.md` | **Гайд** — правила, за якими все будується і перевіряється | | `SKILL.md` (цей файл) | **Процеси** — workflow A/B/C/D/E | | `styles.css`, `base.css`, `components/`, `cards/`, `ui_kits/` | **Спільний пакет** — артефакти, які споживають прототипи; тем не знають | | `themes//` | **Теми** — стилістика (кольори, шрифти, радіуси, тіні); компоненти спільні для всіх тем | | `themes/active.css` | **Перемикач** — один рядок, який визначає активну тему для всього, що лінкує `styles.css` | | `themes/THEME-CONTRACT.md` | **Контракт теми** — токени, які мусить визначити кожна тема | | `themes/theme-generator-prompt.md` | **Промпт-шаблон** генерації теми-кандидата | | `themes/compare.html` | **Порівняння** — side-by-side прев'ю кандидатів на реальних екранах | **Принцип розшарування:** компоненти споживають ТІЛЬКИ семантичні аліаси з THEME-CONTRACT; сирі рампи (`--stone-300`, `--gold-500`…) — внутрішня кухня теми. Саме це дозволяє генерувати N тем і обирати, не торкаючись компонентів. --- ## Workflow A — Повна (ре)генерація системи **Коли:** системи ще немає в репо; кардинальна зміна бренд-напрямку; перехід на нову ітерацію прототипу як сировину. 1. **Підготуй промпт.** Відкрий `generator-prompt.md`. Прибери службові рядки `…` на початку (prompt injection — перевизначає title/дату). За потреби онови: опис продукту, design direction, перелік компонентів у секції DELIVER — він має відповідати актуальному контракту (8 груп / 47 компонентів з OVERVIEW). 2. **Дай сировину.** Генератор реплікує layout/флоу з актуального прототипу (зараз `artifacts/demo/prototype-r2_v4/`) і «перевдягає» його в бренд-токени. Компроміс зафіксований у [pipeline.md](../../wiki/pipeline.md) рівень 8: реплікувати структуру екранів, НЕ їхній YouTube-look. 3. **Запусти генерацію** в design-середовищі (claude.ai design project з компілятором). Вимоги компілятора — в самому промпті: `styles.css` у корені (тільки `@import`), компоненти discoverable за вмістом файлів. 4. **Склади результат у `artifacts/design-system/`**: `styles.css`, `base.css`, `themes/<назва>/` (токени — за THEME-CONTRACT), `assets/`, `cards/`, `components/`, `ui_kits/`. Згенеровані `_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json` не редагуються вручну. 5. **Прийми за контрактом.** Пройди чекліст по OVERVIEW: - [ ] усі токени присутні, семантичні аліаси працюють (`--brand`, `--play`, `--surface-card`) - [ ] кожен компонент з таблиць (або свідомо відкладений — познач ✦ у таблиці) - [ ] кожна група має `*.card.html` - [ ] parent/child режими виражені варіантами, не окремими компонентами - [ ] шрифти Bricolage Grotesque + Hanken Grotesk (НЕ Roboto/Inter) 6. **Онови документацію:** у OVERVIEW зніми ✦ з реалізованих компонентів; задай розбіжності як «⚠️ Діра» в pipeline.md, якщо контракт не виконано. --- ## Workflow B — Створити новий екран **Коли:** нова ітерація прототипу, новий флоу, новий стан існуючого екрана. 0. **Підтверди тему (ОБОВ'ЯЗКОВО перед генерацією).** Перевір `themes/active.css` — яка тема зараз активна. Запитай у користувача: «Яку тему використовуємо для цієї ітерації? Зараз активна `<назва>`. Доступні: `pine-coral`, `violet-sun` (або інша з `themes/`).» Не починай генерацію до підтвердження. - Якщо тема відповідає активній — лінкуй `styles.css` (єдина точка входу). - Якщо обрана інша тема — лінкуй `themes//theme.css` + всі компоненти окремо (або створи `-entry.css` за прикладом `dark.css` в prototype-r3-dark/). - Ніколи не пиши custom `:root {}` override поверх `styles.css` замість наявної теми. 1. **Прочитай правила** в [readme.md](readme.md) (розділи 2–4: voice, visual foundations, iconography) — особливо різницю parent/child режимів. 2. **Підключи токени:** лінкуй `styles.css` (єдина точка входу). Жодних хардкоджених кольорів/розмірів — тільки семантичні токени. 3. **Знайди компоненти.** Для кожного UI-патерна екрана знайди компонент у таблицях OVERVIEW (колонка «Екрани» підказує аналоги). Композиція екрана = тільки компоненти системи + layout-примітиви. 4. **Бракує патерна?** → СПОЧАТКУ Workflow C (додай компонент у систему), ПОТІМ використай на екрані. Не форкай стилі всередині екрана. 5. **Дотримуйся інваріантів:** no dark patterns (без autoplay/infinite-scroll пасток у child mode), WCAG AA, tap targets ≥44px, sentence case, единий токен-баланс у commerce-елементах. 6. **Куди класти:** екрани прототипу — `artifacts/demo/prototype-rN/` (нова ітерація = нова папка); еталонні екрани системи — `ui_kits/watchover-app/`. --- ## Workflow C — Додати новий компонент **Коли:** на екрані потрібен патерн, якого немає в системі. 1. **Перевір, чи це не варіант існуючого.** Нова кнопка ≠ новий компонент; parent/child відмінність = варіант. Новий компонент — лише якщо інша анатомія. 2. **Створи 4 файли** в потрібній групі `components//`: - `.jsx` — реалізація (named-експорт, семантичні токени) - `.d.ts` — контракт пропсів + правила + «starting point» - `.prompt.md` — «що і коли» + приклад використання - додай демо в `.card.html` групи 3. **Онови документацію (обов'язково, в одному коміті з компонентом):** - таблицю групи в `DESIGN-SYSTEM-OVERVIEW.md` (анатомія, варіанти, екрани) - manifest у `readme.md` розділ 5 4. **Назви групу правильно:** core (контроли) · forms (вибір/профілі) · trust (AI-довіра) · media (відео/канали) · navigation · commerce · overlays (шари/фідбек) · layout (списки/каркас). --- ## Workflow D — Згенерувати тему-кандидата **Коли:** хочемо спробувати альтернативну стилістику, НЕ міняючи поточний дизайн і не форкаючи компоненти. 1. **Заповни DIRECTION** у [themes/theme-generator-prompt.md](themes/theme-generator-prompt.md) (назва, характер, кольоровий світ, type voice, shape & depth). 2. **Запусти генерацію** в design-середовищі з контекстом: `themes/THEME-CONTRACT.md` + `themes/pine-coral/` як еталон формату. 3. **Склади результат у `themes//`** — рівно 5 файлів (`theme.css`, `fonts.css`, `colors.css`, `typography.css`, `spacing.css`). Нові woff2 — у `assets/fonts/`. Компоненти НЕ чіпати. 4. **Перевір контракт:** `comm`-чек з THEME-CONTRACT § «Перевірка теми» має повернути порожньо. 5. **Додай тему в масив `THEMES`** у [themes/compare.html](themes/compare.html). 6. **Лог:** запис у `wiki/log.md` (тема-кандидат, від якого DIRECTION). Кандидатів може бути скільки завгодно — вони живуть поруч і нічого не ламають, бо активна тема визначається тільки `themes/active.css`. --- ## Workflow E — Порівняти кандидатів і промоутнути тему **Коли:** кандидати готові, треба обрати один і рухатись з ним. 1. **Підніми статику** (`npx serve artifacts/design-system` або `vercel dev`) і відкрий `themes/compare.html` — side-by-side всі теми на app-екранах, brand modes, семантичних кольорах, type scale, радіусах, тінях. 2. **Перевір продуктові інваріанти** фіналістів: AA-пари з THEME-CONTRACT, спокійні score-кольори, один `--coin`. 3. **Промоутни:** заміни один рядок `@import` у `themes/active.css` на обрану тему. Все, що лінкує `styles.css` (галерея, cards, ui_kits, прототипи), перемикається автоматично. 4. **Приберись:** відхилені кандидати видали або перенеси в `themes/_archive/` — у компонентах слідів нема, бо їх там і не було. 5. **Зафіксуй рішення:** `wiki/decisions/YYYY-MM-DD-theme-.md` (чому обрали, чим пожертвували) + запис у `wiki/log.md`. Якщо тема міняє бренд-напрямок — онови розділ 2–3 у `readme.md`. --- ## Анти-патерни - ❌ Починати екран або ітерацію прототипу без підтвердження активної теми — завжди перевіряй `themes/active.css` і питай користувача - ❌ Писати custom `:root {}` override поверх `styles.css` замість наявної теми — якщо потрібна інша тема, вона вже є в `themes/` або треба зробити Workflow D - ❌ Стилі/кольори всередині екрана повз токени - ❌ Сирі рампи (`--stone-300`, `--gold-500`…) у компонентах — тільки семантичні аліаси з THEME-CONTRACT - ❌ Правити `themes/pine-coral/` під нову стилістику — нова стилістика = нова тема (Workflow D) - ❌ Форк компонентів під тему — якщо темі «потрібен інший компонент», це не тема, це Workflow A - ❌ Екран з one-off CSS-патерном замість компонента (спершу C, потім B) - ❌ Окремі «parent» і «child» компоненти-близнюки замість варіантів - ❌ Редагування `_ds_bundle.js` / `_ds_manifest.json` руками - ❌ Два лічильники валюти (тільки єдиний токен-баланс) - ❌ Roboto/Inter, неонові кольори, чисто чорні тіні