trail-mate/docs/uiux/foundation/firmware_visual_style.md

Firmware Visual Style Specification

1. Scope

本文档定义 Trail Mate 固件界面的整体视觉语言。

它约束的是：

• 色彩系统
• 顶部 chrome 风格
• 面板/按钮/弹窗的基础样式
• 文本层级与对齐原则
• 页面应该呈现出的整体气质

它不定义：

• 某个页面的像素级几何布局
• 某个设备 profile 的固定尺寸
• 某个组件的内部实现细节

这意味着：

• 480x222
• pager
• tdeck
• 任何具体 x / y / w / h

都只能出现在“页面规格”或“设备/profile 示例”里，不能被提升为全固件通用布局法则。

docs/skyplot.md、docs/sstv/SSTV.md、docs/EnergySweep/uiux.md 这类文档里的像素表，只能解释它们各自页面在各自目标 profile 上如何落地；它们共享的是视觉语言，不是同一套几何。

---

2. Distinctions

2.1 视觉风格 != 页面布局

视觉风格回答的是“这个固件看起来像什么”。

页面布局回答的是“某个页面在某个 profile 上具体怎么摆”。

前者是全局约束，后者是页面级约束。

2.2 页面布局 != 设备 profile

同一个页面在不同设备上可以保持同一视觉语言，但采用不同尺寸、边距、字号和控件密度。

因此：

• 视觉风格应跨设备稳定
• 像素布局应跟随 page_profile、屏幕尺寸和交互模式调节

2.3 页面 chrome != 页面内容

以下元素属于共享 chrome：

• TopBar
• 返回入口
• 电量/状态位
• 固定悬浮控制按钮
• 弹窗/底部弹层的基础样式

以下元素属于页面内容：

• 地图
• 列表
• 遥测信息
• 图像区域
• 图表/状态面板

chrome 要保持全局一致；内容可以随页面语义变化。

2.4 语义色 != 装饰色

颜色首先用于表达层级和语义，不是为了制造“花哨”。

可接受的颜色分工是：

• 主强调：Amber
• 主文本：Text
• 次文本：TextDim
• 信息：Info
• 成功：Ok
• 警告：Warn

不可接受的是为每一行、每一个标签随机发明一组风格无关的颜色。

---

3. Canonical Tokens

固件界面整体风格的基线 token 如下：

• Amber = #EBA341
• AmberDark = #C98118
• WarmBG = #F6E6C6
• PanelBG = #FAF0D8
• Line = #E7C98F
• Text = #6B4A1E
• TextDim = #8A6A3A
• Warn = #B94A2C
• Ok = #3E7D3E
• Info = #2D6FB6

新页面和重构页面应优先围绕这组 token 建立视觉。

如果实现层已经存在共享 theme/helper，则应让 helper 朝这组 token 收敛，而不是在页面里继续发散出新的暗色私有体系。

---

4. Global Style Direction

Trail Mate 的界面应统一成“暖色工程仪表风格”，而不是暗色 cyber / HUD 风格。

它的气质应当是：

• 温暖
• 克制
• 可读
• 工程化
• 轻量仪表感

它不应当是：

• 黑蓝霓虹 HUD
• 调试面板堆叠
• 高饱和赛博风
• 到处阴影和浮雕的重装饰 UI

---

5. Layout Principles

5.1 根背景

页面根背景优先使用 WarmBG。

地图、图片、列表或图表所在的主要承载区，可在此基础上用 PanelBG 或内容专属底色分层，但不得背离整体暖色基调。

5.2 TopBar

所有标准页面优先复用共享 top_bar 组件。

TopBar 的语义是“共享应用 chrome”，不是页面自己发明的新标题条。

要求：

• 颜色与全局 theme 保持一致
• 不允许页面局部自定义成另一套标题栏风格
• 标题居中
• 右侧状态信息维持弱层级

5.3 面板与边框

如页面确实需要容器，应遵守：

• 背景优先 PanelBG
• 边框优先 Line 或 AmberDark
• 圆角统一 8~10px
• 边框厚度优先 2px

不允许把所有信息都塞进多层嵌套卡片里。

5.4 按钮

按钮应沿用暖色工程风格：

• 默认态：PanelBG + AmberDark/Line 边框
• 聚焦态：Amber 外轮廓或高亮
• 禁用态：弱化背景与边框，但仍保持可识别

不允许在单个页面中引入一套深色、金属蓝、玻璃态按钮体系。

5.5 弹窗与弹层

弹窗应继承全局风格，而不是成为一块风格孤岛。

要求：

• 背景使用暖色 panel
• 边框使用 AmberDark 或 Line
• 在小屏上优先用紧凑弹层/底部弹层，而不是巨大居中黑色模态块
• 交互入口不能因为弹层遮挡而变得难以操作

5.6 文本层级

文本层级应稳定：

• 主对象名/主读数：Text
• 次级说明/状态：TextDim
• 强调信息：AmberDark 或 Amber
• 状态语义：Info / Ok / Warn

默认不要把页面做成“所有文字都用不同颜色”的彩条板。

5.7 右侧遥测列

当页面右侧承担“遥测/链路/readout”职责时，这一列应按“右缘读数列”处理：

• 整体右对齐
• 一行一项
• 字段语义直接、短、可扫读
• 不要做成“把左对齐段落搬到右边”

---

6. Geometry Rules

全局视觉规格只规定几何原则，不规定统一像素。

允许的全局原则：

• 顶部保留共享 TopBar 区
• 内容区按页面语义自由分配
• 边距、字号、按钮尺寸可随 page_profile 调整

不允许的误读：

• 把某一页在 pager 上的 480x222 布局，当成所有页面或所有设备都必须照抄的布局
• 把某一页的双栏布局，当成所有页面都必须双栏
• 把某一页的按钮坐标，当成共享组件的唯一合法位置

---

7. Guardrails

后续页面设计与改造必须遵守以下约束：

1. 不允许把暗色 HUD 风格引入到标准内容页面。
2. 不允许把 pager 或任何单设备布局示例提升为全局几何规范。
3. 不允许在共享 TopBar 之外私造一套风格冲突的标题栏。
4. 不允许在右侧遥测列中使用“左对齐段落式文本”冒充读数列。
5. 不允许弹窗做成风格割裂、遮挡严重且难以操作的深色模态块。
6. 不允许为了“好看”而突破语义色边界，把颜色变成随机装饰。

---

8. Summary Baseline

一句话总结这份规格：

Trail Mate 的固件界面应统一成“暖色工程仪表风格”，而具体像素布局始终是页面级、profile 级决策，不能从某个设备示例反向立法为全局规则。