Back to Details

ui-ux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UI/UX cho hệ thống dashboard

面向 dashboard 系统的 UI/UX

Chưa đi hết mục 0 thì KHÔNG viết một dòng code nào trong lượt này. Mặc định là làm như một designer (
references/design-process.md
, nhánh 
U
): brief, việc chính của từng màn, 2–3 wireframe, người dùng chọn rồi mới dựng. Đề viết tiếng Việt hay tiếng Anh đều vậy. Hai cổng chờ của nhánh đó (duyệt brief, chọn wireframe) là hai chỗ duy nhất được dừng hỏi (lối design system có một cổng riêng, 
D9
). Ngoài các cổng đó thì không hỏi: chỗ nào đề chưa rõ thì lấy mặc định, báo lúc giao mình đã chọn gì. Các nhánh khác chỉ khi đề nói rõ (câu 1): soi UI đang có (
references/review.md
) thì soi luôn, sửa thì hỏi; dựng lại giữ brand; dựng lại theo gu skill; refactor; dựng luôn không wireframe; dựng design system trước; sửa một component nhỏ.
Skill này không dạy "thế nào là đẹp" bằng tính từ. Nó làm ba việc: đi đúng thứ tự trước khi dựng, cấm những thói quen làm giao diện lộ ngay ra là AI dựng, và ràng buộc bằng con số để phần còn lại tự sạch.
Phạm vi: màn hình trong app. Dashboard, danh sách, bảng, form, cài đặt, modal. Không lo trang bán hàng, trừ bảng giá (
references/layouts/pricing.md
).
Đề là loại UI skill chưa được dạy thì báo trước một dòng, rồi vẫn làm. Gồm: landing page, trang giới thiệu, trang chủ website; cửa hàng online phía người mua (trang chủ shop, trang sản phẩm, giỏ hàng, thanh toán); blog (trang chủ blog, trang đọc bài); và loại tương tự (portfolio, trang sự kiện). Phía quản trị của chúng (quản lý đơn, sản phẩm, bài viết) là màn trong app, không thuộc nhóm này. Câu báo nằm đầu câu trả lời đầu tiên, trước dòng audit, theo ngôn ngữ của đề:
Lưu ý: skill chưa được dạy cho landing page / cửa hàng online / blog, nên mình vẫn làm được nhưng kết quả có thể chưa đẹp bằng màn trong app. Phần nào trùng màn app (bảng giá, danh sách lướt để chọn, form) thì vẫn theo mẫu đã duyệt.
Chỉ báo, không phải cổng: không dừng hỏi có làm tiếp không, đi tiếp câu 1 như mọi đề. Phần trang không có mẫu thì theo luồng "Dựng một thứ chưa có mẫu" (cuối 
references/principles.md
). ⚑
Skill lo giao diện: bố cục, style, và mỗi trạng thái trông ra sao (đang chọn, khoá, rỗng, đang tải, lỗi, một trang, không dòng nào). Không tự viết logic xử lý: bấm trang thì gọi gì, đổi số dòng thì nhảy về đâu, lưu vào URL hay không, gọi API nào. Chỗ đó để prop hoặc handler rỗng (
onPageChange
, 
onConfirm
) cho người dùng tự nối. Cần xem nhiều trạng thái thì dựng mỗi trạng thái một ví dụ tĩnh cạnh nhau, không dựng bản bấm được để xem.
如果尚未完成第 0 项，绝不要在本轮写任何代码。 默认像 designer 一样工作（
references/design-process.md
，
U
分支）：brief、 明确每个画面的主要任务、提供 2–3 个 wireframe，等用户选定后再实现。无论需求使用 越南语还是英语，流程都一样。该分支的两个等待关口（确认 brief、选择 wireframe）是仅有的两处 允许暂停并询问的地方（design system 路径有一个独立关口 
D9
）。除这些关口外，不要询问：任何未明确之处都采用默认值， 并在交付时说明自己选择了什么。 其他分支只在需求明确提出时使用（第 1 问）：审视现有 UI（
references/review.md
）时必须实际审视， 需要修改时再询问；保留 brand 重新设计；按 skill 审美重新设计；refactor；跳过 wireframe 直接实现；先建立 design system；修改一个小型 component。
这个 skill 不会用形容词来教人“什么是好看”。它做三件事：在实现之前遵循正确顺序、 禁止那些一眼就能看出是 AI 所做的界面习惯，并用明确数字加以约束，让其余部分自行变得干净。
范围：app 内的屏幕。Dashboard、列表、表格、表单、设置、 modal。不负责销售页面，但价格表除外（
references/layouts/pricing.md
）。
如果需求属于尚未教授的 UI 类型，需提前用一行说明，然后仍然完成。包括：landing page、关于页面、网站首页；面向买家的在线商店（商店首页、 商品页面、购物车、结账）；blog（blog 首页、文章阅读页）；以及类似类型（portfolio、活动页面）。这些页面的管理端 （订单管理、商品管理、文章管理）属于 app 内屏幕，不在此分类中。说明必须位于首次回答的第一行， 即 audit 行之前，并使用需求所使用的语言：
注意：skill 尚未教授 landing page / 在线商店 / blog，因此我仍然可以完成， 但结果可能不如 app 内页面美观。凡是与 app 页面重合的部分（价格表、可供浏览选择的列表、表单）， 仍遵循已批准的模板。
这只是提示，不是等待关口：不要停下来询问是否继续，直接像处理其他需求一样进入第 1 问。 对于没有既定模板的页面，遵循“构建没有现成模板的东西”流程 （位于 
references/principles.md
末尾）。⚑
这个 skill 负责界面：布局、style，以及每种状态呈现出来的样子（选中、 锁定、空、加载中、错误、单页、无数据行）。不要自行编写处理逻辑：点击页面时调用什么、 改变行数时跳转到哪里、是否将状态保存在 URL、调用哪个 API。这些位置应保留为空 prop 或空 handler （
onPageChange
、
onConfirm
），由用户自行连接。如果需要展示多个状态，应将每个状态制作成一个静态示例并排展示， 不要制作成可点击版本供人操作。

0. Bốn câu hỏi, đúng thứ tự này

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

Câu 1 — Đề đi lối nào? Mặc định là như một designer

第 1 问——需求走哪条路径？默认像 designer 一样工作

