Styling and themes

Use the existing SCSS layers so a brand change reaches the interface consistently. Avoid editing generated CSS or files in node_modules.

Start with semantic settings

src/assets/scss/settings/_colors.scss contains raw color ingredients. settings/_semantic.scss assigns design meaning: fonts, foregrounds, backgrounds, and semantic colors. settings/_index.scss is the settings entry point.

For a first typography change, edit the existing $font-body or $font-heading value in _semantic.scss, then check headings, inputs, buttons, and tables. If you choose a new font family, arrange for the actual font to load; changing a family name alone does not provide font files.

Prefer a semantic setting when the same decision should affect multiple components. Keep a one-page spacing adjustment local or use a Bootstrap utility.

Understand compile-time and runtime values

SCSS settings are compiled during the build. Runtime light and dark values are defined in src/assets/scss/base/_theme.scss and selected through the document's theme attributes.

Use --totem-* custom properties for app-level concepts and --bs-* for Bootstrap-compatible UI. The Bootstrap adapter in src/assets/scss/bootstrap/ translates shared settings into Bootstrap values. Do not give a button, a chart, and a navigation item unrelated hard-coded versions of the same brand color.

For example, a local custom panel can use existing Bootstrap runtime values:

.workspace-note {
  color: var(--bs-body-color);
  background: var(--bs-secondary-bg);
  border: 1px solid var(--bs-border-color);
}

Add the rule to an appropriate application partial and include it through that folder's SCSS index. A file that is never imported will not appear in the compiled stylesheet.

Choose the right layer

• bootstrap/components/: overrides of Bootstrap components
• components/: Totems and application UI styles
• pages/: page-specific styles
• libraries/: third-party compatibility styles

The root stylesheet imports these groups. Library compatibility partials are collected in libraries/_index.scss; upstream CSS loading varies by integration. Follow the matching source component guide instead of importing every dependency stylesheet a second time.

Preserve chart behavior

Chart theme helpers live in src/assets/themes/, with separate helpers for Chart.js, ECharts, and Recharts. The shared useChartRuntimePreferences() hook in src/components/charts/ supplies theme and reduced-motion information.

When adapting a chart, keep its native library API and the matching theme helper. Changing only the chart background can leave labels, grid lines, or tooltips unreadable after a theme switch.

Review the result

Check light and dark content, independently themed menus and headers, focus outlines, disabled controls, validation feedback, and hover states. Try narrow layouts and reduced motion. Color contrast needs to hold on the actual rendered background, including translucent surfaces.

Run lint and build after SCSS changes. A clean compile catches syntax and import problems; it does not replace visual and keyboard checks.