【寻迹校园 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.mdBoard 0107 范围和版本主壳实现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 在没有小艺时仍可完成主流程。如果定位没有固定视觉层再精致也可能服务错误目标。四、用户画像怎样转成页面约束文档把用户分为匆忙失主、拾得者和值班志愿者用户痛点设计响应匆忙失主字段多、走路时单手操作三步表单、草稿、固定底栏拾得者害怕冒领、不愿留手机号私密答案对照、核验门禁、固定交接点志愿者状态混乱、缺少处理回执治理时间线、稳定状态标签、消息直达用户画像不是装饰性段落。每个痛点都对应页面结构、字段或状态。五、先画信息架构再列页面清单项目设计稿先建立路由树App ├─ 主壳首页 / 发布 / 消息 / 我的 ├─ 搜索与匹配 / 详情 / 小艺辅助 ├─ 发布类型 / 三步发布表单 ├─ 认领申请 / 认领处理 / 安全交接 └─ 举报提交 / 举报进度 / 设置 / 我的发布随后为每个可达页面分配 ID、目标、入口和关键状态。这样可以发现“页面存在但没有入口”“按钮存在但没有路由”“进度页没有返回路径”等结构问题。六、全页面设计稿必须覆盖异常状态只设计理想数据页面远远不够。当前 Design Spec 同时记录loadingemptyerrordisabledpressed与selectedPhoto 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获取宽度并集中判断privateisMediumScreen():boolean{returnthis.screenWidth600this.screenWidth840;}privateisLargeScreen():boolean{returnthis.screenWidth840;}privateisExtraLargeScreen():boolean{returnthis.screenWidth1280;}Phone 使用BottomNavigation中等宽度使用TopNavigation大屏使用SideNavigation。页面不各自复制一套断点常量减少边界不一致。十、设计稿到 ArkUI 不是逐像素翻译设计稿提供视觉层级和组件比例ArkUI 需要映射为可维护结构Design Spec 区域ArkUI 映射主壳NavigationNavPathStack底部/顶部/侧边导航共享 Navigation 组件页面滚动内容ScrollColumn状态卡片共享 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 0107 分组Board 01首页、匹配、发布类型Board 02发布表单、详情、小艺、认领申请Board 03认领审核、消息、我的、我的发布Board 04设置、举报、深色空态、小艺降级Board 05安全交接、举报进度、表单异常Board 06Tablet/PC 自适应Board 07深色页面专项验收。分组让设计生成、验收和修订可以局部进行同时仍由同一 Design System 约束。上图为原创信息架构图不是项目截图。页面树、Board 0107、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 深色模式不是简单反色》。