Đây là câu đầu tiên, trước mọi thứ khác. Các lối khác nhau về rủi ro, về thứ tự các bước, và về người phải duyệt.
Đọc đề theo thứ tự bảng, gặp dòng đầu tiên khớp thì dừng. Chủ dự án chốt 29/09/2026: dòng cuối là mặc định, bảy dòng trên chỉ khi đề nói rõ (tiếng Việt hay tiếng Anh).
Đề nóiĐi đâu
Muốn biết UI đang có chỗ nào chưa ổn ("xem giúp", "review", "chỗ nào chưa ổn", "nhìn rối", "check this UI", "what's wrong with", gửi ảnh hay link app của họ nhờ xem)Mở 
references/review.md
, nhánh 
V
chế độ soi: lập bảng trước/sau, người dùng chọn dòng rồi mới sửa. Dừng mục 0 tại đây, lúc giao theo 
V5
chứ không theo 
S15
⚑
Làm lại mà giữ brand / giữ giao diện ("giữ brand", "giữ màu", "giữ giao diện hiện tại", "chỉ làm gọn", "keep the brand", "keep the current look")
references/review.md
, chế độ dựng lại giữ brand: giữ khung trang, thay control gốc bằng component của skill, giữ vai màu. Đề nói bỏ style cũ thì không phải dòng này, xem dòng dựng lại theo gu skill. Dừng mục 0 tại đây ⚑
Refactor / dọn code mà giữ nguyên hình ("refactor", "chuyển sang Tailwind", "dọn CSS")Mở 
references/refactor.md
, nhánh 
L
. Dừng mục 0 tại đây — nhánh đó có bộ mặc định riêng, bắt đầu bằng "đo trước khi kết luận"
Dựng luôn, không wireframe ("dựng luôn", "không cần wireframe", "just build it", "skip the wireframe")Nhánh 
U
không vẽ wireframe: làm 
U1
, 
U2
, chọn phương án sẽ khuyên dùng trong đầu, rồi dựng thẳng theo nó (
design-process.md
, đầu file). Không hỏi. Audit câu 2 vẫn chạy, ở 
U1
. Dừng mục 0 tại đây
Dựng design system trước ("design system", "dựng component trước", "UI kit", "chốt token / spacing / typography trước", "build a design system", "component library first")Mở 
references/system.md
, 
D9
: token, bảy nguyên tố của 
D1
cộng thứ đề nêu tên, một trang xem design system. Không vẽ wireframe. Một cổng: duyệt trang đó; màn dựng sau đi lối bình thường. Dừng mục 0 tại đây, trừ audit câu 2 ⚑
Việc nhỏ hơn một màn: sửa một component, thêm một dropdown, sửa một lỗi, đổi một màuĐi tiếp câu 2, dựng theo bố cục mặc định (câu 4), không hỏi
Dựng lại theo gu skill, bỏ style cũ ("hoàn toàn theo gu skill", "bỏ style cũ", "đổi sang gu của skill", "không cần giữ style cũ")
references/review.md
, chế độ dựng lại theo gu skill: giữ khung trang, đổi cả dáng lẫn vai màu theo gu skill. Dừng mục 0 tại đây ⚑
Mọi đề dựng hay làm lại một màn trở lên ("dựng màn danh sách đơn hàng", "làm lại trang này cho đẹp", "dựng lại theo skill", "thiết kế từ đầu", "build a settings page", "redesign this screen"), sản phẩm mới hay màn đã cóMặc định. Mở 
references/design-process.md
, nhánh 
U
: brief và việc chính của từng màn, rồi 2–3 wireframe, người dùng chọn rồi mới dựng. Dừng mục 0 tại đây, trừ audit câu 2: vẫn chạy ở 
U1
, trước khi viết brief, cho cả dự án đã có UI ⚑
Đề có ảnh wireframe của chính họ thì đó đã là bước wireframe: vào nhánh 
U
từ 
U4
, dựng theo ảnh (
S13
–
S15
). Đề vừa muốn dọn code vừa muốn đổi hình thì đi 
U
trước, dọn theo 
L
sau. Đề nói soi hay giữ brand thì 
V
thay chỗ 
U
, 
L
vẫn sau.
这是第一个问题，必须先于其他所有事项。不同路径在风险、步骤顺序和需要谁审批方面各不相同。
按表格顺序阅读需求，遇到第一条匹配项就停止。项目负责人于 29/09/2026 敲定：最后一行是默认路径， 上方七行仅在需求明确提出时使用（无论使用越南语还是英语）。
需求表述应走的路径
想了解现有 UI 哪些地方不好（“帮我看看”“review”“哪些地方不好”“看起来很乱”“check this UI”“what's wrong with”，并发送自己的 app 图片或链接请人查看）打开 
references/review.md
，进入 
V
分支的审视模式：先建立变更前后对照表，用户选择条目后才修改。在第 0 项此处停止，交付时遵循 
V5
，而不是 
S15
⚑
重做但保留 brand / 保留界面（“保留 brand”“保留颜色”“保留当前界面”“只做精简”“keep the brand”“keep the current look”）
references/review.md
，进入保留 brand 的重新设计模式：保留页面框架，用 skill 的 component 替换原有 control，保留颜色的职责。需求要求去掉旧 style 时不属于这一行，应查看“按 skill 审美重新设计”分支。在第 0 项此处停止 ⚑
Refactor / 整理代码但保持外观不变（“refactor”“切换到 Tailwind”“整理 CSS”）打开 
references/refactor.md
，进入 
L
分支。在第 0 项此处停止——该分支有自己的一套默认值，并以“先测量，后下结论”开始
直接实现，不要 wireframe（“直接做”“不需要 wireframe”“just build it”“skip the wireframe”）进入 
U
分支但不绘制 wireframe：完成 
U1
、
U2
，在内部选择推荐的方案，然后直接按该方案实现（
design-process.md
开头的说明）。不要询问。第 2 问的 audit 仍会运行，位置在 
U1
。在第 0 项此处停止
先建立 design system（“design system”“先做 component”“UI kit”“先确定 token / spacing / typography”“build a design system”“component library first”）打开 
references/system.md
中的 
D9
：建立 token、
D1
的七项基础元素以及需求中点名的其他元素，并制作一个 design system 预览页。不绘制 wireframe。只有一个关口：确认该页面；之后制作的屏幕仍走正常流程。在第 0 项此处停止，但第 2 问的 audit 除外 ⚑
工作量小于一个完整屏幕：修改一个 component、添加一个 dropdown、修复一个错误、更换一种颜色继续第 2 问，按照默认布局实现（第 4 问），不要询问
按 skill 审美重新设计，去掉旧 style（“完全按 skill 的风格”“去掉旧 style”“换成 skill 的风格”“不需要保留旧 style”）
references/review.md
，进入按 skill 审美重新设计模式：保留页面框架，同时按照 skill 的审美改变外观和颜色职责。在第 0 项此处停止 ⚑
所有要求新建或重做一个及以上屏幕的需求（“搭建订单列表”“把这个页面重做漂亮些”“按 skill 重新设计”“从头设计”“build a settings page”“redesign this screen”），无论是新产品还是已有屏幕**默认路径。**打开 
references/design-process.md
，进入 
U
分支：先完成 brief 和每个画面的主要任务，再提供 2–3 个 wireframe，等用户选定后才实现。在第 0 项此处停止，但第 2 问的 audit 除外：对于已有 UI 的项目，也仍要在写 brief 前于 
U1
执行 audit ⚑
如果需求中包含用户自己的 wireframe 图片，那么这已经算作 wireframe 步骤：进入 
U
分支的 
U4
，根据图片实现 （
S13
–
S15
）。如果需求既想整理代码又想改变外观，先走 
U
，之后再按 
L
整理。需求要求审视或保留 brand 时，以 
V
替代 
U
，
L
仍放在之后。

Câu 2 — Dự án đang dùng gì? (TỰ TÌM, ĐỪNG HỎI)

第 2 问——项目正在使用什么？（自行检查，不要询问）

Audit là CỔNG CHẶN, không phải bước tham khảo. Chưa chạy xong khối lệnh dưới đây thì chưa được mở file layout, chưa được đề xuất bố cục, chưa được viết dòng code nào — kể cả khi đề bài nhỏ như "thêm một cái dropdown".
Skill này bám theo codebase, không áp bộ công cụ của mình lên dự án người ta. Audit ba tầng: stack (dự án dùng gì), component (thứ sắp dựng đã có chưa), và phong cách (dự án đang flat, glass, gradient hay tối).
bash
undefined
**Audit 是阻塞关口，不是参考步骤。**在下面的命令块执行完毕之前，不得打开 layout 文件、 不得提出布局建议、不得编写任何代码——即使需求很小，例如“添加一个 dropdown”。
这个 skill 遵循现有 codebase，不会把自己的工具套件强加到用户的项目上。 Audit 分为三层：stack（项目使用什么）、component（准备构建的内容是否已经存在）， 以及风格（项目采用 flat、glass、gradient 还是深色）。
bash
undefined

Tầng 1 — stack

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
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

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
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:

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...

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

**Tầng 2 là tầng hay bị bỏ.** Dự án có sẵn `Avatar` mà dựng thêm một cái nữa thì
app có hai kiểu avatar, và cái mới dựng lệch với mọi chỗ khác. Đã có thì **dùng
cái của họ**, chỉ chỉnh token nếu nó trái luật.

**Báo kết quả audit một dòng trước khi đi tiếp**, kể cả khi không tìm thấy gì:

> Audit: Next + Tailwind v4, có shadcn, token ở `globals.css`. Đã có `Avatar` ở
> `components/ui/avatar.tsx` — dùng cái đó. Chưa có dropdown — dựng mới.

Dòng này làm cho việc bỏ audit **nhìn thấy được**. Không có dòng này thì người
dùng không biết AI đã kiểm hay đoán.

**Tầng 3 — phong cách.** Đếm **số file** có tín hiệu, không đếm số dòng:

```bash
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)')"
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

**第 2 层最容易被忽略。**如果项目已有 `Avatar`，却再构建一个，
应用中就会出现两种头像样式，而新头像还可能与其他位置不一致。如果已经存在，**就使用项目原有的 component**，
只有在违反规则时才调整 token。

**继续之前，用一行报告 audit 结果**，即使什么都没找到也要报告：

> Audit: Next + Tailwind v4，存在 shadcn，token 位于 `globals.css`。`components/ui/avatar.tsx` 中已有 `Avatar`——直接使用。尚无 dropdown——新建。

这一行能让用户看出是否真的执行了 audit，
而不是被跳过。没有这一行，用户无法知道 AI 是检查过还是凭空猜测。

**第 3 层——风格。**统计带有相应特征的**文件数量**，不要统计代码行数：

```bash
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

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)')"
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)

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
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

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
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

Token phong cách: có là có chủ đích, dùng đế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

Lệnh **cố ý bỏ qua** file dialog, dropdown, toast... vì `M15` cho lớp nổi có
bóng và blur. Không bỏ qua thì dự án flat nào dùng shadcn cũng bị đếm thành "nổi".

Đọc số theo `P4` trong `references/styles.md`. Dự án không có phong cách riêng
thì flat. Có phong cách riêng thì **theo phong cách dự án**, báo lúc giao (`P1`).

Dòng `Audit:` thêm phần phong cách:

