# Troubleshooting and FAQ Most problems show up as a diagnostic code. Find yours below, or check the full list in the [CLI reference](https://www.werewolf-ui.dev/docs/cli.md). ## Common problems ### `add` says a component does not exist (`WW_COMPONENT`) The CLI installs from the catalog it was published with. If the name is spelled right, the component is newer than `werewolf-ui@0.1.0-alpha.1`. Install it from the registry with the command below instead. The registry item also carries the default token stylesheet: if the command asks to overwrite `styles/werewolf.css`, answer no so your theme stays. ```bash npx shadcn add https://www.werewolf-ui.dev/r/attachment-preview.json ``` Components on this site that are newer than the published CLI: - [AttachmentPreview](https://www.werewolf-ui.dev/components/attachment-preview.md) - [AvatarStack](https://www.werewolf-ui.dev/components/avatar-stack.md) - [ButtonGroup](https://www.werewolf-ui.dev/components/button-group.md) - [Chart](https://www.werewolf-ui.dev/components/chart.md) - [Checklist](https://www.werewolf-ui.dev/components/checklist.md) - [CodeBlock](https://www.werewolf-ui.dev/components/code-block.md) - [Composer](https://www.werewolf-ui.dev/components/composer.md) - [ConversationList](https://www.werewolf-ui.dev/components/conversation-list.md) - [EmojiPicker](https://www.werewolf-ui.dev/components/emoji-picker.md) - [FileUpload](https://www.werewolf-ui.dev/components/file-upload.md) - [FilterBar](https://www.werewolf-ui.dev/components/filter-bar.md) - [GroupAvatar](https://www.werewolf-ui.dev/components/group-avatar.md) - [MessageActions](https://www.werewolf-ui.dev/components/message-actions.md) - [MessageBubble](https://www.werewolf-ui.dev/components/message-bubble.md) - [MessageList](https://www.werewolf-ui.dev/components/message-list.md) - [Navbar](https://www.werewolf-ui.dev/components/navbar.md) - [OtpInput](https://www.werewolf-ui.dev/components/otp-input.md) - [ResizablePanels](https://www.werewolf-ui.dev/components/resizable-panels.md) - [SortableList](https://www.werewolf-ui.dev/components/sortable-list.md) - [Timeline](https://www.werewolf-ui.dev/components/timeline.md) ### A command reports a conflict (`WW_CONFLICT`) A file the CLI wants to write differs from what it generated, usually because you or your agent edited it. Nothing was written. Compare the file, keep your change or move it aside, then rerun with `--overwrite` and that exact path. ```bash npx werewolf-ui add button --overwrite src/components/ui/button.tsx ``` ### Init cannot choose the app or package manager (`WW_PROJECT_AMBIGUOUS`) You ran it at a workspace root, or the project has several lockfiles, stylesheets or frameworks. Point it at the app and name the package manager. ```bash npx werewolf-ui init --cwd ./apps/web --package-manager pnpm ``` ### Init finds no import aliases (`WW_PROJECT_ALIAS`) Add a path alias to `tsconfig.json` (or `jsconfig.json`), for example `"paths": { "@/*": ["./src/*"] }`, then run init again. ### Init cannot place the CSS import (`WW_CSS_IMPORT`) Your app stylesheet needs exactly one `@import "tailwindcss";`. If you have more than one candidate stylesheet, name it with `--css`. ### `add`, `theme` or `tokens build` says the app is not initialized (`WW_NOT_INITIALIZED`) Run `npx werewolf-ui init` in the same directory first, or pass the same `--cwd` you used for init. ### A Tailwind class does nothing The token stylesheet clears Tailwind's palette, radius, shadow and font weight scales, so a palette class (a hue with a number), `rounded-lg` or `font-bold` produce no CSS. Use the token classes instead (`bg-accent`, `rounded-element`, `font-medium`). Lint reports these as `WW_CLASS_REMOVED`. ### Text on an accent button is invisible With the default accent, the dark mode accent equals the main text color. On `bg-accent` use only `text-text-on-accent` and `text-icon-on-accent`. Lint reports wrong pairs as `WW_SOLID_PAIR`. ### Dark mode styles do not apply Tokens switch with `data-theme`, so `dark:` variants are not used (lint reports `WW_DARK_VARIANT`). Dark is the default; set `data-theme="light"` for light. ### `npx wolf` runs something else `wolf` is an unrelated npm package. Always write `npx werewolf-ui`. The `wolf` alias exists only after a global install (`npm i -g werewolf-ui`). ### The MCP client shows no tools Check that the client can run Node 20+ and `npx`, that the `--cwd` path exists and is absolute, and that nothing else writes to stdout. Startup errors go to stderr, so look at the client's MCP log. ### Lint passes but the screen still looks wrong Lint reads static classes and styles only. Classes built at runtime are reported as `WW_DYNAMIC` warnings, not checked. Read `data.coverage` in the `--json` result, and keep class names whole in your code. ## Questions ### Do I need to know design? No. The design decisions are already in the tokens and the design skill. You pick an accent, a gray tint and a radius. ### Can I change one token by hand? Change the seed instead: the generator keeps every pair readable, which a hand edit cannot promise. If you need a role that no token covers, open an issue; a missing token is treated as a bug. ### Can I use the tokens without React or Tailwind? Yes. `tokens build` exports plain CSS variables, JSON, SwiftUI and Compose. The components need React 19 and Tailwind CSS v4. ### Do I have to use Tabler Icons? No. The docs and components use Tabler, but any icon set or icon font works. Follow the sizes on [Iconography](https://www.werewolf-ui.dev/docs/iconography.md). ### How do I update a component? Run `add` again with a newer CLI. Identical files are skipped and any file that differs reports a conflict, so you can review the change before passing its path to `--overwrite`. ### What is free and what is Pro? Tokens, components, the CLI and the MCP server are free under MIT. Pro is whole screens and large agent components, in pre-sale on the [Pro page](https://www.werewolf-ui.dev/pricing.md), with installation opening in January 2027. For Pro questions, write to support@werewolf-ui.dev. ### Where do I report a bug? Open an issue on [GitHub](https://github.com/joeynguyen1412/werewolf-ui/issues) with the command, its `--json` output and your framework.