chiaroscuro

Chiaroscuro

将面向用户的 Web 界面从需求实现为完整可用的成品。使用产品自身的语言，保留真实内容和行为，并赋予结果鲜明的视觉风格，不要添加无关装饰，也不要暴露底层系统。

可用它来构建组件、区域或页面，也可提升现有界面的层次、完成度和精致感。它会产出一个完整的设计。其他任务有各自对应的技能：

• 提供多个页面方向供选择：maquette；
• 将滚动文档应用改造成固定的应用外壳：armature；
• 针对小型笔记本电脑、平板电脑和手机进行响应式优化：reflow；
• 在 Paper 中制作样稿：paste-up。

当所请求的 UI 在上下文中正常运行、在桌面端和手机上都呈现妥当，且现有行为保持不变时，工作才算完成。

硬性规则

这些规则适用于工作的每个部分，包括交给协作者的内容。产品现有的样式也不例外；要在工作范围内修正，并在范围之外说明。只有用户的明确指示可以覆盖规则。

1. 不要使用小型大写字母、加宽字距的全大写文字或装饰性等宽字体。 不要使用眉题、引题、分区标签、徽标或表格标题大写。等宽字体仅用于代码、标识符，以及需要检查字符内容的值，不用于标签或标题。正式缩写保留大写。
2. 界面该呈现的内容，不要用说明性文字代替。 如果屏幕需要段落来解释，就说明屏幕设计失败了。用标签、控件、值或留白来替代。在产品 UI 中，标题应为事物命名，而不是充当宣传语或引出分区。只保留同意说明、限制条件和错误恢复内容。
3. 使用所选字体，设置 4 到 6 种文字样式。 沿用产品中已命名的文字角色。新增字号或字重，必须有现有角色无法满足的用途。新增字体应来自 typecase 的字体建议，且不能出现在其禁用列表中；Instrument Serif 是该列表中的首选字体。
4. 优先复用，再考虑新建。 在本产品以及用户指定的任何包或项目中，找到能完成任务的现有组件、外壳、页眉或控件并复用。重复实现已有控件属于缺陷。
5. 每种元素只保留一套。 圆角比例只用一套，并采用同心嵌套；图标只用一套图标库和一种描边粗细；每种密度只用一种控件高度。
6. 触控目标至少为 44 × 44 CSS 像素。
7. 完成前先实际查看。 在真实浏览器中走查操作路径，然后像用户一样，在桌面端和手机上查看每个完整屏幕。静态检查既无法证明界面能正常运行，也无法证明它看起来合适。

端到端完成工作

1. 检查产品和任务

阅读项目说明、产品和品牌文档、相关路由和组件、现有设计令牌，以及可运行的界面。明确：

• 用户要完成的任务和核心路径；
• 真实内容、数据和状态；
• 已确立的外壳、网格、组件和术语；
• 技术限制和样式系统；
• 必须保持不变的内容。

不要一开始就脱离实际，自行构想视觉主题。你应该能用几句具体的话，描述用户的任务、产品限制和界面边界。

对于工作流，在绘制屏幕前先走查一个具体场景：用户提供什么、哪些内容必须保持不变、用户会做出哪些选择，以及最终会得到什么结果。含义不同的输入应彼此区分。先确定有用的最终状态，再梳理抵达该状态所需的各个转变。对于范围明确的修改，检查它在现有路径中的位置；不要重新设计整个产品。

2. 仅加载相关参考资料

阅读 references/interface/index.md，并且只打开此任务需要的分支。

• 对于动效，从 references/interface/animation.md 开始。如果已安装，请使用 zoetrope 掌握专业动效设计，并参考该库自身的文档了解当前 API 信息。
• 编写或修改 UI 文案时，在文字影响布局之前，先使用 signage（如果已安装）。否则，在此运用其核心测试：你会对目标受众这样说，并且无需解释，他们就能理解吗？标签要具体，删去用文案代替控件的内容。
• 对于图表或一组数据可视化，请加载 references/interface/charts.md。

参考文件是导航器，而非检查清单。切勿默认加载所有规则文件。

3. 确定视觉风格

先确定产品的形态，再决定样式。专注于单一用途的体验，应让主体内容占据屏幕，其他内容尽量少：默认不设页眉、导航或标题。只有当用户需要在不同页面间切换或跨窗格工作时，持久化外壳才有存在的必要。

接着用一两句话确定视觉风格：层级、字体、色彩表现、信息密度和交互氛围。描述应具体到足以约束实现，而不只是情绪板式的口号。

手机界面应作为独立设计来构思，而不是把桌面界面硬塞进小屏幕：主要操作应位于拇指可及范围内，使用底部弹层而非居中模态框，媒体内容铺满屏幕，一次呈现更少控件，并采用更小的显示尺寸。

