Start with the exact installed package version and the failing command. Compare your application target, config and CSS imports before replacing component source.
Components render without styles
Check that Tailwind CSS v4 is configured and imported before @frontfriend/tailwind/theme.css. Verify the Frontfriend Vite plugin or Next.js wrapper, then run:
npx frontfriend status
npx frontfriend init --forceInspect cache generation errors and restart the dev server if necessary. Do not paste a Tailwind v3 plugin into a v4 build or hand-edit cache CSS as a permanent fix.
The CLI cannot find the Design System
Run from the application root. Check that frontfriend.config.js exports the intended ff-id and uses the right module format. Confirm workspace access and complete frontfriend login if the operation requires authentication.
A downloaded component will not compile
Confirm React/Vue compatibility and the selected primitive. Install dependencies reported by the downloader. Verify the @/components/ui alias and any Icon or Spinner dependencies. An error about asChild, render or onPress often indicates an example from the wrong target.
A component is missing from the registry
Use a canonical route including framework and primitive. Check the package and registry versions; do not silently fall back to legacy source.
A token change does not appear
Check which source owns the property, whether the Design System version was saved and which version your application consumes. Refresh token cache and inspect the generated utilities. Overlapping Studio and configuration edits may need review while canonical authoring improvements are still in progress.
An overlay behaves incorrectly
Check the exact primitive’s composition. Preserve native trigger and dialog wrappers, accessible title and focus behavior. Test outside press and Escape, including when the overlay is nested.
Ask for help
Share the package version, framework/primitive, sanitized config, minimal reproduction and exact error with the Frontfriend team. Keep credentials and private Design System exports out of public reports.