当一个 ArkUI 应用从首页扩展到实时字幕、OCR、任务、历史和设置，最先失控的往往不是业务逻辑，而是页面里散落的颜色、圆角、间距和阴影。听见课堂把这些视觉决策集中在 AppTheme.ets，让 12 个主页面与手语、文字沟通页面共享同一套语义。

一、Token 解决的是变化传播问题

如果每个页面都写 16、#FFFFFF 和 20，单页看起来也许正确，但暗色模式、phone 压缩和 2in1 大屏重排会迫使开发者逐处搜索。Token 的价值不是少写几个常量，而是让一次设计决策有唯一入口。

项目把颜色放进 AppColors，把布局和材质参数放进 AppSizes。页面引用语义名，不直接猜具体值。

二、颜色名必须表达用途

PRIMARY、TEXT_PRIMARY、SURFACE_READABLE、BORDER_GLASS 分别表示操作强调、主文字、可读表面和玻璃边界。相比 BLUE_1 或 WHITE_80，用途名能告诉调用者“为什么用”。

static readonly PRIMARY: string = '#087EA4';
static readonly TEXT_PRIMARY: string = '#102A43';
static readonly SURFACE_READABLE: string = '#B8FFFFFF';
static readonly BORDER_GLASS: string = '#C7FFFFFF';

当品牌色或材料透明度改变时，调用页不用知道新色值，只继续消费同一语义。

三、表面不是只有一张白卡

项目定义了 SURFACE_GLASS、SURFACE_READABLE、SURFACE_SOFT、SURFACE_INPUT 和 SURFACE_FLAT。它们对应不同的信息密度：主内容要保证阅读，辅助区可以更轻，输入区要和展示区可区分。

同一页面若全部使用最强玻璃和最大阴影，层级反而消失。Token 让“主卡、普通卡、软提示”有可复用的材料梯度。

四、暗色不是给背景取反

每类关键表面都有 _DARK 版本，分割线、阴影和危险状态也单独定义。暗色下继续使用浅色半透明白，会造成发灰；只把背景变黑，则会让边界、禁用态和文字对比失去控制。

页面通过 preferences.darkMode 选择语义 Token，暗色适配仍然集中在主题层，而不是在每个 Builder 中复制一套十六进制色值。

五、尺寸 Token 同时承担布局契约

PAGE_PADDING、CARD_PADDING、CARD_RADIUS 是通用尺寸；phone 又有更紧凑的 PHONE_PAGE_PADDING、PHONE_SECTION_GAP 和导航高度。

static readonly TOUCH_MIN: number = 48;
static readonly PHONE_PAGE_PADDING: number = 16;
static readonly PHONE_TOP_BAR_HEIGHT: number = 52;
static readonly PHONE_BOTTOM_NAV_HEIGHT: number = 64;
static readonly LARGE_BREAKPOINT: number = 840;

这些值不是纯装饰。底栏高度、安全区、内容滚动范围和触达目标都依赖它们。

六、48vp 是交互面积，不是图标尺寸

底栏图标可以是 22vp，但承载它的按钮应提供至少 48vp 的有效触达区域。若开发者把 TOUCH_MIN 直接理解成图标边长，视觉会笨重；若只把 22vp 图标设为可点击，键鼠和触屏都容易误操作。

因此 Token 需要和组件结构一起使用：外层控制响应区，内层图像控制视觉尺寸。

七、模糊分成 Hero、Card、Soft 三档

项目使用 GLASS_BLUR_HERO=30、GLASS_BLUR_CARD=24、GLASS_BLUR_SOFT=18。Hero 用于导航壳或核心焦点，Card 用于主要内容容器，Soft 用于轻提示或次级块。

这三档形成明确层级，也避免每个页面随手写一个 blur 值。模糊仍须和表面透明度、边框、阴影共同评估，不能单独决定可读性。

八、phone 与 large 不应只有等比放大

phone 页面边距为 16vp、顶栏 52vp、底栏 64vp；大屏侧栏宽度是 248vp，并在内容区保留更宽的外边距。大屏需要信息分栏和键鼠焦点，手机需要拇指可达和沉浸式内容，两者不能靠整体缩放完成。

共享 Token 保证风格一致，设备分支 Token 保证布局合理，这两件事并不冲突。

九、新组件应先选语义再写样式

新增卡片时先回答：它是主要阅读、辅助信息还是输入？是否需要点击？是否在暗色中出现？phone 和 large 是否共用结构？确认语义后再组合 SURFACE_*、BORDER_*、blur、radius 和 padding。

如果现有 Token 无法表达新语义，应先审查是否真的出现了新材料层级，而不是立即在页面里硬编码。

十、Token 不能替代组件封装

集中常量只能统一原子决策，重复的卡片结构、状态图标和导航按钮仍应封装为 Builder 或共享组件。否则十几个页面虽然颜色相同，内部对齐、按压态和无障碍文本仍会漂移。

最佳边界是：Token 管视觉语言，组件管结构和交互，页面只负责组合当前业务内容。

十一、验收要查使用结果而非常量存在

静态检查可搜索页面中的裸色值、零散圆角和小于 48vp 的交互容器；运行验收还要覆盖浅色、暗色、phone、835vp 附近窗口和宽屏。长标题、空态与错误态同样要进入矩阵。

Token 文件存在不代表页面真正复用。最终证据应来自源码引用、UI 树尺寸和实际截图三类结果。

十二、边界与下一步

当前主题系统已覆盖项目的主要材料与尺寸，但它不是自动化 Design System：字体层级仍有页面内配置，系统 1.5 倍字体和真实屏幕阅读器也不能由 Token 测试替代。

统一 12 个页面的关键，是让颜色、尺寸和材料有稳定语义，让响应式差异留在合理分支中。下一篇继续拆解大屏 LargeAuroraBackground 如何形成连续光场，同时不截获任何交互。