RuView 桌面端 UI 设计系统实战解读：基于 ADR-053 的暗色专业主题与 Unity 风格面板体系

RuView 通过 WiFi 信号实现空间感知、生命体征监测与存在检测，其硬件管理控制面需要一个面向高密度数据（CSI 热力图、节点注册表、日志流、Mesh 拓扑）的专业界面。本文以架构决策记录 ADR-053 为蓝本，结合其在仓库中的真实落地实现，完整拆解这一套「暗色专业 + Unity 风格」设计系统的 7 条设计原则、CSS 设计令牌、排版刻度、三区布局、六大核心组件与动效规范，并给出可直接复用的代码与设计令牌清单。读完本文，你将掌握如何在 Tauri 桌面端（由 ADR-052 引入）与既有 Web 可视化栈上，构建一套面向嵌入式传感硬件管理的、可扫描的、渐进式披露的控制界面。

一、设计背景：为什么控制平面需要一套专门的设计系统

ADR-053 明确将设计目标锁定为「硬件管理控制平面」（hardware management control plane），其信息载体包括 CSI 热力图、节点注册表、日志流与 Mesh 拓扑等密集数据，使用群体涵盖工程师与现场运维人员。两条设计灵感来源决定了整体气质：

1. 数据优先的专业工具（network monitoring dashboards、embedded systems IDEs、infrastructure control panels）——数据自己说话，界面只展示重要的、隐藏无关的，通过状态色而非文字噪音传达信息；
2. Unity Editor——可停靠面板（dockable panels）、inspector / hierarchy / scene 分区、属性网格（property grid）、暗色专业主题与「密集但有序」的数据陈列。Unity 的 UI 天生为管理复杂实时系统设计，与 RuView 的传感网络管控场景高度契合。

两者结合的目标是：把数据组织成可扫描（scannable）的面板并建立清晰层级，用一致的色码传达状态，布局支持从全局总览（overview）到单节点详情（progressive disclosure）的渐进下钻。

这套设计系统所属的载体在 ADR-052 中确定：RuView 需要一个 Tauri v2 桌面应用来统一管理此前分散在 esptool.py CLI、provision.py（13+ 个参数无 GUI）、curl POST :8032/ota、浏览器 localhost:8080 等 6 个以上工具中的操作——烧录固件、NVS 配网、OTA 更新、WASM 模块管理、启动感知服务与 Mesh 拓扑可视化。ADR-053 即为该桌面应用的 UI 层决策。

二、7 条设计原则

ADR-053 提炼出支撑整站一致性的设计原则，每一条都直接映射到后续的令牌与组件规范：

1. 数据即界面（Data is the interface）——系统通过可视化而非文字解释来呈现模式，每个像素都有其存在的价值；
2. 精确排版（Precision typography）——排版干净、权威，技术数值无歧义显示，标签简洁；
3. 面板式布局（Panel-based layout）——借鉴 Unity 面板系统的可停靠分区，操作者一眼纵览整个 Mesh，再逐节点下钻；
4. 状态靠颜色传达（Status through color）——刻意设计的状态色编码：绿色（在线）、琥珀色（降级）、红色（离线/故障）、蓝色（扫描中/新增），杜绝滥用颜色；
5. 渐进式披露（Progressive disclosure）——Dashboard 呈现总览，点击节点展示细节；先摘要、交互后详情；
6. 双字体体系（Dual typography）——所有技术值（MAC 地址、固件版本、CSI 振幅）用等宽字体，标签与描述用无衬线字体，用字体对比传达「数据 vs 上下文」；
7. 由 rUv 驱动（Powered by rUv）——克制的品牌露出：状态栏页脚标语、关于对话框、启动页。

三、色彩系统：Design Tokens 完整清单

ADR-053 给出的核心色板是整套设计系统的地基，按「背景分层 → 文字层级 → 状态指示 → 强调色 → 边框 → 数据字体」六组组织：

