Troubleshooting

A living list of symptoms and fixes. If you hit something not here, open an issue on GitHub.

Component previews are empty

Symptom: Library → Components → any component, but the preview iframe is blank.

Cause: The preview-host (:5179) isn't running.

Fix: In a second terminal:

npm run dev:preview-host

Reload the main app tab. The preview iframe will connect.

Edits don't appear in the preview

Symptom: You edit a token in the main app but the component preview keeps showing the old value.

Checklist:

1. Both dev servers still running? (npm run dev AND npm run dev:preview-host)
2. Open the iframe in its own tab via the Open in new tab link on the preview. Look at the bottom-right diagnostic badge:
   • ● tokens (green) — broadcast received; this is healthy
   • ○ placeholder (amber) — the postMessage handshake didn't complete

If you see amber, reload both tabs in order: preview-host first, then the main app. The handshake re-runs on iframe mount.

Dark mode looks like light mode

Symptom: Toggling dark mode in the top nav doesn't visibly change anything.

Possible causes:

• No darkReferences are set on the relevant semantic tokens. Tostada falls through to the light chain when no dark override exists — so identical-looking modes mean no overrides have been authored yet. See Library → Tokens → Semantic to add overrides.
• The preview iframe lost the dark-class broadcast. Toggle dark off and on in the top nav to re-broadcast.

Hot reload doesn't pick up file changes on WSL

Symptom: You edit a file but neither Vite server picks up the change.

Cause: Native filesystem watching doesn't work on WSL2 + Windows-hosted files.

Fix: Already handled — preview-host/vite.config.ts sets usePolling: true so changes are detected via polling on WSL. If it still misbehaves, restart npm run dev:preview-host.

"Cannot find module @tabler/icons-react" or similar

Symptom: A component preview throws a missing-module error.

Cause: A new component uses an npm package the preview-host doesn't have installed.

Fix: Install it in the preview-host workspace:

npm install --prefix preview-host <missing-package>

My library is gone

Symptom: You launch Tostada and everything is reset to the seeded defaults.

Cause: localStorage was cleared — incognito mode closed, "Clear site data" was clicked, browser sync clobbered the storage, or you switched browsers/profiles.

Fix: There's no recovery if you didn't export your library JSON. Going forward, export periodically as a backup.

Documentation tab shows stale content

Symptom: You edit a token, but the Documentation tab still shows the old value.

Cause: Browsers cache iframes more aggressively than top-level documents. Rare but possible.

Fix: A hard reload of the main app tab (Ctrl/Cmd + Shift + R) clears it. The Documentation tab regenerates on every render — there's no caching layer in Tostada itself.

The ZIP download fails

Symptom: You click Download ZIP on the Documentation page; nothing happens or the file is corrupt.

Cause: A browser extension is intercepting the download (uBlock, some ad-blockers misfire on Blob URLs).

Fix: Try in an incognito window with extensions disabled. If it still fails, open an issue.

Sync script fails

Symptom: npm run sync:shadcn errors out partway through.

Common causes:

• Network hiccup — the component registry is fetched from ui.shadcn.com. Re-run.
• Upstream registry has a new field shape — the sync script's parser may need an update. Report the error in a GitHub issue.

The script is idempotent — re-running picks up where the previous run failed.