# Theming Gears CSS Library provides a flexible and powerful theming system built on CSS Custom Properties (CSS Variables). This allows you to define multiple visual themes for your application (e.g., light, dark, high-contrast) and switch between them dynamically with ease. ## How Theming Works 1. **Base Tokens**: Your `css.config.json` defines a set of base design tokens (colors, space, radius, font) in the `tokens` section. These are generated as CSS Custom Properties under the `:root` selector in `src/settings/tokens.base.css`. ```css :root { --g-colors-primary: #0b76ff; --g-colors-text: #111111; /* ... other base tokens */ } ``` 2. **Theme Overrides**: The `themes` section in `css.config.json` allows you to define specific overrides for these base tokens for each theme. For example, a `dark` theme might redefine `--g-colors-primary` and `--g-colors-text`. ```css [data-theme="dark"] { --g-colors-primary: #66a6ff; --g-colors-text: #f2f2f2; /* ... other dark theme overrides */ } ``` These theme-specific overrides are generated into files like `src/settings/tokens.theme.dark.css`. 3. **Dynamic Switching**: By applying the `data-theme=""` attribute to your `` element, you activate the corresponding CSS rules. Since CSS Custom Properties cascade, the theme-specific values will override the base `:root` values for elements within that `data-theme` scope. ## Defining Themes in `css.config.json` To define or modify themes, edit the `themes` object in your `css.config.json`: ```json { "themes": { "light": { "colors": { "bg": "#ffffff", "text": "#111111", "primary": "#0b76ff" } }, "dark": { "colors": { "bg": "#0b0b0b", "text": "#f2f2f2", "primary": "#66a6ff" } }, "contrast": { // Example of a custom theme "colors": { "bg": "#000000", "text": "#ffffff", "primary": "#ffff00" } } } } ``` Each key under `themes` (e.g., `light`, `dark`, `contrast`) represents a theme name. Within each theme object, you can specify overrides for any of your defined `tokens` (e.g., `colors`, `space`, `font`). Only the tokens you wish to change for that specific theme need to be listed. After modifying `css.config.json`, run `npm run build` to regenerate the theme CSS files. ## Switching Themes Dynamically To switch themes in your application, you can use JavaScript to manipulate the `data-theme` attribute on the `document.documentElement` (which refers to the `` tag). ```javascript // Function to set a theme function setTheme(themeName) { document.documentElement.setAttribute('data-theme', themeName); // Optionally, save the user's preference to localStorage localStorage.setItem('theme', themeName); } // Function to remove the current theme (reverts to base tokens) function removeTheme() { document.documentElement.removeAttribute('data-theme'); localStorage.removeItem('theme'); } // Example usage: // Set the 'dark' theme setTheme('dark'); // Set a custom 'contrast' theme // setTheme('contrast'); // Revert to the default (base) theme // removeTheme(); // On page load, check for a saved theme preference document.addEventListener('DOMContentLoaded', () => { const savedTheme = localStorage.getItem('theme'); if (savedTheme) { setTheme(savedTheme); } }); ``` By following this pattern, your application can offer a seamless and customizable theming experience to users.