/build-polished-visual-frontends

name: build-polished-visual-frontends
description: "构建、重做、诊断或提升最终由浏览器消费的高完成度视觉前端。用于 HTML/CSS/JS/TS、React/Vue/Svelte/Astro、SVG/Canvas/WebGL 或 web-to-print 的网站、产品界面、数据故事、图解、地图、仿真与游戏；负责真实标杆、表达强度、成熟框架与设计系统、专业 Web 引擎、代表画面和最终像素质量，并与一份主要领域 Skill 组合。不用于纯后端、原生应用或仅以网页作为临时查看器的非 Web 母版。"

构建高完成度视觉前端

核心目标

让用户直接完成任务，让视觉、交互和专业对象来自同一组清楚的决定。让成熟工具解决已经 解决的问题，把模型的判断留给当前产品独有的任务、构图和体验。

遵循三个原则：

1. **任务决定形态。** 不因交付是 HTML 就默认应用壳、dashboard、landing page、卡片网格或 16:9。 2. **一套视觉语言。** 控件、导航、列表、面板、专业画布和反馈必须像同一个产品。 3. **标准能力交给工具。** 模型主要设计任务模型、工作顺序、整体构图和必要的连接层。

主要领域 Skill 决定内容模型、专业语义和领域门槛；`visual-artifact-design` 决定共享流程与 证据；本 Skill 只负责浏览器中的视觉方向、技术组合、工具边界和最终像素。用户当前要求与 已接受参考优先，其次是既有品牌、平台和领域约束。题材联想不能为任意颜色或装饰提供理由。

什么算好，八条判据（后文以代号引用）：

• **J1 主角与胆量**：每个交付面能指认主角时刻，且有一个超出安全默认、能一句话说出的决定。
• **J2 删测**：删掉后页面不变差的元素，必须删。
• **J3 一句话可述**：整个产物能被一句话描述（“这是一张……的页”）；说不出即没有方向。
• **J4 具体胜过修辞**：每个宣称可验证；用事实、真数字和真对象替代形容词。
• **J5 主视觉先行**：内容型／营销型 Web 先用真实成图锁定世界、空间与取景，再围绕它排版；

不允许先完成模板图槽，再用一张可拆换的图补空。

• **J6 细节成系统**：字体、标点、边界、图标、状态、运动与目标环境适配共同实现同一视觉命题；

“没有命中反模式”不等于已精致。

• **J7 逐区成品**：每个可见区块和页面族都有明确职责、任务特有的内容关系与完成态；不能精修

首屏后，把其余部分留成默认组件、文字倾倒或模板余料。

• **J8 示能诚实**：任何看起来可点击、可选择、可展开或可切换的东西都兑现相应行为与反馈；

静态内容不借用按钮、选中态、悬停态或可点击卡片的视觉暗示。

1. 先读懂任务，再决定画什么

新建方向或大改前，先写一张短决策卡：

任务: 谁在什么场景完成哪一件主要事情
主要对象: 页面中真正需要看、读、编辑或操纵的对象
自然形态: 页面、工作台、长文、画布、地图、图解、游戏或其他形态
领域惯例: 该领域真实从业者交付此物时的成品形态与表达习惯；偏离惯例必须写出理由
参考与偏好: 实际看见的参考，以及用户明确喜欢和拒绝的特征
表达强度: 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` 必须包含：

world: 用户进入什么具体世界
tension: 哪两个真实力量、时间或状态形成张力
memorable_moment: 三秒内最应被记住的画面
identity_strategy: 如何让产物区别于参考模板与通用同类页
manifestations: 视觉命题如何逐区进入主视觉、排印与规则、内容结构、交互与运动

“高级、克制、科技感、编辑感”等形容词不算命题。`manifestations` 必须覆盖最终产物的每个 顶层区块和页面族，写清它在那里通过什么对象、关系或行为成立；只列三处亮点、只精修首屏， 或用一句全局配色概括整页，都只是文档作文。无用户已接受的项目身份时，可以在参考合同的 `free_axes` 内提出 2–3 个互斥身份策略；候选只改身份与媒介，不重做已锁定的宏观布局。

`MASTER-VISUAL-CONTRACT` 必须包含：

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` 不是面积较大的图片，而是开场构图的空间底座：它必须在无需滚动的画面可见， 是最大的非文字视觉场，标题、主要对象或操作进入其安全区、焦点、层次或边缘关系，图像裁切会直接 改变排版。仅把大图放在文字旁边，即使面积足够，也只是 `