ui-craft

UI Craft

跨领域技能。 将此技能与一种特定库技能（spartan-ng-developer、primeng-developer、ng-zorro-developer、angular-material-developer）以及基础 angular-developer 搭配使用。此技能讲解优秀设计的标准以及背后的原因。库技能则讲解该选用哪个组件。当用户希望打造精致的 UI 时，两者会一起加载。

何时应触发此技能

当用户说出以下任何内容时，积极触发：

• “让它看起来更好 / 更简洁 / 更精致”
• “感觉很普通” / “看起来像模板”
• “改进仪表板” / “重新设计这个页面”
• “为什么看起来这么不专业”
• 特定主题：“层级”“间距”“排版”“配色方案”“阴影”“空状态”“工具提示”“悬停状态”“加载状态”

看到以下情况时，也要主动触发（即使用户没有提出要求）：

• 正在构建仪表板或数据密集型界面
• 表格中的文字全是灰色，没有对齐，也没有弱化 / 激活状态之分
• 表单标签与值的字重和颜色相同
• 仅用颜色传达信息（没有图标、文字或形状作为辅助）
• 操作只有悬停时才显示，且没有提示其存在的视觉线索
• 异步界面完全没有空状态 / 加载状态

不专业的仪表板的三个特征

这些模式会立刻暴露出 UI 缺乏设计意图。每种模式都有自己的参考文件，因为它们各自是一门设计学问，而非单条规则。

1. 数据驱动 UI。 而不是反过来。界面的形状、密度、对齐、颜色，以及图表还是表格的选择，都应源自所展示的数据，而不是默认的表格模板。阅读 data-driven-ui.md。

2. 渐进式展示。 大多数操作、控件和元数据不应永久显示在屏幕上，而应收纳在悬停提示、弹出层、抽屉或上下文菜单中，并通过清晰的视觉线索提示用户。 “明确程度谱系”从始终可见的全局操作，到悬停时显示的行操作，再到右键后才显示的高级用户操作。阅读 progressive-disclosure.md。

3. UI 也包括看不见的部分。 只有图标的按钮都应有工具提示；所有可点击区域都应有悬停提示；还包括空状态、加载状态、错误状态、右键菜单、键盘快捷键，以及保存后显示的 toast。这些隐藏界面才是 UI 的主要组成部分。阅读 hidden-ui.md。

Refactoring UI 原则

Adam Wathan 和 Steve Schoger 合著的 Refactoring UI 一书为布局为何显得协调提供了相关术语。书中的每一章在此都有对应的参考文件。

• 层级， 并非所有元素都同等重要。通过弱化其他元素来突出重点。标签是最后的选择。区分视觉层级与文档层级。阅读 hierarchy.md。
• 间距， 先留出过多的空白，再使用尺寸系统。不要为了填满屏幕而填满屏幕。避免令人困惑的间隙。阅读 spacing.md。
• 排版， 建立字体比例。控制行长（45-75ch）。行高应与字号成比例。让基线对齐，而不是居中对齐。阅读 typography.md。
• 颜色， 弃用十六进制，改用 HSL 或 OKLCH。为每种色相定义由 9 个色阶组成的系统。不要让亮度削弱饱和度。灰色不一定非得是中性色。颜色绝不能成为唯一的信息提示。阅读 color.md。
• 层次感， 模拟光源。阴影传达高度。使用两部分阴影（近距离阴影 + 环境阴影）。扁平设计仍可通过重叠和明度对比营造层次感。阅读 depth.md。
• 完善细节， 强化默认样式。添加强调色边框。为空白背景增添装饰。绝不要跳过空状态。减少边框，增加明度对比。阅读 finishing.md。

仪表板专用模式

构建或改进仪表板、表格、KPI 区域或数据密集型视图时，也请阅读 dashboard-patterns.md。其中涵盖：

• KPI 卡片模式（标签、数值、变化量、迷你趋势图）
• 表格优化（枚举值使用标签、数值右对齐、长文本截断、非活动行弱化显示、固定表头、悬停时显示隐藏操作）
• 筛选栏约定（切换组选项、组合框、日期范围、另存为视图）
• 侧边栏导航密度
• 何时使用图表而非表格（只要数据有有意义的 x 轴）

衔接各组件库技能

四项组件库技能会告诉你该使用哪个 Helm / Aura / NG-ZORRO / Material 组件。这项技能会告诉你如何让它看起来更出色。衔接文件将每项原则映射到这四个组件库，包括应覆盖哪些设计令牌、应选择哪种密度模式，以及哪些常见默认设置开箱即用时并不合适。请阅读 library-bridge.md。

工作原则

1. 生成前先评审。 如果用户已有代码，请先阅读并指出具体问题（灰色文字叠在彩色背景上、没有截断、未弱化显示状态），再进行重构。指出问题也能让用户有所收获。

2. 必要时展示前后对比。 更改间距、层级或颜色时，用一句话说明原因，让改动不显得莫名其妙。“将评审者列从 152px 缩减到 96px，让头像紧贴行的右侧内边距，而不是留着空白漂浮在一旁。”

3. 优先使用 Tailwind，并兼顾设计令牌。 四项组件库技能都能与 Tailwind 组合使用。一次性的外观优化可使用工具类，但应优先使用主题令牌（text-muted-foreground、border-border、bg-card），这样深色模式和主题设置都能自动生效。切勿硬编码十六进制值。

4. 密度是选择，不是默认值。 组件库的默认密度通常不适合仪表板，显得过于宽松。请通过组件库的密度令牌进行收紧（Material：density-3，Spartan：较小的 size 变体，PrimeNG：--p-form-field-padding，ZORRO：nzSize="small"）。请参阅 library-bridge.md。

5. 没有充分理由就不要新增组件。 如果 Helm/PrimeNG/NG-ZORRO/Material 组件可以满足需求，就使用它们。自定义组件也会带来自身的缺陷。

6. 空、加载和错误状态缺一不可。 每个异步区域都要包含这三种状态。请使用组件库的 Skeleton / Empty / Alert 基础组件。

7. 无障碍性也是技艺的一部分。 包括焦点环、仅含图标按钮的 ARIA 标签、键盘快捷键和对比度。各组件库技能中的 accessibility.md 介绍了具体方法；此处强调的是意图。