Troubleshooting and FAQ

`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.

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

Components on this site that are newer than the published CLI:

• AttachmentPreview
• AvatarStack
• ButtonGroup
• Chart
• Checklist
• CodeBlock
• Composer
• ConversationList
• EmojiPicker
• FileUpload
• FilterBar
• GroupAvatar
• MessageActions
• MessageBubble
• MessageList
• Navbar
• OtpInput
• ResizablePanels
• SortableList
• Timeline

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.

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.

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.

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.

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, 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 with the command, its --json output and your framework.