CSS and plugin reference

Understand compiled component styles, project theme generation, SSR injection, file output, watching, and CSS cascade behavior.

Configure every tavoUi option

Option	Default	Behavior
`config`	`tavo-ui.config.json`	Theme config path, relative to app root or absolute.
`out`	`false`	Optional physical CSS output path.
`watch`	`true`	Watch config and trigger a full development reload.
`silent`	`false`	Suppress generation info and contrast warnings.
`required`	`true`	Throw when the theme config does not exist.
`inject`	`true`	Inject the virtual theme import into project source.

Follow theme CSS through a build

At build start, the plugin reads JSON, resolves the theme, validates it, and creates the virtual @tavojs/ui/theme.css module.
With inject enabled, it prepends that import to project JavaScript and TypeScript source modules.
It excludes dependencies, build output, and Tavo.js or Vite configuration files.
An existing theme import is detected and not duplicated.
During SSR, the Tavo.js plugin document hook emits generated CSS as the tavo-ui.theme style record.
During development, a config change regenerates CSS, invalidates the virtual module, and requests a full page reload.

Write physical CSS only when another tool needs it

Set out to write the generated CSS to a project path in addition to virtual delivery. The plugin creates parent directories and skips the write when file content is unchanged.

tstavoUi({
  out: "src/theme/generated/tavo-theme.css",
  inject: false
})

Work with the public cascade layers

The layer order is tavo-ui.theme, tavo-ui.components, then tavo-ui.overrides.
Published component rules occupy the components layer.
Generated sx rules occupy the overrides layer and therefore beat normal component defaults without !important.
Project classes outside a layer participate in the browser's unlayered cascade and can override layered declarations.
Avoid internal CSS module names and DOM nesting; use public props, sx, semantic variables, or a project class on the documented public root.

Reuse style records across SSR and hydration

Dynamic sx rules register through the framework-wide Tavo.js style runtime when it is available.
Server rendering collects those rules and emits deterministic data-tavo-style IDs.
Client initialization scans hydrated style records once per document and deduplicates later registrations.
Styles requested for cleanup remain connected while mounted components retain them.
The fallback client runtime inserts styles directly into document head when no framework style runtime is active.