diff --git a/docs/README.md b/docs/README.md index f2e79e7..55b2675 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,7 +19,7 @@ - [tech-stack.md](tech-stack.md) — канонический технический стек (Rust-first) и крейты. ### Tier 1 — сквозные контракты (соединительная ткань) -- [contracts/](contracts/README.md) — IPC, модель данных, plugin-SDK, безопасность/приватность, safety (граница+distraction), производительность (NFR), железо. +- [contracts/](contracts/README.md) — IPC, модель данных, plugin-SDK, безопасность/приватность, safety (граница+distraction), производительность (NFR), дизайн-система (визуальный язык), железо. ### Инфраструктура разработки - [dev-environment.md](dev-environment.md) — как вести разработку изолированно, с Mac. diff --git a/docs/contracts/README.md b/docs/contracts/README.md index aba3a7d..277f0e0 100644 --- a/docs/contracts/README.md +++ b/docs/contracts/README.md @@ -13,6 +13,7 @@ | `security-privacy.md` | Sandboxing плагинов, модель разрешений, обработка данных, 152-ФЗ. | | `safety.md` | Граница «не safety-critical» + структурный энфорсмент red-lines (CAN read-only) + driver-distraction-политика. *Комплемент security-privacy: вред/отказы, не злоумышленник.* | | `performance.md` | NFR-бюджеты: латентность, кадровый бюджет, память/ресурсы, тепло — принцип #11 как измеримый контракт. | +| `design-system.md` | Визуальный язык ОС: токены (цвет/тип/space/motion), компонент-таксономия, distraction-визуал. AMG-leaning премиум, dark-first; рендерит Shell (C). | | `hardware.md` | Целевой таргет (RK3588), топология питания, периферия + **HAL/board-support API** для портирования на другое железо/авто. | > Важный нюанс: **plugin-SDK** (API, тут) и **домен F «Plugin host»** (рантайм, diff --git a/docs/contracts/design-system.md b/docs/contracts/design-system.md new file mode 100644 index 0000000..7617ceb --- /dev/null +++ b/docs/contracts/design-system.md @@ -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 | diff --git a/docs/contracts/plugin-sdk.md b/docs/contracts/plugin-sdk.md index bcd3fbc..9425473 100644 --- a/docs/contracts/plugin-sdk.md +++ b/docs/contracts/plugin-sdk.md @@ -73,7 +73,7 @@ plugin: ## 4. Точки расширения ### 4.1 UI — тайлы и экраны (слот-модель, решение №6) -- `Shell.RegisterTile(decl)` — **декларативный** элемент (рендерит shell в едином стиле). +- `Shell.RegisterTile(decl)` — **декларативный** элемент (рендерит shell в едином стиле — [design-system.md](design-system.md)). - `Shell.RegisterScreen(decl) → slot_token` (требует capability `ui_screens`) — декларативный экран **или** Wayland-поверхность (slot-token + slot-протокол, c-shell §4). - Декларативный словарь (констрейнт): `icon`, `title`, `value`, `state`, привязки к данным, `action`. Сложнее этого → поверхность. *(🟡 глубину декларативного DSL diff --git a/docs/domains/c-shell-ux.md b/docs/domains/c-shell-ux.md index 6612674..6a29205 100644 --- a/docs/domains/c-shell-ux.md +++ b/docs/domains/c-shell-ux.md @@ -79,7 +79,7 @@ Shell** (его пробрасывает bubblewrap при `ui_*`, security-priv ## 6. Тема и отклик - День/ночь — **авто** (v0: **по времени** (RTC/NTP/fake-hwclock, a-base §7); **GPS-восход — v1** - (после поднятия домена K); датчик освещённости и сигнал машины — later), токены темы. + (после поднятия домена K); датчик освещённости и сигнал машины — later), **токены темы** ([design-system.md](../contracts/design-system.md) — визуальный язык). - Крупные тач-таргеты, **мгновенный отклик** (принцип #11): тяжёлое — фоном, UI-поток не блокируем. ## 7. Driver-distraction (принцип #6) diff --git a/docs/roadmap.html b/docs/roadmap.html index 55cbac0..b0a887b 100644 --- a/docs/roadmap.html +++ b/docs/roadmap.html @@ -119,7 +119,7 @@ const P=[ {id:'v0.2',n:'Boot-конвейер',ids:'A04 A05 A15',dep:'v0.1',test:'VM boot',done:'Stage 0/1/2 разделены; splash мгновенно'}, {id:'v0.3',n:'Power-safe ядро',ids:'B01 B03 B04 B02 B06 B07 A14 B05',dep:'v0.2, hold-up (hw §3)',test:'fake-ACC + power-cut в VM',done:'N циклов зажигания без потери /data; abort до PONR'}, {id:'v0.4',n:'MCU/thermal fail-safe',ids:'B08 B09 B10 A12',dep:'v0.3, мок-MCU',test:'мок-MCU/sensor',done:'thermal-trip → graceful; MCU-таймер режет питание при зависании SoC'}, - {id:'v0.5',n:'Shell первый кадр',ids:'C03 C04 C01 C05 C02 C07 C09 C10',dep:'v0.2',test:'нативный Slint + VM',done:'до интерактива < бюджет (perf §3); авто день/ночь'}, + {id:'v0.5',n:'Shell первый кадр',ids:'C03 C04 C01 C05 C02 C07 C09 C10',dep:'v0.2, design-system',test:'нативный Slint + VM',done:'до интерактива < бюджет (perf §3); авто день/ночь'}, {id:'v0.6',n:'База-доводка + dev-харнесс',ids:'A09 A10 A11 A07 A16 F01 F02 F03 F04 J06',dep:'параллельно',test:'сам harness',done:'dev-итерация без железа; память/лог/eMMC в бюджете'}]}, {id:'v1',t:'Ассистент онлайн + связь + аудио + Location',demo:'«Штурман, …» → устный RU-ответ; аудио с ducking; distraction по GPS',crit:'ассистент-онлайн', gates:'K05 (маппинг руля/ADC) · B08/B09 (если MCU не закрыт) · distraction-числа (safety §4)', diff --git a/docs/roadmap.md b/docs/roadmap.md index 7d8585b..ed84576 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -36,7 +36,7 @@ | **v0.2** Boot-конвейер | splash → таргет фазами | A04 A05 A15 | v0.1 | VM boot | Stage 0/1/2 разделены; splash мгновенно | | **v0.3** Power-safe ядро | переживает срыв питания | B01 B03 B04 B02 B06 B07 A14 B05 | v0.2, hold-up (hw §3) | fake-ACC + power-cut в VM | N циклов зажигания без потери `/data`; abort до PONR | | **v0.4** MCU/thermal fail-safe | аппаратный фундамент питания/тепла | B08 B09 B10 A12 | v0.3, мок-MCU | мок-MCU/sensor | thermal-trip → graceful; MCU-таймер режет питание, если SoC завис | -| **v0.5** Shell первый кадр | красивый home, день/ночь | C03 C04 C01 C05 C02 C07 C09 C10 | v0.2 | нативный Slint + VM | до интерактива < бюджет (perf §3); авто день/ночь | +| **v0.5** Shell первый кадр | красивый home, день/ночь | C03 C04 C01 C05 C02 C07 C09 C10 | v0.2, design-system | нативный Slint + VM | до интерактива < бюджет (perf §3); авто день/ночь | | **v0.6** База-доводка + dev-харнесс | память/лог/eMMC + dev-цикл | A09 A10 A11 A07 A16 F01 F02 F03 F04 J06 | паралл. v0.1–v0.5 | сам harness | dev-итерация без железа работает; память/лог/eMMC в бюджете | **Порядок/параллелизм:** v0.1→v0.2 строго; затем v0.3 (power) и v0.5 (shell) **параллельно** поверх v0.2; @@ -172,6 +172,7 @@ hardware/BSP → v0.1(образ) → v0.2(boot) → v0.3(power-safe) ┬→ v0. plugin-capability-review + perm-UI (v3) → secure-boot/at-rest/trust-anchor (v4). Контракт — [security-privacy.md](contracts/security-privacy.md). - **Цепочка доверия OTA:** подпись плагинов `F11` (v3.2) → secure boot `A20` + signed OTA `A19`/`L09` (v4.3/v4.4) — единая trust-цепочка с anti-rollback. - **Бюджеты/безопасность как gate:** [performance.md](contracts/performance.md) (CI perf-gate, регрессия = баг) и [safety.md](contracts/safety.md) (distraction, red-line-энфорсмент) — сквозные требования к каждой вехе. +- **Дизайн-система** *(язык — до v0.5):* визуальный язык/токены ([design-system.md](contracts/design-system.md)) опережает первый видимый кадр (v0.5); прод-скин/значения итерируются на железе. AMG-leaning премиум, dark-first; плагины наследуют через Shell. ## За горизонтом v4