> Audit: Next + Tailwind v4, có shadcn. Đã có `Avatar`. **Phong cách: glass ở 7
> file** (card, sidebar, header) — màn này làm glass cho khớp.

Rồi áp theo bảng này:

| Tìm thấy | Làm gì |
| --- | --- |
| **Tailwind** (mặc định của skill) | Dùng utility bình thường. Tailwind v4 thì đọc `references/tailwind-v4-traps.md` trước khi đụng `@theme` |
| **Không có Tailwind** | **Theo quy ước của họ** — CSS Module, styled-components, SCSS, gì cũng được. Skill này chi phối *token, nhịp, bố cục, phạm vi*, không chi phối cách bro viết style. Luật trong skill ghi class Tailwind; **màu thì dịch sang biến trong `references/tokens.css`**, đừng tự chọn mã: `text-rose-700` → `var(--danger)`, badge `bg-emerald-50 text-emerald-700` → `--success-bg` / `--success`. Bảng đối chiếu ở `M7`, `M30`; màu avatar ở `components/avatar.md` |
| **shadcn / Radix / MUI / Ant / bộ nội bộ** | **Dùng component của họ.** Viết lại một cái `Button` trong project đã có shadcn là làm hỏng tính nhất quán, không phải làm đẹp thêm |
| **Thư viện chuyên dụng** (biểu đồ, lịch, bảng, danh sách ảo) | **Có thì dùng đúng nó**, chỉnh cho ra hình của skill (tắt thứ nó bật sẵn, màu lấy token). **Chưa có thì không tự cài**: dựng như bình thường theo mẫu trong `references/components/`, và **chỉ đề xuất khi có nhu cầu tự dựng sẽ tốn** (dữ liệu lớn, phóng to, thời gian thực, nhiều loại biểu đồ). Chọn theo tiêu chí: nhẹ, giải quyết đúng nhu cầu, tô được bằng token, còn bảo trì, hợp hệ sinh thái sẵn có. Đề xuất một dòng kèm lý do; cài hay không là người dùng quyết (`N10`). Bảng cấu hình cho biểu đồ ở `components/charts.md` |
| **Chưa có component nào** | Gợi ý code từ `references/components/`. Nói rõ đây là gợi ý để họ đặt vào đâu thì đặt |
| **Không có `package.json`** | HTML/CSS thuần, hoặc WordPress, PHP, Rails, Django. Mẫu trong `references/components/` viết bằng `.tsx` — **dịch sang thẻ HTML + class rồi mới đưa**, đừng dán JSX vào dự án không có React. `references/tokens.css` thì dán thẳng được, nó là CSS thuần |

**Ngôn ngữ của copy cũng tự tìm ở bước này** — grep i18n và nhãn hiện có, luật
`T24`. Chốt trước khi viết cái nhãn đầu tiên, vì đoán sai thì phải sửa lại toàn
bộ nhãn chứ không phải một dòng. Copy không phải tiếng Việt thì mở `T28`, `T29`.

**Có token sẵn thì dùng, không hỏi.** Chỉ khi grep ra rỗng mới lấy
`references/tokens.css` và dựng luôn, kể cả khi khách có thể đã có bộ nhận diện:
màu nhấn và font chỉ nằm ở một chỗ, lúc giao chỉ ra chỗ đó (`S15`) là họ tự thay.
**Không bao giờ hỏi số lượng font.**

Dùng thư viện của họ thì cách áp skill là **chỉnh token cho khớp**, cộng vài mặc
định trái luật. Với shadcn thường là ba chỗ:

