# Build Polished Visual Frontends > 构建、重做、诊断或提升最终由浏览器消费的高完成度视觉前端。用于 HTML/CSS/JS/TS、React/Vue/Svelte/Astro、SVG/Canvas/WebGL 或 web-to-print 的网站、产品界面、数据故事、图解、地图、仿真与游戏；负责真实标杆、表达强度、成熟框架与设计系统、专业 Web 引擎、代表画面和最终像素质量，并与一份主要领域 Skill 组合。不用于纯后端、原生应用或仅以网页作为临时查看器的非 Web 母版。 - Skill: `evermind-ai/build-polished-visual-frontends` (Agent Skill, multi-file: 36 files) - Install (CLI): `npx skillmds@latest add evermind-ai/build-polished-visual-frontends` - Raw SKILL.md: https://api.skillmd.com/api/skills/evermind-ai/build-polished-visual-frontends/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: EverMind-AI (https://skillmd.com/u/evermind-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/evermind-ai/build-polished-visual-frontends --- # 构建高完成度视觉前端 ## 核心目标 让用户直接完成任务，让视觉、交互和专业对象来自同一组清楚的决定。让成熟工具解决已经 解决的问题，把模型的判断留给当前产品独有的任务、构图和体验。 遵循三个原则： 1. **任务决定形态。** 不因交付是 HTML 就默认应用壳、dashboard、landing page、卡片网格或 16:9。 2. **一套视觉语言。** 控件、导航、列表、面板、专业画布和反馈必须像同一个产品。 3. **标准能力交给工具。** 模型主要设计任务模型、工作顺序、整体构图和必要的连接层。 主要领域 Skill 决定内容模型、专业语义和领域门槛；`visual-artifact-design` 决定共享流程与 证据；本 Skill 只负责浏览器中的视觉方向、技术组合、工具边界和最终像素。用户当前要求与 已接受参考优先，其次是既有品牌、平台和领域约束。题材联想不能为任意颜色或装饰提供理由。 什么算好，八条判据（后文以代号引用）： - **J1 主角与胆量**：每个交付面能指认主角时刻，且有一个超出安全默认、能一句话说出的决定。 - **J2 删测**：删掉后页面不变差的元素，必须删。 - **J3 一句话可述**：整个产物能被一句话描述（“这是一张……的页”）；说不出即没有方向。 - **J4 具体胜过修辞**：每个宣称可验证；用事实、真数字和真对象替代形容词。 - **J5 主视觉先行**：内容型／营销型 Web 先用真实成图锁定世界、空间与取景，再围绕它排版； 不允许先完成模板图槽，再用一张可拆换的图补空。 - **J6 细节成系统**：字体、标点、边界、图标、状态、运动与目标环境适配共同实现同一视觉命题； “没有命中反模式”不等于已精致。 - **J7 逐区成品**：每个可见区块和页面族都有明确职责、任务特有的内容关系与完成态；不能精修 首屏后，把其余部分留成默认组件、文字倾倒或模板余料。 - **J8 示能诚实**：任何看起来可点击、可选择、可展开或可切换的东西都兑现相应行为与反馈； 静态内容不借用按钮、选中态、悬停态或可点击卡片的视觉暗示。 ## 1. 先读懂任务，再决定画什么 新建方向或大改前，先写一张短决策卡： ```yaml 任务: 谁在什么场景完成哪一件主要事情 主要对象: 页面中真正需要看、读、编辑或操纵的对象 自然形态: 页面、工作台、长文、画布、地图、图解、游戏或其他形态 领域惯例: 该领域真实从业者交付此物时的成品形态与表达习惯；偏离惯例必须写出理由 参考与偏好: 实际看见的参考，以及用户明确喜欢和拒绝的特征 表达强度: quiet | editorial | expressive 视觉系统: 哪一套成熟设计语言负责字体、控件、表面、图标和反馈 专业引擎: 哪个领域工具负责图表、地图、排版、媒体、画布或其他核心对象 衔接合同: 两者如何共享 token、状态、字体、颜色、焦点、图例和导出 目标画面: 最能决定方向的尺寸、内容密度和关键状态 ``` 真实参考依次来自用户提供的画面、已接受的同项目产物、实际生产产品和成熟公共系统。参考先 回答领域惯例：该领域真实从业者交付这类产物时，成品长什么样、用什么表达；产物先像该领域的 真实交付物，再谈风格取向。必须看到真实画面再提取 3–6 个可观察特征；品牌印象、文章描述和 模型记忆不算视觉证据。需要自行 研究时，只查看覆盖主要风险的少量真实工作态、密集态和合同所列目标环境，不照搬独特版式、资产或 文案。按需读取[审美路由](references/aesthetic-routing.md)。 表达强度由任务和参考决定： | 强度 | 常见任务 | 默认表现 | | --- | --- | --- | | `quiet` | 产品、数据、地图、技术工作 | 让主要对象与状态主导；层级来自比例、字重、间距和关系 | | `editorial` | 内容网站、字体、演示、出版 | 用排版、图像角色、节奏和叙事顺序形成方向 | | `expressive` | 品牌、营销、插画、游戏 | 可使用强色彩和动效，但每个强信号都承担传播、叙事或玩法职责 | ### 内容型／营销型 Web 的前置参考分流 内容型或营销型 Web 在形成视觉方向之前，先分别锁定两条路线并写入 `REFERENCE-CONTRACT`：`identity_route` 决定 标识、色、字与既有视觉语言；`layout_route` 决定宏观结构与阅读顺序。`identity_route` 取 `accepted_system` 或 `none`；`layout_route` 取 `pool_template` 或 `observed_benchmark`，不因 `identity_route` 已锁定而省略。合同中至少 一条宏观结构／阅读顺序关系必须来自 `layout_route` 的来源画面。 - `accepted_system`：用户已接受的参考、品牌系统或质量合格的既有视觉语言能够约束当前页面； 必须保存实际可查看的来源画面，名称、印象和模型记忆不算证据。它约束身份，不提供版式参照。 - `pool_template`：没有可沿用系统，且模板池存在不违反任务硬约束的候选；先完成 [模板池](references/template-pool/POOL.md)「第零步」翻译、逐张查看候选截图并选定主要骨架。 - `observed_benchmark`：池中没有该形态候选，或每个候选均与已经声明的硬约束冲突；逐候选记录 来源画面、冲突约束、证据，以及为何通过内容替换、token 重映射或结构裁剪仍无法解决，之后才 允许选择真实生产标杆。 硬约束只来自用户要求、品牌、内容结构、功能、许可或运行环境；模型偏好的气质、色相、实现便利、 学习成本和「想手写」都不是硬约束。视觉参考路线与实现底座分开记录：clone、既有框架、预装骨架 或最薄手写骨架只是 `implementation_base`；手写代码不等于可以自创视觉语法，网络或 clone 失败也 不自动撤销已经锁定的参考关系。 按[审美路由](references/aesthetic-routing.md)建立 `REFERENCE-CONTRACT`：记录实际来源帧、3–6 条 可观察关系、允许迁移轴、不可迁移项、实现对象和代表帧／终态证据。每条关系使用 `fact_id / source_frame / observed_relation / protected_axis / target_object / representative_frame_evidence / final_frame_evidence / deviation_constraint`；至少包含一条宏观结构或 阅读顺序、一条层级或密度关系、一条主对象或图像角色，只记录颜色关系不算完成。引用名称、描述 气质或只写进 brief 只是建立假设，不算参考已经执行。在 `identity_route` 与 `layout_route` 与合同完成前，不得生成视觉方向、风格合同或写第一行页面代码。 ### Web 技术底座预构建 gate 新建 Web 工程时，在生产视觉资产或实现页面前，先用当前环境声明的 initializer 与正式构建入口， 在临时探针目录完成一次空工程构建。具体命令、冻结档位与联网依赖方式只以 [工具运行手册](references/tool-install.md)和当前 runtime 能力清单为准，不写成跨环境的审美要求。 这次探针只证明底座可用，不构成代表画面或页面完成度。失败时停止实现并保留原始错误；不得通过 修改项目配置、复制依赖、手工建立依赖链接或绕开正式入口来吸收 runtime 缺陷。通过后清理探针， 再按已锁定的 `implementation_base` 开始项目。 ### 内容型／营销型 Web 的主视觉前置 gate 参考合同锁定后，先在 `DESIGN-BRIEF.md` 建立 `VISUAL-THESIS`，再建立 `MASTER-VISUAL-CONTRACT`。参考合同负责经验证的结构与章法；视觉命题负责项目身份。 参考是骨架，不是最终画面的身份来源。 `VISUAL-THESIS` 必须包含： ```yaml world: 用户进入什么具体世界 tension: 哪两个真实力量、时间或状态形成张力 memorable_moment: 三秒内最应被记住的画面 identity_strategy: 如何让产物区别于参考模板与通用同类页 manifestations: 视觉命题如何逐区进入主视觉、排印与规则、内容结构、交互与运动 ``` “高级、克制、科技感、编辑感”等形容词不算命题。`manifestations` 必须覆盖最终产物的每个 顶层区块和页面族，写清它在那里通过什么对象、关系或行为成立；只列三处亮点、只精修首屏， 或用一句全局配色概括整页，都只是文档作文。无用户已接受的项目身份时，可以在参考合同的 `free_axes` 内提出 2–3 个互斥身份策略；候选只改身份与媒介，不重做已锁定的宏观布局。 `MASTER-VISUAL-CONTRACT` 必须包含： ```yaml role: world_builder | identity_carrier | narrative_stage semantic_job: 它独自建立或传达什么 subject_and_action: 具体主体、动作与关系 composition: 视觉中心、空间层次与版面接口 copy_safe_zone: 可叠字区和最低对比要求 crop_anchor: 各目标画幅的焦点；盲裁失效时用 image edit 派生专用版本 asset_family_id: 母版与派生资产共用的家族标识 asset_family_plan: 同源不变量 / 页面族开场 / 后续辅助视觉 / 表现型符号 / 真实资产与精确图形层 page_family_visual_map: - page_family: 页面族 opening_job: 开场首先要完成的阅读或操作职责 visual_role: dominant_background | integrated_visual_field | content_first asset_lineage: 母版、同源裁切或 image edit 派生关系 reason: 选择该角色的任务证据 final_evidence: 最终入口与开场像素证据 truth_boundary: 不承担的事实、数据、人物或产品责任 final_asset: 成图、尺寸、lineage、原图查看与页面引用证据 ``` 新建或大改的公开内容站与营销站，默认先由 `image_generate` 取得一张项目级主视觉母版；已有的 合法真实资产只有在能完成同一 `semantic_job` 且用户或权威来源允许时才可替代。每个主要页面族 在布局前都要进入 `page_family_visual_map`，默认选择 `dominant_background`。`integrated_visual_field` 与 `content_first` 只对当前页面族的开场职责成立，不能用一个理由批量覆盖其余页面族；文字多、包含事实、没有真图、 担心生成图被误认或担心可读性，都不能单独构成选择这两种角色的理由。`visual_role` 的声明须与渲染返回的 `opening_visual` 读数相符：声明 `dominant_background` 而读数显示标题与图像重叠为 0%，即为不符，改声明或改图； 读数标为 `uniform` 时必须在 `reason` 中说明该区域为何属于画面；读数未回填或 `uniform` 无说明，该页面族的 `visual_role` 视为未结账。默认先按大背景路线完成代表帧；若实际像素显示它妨碍主要阅读或操作任务， 先检查构图、裁切与文字关系。若冲突来自任务本身，可改用 `integrated_visual_field` 或 `content_first`， 在当前页面族的 `reason` 与 `final_evidence` 中记录具体冲突、调整前后像素和主要任务改善的证据， 并更新参考合同与视觉角色声明。不得仅因实现便利、生成失败、资产成本或模型偏好放弃主视觉路线， 也不得把单个页面族的例外推广到全站。页面族可以复用母版的有意义裁切，或用 image edit 派生适配构图， 不要求每个内容实体重新生成。 `dominant_background` 只约束页面族开场，不要求每个后续区块重复铺图。离开开场后，可由同源资产、 排印关系、内容结构或交互继续身份；但不能退回与视觉命题无关的默认内容块。 主视觉母版必须在写页面 DOM、布局 CSS 或改造模板版式前真实取得并查看，之后才能围绕成图 决定标题位置、色彩、表面、边界与开场节奏。主视觉不授权制造空洞的营销壳面：主对象、主任务或 阅读起点仍须在同一画面成立，也不得烘焙关键文字、logo、数据、产品界面或事实证据。 `dominant_background` 不是面积较大的图片，而是开场构图的空间底座：它必须在无需滚动的画面可见， 是最大的非文字视觉场，标题、主要对象或操作进入其安全区、焦点、层次或边缘关系，图像裁切会直接 改变排版。仅把大图放在文字旁边，即使面积足够，也只是 `integrated_visual_field` 或普通图槽； 半出血只有在内容真正锚定进图像构图时才成立。`content_first` 的最终像素必须证明主要任务因此更 清楚。一个站若只有首页使用主视觉，其余主要页面族全部退回普通纸面、表格或默认模板，仍未形成 视觉系统。 `image_generate` 失败是能力缺口，不授权先用占位完成布局，也不授权改用 CSS 渐变、手写 SVG、 Canvas 或发光几何模拟。此 gate 没有真实母版、原图查看、完整页面族映射和对应最终开场像素即未完成。 ## 2. 立意与方向，再落到一套视觉系统 在本节做出任何方向决定之前，完成两次阅读，顺序固定——先立标尺，后排雷： 1. **先例**：读取 `references/design-precedents/page-1.jpg`（使用规则与类型索引），再按本任务的 产物类型读取对应页。先例给出该类型的风格谱系与已被验证的决策，是标尺和词汇，不是模板。 2. **风险路由**：按 `$review-against-ai-patterns` 第 1 节读取图鉴索引，并按实际风险读取标本页。 然后在工作区根目录（`submission/` 之外）建立两份工作证据，与产物同为交付的一部分。工作证据是 随实现更新的短决策账本，不是说明报告：只记录会改变事实、像素、资产、行为或验收的决定，不得 复述本 Skill、附件或模板说明。方向阶段先登记风险与实现落点，完整逐项结账留到终态。 **`DESIGN-BRIEF.md`**——正面：要什么。包含： - 第 1 节的决策卡； - 内容型／营销型 Web 的 `identity_route` 与 `layout_route`、`implementation_base` 与 `REFERENCE-CONTRACT`； - **条件式方向候选**：只有参考合同仍留下结构、媒介或叙事上的实质不确定性时，才提出 2–3 个 互斥候选并写出关键视觉取舍；否则直接采用已锁定方向，不为满足数量制造候选。选择模板时， 池内候选本身就是方向候选，不得另造一组越过模板事实的独立风格方向； - **先例参照**：选定方向参照了哪个先例的哪条决策，并逐区写明它在产物中的实际落点（概念锚点）； - 内容型／营销型 Web 的 `VISUAL-THESIS`、`MASTER-VISUAL-CONTRACT`、页面族视觉映射与实际母版证据； - **`DETAIL-CONTRACT`**：包含 `SURFACE-MANIFEST` 与 `COMPONENT-BEHAVIOR-MAP`。前者覆盖页面族、 顶层区块、独特状态与视觉例外，记录职责、主要对象、顺序、资产和最终证据；后者按独特行为类 记录示能、动作、反馈、恢复与自动遍历入口。由同一组件、状态合同和数据规则产生的重复实例可 共享视觉证据，但每个真实目标仍须由浏览器自动遍历；静态项若产生交互暗示，必须移除暗示或补齐 行为，不能靠文档解释过去； - **图像来源清单**（按第 3 节图像来源纪律填写与更新）； - **工具清单**（按第 3 节要求填写与更新）。 **`ANTI-SLOP-CHECK.md`**——负面：避什么。内容、格式与结账规则见 `$review-against-ai-patterns`。 先检查仓库已有框架、组件、字体、图标、浏览器支持、离线要求和许可。已有系统质量合格且 覆盖任务时直接沿用，不为追新制造第二套语言。 新建 React 产品界面且没有既有品牌或平台约束时，先查看 Appica 的真实样张，再与一至两个适合 当前任务的成熟系统比较。环境提供 `visual-web-info` 时，全部候选样张一律来自其 visual catalog 的本地图版；可联网时用 [Appica UI](https://appica.dev/ui) 与各系统官方页面。 Appica 优先进入候选，但不自动获胜；选择能以最少例外覆盖任务、状态、密度、无障碍、部署和 用户偏好的那一套。按需读取[设计系统路由](references/design-system-routing.md)。 视觉系统与专业引擎是两次不同的选择。视觉系统回答“整个产物如何说话”，专业引擎回答“核心 对象如何正确工作”；任何一方都不能替代另一方。地图引擎、图表语法、分页器或媒体引擎的默认 皮肤不自动成为成品审美，组件库也不能替代制图、统计编码、出版排版或媒体语义。两者都必须查看 真实样张，并在代表画面中证明可以融合成一种语言。 选定后，从真实样张、token 或计算样式中提取一份简短风格合同。内容型／营销型 Web 还必须先 查看已取得的主视觉母版，再把成图中真实存在的色域、光线、边缘、材质和空间节奏映射进合同；不得 先写一套皮肤再要求背景服从它： ```text 字体角色与字重 / 控件高度与密度 / 间距步进 / 圆角族 表面与分隔策略 / 中性色与语义色 / 图标规格 / 焦点、反馈与运动 ``` 主设计系统负责全部可见界面语言，而不只是几个按钮。导航、筛选、列表、面板、空态、通知、 自定义组合组件和专业画布周边都消费同一合同。遮住现成控件后，剩余页面仍应像该系统自然 延伸出的产品；否则先统一系统，不继续补局部样式。 专业引擎内部可以保留其经过验证的对象语法，但字体、强调色、背景、选中、焦点、图例、tooltip 和控制层必须映射到风格合同。无法映射时应更换工具、缩小自定义边界或把它明确做成独立嵌入物， 不能在同一连续表面上留下两套视觉语言。 ### 字体选型（中西文都必须显式选型） **裸用系统兜底链（system-ui/PingFang/雅黑/Noto Sans 链）交付＝没有选型**，与手写控件同级的 退化——中文标题一旦落回默认黑体，任何模板与配色都长成同一张脸。风格合同的字体行必须写明 标题字、正文字、等宽字的具体字面与选择理由。环境可出网时按下表从 npm 取字体 （`npm i <包名>`，按需子集化控制体积）；拉丁字体可沿用模板自带的；安装失败才降级系统字体 并在 BRIEF 记录理由。 | 页面气质 | 中文标题/正文 | npm 包 | 拉丁配对 | | --- | --- | --- | --- | | 编辑、文化、档案、氛围 | 思源宋体（标题用足字重） | `@fontsource/noto-serif-sc` | `EB Garamond` / `Libre Caslon` | | 屏显人文、手记温度 | 霞鹜文楷 | `lxgw-wenkai-webfont` | `Inter` / `Source Serif 4` | | 科技、工程、产品 | 思源黑体（Bold/Black 当标题，禁 Regular 大字） | `@fontsource/noto-sans-sc` | `@fontsource/space-grotesk` / `Inter` | | 数据、代码、编号点缀 | — | `@fontsource/jetbrains-mono` | 同左 | 标题的性格来自**字重与字号的极端对比**加上正确的字族，不来自加粗系统黑体； 中西文混排时拉丁与中文的字重视觉密度要对齐（拉丁常需降半档字重）。 ## 3. 让成熟工具承担成熟能力 动手前先问:这个能力有没有人已经做好了?常用工具已在只读实验环境中锁定;使用方式见 [工具运行手册](references/tool-install.md)——**需要的能力优先从锁定 runtime 选择并实际使用, 禁止读取宿主仓库**。**环境可出网时,联网外采是被允许且被期待的**:模板按模板池条款 clone, 字体按字体选型表 npm 安装,依赖走 npm registry——外采来源记入 THIRD_PARTY_NOTICES; "锁定"指预装档位,不构成禁止外采。无网环境才禁止联网安装。环境未覆盖时先换已锁定的候选, 全部不覆盖才记录能力缺口。**重新造轮子默认禁止**:任何自建实现,必须先在 `DESIGN-BRIEF.md` 的工具清单里写明调研过哪些现成工具、不用的一句理由;写不出调研过程就 不允许自建。锁定候选确实都不覆盖时才允许降级自建,并在交付说明中写明。 遇到以下能力时,先寻找并实际检查成熟工具,不从事件监听、焦点管理、绘制算法或存储细节 开始手写: - 选择、日期、拖放、弹窗、通知、表格、虚拟列表、上传等标准交互； - 键盘、触摸、撤销、序列化、导出、跨浏览器状态或无障碍要求； - 图表、地图、流程、富文本、媒体、图像、2D/3D、物理或游戏等专业对象； - 大数据、大文件、本地持久化、协作和明显的性能风险； - 用户、仓库、品牌或平台已经指定的合格工具。 简单静态排版和一个语义完整的浏览器原生控件不必增加依赖。工具不是越多越好；每个工具都 必须消除一个真实风险，并且每项能力只有一个主要负责人。 ### 如何选型 1. **先拆能力。** 列出页面框架、可见控件、专业对象、数据或文件处理、持久化、导出和验证， 写清每项最难的状态以及目标设备、离线和交付要求。 2. **先看现有环境。** 以 `visual-web-info --json` 和系统可执行命令为准；能完成任务就沿用， 不能时，再从同一锁定环境为关键能力列 2–4 个候选。 **例外(优先级已定):有网环境的内容型/营销型站点,模板池优先于预装骨架**——真实设计师的 模板是更高的美学与结构基线,预装骨架只在池内无匹配形态、或候选经截图目检确不适配时才用, 且降级理由必须写进「技术底座」。"骨架就在环境里、阻力最低"不构成理由。 3. **看真实能力。** 环境提供 `visual-web-info` 时，先读其 visual catalog，逐张查看进入决选候选 的本地样张，每看一张当场记下图版文件名和一条可观察画面特征，这份记录直接成为决策卡的 「候选」栏；可联网时打开官方样张与文档。之后在当前环境运行能覆盖最难状态的最小示例。 样张不可达不构成跳过理由，更不允许退回凭名称、榜单或模型印象决定。 4. **按任务比较。** 依次比较任务覆盖、原生数据或场景模型、状态与无障碍、视觉默认值与主题能力、 框架集成、离线与浏览器、性能、维护、许可和包体；视觉新奇度不能覆盖硬约束，也不能把默认主题 的截图当成项目已经完成设计。 5. **划清职责。** 一项能力交给一个主工具。其他工具只能补它明确不负责的部分；两套组件系统、 两个图表语法或自制控件与库控件不能同时争夺同一表面。 6. **原生采用。** 使用工具的组件、状态、数据模型、键盘语义、主题和导入导出路径。让专业工具的 输出成为主要对象，不要把它缩成手写卡片中的装饰图。只导入一个按钮、一个图形标记或一个函数， 不算真正使用。 7. **最后才自定义。** 先比较锁定的替代工具；仍无法覆盖时，只实现被证明确实缺失的最小边界。 不得把宿主路径当作逃离实验边界的办法(有网时的联网外采按上文条款执行,不属逃离)。 新建方向或更换主要工具时，把这张决策卡写入 `DESIGN-BRIEF.md` 的工具清单，不再是可选记录， 只回答七件事： ```yaml 能力: 要解决什么，以及最难状态是什么 候选: 逐张列出实际查看的图版文件名并各附一条可观察画面特征，写不出的候选视为未查看，不得进入结论；落选者各写一条可观察理由 选择: 选了什么，为什么它需要的例外最少 气质: 选中者的样张特征与本任务受众为何匹配 职责: 它负责什么，不负责什么 衔接: 如何服从主设计系统 验证: 最终产物中如何证明它真的工作 ``` 这份选择与验证记录属于工作证据，不是界面内容。候选比较、包版本、hash、claim ledger、工具调用和 内部限制默认留在 brief、源码或 evidence；面向评审与流程的话语（候选状态、审批免责、制作说明） 不进入面向使用者的画面。最终界面只显示用户完成当前任务所需的来源、状态、限制和下一步，并按 形态阶梯处理：能成为交互对象或结构化占位的不做静态标注，能做成设计化格律标注的不写免责小字。 不要把内部治理直接排成横幅、状态条、卡片墙或灰色微文案。 ### 口述例：离线照片筛选工作台 用户要一个不上传云端的本地筛片网页：拖入照片、方向键浏览、按键保留或淘汰、放大细节、 导出清单。本例只示范选型方法；不要复制它的题材、布局、配色、文案、快捷键或技术栈。 先识别成熟能力：文件导入、高清查看、数百张缩略图滚动、EXIF 解析、本地恢复、清单导出—— 全部有成熟工具；只有保留/淘汰的状态模型、审片顺序和画面构图是这个产品独有的问题。可见 界面比较两三套成熟系统的真实工作态，选例外最少的一套负责全部可见控件；专业能力各交给 专门工具（图片查看、虚拟滚动、IndexedDB、EXIF、CSV 各一个主责工具），它们不能各自发明 视觉风格。模型只编写状态模型、工具连接、整体构图和风格衔接。某工具的最小示例覆盖不了 需求时，先检查替代工具；都不合适才只实现被证明缺失的最小边界，而不是接管整个查看器。 最终以真实操作、刷新恢复和可重新解析的导出证明工具被使用；`package.json` 里出现依赖名 不算证据。 复杂图表、地图、编辑器、媒体、仿真或游戏同样遵循这套方法。按需读取 [技术栈路由](references/stack-routing.md)。 ### 模板池(有网环境的内容型/营销型站点) 第 1 节的前置分流决定视觉参考，本节只处理实现。`pool_template` 选定后使用 `git clone --depth 1` 获取并深度定制；无法 clone 时可以更换 `implementation_base`，但仍须落实 已从候选截图锁定的参考合同。`observed_benchmark` 也只能用最薄骨架承载已观察事实，不能把 「手写」当作新的视觉路线。 模板不豁免反模式图鉴：示例内容与占位图全部清除。主视觉与资产家族仍按前置合同生产，模板图槽 不能反向决定资产计划。配色按 POOL 的色彩关系执行，结构、层级、图像角色与节奏按 `REFERENCE-CONTRACT` 执行，字体显式选型；外采来源记入 THIRD_PARTY_NOTICES。 ### 视觉资产前置路由 构建代表画面前，先按整页定义图像角色，再按主要区块列出具体图像与 icon 槽位。每项填写 `semantic_job`（它独自传达什么）、与主视觉／排印／内容结构／交互中哪两项形成关系，并选择且只选择 一个 route；同系列资产另填 `asset_family_id / master_asset / derived_from / final_size_check`。 只用于填空、显得高级或增加题材气氛的资产删除： - `truth_asset`：任务资产、官方资产或可运行对象的真实截图； - `standard_symbol`：既有设计系统或一个成熟 icon 家族中的标准功能符号； - `generated_visual`：由 `image_generate` 创建的照片、场景、插画、纹理、表现型 icon、feature pictogram，或其他质量依赖构图、画风、材质、光影、有机形体与系列一致性的视觉资产； - `exact_graphic`：由真实数据、文字、坐标或拓扑驱动的专业图表、地图、技术图形或结构关系。 不存在 `manual_svg`、`decorative_css` 或 `placeholder_as_final` 路线。搜索、关闭、菜单等标准功能 icon 来自现有设计系统或一个成熟家族；章节、类别、能力和场景等项目独有的表现型 icon／pictogram 走 `generated_visual`。它们先生成家族母图，再用 image edit 派生变体，并在最终显示尺寸检查轮廓、 透明背景与一致性；favicon 不代表页面已形成表现型 icon 家族。没有独立语义时不添加 icon，不能 为了显得丰富而给每个标题配图标。若需矢量交付，使用专业工具从已生成母版转换，不由模型重画； Logo、公共／安全符号和品牌母版继续使用权威资产或对应专业工具。 `generated_visual` 必须有成功工具调用、原图查看、最终文件引用和生成／编辑范围记录。工具不可用 或调用失败是能力缺口，不授权改用手写 SVG、CSS 渐变、发光几何或 Canvas 装饰。SVG 是输出格式， 不是自绘许可：只允许权威矢量资产、成熟库资产、专业图形工具输出和数据／文字／拓扑决定的最小 精确几何。内容型页面的主要生成资产必须在代表画面中使用真实成图，禁止用占位框先定版再补图。 主视觉进入代表画面并稳定后，再按 `asset_family_plan` 生产子素材。页面存在后续关键区块、不同 页面族或需要快速辨认的类别时，优先把主视觉作为 image edit 输入，派生章节视觉、局部背景、纹理 或表现型 pictogram；若直接编辑会破坏小尺寸语义，先产出同命题的家族母图再派生。子素材不必重复 母版主体，但必须继承足以被看出的形体、视角、光线、材质、色域或背景处理。复制文件、机械裁切、 统一套滤镜或用互不相关的新 prompt 分别抽卡，都不构成资产家族。 ### 图像来源纪律 素材与能力同理。产物里的每一张非代码绘制图像，来源都必须走完一条固定的优先级阶梯， **高档可得时禁止用低档**： 优先级只在同一 `semantic_job` 内比较；一张可作档案证据的真图不会自动取消“建立整页世界”的主视觉角色， 除非它确实能完成同一语义工作且用户已接受。 1. **任务资产里的真图**。动手前先穷尽搜索工作区与任务材料（全部 png/jpg/webp/svg，包括草稿、 文档、测试记录之类不起眼的目录，逐张查看），产品截图、实物照片、官方物料 一律优先采用； 2. **可运行对象的真截图**。任务对象本身能在当前环境跑起来时（静态站点、纯前端、现成构建 产物），必须先尝试运行并截取真实画面；尝试记录（命令与结果原文）写入图像来源清单； 3. **生成图像**。环境提供图像生成工具时，概念、氛围与有语义职责的表现型图像用它生成，不用 CSS 渐变或摆设 SVG 凑数。**质感门槛**：凡目标画面离不开材质与光影词（金属、玻璃、体积光、景深、渲染）—— 硬件渲染 hero 背景、产品效果大图、品牌标识的质感呈现稿、氛围场景图——必须用图像 生成产出；用 CSS 渐变、发光弧线、抽象几何 SVG 手写模拟这一档质感即图鉴 D 组病，不许做 （判据与场景详见[素材与图像生成](references/assets-and-imagegen.md)第 3 节）。 **禁止用生成图像冒充产品截图、实物照片或数据图表——那是编造**。生成图的 route、lineage、 prompt 摘要、编辑范围和真实性边界一律进入图像来源清单；纯粹建立世界、气氛或节奏且不声称 事实的背景，只记录 provenance，不在成品页面展示制作过程。只有图像邻接真实人物、档案、事件、 客户、产品状态或其他事实 claim，省略说明会让普通读者误认其为证据时，才在页面用贴合内容语境 的短说明消除误认；无法消除误认时不得使用。无真图可用时，遵守该边界的生成图仍是默认选择， 禁止以“不敢编造”为由留白、裁掉图位或整页纯文字化； 4. **精确图形**。图表、地图、带可靠文字的结构示意由真实数据和专业工具绘制；标准功能 icon 走 `standard_symbol`，表现型 icon 走 `generated_visual`。用手绘示意「还原」一个真实存在且 真图可得的界面，视为与手写控件同级的退化，必须在清单里写明第 1、2 档为何不可用。 **档位只回答「从哪来」，不豁免「好不好」**：任何档位的图像放上页面前，都必须先过第 4 节 代表画面标准——这张图在它所在的版面里能指认主体、构图撑得住尺寸。空态界面、大面积留白、 偶然的测试记录不能作为主视觉或整幅展示；先裁剪到主体或换同档更饱满的一张，同档全部 不合格时降一档并在清单写明理由。「这是真图」永远不是「这张图可以用」的理由；用一张空态 真图冒充产品的代表画面，与手绘假界面是同一种失败。 **页面上只有产品语言**：图注、标签与图像周边文字只回答产品用户关心的事（这是什么界面、 它在做什么），用产品自己的口吻。裁剪说明、「未重绘」「验收截图」「测试 fixture」、来源路径、 处理过程，以及为了证明合规而添加的制作过程标签——一切解释「我怎么做出这张页面」的话语， 一律只进图像来源清单与 evidence，不出现在页面任何角落；上一条为避免 事实误认所必需的内容说明不属于制作说明。成品是给产品的用户看的，不是给评审看的；把制作说明印上页面， 成品就变回了作业（与第 3 节「面向评审与流程的话语不进入画面」同一条纪律，对图像同样生效）。 **位图上页先过清晰度账，糊等于没做**：按 2 倍屏结账——图像物理宽度必须 ≥ 页面显示宽度的 2 倍；不够就缩小显示宽度、裁出局部重点，或换更高分辨率素材，禁止把低分辨率图整幅拉满版面。 界面截图属于文字加平色块，一律用无损格式（PNG / 无损 WebP），禁止 JPEG 与有损 WebP。 窗口外壳、阴影、圆角用 CSS 绘制保持矢量锐利，位图只承载内容区。文字型界面需要大幅呈现而 素材分辨率不足时，正确做法是**以真截图为蓝本的 HTML/CSS 忠实转写**（逐区对照蓝本，清单里 标注蓝本文件）——这是「矢量级清晰」的合法路径；没有蓝本的凭空重绘仍按第 4 档处理。 交付前的最终走查必须包含一次 2 倍缩放（deviceScaleFactor=2）下的截图对比，确认无一处 可见模糊，proof 留档。 `DESIGN-BRIEF.md` 必须包含**图像来源清单**：按页面主要区块逐行覆盖——配图的区块写明 位置、档位（资产真图/自截真图/生成/代码绘制）、真实性／披露处理与一句挑选理由（为什么是这张， 而不只是这一档）；不配图的区块写明无图理由，而「无真图可用」不算理由——无真图的默认 动作是生成并在 provenance 写清边界。采用低档而高档可能存在的，附搜索或尝试记录。缺清单、或有主要 区块缺行，即未完成。无图区块仍须说明它如何延续页面的视觉家族；不能让主视觉之后的整页退回 与项目无关的默认排版。 ## 4. 先完成决定成败的代表画面 完整扩展前，先构建一个代表性非空画面或关键帧。它应包含真实内容或明确标记的确定性 fixture、 主要对象、最高典型密度、核心判断、主要命令，以及决定方向所需的真实组件和专业引擎。 内容型／营销型 Web 的代表画面还必须使用已查看的最终主视觉，并直接在真实像素上验证文字安全区、 焦点、裁切、对比与主任务可见性；占位背景不是代表画面。 一个真实代表画面完成后，立即用当前环境声明的正式构建入口构建并从实际交付入口预览。 代表画面尚未同时通过构建、真实像素与 J1/J3 时，不得扩展其余区块、页面族或子素材；源码存在、 开发服务器可打开或文档声称方向成立都不能替代这一步。 按以下顺序查看实际渲染像素： ```text 轮廓与空间分配 → 视觉中心和主要对象 → 阅读与操作顺序 → 字体关系和可读性 → 色彩职责与对比 → 设计系统一致性 → 图标、边界和动效细节 ``` 前四项不成立时，重新处理构图，不用阴影、圆角、渐变、标签、图标和说明文字掩盖问题。 代表画面还必须通过 J1 与 J3：能指认一个主角时刻——读者最先遇到的表面上，最值得记住的 对象、构图或表达，并且整个画面能被一句话描述。指认不出主角时刻的画面只是没有错误， 尚未成立。主角优先来自任务的世界——被展示、被分析、被使用的对象本身；主角只能指向交付 自身的步骤、分类或框架时，重选。方向与主角都稳定后，再扩展完整功能、状态和合同内目标环境。 ## 5. 逐区完成，再扩展真实功能 方向稳定后，先把最终产物的顶层区块和页面族全部列入 `SURFACE-MANIFEST`，再按同一任务模型 逐区扩展。一个区块只有在真实内容、主要对象、阅读／操作顺序、任务特有细节、适用状态和目标环境 都已进入实际渲染，并在可读尺度下检查、修正和重渲染后，才从 `built` 进入 `visually_verified`。 首屏通过、构建成功、内容齐全或整页缩略图看起来统一，都不能替下方区块结账。 认真完成每一部分不等于让每一部分都使用不同造型。重复内容应复用同一组件和 token，连续叙事应 保持节奏；但每个区块都必须有适合自身任务的层级、密度、边界、图文关系和过渡，不能把未设计的 文字、表格或卡片接在精修首屏后面。整页截图只检查总节奏；文字、控件和细节必须另以足够清晰的 区块证据检查。 视觉面积、对比和位置跟随主要任务、主要对象与判断风险，不因某项内容“必须出现”就自动放大。 来源、真实性边界和方法限制应邻近其约束的 claim；除非该风险本身就是主要任务，不把它做成巨幅、 重复或比受影响内容更强的告示。 使用同一任务模型驱动界面、专业对象、摘要、详情和导出。按钮、筛选、导入、播放、编辑、保存、 下载和反馈必须真的改变状态并产生相符结果；不要用静态图形、固定数字或成功提示冒充能力。 实现后再从首次使用者视角检查全部视觉示能：按钮轮廓、下划线、chevron、悬停／焦点变化、选中／ 当前态、可点击卡片、行高亮、标签页和 disclosure 都会许诺交互。许诺成立就补齐真实动作、状态和 反馈；不成立就把它改成明显的静态表达。 最终交互检查必须在真实浏览器中遍历 `COMPONENT-BEHAVIOR-MAP`，不能只验证一条主路径。每种独特 行为、状态与视觉例外都要取得触发前状态、动作、可见结果和恢复／下一步证据；同组件、同状态合同 和同数据规则的重复实例可以共享视觉证据，但所有实际目标、状态变化或链接结果仍须自动遍历。 内部链接全部爬通，外部链接至少核对最终 `href` 与允许环境中的可达结果。只有全部结账的表面才能 进入最终检查。 多环境适配不是等比缩放。根据合同内目标环境保留主要对象和任务顺序，必要时改变导航、并排关系 和交互，但不改变内容语义。目标环境只来自用户任务与最终消费者合同；不得为“完整”自行扩张设备、 页面或模式范围。 需要图像、人物、场所或独特视觉世界时，按需读取 [素材与图像生成](references/assets-and-imagegen.md)。生成图不能冒充数据、地图事实、技术结构、 品牌标志或界面状态。 ## 6. 看见这些迹象就停下来重构 制作中任一图鉴组在产物里成形，按 `$review-against-ai-patterns` 第 2 节立即停下重构并记账。 套壳（无端 dashboard、landing、16:9 应用壳）、题材配色、假能力与假对象同属此列。 浏览器中的持续辅助文字通常不小于 `14 CSS px`，正文通常不小于 `16 CSS px`；更小字号只用于 少量高对比刻度、单位或时间戳，不能承担字段名、状态、错误、下一步或关键判断。辨识度和惊喜 应来自任务独有的主要对象、关系或交互，不来自额外装饰。遇到“不够精致”，先做 J2 删测—— 删除重复容器、标签、颜色、阴影和解释文字，再调整关系。 色条、顶边、标题旁竖线、局部 `border-left`、角括号、伪元素轨道和图标外框等强信号，只在它们 稳定编码选择、状态、进度、尺度、真实分组或已锁定身份语法时保留。“强调重点”“增加层次” “显得精致”不是职责，CSS 属性名也不能自证职责。CSS 可以完成布局、排印、必要分隔、真实状态反馈， 以及真实图像的裁切、遮罩和可读性 scrim；不能凭渐变、边框或伪元素另造装饰资产。 ## 7. 按风险检查，不制造审查循环 视觉判断不是固定三轮，也不按问题数量无限复审： - **方向检查**：新建方向或大改时，只看代表画面、参考特征和工具分工。 - **系统检查**：多页面、多状态、目标环境适配或共享视觉规则发生实质变化时再做。 - **最终检查**：最后一次可见修改后，在真实交付入口检查目标尺寸和关键状态。先以首次观看者 身份写下“没读过任务的人 3 秒内看到什么”，记入 `DESIGN-BRIEF.md` 终检段，再对照概念锚点 与 J 判据逐条核对——制作者视角看到的是意图，首见描述暴露的才是效果。 - **Diagnose/Audit**：只读复现和定位问题，不进入制作轮次。 独立 reviewer 的调用判断、输入边界与 `SELF_REVIEW_ONLY` 见 `$review-against-ai-patterns` 第 3 节。 最终检查中的正向细节门槛独立于反模式图鉴。先逐行关闭 `SURFACE-MANIFEST`：在完整页面中 检查区块之间的节奏和承接，再以可读尺度检查每个区块的排印（中文标点、中西文混排、数字、字重、 断行与孤行）、对齐与边界、图标家族、内容密度、图文关系、hover/focus/selected/empty/error/loading、 有职责的运动，以及各目标画幅的背景焦点、sticky 遮挡与主任务顺序。随后逐项执行 `COMPONENT-BEHAVIOR-MAP`；DOM 中存在监听器或链接不算通过，真实输入后必须出现与示能一致的可见结果。 执行五个返工测试： - **背景依赖测试**：若移除或替换主视觉后，标题位置、token、边界和开场构图都无需变化，说明它 仍是图槽，返回 `VISUAL-THESIS`； - **家族连续性测试**：离开开场后，页面不能再从同源背景、辅助视觉、排印关系或表现型符号辨认出 同一项目，说明身份只存在于 hero，返回资产家族计划； - **模板距离测试**：若只替换文案、色相和图像即可还原参考模板，或页面身份只存在于背景图，说明项目身份尚未 进入排印、结构和交互，返回代表画面； - **信号职责测试**：临时移除色条、边框、角标、伪元素和图标外框；若信息、状态、分组与身份均不变， 删除这些信号； - **注意力归属测试**：画面最强的三个区域必须对应主要任务、主要对象或关键判断，不能被免责声明、 装饰或元数据占据。 ## 8. 完成条件 交付前确认： - 内容型／营销型 Web 在首行页面代码之前完成 `identity_route` 与 `layout_route` 与 `REFERENCE-CONTRACT`；代表帧 和最终帧逐条写入实际像素证据，缺行、只引用名称或无硬约束地推翻主要关系即未完成； - 内容型／营销型 Web 在页面布局之前完成 `VISUAL-THESIS` 和 `MASTER-VISUAL-CONTRACT`，真实母版 已取得并查看；每个主要页面族均有预先锁定的视觉角色、资产 lineage 和开场证据，选择 `dominant_background` 的页面族由同一视觉家族主导开场，其他角色有任务证据且没有退回默认模板； 每个页面族的 `visual_role` 已与渲染返回的 `opening_visual` 读数对照回填，`uniform` 读数已在 `reason` 说明； - `SURFACE-MANIFEST` 覆盖每个顶层区块和页面族；没有 `planned`、`built`、待检查或缺证据行。 每一行均有最后一次可见修改后的可读尺度像素，整页缩略图不代替区块细节证据； - `COMPONENT-BEHAVIOR-MAP` 覆盖全部独特行为类和视觉交互暗示；所有具体目标已由浏览器遍历， 独特状态与例外有可见结果。看起来可点却没有行为，或有行为却没有反馈，均视为未完成； - 用户能在三秒内辨认主要对象、主任务和下一步； - 视觉方向能追溯到用户、参考、设计系统或领域，而不是题材联想； - 一套主视觉语言贯穿现成组件和自定义表面； - 标准能力与专业对象由合适工具真实承担，实现与 `DESIGN-BRIEF.md` 工具清单一致，自建项 均有调研记录，任务特有自定义保持最小； - “有一张生成图”只是能力送达证据，不构成视觉质量通过。内容型页面必须同时有完整页面族视觉映射、 `asset_family_plan`、`VISUAL-THESIS.manifestations` 的最终像素落点，以及背景依赖、家族连续性和 模板距离测试的真实结论。主要区块的配图必须有任务意义；无图区块仍须延续家族而不退回默认模板。 精确数据与文字继续由代码或专业图形承担，生成图不冒充证据； - 所有表现型 icon、插画、hero、场景、纹理与其他依赖审美绘制的精致视觉均走 `generated_visual`；标准功能 icon 来自同一既有系统或成熟家族；源码中的新建 inline SVG、 `.svg`、Canvas 与大面积 CSS 图形已扫描并逐项归类，未登记的手写 SVG 或用 CSS 模拟精致图像 即未完成； - 产物图像与 `DESIGN-BRIEF.md` 图像来源清单一致：按主要区块逐行覆盖，每张图像有档位与 理由，低档替代高档处有搜索或尝试记录，没有生成图像冒充实物或数据；页面上的图注与图像 周边文字全部是产品语言，无任何制作过程话语； - 真实内容密度、关键状态、目标尺寸和承诺交互均已检查；每个区块都达到成品状态，不存在只因 位于长页下方、使用重复组件或不承担主角职责而被略过的部分； - 最终像素晚于最后一次可见修改，并来自实际交付 URL 和消费环境，且至少一张主入口最终截图 已存档到工作区根目录 `proof/` 下； - `DESIGN-BRIEF.md` 已更新终态：概念锚点逐处标注（成立，或调整及原因）；终检段含首见描述， 以及与所选先例并排后写出的“它仍强于本产物的三点”；`VISUAL-THESIS`、主视觉、 `SURFACE-MANIFEST`、`COMPONENT-BEHAVIOR-MAP`、背景依赖、家族连续性和模板距离测试均已按最终 像素和真实操作结账，不得留有“待回填／待检查／计划规避”； - `ANTI-SLOP-CHECK.md` 已按 `$review-against-ai-patterns` 的完成条件结账； - 只报告真实复用、项目定制、检查范围、`SELF_REVIEW_ONLY` 和已知限制。 需要诊断选择过程时再读取[决策轨迹](references/decision-traces.md)。示例只用于学习决策方法， 不得成为跨任务复用的布局、配色或技术模板。