Skill
Triển khai UI accessible với ak:ui-styling
Áp dụng shadcn/ui, Tailwind, responsive theme và visual check trong khi vẫn kiểm soát tệp project.
Dùng ak:ui-styling để triển khai hoặc tinh chỉnh giao diện dựa trên React bằng
shadcn/ui, Radix primitive, Tailwind CSS, theme token, responsive layout và
accessibility pattern. Skill có thể tư vấn từ reference đóng gói hoặc thay đổi
project bằng cách thêm component và generate configuration.
Chọn ak:ui-styling cho UI implementation
Dùng ak:ui-styling khi
- Bạn cần thêm hoặc compose shadcn/ui component trong project hiện có.
- Bạn đang triển khai Tailwind utility, token, dark mode, responsive layout, form behavior, focus state hoặc screen-reader support.
- Bạn muốn accessibility và visual-consistency pass ở cấp component.
- Bạn cần visual artifact kiểu canvas cùng design philosophy đi kèm.
Chọn workflow khác khi
- Bạn cần recommendation cấp product về style, palette, typography, UX hoặc chart
trước implementation. Dùng
ak:ui-ux-pro-max. - Bạn chỉ cần audit theo web guideline bên ngoài hiện tại. Dùng
ak:web-design-guidelines. - Bạn cần logo, identity mockup, poster hoặc marketing graphic. Dùng
ak:design. - Task chỉ liên quan backend hoặc không đổi bề mặt hiển thị hay tương tác.
Chuẩn bị project
- Đọc instruction của repository và xác định framework, package manager, Tailwind version, theme source, alias cùng component convention hiện có.
- Giữ nguyên design token hiện tại. Cung cấp page hoặc component liên quan, breakpoint được hỗ trợ, state, content và acceptance criteria.
- Xác nhận có
components.jsontrước khi thêm shadcn/ui component. Installer đóng gói không init shadcn/ui thay bạn. - Chuẩn bị Node.js và
npxcho shadcn/ui. Chỉ helper script đóng gói mới cần Python. - Nêu ranh giới tệp và package manifest, lockfile,
components/ui/, global CSS hoặc Tailwind configuration có được đổi hay không.
| Runtime | Cách gọi | Ranh giới bằng chứng |
|---|---|---|
| Claude Code | /ak:ui-styling ... | Phân phối native có thể dùng bề mặt Claude Hook được hỗ trợ đầy đủ. Package installation và visual testing vẫn phụ thuộc tool của project. |
| Cursor | /ak:ui-styling ... | Cách gọi slash đã được người dùng xác minh; behavior tương đương cho browser, Hook hay package manager chưa được thiết lập. |
| Codex | $ak:ui-styling ... | Hỗ trợ native Skill discovery, với Hook projection một phần và render tool phụ thuộc session. |
Xem Runtime adapter để biết chi tiết phân phối.
Chạy Skill
Skill cấp cao nhất nhận yêu cầu component hoặc layout và không có mode flag được tài liệu hóa. Đặt state mong muốn, responsive behavior, accessibility check và ranh giới tệp trong yêu cầu.
/ak:ui-styling "Add an accessible account dialog using existing tokens; preserve components.json, support keyboard focus and reduced motion, test light/dark at mobile and desktop, and do not overwrite existing UI files"/ak:ui-styling "Add an accessible account dialog using existing tokens; preserve components.json, support keyboard focus and reduced motion, test light/dark at mobile and desktop, and do not overwrite existing UI files"$ak:ui-styling "Add an accessible account dialog using existing tokens; preserve components.json, support keyboard focus and reduced motion, test light/dark at mobile and desktop, and do not overwrite existing UI files"Chọn mutation path có chủ đích
| Path | Hành vi mặc định | Ranh giới quan trọng |
|---|---|---|
| Reference hoặc review | Đọc guidance đóng gói về component, theme, accessibility, Tailwind, responsive và canvas | Recommendation không phải runtime proof; hãy test UI thực tế. |
shadcn_add.py | Gọi npx shadcn@latest add cho component được nêu | Có thể dùng mạng và resolve package. CLI ghi component cùng dependency file. Helper dừng khi component đã tồn tại trừ khi truyền --overwrite. |
shadcn_add.py --dry-run | In lệnh npx mà không chạy | Dùng để review scope; không chứng minh component sẽ cài thành công. |
tailwind_config_gen.py | Ghi tailwind.config.ts cho React trong thư mục hiện tại | Ghi trực tiếp vào output path đã resolve. Dùng --output hoặc --validate-only để tránh thay config hiện có ngoài ý muốn. |
| Canvas workflow | Tạo tệp Markdown design philosophy cùng visual expression PNG hoặc PDF | Cần renderer và visual QA; đây là path visual artifact, không phải application component code. |
Tailwind generator hỗ trợ --framework, --js, --colors, --fonts,
--spacing, --breakpoints, --plugins, --output và --validate-only.
Plugin entry được generate vẫn cần cài package tương ứng.
Theo dõi các stage có thể quan sát
- Kiểm tra system. Xác định version, token, component pattern, accessibility requirement, responsive boundary và tệp được bảo vệ.
- Chọn primitive và state. Ưu tiên semantic HTML cùng behavior dựa trên Radix; xác định default, hover, focus, pressed, disabled, loading, error, empty và dark-mode state trước khi styling.
- Review file plan. Phân biệt component copy, package change, global theme change và generated configuration. Dùng dry-run hoặc validation-only khi hợp lý.
- Triển khai bằng token hiện có. Giữ utility tĩnh và dễ discover, dùng tên màu semantic, giữ visible focus và xây mobile-first.
- Xác minh behavior và visual. Chạy project check tập trung, keyboard flow, contrast check, reduced motion, zoom và breakpoint inspection.
- Báo cáo bằng chứng. Liệt kê tệp đã đổi, package đã cài, lệnh, test result, screenshot hoặc manual check và trạng thái chưa xác minh.
Giữ approval ở project owner
Cài component làm đổi source code
shadcn/ui dùng mô hình copy vào codebase. Hãy duyệt riêng package installation,
component file mới và mọi overwrite. Không dùng --overwrite để vượt qua
conflict chưa được kiểm tra.
npx shadcn@latestcó thể liên hệ package registry và thực thi CLI được tải. Ghi nhận package change đã resolve và dùng package manager của repository khi policy yêu cầu.- Configuration generator có thể thay tệp hiện có tại output path. So sánh hoặc chọn path mới trước khi ghi.
- Dark-mode và token change có thể ảnh hưởng toàn ứng dụng. Coi global CSS và shared primitive là scope rộng hơn một component.
- Primitive accessible không làm composition tự động accessible. Label, focus order, error, contrast, keyboard behavior, zoom và reduced motion vẫn cần test.
Xác minh output và bằng chứng
Một lần chạy hoàn tất nên cho thấy:
- Exact diff của component, stylesheet, config, manifest và lockfile.
- Source token mapping và xác nhận raw color hoặc one-off spacing ngoài ý muốn không thay semantic token.
- Keyboard navigation, visible focus, focus return của dialog, label, live-region behavior, error association, touch target và color-contrast result.
- Light và dark mode ở breakpoint liên quan, gồm 320px, 640px, 768px, 1024px, landscape, zoom 200% và reduced motion khi áp dụng.
- Test tập trung cùng build/type evidence có trong project, cộng ghi chú rõ cho mọi mục chỉ check thủ công hoặc chưa check.
Xử lý sự cố và giới hạn
| Triệu chứng | Bước tiếp theo an toàn |
|---|---|
Thiếu components.json | Kiểm tra project và xin approval trước khi chạy npx shadcn@latest init; helper chỉ thêm component vào project đã init. |
| Component đã tồn tại | Diff component local với component upstream được yêu cầu. Sửa có chủ đích hoặc dừng; đừng chọn --overwrite đầu tiên. |
| Tailwind config được generate xung đột project | Dùng --validate-only hoặc ghi vào review path, rồi merge field tương thích thủ công. |
| Layout chỉ hoạt động ở một width | Quay về style mobile-first rồi test exact breakpoint boundary, orientation, zoom và overflow. |
| Radix behavior hoạt động nhưng audit lỗi | Kiểm tra label, description, focus order, live region và cặp foreground/background riêng của composition. |
| Visual đúng nhưng thiếu bằng chứng | Chạy keyboard, contrast, responsive và project check tập trung trước khi tuyên bố hoàn tất. |
Reference đóng gói có thể chậm hơn tài liệu shadcn/ui, Tailwind, browser hoặc
accessibility hiện tại. Xác nhận cú pháp nhạy theo version với project đã cài.
Stable và beta chứa nội dung cùng helper ak:ui-styling giống nhau trong các
release được tài liệu hóa.
Tiếp tục với Runtime adapter, Project, artifact và checkpoint, hoặc Tổng quan Engineer Kit.