Theme Guidance

Treat foundational foreground and surface colors as a coordinated theme system. QP components often consume semantic Theme variables directly, so changing a container color or background does not necessarily recolor its descendants. When changing the document canvas or ordinary surfaces, review primary, strong, muted, inverse, and heading foregrounds together with ordinary, muted, hover, and overlay surfaces. Use local CSS for image-dependent overlay contrast, but do not rely on body color inheritance as a substitute for declaring the theme’s ordinary semantic color decisions.

Prefer modifying CSS properties directly over overriding QP variables within scoped selectors. Use scoped variable overrides when a change intentionally coordinates multiple descendant consumers or carries shared inherited context. For configurable color, size, spacing, and other design values, prefer an explicit alternate Theme variable applied by the selector.

Establish a theme’s visual identity through a small set of coordinated semantic Root decisions, then let their Derived and Inherited families carry that identity through QP components. Override child variables only when the child has a meaningful exception; inherited defaults are useful behavior, not unfinished work. Optional style.config.json owns intrinsic package identity and may add a human-facing name or explicit font-preload intent. Filesystem discovery remains directory-based and requires canonical style.css; resources and owner CSS derive from the package. Keep sparse variable decisions in theme.config.json. Use custom component or infrastructure CSS for composition, responsive art direction, imagery, and effects that cannot be expressed truthfully as reusable semantic variables. Do not restate Base mechanically or convert every CSS literal into a Theme variable.

Enums are available authored vocabulary, not a checklist every theme must use. Generated theme inspection derives active vocabulary transitively from the effective dependency graph and omits unused Base and theme-owned Enums automatically. Theme-owned Enums should represent intentionally reusable value vocabulary. Identity colors should enter components through semantic Roots and their families rather than direct Enum consumption.