shadcn

Tổng quan về shadcn skill

shadcn skill dùng để làm gì

shadcn skill giúp trợ lý AI làm việc đúng cách bên trong các dự án shadcn/ui thực tế: tìm component, cài bằng đúng CLI, ghép màn hình từ các primitive sẵn có, và tránh các lỗi API thường gặp giữa các preset và họ component khác nhau. Skill này đặc biệt hữu ích khi bạn cần nhiều hơn kiểu “generate một cái button”, mà muốn đầu ra tôn trọng components.json, các mục registry đã cài, template của dự án, cũng như khác biệt giữa base và radix.

Ai nên dùng shadcn skill này

Những nhóm phù hợp nhất gồm:

• lập trình viên đã dùng shadcn/ui
• team đang áp dụng preset hoặc quy trình UI dựa trên registry
• người dùng AI để thêm hoặc refactor form, dialog, trang settings, dashboard, hoặc phần theme
• bất kỳ ai muốn trợ lý kiểm tra ngữ cảnh dự án trước khi viết JSX

Nếu bạn không dùng shadcn/ui, components.json, hoặc shadcn CLI, thì skill này có lẽ quá chuyên biệt.

Nhu cầu thực sự mà skill giải quyết

Người dùng không chỉ cần một bản tóm tắt repo. Họ muốn trợ lý:

1. nhận diện đúng cấu hình shadcn của dự án,
2. ưu tiên component sẵn có trước khi tự nghĩ ra component mới,
3. dùng đúng lệnh CLI và đúng flag đã được tài liệu hóa,
4. dựng UI theo pattern được thư viện ưu tiên,
5. tránh những lỗi vỡ ngầm như ghép trigger sai, thiếu wrapper nhóm, hoặc nối validation form không đúng.

Đó chính là điểm mà shadcn skill tạo ra giá trị vượt lên trên một prompt UI thông thường.

Điều gì khiến shadcn khác với prompt chung chung

Những khác biệt mạnh nhất đều rất thực tế:

• bắt đầu từ ngữ cảnh dự án lấy qua npx shadcn@latest info --json
• ưu tiên search, view, và docs trước khi tự triển khai
• mã hóa các quy tắc dự án từ những file như rules/composition.md, rules/forms.md, rules/styling.md, và rules/base-vs-radix.md
• bao quát cả theme và chuyển preset, không chỉ các snippet component
• có hướng dẫn MCP cho luồng tìm registry và cài đặt

Nói ngắn gọn, shadcn skill không chỉ là “viết React”, mà là “viết đúng React cho cấu hình shadcn này”.

Những ràng buộc quan trọng trước khi áp dụng

Trước khi phụ thuộc vào skill này, bạn nên biết các giới hạn sau:

• skill giả định bạn có thể chạy shadcn CLI qua package runner của dự án: npx, pnpm dlx, hoặc bunx --bun
• nó bị giới hạn trong các flag CLI đã được tài liệu hóa; skill chủ động cảnh báo không được bịa thêm flag
• nhiều đầu ra tốt phụ thuộc vào việc có components.json hợp lệ
• chi tiết API có thể khác nhau theo preset và theo base vs radix, nên bê nguyên ví dụ mà không kiểm tra rất dễ sai

Cách dùng shadcn skill

Ngữ cảnh cài đặt cho shadcn skill

Hãy thêm skill vào môi trường AI của bạn theo quy trình cài đặt chuẩn của directory, sau đó dùng nó trong một repo thực sự có — hoặc dự định sẽ có — cấu hình shadcn. Trên thực tế, yêu cầu ở phía repository còn quan trọng hơn cả lệnh cài skill: trợ lý cần truy cập được file dự án và nên có khả năng chạy các lệnh shadcn CLI.

Trong project đích, những lệnh runtime liên quan là:

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

Hãy thay bằng pnpm dlx shadcn@latest hoặc bunx --bun shadcn@latest nếu đó là package manager của dự án.

