Troubleshooting

Styles or behavior missing

1. Check the network panel: CSS and JavaScript should return successful responses.
2. Use CSS and JavaScript from the same pinned release. The repository does not publish an npm package.
3. Check that classes start with focus-. Load application overrides after the library.
4. Interactive controls need JavaScript; styling alone does not initialize them.

Styles conflict with another framework

Focus UI includes reset and base rules for native elements, so another framework's reset, form styles, or button rules can affect the same elements. Check computed styles and the cascade in browser developer tools. Load Focus UI CSS in a consistent order, then place narrowly scoped application overrides after it. Avoid combining two global resets unless you have checked their effects on forms, headings, and buttons.

Dynamically inserted content

Load the Focus UI browser script after the document markup (or use defer) so its automatic DOM-ready initialization can run. For declarative controls inserted later, call FocusUI.init() after insertion. Searchbar, Tables and TOC require explicit initialization. Keep the API returned by an initializer that provides one and call its destroy method before removing the component. Check console warnings for missing selectors.

const table = FocusUI.Tables.init('#projects')
// Before removing the table:
table?.destroy()

Dark theme does not appear

Check that the root element has data-focus-theme="dark" for a manual dark choice. FocusUI.Theme.set('auto') removes this attribute and follows the operating system's prefers-color-scheme setting; an absent attribute is therefore expected in auto mode. Use FocusUI.Theme.get() to inspect the saved mode and FocusUI.Theme.getEffective() to check whether auto currently resolves to light or dark. Focus UI stores the preference under focus-ui-theme in localStorage. If storage is blocked by browser privacy settings or an embedded context, theme changes still apply for the current page session but may not persist after reload.

Dialogs and tabs

A dialog uses .focus-modal-overlay around .focus-modal, with body/footer sections inside. Open the modal element, not an invented focus-modal-content wrapper. Tab buttons and panels match through data-tab; the value is not necessarily an HTML ID.

Copy button fails

Clipboard access depends on browser permissions and a secure context. Try localhost or HTTPS and inspect permission errors. A copy failure should not prevent reading or manually selecting the code.

Old files after an update

Inspect the versioned URL and response cache headers. Use immutable version paths for production. Replace downloaded assets together and change their versioned path; avoid year-long immutable caching for files you overwrite in place.