# Xử lý sự cố và FAQ Phần lớn sự cố hiện ra dưới dạng một mã chẩn đoán. Tìm mã của bạn bên dưới, hoặc xem danh sách đầy đủ trong [tài liệu CLI](https://www.werewolf-ui.dev/vi/docs/cli.md). ## Sự cố thường gặp ### `add` báo component không tồn tại (`WW_COMPONENT`) CLI cài từ catalog có sẵn lúc nó được phát hành. Nếu tên đúng chính tả, component đó mới hơn `werewolf-ui@0.1.0-alpha.1`. Hãy cài qua registry bằng lệnh bên dưới. Item trong registry có kèm stylesheet token mặc định: nếu lệnh hỏi ghi đè `styles/werewolf.css`, chọn không để giữ theme của bạn. ```bash npx shadcn add https://www.werewolf-ui.dev/r/attachment-preview.json ``` Các component trên site này mới hơn bản CLI đã phát hành: - [AttachmentPreview](https://www.werewolf-ui.dev/vi/components/attachment-preview.md) - [AvatarStack](https://www.werewolf-ui.dev/vi/components/avatar-stack.md) - [ButtonGroup](https://www.werewolf-ui.dev/vi/components/button-group.md) - [Chart](https://www.werewolf-ui.dev/vi/components/chart.md) - [Checklist](https://www.werewolf-ui.dev/vi/components/checklist.md) - [CodeBlock](https://www.werewolf-ui.dev/vi/components/code-block.md) - [Composer](https://www.werewolf-ui.dev/vi/components/composer.md) - [ConversationList](https://www.werewolf-ui.dev/vi/components/conversation-list.md) - [EmojiPicker](https://www.werewolf-ui.dev/vi/components/emoji-picker.md) - [FileUpload](https://www.werewolf-ui.dev/vi/components/file-upload.md) - [FilterBar](https://www.werewolf-ui.dev/vi/components/filter-bar.md) - [GroupAvatar](https://www.werewolf-ui.dev/vi/components/group-avatar.md) - [MessageActions](https://www.werewolf-ui.dev/vi/components/message-actions.md) - [MessageBubble](https://www.werewolf-ui.dev/vi/components/message-bubble.md) - [MessageList](https://www.werewolf-ui.dev/vi/components/message-list.md) - [Navbar](https://www.werewolf-ui.dev/vi/components/navbar.md) - [OtpInput](https://www.werewolf-ui.dev/vi/components/otp-input.md) - [ResizablePanels](https://www.werewolf-ui.dev/vi/components/resizable-panels.md) - [SortableList](https://www.werewolf-ui.dev/vi/components/sortable-list.md) - [Timeline](https://www.werewolf-ui.dev/vi/components/timeline.md) ### Lệnh báo xung đột (`WW_CONFLICT`) File mà CLI muốn ghi khác với bản nó đã tạo, thường vì bạn hoặc agent đã sửa. Chưa có gì được ghi. So sánh file, giữ chỉnh sửa của bạn hoặc chuyển nó sang chỗ khác, rồi chạy lại với `--overwrite` và đúng đường dẫn đó. ```bash npx werewolf-ui add button --overwrite src/components/ui/button.tsx ``` ### Init không chọn được app hoặc package manager (`WW_PROJECT_AMBIGUOUS`) Bạn chạy ở thư mục gốc của workspace, hoặc dự án có nhiều lockfile, stylesheet hay framework. Chỉ rõ app và package manager. ```bash npx werewolf-ui init --cwd ./apps/web --package-manager pnpm ``` ### Init không tìm thấy import alias (`WW_PROJECT_ALIAS`) Thêm path alias vào `tsconfig.json` (hoặc `jsconfig.json`), ví dụ `"paths": { "@/*": ["./src/*"] }`, rồi chạy lại init. ### Init không đặt được CSS import (`WW_CSS_IMPORT`) Stylesheet của app cần đúng một dòng `@import "tailwindcss";`. Nếu có nhiều stylesheet có thể chọn, chỉ rõ bằng `--css`. ### `add`, `theme` hoặc `tokens build` báo app chưa khởi tạo (`WW_NOT_INITIALIZED`) Chạy `npx werewolf-ui init` trong cùng thư mục trước, hoặc truyền đúng `--cwd` bạn đã dùng cho init. ### Class Tailwind không có tác dụng Stylesheet token xóa bảng màu, bo góc, đổ bóng và độ đậm chữ gốc của Tailwind, nên class bảng màu (tên màu kèm số), `rounded-lg` hay `font-bold` không sinh CSS. Dùng class token thay thế (`bg-accent`, `rounded-element`, `font-medium`). Lint báo các class này là `WW_CLASS_REMOVED`. ### Chữ trên nút accent bị mất Với accent mặc định, accent ở chế độ tối trùng màu chữ chính. Trên `bg-accent` chỉ dùng `text-text-on-accent` và `text-icon-on-accent`. Lint báo cặp sai là `WW_SOLID_PAIR`. ### Style cho chế độ tối không có tác dụng Token đổi theo `data-theme`, nên không dùng biến thể `dark:` (lint báo `WW_DARK_VARIANT`). Mặc định là tối; đặt `data-theme="light"` để chuyển sáng. ### `npx wolf` chạy một thứ khác `wolf` là một package npm không liên quan. Luôn viết `npx werewolf-ui`. Alias `wolf` chỉ có sau khi cài global (`npm i -g werewolf-ui`). ### Client MCP không hiện công cụ nào Kiểm tra client chạy được Node 20+ và `npx`, đường dẫn `--cwd` tồn tại và là đường dẫn tuyệt đối, và không có gì khác ghi ra stdout. Lỗi khởi động ghi ra stderr, nên hãy xem log MCP của client. ### Lint qua nhưng màn hình vẫn sai Lint chỉ đọc class và style tĩnh. Class ghép lúc chạy được báo là cảnh báo `WW_DYNAMIC`, không được kiểm tra. Xem `data.coverage` trong kết quả `--json`, và giữ tên class nguyên vẹn trong code. ## Câu hỏi ### Tôi có cần biết thiết kế không? Không. Các quyết định thiết kế đã nằm trong token và design skill. Bạn chỉ chọn accent, độ ám xám và bo góc. ### Tôi có thể tự sửa một token không? Hãy đổi seed: bộ tạo theme giữ mọi cặp màu dễ đọc, điều mà sửa tay không đảm bảo được. Nếu cần một vai trò chưa có token, hãy mở issue; thiếu token được xem là lỗi. ### Dùng token mà không có React hay Tailwind được không? Được. `tokens build` xuất biến CSS thuần, JSON, SwiftUI và Compose. Component thì cần React 19 và Tailwind CSS v4. ### Có bắt buộc dùng Tabler Icons không? Không. Docs và component dùng Tabler, nhưng bộ icon hay icon font nào cũng được. Theo đúng kích thước ở trang [Icon](https://www.werewolf-ui.dev/vi/docs/iconography.md). ### Cập nhật component thế nào? Chạy lại `add` với CLI mới hơn. File giống hệt được bỏ qua, file nào khác sẽ báo xung đột, để bạn xem thay đổi trước khi truyền đường dẫn của nó vào `--overwrite`. ### Cái gì miễn phí, cái gì là Pro? Token, component, CLI và MCP server miễn phí theo MIT. Pro là các màn hình hoàn chỉnh và component agent lớn, đang mở bán trước trên [trang Pro](https://www.werewolf-ui.dev/vi/pricing.md), mở cài đặt vào tháng 1 năm 2027. Câu hỏi về Pro, gửi tới support@werewolf-ui.dev. ### Báo lỗi ở đâu? Mở issue trên [GitHub](https://github.com/joeynguyen1412/werewolf-ui/issues) kèm lệnh đã chạy, kết quả `--json` và framework bạn dùng.