【寻迹校园 HarmonyOS NEXT 实战 35】先写全页面 Design Spec 再写 ArkUI：一个比赛项目的设计稿门禁实践

本章导读：这是"寻迹校园 HarmonyOS NEXT 实战"系列第 35 篇。本文结合 docs/design/all-pages-design-spec-v2.md、Index.ets、路由树、七组设计板和首发设备配置，复盘如何在多页面 HarmonyOS NEXT 项目中先固定页面、状态、断点、组件和文案，再把设计映射到 ArkUI 实现。

上图为原创生成的设计交付流程插画，不是项目页面截图。需求和页面树先进入 Markdown Design Spec，经确认后再映射到 ArkUI、主题 Token、路由和 Service，最后分别进行视觉与运行验收。

一、没有设计基准时，多页面最先漂移什么

失物招领不是单页展示项目。首页、匹配、发布、详情、认领、交接、消息、我的、举报和设置会共享状态与组件。如果边写代码边临时决定样式，常见结果包括：

同一个 OPEN 在不同页面使用不同颜色；
页面入口和返回路径不一致；
表单错误、空态和加载态最后才补；
Phone 端能用，大屏只是机械拉伸；
按钮文案改变了业务含义；
设计图、代码和验收截图互相矛盾；
新页面重复创建颜色、间距和卡片组件。

Design Spec 门禁的目标，是在 ArkUI 实现前把这些跨页面决策变成可评审文档。

二、本章的真实文件映射

产物	项目路径	作用
产品需求	`docs/requirements/PRD.md`	核心流程与功能边界
全页面设计稿	`docs/design/all-pages-design-spec-v2.md`	页面树、状态、断点、文案和 Token
视觉验收	`docs/design/ui-color-visual-acceptance-review-2026-08-11.md`	对比度与语义色整改
设计板清单	`docs/design/mockups/README.md`	Board 01～07 范围和版本
主壳实现	`entry/src/main/ets/pages/Index.ets`	路由、Tab 和响应式 Shell
页面路由	`common-core/src/main/ets/navigation/AppRoute.ets`	稳定路由键与参数类型
主题实现	`common-ui` 主题与资源	颜色、字号、间距、圆角

Markdown 文档是可追踪的设计合约，不是"写完就丢"的说明附件。

三、第一步不是配色，而是产品定位

Design Spec 先明确产品类型：校园工具型 UGC 应用，核心是"结构化发布---可解释召回---匿名认领---安全交接---双方确认---结案"。

这会直接影响设计选择：

不做社区信息流和关注关系；
不开放陌生人聊天；
主操作强调可信和可解释；
联系方式不进入公开卡片；
小艺只比较脱敏候选，不判断归属；
V1.0 在没有小艺时仍可完成主流程。

如果定位没有固定，视觉层再精致也可能服务错误目标。

四、用户画像怎样转成页面约束

文档把用户分为匆忙失主、拾得者和值班志愿者：

用户	痛点	设计响应
匆忙失主	字段多、走路时单手操作	三步表单、草稿、固定底栏
拾得者	害怕冒领、不愿留手机号	私密答案对照、核验门禁、固定交接点
志愿者	状态混乱、缺少处理回执	治理时间线、稳定状态标签、消息直达

用户画像不是装饰性段落。每个痛点都对应页面结构、字段或状态。

五、先画信息架构，再列页面清单

项目设计稿先建立路由树：

text 复制代码

App
├─ 主壳：首页 / 发布 / 消息 / 我的
├─ 搜索与匹配 / 详情 / 小艺辅助
├─ 发布类型 / 三步发布表单
├─ 认领申请 / 认领处理 / 安全交接
└─ 举报提交 / 举报进度 / 设置 / 我的发布

随后为每个可达页面分配 ID、目标、入口和关键状态。这样可以发现"页面存在但没有入口""按钮存在但没有路由""进度页没有返回路径"等结构问题。

六、全页面设计稿必须覆盖异常状态

只设计理想数据页面远远不够。当前 Design Spec 同时记录：

loading；
empty；
error；
disabled；
pressed 与 selected；
Photo Picker 取消；
小艺不支持；
深色首页空态；
长文本截断；
键盘与底部操作栏；
安全区和返回流程。

异常状态在设计阶段有位置，开发时才不会临时用一行红字挤坏布局。

七、Phone 画布先定义共享骨架

Design Spec 以 360×800vp 为 Phone 基准，定义状态栏、TopBar、Content、StickyAction 和 BottomNavigation 的相对区域。

