UI diagnostics

Trace missing styles, invalid configuration, unknown tokens, contrast warnings, and theme runtime problems.

Start from the visible symptom

API / option	Type	Default	Behavior
`Components are unstyled`	`CSS loading`	—	Confirm the component comes from a public normal or /css entry point, not a source-internal path.
`Variables are missing`	`theme loading`	—	Enable `tavoUi`(), import `theme.css` once, or import one generated theme file.
`Missing theme config`	`plugin`	required: true	Create the default config, correct config path, or intentionally use required: false.
`Unknown --tui-* variable`	`validate-css`	—	Use the reported file, line, column, and same-group suggestions to replace the token.
`Contrast warning`	`theme audit`	AA	Adjust brand anchors or semantic overrides; enable `failOnViolation` when it must block builds.
`Mode does not persist`	`runtime`	—	Storage may be blocked. Switching still works for the current document by design.

Use theme audits and token metadata

tsimport { auditThemeA11y } from "@tavojs/ui/a11y";
import { getTavoUiTokenMetadata } from "@tavojs/ui/theme";

const themeAudit = auditThemeA11y(config);
const projectTokens = getTavoUiTokenMetadata(config);

Audit issues contain id, severity, message, and an optional target.
Theme issues are errors only when failOnViolation is enabled; otherwise they are warnings.
The theme audit checks generated contrast pairs, not rendered DOM or component-documentation metadata.
Token metadata includes built-in and config-defined tokens with CSS names and groups.