- `Input` mặc định `bg-transparent` → đổi thành nền surface. Ô nhập trong suốt trên nền trang thì người dùng không thấy nó là ô nhập.
- `Button` mặc định có nhiều variant và size → không xoá bớt của thư viện, chỉ **tự giới hạn mình** dùng bốn dạng ở luật `I1`.
- Kiểm bóng: nhiều bộ cho card `shadow-sm` mặc định, mà luật `M15` chỉ cho bóng ở lớp nổi.
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` 允许浮层使用阴影和 blur。
如果不忽略，任何使用旧版 shadcn 的 flat 项目都会被误判为“悬浮”风格。

按照 `references/styles.md` 中的 `P4` 解读数字。如果项目没有自己的风格，则采用 flat。
如果项目有独特风格，则**遵循项目风格**，并在交付时说明（`P1`）。

`Audit:` 行还要加入风格信息：

> Audit: Next + Tailwind v4，存在 shadcn。已有 `Avatar`。**风格：7 个文件使用 glass**（card、sidebar、header）——该页面也采用 glass 以保持一致。

然后按下表执行：

| 发现 | 执行方式 |
| --- | --- |
| **Tailwind**（skill 的默认选项） | 正常使用 utility。遇到 Tailwind v4 时，在修改 `@theme` 前先阅读 `references/tailwind-v4-traps.md` |
| **没有 Tailwind** | **遵循项目自己的约定**——CSS Module、styled-components、SCSS 或其他方式均可。这个 skill 主导的是 *token、节奏、布局、范围*，而不是开发者编写 style 的方式。skill 中的规则虽然写成 Tailwind class，但**颜色应转换为 `references/tokens.css` 中的变量**，不要自行选择色值：`text-rose-700` → `var(--danger)`，badge `bg-emerald-50 text-emerald-700` → `--success-bg` / `--success`。对照表见 `M7`、`M30`；头像颜色见 `components/avatar.md` |
| **shadcn / Radix / MUI / Ant / 内部组件库** | **使用项目现有的 component。**在已有 shadcn 的项目中重新编写一个 `Button`，会破坏一致性，而不是让设计变得更好 |
| **专业库**（图表、日历/日期、表格、虚拟列表） | **已有就正确使用**，再调整成 skill 的外观（关闭默认项，颜色使用 token）。**尚未拥有时不要自行安装**：按照 `references/components/` 中的模板正常实现，且**只有当自行实现成本较高时才提出建议**（数据量大、需要缩放、实时更新、多种图表类型）。选择标准应是：轻量、正确解决需求、可使用 token 着色、易维护，并且兼容已有生态。提出建议时用一行说明并给出理由；是否安装由用户决定（`N10`）。图表配置见 `components/charts.md` |
| **没有任何 component** | 建议使用 `references/components/` 中的代码。明确说明这些代码建议应放在哪里，再放入项目 |
| **没有 `package.json`** | 使用纯 HTML/CSS，或者 WordPress、PHP、Rails、Django。`references/components/` 中的模板使用 `.tsx` 编写——**应先转换成 HTML 标签和 class，再放入项目**，不要把 JSX 直接贴进没有 React 的项目。`references/tokens.css` 是纯 CSS，可以直接使用 |

**文案语言也要在本步骤自行检查**——grep i18n 和现有标签，遵循规则 `T24`。必须在写下第一个标签前确定语言，
因为猜错后需要修改全部标签，而不只是某一行。文案不是越南语时，打开 `T28`、`T29`。

**如果已有 token，就直接使用，不要询问。**只有 grep 结果为空时，才采用
`references/tokens.css` 并直接建立，即使客户已经有品牌识别系统：
强调色和 font 应集中放在一个位置，交付时指出该位置（`S15`），由客户自行替换。
**绝不要询问 font 数量。**

使用项目自己的库时，应用 skill 的方式是**调整 token 以保持一致**，并补充少量默认规则。对于 shadcn，通常是三处：

- `Input` 默认使用 `bg-transparent` → 改为 surface 背景。透明输入框放在页面背景上时，用户无法看出它是输入框。
- `Button` 默认提供多种 variant 和 size → 不要删除库中的 variant，只**限制自己使用** `I1` 规则中的四种形式。
- 检查阴影：很多组件集默认给 card 设置 `shadow-sm`，但 `M15` 只允许浮层使用阴影。

Câu 3 — Muốn UI trông như thế nào?

第 3 问——希望 UI 呈现什么风格？

Phong cách mặc định là flat, theo 
P1
trong 
references/styles.md
:
  • Người dùng tự nêu phong cách ("kiểu glassmorphism", "gradient kiểu landing SaaS") → làm theo, không hỏi lại. Mở 
    references/styles.md
    lấy khối của phong cách đó.
  • Audit tầng 3 thấy dự án có phong cách khác flat → theo phong cách dự án, dựng luôn. Lúc giao báo một dòng: đã theo phong cách gì, thấy ở đâu, muốn flat thì nói. Mẫu ở 
    P1
    .
  • Còn lại → flat, không hỏi về phong cách.
Chọn phong cách nào thì mở khối của nó trong 
references/styles.md
: khối đó nói luật gu flat nào được đè, và bẫy riêng của phong cách đó. Nguyên tắc thì không phong cách nào đè (
P2
).
Có ảnh tham chiếu, có mô tả, có sản phẩm muốn giống → bám theo cái đó, bỏ qua phần còn lại của câu này.
Họ nói "chưa biết", "tuỳ bro", "làm sao đẹp thì làm" → dựng hướng A, báo một dòng lúc giao rằng còn hướng B và C, muốn thì nói. Không hỏi trước.
HướngHình thứcHợp khi
A. Đường tóc phẳng (mặc định của skill)Nền xám nhạt, card trắng, viền 1px rất nhạt, bo ~12px, không bóng. Thứ bậc bằng cỡ chữ và độ đậmHầu hết dashboard. Nhiều khối nhỏ cạnh nhau vẫn đọc ra ranh giới. Đây là hướng mọi luật trong skill viết theo
B. Khối chìmKhông viền. Tách khối bằng chênh lệch nền + khoảng trắng, card trắng nổi trên nền xám. Bo góc lớn hơnMàn ít khối, mỗi khối lớn. Trông thoáng và mềm hơn A. Trả giá: khối nhỏ cạnh nhau thì ranh giới mờ
C. Dày đặc dữ liệuBảng là nhân vật chính. Chữ nhỏ, hàng sát, bo góc nhỏ, đường kẻ rõ, ưu tiên nhìn được nhiều dòng một lúcMàn hình người ta ngồi cả ngày: bảng vận hành, sổ giao dịch, log. Trả giá: nhìn "dày", không hợp màn tổng quan
Chọn B hoặc C thì nói rõ nó đè lên luật nào: B đè 
M13
(tách bằng viền) và 
M15
; C đè phần nhịp trong 
references/budgets.md
. Ghi một dòng lúc giao, để lượt sau không có ai "sửa lại cho đúng luật".
Chọn xong thì trả lời luôn câu này: có cần dark mode không. Mặc định là không — xem 
M20
.
Đề có form: ô nhập mặc định KHÔNG có icon trái. Đừng hỏi, cứ dựng không icon rồi báo một dòng lúc giao: "ô nhập đang để trơn, muốn có icon trái thì nói." Họ muốn thì dựng theo 
references/components/input.md
, lấy icon theo 
F15
.
Cùng cách làm với bộ mặc định của màn xác thực trong 
references/layouts/form.md
: mặc định + một dòng báo, không phải một bảng câu hỏi.
默认风格是 flat，依据 
references/styles.md
中的 
P1
：
  • 用户明确指定风格（“glassmorphism 风格”“类似 SaaS landing page 的 gradient”）→ 直接照做，不要再次询问。打开 
    references/styles.md
    并读取对应风格区块。
  • 第 3 层 audit 发现项目采用 flat 以外的风格 → 遵循项目风格，直接实现。交付时用一行说明：采用了什么风格、在哪里发现、如果希望改成 flat 可以说明。模板见 
    P1
    。
  • 其他情况 → 采用 flat，不询问风格。
选定风格后，打开 
references/styles.md
中对应的区块：该区块会说明哪些 flat 规则被覆盖，以及该风格特有的陷阱。原则不受风格覆盖（
P2
）。
如果提供了参考图片、描述或希望模仿的产品 → 遵循这些内容，跳过本问的其余部分。
如果用户表示“不知道”“随便你”“怎么好看就怎么做” → 采用方向 A，并在交付时用一行说明 仍有方向 B 和 C，如需调整可以提出。不要提前询问。
方向外观适用场景
A. 平直细线（skill 的默认方向）浅灰背景、白色 card、非常浅的 1px 边框、约 12px 圆角、无阴影。通过字号和字重建立层级大多数 dashboard。即使许多小模块并排，仍能清楚分辨边界。这个方向也是 skill 中所有规则的设计基准
B. 沉入式模块无边框。通过背景差异 + 留白区分模块，白色 card 从灰色背景上浮起。圆角更大模块较少、每个模块都较大的页面。看起来更通透、柔和。代价：相邻的小模块之间边界会显得模糊
C. 数据密集型表格是主角。文字较小、行距紧凑、圆角较小、分隔线清晰，优先让用户一次看到更多行用户会长时间盯着的屏幕：运营表格、交易流水、log。代价：视觉上显得“厚重”，不适合概览页
选择 B 或 C 时，要明确说明它覆盖了哪些规则：B 覆盖 
M13
（通过边框区分模块）和 
M15
；C 覆盖 
references/budgets.md
中的部分间距规则。交付时写一行说明，避免后续有人“为了符合规则又把它改回去”。
选定后始终要回答本问：**是否需要 dark mode。**默认不需要——见 
M20
。
**如果需求包含表单：输入框默认不要带左侧 icon。**不要询问，先制作无 icon 版本， 并在交付时用一行说明：*“输入框目前保持无图标，如果希望增加左侧 icon，请告诉我。”*用户需要时， 按照 
references/components/input.md
实现，并依据 
F15
选择 icon。
认证页面的默认实现也采用相同方式， 参考 
references/layouts/form.md
：采用默认值并用一行说明，不要列成一张问题表。

Câu 4 — Bố cục: dựng bố cục mặc định, báo một dòng

第 4 问——布局：实现默认布局，并说明一行

Người dùng đưa ảnh wireframe thì AI dựng ra đồ tử tế. Người dùng chỉ mô tả bằng lời thì AI vẽ tùm lum, kể cả khi đã có đủ bảng màu, cỡ chữ, thang khoảng cách. Lý do: design system nói màu gì cỡ nào cách nhau bao nhiêu, nó không nói cái gì nằm ở đâu. Bố cục mới là thứ quyết định trang đẹp hay xấu, và không luật màu nào bù được cho một bố cục bịa.
Cách chặn: mỗi loại màn hình có đúng một bố cục mặc định, nằm trong file layout. Không bịa, cũng không bày phương án.
  1. Nhận loại màn hình. Nói thẳng ra đây là loại gì: màn hình trong app, form, khối nổi, hay bảng giá. Loại màn hình quyết định luôn file layout phải mở.
  2. Mở file layout, lấy bố cục mặc định. File có ghi điều kiện ("từ 8 trường trở lên thì B") thì theo điều kiện đó, vì nó suy ra từ đề chứ không phải khẩu vị.
  3. Dựng luôn, rồi báo một dòng lúc giao: đã dựng bố cục nào, muốn kiểu khác thì nói.
Mình dựng bảng giá ba card ngang, gói Pro nổi bật. Muốn gộp một khối hay đưa nút lên trên thì nói.
Skill lo cái mặc định đơn giản, chuẩn nhất. Biến thể là việc của người dùng: họ nói thì sửa theo, không hỏi lại.
Câu 4 chỉ chạy ở lối việc nhỏ hơn một màn (câu 1). Mặc định là nhánh 
U
, nơi bố cục mặc định ở đây là một trong các phương án wireframe, thường là phương án khuyên dùng.
⚠️ Luật cũ đã bỏ (21/09/2026), đừng hồi sinh: "đưa 2–3 phương án bố cục bằng lời rồi DỪNG HẲN chờ chọn". Bỏ vì bắt người dùng chọn trước khi thấy gì, và buộc mỗi file layout nuôi nhiều phương án cho mọi loại màn. Nhánh 
U
mặc định từ 29/09/2026 (chủ dự án chốt) không phải luật đó sống lại: người dùng chọn sau khi đã thấy wireframe có nội dung thật, đã probe, bấm mở được; mỗi file layout vẫn chỉ nuôi một bố cục mặc định.
Loại màn hìnhMở
Dashboard, các bước bắt đầu (onboarding checklist), danh sách, bảng, danh sách rỗng, cài đặt, hồ sơ cá nhân, bảo mật (xác thực hai lớp, phiên đăng nhập), khoá API, thành viên và phân quyền, trang lịch (lịch tháng), trang lỗi (404, 403, 500, bảo trì), trang báo cáo (doanh thu, phân tích theo khoảng ngày), đầu trang (đường dẫn + tên + nút), trang chi tiết bản ghi
references/layouts/app.md
Đăng nhập, đăng ký, quên mật khẩu, form nhiều trường, form nhiều bước (thanh các bước), trạng thái lỗi
references/layouts/form.md
Modal, panel trượt, dropdown, command palette, panel thông báo, toast, chuyển động mở đóng của mọi khối nổi (cả select, date picker)
references/layouts/overlay.md
Bảng giá, trang chọn gói
references/layouts/pricing.md
Nhiều hơn một màn trong cùng một đềVào nhánh 
U
như mọi đề dựng; 
references/system.md
— hợp đồng nguyên tố chốt ở 
U4
, trước màn đầu tiên. Bố cục mặc định chỉ dùng thẳng ở lối dựng luôn hoặc việc nhỏ
Có wireframe rồi thì bỏ qua câu 4, đi thẳng xuống mục 1 và bám ảnh theo luật 
S13
, 
S14
, 
S15
.
用户提供 wireframe 图片时，AI 可以精确实现。若用户只用文字描述， AI 就会随意绘制，即使已经有完整的配色、字号和间距表也是如此。 原因在于：design system 只规定颜色、字号和间距，却不会说明什么东西应该放在哪里。 布局才是决定页面美观与否的关键，任何颜色规则都无法弥补凭空编造的布局。
防范方式：每一种屏幕类型都只有一种默认布局，并保存在对应的 layout 文件中。 不要凭空创造，也不要罗列多个方案。
  1. **识别屏幕类型。**明确判断它是 app 内屏幕、表单、浮层还是价格表。屏幕类型直接决定应打开哪个 layout 文件。
  2. **打开 layout 文件并采用默认布局。**如果文件包含条件（例如“从 8 个字段开始采用 B”），则遵循该条件，因为这是根据需求推导出来的，而不是凭个人品味。
  3. 直接实现，并在交付时用一行说明：已实现哪种布局，如需其他样式可以提出。
我实现了一个包含三个横向 card 的价格表，其中 Pro 套餐更加突出。如果想合并为一个模块或把按钮移到上方，请告诉我。
这个 skill 主张简单、标准的默认值。变体由用户决定： 用户提出后再修改，不要再次询问。
第 4 问只在工作量小于一个完整屏幕的路径中执行（第 1 问）。默认 
U
分支中， 这里的默认布局是wireframe 方案之一，通常也是推荐采用的方案。
⚠️ 旧规则已于 21/09/2026 移除，不得恢复：“用文字提出 2–3 个布局方案，然后停下来等待选择”。 移除原因是，它要求用户在看到任何东西之前先做选择，还迫使每个 layout 文件为所有屏幕类型维护多个方案。 自 29/09/2026 起，
U
分支的默认规则不是让旧规则复活：用户是在看到包含真实内容的 wireframe、进行 probe 并能够点击打开之后再做选择；每个 layout 文件仍然只维护一种默认布局。
屏幕类型打开
Dashboard、onboarding checklist、列表、表格、空列表、设置、个人资料、安全设置（双因素认证、登录会话）、API key 锁、成员与权限、日历页（月历）、错误页（404、403、500、维护页）、报表页（收入、按日期区间分析）、页头（路径 + 名称 + 按钮）、记录详情页
references/layouts/app.md
登录、注册、忘记密码、多字段表单、多步骤表单（步骤条）、错误状态
references/layouts/form.md
Modal、侧滑 panel、dropdown、command palette、通知 panel、toast、所有浮层的打开与关闭动效（包括 select、date picker）
references/layouts/overlay.md
价格表、套餐选择页
references/layouts/pricing.md
同一需求中包含多个屏幕像其他设计需求一样进入 
U
分支；使用 
references/system.md
——在第一个屏幕之前，于 
U4
确定设计契约。默认布局只在直接实现或小型修改路径中直接使用
如果已经提供 wireframe，则跳过第 4 问，直接进入第 1 节并依据 
S13
、
S14
、
S15
遵循图片实现。

1. Phạm vi — luật S

1. 范围——S 组规则

Phần này ở lại 
SKILL.md
vì nó cần cho mọi task. Luật về hình thức nằm trong 
references/
, xem mục 2.
S1. Không tự đẻ thêm section. Đề bài có mấy khối thì dựng đúng mấy khối. Skeleton vẽ ba card thì giao ba card, không tự thêm header, bảng so sánh, câu hỏi thường gặp, footer.
S2. Chữ "làm cho hoàn chỉnh" không phải giấy phép thêm nội dung. Nó chỉ có nghĩa là dựng xong phần được giao.
S3. Tiêu đề màn hình không tính là nội dung thêm. Người dùng liệt kê phần tử mà quên tiêu đề thì cứ đặt, vì nó là cấu trúc chứ không phải nội dung. Cùng loại: nhãn ô nhập, chữ trên nút, câu lỗi. Còn lại thì không — không thêm logo, không thêm câu quảng cáo, không thêm ô "ghi nhớ đăng nhập", không thêm nhà cung cấp đăng nhập thứ hai.
⚠️ Màn xác thực có bộ mặc định riêng, xem 
references/layouts/form.md
. Logo sản phẩm, "Quên mật khẩu", một nút Google và placeholder thì dựng luôn; ghi nhớ đăng nhập thì không vì cần backend. Báo một dòng về những lựa chọn đó lúc giao — đừng biến nó thành một bảng câu hỏi.
S4. Không hỏi lại nội dung. Người dùng đã liệt kê rõ màn hình có những gì thì giữ nguyên đúng danh sách đó, và bày ra theo phương án wireframe đã chọn (bố cục mặc định của câu 4 ở việc nhỏ hoặc lối dựng luôn).
Ví dụ: đề ghi "trang đăng nhập có ô email, ô mật khẩu, link quên mật khẩu, nút đăng nhập, nút đăng nhập bằng Google". Nội dung thế là chốt cứng: brief ở 
U1
ghi đúng năm thứ đó, mọi phương án wireframe đều có đủ năm thứ đó (lối dựng luôn thì dựng thẳng một cột giữa màn). Đừng hỏi lại có cần nút Google không.
S5. Đề để hở phạm vi thì dựng phạm vi mặc định, không hỏi.
  • Đề có liệt kê ("trang đăng nhập gồm ô email, ô mật khẩu, nút…"): phạm vi đã chốt, dựng luôn.
  • Đề để hở ("dựng màn hình tổng quan"): lấy bộ khối mặc định của loại màn đó trong file layout (màn tổng quan: bảng khối trong 
    references/layouts/app.md
    ), dựng đủ bộ đó. Đừng để 
    S1
    hoá thành "làm ít nhất có thể" rồi ra một màn mỏng dính 3 khối (đã dính ở vòng test 11).
  • Lúc giao, câu đầu tiên liệt kê các khối đã dựng, và khối nào trong bảng đã bỏ ra. Muốn thêm bớt thì người dùng nói.
S6. Dựng mockup thì điền dữ liệu giả hợp lý, đừng để chỗ trống. Một trang đầy 
[cần điền]
không nhìn ra được thiết kế, nó thành cái biểu mẫu. Điền số nghe được, rồi báo một dòng lúc giao: số liệu trong bản này là giả. Các khối của cùng một bản ghi phải khớp nhau: tab Hoạt động có một đơn đã huỷ thì ô số liệu không ghi 3 đơn, 12,3 tr đ (đã dính 24/09/2026). Số giả lệch nhau giữa hai tab làm người duyệt tưởng giao diện tính sai. Sửa dữ liệu giả cho khớp (lùi ngày tạo, thêm đơn vào lịch sử) là việc của bản dựng, tự làm, không hỏi: nó không đụng logic hay dữ liệu thật.
S7. Chỉ để 
[cần điền]
 khi bản dựng đi thẳng ra người dùng thật, và chỉ cho thứ có hậu quả pháp lý hoặc tài chính: giá bán, mức hoàn tiền, cam kết uptime, điều khoản.
S8. Dữ liệu giả phải phủ ca biên, không phải dữ liệu đẹp. Tên tràn hai dòng, số chín chữ số, số 
0
, thiếu ảnh, thiếu mô tả, danh sách rỗng. Dữ liệu đẹp làm giao diện trông ổn cho tới lúc gặp khách thật.
S9. Dùng thư viện component sẵn có của dự án. Xem câu 2 ở mục 0. Người dùng nói rõ dùng thư viện nào thì theo họ, đừng cãi.
S10. Gặp từ mơ hồ trong đề thì lấy nghĩa mặc định, và NÓI RA lúc giao.
TừNghĩa mặc địnhNghĩa kia, chỉ khi đề nói rõ
bảngtable dữ liệuboard kiểu kanban ("kéo thả", "cột trạng thái", "board")
thẻcardtab
danh sáchlist dọcdropdown
khungvùng bố cụcmodal ("bật lên", "popup")
trangmột routemột tờ trong nhiều bước ("bước 2")
lịchlịch thángdòng thời gian ("timeline")
Câu đầu tiên lúc giao nói thẳng cách hiểu: "Mình hiểu bảng là table dữ liệu. Nếu ý bạn là board kanban thì nói, mình đổi." Hiểu sai thì người dùng thấy ngay ở câu đầu, không phải tới lúc test mới lộ. Bài học gốc: "bảng quản lý dự án" từng bị hiểu thành kanban mà không ai nói ra, cả vòng test coi như bỏ (vòng 18). Lỗi lúc đó là im lặng chọn nghĩa hiếm, không phải chuyện không hỏi.
S11. Code mẫu trong 
layouts/
chỉ mở SAU khi đã chốt loại màn hình. Nó trả lời câu "dựng thế nào", không trả lời câu "đề bài muốn gì". Có sẵn một file kanban mẫu thì rất dễ đọc mọi thứ mơ hồ thành kanban.
S12. Người dùng đưa ảnh thì tự nhận ảnh đó là gì, không hỏi.
  • Mặc định là design ref: bám bố cục, bảng màu, kiểu dáng.
  • Là wireframe khi đề gọi nó là wireframe / phác thảo / khung, hoặc ảnh chỉ có đen trắng xám, khối chữ nhật, chữ giả: chỉ lấy bố cục, màu và kiểu dáng theo skill.
  • Là ảnh hiện trạng khi đó là ảnh app của chính người dùng mà họ nhờ xem: đề có "xem giúp", "review", "chỗ nào chưa ổn", "sao trông kỳ", "nhìn rối". Ảnh này là thứ để soi lỗi, không phải mẫu để bám. Đi nhánh 
    V
    (
    references/review.md
    ). Ảnh khớp một route trong repo mà đề không có từ soi, chỉ bảo dựng hay làm lại, thì đó là ảnh "trước" của nhánh 
    U
    : đọc ở 
    U1
    , đặt cạnh ảnh sau lúc giao, không xếp 
    V
    . ⚑
  • Lúc giao nói một dòng: "Mình dùng ảnh làm design ref (bám cả màu)", "…làm wireframe (chỉ lấy bố cục)", hoặc "…là ảnh hiện trạng app của bạn (soi lỗi)".
S13. Bố cục gồm cả vị trí, không chỉ danh sách phần tử. Badge nằm giữa mép trên card thì để giữa. Ô icon đứng cạnh giá thì giữ đúng chỗ. Thứ tự các khối giữ nguyên. Thay màu và kiểu dáng thì được, xê dịch vị trí thì không.
S14. Icon trong wireframe cứ giữ, kể cả icon trang trí. Xem luật 
F17
về việc mỗi mục được phép một icon khác nhau.
S15. Lúc giao phải nói bốn thứ: các mặc định đã chọn thay người dùng (cách hiểu từ mơ hồ 
S10
, bộ khối 
S5
, loại ảnh 
S12
, phong cách 
P1
, bố cục câu 4; mỗi thứ một dòng, kèm "muốn khác thì nói"), chỗ đổi thương hiệu (dòng nào chứa màu nhấn, dòng nào chứa font), số liệu nào là giả, và có làm dark mode hay không. Mặc định đặt lên đầu, vì đó là chỗ duy nhất có thể đã đoán sai. Nói bằng tiếng người dùng đang viết, kể cả khi skill và nhãn trên UI là tiếng Việt (
T27
).
S16. Dữ liệu giả có ảnh thì dùng ảnh chụp thật, không khối xám hay hình vẽ ⚑. Mục mà sản phẩm thật sẽ có ảnh (phòng, sản phẩm, bài viết, ảnh bìa công ty, avatar người) thì mockup và wireframe dùng ảnh thật, trang mới trông như sản phẩm đang chạy:
  • Ảnh cảnh, vật: Unsplash, dạng 
    https://images.unsplash.com/photo-<id>?w=800&q=80&auto=format&fit=crop
    , đúng chủ đề của mục (phòng trọ là nội thất phòng, tin tuyển dụng là văn phòng). Không tự bịa 
    <id>
    : tìm trên Unsplash, rồi 
    curl -sI
    từng link, không ra 200 thì thay. Mỗi mục một ảnh khác nhau.
  • Avatar người: ảnh chân dung (
    https://randomuser.me/api/portraits/women/<0-99>.jpg
    , 
    .../men/<0-99>.jpg
    ), khớp giới của tên giả. Ảnh vẫn theo khuôn của 
    components/avatar.md
    .
  • Logo công ty giả: ô chữ cái theo 
    components/avatar.md
    (hình vuông bo góc), không lấy logo thương hiệu thật gắn cho công ty giả.
  • Vẫn giữ ca biên của 
    S8
    : ít nhất một mục không ảnh, một người không avatar, để thấy chỗ rơi về chữ cái hay khung "Chưa có ảnh".
  • Next.js thì thêm hai host vào 
    images.remotePatterns
    trong 
    next.config
    ; dự án có ảnh riêng (thư mục 
    public/
    , CDN của họ) thì dùng ảnh của họ trước.
  • Lúc giao, dòng "số liệu giả" của 
    S15
    nói luôn: ảnh từ Unsplash và randomuser là ảnh mẫu, thay bằng ảnh thật trước khi chạy thật.
Đã dính 29/09/2026: trang phòng trọ dùng tám hình vẽ giường gần giống nhau, chủ dự án thấy "nhìn chán" dù bố cục đã đúng.
这一部分保留在 
SKILL.md
中，因为每项任务都需要它。关于具体形式的规则位于 
references/
，见第 2 节。
**S1. 不要自行添加额外 section。**需求中列出多少个模块，就实现多少个模块。 Skeleton 画了三个 card，就交付三个 card，不要自行添加 header、对比表、常见问题、footer。
**S2. “做得完整”不是添加内容的许可。**它只表示完整实现被分配的部分。
**S3. 屏幕标题不算额外内容。**用户列出页面元素却忘记标题时，可以直接添加，因为标题属于结构，不是内容。 同类情况还包括：输入框标签、按钮文字、错误提示。除此之外则不可以——不要添加 logo、广告文案、 “记住登录”选项或第二个登录提供商。
⚠️ 认证页面有独立默认值，参见 
references/layouts/form.md
。 产品 logo、“忘记密码”、一个 Google 按钮和 placeholder 应直接实现；“记住登录”则不实现，因为需要 backend。 交付时用一行说明这些选择——不要将其变成一张问题表。
**S4. 不要再次询问内容。**用户已经明确列出的页面元素应完整保留， 并按照已选 wireframe 方案呈现（小型修改或直接实现路径中，采用第 4 问的默认布局）。
例如，需求写明“登录页包含邮箱输入框、密码输入框、忘记密码链接、登录按钮和 Google 登录按钮”。这些内容就是硬性约束： brief 在 
U1
中准确记录这五项，所有 wireframe 方案都必须包含这五项（直接实现路径则直接构建居中的单列页面）。 不要再询问是否需要 Google 按钮。
S5. 需求未明确范围时，实现默认范围，不要询问。
  • 需求有明确列表（“登录页包含邮箱输入框、密码输入框、按钮……”）：范围已经确定，直接实现。
  • 需求未明确范围（“构建一个概览页”）：采用该屏幕类型在 layout 文件中的默认模块集合（概览页：采用 
    references/layouts/app.md
    中的模块表），并完整实现整套模块。不要让 
    S1
    被误解为“能少做就少做”，最后只交付一个包含三个模块的单薄页面（测试第 11 轮已经出现这种问题）。
  • 交付时，第一句列出已实现的模块，以及从表格中省略了哪些模块。用户需要增减时自行提出。
S6. 制作 mockup 时，填入合理的虚假数据，不要留空。一个布满 
[需要填写]
的页面无法体现设计效果，只会变成一张表单。填入听起来合理的数据，并在交付时用一行说明： 本版本中的数字均为虚假数据。同一记录在不同模块中的数据必须一致：如果“活动”tab 中有一个已取消订单，指标卡不能显示 3 个订单、12.3 万 VND（该问题已于 24/09/2026 出现）。 不同 tab 中虚假数据不一致，会让审批者误以为界面计算错误。调整虚假数据使其保持一致（推迟创建日期、向历史记录中添加订单） 属于所构建版本的一部分，应自行完成，不要询问：这不会触及真实逻辑或数据。
S7. 只有当版本会直接交付给真实用户，并且只涉及具有法律或财务后果的内容时，才使用 
[需要填写]
： 售价、退款额度、uptime 承诺、服务条款。
**S8. 虚假数据必须覆盖边界情况，而不是只放美观数据。**超长两行姓名、九位数数字、数字 
0
、 缺少图片、缺少描述、空列表。美观数据只能让界面在遇到真实客户之前看起来正常。
**S9. 使用项目已有的 component 库。**参见第 0 节的第 2 问。用户明确指定某个库时，遵循用户选择，不要争辩。
S10. 需求中出现含糊词语时，采用默认含义，并在交付时明确说明。
词语默认含义另一种含义，仅在需求明确提出时使用
表格数据 tablekanban 风格的 board（“拖放”“状态列”“board”）
卡cardtab
列表纵向 listdropdown
框架布局区域modal（“弹出”“popup”）
页面一个 route多步骤流程中的一页（“第 2 步”）
日历月历时间线（“timeline”）
交付时第一句应直接说明理解：“我理解这里的‘表格’指数据 table。如果你想表达的是 kanban board，请告诉我，我会更改。” 理解错误时，用户会在第一句就看到，而不是等到测试阶段才暴露。原始教训：“项目管理表格”曾被理解为 kanban， 而无人说明，导致整个测试轮次作废（第 18 轮）。错误在于默默选择了罕见含义，而不是“不询问”本身。
**S11. 
layouts/
中的模板代码只有在确定屏幕类型后才能打开。**它回答的是“如何实现”， 而不是“需求想要什么”。如果项目中已有 kanban 模板，很容易把所有模糊需求都理解成 kanban。
S12. 用户提供图片时，自行判断图片类型，不要询问。
  • 默认是 design ref：遵循其布局、配色和风格。
  • 当需求称其为 wireframe / 草图 / 框架，或者图片只有黑白灰、矩形块和占位文字时，属于 wireframe：只采用布局，颜色和风格仍遵循 skill。
  • 当图片是用户自己的 app，并要求“帮我看看”“review”“哪里不好”“看起来很奇怪”“看起来很乱”时，属于现状截图： 这是用于审查问题的素材，不是需要照着实现的模板。进入 
    V
    分支（
    references/review.md
    ）。如果图片与仓库中的某个 route 对应，但需求没有审查要求，只要求设计或重做，则它属于 
    U
    分支的“之前”图片：在 
    U1
    读取，交付时将其与“之后”图片并排展示，不进入 
    V
    。⚑
  • 交付时用一行说明：“我会将图片作为 design ref（沿用配色）”、“……作为 wireframe（只采用布局）”，或*“……作为你当前 app 的现状截图（用于审查问题）”*。
**S13. 布局还包括位置，而不只是元素列表。**如果 badge 位于 card 上边缘中央，就保持在中央。 如果价格旁的 icon 框在右侧，就保持原位。各模块的顺序保持不变。可以更改颜色和风格，但不能移动位置。
**S14. Wireframe 中的 icon 应保留，即使是装饰性 icon。**关于每个条目可以使用不同 icon 的规则，参见 
F17
。
S15. 交付时必须说明四件事：代用户选择的默认值 （对含糊词语的理解 
S10
、模块集合 
S5
、图片类型 
S12
、风格 
P1
、第 4 问的布局；每项各占一行，并附上“如需不同请告诉我”）、 需要替换品牌信息的位置（哪一行包含强调色、哪一行包含 font）、哪些数字是虚假数据，以及是否实现了 dark mode。 默认将这部分放在最前面，因为这里最容易出现错误猜测。 使用用户当前使用的语言回复，即使 skill 和界面标签使用越南语（
T27
）。
S16. 虚假数据需要图片时，应使用真实照片，而不是灰色占位块或插画 ⚑。如果真实产品会有图片（房间、商品、文章、公司封面、用户头像）， 则 mockup 和 wireframe 应使用真实照片，让新页面看起来像已经运行中的产品：
  • 场景和物品：使用 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
    中增加两个 host；如果项目已有自己的图片（
    public/
    目录、CDN），优先使用项目图片。
  • 交付时，
    S15
    中的“虚假数据”一行还需说明：Unsplash 和 randomuser 图片均为样例图片，正式运行前应替换为真实图片。
29/09/2026 已出现相关问题：租房页面使用了八张几乎相同的插画床铺图，导致项目负责人觉得“很无聊”，尽管布局本身没有问题。

2. Mở doc nào khi nào

2. 何时打开哪个文档

SKILL.md
chỉ giữ phần luôn luôn cần. Mở đúng file cần rồi làm, đừng nạp hết.
Nguyên tắc một nguồn: mỗi luật sống ở đúng một file. 
SKILL.md
chỉ được trỏ số hiệu, không được chép lại nội dung luật. Thấy hai chỗ cùng nói một luật thì một trong hai chỗ là sai.
NhómFileDùng cho
S
SKILL.md
mục 1		Phạm vi: được làm gì, không được tự thêm gì
N
references/principles.md
Mười hai nguyên tắc đứng sau mọi luật khác, mỗi cái một phép thử. Chỗ nào không có spec thì bám nó
M
references/rules-color.md
Màu, viền, bóng, dark mode, token
T
references/rules-type.md
Chữ, font, xuống dòng, cắt chữ, copy, ngôn ngữ trả lời và copy tiếng Anh
F
references/rules-form.md
Khối, lưới, bo góc, khoảng thở, icon, hiệu ứng
I
references/rules-state.md
Nút, hover, focus, danh sách, modal
R
references/responsive.md
Mọi luật về màn hẹp, ngưỡng kiểm 375px
D
references/system.md
Đề nhiều hơn một màn: hợp đồng nguyên tố; dựng design system trước (
D9
)
V
references/review.md
Soi UI đang có: ba hạng lỗi, quét bề rộng, dark mode của dự án, bảng trước/sau
L
references/refactor.md
Refactor codebase đã có
U
references/design-process.md
Thiết kế từ đầu: brief, việc chính của từng màn, wireframe phương án, dựng
W
references/tailwind-v4-traps.md
Bẫy Tailwind v4 khi có CSS cũ
P
references/styles.md
Phong cách thị giác: flat, nổi, glass, gradient, tối. Luật nào được đè, bẫy riêng, tương phản
Luôn mở, mọi task:
CầnMở
Nguyên tắc chung, phép thử cho UI chưa có mẫu
references/principles.md
Ngân sách, nhịp, thang cỡ chữ
references/budgets.md
Bảng màu, font, cách đổi thương hiệu
references/brand-tokens.md
+ 
references/tokens.css
Kiểm trước khi báo xong
references/checklist.md
Luật chủ dự án đã chốt và lý lẽ đã bị bác: mở trước khi chọn màu, mức nặng của nút (đỏ hay trung tính, 
primary
hay viền)
references/locked-rules.md
Mở khi dựng đúng khối đó:
Cần dựngMở
Card, widget, panel
references/components/card.md
Khối nhãn và giá trị của trang chi tiết
references/components/description-list.md
Nút
references/components/button.md
Ô nhập, form field
references/components/input.md
Ô nhập mã OTP
references/components/otp-input.md
Ô nhập số lượng có nút − +
references/components/quantity-input.md
Tên sửa tại chỗ ở đầu trang (tên dự án, tài liệu)
references/components/inline-edit.md
Đường dẫn (breadcrumb) trên thanh header hoặc trên tên trang
references/components/breadcrumb.md
Tiêu đề cột bảng bấm để sắp xếp
references/components/sortable-header.md
Checkbox, radio, công tắc, select, ô chọn giờ, ô chọn ngày, khoảng ngày, ngày giờ, lựa chọn dạng card
references/components/choice-controls.md
Dòng trong danh sách
references/components/list-row.md
Dòng thời gian, lịch sử hoạt động
references/components/timeline.md
Cây thư mục, cây lồng nhau mở đóng được
references/components/tree.md
Accordion, FAQ, mục mở/đóng tại chỗ
references/components/accordion.md
Khu bình luận, trả lời lồng nhau
references/components/comment-thread.md
Khung chat với trợ lý AI: tin nhắn hai phía, bước dùng công cụ, gợi ý hỏi tiếp, ô soạn tin
references/components/chat.md
Thanh trượt chọn khoảng số, khoảng giá
references/components/range-slider.md
Ô nhập nhiều tag (email người nhận, nhãn)
references/components/tag-input.md
Danh sách rỗng, đang tải (chữ hoặc khung chờ), lỗi tải
references/components/empty-state.md
Thanh thông báo trong trang (thông tin, cần chú ý, lỗi)
references/components/banner.md
Chip lọc, chip lọc đang áp dụng (có ×), nút chỉ có icon, thanh tab (4 variant), phân trang
references/components/small-controls.md
Avatar, nhóm avatar chồng nhau
references/components/avatar.md
Biểu đồ cột, biểu đồ đường, số liệu, thanh tiến độ
references/components/charts.md
Khung kéo thả tệp, danh sách tệp đang tải lên
references/components/file-upload.md
Dựng một trang là RÁP, không phải vẽ lại. Trên trang có phần tử nào nằm trong bảng trên thì mở đúng file đó và chép công thức, kể cả khi nó chỉ là một nút nhỏ ở góc. Không tự nặn biến thể "cho hợp trang này": cùng một badge mà bảng một kiểu, drawer một kiểu là hai app ghép lại (
D1
, 
D2
). Trang cần một phần tử chưa có file thì theo luồng "Dựng một thứ chưa có mẫu" ở cuối 
references/principles.md
: mượn khuôn gần nhất, dựng cả ca biên, probe tự sửa, soi năm câu bằng mắt, lúc giao nói một dòng "X chưa có mẫu đã duyệt, mình mượn khuôn của Y".
Code mẫu đã duyệt (chỉ mở sau khi chốt loại màn hình, luật 
S11
): 
references/layouts/app-kanban.html
SKILL.md
只保留始终需要的内容。只打开真正需要的文件并执行，不要一次性加载全部内容。
单一来源原则：每条规则只存在于一个文件中。
SKILL.md
只能引用规则编号，不能复制规则内容。 如果两个位置都描述了同一条规则，那么其中一个位置就是错误的。
分组文件用途
S
SKILL.md
第 1 节		范围：可以做什么、不能自行添加什么
N
references/principles.md
支撑所有其他规则的十二项原则，每项都是一种检验方法。没有规范可依时遵循它
M
references/rules-color.md
颜色、边框、阴影、dark mode、token
T
references/rules-type.md
字体、font、换行、文字截断、文案、回复语言和英文文案
F
references/rules-form.md
模块、网格、圆角、间距、icon、效果
I
references/rules-state.md
按钮、hover、focus、列表、modal
R
references/responsive.md
所有窄屏规则和 375px 检查阈值
D
references/system.md
需求包含多个屏幕时的设计契约；先建立 design system（
D9
）
V
references/review.md
审查现有 UI：三类问题、横向扫描、项目 dark mode、变更前后对照表
L
references/refactor.md
Refactor 已有 codebase
U
references/design-process.md
从头设计：brief、每个画面的主要任务、方案 wireframe、实现
W
references/tailwind-v4-traps.md
存在旧 CSS 时的 Tailwind v4 陷阱
P
references/styles.md
视觉风格：flat、悬浮、glass、gradient、深色。哪些规则被覆盖、专属陷阱、对比度
所有任务始终打开：
需要打开
通用原则，以及没有模板的 UI 检验方法
references/principles.md
空间预算、节奏、字号阶梯
references/budgets.md
配色、font、品牌替换方式
references/brand-tokens.md
+ 
references/tokens.css
宣布完成前进行检查
references/checklist.md
项目已敲定的规则及其被否决的理由：选择颜色、确定按钮权重（红色还是中性色、
primary
还是边框）前打开
references/locked-rules.md
构建特定模块时打开：
需要构建打开
Card、widget、panel
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
Header 或页面名称上方的路径（breadcrumb）
references/components/breadcrumb.md
可点击排序的表头
references/components/sortable-header.md
Checkbox、radio、switch、select、时间选择器、日期选择器、日期区间、日期时间、card 形式的选项
references/components/choice-controls.md
列表中的行
references/components/list-row.md
时间线、活动历史
references/components/timeline.md
目录树、可展开嵌套树
references/components/tree.md
Accordion、FAQ、就地展开/收起内容
references/components/accordion.md
评论区、嵌套回复
references/components/comment-thread.md
带 AI 辅助的聊天框：双向消息、工具调用步骤、建议问题、输入框
references/components/chat.md
数值区间、价格区间滑块
references/components/range-slider.md
多 tag 输入框（收件人邮箱、标签）
references/components/tag-input.md
空列表、加载中（文字或骨架屏）、加载错误
references/components/empty-state.md
页面内通知条（信息、需要注意、错误）
references/components/banner.md
筛选 chip、已应用筛选 chip（带 ×）、纯 icon 按钮、tab 栏（4 种 variant）、分页
references/components/small-controls.md
头像、堆叠头像组
references/components/avatar.md
柱状图、折线图、统计数据、进度条
references/components/charts.md
文件拖放框、正在上传的文件列表
references/components/file-upload.md
**构建页面很快，不是重新画一遍。页面中只要包含上表中的元素，就应打开对应文件并复制其公式， 即使它只是角落里的一个小按钮。不要自行“捏造”一个适合当前页面的变体： 同一种 badge 在一个页面是一种样式，在 drawer 中又是另一种样式，就等于把两个 app 拼在一起（
D1
、
D2
）。 如果页面需要某个尚无模板的元素，遵循 
references/principles.md
末尾的“构建没有现成模板的东西”**流程： 借用最接近的模板、覆盖边界情况、执行 probe、自行检查、用肉眼审查五个问题，并在交付时用一行说明： “X 尚无已批准的模板，我借用了 Y 的模板。”
已批准的模板代码（只有在确定屏幕类型后才能打开，规则 
S11
）： 
references/layouts/app-kanban.html

3. Sáu thứ không được quên

3. 六个不可遗忘的事项

Rút gọn từ 
references/checklist.md
. Chạy hết checklist đầy đủ trước khi báo xong.
  • Câu 1 của mục 0 đã trả lời chưa — như một designer (mặc định), soi UI, dựng lại giữ brand, dựng lại theo gu skill, refactor, dựng luôn hay dựng design system trước. Đề không nói rõ lối khác mà đã dựng thẳng, bỏ qua brief và wireframe, là sai câu 1.
  • Đã grep codebase xem họ dùng Tailwind / shadcn / gì chưa, hay đang tự áp bộ của mình lên.
  • Đã dựng đúng phương án wireframe đã chọn chưa (nhánh 
    U
    ), hay tự bịa. Việc nhỏ hoặc lối dựng luôn thì đúng bố cục mặc định trong file layout, lúc giao báo một dòng "muốn kiểu khác thì nói".
  • Có section nào tự thêm ngoài đề bài không.
  • Đã mở trang thật bằng 
    scripts/probe.mjs
    và xem ảnh chụp chưa     (cổng 3), hay trả lời checklist bằng đọc lại code. Trang cuộn ngang ở 375px là hỏng.
  • Đã chạy mười hai phép thử trong 
    references/principles.md
    chưa, nhất là với thứ chưa có mẫu.
内容摘自 
references/checklist.md
。宣布完成前必须执行完整 checklist。
  • 第 0 节第 1 问是否已经回答——像 designer 一样工作（默认）、审查 UI、保留 brand 重做、按 skill 审美重做、refactor、直接实现，还是先建立 design system。如果需求没有明确要求其他路径，却直接实现、跳过 brief 和 wireframe，就是第 1 问出错。
  • 是否已经 grep codebase，确认项目使用 Tailwind / shadcn / 其他方案，而不是把自己的方案强加上去。
  • 是否实现了已选定的 wireframe 方案（
    U
    分支），而不是自行编造。对于小型修改或直接实现路径，应使用 layout 文件中的默认布局，并在交付时用一行说明“如需其他样式请告诉我”。
  • 是否添加了需求之外的 section。
  • 是否已经用 
    scripts/probe.mjs
    打开真实页面并查看截图（关口 3），而不是只重读代码就回答 checklist。页面在 375px 下出现横向滚动就是故障。
  • 是否已经执行 
    references/principles.md
    中的十二项检验，尤其是针对尚无模板的内容。

4. Thêm luật mới thì theo quy tắc này

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

Skill này đã có lần tệ đi vì thêm luật. Luật viết để chữa một triệu chứng thường đẻ ra triệu chứng khác ở lần dựng sau.
  • Mỗi đợt tối đa 5 luật mới.
  • Mỗi luật mới phải nói rõ nó thay thế hay mâu thuẫn với luật nào đang có. Đảo một luật cũ thì để lại một khối ⚠️ ghi rõ "luật cũ đã bỏ, đừng hồi sinh", kèm ngày.
  • Luật phải kèm điều kiện áp dụng. "Trong app thì X, khi refactor thì Y" chứ không phải "luôn luôn X".
  • Luật nào chưa từng bắt được lỗi thật sau 3 vòng test thì bỏ.
  • Một luật một chỗ. Thêm luật vào đúng file của nhóm nó. 
    SKILL.md
    chỉ được trỏ số hiệu.
  • Thêm luật xong thì rà lại file mẫu trong 
    layouts/
    và 
    components/
     xem chúng có vi phạm luật vừa thêm không. Code mẫu được chép nguyên, nên một lỗi nằm trong đó sẽ đi khắp nơi. Đã xảy ra thật hai lần.
  • Đánh số liền mạch trong nhóm. Đừng đẻ 
    15b
    , 
    15c
    , 
    17d
    chen vào giữa.
  • Luật chưa qua vòng test nào thì gắn dấu ⚑, để người dùng biết đang dùng thứ chưa ai thử.
这个 skill 曾经因为添加规则而变差。新规则用于修复一个常见症状，却可能在后续构建中引发另一个常见症状。
  • 每轮最多添加 5 条新规则。
  • 每条新规则必须明确说明它替代或冲突于哪些现有规则。如果要推翻旧规则，应保留一个 ⚠️ 区块，写明“旧规则已移除，不得恢复”，并附上日期。
  • 规则必须附带适用条件。例如“在 app 中使用 X，在 refactor 时使用 Y”，而不是“永远使用 X”。
  • 如果某条规则在 3 轮测试中都未真正捕获过问题，就应移除。
  • **一条规则只放在一个位置。**将新规则加入其所属分组的正确文件。
    SKILL.md
    只能引用编号。
  • 添加规则后，重新检查 
    layouts/
    和 
    components/
    中的模板文件，看它们是否违反新规则。模板代码会被原样复制，因此其中的一个错误会扩散到所有使用位置。这已经发生过两次。
  • **在同一分组内连续编号。**不要插入 
    15b
    、
    15c
    、
    17d
    之类的编号。
  • 尚未经过任何测试轮次的规则应标记 ⚑，让用户知道它尚未被实际验证。