百分比不是要求 ArkUI 写死坐标，而是帮助评审不同页面的视觉占比。实现仍优先使用 Column、Row、Stack、layoutWeight、最大宽度和安全区，而不是绝对定位。

八、四档断点在文档里先形成契约

断点	导航	主要布局
`sm < 600vp`	底部导航	单栏
`md 600--839vp`	顶部导航	双栏或覆盖筛选
`lg 840--1279vp`	常驻侧栏	列表/详情双栏
`xl >= 1280vp`	常驻侧栏	34%/44%/22% 三栏工作台

断点同时约束导航、内容密度和交互，不只是改变卡片宽度。

九、Index.ets 如何映射断点

主壳通过 onAreaChange 获取宽度，并集中判断：

ts 复制代码

private isMediumScreen(): boolean {
  return this.screenWidth >= 600 && this.screenWidth < 840;
}

private isLargeScreen(): boolean {
  return this.screenWidth >= 840;
}

private isExtraLargeScreen(): boolean {
  return this.screenWidth >= 1280;
}

Phone 使用 BottomNavigation，中等宽度使用 TopNavigation，大屏使用 SideNavigation。页面不各自复制一套断点常量，减少边界不一致。

十、设计稿到 ArkUI 不是逐像素翻译

设计稿提供视觉层级和组件比例，ArkUI 需要映射为可维护结构：

Design Spec 区域	ArkUI 映射
主壳	`Navigation` + `NavPathStack`
底部/顶部/侧边导航	共享 Navigation 组件
页面滚动内容	`Scroll` + `Column`
状态卡片	共享 Card、StatusPill、Icon
固定操作区	布局权重 + 安全区避让
断点分支	主壳集中判断和参数下传
数据状态	`@Local` 展示态 + Service 权威数据

像素、状态和业务责任必须同时映射，不能只抄颜色和圆角。

十一、为什么路由参数也属于设计稿

页面可达路径不仅决定返回按钮，也决定数据来源。详情页需要 reportId，匹配页需要 queryReportId，认领页需要 claimId，举报进度需要 caseId。

项目用类型化 RouteParam 集中定义参数。设计稿标明入口后，开发可以检查空参数、深链和返回栈，而不是在页面中读取不稳定的全局变量。

十二、状态动作矩阵防止出现假按钮

Design Spec 用矩阵定义每个状态能显示哪些动作。例如：

Report OPEN 可查看匹配、编辑、撤回或删除，但不能结案；
Claim PENDING 未核对时不能同意；
Claim ACCEPTED 才能安排交接；
Handoff CONFIRMED 可以确认完成，但不能自动结案；
Report RESOLVED 不再允许编辑关键字段。

页面实现和 Service 状态机都要对齐这张矩阵。只检查视觉图，无法发现按钮语义越权。

十三、中文文案表为什么是设计资产

生成式设计图中的长中文容易失真，因此项目把权威文案单独写进 Markdown，例如：

"信息相似分"；
"仅表示公开信息相似，不代表物品归属"；
"仅该拾得信息发布者可见"；
"举报人信息不会向被举报者公开"；
"选择校内交接点"；
"我已核对两段信息"。

实现时使用真实文本图层，不从位图识别文案。文案变化也可以通过 Git diff 审查。

十四、颜色必须按语义 Token 设计

文档规定品牌蓝只承担主操作、交互选中和信息相似分；丢失珊瑚、拾得绿、冲突琥珀和危险红各自表达业务语义。

如果直接从效果图取色，生成模型可能把丢失/拾得标签也画成品牌蓝。项目明确规定：位图残留不能覆盖 Design Spec 的 token 权威。这是"设计稿文档优先于生成图偶发错误"的实际案例。

十五、七组设计板怎样覆盖页面

当前设计资产按 Board 01～07 分组：

Board 01：首页、匹配、发布类型；
Board 02：发布表单、详情、小艺、认领申请；
Board 03：认领审核、消息、我的、我的发布；
Board 04：设置、举报、深色空态、小艺降级；
Board 05：安全交接、举报进度、表单异常；
Board 06：Tablet/PC 自适应；
Board 07：深色页面专项验收。

分组让设计生成、验收和修订可以局部进行，同时仍由同一 Design System 约束。

上图为原创信息架构图，不是项目截图。页面树、Board 01～07、Phone 到 xl 的断点以及 ArkUI 主壳在同一张图中建立映射。

十六、设计图生成后为什么还要视觉验收

生成图可以表达布局和视觉层级，但不能自动证明语义正确。项目额外复核：

品牌蓝正文对比度；
语义基础色是否误用于小字；
disabled 是否只降低透明度；
消息图标颜色是否过多；
大屏层级是否足够；
深色模式是否有独立 token；
候选 82/61/48 是否跨页一致。