Hãy đọc các file này trước khi yêu cầu đầu ra

Để dùng shadcn nhanh và chính xác, nên kiểm tra các file theo thứ tự gần đúng sau:

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

Vì sao thứ tự này hiệu quả:

• SKILL.md xác định điều kiện kích hoạt và workflow
• cli.md giúp tránh đoán mò lệnh và flag
• các file rules/ ghi lại đúng những lỗi mà codegen generic rất hay mắc
• customization.md quan trọng khi bạn cần styling an toàn với theme, thay vì hack màu Tailwind trực tiếp
• mcp.md quan trọng khi trợ lý có thể duyệt registry qua MCP thay vì chỉ gọi shell

Bắt đầu mọi tác vụ shadcn bằng bước khám phá dự án

Bước đầu tiên tốt nhất gần như luôn là:

npx shadcn@latest info --json

Lệnh này cho trợ lý biết những gì đã được cấu hình sẵn, bao gồm cả ngữ cảnh component và project. Nó đặc biệt hữu ích để:

• kiểm tra xem có components.json hay không
• nhận diện các component đã cài
• phát hiện chi tiết cấu hình làm thay đổi lựa chọn code hợp lệ
• xác nhận package runner để tránh đưa ví dụ lệnh sai

Nếu bỏ qua bước này, shadcn skill sẽ trở nên gần giống một prompt chung chung hơn nhiều.

Biến một mục tiêu còn mơ hồ thành prompt shadcn tốt

Prompt yếu:

Build me a profile dialog with shadcn.

Prompt tốt hơn:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

Vì sao prompt này mạnh hơn:

• buộc phải khám phá dự án trước
• chỉ rõ hành vi phụ thuộc preset
• nêu rõ ràng ràng buộc về icon và styling
• yêu cầu bước cài đặt nếu còn thiếu dependency

Dùng search và docs trước khi tự viết code

Một workflow shadcn chất lượng cao thường là:

1. tìm component sẵn có trong registry,
2. xem docs và ví dụ,
3. thêm phần còn thiếu,
4. rồi mới ghép thành màn hình.

Các lệnh thực tế:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

Điều này đặc biệt quan trọng với form, overlay, navigation, và empty state, nơi các rule của skill ưu tiên pattern của thư viện hơn là các cấu trúc div tự chế.

Ghép màn hình từ các khối có sẵn của shadcn

shadcn skill phát huy tốt nhất khi bạn yêu cầu “composition”, không phải một UI custom nguyên khối. Cách mô tả bài toán tốt thường là:

• “settings page = Tabs + Card + form controls”
• “dashboard = Sidebar + Card + Chart + Table”
• “empty state = Empty component, không phải một div căn giữa tự viết”
• “callout = Alert, không phải box viền tự dựng”

Điều này bám đúng workflow ưu tiên của skill: dùng component sẵn có trước, rồi chỉ điều chỉnh variant và wrapper khi thật sự cần.

Tôn trọng khác biệt giữa base và radix trong shadcn

Một trong những điểm khiến nhiều người vấp nhất khi dùng shadcn là cho rằng mọi ví dụ shadcn đều thay thế cho nhau được. Thực tế là không.

Skill này có hướng dẫn rõ ràng cho base vs radix, bao gồm:

• asChild vs render
• khác biệt trong cách ghép trigger
• nativeButton={false} trong một số trường hợp chỉ dành cho base
• khác biệt API ở các component như Select, ToggleGroup, Slider, và Accordion

Nếu prompt của bạn chưa nêu rõ đang dùng cấu hình nào, hãy yêu cầu trợ lý tự phát hiện từ npx shadcn@latest info.

Dùng hướng dẫn styling để không vỡ theme

Với shadcn cho UI Design, kết quả tốt hơn thường đến từ semantic token và theme dựa trên CSS variable, không phải màu Tailwind hard-code.