:root {
  /* Background layers */
  --bg-base:        #0d1117;     /* App background */
  --bg-surface:     #161b22;     /* Panel backgrounds */
  --bg-elevated:    #1c2333;     /* Cards, modals, dropdowns */
  --bg-hover:       #242d3d;     /* Hover state */
  --bg-active:      #2d3748;     /* Active/selected state */

  /* Text hierarchy */
  --text-primary:   #e6edf3;     /* Headings, primary content */
  --text-secondary: #8b949e;     /* Labels, descriptions */
  --text-muted:     #484f58;     /* Disabled, hints, placeholders */

  /* Status indicators */
  --status-online:  #3fb950;     /* Node online, healthy */
  --status-warning: #d29922;     /* Degraded, needs attention */
  --status-error:   #f85149;     /* Offline, failed, critical */
  --status-info:    #58a6ff;     /* Scanning, discovering, info */

  /* Accent */
  --accent:         #7c3aed;     /* rUv purple — primary actions */
  --accent-hover:   #6d28d9;

  /* Borders */
  --border:         #30363d;
  --border-active:  #58a6ff;

  /* Data display */
  --font-mono:      'JetBrains Mono', 'Fira Code', 'Consolas', monospace;
  --font-sans:      'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

仓库落地证据：这些令牌已经以几乎一致的数值写入桌面端设计系统样式表 design-system.css。在实际落地时，还在此基础上扩展了三组实用令牌，可视为对 ADR 规范的工程化补齐：

• 阴影层：--shadow-sm: 0 1px 2px rgba(0,0,0,0.3)（普通控件）、--shadow-md: 0 4px 12px rgba(0,0,0,0.4)（浮层）、--shadow-lg: 0 8px 24px rgba(0,0,0,0.5)（弹窗）、--shadow-accent: 0 0 0 3px var(--accent-glow)（聚焦态用紫色光晕描边）；
• 强调光晕：--accent-glow: rgba(124, 58, 237, 0.15)——紫色强调色需要视觉「呼吸感」，用低透明度光晕而非高饱和色块实现聚焦反馈；
• 圆角体系：--radius-sm: 4px / --radius-md: 6px / --radius-lg: 8px / --radius-xl: 12px / --radius-full: 9999px；
• 过渡时长：--transition-fast: 0.1s ease / --transition-normal: 0.15s ease / --transition-slow: 0.25s ease。

落地文件同时将状态栏高度定为 --statusbar-height: 32px（ADR 草案为 28px），并把 heading-sm 设计为大写、字距 0.04em 的等宽面板标签、data-lg 放大到 24px 作为关键指标值——这些细节说明令牌进入代码时会围绕真实渲染效果做微调，阅读时以落地实现为准。

四、排版系统：字体与字号刻度

排版遵循「数据用等宽、标签用无衬线」的双字体原则。ADR-053 给出了完整的排版刻度，design-system.css 的 .heading-sm/.body/.data 等类名与之对应：

/* Typographic hierarchy */
.heading-xl   { font: 600 28px/1.2 var(--font-sans); }   /* Page titles */
.heading-lg   { font: 600 20px/1.3 var(--font-sans); }   /* Section titles */
.heading-md   { font: 600 16px/1.4 var(--font-sans); }   /* Card titles */
.heading-sm   { font: 600 13px/1.4 var(--font-sans); }   /* Panel labels */
.body         { font: 400 14px/1.6 var(--font-sans); }   /* Body text */
.body-sm      { font: 400 12px/1.5 var(--font-sans); }   /* Captions */
.data         { font: 400 13px/1.4 var(--font-mono); }   /* Technical values */
.data-lg      { font: 500 18px/1.2 var(--font-mono); }   /* Key metrics */

使用建议（依据 ADR 语义推断并可与 design-system.css 中的落地类对照）：heading-xl 只用于页面主标题并保留 -0.02em 的字距压缩以获得更强的标题感；所有 MAC/IP/固件版本/CSI 数值一律使用 .data/.data-lg 等宽类；heading-sm 落地为大写标签，用作面板区块小标题。落地样式将字号层级控制在 12~28px 之间、正文行高 1.6，保证长时间盯监控屏的可读性。

五、布局系统：三区结构与面板行为

ADR-053 定义了「导航侧栏 + 节点列表 + 详情检查器」的三区布局，Unity 停靠系统为其提供机械框架：

+--[ Sidebar ]--+--[ Main ]-------------------------------------+
|               |                                                 |
| [Nav Items]   |  +--[ Command Bar ]---------------------------+ |
|               |  | Breadcrumb    | Actions | Search           | |
| Dashboard     |  +-------+-----------------------------------+ |
| Nodes         |  |       |                                   | |
| Flash         |  | Node  |  Detail Inspector                 | |
| OTA           |  | List  |  (selected node properties)       | |
| Edge Modules  |  |       |                                   | |
| Sensing       |  |       |  [Property Grid]                  | |
| Mesh View     |  |       |  [Status Indicators]              | |
| Settings      |  |       |  [Action Buttons]                 | |
|               |  |       |                                   | |
+-[ Status Bar ]+--+-------+-----------------------------------+ |
| rUv | 3 nodes online | Server: running | Port: 8080           |
+---------------------------------------------------------------+

面板行为规范：

• 侧栏在窄窗口下折叠为纯图标模式（对应落地令牌 --sidebar-width: 220px 与 --sidebar-collapsed: 52px，见 design-system.css）；
• 节点列表与 Inspector 之间的分隔可通过拖拽手柄调整（split 可缩放）；
• Inspector 独立滚动——下钻任意节点时不会丢失列表上下文；
• 状态栏（--statusbar-height: 32px）一目了然地呈现全局系统状态：节点在线数、服务端状态、端口。

落地实现中侧栏对应 components/Sidebar.tsx，主区路由页面由 App.tsx 组织，Dashboard、FlashFirmware、OtaUpdate、EdgeModules、Sensing、MeshView、NetworkDiscovery、Settings 等 8 个页面分别位于 ui/src/pages/ 下——ADR 草案中的 7 个页面在此扩展为 8 个，新增了独立的 NetworkDiscovery（网络发现）。

六、组件库：六大核心组件的规格与落地

1. NodeCard —— 节点状态卡

NodeCard 是 Dashboard 上逐节点信息的基本单元：

+-- NodeCard -----------------------------------------------+
|  [●] ESP32-S3 Node #2              firmware: 0.3.1       |
|  MAC: AA:BB:CC:DD:EE:FF            TDM Slot: 2/4        |
|  IP:  192.168.1.42                  Edge Tier: 1          |
|  Last seen: 3s ago                  [Flash] [OTA] [···]  |
+-----------------------------------------------------------+

• 状态圆点使用 --status-online / warning / error 三态色码；
• 卡片背景在 hover 时向 --bg-hover 过渡；
• MAC、IP、firmware、TDM Slot、Edge Tier 等技术值全部用等宽字体；
• 内置快捷操作（Flash / OTA / 更多），与桌面端 ADR-052 定义的 flash_firmware、ota_update 等 Rust 命令一一衔接。

落地组件见 components/NodeCard.tsx。

2. FlashProgress —— 烧录进度组件

对应固件烧录这一高风险操作，进度组件要同时呈现阶段、速率与剩余时间：

+-- Flash Progress -----------------------------------------+
|  Flashing firmware to COM3 (ESP32-S3)                     |
|                                                           |
|  Phase: Writing                                           |
|  [████████████████████░░░░░░░░░░]  67.3%                 |
|  412 KB / 612 KB  •  38.2 KB/s  •  ~5s remaining        |
+-----------------------------------------------------------+

• 进度条以 --accent（rUv 紫）填充，写入活跃期间带细微脉冲动画；
• 进度事件来自 Tauri 后端 FlashProgress { phase, progress_pct, bytes_written, bytes_total, speed_bps }（见 ADR-052 的 flash.rs），阶段为 Connecting → Erasing → Writing → Verifying；
• 落地于 pages/FlashFirmware.tsx，与 espflash（Rust 原生，替代 esptool.py）的进度回调绑定。

3. Mesh Topology View —— Three.js 网格拓扑视图

这是与既有可视化栈衔接最深的一个组件：传感网络的交互式 3D 可视化，节点为球体、边为表示信号路径的线段，协调器（coordinator）节点以更大的尺寸与环形描边视觉区分。

+-- Mesh Topology ------------------------------------------+
|                                                           |
|         [Node 0]----[Node 1]                              |
|            |    \   /   |                                 |
|            | [Coordinator] |   Coordinator = TDM master    |
|            |    /   \   |                                 |
|         [Node 2]----[Node 3]                              |
|                                                           |
|  Drift: ±0.3ms  |  Cycle: 50ms  |  4/4 nodes online     |
+-----------------------------------------------------------+

ADR-053 给出了可直接指导实现的 Three.js 细节：

• 力导向布局（force-directed layout）在 CPU 计算，渲染为 THREE.Group，内部由球体 THREE.Mesh 与连线 THREE.Line 组成；
• 节点球体使用 THREE.MeshPhongMaterial，其 emissive 颜色映射 --status-online / warning / error——设计令牌与三维材质直接打通，保证 2D/3D 状态语义一致；
• 边线使用 THREE.LineBasicMaterial，opacity 映射信号强度；
• 协调器节点用 THREE.RingGeometry 环形描边叠加区分；
• 相机采用 OrbitControls（平移/缩放/旋转），重置按钮回到默认视角；
• 动态数据遵循仓库既有模式：BufferGeometry + BufferAttribute 承载每帧更新的属性数据，射线拾取（raycasting）实现「点击节点 → Inspector 面板打开详情」；
• 节点加入/离开/状态变化时实时更新，几何体属性按帧刷新。

该「按帧更新 BufferAttribute」的实现范式在既有 Three.js 视觉栈中真实存在：如 subcarrier-manifold.js 使用 PlaneGeometry 建立 aHeight/aAge 两个 BufferAttribute 并在更新循环中通过 geo.attributes.aHeight.needsUpdate = true 触发重绘（subcarrier-manifold.js）；convergence-engine.js 与 figure-pool.js 同样以 THREE.Group + Mesh/Line 组织场景对象。桌面端页面落地为 pages/MeshView.tsx。

4. PropertyGrid —— Unity Inspector 风格属性网格

节点详情使用 Unity Inspector 式的分组属性网格，支撑分组的折叠与交替行背景以获得可扫描性：

+-- Node Inspector -----------------------------------------+
|  General                                            [▼]  |
|    MAC Address      AA:BB:CC:DD:EE:FF                    |
|    IP Address       192.168.1.42                         |
|    Firmware         0.3.1                                |
|    Chip             ESP32-S3                             |
|  TDM Configuration                                 [▼]  |
|    Slot Index       2                                    |
|    Total Nodes      4                                    |
|    Cycle Period     50 ms                                |
|    Sync Drift       +0.12 ms                             |
|  WASM Modules                                      [▼]  |
|    [0] activity_detect  running    12.4 KB    83 us/f    |
|    [1] vital_monitor    stopped     8.1 KB     — us/f   |
+-----------------------------------------------------------+

三个分组（General / TDM Configuration / WASM Modules）对应 ADR-052 中 Rust 侧 DiscoveredNode 与 wasm_list 返回的模块状态数据，体现了「设计系统字段 ⇄ 后端命令返回结构」的对齐关系。

5. StatusBadge —— 内联状态徽章

[● Online]    [◐ Degraded]    [○ Offline]    [↻ Updating]

小型内联徽章：状态圆点 + 标签 + 可选 tooltip。落地组件见 components/StatusBadge.tsx。

6. LogViewer —— 日志查看器

感知服务端日志的滚动视图：

+-- Server Log (auto-scroll) -----------[ Clear ] [ ⏸ ]---+
| 19:42:01.234 INFO  sensing-server  HTTP on 127.0.0.1:8080|
| 19:42:01.235 INFO  sensing-server  WS on 127.0.0.1:8765  |
| 19:42:01.890 INFO  udp_receiver    CSI frame from .42    |
| 19:42:02.003 WARN  vital_signs     Low signal quality    |
+-----------------------------------------------------------+

• 全等宽字体；按日志级别着色：INFO=正文色、WARN=琥珀（--status-warning）、ERROR=红（--status-error）；
• 自动滚动 + 暂停 + 清空控件；
• 用虚拟滚动（virtual scrolling）保障长时间日志流的渲染性能——对桌面端场景尤其重要，因为该视图直接承接线上的 UDP 接收与感知服务输出。

七、间距与栅格：4px 基数体系

一致性依赖严格的间距节奏，ADR-053 规定 4px 基数栅格与常用面板尺寸：

/* 4px base grid */
--space-1: 4px;    /* Tight spacing (within components) */
--space-2: 8px;    /* Component internal padding */
--space-3: 12px;   /* Between related elements */
--space-4: 16px;   /* Card padding, section gaps */
--space-5: 24px;   /* Between sections */
--space-6: 32px;   /* Page-level spacing */
--space-8: 48px;   /* Major section breaks */

/* Panel dimensions */
--sidebar-width: 220px;
--sidebar-collapsed: 52px;
--statusbar-height: 28px;
--toolbar-height: 44px;

实践要点：组件内部紧凑间距用 --space-1/2，卡片内边距与分组间隙用 --space-4，页面级大节奏用 --space-6/8；同一页面不要混用 4px 之外的「异数」间距。落地文件在相同变量基础上补齐了圆角、阴影与过渡令牌（见第三节），并按实际渲染将状态栏高调整为 32px。

八、动效规范：克制且目的明确

ADR-053 对动效的态度是「极简且有意义」（minimal and purposeful），并明确反对转圈 loading：

• 面板折叠/展开：200ms ease-out；
• 节点卡健康状态切换：300ms（颜色淡入淡出，而非闪烁切换）；
• 进度条填充：平滑的 60fps CSS transition；
• Mesh 图：Three.js 渲染循环 60fps，力模拟挂在 requestAnimationFrame 上；
• 不用 loading spinner——一律用骨架占位（skeleton placeholders），这一条直接面向感知数据加载的感知质量。

九、品牌表现（Branding）

rUv 品牌以克制方式渗透，避免干扰数据内容：

• 启动页（Splash screen）：rUv logo + 「RuView Desktop」+ 版本号，持续 1.5s；
• 状态栏：左对齐的「Powered by rUv」--text-muted 弱化文案；
• 关于对话框：rUv logo、版本、许可协议与文档链接；
• 应用图标：rUv 紫（#7c3aed）的「WiFi 信号 + 人形剪影」造型——恰好呼应项目「把 WiFi 变成无摄像头的感知传感器」的核心主张。

十、影响与权衡（Consequences）

正向收益：

• 面向硬件管理的专业、数据密集 UI 体验；
• 全部 8 个页面共享一致的设计语言；
• 双字体体系（mono + sans-serif）在任何信息密度下都保证可读性；
• Unity 风格面板让熟悉 IDE/编辑器工具的工程师上手自然；
• 暗色主题降低长时间监控会话的视觉疲劳。

代价与限制：

• 自建设计系统意味着无法直接用现成组件库（shadcn/ui 仅部分可用——ADR-052 技术栈中同时引入了 shadcn/ui + Tailwind CSS 作为基础层）；
• 可停靠面板为布局系统带来复杂度；
• 纯暗色主题未必适合所有用户（ADR 明确留出「未来可加浅色模式」的口子，ADR-169-adam-mode-light-theme 后续可作印证方向）。

中性判断：

• 设计系统以 CSS + React 组件实现，无重型 UI 框架依赖；
• 组件库可拆分为独立包供其他 rUv 项目复用。

十一、仓库中的落地证据链

想要进一步核对设计系统的实现状态，可沿以下路径深入：

• 设计令牌与排版、圆角、阴影、过渡的实际 CSS：design-system.css（文件头注释即注明 "RuView Design System (ADR-053)"）；
• 组件落地：NodeCard / StatusBadge / Sidebar 位于 ui/src/components/；
• 页面落地：Dashboard、FlashFirmware、OtaUpdate、EdgeModules、Sensing、MeshView、NetworkDiscovery、Settings 位于 ui/src/pages/；
• Three.js 动态数据渲染范式参考：既有可视化栈 ui/observatory/js/ 与 ui/components/（ADR-053 明确将 Mesh Topology 建立在与此一致的 BufferGeometry + BufferAttribute 每帧更新模式之上）；
• 设计系统所服务的桌面应用架构与 Rust 命令面：docs/adr/ADR-052-tauri-desktop-frontend.md。

总体而言，ADR-053 提供了一套「原则 → 令牌 → 排版 → 布局 → 组件 → 动效 → 品牌」层层递进、可直接落地的完整设计系统，而仓库中 design-system.css 与其组件的存在印证了该决策已进入工程实现阶段；对需要为 RuView 桌面端新增页面或自行构建同类传感硬件控制面板的开发者，这套规范可作为设计令牌、布局与组件的直接参照基准。