Cài đặt

1. Yêu cầu

Node 20+, React 19 và Tailwind CSS v4 trong app Next.js app-router hoặc Vite React TypeScript. Thiết lập compiler alias cho import component. Chạy lệnh trong thư mục app, hoặc dùng --cwd để chọn app trong workspace.

2. Khởi tạo app

npx werewolf-ui init

Chạy init một lần. Lệnh tạo werewolf.json, tokens/seed.json và styles/werewolf.css, thêm CSS import sau import Tailwind, và cài luật cho agent. Seed hợp lệ đã có được giữ nguyên. Bạn không cần tự thêm CSS import.

CLI nhận diện package manager từ lockfile hoặc trường packageManager. Nếu chưa có cả hai, chọn rõ bằng --package-manager npm chẳng hạn. Nếu có nhiều lockfile hoặc thông tin không khớp, hãy chọn rõ app và package manager.

3. Thêm component

npx werewolf-ui add button
npx werewolf-ui add button input dialog

Sau init, thêm một hoặc nhiều component theo tên. Add cài các dependency component và package, ánh xạ import theo compiler alias của app, và giữ nguyên seed cùng theme đã tạo. File có nội dung giống nhau được bỏ qua.

4. Đổi theme

Xem thử theme bằng panel Giao diện trên header: màu accent, độ ám xám và bo góc. Nút Copy lệnh cho bạn lệnh theme với các lựa chọn đó, hoặc thay <hex> bên dưới bằng mã hex bạn chọn. Lệnh theme cập nhật seed và stylesheet của app. Bạn có thể đặt thêm --gray-tint và --radius-base (sharp, default, round, pill); các lựa chọn không truyền vào được giữ nguyên.

npx werewolf-ui theme --accent "<hex>"

Dùng theme để đổi theme do CLI quản lý. Thay stylesheet đã tạo bằng file tải về được tính là chỉnh sửa của bạn, nên lần tạo sau cần chỉ định ghi đè.

5. Đưa luật cho agent

Init cài .agents/skills/werewolf-design/SKILL.md, một phần do CLI quản lý trong AGENTS.md và .cursor/rules/werewolf.mdc. Cho agent đọc design skill trước khi viết UI. Cấu hình MCP là bước riêng.

Công cụ CLI

Với script và agent code, thêm --yes --json vào lệnh CLI để chấp nhận thao tác đã lên kế hoạch và nhận kết quả có cấu trúc. Mỗi lệnh đều có --help. API component vẫn ở trạng thái draft trong bản alpha.

CLI giữ nguyên chỉnh sửa của bạn: --yes không ghi đè chúng. Xem xét xung đột trước khi truyền --overwrite cùng đường dẫn chính xác của file đã tạo. Add cần chỉ định ghi đè cho file component có nội dung khác, kể cả dependency. Khi ghi file thất bại, CLI hoàn tác file nhưng không hoàn tác việc cài package.

npx werewolf-ui lint src --json
npx werewolf-ui lint src --fix --yes --json

{
  "command": "npx",
  "args": [
    "--yes",
    "werewolf-ui@0.1.0-alpha.0",
    "mcp",
    "--cwd",
    "/absolute/path/to/app"
  ]
}

npx werewolf-ui tokens build --platform ios --out exported-tokens

npx werewolf-ui docs button
npx werewolf-ui add --help

Cách khác: registry và cài thủ công

Dùng cách này nếu bạn đang cài component qua registry công khai. Lệnh thêm component, các dependency và styles/werewolf.css. Luồng này không khởi tạo CLI Werewolf hay cài luật cho agent.

npx shadcn add https://www.werewolf-ui.dev/r/button.json

Import stylesheet một lần trong CSS gốc, sau @import "tailwindcss", bằng đường dẫn tính từ file đó. Từ app/globals.css, dòng import là:

@import "../styles/werewolf.css";

Với cách cài thủ công này, dùng panel Giao diện trên header (Copy CSS hoặc Tải werewolf.css) và thay styles/werewolf.css. Copy design skill vào thư mục mà agent đọc luật.