shturman/docs/contracts/design-system.md

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

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

Статус: v1 (черновик на ревью). Связано с: principles.md (#6/#10/#11) · домен C (владелец рендера/слот-модель/тема) · safety.md (§4 distraction) · performance.md (§3 motion/кадр) · plugin-sdk.md (ui_*) · 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 — рендер 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).
• Поверхности/тайлы встают в слот-модель C §4.

3.4 Радиусы и материальность

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

3.5 Motion

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

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

Каждый компонент — в слот-модели C §4:

• Тайл (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)

• На ходу (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): плагин даёт декларацию/данные, не свой рисунок — рендерит Shell в Slint (C §5: чужой код в 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