# Watchover Design System — структура та перелік файлів

Цей документ описує склад дизайн-системи Watchover: усі елементи,
структуру папок, перелік файлів та їхнє призначення.

> **Watchover** — шар довіри для дитячого відео. Батьки формують «білий список»
> схвалених каналів (YouTube / TikTok / Instagram), а AI перевіряє нові канали та
> підбирає безпечний контент. Один телефон на сім'ю: дитина тримає його в
> безпечній стрічці, батько розблоковує режим керування за PIN-кодом.

---

## 🎨 Елементи системи

### Токени (122 CSS-змінні)
- **Колір**
  - `Stone` — тепла нейтральна основа (кремове полотно `--paper`, а не білий; теплий майже-чорний `--ink`)
  - `Pine` — бренд / довіра (`--brand`), батьківський режим
  - `Coral` — play / відео (`--play`), нащадок YouTube-червоного
  - `Marigold` + `Sky` — акценти дитячого режиму
  - `Score`-кольори — `safe` / `caution` / `flag` (спокійні, не неонові)
- **Типографіка** — Bricolage Grotesque (заголовки, цифри, логотип) + Hanken Grotesk (UI і текст); шкала display 40 → micro 12
- **Простір** — сітка 4px, драбина радіусів (8 → pill), драбина тіней (теплі коричневі, не чорні), motion-токени (easing + тривалості)

### Компоненти (47, у 8 групах)

> Повний цільовий склад, виведений з інвентаризації прототипу `artifacts/demo/prototype-r2_v4/`
> (25 екранів) + дельти R4-спеки. **Усі 47 компонентів реалізовані (2026-06-12):**
> кожен має `<Name>.jsx` + `<Name>.d.ts` + `<Name>.prompt.md`, кожна група — `<group>.css`
> і `<group>.card.html`.

