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.

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.

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:

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

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.

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.

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, 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 kèm lệnh đã chạy, kết quả --json và framework bạn dùng.