Styling and Theming

KatluxToolkit uses CSS Custom Properties (CSS variables) for modern, dynamic theming. This allows you to switch presets at runtime without reloading the page.

1. How Variables Work

Variables are defined in `assets/scss/css-variables.scss` within each preset folder. They are scoped using a `data-preset` attribute on the root element.

// presets/modern/assets/scss/css-variables.scss
[data-preset="modern"] {
  --primary-500: #8b5cf6;
  --background-color: #ffffff;
  // ... other tokens
}

2. Writing Variables

When creating styles for your components, always use the `var(--variable-name)` syntax instead of hardcoded colors or SCSS variables. This ensures your component automatically adapts when the preset changes.

.my-custom-element {
  background-color: var(--primary-500);
  border-radius: var(--border-radius-md);
}

3. Overwriting Variables

You can overwrite existing variables in your preset's `css-variables.scss` or even at the component level for specific overrides.

Preset Level Override

If you want to change the primary color for the entire `modern` preset:

[data-preset="modern"] {
  --primary-500: #ff00ea; // New vibrant pink
}

Component Level Override

You can also override variables for a specific component instance or class:

.special-button {
  --button-bg-primary: var(--accent-500);
}

4. Standard Design Tokens

KatluxToolkit provides a set of standard tokens that you should implement in your `css-variables.scss` for full compatibility:

• Colors: `--primary-XXX`, `--neutral-XXX`, `--success-color`, `--error-color`, etc.
• Typography: `--font-family`, `--font-size-md`, `--font-weight-bold`.
• Layout: `--layout-header-height`, `--layout-sidebar-width`, `--grid-gap`.
• Components: `--button-border-radius`, `--input-border-color`.