| Група | Компоненти |
|---|---|
| `core/` | Button · IconButton · Badge · Tag · Avatar · Switch · Input · SearchField · PinInput · ProgressSteps |
| `forms/` | OptionCard · KidCard · ProfileChip · AddCard |
| `trust/` | AICheckScore (підписний: оцінка + вердикт + докази) · ScoreRing · EvidenceRow · ProcessLog · Mascot |
| `media/` | VideoCard · ChannelCard (картка каналу — головний об'єкт «білого списку») · ChannelHero · VideoPlayer · VideoRow |
| `navigation/` | BottomNav · AppHeader (режими parent / child) · ModePill · TokenBalance · Subtabs |
| `commerce/` | PlanCard · TokenPackRow · CoinMedallion · CreditCost · GuaranteeBox · BeforeAfterGrid · FeaturePillar · ReviewCard · FAQItem |
| `overlays/` | BottomSheet · Toast · EmptyState · SearchOverlay |
| `layout/` | SectionHeader · SettingsRow · SwipeRow · RequestRow · StickyFooter |

### UI-кіт
`watchover-app` — інтерактивний «сімейний телефон»: дитяча стрічка → перегляд →
розблокування PIN → батьківський режим → черга перевірки → деталі каналу.

### Картки специфікацій (24)
Colors (6) · Type (4) · Spacing (3) · Brand (2) · Components (8 — по одній на групу) · Watchover App (1).

---

## 📁 Структура папок

```
Watchover Design System/
│
├── styles.css              ← єдина точка входу (лише @import), консьюмери лінкують її
├── index.html              ← локальна галерея всіх карток (заміна вкладки Design System)
├── readme.md               ← повний гайд: контекст, тон голосу, візуальні основи, іконографія, маніфест
├── SKILL.md                ← вхід для Claude Code / Agent Skills
│
├── base.css                ← дефолти елементів, reduced-motion (поза темами)
│
├── themes/                 ← стилістика; компоненти спільні для всіх тем
│   ├── active.css          • перемикач активної теми (один @import)
│   ├── THEME-CONTRACT.md   • токени, які мусить визначити кожна тема
│   ├── theme-generator-prompt.md  • шаблон генерації теми-кандидата
│   ├── compare.html        • side-by-side прев'ю кандидатів
│   └── pine-coral/         ← поточна тема
│       ├── theme.css       • маніфест теми (@import 4 файлів нижче)
│       ├── colors.css      • кольорові рампи + семантичні аліаси
│       ├── typography.css  • шкала розмірів, ваги, трекінг
│       ├── spacing.css     • відступи, радіуси, тіні, motion
│       └── fonts.css       • @font-face (Bricolage + Hanken)
│
├── assets/logo/            ← бренд-знак (щит-захист × кораловий play-трикутник)
│   ├── watchover-mark.svg          • на кремовому / білому
│   └── watchover-mark-light.svg    • на pine / фото
│
├── cards/                  ← картки-специмени для вкладки Design System
│   ├── colors-*.html       • stone, pine, coral, child, scores, semantic
│   ├── type-*.html         • display, scale, body, detail
│   ├── spacing-scale.html, radii.html, shadows.html
│   ├── brand-modes.html    • «два режими, один застосунок»
│   └── logo-lockup.html    • логотип на світлому / темному
│
├── components/             ← React-примітиви (кожен: .jsx + .d.ts + .prompt.md + картка)
│   ├── core/               • Button, IconButton, Badge, Tag, Avatar, Switch,
│   │                         Input, SearchField, PinInput, ProgressSteps + core.card.html
│   ├── forms/              • OptionCard, KidCard, ProfileChip, AddCard + forms.card.html
│   ├── trust/              • AICheckScore, ScoreRing, EvidenceRow, ProcessLog, Mascot + trust.card.html
│   ├── media/              • VideoCard, ChannelCard, ChannelHero, VideoPlayer, VideoRow + media.card.html
│   ├── navigation/         • AppHeader, BottomNav, ModePill, TokenBalance, Subtabs + navigation.card.html
│   ├── commerce/           • PlanCard, TokenPackRow, CoinMedallion, CreditCost, GuaranteeBox,
│   │                         BeforeAfterGrid, FeaturePillar, ReviewCard, FAQItem + commerce.card.html
│   ├── overlays/           • BottomSheet, Toast, EmptyState, SearchOverlay + overlays.card.html
│   └── layout/             • SectionHeader, SettingsRow, SwipeRow, RequestRow, StickyFooter + layout.card.html
│
└── ui_kits/watchover-app/  ← інтерактивна реконструкція застосунку
    ├── index.html          • оболонка: скрипти, рамка девайса, масштабування
    ├── app.css             • стилі екранів + корпусу телефона
    ├── icons.jsx           • набір іконок (Lucide-стиль) → window.WoIcons
    ├── data.jsx            • mock-дані каналів / відео → window.WoData
    ├── App.jsx             • роутинг та стани → window.WatchoverApp
    ├── ChildHome / WatchScreen / PinUnlock.jsx      • дитячий режим
    ├── ParentHome / ReviewQueue / ChannelDetail.jsx • батьківський режим
    └── README.md           • опис потоку та файлів кіту
```

---

## 📄 Перелік файлів і призначення

### Корінь
| Файл | Призначення |
|---|---|
| `styles.css` | Єдина точка входу. Лише список `@import`: шрифти → токени → base → 8 групових CSS. Через неї консьюмер отримує всю систему. |
| `index.html` | Локальна галерея: всі 23 картки (15 foundation + 8 груп) в iframe'ах зі sticky-навігацією і лінками на сорси. Відкривається без сервера. |
| `readme.md` | Повний дизайн-гайд: контекст продукту, модель «двох режимів», тон голосу, візуальні основи, іконографія, маніфест. |
| `SKILL.md` | Сумісний з Agent Skills вхід — щоб систему можна було підключити в Claude Code. |
| `DESIGN-SYSTEM-OVERVIEW.md` | Цей документ — структура та перелік файлів. |

### `themes/<name>/` — низькорівневі основи (по темі)
| Файл | Призначення |
|---|---|
| `theme.css` | Маніфест теми — єдиний import-таргет (fonts → colors → typography → spacing). |
| `colors.css` | Кольорові рампи (внутрішні для теми) + семантичні аліаси (`--surface-card`, `--text-body`, `--brand`, `--play`) — компоненти споживають ТІЛЬКИ аліаси. |
| `typography.css` | Сімейства шрифтів, шкала розмірів / line-height, ваги, трекінг. |
| `spacing.css` | Відступи (сітка 4px — інваріант), радіуси, тіні, motion (easing + тривалості). |
| `fonts.css` | `@font-face` для шрифтів теми (pine-coral: Bricolage Grotesque + Hanken Grotesk). |

Повний контракт токенів — [themes/THEME-CONTRACT.md](themes/THEME-CONTRACT.md).
`base.css` (корінь) — дефолти елементів і `prefers-reduced-motion`; спільний для
всіх тем, споживає лише семантичні аліаси.

### `assets/logo/`
| Файл | Призначення |
|---|---|
| `watchover-mark.svg` | Бренд-знак (pine щит + кораловий play-трикутник) для кремового / білого фону. |
| `watchover-mark-light.svg` | Кремовий варіант знаку для темного / фото-фону. |

### `cards/` — картки-специмени (вкладка Design System)
| Файл | Призначення |
|---|---|
| `colors-stone.html` | Тепла нейтральна рампа + ролі polotna/тексту. |
| `colors-pine.html` | Бренд-колір довіри + ролі `--brand*`. |
| `colors-coral.html` | Play-акцент + ролі `--play*`. |
| `colors-child.html` | Акценти Marigold + Sky (дитячий режим). |
| `colors-scores.html` | Кольори вердиктів AI-Check. |
| `colors-semantic.html` | Семантичні аліаси для поверхонь / тексту / меж. |
| `type-display.html` | Специмен заголовкового Bricolage Grotesque. |
| `type-scale.html` | Уся типографічна шкала display → micro. |
| `type-body.html` | Hanken Grotesk для UI / тексту + ваги. |
| `type-detail.html` | Eyebrow (єдиний CAPS-стиль) + табличні цифри. |
| `spacing-scale.html` | Шкала відступів на сітці 4px. |
| `radii.html` | Драбина радіусів (parent vs child). |
| `shadows.html` | Драбина теплих тіней. |
| `brand-modes.html` | «Два режими, один застосунок» — сигнал бренду. |
| `logo-lockup.html` | Логотип-локап на світлому й темному фоні. |

### `components/` — React-примітиви
Кожен компонент — це набір з 4 файлів:
- `<Name>.jsx` — реалізація (named-експорт, який збирає компілятор);
- `<Name>.d.ts` — контракт пропсів + правила + позначка «starting point»;
- `<Name>.prompt.md` — «що і коли» + приклад використання;
- `*.card.html` (один на папку) — жива картка-демо для вкладки Design System.

> **Джерело інвентаризації:** прототип `artifacts/demo/prototype-r2_v4/` (25 екранів: онбординг,
> квіз/пейвол, parent mode, child mode) + дельта `wiki/specs/2026-06-04-prototype-r4-spec.md`
> (єдиний токен-баланс P0-3, notification dot P1-6, черга запитів). Колонка «Екрани»
> вказує, де патерн зустрічається в прототипі — ці компоненти мають покрити 100% екранів.

#### `core/` — базові контроли
| Компонент | Призначення / анатомія | Варіанти | Екрани (прототип) |
|---|---|---|---|
| **Button** | Головна дія; pill, повна ширина за замовч. | pine / coral / secondary / ghost / danger · sm · disabled · loading | усі |
| **IconButton** | Кругла іконкова дія 32–44px | default / danger · header-on-color (child) | header, kid-card, search |
| **Badge** | Статус-мітка; pill 12px | success / warning / secondary · **notification dot** (новий контент на каналі, R4 P1-6) | списки, nav, channel rows |
| **Tag** | Інтереси / фільтри / категорії | selectable (selected/unselected) · read-only (topic chip) | interests, ai-discovery, ai-check |
| **Avatar** | Канал / дитина; коло | monogram · фото · emoji (kid) · 28/36/48/56px | скрізь |
| **Switch** | Перемикач налаштувань | on/off · disabled | settings |
| Input | Текстове поле / select; label + helper + error | text / email / select · with-mic | signup, child-profile, search |
| SearchField | Закруглене поле пошуку з mic + clear | parent (на paper) · child (на coral header) | parent-search, child-feed |
| PinInput | PIN-дотси (4) + цифровий numpad 3×4 | create / verify · error (shake) | onboarding-5-pin, pin-verify |
| ProgressSteps | Сегментний прогрес онбордингу | done / active / pending | онбординг 3–5b, iap-quiz |

#### `forms/` — вибір та профілі
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| OptionCard | Картка-відповідь з radio/checkbox | single / multi · selected | language, iap-quiz |
| KidCard | Рядок дитини: avatar + ім'я/вік/мова + інтереси + дії | view · editable (edit/delete) | child-profile, settings, analysis |
| ProfileChip | Перемикач профілю дитини (Netflix-style) | default / active / add | preset-library, передача телефону (R4 P0-2) |
| AddCard | CTA додавання | add-first (dashed, великий) · add-more (компактний рядок) | parent-home, child-profile |

#### `trust/` — AI-довіра (підписна група)
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| **AICheckScore** | Оцінка 0–100 + вердикт + докази | safe / caution / flag · compact / full (score-circle 100px) | ai-check |
| ScoreRing | Кільце-оцінка 48px (conic-gradient) з числом | safe / caution / flag | ai-discovery results |
| EvidenceRow | Рядок доказу: іконка-коло + заголовок + текст | ok / warn / info | ai-check (why it works / keep in mind) |
| ProcessLog | Кроки AI-аналізу: spinner → check, поетапна поява | running / done · staggered delays | interest-analysis, ai-check, ai-discovery |
| Mascot | AI-персонаж процесингових станів (пульсація) | idle / processing | interest-analysis, ai-discovery |

#### `media/` — відео та канали
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| **VideoCard** | Thumb 16:9 + назва + канал | grid (child, 2 кол.) / list (parent) / feed (child home, повна ширина, play-оверлей + аватар каналу) · duration badge | child-feed, parent-home-empty |
| **ChannelCard** | Avatar + назва + meta + trailing | card / row · child (read-only) · + notification dot | parent-home, search, child-channels |
| ChannelHero | Банер 16:9 з градієнтним скрімом + score chip + інфо каналу | — | ai-check |
| VideoPlayer | Обгортка плеєра: постер → playing iframe, play-кнопка | poster / playing | child-player, ai-check (sample) |
| VideoRow | Компактний рядок «up next»: thumb 158px + 2-рядкова назва | — | child-player |

#### `navigation/` — навігація та режим
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| **AppHeader** | Верхня панель 56px | parent (paper) / child (coral) · autohide | усі app-екрани |
| **BottomNav** | Нижня навігація, 4 пункти | parent (pine) / child (coral) · badge | parent + child екрани |
| ModePill | Індикатор «PARENT MODE» (uppercase + крапка) | — | усі parent-екрани |
| TokenBalance | Баланс токенів у хедері: coin + число (**єдиний баланс**, R4 P0-3) | default / low | search, ai-check, ai-discovery |
| Subtabs | Сегментований перемикач у межах екрана | active / inactive | внутрішні вкладки |

#### `commerce/` — монетизація
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| PlanCard | Тариф: radio + назва + strike-ціна + daily price | selected · badge «most popular» | iap-paywall |
| TokenPackRow | Пакет токенів для докупівлі | default / popular | buy-tokens sheet (R4 P0-3) |
| CoinMedallion | Великий золотий медальйон балансу 88px | — | settings / buy-tokens |
| CreditCost | Інлайн-вартість дії: coin + число | default / is-high | search, ai-check, swipe actions |
| GuaranteeBox | Money-back блок довіри | — | iap-paywall |
| BeforeAfterGrid | Порівняння «до/після», 2 колонки | — | iap-paywall |
| FeaturePillar | Ціннісний блок: іконка 42px + заголовок + опис | — | iap-paywall, onboarding-1 |
| ReviewCard | Відгук: зірки + текст + автор | — | iap-paywall |
| FAQItem | Розгортуване питання-відповідь | open / closed | iap-paywall |

#### `overlays/` — шари та фідбек
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| BottomSheet | Нижній лист: handle + скрім + sheetUp-анімація | form (add child) · menu (report) · commerce (buy tokens) | child-profile, child-player, paywall |
| Toast | Коротке підтвердження знизу | — | settings, дії зі списком |
| EmptyState | Іконка + заголовок + підзаголовок + CTA | parent / child · з CTA / без | child-feed-empty, search, requests |
| SearchOverlay | Повноекранний пошук дитини: back + field + clear + результати | closed / open · empty result | child-feed (пошук по whitelist, R4 P1-8) |

#### `layout/` — списки та каркас
| Компонент | Призначення / анатомія | Варіанти | Екрани |
|---|---|---|---|
| SectionHeader | Заголовок блока 15/700 (+ опц. лічильник або дія) | — | усі екрани зі списками |
| SettingsRow | Рядок меню: icon-square 36px + назва + meta + chevron | default / destructive | parent-settings |
| SwipeRow | Swipe-to-reveal обгортка рядка з діями | view / similar / delete · + CreditCost на дії | parent-home (whitelist) |
| RequestRow | Запит дитини на канал → approve / deny | pending / approved / denied | parent-requests, child-request (черга запитів) |
| StickyFooter | Закріплена CTA-зона над safe-area | — | онбординг, paywall, ai-check |

### `ui_kits/watchover-app/` — інтерактивний застосунок
| Файл | Призначення |
|---|---|
| `index.html` | Оболонка: підключення скриптів, рамка девайса, масштабування під екран, монтування. |
| `app.css` | Стилі екранів і корпусу телефона (на брендових токенах). |
| `icons.jsx` | Набір іконок у стилі Lucide → `window.WoIcons`. |
| `data.jsx` | Mock-дані каналів / відео / категорій → `window.WoData`. |
| `App.jsx` | Машина станів і роутинг екранів → `window.WatchoverApp`. |
| `ChildHome.jsx` | Дитячий режим — головна (стрічка). |
| `WatchScreen.jsx` | Дитячий режим — перегляд відео (без автоплею). |
| `PinUnlock.jsx` | Шлюз розблокування PIN між дитячим і батьківським режимами. |
| `ParentHome.jsx` | Батьківський режим — головна (білий список). |
| `ReviewQueue.jsx` | Батьківський режим — черга перевірки кандидатів. |
| `ChannelDetail.jsx` | Батьківський режим — деталі каналу + докази. |
| `README.md` | Опис потоку та файлів UI-кіту. |

### Авто-генеровані (вручну не редагуються)
| Файл | Призначення |
|---|---|
| `_ds_bundle.js` | Скомпільована рантайм-бібліотека компонентів. |
| `_ds_manifest.json` | Індекс компонентів, карток, токенів, starting points. |
| `_adherence.oxlintrc.json` | Правила відповідності для консьюмерів. |

> ⚠️ **Свідоме відхилення (2026-06-12):** ці три файли — продукт зовнішнього компілятора
> claude.ai design-середовища, якого в цьому репо немає. Вони **не генеруються**.
> Наслідки: картки (`cards/`, `<group>.card.html`) — статичні HTML на `wo-*` класах
> (без React-бандла); навігація по системі — через [index.html](index.html)
> (локальна галерея всіх карток, замінює вкладку Design System). JSX-файли —
> референс-реалізації для майбутньої компіляції; CSS-шар повністю робочий.

---

## Ключові принципи (з readme.md)
1. **Два режими — відчутно різні.** Parent: спокій, pine, тісні радіуси, докази. Child: гра, coral, круглі форми, мало слів.
2. **Довіра важливіша за залученість.** Завжди показувати *чому* контент безпечний (оцінка + докази AI-Check).
3. **Жодних dark patterns.** Без автоплею, без нескінченної стрічки, без нав'язливих бейджів.
4. **Mobile-first**, одноколонковий, зручний для великого пальця, WCAG AA.
5. **Типографіка:** Bricolage Grotesque + Hanken Grotesk — ніколи Roboto/Inter.