ui-ux

Dashboard 系统的 UI/UX

第 0 项没完成之前，本轮一行代码都不要写。 默认按设计师的方式做（references/design-process.md，U 分支）：先写需求说明、 梳理每个页面的主要任务，提供 2–3 个线框图，用户选定后再搭建。无论需求用越南语 还是英语都一样。该分支的两个等待确认点（确认需求说明、选择线框图）是仅有的两个 可以停下来提问的地方（设计系统流程有一个单独的确认点 D9；Logo 流程有一个 选择 Logo 的确认点，见 components/logo.md）。除了这些确认点，不要提问：需求 不明确之处采用默认方案，并在交付时说明自己做了哪些选择。 只有需求明确提出时（问题 1），才走其他分支：检查现有 UI（references/review.md） 就直接检查，要修改则先询问；重建并保留品牌风格；按 skill 的风格重建； 重构；不提供线框图，直接搭建；先搭建设计系统；修改一个小型组件。

这个 skill 不会用形容词来教“什么才算好看”。它做三件事：搭建之前按正确的顺序 进行，禁止那些会让界面一眼看出是 AI 搭建的习惯，并用数字约束让其余部分 自然保持整洁。

范围：应用内页面。Dashboard、列表、表格、表单、设置、modal。不包含营销页面， 价格表除外（references/layouts/pricing.md）。

**如果需求属于 skill 尚未教授的 UI 类型，先用一句话说明，然后仍然继续完成。**包括： landing page、介绍页面、网站首页；面向买家的网店页面（店铺首页、商品页面、购物车、 结账）；博客（博客首页、文章阅读页面）；以及类似类型（portfolio、活动页面）。这些 类型的管理端（订单、商品、文章管理）属于应用内页面，不在此范围内。说明文字放在 第一条回复的开头，审计提示之前，并使用需求所用的语言：

提示：skill 尚未教授 landing page / 网店 / 博客的设计，因此我仍然可以完成，但效果可能不如应用内页面。与应用内页面重合的部分（价格表、可供浏览选择的列表、表单）仍会遵循已审定的样例。

这只是说明，不是确认点：不要停下来询问是否继续，像处理其他需求一样继续执行问题 1。 没有样例的页面，按“搭建一个没有样例的页面”流程处理（见 references/principles.md 末尾）。⚑

这个 skill 只负责界面：布局、风格，以及每种状态的外观（选中、禁用、空白、 加载中、错误、单页、无数据行）。不要自行编写处理逻辑：点击页面时调用什么、 更改行数时跳转到哪里、是否保存到 URL、调用哪个 API。将这些留给空的 prop 或 handler（onPageChange、onConfirm），由用户自行接入。需要展示多种状态时，在旁边 并列构建每种状态一个静态示例，不要构建可交互版本供用户查看。

---

第 0 项之前 — 检查新版本 ⚑

在一个会话中首次调用 skill 时，运行 node <此 skill 所在目录>/scripts/check-update.mjs。 这不属于第 0 项，即使与其他命令同时运行也可以。

• 没有输出：保持静默，不要提及。
• 输出 UPDATE <旧版本> -> <新版本> | <命令>：回复必须以一行开头，使用需求所用的 语言：“Skill ui-ux 有新版本 <新版本>（当前使用 <旧版本>），更新：<命令>”。这一行 还要放在 UI 类型尚未教授的说明之前。然后在本轮中立即继续主要任务。
• **不要询问，也不要自行运行更新命令。**用户想更新时可以自行运行。中途更新会导致搭建 过程中规则发生变化。
• 没有 Node、命令出错或权限被拒绝时：忽略，不要说明。

---

0. 四个问题，严格按以下顺序

问题 1 — 需求要走哪条路径？默认按设计师的方式

这是第一步，优先于其他所有事项。不同路径的风险、步骤顺序以及需要审批的人都不同。

按表格顺序阅读需求，遇到第一条匹配项就停止。项目负责人已确定：最后一行是默认路径；只有需求明确提到时，才使用前九条路径（无论是越南语还是英语）。