Nên ưu tiên:

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

Tránh mặc định dùng:

• bg-red-500
• text-gray-400
• quá nhiều override dark: thủ công

Điều này quan trọng vì customization.md giải thích rằng component kế thừa từ CSS variable. Nếu trợ lý dùng semantic token, thiết kế của bạn sẽ mở rộng qua light/dark theme và các preset sạch sẽ hơn nhiều.

Xử lý form theo đúng cách của shadcn

Các eval và rule cho thấy chất lượng form là một trọng tâm thật sự. Cách dùng shadcn tốt cho form thường bao gồm:

• dùng pattern layout field có sẵn thay vì xếp chồng div thô
• đánh dấu trạng thái invalid bằng data-invalid và aria-invalid
• dùng Switch cho các tùy chọn on/off độc lập
• ưu tiên spacing kiểu gap-* thay vì space-y-* khi rule yêu cầu

Nếu tác vụ của bạn có validation, hãy nói rõ điều đó. Nếu không, nhiều trợ lý sẽ sinh ra form trông có vẻ ổn nhưng lại không nhất quán với thư viện.

Dùng MCP khi editor của bạn hỗ trợ

Nếu môi trường của bạn hỗ trợ MCP, shadcn skill có thể đáng tin hơn trong các thao tác với registry. mcp.md mô tả các công cụ để:

• liệt kê registry của project
• tìm mục trong registry
• xem chi tiết item và nội dung file
• lấy ví dụ
• cài item

Điều này hữu ích khi bạn muốn trợ lý duyệt registry theo kiểu hội thoại thay vì chỉ phụ thuộc vào output từ CLI. Tuy nhiên nó không thay thế info --json cho cấu hình project.

Mẫu prompt thực tế để dùng shadcn skill

Hãy dùng mẫu này khi bạn muốn đầu ra chất lượng hơn:

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

Câu hỏi thường gặp về shadcn skill

shadcn skill này chỉ dùng để cài component thôi sao?

Không. Các tác vụ shadcn install là một phần của nó, nhưng phạm vi của skill rộng hơn nhiều: kiểm tra dự án, tìm registry, ghép component, xử lý theme, debug, chuyển preset, và refactor đúng API đều nằm trong phạm vi.

shadcn skill có thân thiện với người mới không?

Có, nếu bạn đã quen với React và một package manager. Skill này giảm bớt việc đoán mò bằng cách hướng trợ lý đến đúng lệnh và đúng rule. Nó sẽ kém thân thiện hơn nếu bạn đang cần một phần nhập môn đầy đủ về React, Tailwind, hoặc design system từ đầu.

Khi nào shadcn tốt hơn một prompt bình thường?

Hãy dùng shadcn skill khi độ chính xác phụ thuộc vào ngữ cảnh dự án:

• components.json hiện có
• khớp với các component đã cài
• hành vi base vs radix
• chỉ dùng các CLI flag đã được tài liệu hóa
• giữ nguyên token theme và rule composition của thư viện

Một prompt thường có thể tạo ra JSX trông hợp lý, nhưng dễ bỏ sót bước cài đặt hoặc dùng sai API của component hơn.

Khi nào bạn không nên dùng shadcn skill?

Hãy bỏ qua nếu:

• dự án của bạn không dùng shadcn/ui
• bạn chỉ cần mockup HTML/CSS chung chung
• bạn muốn một câu trả lời không phụ thuộc design system nào
• trợ lý không thể đọc file hoặc chạy lệnh, và bạn cũng không thể cung cấp thủ công ngữ cảnh cần thiết

Trong những trường hợp đó, một skill frontend tổng quát hơn có thể phù hợp hơn.

Skill này có hỗ trợ các quyết định shadcn cho UI Design không?

