Theming

ShockStack ships with multiple built-in themes through semantic tokens and a root theme attribute.

Theme Model

The system has three parts:

  1. token-generated CSS variables for each theme
  2. root data-theme attribute to activate a theme
  3. semantic utility classes that consume token values

Because components use semantic classes, theme changes do not require component rewrites.

Theme Resolution

Theme selection follows this order:

  1. saved user preference
  2. system color preference
  3. project default

Set the theme attribute before first paint to avoid flashing the wrong theme.

Using Theme-Aware Utilities

Use semantic utilities for backgrounds, text, accents, and borders.
Avoid hardcoding hex values in components when a semantic token exists.

Accessibility Notes

  • Ensure color contrast remains acceptable in both themes
  • Respect reduced motion preferences for animated transitions
  • Validate focus and interactive states across themes

Extending Themes

To add a new theme:

  1. add token values for the new palette
  2. include it in token build output
  3. update theme selection UI/logic
  4. verify all semantic utilities render correctly