需求内容	路径
将新版本与原版对比（“与原版比较”、“与原页面比较”、“有什么改进”、“更好还是更差”、“和……比起来已经可以了吗”、“compare with the original”、“is it better than before”）	references/review.md，V6：以相同方式截取两个版本，列出原版 / 新版 / 更优的一方的对比表，必须找出较差的项目，并逐项提出改进建议。用户选择项目之前不要修改。在此处停止第 0 部分 ⚑
想知道 UI 哪些地方不太理想（“帮我看看”、“review”、“哪些地方不太理想”、“看起来很乱”、“check this UI”、“what's wrong with”，发送截图或他们的应用链接请你查看）	打开 references/review.md，走 V 分支的检查模式：先制作前后对比表，用户选择项目后再修改。在此处停止第 0 部分；交付时按 V5，而不是 S15 ⚑
重做但保留品牌 / 保留界面（“保留品牌”、“保留颜色”、“保留当前界面”、“只做精简”、“keep the brand”、“keep the current look”）	references/review.md，保留品牌重建模式：保留页面框架，用技能中的组件替换原有控件，并保留颜色的作用。若需求要求去掉旧样式，则不属于此路径，请看按技能风格重建一行。在此处停止第 0 部分 ⚑
重构 / 清理代码但保持外观不变（“refactor”、“改用 Tailwind”、“清理 CSS”）	打开 references/refactor.md，走 L 分支。在此处停止第 0 部分——该分支有自己的默认流程，从“下结论前先测量”开始
制作 logo（“制作 logo”、“构建 logo”、“替换 logo”、“design a logo”）	打开 references/components/logo.md：先执行问题 2 的审查，然后制作一个logo 选择页面，在侧边栏、登录屏幕和浏览器标签页中展示三个方向。一个确认关卡：用户选择方向；如果需求中有“始终”，就直接构建推荐方向。在此处停止第 0 部分 ⚑
直接构建，不要线框图（“直接构建”、“不需要线框图”、“just build it”、“skip the wireframe”）	走 U 分支的不绘制线框图模式：执行 U1、U2，在心中选定准备推荐的方案，然后直接按该方案构建（design-process.md，文件开头）。不要提问。问题 2 的审查仍会在 U1 执行。在此处停止第 0 部分
先搭建设计系统（“design system”、“先搭建组件”、“UI kit”、“先确定 token / spacing / typography”、“build a design system”、“component library first”）	打开 references/system.md，D9：token、D1 中的七个要素，以及需求明确提到的内容；制作一个设计系统展示页。不绘制线框图。一个确认关卡：审批该页面；后续屏幕按常规路径构建。在此处停止第 0 部分，问题 2 的审查除外 ⚑
小于一个屏幕的工作：修改一个组件、添加一个下拉菜单、修复一个错误、更换一种颜色	继续问题 2，按默认布局构建（问题 4），不要提问
按技能风格重建，去掉旧样式（“完全采用技能风格”、“去掉旧样式”、“改成技能的风格”、“不需要保留旧样式”）	references/review.md，按技能风格重建模式：保留页面框架，按技能风格同时改变外观和颜色的作用。在此处停止第 0 部分 ⚑
所有构建或重做一个及以上屏幕的需求（“构建订单列表屏幕”、“把这个页面重新做漂亮些”、“按技能重建”、“从头设计”、“build a settings page”、“redesign this screen”），包括新产品或已有屏幕	默认路径。 打开 references/design-process.md，走 U 分支：整理 brief 和每个屏幕的主要工作，然后提供 2–3 个线框图，用户选择后再构建。在此处停止第 0 部分，问题 2 的审查除外：已有 UI 的项目也要在 U1 执行审查，且在编写 brief 之前 ⚑

如果需求附有他们自己的线框图，那就已经完成了线框图步骤：从 U4 进入 U 分支，并按图片构建（S13–S15）。如果需求既要清理代码又要改变外观，先走 U，之后再按 L 清理。如果需求要求检查或保留品牌，就用 V 替代 U；L 仍放在后面。

问题 2 — 项目正在使用什么？（自行检查，别问）

审计是硬性门槛，不是参考步骤。 在完成下面的命令块之前，不得打开布局文件，不得提出布局方案，也不得编写任何代码——即使任务小到只是“添加一个下拉菜单”。

此技能以代码库为准，不把自己的工具套用到别人的项目上。 分三层审计：技术栈（项目用了什么）、组件（准备构建的东西是否已经存在）和风格（项目当前是扁平、玻璃、渐变还是深色）。

# Tầng 1 — stack
ls package.json 2>/dev/null || echo "KHÔNG CÓ package.json — xem dòng cuối bảng"
cat package.json 2>/dev/null | grep -E '"(tailwindcss|@radix-ui|@mui|antd|@chakra|bootstrap)"'
ls components/ui src/components/ui 2>/dev/null          # dấu hiệu shadcn
# thư viện chuyên dụng: biểu đồ, lịch/ngày, bảng, danh sách ảo
cat package.json 2>/dev/null | grep -E '"(recharts|chart\.js|react-chartjs-2|echarts[a-z-]*|@tremor/react|@nivo/[a-z]+|victory|react-apexcharts|react-day-picker|react-datepicker|@mantine/dates|@fullcalendar/[a-z]+|react-big-calendar|date-fns|dayjs|@tanstack/react-table|@tanstack/react-virtual|react-window|react-virtuoso|ag-grid-react)"'
grep -rn "@import\|@theme\|--primary\|--brand\|font-family" \
  app/globals.css src/index.css tailwind.config.* 2>/dev/null | head   # không có `@import "tailwindcss"` = không preflight, W9

