context-uiux-design

name

context_uiux_design

description

Use when the user explicitly asks for 设计稿, 重做设计, UI/UX 设计方案, UI 设计师, UX 设计师, 视觉设计方案, 视觉专家, 交互设计方案, 界面设计方案, 页面设计方案, 原型设计, 线框图方案, 视觉规范, 设计系统方案, DESIGN.md, Impeccable review, UX designer, UI designer, frontend redesign, visual polish, or design system spec in a Minimal Context Harness project. Do not trigger for ordinary UI implementation, CSS tweaks, bug fixes, or generic mentions of 设计, design, or user experience.

Context UIUX Design

Package-Managed Boundary

This Skill is generated by ty-context sync and owned by the Harness package. Do not edit the generated context_uiux_design Skill directly.

Project-specific UI/UX and visual design rules belong in a separate project-local Skill under <harnessRoot>/skills/uiux_design/SKILL.md. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in project_context/** and DESIGN.md. Keep the project-local Skill front matter description trigger keywords aligned with this package-managed Skill and the project AGENTS.md role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and Tiny Context guidance do not drift apart.

目标

帮助 agent 把界面、交互和视觉设计结论沉淀成可恢复的 Minimal Context 和 DESIGN.md。

工作方式

1. 先读取 project_context/global.md 和 project_context/context.toml，按 default area、triggers、read_when 选择相关 context。
2. 如果项目存在 DESIGN.md，先读取它；如果用户要求视觉体系、设计稿或界面风格，按 Google @google/design.md 的 DESIGN.md 格式创建或更新根目录 DESIGN.md。
3. 整理或生成：用户流程、页面/组件清单、关键状态、交互反馈、响应式边界、a11y 要求、视觉约束和设计 token。
4. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置时，把产品/页面定位检查作为前置动作：用户在这个 surface 要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、主层/下钻/运维/诊断/详情归属、布局和信息密度是否匹配任务。多 surface、多平台或多模块归属不清时，先读取相关 Context、搜索入口并结合已有 UI 代码/截图做信息架构 sweep，必要时使用 context_surface_contract 做 Surface Contract Check，再收窄到具体视觉或交互实现。该检查是下一步变更分类的输入；只有形成长期 surface 职责、信息架构、交互契约或模块边界结论时才更新 Context 或 DESIGN.md。
   • 若存在 Product Surface Contract，读取并对齐 primary user question、main allows/forbids、drilldown ownership、long-task state 和 verification。
   • 若缺失且本任务改变 durable surface responsibility，输出 Surface Contract Delta: required，把界面职责写入 project_context/**；视觉 token、颜色、字体、间距、圆角和视觉 rationale 仍写入 DESIGN.md。
5. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件交互框架”检查控件语义、反馈状态、校验、错误预防、可供性和信息密度；这只是通用判断框架，不是固定控件处方。
6. 界面职责、流程归属和长期交互契约以 project_context/** 为准；DESIGN.md 负责视觉 token 和视觉 rationale；代码、截图和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码和截图揭示“现在是什么”，代码不能静默重定义 Context。
7. 设计判断或第一处实现编辑前，先给出唯一长期事实判断 Context Delta: none|required。若输入包含产品、架构、技术、界面或验收来源，在 agent 内部逐项判断 durable surface / IA / interaction / verification constraint 已被 Context / DESIGN.md 覆盖、需要先更新、仅属 task-local、显式 out-of-scope 或需要真实用户决策；不要创建 plan.md、Task Contract 文件或 Markdown 映射表。
8. 普通 UI bug、局部样式或 CSS 修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期交互或视觉结论，继续对齐或交付前必须回写 Context 或 DESIGN.md。不要把 Context 机械补成代码改动摘要。
9. 如果二者冲突，显式标记为实现漂移、缺失工作或 Context 过期。
10. 如果涉及已有 UI，优先结合代码入口、运行截图或用户提供的参考图来描述差异。
11. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 npx impeccable detect <target>；实现前可用于识别既有视觉问题，实现后或交付前用于审查结果。没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。
12. 需要长期沉淀时：

• 项目级体验原则和屏幕清单写入 global.md。
• 模块级 screen contract、state、interaction 和视觉约束写入对应 area / subdomain Context。
• 颜色、字体、间距、圆角、组件视觉 token 和视觉 rationale 写入 DESIGN.md。
• 新 UI context unit 可新增 project_context/areas/<unit>.md，并更新 global.md#Context Index；复杂项目同时更新 project_context/context.toml。
• 如果 upgrade 自动把深层 .md 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。

13. Context 只能声明设计验收入口或 smoke 入口，不能伪造“已验证通过”。
14. Verification / Deployment Role Context 只记录长期可复用的设计验证、smoke、部署或运行初始化路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id、raw payload 或完整截图报告。
15. 收尾时做 Contract Conformance 和 Context drift check，只报告轻量状态：Context: 已更新 ... 或 Context: 本次无长期事实变化。Conformance 说明本次契约满足情况、未满足或延期项和截图 / 手动检查入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。

内部执行约束与 Conformance

• Context Delta 只能是 none 或 required。required 先更新 owning Context 或 DESIGN.md；none 按现有事实工作，不制造 Context 噪音。
• Agent 内部计划应保持页面 / 组件任务、用户判断、主辅信息归属、动作层级、输入语义、loading / empty / no-results / stale / error / degraded / success 状态、布局稳定性、非目标与验收入口清晰。
• 触及 Product Surface 时，同时保持 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification 清晰；字段、枚举、JSON 和截图仅是实现证据。
• 外部来源的重要约束在内部分类为 Context / DESIGN.md 已覆盖、已更新、task-local、显式 out-of-scope 或需要用户决策；存在未处理项时不能声称全量完成。
• 默认流程不要求或验证固定 plan.md、Task Contract 文件、Source-to-Context 表、Context-to-Implementation 表、matrix、verdict 或 evidence ledger；可选 scratch 没有固定名称或权威。
• Contract Conformance 直接检查 controlling Context / DESIGN.md 是否到达正确 surface、状态、交互与验证路径并避开 forbidden shortcut。实现偏差修实现；缺少长期事实则返回 Context Delta: required，先更新长期事实再对齐。
• small code task、普通 UI bug、局部 CSS 修复、小重构、测试修复或探索性 spike 不创建额外流程 artifact。

信息呈现校准

• 页面设计先回答：产品/页面定位是什么、要解决什么问题、用户需要什么、页面需要提供什么内容/能力/反馈；再决定元素放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。常驻元素应证明它比位置、图标、状态、数据或交互提示更能省注意力。
• 追求有效信息密度，而不是塞满页面。判断标准是更少无效 chrome、更少解释、更靠近真实内容和可执行动作；警惕用大标题、大容器、空卡片、假摘要或装饰区块制造仪式感。
• 对返回、刷新、同步、关闭、搜索、展开/收起等熟悉动作，比较 icon-only、紧凑控件、文字按钮和图标+文字哪种最省注意力；如果使用 icon-only，必须保留 aria-label、title、tooltip 或 hover/focus 说明。动作不熟悉、风险高或需要区分多个相近命令时，文字通常更合适。
• 常驻文字要克制。用户已经知道且不帮助行动的页面标题、面包屑、说明句或分区名，先判断是否可以删除，而不是先润色；必要解释可进入 tooltip、hover/focus 展开层、空态、详情页、帮助或 Context。
• 空间应由内容价值支撑。内容少时布局可以收缩到内容附近；警惕保留一整行只有几个字的 header、空指标槽、空列表容器或没有真实数据支撑的摘要。
• 信息架构按归属放置：真正跨页面的动作可放系统级 chrome，模块动作放模块内部，运维/连接/缓存/后台任务状态只在影响用户判断或行动时进入主工作面，低频系统解释放详情、日志、调试视图或文档。
• 空态、加载态和错误态必须真实。不要用 fixture、看似真实的 fallback 行或“这里不展示示例数据”这类元说明遮住没有数据；筛选无结果、系统无数据和连接失败要视觉上可区分。
• 页面稳定性是 UX 合同。滚动条出现、列表加载、tab 切换、虚拟列表高度变化、面板展开收起都不应导致布局跳动；需要时预留 scrollbar-gutter、稳定容器尺寸、固定关键控件尺寸和可预测的 loading skeleton。
• 文案服务任务，不解释设计。主界面避免内部黑话、实现边界说明、生产/示例数据规则和后端来源说明；必要技术细节放到详情、日志、调试视图或运维区域。

控件交互框架

• 当界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先判断控件承载的交互语义，而不是直接沿用后端字段形态。
• 判断输入数据是自由文本、枚举、实体选择、时间/区间、数量/预算还是规则配置；不同语义需要不同的可供性、约束、校验和错误恢复。
• 明确用户完成动作前后需要的反馈状态：loading、empty、no results、error、disabled、saving、success 和 validation feedback 应该支持用户判断下一步。
• 检查控件是否给足单位、范围、默认值、示例、推荐值、风险/成本/影响提示；解释应靠近决策点，低频细节可以进 tooltip、详情或帮助。
• 检查可见标签、helper text、错误文案和状态文案是否是用户语言，而不是内部字段、接口名或枚举名。
• 自由输入不是禁用项，但要和错误成本匹配：当格式固定、错误代价高或反馈复杂时，应考虑更明确的约束、选择机制或校验反馈。
• 不把本框架读成固定控件清单：搜索是否自动触发、时间是否用 picker、预算是否用 stepper，都应由数据规模、API 成本、用户任务、错误成本和项目组件体系决定。

视觉质量校准

• 先判断界面 register：品牌页、营销页、作品集等让设计承载表达；产品工具、后台、dashboard、表单等让设计服务任务。品牌界面可以更强烈地使用图像、色彩和编排；产品界面优先可扫读、稳定组件、熟悉交互和任务效率。
• 已有 UI 优先保持身份连续性：先找现有 token、组件库、全局 CSS、Tailwind config、截图或代表性页面；除非用户明确要求重设计，不要推翻已建立的字体、颜色、组件语言。
• 绿色地设计视觉体系时，先说明场景和色彩策略，再选 token：谁在什么环境下使用、界面应该 restrained / committed / full palette / drenched 到什么程度。不要按品类套默认审美。
• 做设计方案或视觉规范时，显式检查：文字对比度、65-75ch 正文行长、清晰字号层级、响应式边界、44px 触控目标、焦点态、hover/active/disabled/loading/error/success 状态、空态/错误态/长文本、reduced motion 和文本不溢出。
• 避免常见 AI 视觉反模式：嵌套卡片、无意义玻璃拟态、紫蓝渐变或渐变文字、灰字压在彩色背景上、默认米色/奶油色大背景、过度圆角、边框加大模糊阴影的幽灵卡片、每段一个圆角 icon tile、每节重复小号全大写 eyebrow 或 01 / 02 / 03 标记、bounce/elastic easing、空泛营销 buzzword。
• 视觉审查时先分清问题类型：a11y / responsive / theming / interaction / copy / performance / anti-pattern。把真正影响用户理解、操作或品牌信任的问题列为高优先级；少量纯审美偏好不要淹没关键问题。
• Harness 默认携带 Impeccable CLI 能力；做设计稿、重做设计、视觉设计方案、设计系统方案、frontend redesign、visual polish 或既有 UI 视觉审查时，默认尝试运行 npx impeccable detect <target> 作为辅助证据，不必等待用户点名。其输出只能作为设计缺陷线索，不是 Harness gate，也不能替代人工截图检查、项目测试或 validate-context。

输出边界

• 不默认创建 .work_products/**、UI/UX 独立文档、handoff matrix、review/test/release 文档。
• 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
• 如果用户明确要求独立设计稿、mock 或页面说明，可以临时生成；长期事实仍要提炼回 project_context/** 和 DESIGN.md。
• DESIGN.md 是视觉设计系统事实源；项目流程、模块契约和下一步动作仍以 project_context/** 为准。
• 如果用户只是要求实现页面、修复 UI bug、局部改 CSS、换颜色，或只是泛泛提到“设计 / design / user experience”，不需要触发本 Skill；只有明确角色名或强相关产物名指向设计方向、界面方案、视觉体系、交互规则或长期设计事实沉淀时才使用。

DESIGN.md 使用规则

• 使用 Google @google/design.md 格式：YAML front matter 存 tokens，Markdown body 存设计理由。
• 优先包含 name、colors、typography、spacing、rounded 和必要 components token。
• Markdown section 顺序优先为：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts。
• 写入或修改后，如本地可用，运行 npx @google/design.md lint DESIGN.md 检查结构；不要把 lint 结果写成“已通过”除非本轮真实执行。
• 需要给工程消费 token 时，可用 npx @google/design.md export --format css-tailwind DESIGN.md 或 json-tailwind 生成临时输出。

建议沉淀位置

• global.md#UX / Screen Brief：全局体验原则、主要屏幕、跨模块流程。
• areas/*.md#User / System Contract：页面、组件、状态、交互和数据展示契约。
• areas/*.md#Key Constraints：responsive、a11y、品牌/视觉边界、加载/空态/错误态约束。
• role=contract Context：跨页面 / 跨域界面契约及其 durable rationale。
• role=decision-rationale Context：更大或跨切面的稳定交互、信息架构或 surface ownership 取舍原因。
• areas/*/verification.md 或 role=verification Context：UI smoke、截图验收、可访问性检查或项目自己的关键验证重复执行路径。
• areas/*/deployment.md 或 role=deployment Context：前端部署、预览环境、运行拓扑或健康检查重复执行路径。
• project_context/context.toml：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
• DESIGN.md：视觉 identity、design tokens、组件视觉规则、do/don't 和视觉 rationale。

不要编造 rationale；仅由当前代码或截图形态反推的理由、实现摘要、PR notes、命令输出、测试通过声明、截图审查、debug 过程和 agent reasoning 不进入 Context 或 DESIGN.md。