build-web-ui

# 构建网页与 Web UI 把网页视为内容、任务、品牌、组件行为、工程和真实运行状态的统一产物。先分流改动范围、风险和页面类型，再建立与本轮范围相称的页面、视觉和组件合同；页面能显示、静态检查通过或首屏截图好看都不能单独证明完成，机器报告为零问题也不能。 ## 按范围与页面类型读取 1. 先判断本轮是局部修复、既有页面改版、新页面还是跨页面系统重构。局部文案、间距或单组件修复只处理受影响角色，不重建整站设计系统，也不强制外部研究。 2. 新站、整页改版或跨页面系统重构必须读取 [site-archetypes.md](references/site-archetypes.md)，先按页面用途区分科研结果/操作、非科研任务界面与表达型页面，再选择具体类型。科研页面保持保守清晰，其他页面可采用更丰富的视觉表达；不能因作者从事科研、需要登录或名称含“管理台”就继承科研工具风格。混合站逐页分流，不取平均风格。 3. 确定风格、排版、内容密度、视觉角色或消除通用 AI 感时，读取 [design-playbook.md](references/design-playbook.md)。整体美化、主题重构或配色决定整页身份时，同时读取 [color-systems.md](references/color-systems.md)。 4. 新建或重构复合组件、筛选/表格、导航、弹窗、标签页、轮播、拖拽或动效时，读取 [interaction-components.md](references/interaction-components.md)。 5. 个人生活、作品集、摄影、音乐、艺术、文化或活动站必须读取 [personal-cultural-sites.md](references/personal-cultural-sites.md)，按用户语气校准作者性与表达强度。 6. 参考用户既有网页或在个人站、内容站与任务型工具之间选择设计语言时，读取 [local-reference-patterns.md](references/local-reference-patterns.md)。 7. 用户要求外部案例、开源仓库或高级交互，实现可能新增依赖，或只给出“美观、现代、高级、有趣、不生硬”等抽象目标且没有已锁定品牌/设计稿时，读取 [external-design-research.md](references/external-design-research.md)。局部修复、完整品牌系统或精确设计稿不因本条强制联网。 8. 开始性能、SEO、无障碍实现或交付前验证时，必须读取 [quality-gates.md](references/quality-gates.md)。 静态构建产物运行 `python scripts/audit_static_html.py <html-or-directory> [--root <site-root>]`。需要可复现的桌面与手机浏览器证据且本机已有 Chromium 时，运行 `python scripts/audit_browser.py <url...> --output <directory>`；脚本使用 Chrome DevTools Protocol（CDP）设置真实布局视口，不自行安装浏览器，也不评价审美。 ## 1. 建立页面、视觉与组件合同 1. 读取当前工作区规则、入口、路由、样式、组件、资源、构建命令和已有测试。保留来源不明的改动，不读取或回显 `.env`、凭证和私密配置。 2. 识别读者、核心任务、真实内容量、品牌语气、公开或登录状态、目标设备与必须保持的行为。只有会显著改变信息架构、技术栈或品牌方向的选择无法从材料推断时才询问。 3. 建立页面清单，区分公开页、登录/账户页、后台/任务页和共享组件。每项写明页面类型、主任务、真实长内容、加载/空/错/成功/权限状态、目标视口和验收路径；不得只改公开首页而默认后台已经一致。 4. 沿用既有框架、组件体系和依赖合同。新站选择满足需求的最小技术方案；不要仅为视觉翻新迁移框架、引入大型 UI 库或重写正常工作的业务逻辑。确需外部组件时，按 [external-design-research.md](references/external-design-research.md) 对当前需要的具体组件建立能力矩阵，核对源码/包所有权、状态、可访问性、主题、运行边界、生产包增量、迁移与测试证据；星数和示例截图不作采用结论。 5. 在编码前建立可检查的视觉合同。整体页面或主题重构必须写明： - 一句与真实内容、媒介感和行为有关的视觉命题； - 用户可见的必须特征、不得出现的特征、一个主表达手段和最多两个辅助手段； - 首屏视觉重心、默认表面层级、内容密度与长内容节奏； - 桌面与手机的页面外框、内容框宽度、左右安全区、共享对齐线，以及全宽或有意非对称区块； - 正文、标题、界面标签、数字、字体、间距、几何、图像和动效角色； - 明暗模式、中性色、主操作色、强调色、语义色、数据序列的职责与竞争色相预算； - 每项边界的截图或代码证据。单组件修复只写受影响角色。 6. 为复合组件写明信息源、适用状态、键盘/触控路径、加载和失败恢复、减少动效与无 JavaScript 基线。只有实际需要的状态进入实现，不为组件库展示虚构业务状态。 7. 使用外部参考时，记录来源身份、许可、可迁移模式、采用或拒绝理由、依赖选择和无动效回退。链接清单、流行度和示例截图不能替代设计决策。 ## 2. 组织真实内容与任务 1. 先排列用户要完成的任务和页面信息，再决定组件。每个公开首屏回答“这是什么、对谁有用、下一步做什么”，任务页先显示当前对象、状态和可执行动作。 2. 按页面类型覆盖关键路径：营销页说明价值、差异、证据和行动；电商覆盖发现、比较、库存/规格、购物车和结算状态；内容与知识站覆盖搜索、目录、阅读和来源；管理台覆盖筛选、批量操作、异常和审计；社区/账户覆盖身份、权限、通知和治理。 3. 为公开内容提供稳定 URL、可抓取文本和清楚层级；为应用界面覆盖适用的默认、悬停、聚焦、按下、选中、禁用、加载、空、成功、错误和权限不足状态。 4. 使用真实内容长度、真实字段和真实约束设计。不得编造评价、客户、统计数字、合作方、研究发现或功能状态来填满界面。 5. 让桌面、窄屏和触控布局各自成立，不把桌面版等比例缩小。优先重排、折叠次要信息、保持阅读宽度和操作目标，不隐藏核心功能。 6. 先从 `viewport → page shell → section → content column → component` 建立布局骨架，再增加卡片、色彩和动效。为关键区块明确采用居中内容框、全宽、任务外壳或有依据的非对称构图；正文左对齐不等于内容框可以整体偏左，未声明的单边固定外边距、桌面偏移和不对称内边距不得带入手机端。 ## 3. 形成现代且有来源的视觉系统 1. 从页面目的、页面类型、内容、读者和使用场景推导视觉，不套用固定“现代 SaaS”模板。示例、模板和 showcase 只提供可选的结构、组件角色与行为证据，其配色不是本 skill 的默认值；除非它属于用户确认的权威品牌系统，否则每个项目都重新确定表面、操作、强调、语义和数据颜色。至少建立一项与主题直接相关的识别特征，例如编辑式构图、内容索引、任务时间线、领域图形语言、真实商品关系或材料质感。 2. 按 [color-systems.md](references/color-systems.md) 把颜色映射为表面、文字、操作、反馈和数据角色。每个在同一视口争夺注意力的色相都必须有职责；语义色不得承担无语义的大面积装饰。没有用户、品牌或真实素材的颜色依据时，不因科研、医疗或“专业”自动使用大面积深绿、深蓝等暗色外壳，先从中性表面和职责明确的操作色建立候选。计算关键正文、次要文字、按钮、链接、焦点和状态色的前景/背景对比度；渐变、图片、混合模式或透明叠层不能可靠自动判断时人工核对。不能凭色值列表或肉眼声称协调。 3. 把颜色、字体、尺寸、间距、圆角、边框、阴影、层级和动效写成少量 token，并明确它们实际作用的页面、组件和状态。删除未被任何页面或组件使用、同义重复或只为展示变量数量的 token。 4. 默认选择一个主表达手段和最多两个辅助手段。若同一视口同时出现 3D 倾斜、持续位移、滚动显影、自动轮播、视差、重复装饰运动中的两类或更多，先视为效果堆叠候选，逐项说明它服务的内容或任务；无法说明或关闭后层级更清楚时撤回。 5. 用户明确要求实验、沉浸或强动效时可以提高效果预算，但不得让核心内容依赖动画、hover 或高性能设备。导航、正文、表单、错误和权限信息保持稳定，触控、键盘和减少动效有等价路径。 6. 删除无内容依据的渐变、玻璃拟态、悬浮色块、同质卡片阵列、过量胶囊、假大空口号、随机图标盒与大面积空白；不得反向把所有页面收敛成低饱和、规则网格和无动效。 7. 需要原创品牌插画、英雄图或纹理且位图更合适时调用 imagegen。界面文字、数据、表单和真实产品截图留在 HTML/CSS 或实际浏览器渲染中，不烘焙进生成图片。 ## 4. 实现流畅且稳健的组件 1. 使用语义 HTML、清楚标题层级、原生交互元素和可见标签。CSS 优先流式布局、容器查询或媒体查询与 token；JavaScript 只承担必要交互。 2. 从外到内检查各层盒模型。共享内容框优先使用逻辑方向属性、对称 `padding-inline`、可追踪的 `max-width` 和 `margin-inline: auto`；网格/弹性子项按需使用 `min-width: 0`，窄屏撤回桌面专用的固定宽度、单边定位、位移和跨列。不要在父子两层无意重复加入页面边距。 3. 在 320、390 和 430 像素附近预览新页面或整体改版的关键布局；至少保存 390 像素正式证据，并按最长内容、组件断点或用户目标补充最容易失衡的边界宽度。局部修复只验证受影响宽度与同类组件。 4. 先沿用项目组件，再比较原生元素、无样式可访问组件和专用依赖。只在焦点管理、碰撞定位、触控惯性、虚拟化或复杂时间线确实需要时引入依赖，并固定兼容版本、检查许可和包体积。 5. 组件状态变化应立即给出可感知反馈，运动可被中断并结束在正确业务状态。动效优先使用 `transform` 与 `opacity`，避免布局抖动；隐藏、离屏或失焦后停止连续更新。 6. 保持业务逻辑、API、鉴权、路由和数据契约。视觉重构先识别行为测试，再小步修改；不要用静态假界面替换已工作的真实状态。 7. 为图像提供准确替代文本或明确空 `alt`、固有尺寸和适合容器的响应式资源。真实截图必须来自实际渲染；发现破图、溢出或字体回退时回到资源和布局源修复。 8. 高级效果必须有静态基线、触控替代、键盘路径和 `prefers-reduced-motion` 分支；核心操作的输入、结果和错误在回退路径中保持等价。 ## 5. 同步优化性能、SEO 与可访问性 1. 让公开核心内容尽早出现在 HTML 中，缩小关键渲染路径和客户端 JavaScript。优先静态或服务端输出，按路由和交互边界延迟非关键代码。 2. 让 Largest Contentful Paint（LCP）资源可从 HTML 发现且不懒加载；为首屏关键资源设置合理优先级。首屏外图像和重内容再懒加载，使用 AVIF/WebP、`srcset`/`sizes`、尺寸声明和缓存。 3. 子集化并自托管必要字体，使用 WOFF2、可靠回退与合适的 `font-display`；只预加载确定会出现在首屏的关键字重。 4. 为可索引页面提供独立且准确的 title、description、canonical、一个主 H1、语言、可抓取链接、站点地图、开放图和与内容相符的结构化数据。登录、后台、预览和私密页面使用鉴权或 `noindex`，不要用 robots.txt 代替禁止索引。 5. 以 WCAG 2.2 AA 为最低目标：键盘可达、焦点可见且不被遮挡、标签与错误关联、对比足够、触控目标可用、缩放不受限、颜色不是唯一状态线索。 ## 6. 实跑、分层门禁与反馈升级 1. 先按实际 diff 和用户请求列出受影响层，再按 [quality-gates.md](references/quality-gates.md) 选择门禁： - **L 局部纯前端**：只改文案、CSS、局部语义标记或既有 DOM 交互，且不改变路由、共享布局/组件、依赖、构建配置、API、schema、鉴权、权限、持久化或安全边界。只检查目标文件，以及实际使用该规则或组件的页面、状态和视口。 - **P 页面或前端系统**：新页面、整页改版、共享布局/token/组件、新交互、路由、依赖或构建行为。运行受影响包的格式化、类型、lint、测试和构建，并用代表性页面矩阵验收。 - **P/R 契约或生产高风险**：触及 API、schema、鉴权、权限、持久化、迁移、安全、并发写入或生产配置时按 P 处理；用户明确正式发布时按 R 处理。网页门禁之外继续执行项目规定的专项测试与安全检查，不得用局部路径降级。 2. 代码写完必须实跑，但只运行能为受影响层增加证据的命令。L 任务使用项目已有的定向语法、格式、组件或单文件检查；HTML 结构、元数据或静态构建产物变化时才运行结构审计；纯 CSS 或纯文案修改不因网页 skill 自动触发无关的全仓测试、生产构建或整站静态审计。项目更高优先级规则明确要求的命令仍须执行。 3. L 任务使用一个受影响 URL、状态和最容易暴露问题的实际布局视口完成技术核对；修改共享规则时，再抽查实际使用它的代表页面。用户明确在实际页面接手视觉验收时，其确认可以作为本轮受影响角色的视觉证据，不再默认生成桌面/手机截图矩阵；执行者仍完成文件级检查，部署后只做只读健康检查，并分别记录自动检查和用户确认。用户未接手时，由执行者在真实浏览器检查该受影响状态。 4. P/R 任务用真实浏览器覆盖页面合同：至少检查约 1440 像素桌面和 CDP 仿真的 390 像素手机布局视口；新页面、整体改版或用户点名手机体验时，再检查 320 与 430 像素或更危险的边界宽度。记录 `innerWidth`、`clientWidth`、`scrollWidth` 与 `body.scrollWidth`。不得把 `--window-size=390` 的外窗宽度或被裁切的窄截图当作 390 像素移动端证据。 5. P/R 的每类页面至少检查首屏，以及一个锚点、滚动深处或任务状态。根据项目覆盖真实长文本、筛选表单、空/错/加载状态、弹窗、后台列表和编辑页；公开页与后台页分别验收。每个场景记录 H1 数量、重复 ID、缺失 alt、破图、横向溢出、关键布局容器的左右间隙与中心偏移、核心内容越界，以及控制台异常、脚本异常、HTTP 失败和网络加载失败。 6. 新增或重构共享组件且项目已有 Storybook、组件夹具或截图回归框架时，复用它们固化真实适用的状态和交互，再在实际页面验证组合关系。截图基线必须在稳定环境生成并经人工确认；差异失败不得通过自动更新基线关闭。项目没有这些工具时不为本轮强制安装或初始化。 7. 分开给出与本轮范围相称的技术门禁和视觉门禁结论。L 只判断受影响的页面、组件、状态和视口；P/R 按同一组截图核对完整视觉合同、运行时、键盘、触控、对比度和布局几何。正文左对齐不算偏左；未声明且无内容依据的左右安全区失衡、桌面偏移残留或多区块共同偏向一侧判为失败。机器报告零问题不得改写为视觉通过。 8. 已定位且与本轮无关的稳定失败只有在项目规则允许、相关文件未变化且定向检查未出现新异常时才不重复运行；保留失败命令、原因和未通过状态，不得声称全套测试通过。未知失败、失败内容变化、服务不健康或安全/数据完整性异常必须重新定位并阻止完成。 9. 第一次整体风格或配色否定后，更新视觉合同并从共享 token、布局和组件层修正。同一页面第二次连续出现整体否定时，停止逐色或逐组件补丁，汇总用户确认的保留项与禁止项，撤回冲突 token/效果，回到最近可接受或最简单的内容完整基线，重新选择参考和角色后再产出候选。错别字、单个像素和明确局部调整不触发重建。 10. 用户正在逐张审阅候选、要求继续修改或存在未关闭视觉异议时，把候选标为“待审阅”或“被否定”，继续本地/脱敏预览但暂停生产部署。用户明确接受当前候选或关闭最新异议后标为“可部署”。用户未进入审阅态时，适用门禁通过即可按授权范围自治完成；紧急故障恢复或用户明确要求立即部署按用户指示执行。 11. 发现一类缺陷后扫描受同一源影响的页面和同类组件；局部选择器只查目标和实际使用它的页面，共享 token、布局或组件才扩大到代表性页面。修复后只重跑受影响检查。若高级效果破坏内容层级、核心任务、触控、键盘、减少动效、性能或低能力设备体验，撤回该效果。 ## 完成判定 - L 局部任务已经确认唯一文件或部件、实际使用它的页面及不变范围；目标检查实跑通过，受影响状态由执行者或用户在实际页面确认，范围外没有意外差异。没有执行的全仓、整站或跨视口检查不包装成已通过。 - P 页面或前端系统任务的页面类型、核心任务、真实内容、公开/私密边界与既有行为均有代表性页面和状态证据，没有用首页代表整站；契约高风险任务通过项目规定的专项与安全门禁，R 任务再通过发布门禁。 - P/R 的视觉合同说明主题来源、正向特征、反向边界、视觉重心、页面骨架、内容框与角色分工；适用组件覆盖状态、键盘、触控、失败恢复和减少动效。 - P/R 在桌面与 CDP 手机布局视口下的代表性首屏、深层内容和关键状态可读可操作；关键容器的安全区、对齐线和视觉重心符合合同，无未解释的偏移、溢出、裁切、破图、控制台或网络失败。 - 适用的技术门禁与视觉门禁分别记录；用户接手视觉验收时写明其确认的 URL、状态和范围，不把局部确认扩写为全站通过。 - 候选审阅态没有未关闭异议；生产部署只在当前授权和部署状态允许时执行。 - 交付说明只列本轮实际改动、执行过的验证、对应范围、已知限制和需要部署后观察的指标；不为满足固定模板补写未执行的页面矩阵、视觉命题或全套测试结论。