Troubleshooting

Start with the first error and the smallest reproducible change. Keep your source revision, tool versions, command, and relevant error output together when investigating.

Installation does not finish

Check node --version and yarn --version against Getting started. Confirm the terminal is in the directory containing package.json.

If yarn install --frozen-lockfile reports a lockfile mismatch, verify that the manifest and lockfile came from the same snapshot. Do not regenerate the lockfile just to hide an unexplained mismatch. Network or package-download errors need their own resolution; a different command does not establish equivalent dependency versions.

If Vite or another package cannot be found, finish dependency installation before retrying its script.

The local page does not open

Use the URL printed by the running development or preview command. The chosen port may differ if another process already occupies the preferred port. Keep the server terminal open and inspect its output for startup failures.

If the dashboard appears but your edit does not, verify you changed the same source folder that the server is running. A preview server shows the last production build; rebuild before expecting new source changes there.

A route or menu item is wrong

Check both the Route in src/App.tsx and its to value in src/components/navigation/appNav.data.tsx. For parameterized detail pages, confirm the fixture ID exists. For incorrect submenu highlighting, inspect end and activePath rather than changing every navigation renderer.

If navigation works but a direct reload fails only after deployment, check the host's SPA fallback. If scripts or images fail below a subdirectory, review the asset base, router basename, and root-relative paths together. See Build and deployment.

Changes disappear after navigation

Most example records live in page-local state. Resetting after navigation or reload is expected until you connect application persistence. A successful demonstration toast is not proof of a database write.

Saved appearance settings are separate. If a changed theme or layout default does not take effect, inspect the relevant totem-* preference key for that browser origin. Clear only the key you need to reset.

Styling or controls look wrong

Verify src/main.tsx still imports src/assets/scss/root.scss. Check that your new SCSS partial is included by its index and that you edited source styles rather than generated output.

For a third-party control, preserve the documented compatibility hooks and upstream CSS imports. React Select needs its container class and class-name prefix. A Calendar or chart copied without its theme integration may render but look incorrect in another theme.

Use the matching docs/components/ guide in the source for integration-specific details. Check theme attributes on the document root before introducing a competing theme override.

Build fails after a change

Read the first TypeScript or Vite error. Check import paths, file-name casing, exported types, and newly required values. Run the most relevant test while fixing the issue, then run the full lint, test, and build checks.

For a bundle-budget failure, inspect which import or dependency expanded the output. Do not immediately widen the limit. For an unresolved browser problem, record the route, steps, viewport, theme, and console error so it can be reproduced.

A page is unfinished

A “Coming soon” page is not an installation failure. The development demo still contains unfinished routes and earlier Toumei branding. Use the implemented examples described in Adapt an app example as the starting points covered by this draft.