Troubleshooting

Troubleshooting consumption

Start by recording the theme version, consumption mode, framework/browser and exact error. These instructions target v1.1.0.

Installation and copying

Symptom	Check and resolution
npm cannot find @j3w1/ui@1.1.0	Use the published archive from Quick start. Archive release and npm registry publication are separate.
CLI is missing	Install in the app directory, use Node 24+, then npx --no-install j3w1-ui list. Check the install result.
CLI refuses the destination	Choose a new non-symlink directory. It deliberately does not overwrite existing application files.
Copy integrity failure	Obtain the same pinned archive again and compare it with its release manifest. Do not bypass checks.
A copied component is unstyled or inert	Keep tokens.css, component.css and the whole runtime/ directory; check registration and relative HTTP paths.
A kit did not create a Vue app	Kits provide components/contracts and guidance. Incorporate them into your own app; the framework flag is not an app scaffolder.
Package kit has no runtime files	Package mode expects the separately installed package. Use copy mode for full source bundles.

Rendering and framework integration

Symptom	Check and resolution
Vue warns about unknown j3w1-* components	Configure isCustomElement in the Vue SFC compiler as shown in Vue integration.
Empty custom tag renders nothing useful	Include the maintained native markup. Labels and inputs are not inferred.
Tokens load but controls look wrong	Load the matching component stylesheet; preserve canonical classes and check broad host resets.
Styles changed after an upgrade	Keep runtime, styles and tokens at one release. Review actual computed styles and the migration notes.
Server render fails while registering elements	Use class imports server-side; place registration in browser execution. Astro registers in a browser script.
Duplicate registration conflict	Remove the second implementation/version; do not overwrite the Custom Elements registry.
Browser cannot resolve a bare package import	Use a bundler or a complete HTTP-served copy bundle with relative ESM paths.
Modules fail after double-clicking HTML	Serve the example over HTTP instead of a file: URL.

Forms, choices and lifecycle

Symptom	Check and resolution
Native blue select popup still appears in the app	Load the 1.1.0 select component or enhanceControls(root) plus styles/controls.css after mount. See Themed controls. Static/no-JS fallback is intentionally native.
Required field name includes unexpected text	Preserve maintained label structure and visibility rules; verify the actual accessible name and required state.
Value is missing from FormData	Check native name, disabled/checked state and owning form. Unchecked checkboxes and disabled fields are not successful values.
FormData contains duplicates	Do not add a second hidden input for a control that already owns its native value.
disabled="false" remains disabled	Boolean attributes are presence-based. Remove the attribute or set the documented property to false.
Vue state does not follow the wrapper	Put v-model on the native input when Vue owns the value. The custom tag is not a Vue modelValue component.
Objects become strings	Bind the declared property, e.g. Vue .prop, or use a ref; do not serialize complex values into arbitrary attributes.
Changed native children behave stale	Await the framework DOM update and call the component's refresh(). Avoid two owners of the same child collection.
Reset conflicts with framework state	Choose explicit framework state ownership and reset it consistently. Test the native defaults/form reset path your app uses.
Focus is wrong after moving/remounting a view	Preserve stable identity, unique IDs and the app's focus recovery. Test the new mounted control rather than a removed element.
Date/time input is rejected	Use documented ISO date/time text and inspect min/max/step, required and read-only constraints.

Agent and mapping problems

If an agent used a branch, mixed versions or copied values from a screenshot, re-establish a single immutable pin and read the selected canonical exports. Do not hide the mismatch behind an invented approximation. use-and-report means disclose the pending IDs; it does not ask the agent to redesign that role.

If a host cannot express a required surface or focus rule, follow its supported API and record the limitation. A passing parser does not establish a real native import. See Ports.

Report a useful issue

Use repository issues and include component ID/variant, exact version and mode, framework/browser/OS, a minimal synthetic reproduction, expected versus actual behavior, and the relevant check or screenshot. Describe the integration's CSS order and dynamic lifecycle if relevant.

Do not include credentials, private form values, customer data or Figma ownership receipts. Keep the report scoped to the defect. See Verification for describing evidence without overstating it.