# Tầng 2 — thứ sắp dựng đã có chưa. Thay TÊN bằng thứ đang dựng:
# avatar, dropdown, menu, modal, dialog, button, input, badge, toast...
find . -path ./node_modules -prune -o -iname "*TÊN*" -print 2>/dev/null | head
grep -rliE "function TÊN|const TÊN|export.*TÊN" --include="*.tsx" --include="*.jsx" \
  --include="*.vue" --include="*.svelte" . 2>/dev/null | grep -v node_modules | head

第二层最容易被跳过。 项目已有 Avatar，你却又构建一个，应用里就会有两种头像样式，新建的还会与其他地方不一致。已有组件就用他们的，只有违反规范时才调整令牌。

继续之前先用一行汇报审计结果，即使什么也没找到：

Audit: Next + Tailwind v4，有 shadcn，令牌在 globals.css。已有 Avatar，位于 components/ui/avatar.tsx——使用它。没有下拉菜单——新建。

这一行能让跳过审计的行为显而易见。没有这一行，用户就不知道 AI 是检查过了还是在猜。

第三层——风格。 统计有相关信号的文件数量，不要数行数：

count_files() {
  grep -rlE "$1" --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
    --include='*.html' --include='*.css' --include='*.scss' . 2>/dev/null \
    | grep -viE 'node_modules|dialog|modal|popover|dropdown|menu|select|toast|tooltip|sheet|drawer|command' \
    | wc -l | tr -d ' '
}
echo "glass:    $(count_files 'backdrop-blur|backdrop-filter')"
echo "gradient: $(count_files 'bg-gradient-|bg-linear-|bg-radial-|linear-gradient\(|radial-gradient\(')"
echo "nổi:      $(count_files 'shadow-(md|lg|xl|2xl)')"
# Màu: nền / viền / chữ có sắc dùng làm trang trí hay phân vai, không phải trạng thái
echo "màu:      $(count_files '(bg|border|ring)-(blue|sky|indigo|violet|purple|fuchsia|pink|cyan|teal)-(50|100|200)|bg-primary/(5|10|15|20)|bg-(accent|brand)')"
# Thang màu biểu đồ có sẵn (shadcn sinh --chart-1..5)
grep -rhoE -- '--(chart|categorical|category)-[a-z0-9-]*' --include='*.css' . 2>/dev/null | grep -v node_modules | sort -u | head
# Tối: chỉ cần MỘT file, là layout gốc
grep -rlE '<(body|html)[^>]*(bg-black|bg-(zinc|neutral|slate|gray|stone)-9[0-9]{2})|color-scheme: *dark' \
  --include='*.tsx' --include='*.jsx' --include='*.html' --include='*.css' . 2>/dev/null | grep -v node_modules | head -3
# Token phong cách: có là có chủ đích, dù đếm file ra ít
grep -rhoE -- '--(glass|gradient|shadow|blur)[a-z0-9-]*' --include='*.css' . 2>/dev/null | grep -v node_modules | sort -u | head

这条命令有意跳过 dialog、dropdown、toast 等文件，因为 M15 允许浮层带阴影和模糊。不跳过的话，任何使用 shadcn 的扁平风格项目都会被算作“浮层风格”。

根据 references/styles.md 中的 P4 解读数量。项目没有独特风格时，就按扁平风格处理；有独特风格时，就遵循项目风格，并在交付时说明（P1）。

在 Audit: 行中补充风格信息：

Audit: Next + Tailwind v4，有 shadcn。已有 Avatar。风格：7 个文件采用玻璃风格（卡片、侧边栏、页眉）——本屏也采用玻璃风格，以保持一致。

然后按此表处理：

找到的内容	怎么做
Tailwind（技能默认配置）	正常使用 utility。Tailwind v4 则在动 @theme 之前先阅读 references/tailwind-v4-traps.md
没有 Tailwind	遵循他们的约定——CSS Module、styled-components、SCSS，什么都可以。此技能规定的是令牌、节奏、布局和范围，不规定 bro 如何编写样式。技能中的规则使用 Tailwind 类；将颜色转换为 references/tokens.css 中的变量，不要自行选择色值：text-rose-700 → var(--danger)，徽标 bg-emerald-50 text-emerald-700 → --success-bg / --success。对照表见 M7、M30；头像颜色见 components/avatar.md
shadcn / Radix / MUI / Ant / 内部组件库	使用他们的组件。 在已有 shadcn 的项目里重写一个 Button，只会破坏一致性，不会让界面更好看
专用库（图表、日历、表格、虚拟列表）	已有就正确使用，调整到符合技能要求的样式（关闭它默认启用的效果，颜色使用令牌）。没有就不要自行安装：按照 references/components/ 中的示例正常构建，且仅在自行构建成本较高时才提出建议（大数据量、缩放、实时数据、多种图表）。选择标准：轻量、解决实际需求、支持令牌着色、仍在维护、适合现有生态。用一行说明建议和理由；是否安装由用户决定（N10）。图表配置表见 components/charts.md
没有任何组件	从 references/components/ 中获取代码建议。明确说明这只是建议，他们可以自行决定放在哪里
没有 package.json	使用纯 HTML/CSS，或 WordPress、PHP、Rails、Django。references/components/ 中的示例使用 .tsx 编写——先转换成 HTML 标签 + class 再交付，不要把 JSX 粘贴到没有 React 的项目中。references/tokens.css 可以直接粘贴，它是纯 CSS

