docs(design-system): новый контракт Tier-1 — визуальный язык (токены/компоненты/distraction-визуал), AMG-leaning премиум dark-first, после adversarial-ревью (11 находок) + швы (C §5/§6, plugin-sdk §4.1, roadmap-трек+v0.5, README×2)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-23 20:27:16 +03:00
parent cf04b05097
commit 32edd07636
7 changed files with 156 additions and 5 deletions
@@ -0,0 +1,149 @@
+# Контракт: дизайн-система (визуальный язык)
+
+> Единый **визуальный язык** ОС: токены, компоненты, правила. Делает измеримыми
+> визуальные стороны принципов #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 |