设计板通过不等于代码通过，视觉验收和运行验收仍需分开。

十七、门禁如何避免"边写边改全项目"

推荐流程：

读取 PRD、路由和现有页面；
输出全页面 Markdown Design Spec；
确认页面树、关键状态和断点；
生成或修订视觉板；
做视觉语义和对比度验收；
建立 theme token 与共享组件；
按页面路径最小实现；
运行构建、截图和状态回归；
把偏差回写到设计与验收记录。

门禁不是要求所有细节一次定死，而是要求变更有统一基准。

十八、设计稿如何映射架构边界

Design Spec 可以注明每个区域的数据来源：

页面保存输入草稿和短生命周期状态；
ViewModel/Service 提供业务动作与可展示状态；
Repository 负责 RelationalStore 或远程 API；
主题 token 负责颜色、字号、间距和暗色；
路由层负责页面参数与返回栈；
权限和系统 Kit 通过已有 Adapter/Service 封装。

这样设计要求不会诱导开发把数据库、网络和权限逻辑直接写进 build()。

十九、首发设备声明必须独立核对

Design Spec 保留 Foldable、Tablet、PC/2in1 响应式方向，Index.ets 也存在多档 Shell；但当前 entry/src/main/module.json5 的 deviceTypes 只声明 phone。

因此可以说"保留多端响应式代码和设计基线"，不能说"应用市场已经支持 Tablet/2-in-1"。商店设备声明、真实设备测试和代码分支是三种不同证据。

二十、设计对齐不等于像素级复刻

当前项目的设计验收目标是页面层级、语义颜色、状态动作、间距和多端结构对齐。不同系统字体、动态内容、设备安全区和 ArkUI 组件行为会造成像素差异。

只有建立同设备、同数据、同字体、同截图方法的量化对比，才能谈像素误差。普通设计评审通过不能冒充"100% 还原"。

二十一、Design Spec 也需要版本管理

项目文档当前为 V2.1，并记录首次协议页已移除、旧设计板仅保留历史参考。版本说明能避免开发人员继续按旧图实现已经取消的页面。

文档修改应和页面、路由、文案、Token 及验收记录一起更新。只替换一张设计图而不说明变化范围，会让历史状态不可追踪。

二十二、如何验证设计稿真正影响了代码

可以从四类证据检查：

设计要求	代码证据
四档宽度	`Index.ets` 的 600/840/1280 判断
不开放聊天	`MessagesPage` 无输入框并显示边界文案
认领核验门禁	`ClaimReviewPage` 展开、勾选和二次确认
固定校内交接	`HandoffService` 地点白名单与时间段
治理状态顺序	`ModerationService.advance()` 来源校验
语义颜色	`AppColors` 与共享状态组件

设计文档中的关键句应能找到对应代码或明确标记为未实现。

二十三、设计与运行验证必须分别记录

设计验收可以确认布局、文案和颜色；构建可以确认 ArkTS 编译；模拟器或真机可以确认交互和系统能力；AGC 可以确认外部发布状态。

任何单一结果都不能覆盖另外三层。本章引用的 Design Spec 和代码映射不代表今天重新完成了全页面真机截图、暗色读屏或 Tablet 实机验收。

二十四、工程复盘：Design Spec 是跨层合约

优秀的 Design Spec 不只写"蓝色卡片、16vp 圆角"。它还应该回答：页面从哪里进入、依赖哪个实体、空数据如何显示、哪个状态允许哪个动作、宽度变化后什么状态不能丢、文案如何表达证据边界、系统能力不可用时怎样降级。

这些信息让产品、视觉、ArkUI、Service 和测试使用同一套语言。以后新增"申诉中"状态，团队可以同时检查状态矩阵、举报进度、消息文案、颜色 Token、路由和自动化，而不是等到联调时逐页发现遗漏。

二十五、本文小结

"寻迹校园"的设计稿门禁先固定产品定位、用户场景、页面树、异常状态、断点、动作矩阵、中文文案和 Design System，再把它们映射到 ArkUI 主壳、路由、共享组件和 Service。

当前 Design Spec V2.1、七组设计板和代码中 600/840/1280 响应式分支形成了可追踪基线；但首发 manifest 只声明 Phone，设计对齐也不等于逐像素复刻或多设备商店验收。文档、实现、视觉和运行证据必须分别报告。

系列导航：第 35 篇 / 共 50 篇。上一篇：《单机角色模拟的证据边界》；下一篇：《HarmonyOS 深色模式不是简单反色》。