Impeccable: bộ lệnh thiết kế giúp AI viết giao diện đẹp — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về pbakaus/impeccable — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: impeccable: bắt lỗi thiết kế do AI và chỉnh giao diện bằng lệnh — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Impeccable là một skill thiết kế cho coding agent (Claude Code, Cursor, Codex CLI…). Nó cho bạn các lệnh như polish, bolder, critique, audit để chỉ đạo và kiểm tra giao diện do AI tạo ra. Cài bằng một lệnh npx ở thư mục dự án nên khá dễ, nhưng bạn cần đã có sẵn một công cụ coding agent.
Impeccable là một bộ "từ vựng thiết kế" cài vào coding agent của bạn (Claude Code, Cursor, Codex CLI và nhiều công cụ khác). Có nó, bạn không cần nói mơ hồ kiểu "làm cho đẹp lên" nữa. Bạn gọi đúng tên động tác, ví dụ polish, bolder, quieter, rồi để agent làm theo một quy trình viết sẵn cho đúng động tác đó. Repo hiện có khoảng 109.000 sao và khoảng 6.500 fork, giấy phép Apache-2.0.
Vấn đề nó giải quyết rất quen. Nhờ AI dựng một trang web mà không dặn gì thêm, bạn hay nhận về cùng một kiểu: chữ Inter cho mọi thứ, nền gradient tím sang xanh, thẻ lồng trong thẻ, chữ xám trên nền màu, ô icon bo tròn đặt trên mỗi tiêu đề. README gọi đó là "AI slop", tức giao diện làm ẩu theo công thức chung. Impeccable vừa giúp bạn chỉ đạo AI cụ thể hơn, vừa có bộ kiểm tra để bắt những lỗi này trước khi bạn đưa sản phẩm ra.
Người nên dùng là chủ shop hoặc nhân viên văn phòng đang nhờ AI dựng trang giới thiệu, và lập trình viên mới muốn giao diện bớt "đồ AI". Điểm đáng giá nhất theo mình là bộ dò lỗi: 62 quy tắc cố định, chạy không cần LLM và không cần API key, nên dùng được cả trong terminal lẫn CI.
pbakaus/impeccable
Impeccable cho coding agent bộ lệnh thiết kế như bolder, polish, critique, audit và bộ dò 62 quy tắc để bắt giao diện kiểu AI làm ẩu.
I.Impeccable làm được gì
A.Lệnh để chỉ đạo thiết kế
README liệt kê 24 lệnh, chia theo nhóm việc. Bạn không cần nhớ hết, chỉ cần biết mỗi nhóm để làm gì:
- Steer (điều hướng):
bolderlàm đậm một thiết kế quá an toàn,quieterlàm dịu thiết kế quá ồn,distillbỏ những gì trang không cần,colorizethêm màu cho giao diện xám xịt,typesetchỉnh phông chữ và thứ bậc chữ,layoutchỉnh khoảng cách và nhịp trình bày,animatethêm chuyển động,delightthêm cá tính,overdriveđẩy tới hiệu ứng nặng như shader hay cuộn có hiệu ứng. - Review (đánh giá):
critiquechấm điểm trải nghiệm người dùng và xếp thứ tự việc cần sửa.auditkiểm tra kỹ thuật: khả năng truy cập, hiệu năng, theme, hiển thị đa kích thước màn hình, với mức từ P0 (chặn) đến P3 (chỉnh cho đẹp). - Finish (hoàn thiện):
polishlà lượt chỉnh cuối trước khi đưa ra,hardenlo lỗi, đa ngôn ngữ, tràn chữ và các trường hợp biên,clarifyviết lại câu chữ khó hiểu,adaptlo màn hình và thiết bị,optimizelo tốc độ tải,onboardthiết kế luồng lần đầu dùng và màn hình trống. - Iterate live:
livecho bạn chọn một phần tử ngay trên trình duyệt rồi xem nhiều phương án.generatetạo các phương án cho một phần tử mà không cần bạn bấm chọn. - Plan and set up:
shapelên kế hoạch UX trước khi viết code,inittạoPRODUCT.md,documenttạoDESIGN.md,extractgom các mẫu lặp lại vào hệ thống thiết kế.
Lệnh thứ 24 là craft, README ghi là bí danh đã bị loại bỏ, tương đương một yêu cầu "hãy xây" bình thường.
B.Bộ dò lỗi thiết kế
Có 62 quy tắc cố định để phát hiện các dấu hiệu AI làm ẩu, cộng với lỗi chất lượng như đệm quá sát hay nhảy cấp tiêu đề. Bộ này không dùng LLM và không cần API key, nên kết quả lặp lại được và chạy rẻ.
C.Bốn cách chạy bộ dò
Bạn có thể chạy ngay trong agent (qua hook tự quét mỗi file giao diện mà agent sửa), chạy bằng lệnh CLI trong terminal hoặc CI, hoặc dùng tiện ích mở rộng Chrome để xem lỗi chồng lên bất kỳ trang nào đang mở.
D.File ngữ cảnh để giữ đúng thương hiệu
init viết file PRODUCT.md (sản phẩm cho ai, cần làm gì, ràng buộc gì). document viết DESIGN.md ghi lại hệ thống hình ảnh hiện có. Các lệnh sau đều đọc hai file này nên kết quả bám đúng sản phẩm của bạn.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Một coding agent đã dùng được. README liệt kê các công cụ hỗ trợ: Claude Code, Cursor, Codex CLI, GitHub Copilot, Devin, Replit Agent, Gemini CLI, Grok Build, OpenCode, Google Antigravity, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Pi, Hermes Agent, DeepSeek Harness và Veto.
- Node từ phiên bản 18.19.0 trở lên, vì
package.jsonyêu cầu như vậy. README nói Node chỉ cần cho lệnhnpx. Bản thân skill chạy bằng một engine đóng gói sẵn đi kèm, hoặc tải một lần về thư mục~/.impeccable/bin/. - Một dự án có sẵn để thử. README nói công cụ mạnh nhất với giao diện đã tồn tại: chỉ vào một trang hoặc một thành phần rồi chỉnh dần.
- Muốn quét một trang đã hiển thị bằng CLI thì cần Chrome hoặc Edge đã cài trên máy.
Tư liệu không nêu yêu cầu GPU, dung lượng ổ đĩa hay hệ điều hành cụ thể cho cả bộ công cụ. Riêng tiện ích cho VS Code cần VS Code 1.109.3 trở lên, Copilot Chat và một workspace đã tin cậy.
III.Cài đặt từng bước
- Mở terminal đúng chỗVào thư mục gốc của dự án bạn đang làm
- Chạy trình càiGõ npx impeccable install và chọn công cụ, phạm vi cài
- Chấp nhận hookĐồng ý để cài hook kiểm tra thiết kế tự động
- Tải lại công cụKhởi động lại hoặc reload coding agent
- Khởi tạo dự ánChạy /impeccable init để tạo PRODUCT.md
- Thử một lệnhChạy /impeccable critique trên một thành phần
A.Mở terminal ở thư mục dự án
README ghi rõ: chạy từ thư mục gốc của dự án. Đây là chỗ người mới hay vấp nhất. Nếu bạn mở terminal ở thư mục khác, bản cài sẽ nằm sai chỗ. Ví dụ bạn có dự án ở my-site:
cd my-siteB.Chạy trình cài
Đây là lệnh chính trong README:
npx impeccable installnpx tải và chạy gói impeccable mà không cần cài trước. Trình cài sẽ tự dò các công cụ coding agent trên máy, hỏi bạn muốn cài cho dự án này hay cài toàn cục, và đề nghị cài hook thiết kế nếu công cụ của bạn hỗ trợ. README khuyên bạn nên đồng ý cài hook.
Nếu cần chạy tự động trong script, README cho phép chỉ định sẵn công cụ và phạm vi:
npx impeccable install --providers=claude,codex,cursor --scope=projectPhạm vi có hai giá trị project hoặc global. Muốn làm mới bản đã cài, dùng:
npx impeccable updateC.Bước thêm cho ba công cụ
Ba công cụ cần thêm một thao tác thì hook mới chạy:
- Codex: mở
/hooksvà duyệt hook của dự án (duyệt lại sau mỗi bản cập nhật có đổi hook). - Grok Build: chạy
/hooks-trust, hoặc khởi động với--trust. - Hermes Agent: hook là một plugin, chạy một lần lệnh sau:
hermes plugins enable impeccable-design-hookD.Tải lại công cụ rồi khởi tạo
Sau khi cài, hãy reload công cụ coding của bạn, rồi trong khung chat của agent gõ:
/impeccable initTrên Codex, bạn gõ $impeccable init. Lệnh này chỉ cần chạy một lần cho mỗi dự án. Nó đọc code của bạn, chỉ hỏi những gì không tự suy ra được (sản phẩm cho ai, cần làm gì, ràng buộc), rồi ghi PRODUCT.md. Muốn ghi lại hệ thống hình ảnh sẵn có, chạy tiếp /impeccable document để tạo DESIGN.md.
E.Các cách cài khác
Nếu không dùng npx, README có thêm vài đường:
- Claude Code (plugin): gõ
/plugin marketplace add pbakaus/impeccable, sau đó mở/pluginvà cài Impeccable. - GitHub Copilot trong VS Code: cài tiện ích từ Visual Studio Marketplace, hoặc chạy lệnh dưới đây. Bản này cài skill nhưng không có hook.
code --install-extension renaissance-geek.impeccable- Grok Build:
grok plugin install pbakaus/impeccable#plugin --trust- Git submodule (cố định một phiên bản cho cả nhóm):
git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursorSau đó commit .gitmodules, submodule và các liên kết vừa tạo. Đồng đội chỉ cần chạy git submodule update --init --recursive. Cách này chỉ cài skill, không cài hook.
- Chép tay, không cần Node: tải file ZIP cho công cụ của bạn từ trang impeccable.style, hoặc clone repo rồi chép thư mục
skills/impeccablesang đúng chỗ trong dự án. Ví dụ cho Claude Code:
mkdir -p your-project/.claude/skills && cp -r .claude/skills/impeccable your-project/.claude/skills/Chép tay sẽ không có hook và subagent. Bảng đầy đủ thư mục của từng công cụ nằm trong README, mục Installation.
Hook trong Claude Code chạy ngoài sự phê duyệt của model: kể cả khi bạn từ chối lệnh của model, hook đã cài vẫn chạy, và lần sửa đầu tiên có thể tải engine về. Hãy xem lại các hook đã cài trước khi để agent chạy không có người trông. README cũng cho biết có thể tắt hook cho một lượt chạy bằng cờ --settings với disableAllHooks.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra đơn giản nhất là gõ /impeccable một mình trong agent. README nói lệnh này hiện danh sách các lệnh. Nếu danh sách hiện ra, skill đã nạp xong. Trên Codex, mở /skills hoặc gõ $impeccable.
Tiếp theo, chạy thử /impeccable init và xem nó có hỏi bạn về sản phẩm rồi tạo PRODUCT.md ở thư mục dự án không. Nếu cài hook, thử nhờ agent sửa một file giao diện: README nói hook sẽ quét file đó và trả kết quả về cho agent trước khi nó báo là xong.
Còn nếu thấy có gì trục trặc, README có sẵn lệnh chẩn đoán:
/impeccable doctorLệnh này tìm file ngữ cảnh đã cũ, cài đặt không dùng và hook bị hỏng.
Bạn cũng có thể thử bộ dò độc lập, không cần agent:
npx impeccable detect --list-rulesLệnh này in ra mọi quy tắc cùng mã và mô tả.
V.Dùng vào việc thật
A.Chủ shop nhờ AI chấm điểm trang bảng giá
Bạn bán dịch vụ và đã nhờ AI dựng trang bảng giá. Nhìn vào thấy hơi chung chung nhưng không biết sửa gì. Trong agent, gõ:
/impeccable critique the pricing cardsĐây chính là ví dụ khởi đầu README đề nghị. critique chấm thiết kế theo các tiêu chí dễ dùng và xếp thứ tự việc cần sửa trước. Bạn nhận được một danh sách ưu tiên thay vì cảm giác mơ hồ. README lưu ý: mục tiêu hẹp cho kết quả tốt hơn, nên chọn một thành phần thay vì cả trang.
Một phần được xem kỹ còn hơn cả trang liếc qua.
Ông T
B.Nhân viên văn phòng làm cho trang bớt nhạt hoặc bớt ồn
Trang giới thiệu công ty của bạn trông an toàn đến mức nhạt. Bạn gõ:
/impeccable bolder the landing pageNếu ngược lại, trang quá rối, dùng quieter. README viết rằng bolder nạp một bộ hướng dẫn riêng cho đúng động tác đó và nhắm vào đúng một mục tiêu. Bạn cũng có thể mô tả bằng lời thường, ví dụ /impeccable redo this hero section.
C.Lập trình viên kiểm tra trước khi đưa lên
Trước khi đẩy lên, bạn chạy lượt cuối và kiểm tra kỹ thuật:
/impeccable polish settings
/impeccable harden checkout
/impeccable auditpolish là lượt chỉnh cuối, harden lo lỗi, tràn chữ và trường hợp biên, audit cho báo cáo xếp từ P0 đến P3. Nếu dùng lệnh nào thường xuyên, ghim nó lại bằng /impeccable pin audit để có luôn /audit làm lối tắt.
D.Đội dev đặt bộ dò vào CI
Cả nhóm muốn chặn giao diện kém chất lượng ngay từ lúc gộp code. CLI không cần agent:
npx impeccable detect src/
npx impeccable detect --github src/
npx impeccable detect http://localhost:5173Dòng đầu quét một thư mục, dòng hai in chú thích cho GitHub Actions, dòng ba quét trang đang chạy ở máy bạn (cần để bắt các lỗi như độ tương phản thấp hay chữ quá nhỏ, vì chúng chỉ phát hiện được trên trang đã hiển thị). Mã thoát 2 nghĩa là có phát hiện lỗi, 1 nghĩa là không quét được mục tiêu. Nếu thương hiệu của bạn cố ý dùng phông Inter, cho phép nó bằng:
npx impeccable ignores add-value overused-font Inter --reason "Brand font"VI.Lỗi hay gặp và cách xử lý
A.Gõ /impeccable mà không thấy gì
Thường do chưa reload công cụ sau khi cài, hoặc cài sai thư mục. Hãy khởi động lại agent, xác nhận bạn chạy npx impeccable install ở thư mục gốc dự án. Với Cursor và Gemini CLI, README nói có thể phải bật Agent Skills trong phần cài đặt. Với OpenCode, cần chép thêm .opencode/commands/impeccable.md vào dự án để có lệnh /impeccable. Trae thì cần khởi động lại sau khi chép tay.
B.Hook không chạy
Codex, Grok Build và Hermes Agent cần bước duyệt riêng như ở phần cài đặt. Nếu đã làm mà vẫn không thấy gì, chạy /impeccable doctor để tìm hook hỏng.
C.Bộ dò báo ít lỗi khi quét mã nguồn
Với file JSX hay TSX, bộ dò chỉ áp dụng các quy tắc theo mẫu. Các quy tắc cần trang đã hiển thị, như độ tương phản thấp và chữ quá nhỏ, chỉ chạy khi bạn quét một địa chỉ URL. Hãy bật dev server rồi quét đường dẫn localhost.
D.Quét URL báo không quét được
Mã thoát 1 nghĩa là không quét được mục tiêu. Với trang đã hiển thị, README nói CLI dùng Chrome hoặc Edge bạn đã cài, nên hãy kiểm tra máy có một trong hai trình duyệt đó và địa chỉ có truy cập được.
E.Lệnh live mode làm bạn lo
Chế độ live mở dev server của bạn kèm lớp phủ chọn phần tử. Nó chỉ dành cho bản checkout ở máy bạn, đừng chèn vào trang đã triển khai và đừng nới lỏng CSP của bản production để nó chạy. Khi áp dụng chỉnh sửa chữ, nó chạy script impeccable:manual-edit-validate tùy chọn trong package.json bằng quyền của bạn, nên hãy đọc script đó trước khi dùng trong repo lạ.
Khi bấm Apply trong live mode mà không có agent chat nào đang nhận, README nói công cụ có thể chạy lệnh codex (hoặc claude nếu thiếu codex) trong PATH với phê duyệt, kiểm tra quyền và sandbox đều tắt. Nếu bạn muốn giữ việc này trong phiên chat, đặt biến môi trường IMPECCABLE_LIVE_COPY_AGENT=chat khi khởi động live mode, hoặc đặt off để tắt Apply.
VII.Có nên dùng không
Điểm mạnh. Bạn có ngôn ngữ chung để nói chuyện với AI về thiết kế: nói tên động tác thay vì mô tả dài dòng. Bộ dò 62 quy tắc chạy không cần LLM và API key, dùng được cả trong terminal lẫn CI. Công cụ hỗ trợ rất nhiều agent, giấy phép Apache-2.0, và repo vẫn được cập nhật trong vài tháng gần đây.
Giới hạn. Công cụ này không thay thế một người thiết kế thật. README nói nó mạnh nhất khi làm việc trên giao diện đã có, còn dựng trang mới là chế độ khó hơn. Bộ dò, live mode và hook sửa file chỉ dành cho web (HTML và CSS), còn ứng dụng gốc iOS hay Android chỉ được hỗ trợ ở các lệnh thiết kế và audit. Hook chạy ngoài sự phê duyệt của model và live mode có thể chạy lệnh với quyền rộng, nên cần đọc kỹ trước khi dùng trong repo lạ hoặc chạy không người trông.
Về dữ liệu. README ghi rằng khi bắt đầu một thiết kế mới, skill tải một bộ hướng thiết kế từ danh mục của impeccable.style. Tắt telemetry không chặn yêu cầu đó, chỉ chặn bản ghi ẩn danh về hướng nào được hiển thị và bạn chọn hướng nào. Tên dự án, file, code và PRODUCT.md không bị gửi đi. Tắt telemetry bằng npx impeccable telemetry off, hoặc DO_NOT_TRACK=1.
Khi nên chọn cách khác. Nếu bạn chưa dùng coding agent nào, hãy làm quen với một công cụ trước. Nếu chỉ cần kiểm tra giao diện của một trang bất kỳ, tiện ích Chrome hoặc lệnh detect là đủ, không cần cài cả skill. Nếu dự án là ứng dụng gốc, hãy nhớ phần dò lỗi tự động không áp dụng cho nó.
Tóm lại, nếu bạn đã dùng AI để dựng giao diện và thấy kết quả cứ na ná nhau, Impeccable là một bổ sung đáng thử. Cài mất một lệnh, và bạn có thể bắt đầu từ một thành phần nhỏ để xem hiệu quả.
Câu hỏi thường gặp
Impeccable có miễn phí không?
Repo dùng giấy phép Apache-2.0 và bộ dò lỗi không cần API key. Tư liệu không nói gì về chi phí của coding agent bạn dùng kèm, nên khoản đó phụ thuộc vào công cụ của bạn.
Cài Impeccable cần những gì?
Bạn cần một coding agent được hỗ trợ và Node từ 18.19.0 trở lên để chạy npx. README còn nói có cách chép tay không cần Node. Tư liệu không nêu yêu cầu GPU.
Impeccable chạy trên Windows được không?
Tư liệu không nói rõ về hệ điều hành cho cả bộ công cụ. Lệnh npx impeccable install là lệnh Node thông thường. Nếu gặp vấn đề, bạn có thể chạy /impeccable doctor hoặc xem tài liệu tại impeccable.style/docs.
Impeccable có gửi code của tôi đi đâu không?
README nói tên dự án, file, code và PRODUCT.md không bao giờ bị gửi đi. Có một yêu cầu tải bộ hướng thiết kế từ danh mục impeccable.style khi bắt đầu thiết kế mới, và telemetry ẩn danh ghi hướng nào được hiển thị và chọn. Bạn có thể tắt telemetry bằng npx impeccable telemetry off hoặc DO_NOT_TRACK=1.
Khác gì so với tự viết prompt cho AI?
Impeccable gói sẵn các động tác thiết kế có tên (polish, bolder, critique, audit…) mỗi cái nạp một quy trình riêng cho một mục tiêu. Nó còn có bộ dò 62 quy tắc cố định không dùng LLM. Tư liệu không so sánh chi tiết với công cụ khác.
Dùng được với công cụ nào?
README liệt kê Claude Code, Cursor, Codex CLI, GitHub Copilot, Devin, Replit Agent, Gemini CLI, Grok Build, OpenCode, Google Antigravity, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Pi, Hermes Agent, DeepSeek Harness và Veto. Hook kiểm tra tự động có trên Claude Code, Cursor, Codex, GitHub Copilot, Grok Build và Hermes Agent.
Có dùng được cho ứng dụng di động không?
Có một phần. Đặt mục Platform trong PRODUCT.md là ios, android hoặc adaptive thì các lệnh thiết kế dùng chuẩn Apple HIG hoặc Material 3, và audit đọc được mã SwiftUI, Compose, React Native, Flutter. Bộ dò, live mode và hook sửa file chỉ dành cho web.