Có, đặc biệt ở phần composition và theming. Nó đẩy trợ lý theo hướng dùng primitive tái sử dụng được, semantic color token, pattern overlay đúng chuẩn, và cấu trúc component dễ bảo trì hơn so với các layout “đóng tay” dùng một lần.

Điều gì thường làm đầu ra AI dùng shadcn bị hỏng?

Những lỗi phổ biến gồm:

• bịa ra CLI flag không được hỗ trợ
• dùng sai cách ghép trigger cho base vs radix
• tự tạo UI custom thay vì dùng component có sẵn trong registry
• styling bằng màu thô làm xung đột với hệ theme
• bỏ sót các subcomponent bắt buộc như title, group, hoặc fallback

Đây chính xác là những điểm mà skill này được thiết kế để siết chặt.

Cách cải thiện shadcn skill

Cung cấp trước phần ngữ cảnh còn thiếu cho shadcn skill

Cải thiện có tác động lớn nhất là đầu vào tốt hơn. Hãy nêu rõ:

• framework hoặc template (next, vite, astro, v.v.)
• có components.json hay không
• base hay radix nếu đã biết
• bộ icon hiện tại
• component hoặc màn hình mục tiêu
• tác vụ có bao gồm cài đặt, refactor, hay bugfix không

Chỉ một câu mô tả ngữ cảnh đủ cụ thể cũng có thể ngăn trợ lý chọn sai API.

Yêu cầu lệnh trước khi yêu cầu code nếu có thể đang thiếu component

Nếu dự án của bạn có thể chưa cài component cần thiết, hãy prompt như sau:

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

Cách này cải thiện chất lượng đầu ra vì nó tách thay đổi môi trường ra khỏi phần triển khai, giúp kết quả dễ tin cậy và dễ áp dụng hơn.

Buộc đầu ra phải bám rule với các loại component dễ vỡ

Với form, dialog, dropdown, sheet, drawer, và select, hãy yêu cầu trợ lý bám sát các file rule. Ví dụ:

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

Điều này quan trọng vì nhiều output chất lượng thấp nhìn thì ổn nhưng lại làm hỏng accessibility hoặc vi phạm contract composition.

Cải thiện cách dùng shadcn bằng cách nêu rõ ràng ràng buộc thiết kế

Một prompt UI tốt không chỉ là “làm nó trông hiện đại.” Hãy thêm các ràng buộc như:

• chỉ dùng semantic token
• không dùng utility màu trực tiếp từ palette
• dark mode phải hoạt động mà không cần override thủ công
• ưu tiên variant sẵn có trước khi thêm class custom
• ưu tiên empty state, alert, separator, badge, và skeleton của thư viện

Các chi tiết này cải thiện đáng kể chất lượng ngay từ lượt đầu trong các tác vụ shadcn cho UI Design.

Lặp lại bằng các chỉnh sửa có mục tiêu, không viết lại toàn bộ

Sau đầu ra đầu tiên, đừng chỉ nói “thử lại.” Thay vào đó, hãy nói:

• “Refactor this to use installed shadcn components only.”
• “Make this valid for base, not radix.”
• “Replace raw color classes with semantic tokens.”
• “Add the missing title/fallback/group wrappers required by shadcn.”
• “Show the exact shadcn add commands for anything assumed.”

Cách này giữ lại phần làm tốt, đồng thời sửa trúng những chỗ dễ sai nhất.

Đối chiếu với những tín hiệu mạnh nhất trong repository

Để tăng độ tin cậy, hãy so đầu ra với:

• cli.md cho lệnh và flag
• rules/composition.md cho cấu trúc
• rules/base-vs-radix.md cho tính đúng đắn của API
• rules/forms.md cho pattern validation và layout
• rules/styling.md và customization.md cho styling an toàn với theme
• evals/evals.json để biết trong thực tế “đầu ra tốt” trông như thế nào

Đó là cách nhanh nhất để biết shadcn skill đang tạo ra đầu ra bám sát repository hay chỉ là code UI chung chung.