# Контракт: дизайн-система (визуальный язык)

> Единый **визуальный язык** ОС: токены, компоненты, правила. Делает измеримыми
> визуальные стороны принципов #11 (отзывчивость), #6 (driver-distraction), #10 (RU-first).
> Все UI-вкладчики (Shell, now-playing, навигация, камера, плагины) говорят на нём.

Статус: **v1 (черновик на ревью).**
Связано с: [principles.md](../principles.md) (#6/#10/#11) · домен [C](../domains/c-shell-ux.md) (владелец рендера/слот-модель/тема) · [safety.md](safety.md) (§4 distraction) · [performance.md](performance.md) (§3 motion/кадр) · [plugin-sdk.md](plugin-sdk.md) (`ui_*`) · [tech-stack.md](../tech-stack.md) (Slint)

---

## 1. Назначение и рамки

- **Язык-контракт:** все, кто вкладывает UI (Shell C, now-playing H, нав I, камера J,
  плагины через `ui_tiles`/`ui_screens`), рендерятся в **едином стиле** — система задаёт язык,
  они дают контент.
- **НЕ финальный скин.** Конкретные ЗНАЧЕНИЯ токенов (точные цвета/размеры/шрифт) — **🟡**,
  финализируются на **реальном экране** (контраст на солнце, glance-тест за рулём). Здесь —
  **структура языка + рекомендованные дефолты** (как distraction-числа в safety, латентность в performance).
- **Владелец рендера — Shell (C):** тайлы рисует сам shell единым стилем ([C §5](../domains/c-shell-ux.md) —
  рендер shell / единый стиль), через декларативный Slint-UI-DSL (C §5); поверхности встают в слоты (C §4).

## 2. Дизайн-направление: «тихая премиальность, водитель в фокусе»

Вдохновение **Mercedes-AMG GT** (мультимедиа) + **Tesla** → **наш** язык (MIT, не клон).
- **Характер — AMG-leaning:** глубокий чёрный, драматичный контраст, **хром-хайрлайны**,
  выраженный **приборный мотив** (круговые шкалы), технический premium, монохромный кластер.
- **Каркас — ясность:** плоско, воздух, крупные цели, контент-первый (спокойствие как у Tesla).
- **Три столпа:** (1) **читаемость за рулём** прежде красоты; (2) **премиальная сдержанность** —
  один акцент, не радуга; (3) **машина как герой** — vehicle-data first-class, приборные мотивы.

## 3. Токены

### 3.1 Цвет
- **Две темы: Ночь (дефолт, AMG-чёрный) и День (полноценная).** Авто-переключение
  (C02: по времени v0 → GPS-восход v1); ручной оверрайд в Settings.
- **Слои глубины** (не тени — плоско): `bg` (фон-экран) → `surface` (тайл) → `surface-2`
  (под-тайл/трек); разделение — **хром-хайрлайн** `line` 0.5px + яркость, не shadow.
- **Бренд-акцент — ТОКЕН, выбираемый пользователем** (Settings). Дефолт — **«Платина»**
  (high-key нейтраль; AMG-кластер: серебристая энергия на чёрном — не навязывает цвет, эмфаза
  яркостью/заливкой). Курируемый набор (🟡): Платина (дефолт) · Cyan-teal · Электрик-блю · Индиго ·
  Маджента — все **держат дистанцию от hue-секторов семантики** (`danger`/`warn`/`ok`), чтобы на
  фокус-ринге/прогрессе не путаться с алертом/distraction-lock (возможен пользовательский hex с тем же
  ограничением). Акцент — **только на активном/живом** (now-playing, PTT, прогресс, фокус-ринг).
- **Семантика — ФИКСИРОВАНА, не бренд-акцент:** `danger` (красный — критич./DTC),
  `warn` (янтарь — предупреждение / distraction-lock), `ok` (зелёный — online / двигатель OK).
  **Red/amber зарезервированы под алерты** → бренд-акцент их не использует (иначе предупреждение теряется).

| Токен | Ночь (дефолт) 🟡 | День 🟡 | Роль |
|-------|------------------|---------|------|
| `bg` | `#0a0c0e` | `#e7ebee` | фон-экран |
| `surface` | `#14181b` | `#ffffff` | тайл/карточка |
| `surface-2` | `#1b2125` | `#f1f5f7` | под-тайл/трек |
| `text` | `#eef2f4` | `#131a1e` | основной текст |
| `muted` | `#7e888f` | `#5c6772` | вторичный |
| `line` | `rgba(255,255,255,.08)` | `rgba(0,0,0,.08)` | хром-хайрлайн |
| `accent` (Платина) | `#d8dee2` | `#2a3138` | активное / now / фокус |
| `danger` | `#e2554e` | `#cf3d36` | критич. / DTC |
| `warn` | `#e3a948` | `#bf7a0c` | предупреждение / distraction-lock |
| `ok` | `#54b06b` | `#3d9657` | online / двигатель OK |

### 3.2 Типографика
- **RU-first / Cyrillic** (#10): шрифт с полным кир. набором и хорошей читаемостью мелкого —
  🟡 кандидаты (open/MIT-совместимые): Inter / Manrope / собственный. На ходу — крупно, средний вес.
- **Два веса (400/500)** — тяжёлые начертания выглядят дёшево (premium-сдержанность, как perf-эстетика).
- **Tabular цифры** (`tnum`) для времени / скорости / значений — приборный мотив.
- **Шкала** (🟡): display 30–56 (скорость/часы), h 19–22, body 15, label 12–13, micro 11.
  **Sentence case** везде (не Title Case, не CAPS — кроме осознанного брендового вордмарка).

### 3.3 Пространство и сетка
- База **4px**; отступ тайла 14–16; гэп 12; **крупные touch-цели ≥ 46–48px** (🟡 собственный дефолт; крупные цели в движении — [safety §4.4](safety.md)).
- Поверхности/тайлы встают в **слот-модель** [C §4](../domains/c-shell-ux.md).

### 3.4 Радиусы и материальность
- Радиусы: `md` 12 · `lg` 16 · `pill` 23+. **Плоско:** без градиентов / тяжёлых теней
  (дёшево для Panfrost, держит 60 fps — performance §3). Глубина — слоями + хром-хайрлайн.

### 3.5 Motion
- В рамках [performance §3](performance.md) (60 fps, ввод ≤100 ms). Сдержанно: **150–250 ms**,
  ease; типы — fade / slide / малый scale. **Декоративной анимации на ходу нет** (distraction);
  в `driving` — редукция движения.

## 4. Компонент-таксономия

Каждый компонент — в слот-модели [C §4](../domains/c-shell-ux.md):
- **Тайл** (home, крупный, тап → апп/действие) · **Карточка** · **Статус-бар** (время/сеть/темп/вордмарк) ·
  **Now-playing** (арт / тайтл / прогресс / транспорт / источник) · **Ассистент-оверлей** (PTT-пилюля
  всегда доступна + лог-диалог в слоте, C §8) · **Нав-поверхность** (карта + turn-by-turn) ·
  **Камера-вид** · **Экраны настроек** · **Диалоги разрешений** (capability-review, C14).
- **Приборные компоненты** (фирменный AMG-мотив): **круговая шкала** (speed / RPM / temp),
  vehicle-data — first-class гражданин UI.

## 5. Driver-distraction визуал *(операционализация [safety §4](safety.md))*

- На ходу (`driving`): **крупнее цели, меньше элементов**; **прячем** клавиатуру, длинные списки,
  мелкое, видео на экране водителя; **голос-первый** (PTT крупно). Компонент, требующий долгого
  взгляда (glance > 2 c), на ходу недоступен.
- Растут контраст и размер; **анимации редуцируются**.
- **Состояния компонента** (🟡): default → active (`accent`) → focus (фокус-ринг) → **disabled/blocked**.
  Различаем **«прячем»** (убираем из UI на ходу) и **«показываем заблокированным»** (distraction-lock):
  недоступный-но-видимый аффорданс = приглушение к `muted` + индикатор-замок через `warn`.
- `DistractionModeChanged(level)` (ipc §4) → UI адаптируется **централизованно** в Shell;
  плагины получают `level` для адаптации (safety §4.6 — ◻️ точка доставки открыта).

## 6. Типографика RU-first (детали)

- Кириллица — **первый класс**, не латиница с «костылём» (#10). Шрифт с полным кир. набором,
  `tnum`, читаемостью мелкого на солнце.
- Единицы/локаль (км/ч, °C, В) — формат RU; источник величин — data-model / Settings.

## 7. Motion-язык (детали)

- Роли: вход/выход поверхности; **фокус** (руль-навигация — видимый фокус-ринг, C §9); смена
  темы (кросс-фейд день↔ночь); смена now-playing. Все ≤ перф-бюджета (§3.5).

## 8. Наследование плагинами

- **Декларативный путь** (`ui_tiles` / декларативный `ui_screens`, [plugin-sdk §4.1](plugin-sdk.md)):
  плагин даёт **декларацию/данные, не свой рисунок** — **рендерит Shell** в Slint ([C §5](../domains/c-shell-ux.md):
  чужой код в UI не исполняем) → визуальный язык гарантирован **структурно**.
- **Богатая Wayland-поверхность** (карта/видео/камера — `ui_screens`, C §4/§5; plugin-sdk §4.1): плагин
  **рисует пиксели сам**; единство держится не структурно, а через **токены/гайдлайны** этой системы.
- В **обоих** случаях тема, акцент, distraction-режим и слот-рамка — **от системы**; плагин их **не переопределяет**.

## 9. Зависимости / связи

- **C** — владелец рендера, слот-модель (§4), тема (C §6), Slint-UI-DSL (C §5).
- **safety §4** — distraction-визуал · **performance §3** — motion/кадр-бюджет · **plugin-sdk** — `ui_*` ·
  **tech-stack** — Slint · **data-model/Settings** — единицы/тема-оверрайд · **principles** #6/#10/#11.

## 10. Открытые вопросы

- 🟡 **Значения токенов** (палитры день/ночь, шкала типографики) — финал на реальном экране (солнце/glance).
- 🟡 **Дефолт-акцент + курируемый набор** пользовательских акцентов — подтвердить (дефолт «Платина»).
- 🟡 **Выбор шрифта** с кириллицей (Inter / Manrope / собственный) — по читаемости на железе.
- ◻️ **Глубина пользовательской темизации** — только акцент vs полные пользовательские темы.
- ◻️ **Доставка `distraction-level` плагину** (общая с safety §4.6 / §8).
- 🟡 **Иконо-система** — line-icon стиль, сетка из space-базы 4px, размеры в шкале, толщина штриха под
  два-веса-эстетику — финал на экране (читаемость за рулём). Иконка — структурный слот тайла (C §5).

## Журнал решений (design-system)

| Решение | Выбор | Дата |
|---------|-------|------|
| Направление | «тихая премиальность, водитель в фокусе» — **AMG-leaning** премиум + ясность; наш язык (MIT) | 2026-06-23 |
| Бренд-акцент | **пользовательский токен** (Settings), дефолт **«Платина»** (нейтраль); набор **вне hue-секторов семантики**; red/amber — **только алерт** | 2026-06-23 |
| Темы | две, **dark-first** (Ночь дефолт, День полноценная), авто-переключение | 2026-06-23 |
| Материальность | плоско (без градиентов/теней) — глубина слоями + хром-хайрлайн (perf/Panfrost) | 2026-06-23 |
| Единый стиль | плагины рендерятся **Shell**, дают декларацию — язык гарантирован структурно | 2026-06-23 |