此时也要检查文案所用的语言——搜索 i18n 和现有标签，遵守 T24 规则。先确定再编写第一个标签，因为猜错了就得修改所有标签，而不只是一行。文案不是越南语时，打开 T28、T29。

已有令牌就直接使用，不要询问。 只有搜索结果为空时，才使用 references/tokens.css 并直接构建，即使客户可能已经有品牌规范：强调色和字体只需放在一个位置，交付时指出该位置（S15），他们就可以自行替换。 绝不要询问字体数量。 滚动条一定要复制，即使项目已有 token。“使用他们的 token”只适用于颜色和字体。tokens.css 中的滚动条代码块（从 * { --scrollbar-thumb 到 .scrollbar-clean 结束）以及 ScrollbarAutohide 组件（I18）描述的是样式，不是品牌：在原始 CSS 中搜索 ::-webkit-scrollbar，如果没有或版本不同，就复制过来。缺少这段代码，浏览器就会在所有滚动区域绘制默认滚动条，又粗又难看：页面、侧边栏、横向滚动表格、下拉菜单。纯 HTML 页面、线框图也要复制。

使用他们的库时，应用 skill 的方式是调整 token 以匹配，再加上几项不合规的默认设置。对于 shadcn，通常有三个地方：

• Input 默认是 bg-transparent → 改为 surface 背景。页面背景上的透明输入框会让用户看不出那是输入框。
• Button 默认有多种 variant 和 size → 不要删掉库里的选项，只需限制自己使用规则 I1 中的四种样式。
• 检查阴影：许多套件默认给卡片设置 shadow-sm，而规则 M15 只允许浮层使用阴影。

问题 3 — 希望 UI 看起来是什么样？

默认风格是扁平风格，参见 references/styles.md 中的 P1：

• 用户主动提出风格（“glassmorphism 风格”“SaaS 落地页式渐变”）→ 按要求实现，不要再问。打开 references/styles.md，找到对应风格的代码块。
• 第 3 层审查发现项目采用了不同于扁平风格的风格 → 遵循项目风格，直接实现。交付时用一行说明采用了什么风格、在哪里发现的；如果想要扁平风格，请告诉我。示例见 P1。
• 其他情况 → 使用扁平风格，不要询问风格。

无论选择哪种风格，都要打开 references/styles.md 中对应的代码块：其中说明哪些扁平风格审美规则可以覆盖，以及该风格特有的陷阱。原则不受任何风格覆盖（P2）。

有参考图片、有文字描述，或有想要仿照的产品 → 以它们为准，忽略本题其余部分。

他们说“还不知道”“随便啦”“怎么好看怎么做” → 按方向 A 实现，交付时用一行说明还有方向 B 和 C，想要的话告诉我。不要提前询问。

方向	外观	适用场景
A. 纤细线条扁平风 (skill 默认)	浅灰背景、白色卡片、极浅的 1px 边框、约 12px 圆角、无阴影。通过字号和字重体现层级	大多数仪表盘。多个小区块并排时仍能看清边界。skill 中所有规则都是按这个方向编写的
B. 凹陷区块风	无边框。通过背景色差异 + 留白区分区块，白色卡片浮于灰色背景上。圆角更大	区块较少、每个区块都较大的页面。比 A 更通透柔和。代价：小区块并排时边界会模糊
C. 高密度数据风	表格是主角。小字号、紧凑行距、小圆角、清晰分隔线，优先让用户一次看到更多行	人们整天使用的屏幕：运营表格、交易记录、日志。代价：看起来“密”，不适合总览页面

选择 B 或 C 时，要明确说明它覆盖了哪些规则：B 覆盖 M13（通过边框区分）和 M15；C 覆盖 references/budgets.md 中关于节奏的部分。交付时记一行，避免下一轮有人“按规则修正”。

选好后，顺便回答这个问题：**需要深色模式吗。**默认不需要——参见 M20。

需求包含表单：输入框默认不带左侧图标。不要问，直接实现为无图标，然后在交付时用一行说明：*“输入框目前是纯净样式，想加左侧图标请告诉我。”*如果他们需要，就按照 references/components/input.md 实现，图标按 F15 选择。

认证页面的默认样式也采用同样的做法，见 references/layouts/form.md：直接使用默认样式 + 一行说明，而不是列出一组问题。

第 4 条——布局：搭建默认布局，简短说明

用户给出线框图时，AI 能做出像样的成品；用户只用文字描述时，AI 就会乱画，即使已经提供了完整的配色、字号和间距尺度。原因是：设计系统说明用什么颜色、字号多大、间距多少，却不说明元素应该放在哪里。 布局才是决定页面好看与否的关键，再多颜色规则也弥补不了凭空编造的布局。

解决方法：每种屏幕类型都只有一个默认布局，放在 layout 文件中。不凭空编造，也不提供多个方案。

1. 识别屏幕类型。 明确说明它属于哪种类型：应用内屏幕、表单、浮层，还是定价页。屏幕类型也决定了要打开哪个 layout 文件。
2. 打开 layout 文件，采用默认布局。 如果文件中注明了条件（例如“字段达到 8 个时使用 B”），就按条件执行，因为这是根据需求推导出来的，不是个人偏好。
3. 直接搭建，交付时简短说明 使用了哪种布局；如果想要其他样式，请告诉我。

我搭建了横向排列的三张定价卡片，并突出显示 Pro 套餐。想合并成一个区块或把按钮移到上方，请告诉我。

Skill 负责最简单、最标准的默认布局。变体由用户决定：用户提出后就按要求修改，不再追问。

第 4 条仅适用于小于一个屏幕的任务（第 1 条）。默认走 U 分支，此处的默认布局是若干线框方案之一，通常是推荐方案。

⚠️ 旧规则已废弃，请勿恢复：“用文字提供 2–3 种布局方案，然后彻底停下等待用户选择”。废弃这条规则，是因为它要求用户在看到任何内容之前先做选择，也迫使每个 layout 文件为每种屏幕维护多个方案。U 分支的默认规则（由项目负责人确定）并不是旧规则的复活：用户是在已经看到包含真实内容、经过探测且可以点击打开的线框图后再做选择；每个 layout 文件仍然只维护一个默认布局。

屏幕类型	打开
Dashboard、入门步骤（onboarding checklist）、列表、表格、空列表、设置、个人资料、安全（双重身份验证、登录会话）、API 密钥、成员和权限、日历页（月历）、错误页面（404、403、500、维护）、报告页面（收入、按日期范围分析）、页头（面包屑 + 名称 + 按钮）、记录详情页	references/layouts/app.md
登录、注册、忘记密码、多字段表单、多步骤表单（步骤栏）、错误状态	references/layouts/form.md
Modal、滑出面板、下拉菜单、命令面板、通知面板、Toast、所有浮层的打开和关闭动效（包括 select、date picker）、需求要求添加动画但未指定库（“需求要求添加动画但未指定库”一节）	references/layouts/overlay.md
定价页、套餐选择页	references/layouts/pricing.md
同一需求中有多个屏幕	与所有搭建需求一样，进入 U 分支；references/system.md——在第一个屏幕之前，于 U4 确定原子合约。默认布局仅直接用于立即搭建或小型任务

如果已有线框图，就跳过第 4 条，直接转到第 1 节，并按 S13、S14、S15 的规则遵循图片。

---

1. 范围——S 规则

本部分保留在 SKILL.md 中，因为它适用于所有任务。关于形式的规则位于 references/ 中，参见第 2 节。

S1. 不要自行添加区块。 需求中有几个区块，就准确搭建几个。Skeleton 画了三张卡片，就交付三张卡片，不要擅自添加页头、对比表、常见问题或页脚。

S2.“做完整”不等于可以添加内容。 它只表示完成分配给你的部分。

S3. 屏幕标题不算新增内容。 用户列出了元素却漏掉标题时，可以直接添加，因为标题属于结构，而不是内容。同类元素还有输入框标签、按钮文字和错误提示。除此之外则不行——不要添加 logo、广告语、“记住登录”选项或第二个登录服务提供商。 ⚠️ 验证页面有专属默认项，请参阅 references/layouts/form.md。 产品 Logo、“忘记密码”、一个 Google 按钮和占位文本都直接构建；记住登录状态则不构建，因为需要后端。交付时用一句话说明这些选择——别把它变成一张问卷。

S4. 不要追问内容。 用户已明确列出页面包含什么，就原样保留该清单，并按照已选的线框方案呈现（小任务采用第 4 条的默认布局，或直接构建）。

例如：需求写着“登录页包含电子邮箱输入框、密码输入框、忘记密码链接、登录按钮、使用 Google 登录按钮”。内容就此敲定：U1 中的 brief 准确写明这五项，每种线框方案都包含这五项（直接构建时则直接居中呈现为一列）。不要再问是否需要 Google 按钮。

S5. 需求未明确范围时，直接采用默认范围，不要提问。

• 需求有列举（“登录页包含电子邮箱输入框、密码输入框、按钮……”）：范围已敲定，直接构建。
• 需求未明确范围（“构建一个总览页面”）：采用布局文件中该页面类型的默认模块集（总览页面：references/layouts/app.md 中的模块表），并全部构建。不要让 S1 变成“尽可能少做”，最后只交付一个薄薄的、只有 3 个模块的页面。
• 交付时，第一句话列出已构建的模块，以及表中省略了哪些模块。用户想增删时再提出。

S6. 构建 mockup 时填入合理的虚构数据，不要留空。 满页都是 [需要填写] 就看不出设计效果，只会像一张表单。填入看起来合理的数字，然后在交付时用一句话说明：此版本中的数据是虚构的。 同一条记录中的各模块必须相互吻合：活动选项卡中有一笔已取消的订单，数据卡片就不能显示 3 笔订单、12.3 万越南盾。不同选项卡中的虚构数字对不上，会让审核者以为界面计算错误。调整虚构数据使其吻合（修改创建日期、在历史记录中添加订单）是构建时该做的事，直接处理，不要提问：这不会影响逻辑或真实数据。

**S7. 只有构建版本会直接交给真实用户时，才使用 [需要填写]，且仅用于具有法律或财务后果的内容：售价、退款金额、正常运行时间承诺、条款。

S8. 虚构数据必须覆盖边界情况，而不只是好看的数据。 名称长到占两行、九位数、0、缺少图片、缺少描述、空列表。好看的数据只能让界面在遇到真实客户之前显得没问题。

S9. 使用项目已有的组件库。 请参阅第 0 部分中的第 2 条。用户明确指定使用哪个库时，就按他们说的做，别争辩。

S10. 需求中出现含义模糊的词时，采用默认含义，并在交付时明确说明。

词语	默认含义	仅在需求明确说明时采用的另一种含义
表格	数据表格	看板式 board（“拖放”、“状态列”、“board”）
卡片	card	选项卡
列表	纵向列表	下拉菜单
框	布局区域	modal（“弹出”、“popup”）
页面	一个 route	多步骤中的一页（“第 2 步”）
日历	月历	时间线（“timeline”）

交付时的第一句话要直说你的理解：“我把表格理解为数据表格。如果你指的是 kanban 看板，请告诉我，我会调整。” 如果理解错了，用户一开始就能发现，而不是等到测试时才暴露。根本教训是：“项目管理表格”曾被误解为 kanban，却没人说出来，整轮测试都白费了。当时的问题是默默选了少见的含义，而不是没有提问。

S11. 只有敲定页面类型后，才能打开 layouts/ 中的示例代码。 它回答的是“如何构建”，而不是“需求要什么”。如果有现成的 kanban 示例文件，就很容易把所有模糊需求都解读成 kanban。

S12. 用户提供图片时，自行判断图片内容，不要提问。

• 默认作为设计参考：遵循布局、配色和样式。
• 当作线框图：如果需求称其为线框图／草图／框架，或者图片只有黑白灰、矩形块和占位文字，则只参考布局，颜色和样式按技能指南处理。
• 当作现状截图：如果这是用户自己的应用截图，且用户请你查看，需求中有“帮我看看”“审查”“哪里不太对”“怎么显得奇怪”“看起来很乱”等说法。这张图是用来检查问题的，不是用来照着做的。走 V 分支（references/review.md）。如果图片对应仓库中的某个路由，而需求没有检查问题的措辞，只说搭建或重做，那么它就是 U 分支的**“之前”截图**：在 U1 中阅读，交付后与新图放在一起比较，不归入 V。⚑
• 交付时用一行说明：“我把图片作为设计参考（包括配色）”、“…作为线框图（只参考布局）”，或 “…作为你应用的现状截图（用于检查问题）”。

**S13. 布局也包括位置，不只是元素列表。**徽章位于卡片上边缘中间，就保持居中。图标框位于价格旁边，就保持在对应位置。各区块的顺序保持不变。可以替换颜色和样式，但不能挪动位置。

**S14. 线框图中的图标都保留，包括装饰性图标。**每个条目可以使用不同图标，参见规则 F17。

S15. 交付时必须说明四件事：替用户选定的默认项（对模糊需求 S10 的理解、区块组合 S5、图片类型 S12、风格 P1、第 4 条布局；每项一行，并附上“想要不同的效果可以告诉我”）、品牌替换位置（哪一行包含强调色，哪一行包含字体）、哪些数据是虚构的，以及是否制作了深色模式。默认项要放在开头，因为这些是唯一可能猜错的内容。使用用户正在使用的语言撰写，即使技能指南和 UI 标签是越南语也一样（T27）。

S16. 虚构数据中需要图片的地方应使用真实照片，不要用灰色块或绘图 ⚑。实际产品会包含图片的条目（房间、商品、文章、公司封面图、人物头像），在线框图和 mockup 中都要使用真实照片，让新页面看起来像正在运行的产品：

• 场景、物品照片：使用 Unsplash，格式为 https://images.unsplash.com/photo-<id>?w=800&q=80&auto=format&fit=crop，并与条目主题相符（出租房应配室内照片，招聘信息应配办公室照片）。不要自行编造 <id>：先在 Unsplash 上查找，再对每个链接运行 curl -sI；如果返回的不是 200，就换一个。每个条目使用不同的照片。
• 人物头像：使用人像（https://randomuser.me/api/portraits/women/<0-99>.jpg、 .../men/<0-99>.jpg），并与虚构姓名的性别相符。图片仍遵循 components/avatar.md 的格式。
• 虚构公司 Logo：使用 components/avatar.md 中的字母方块（圆角正方形），不要给虚构公司使用真实品牌的 Logo。
• 仍要保留 S8 的边缘情况：至少有一个条目没有图片、一个人没有头像，以展示回退为字母或“暂无图片”框的效果。
• 如果使用 Next.js，在 next.config 的 images.remotePatterns 中添加这两个主机；如果项目有自己的图片（public/ 目录或其 CDN），则优先使用项目图片。
• 交付时，在 S15 的“虚构数据”说明中也要注明：来自 Unsplash 和 randomuser 的图片是示例图片，正式运行前应替换为真实图片。

八个条目都用相似的绘图，即使布局正确，页面看起来还是会“很无聊”。

---

2. 何时打开哪些文档

SKILL.md 只保留始终需要的内容。只打开当前需要的文件，然后开始处理，不要一次性加载全部内容。

单一来源原则：每条规则只存在于一个正确的文件中。SKILL.md 只能指向规则编号，不得抄写规则内容。如果发现同一条规则在两个地方都有说明，其中一处就是错的。

类别	文件	用途
S	SKILL.md 第 1 节	范围：可以做什么，不能擅自添加什么
N	references/principles.md	凌驾于所有其他规则之上的十二条原则，每条都附带一项测试。没有明确规范时，以此为准
M	references/rules-color.md	颜色、边框、阴影、深色模式、令牌
T	references/rules-type.md	文字、字体、换行、截断、复制、回复语言和英文复制
F	references/rules-form.md	区块、网格、圆角、留白、图标、效果
I	references/rules-state.md	按钮、悬停、焦点、列表、模态框
R	references/responsive.md	所有窄屏规则，375px 检查阈值
D	references/system.md	涉及多个屏幕的需求：原子设计规范；先搭建设计系统（D9）
V	references/review.md	检查现有 UI：三类错误、宽度扫描、项目深色模式、前后对照表；将新版本与原版比较（V6）
L	references/refactor.md	重构现有代码库
U	references/design-process.md	从零开始设计：需求说明、每个屏幕的主要任务、方案线框图、构建
W	references/tailwind-v4-traps.md	存在旧 CSS 时的 Tailwind v4 陷阱
P	references/styles.md	视觉风格：扁平、凸起、玻璃、渐变、深色。可覆盖的规则、特有陷阱、对比度

始终打开，适用于所有任务：

需要	打开
通用原则、适用于没有范例的 UI 的测试	references/principles.md
预算、节奏、字号阶梯	references/budgets.md
调色板、字体、品牌切换方式	references/brand-tokens.md + references/tokens.css
完成前检查	references/checklist.md
项目已敲定的规则及已被否决的理由：选择颜色和按钮权重（红色还是中性色、primary 还是描边）前先打开	references/locked-rules.md

构建对应区块时打开：

需要搭建	打开
卡片、widget、面板	references/components/card.md
详情页的标签和值区块	references/components/description-list.md
按钮	references/components/button.md
输入框、表单字段	references/components/input.md
OTP 输入框	references/components/otp-input.md
带 − + 按钮的数量输入框	references/components/quantity-input.md
页面顶部的就地编辑名称（项目、文档名称）	references/components/inline-edit.md
标题栏或页面名称上方的路径（面包屑）	references/components/breadcrumb.md
可点击排序的表格列标题	references/components/sortable-header.md
复选框、单选框、开关、选择框、时间选择器、日期选择器、日期范围、日期时间、卡片式选项	references/components/choice-controls.md
列表行	references/components/list-row.md
时间线、活动历史	references/components/timeline.md
文件夹树、可展开和折叠的嵌套树	references/components/tree.md
Accordion、常见问题、就地展开/折叠的项目	references/components/accordion.md
评论区、嵌套回复	references/components/comment-thread.md
AI 助手聊天框：双方消息、工具使用步骤、后续提问建议、消息输入框	references/components/chat.md
数值范围、价格范围滑块	references/components/range-slider.md
多标签输入框（收件人邮箱、标签）	references/components/tag-input.md
空列表、加载错误	references/components/empty-state.md
加载状态：骨架屏、二次加载、屏幕内即时切换、“正在保存… / 已保存”、长时间运行的任务	references/components/loading.md
页面内通知栏（信息、需要注意、错误）	references/components/banner.md
筛选 chip、已应用的筛选 chip（带 ×）、纯图标按钮、标签栏（4 种变体）、分页	references/components/small-controls.md
头像、重叠头像组	references/components/avatar.md
产品 logo（侧边栏顶部、身份验证界面、独立错误页面）和 favicon，适用于项目尚无 logo 的情况	references/components/logo.md
柱状图、折线图、数据、进度条	references/components/charts.md
文件拖放框、上传中的文件列表	references/components/file-upload.md

搭建页面是拼装，不是重新绘制。 页面上凡是属于上表的元素，都要打开对应文件并照搬规范，即使它只是角落里的一个小按钮。不要自行捏造“适合这个页面”的变体：同一个 badge 在表格里一种样式、在抽屉里另一种样式，就像把两个 app 拼到了一起（D1、D2）。页面需要的元素尚无对应文件时，遵循 references/principles.md 末尾的 “搭建一个尚无范例的元素” 流程：借用最接近的样式框架，搭建所有边界情况，probe 自行修正，用肉眼检查五个问题，交付时说明一句 “X 尚无已批准的范例，我借用了 Y 的样式框架”。

已批准的示例代码（仅在确定屏幕类型后打开，遵循 S11 规则）： references/layouts/app-kanban.html

---

3. 六件不能忘的事

摘自 references/checklist.md。报告完成前，请跑完完整检查清单。

• 是否回答了第 0 节的第 1 个问题——（默认）作为一名设计师、检查 UI、保留品牌进行重建、按技能偏好重建、重构、直接构建，还是先构建设计系统。如果需求没有明确说明其他路径，却直接开始构建、跳过 brief 和线框图，那就是答错了第 1 个问题。
• 是否检查过代码库，确认他们使用的是 Tailwind、shadcn 还是其他工具，而不是把自己的一套强加上去。
• 是否按照选定的线框图方案（分支 U）构建，而不是自行编造。如果是小任务或选择直接构建，则应遵循布局文件中的默认布局，交付时加一句“想要其他风格的话请告诉我”。
• 是否自行添加了需求之外的章节。
• 是否用 scripts/probe.mjs 打开实际页面并查看截图（第 3 道关卡），还是只靠重读代码来回答检查清单。页面在 375px 宽度下出现横向滚动就是坏了。
• 是否运行了 references/principles.md 中的十二项测试，尤其是针对尚无示例的内容。

---

4. 添加新规则时遵循以下规范

这个技能曾经因为添加规则而变得更糟。为了解决某个症状而写的规则，往往会在下一次构建时引发另一个症状。

• 每轮最多新增 5 条规则。
• 每条新规则都必须明确说明它取代或与哪条现有规则冲突。推翻旧规则时，留下一个 ⚠️ 区块，明确写出“旧规则已弃用，勿恢复”，并说明原因。
• 规则必须附带适用条件。应该写“在 app 中做 X，重构时做 Y”，而不是“始终做 X”。
• 三轮测试后仍未实际发现问题的规则，删除。
• **一条规则只放一处。**将规则添加到对应类别的文件中。SKILL.md 只能列出规则编号。
• 添加规则后，检查 layouts/ 和 components/ 中的示例文件，确认它们没有违反新规则。示例代码会被原样复制，因此其中的错误会扩散到各处。这种情况已经发生过两次。
• **技能只记录规则和原因，不记录历史。**不写日期、不写测试页面或项目名称、不写“第二轮”，也不叙述尝试过的版本。对于 AI 容易再次采用的错误做法，用一句“不要做 X：后果”说明。日期和相关位置写在 commit message 中。项目负责人作出的决定应保留原始动词（“敲定”“放弃”“选择”等），不附日期，也不要擅自改成“敲定”。技能中唯一允许记录日期的地方，是 locked-rules.md 中的“敲定日期”列。
• **在组内连续编号。**不要在中间插入 15b、15c、17d 之类的编号。
• 尚未经过任何测试的规则必须加上 ⚑ 标记，让用户知道这条规则还没人验证过。