将提供的设计或审核通过的方案中少数关键决策落实到实现中：什么内容优先、什么内容弱化、哪些内容始终可见，以及操作与辅助信息之间的关系。组件默认样式必须保留这些决策；不能因为某个变体更方便就改变布局。

借鉴其他界面的美学风格时，要明确指出借鉴了哪些特征，例如字体、纹理、信息密度或控件样式。保留目标产品的任务、对象和状态转换；视觉上相似，并不代表原应用仍能正常工作。

4. 使用 Tailwind v4 实现

优先使用项目现有的组件和约定，而不是创建新的基础组件。通过 Tailwind v4 工具类、变体和 @theme 令牌表达视觉决策，避免零散使用任意值。若采用 v4 会改动软件包清单、构建配置或全局 CSS 入口文件，请先建议迁移并征求同意；局部 UI 需求不应演变成全仓库样式迁移。

构建稳定的各种状态，而不只是稳定的首帧。避免意外的布局偏移：为延迟出现的标签和控件预留空间；用环绕阴影或内阴影绘制依赖状态的边缘，而不是使用边框；确保同一行中的控件高度一致；为图片设置固定宽高比。键盘操作应保留原生表单语义；焦点应始终可见，并在需要时滚动到视野内；裁切不得意外创建滚动容器。

5. 锻炼并完善渲染后的体验

在实际应用中，使用正在修改的精确路由、视口和状态运行应用，并完整走完核心用户路径。根据需要检查：

• 桌面端和手机端布局；
• 键盘和指针操作；
• 焦点顺序、焦点可见性、语义和无障碍树；
• 长内容、空、加载、失败和成功状态；
• 控制台错误和失败的网络请求；
• 持久化，以及用户操作带来的后续影响；
• 动画中断和减少动态效果时的行为；
• 深色模式下的对比度和实际栅格资源。

缩小视角并审视整体。 首次完成整体构图以及做出重要改动后，都要将整个视口和连续状态放在一起查看。最先吸引注意力的是什么？那是用户关注的主体，还是它周围的控件？下一步操作是否一目了然？最明显的问题是否出在整体构图？先解决这个问题，再打磨细节；如果局部修补让整体显得不协调，就重新构图。通过技术检查并不能回答这些问题。

如果已安装且风险值得投入，请使用 fieldtest 进行更深入的浏览器 QA，并使用 reflow 完整检查各种屏幕尺寸。

6. 清理并报告

移除工作中引入的临时包装、隐藏分支、抑制项和未使用的导入。报告改动内容、实际检查和观察的内容，以及任何确实存在的限制。只运行静态检查时，绝不能声称已完成浏览器检查。

品味与工艺守则

• 使用真实的产品内容。占位标语和通用仪表盘数据会掩盖设计问题。
• 将产品自身的图像作为一组风格统一的资源，保持光线、比例和裁剪一致。与其使用图库填充图或错误的图像，不如不放图。
• 普通 UI 文案使用句首字母大写格式。对齐的数字应在正文使用的字体中采用等宽数字，而不是改用等宽字体。
• 如果图标的含义不明显，就为其提供无障碍名称或相邻标签。
• 通过不可见的内边距满足触控目标尺寸，不要把所有可见控件都做得笨重。
• 如果数学上的居中看起来不对，就凭视觉对齐形状。
• 避免通用的 AI 默认风格：层叠的圆角卡片、无端的渐变、发光边框、装饰性药丸标签、过大的主视觉文案、产品 UI 中的编辑式标题，以及装饰性状态栏。
• 深色模式下，应重新构建对比关系，而不是简单反转颜色。如果浅色资源在深色模式下效果不佳，就使用对应的深色模式栅格资源。
• 动画需要有明确用途、起点、中断行为、频率预算和减少动态效果时的处理方式。快速反馈和感知速度比炫技更重要。

专项边界

Chiaroscuro 本身即可胜任工作。专项技能可以增加深度，但绝不能替你遵守硬性规则。只有在已安装且任务确实需要深入处理时，才委派给专项技能：

• typecase：处理字体阶梯及其扫描器；
• componentize：审计复用情况和重复内容；
• zoetrope：构建、审查或查找动画，包括手势；
• signage：按步骤 2 的指示编写或修改 UI 文案；
• fieldtest：进行需要大量证据的浏览器 QA；
• reflow：检查所有视图的响应式表现；
• armature：当应用需要先搭建固定外壳和分栏，再进行润色时使用；
• maquette：当用户希望从多个页面方案中进行选择时使用；
• paste-up：处理 Paper 文件中的任何工作；
• dark-mode-image、canonicalize-tailwind、markup-from-image、prototype 或 pick-ui-library：用于各自特定范围的辅助工作。

在此处完成常规的端到端界面工作。除非用户要求，否则不要强行引入专项依赖、保存设计规范、线框图或审批暂停。