- Theming
- Dark Mode
- CSS
Hygular Themes and Dark Mode with CSS Custom Properties
Customize Hygular theme tokens, apply dark colors, and connect a theme button to DarkMode without rebuilding component styles.
A theme is more than a primary color. It includes surfaces, readable text, borders, link states, and the contrast between each control and its background. Dark mode adds a second set of relationships rather than simply inverting the first.
Hygular uses CSS custom properties for shared visual values. Its dark theme is selected through data-hygular-theme="dark" on the document root. CSS supplies the colors; the optional DarkMode API manages user preference and controls.
Begin with semantic values
Load the framework stylesheet and place your overrides in an application stylesheet. This example sets a small group of tokens for a green theme:
:root {
--primary: oklch(0.43 0.075 175);
--primary-contrast: oklch(0.99 0.005 160);
--body: oklch(0.98 0.006 160);
--body-text: oklch(0.24 0.025 175);
--surface: oklch(0.95 0.012 165);
}
[data-hygular-theme="dark"] {
--primary: oklch(0.79 0.065 165);
--primary-contrast: oklch(0.20 0.035 175);
--body: oklch(0.18 0.015 175);
--body-text: oklch(0.94 0.01 165);
--surface: oklch(0.25 0.025 175);
}
The palette demonstrates the override mechanism. It is not a complete token specification or a guarantee that every component state passes a contrast target. Review the tokens used by the components you ship, including accent colors, muted text, links, focus rings, and status messages.
A semantic token expresses a role. --surface describes a background used by an interface element; --primary describes an emphasis color. Keeping those roles distinct lets the theme change without replacing every class name.
Connect an existing theme button
If your layout already contains a theme control, bind it explicitly rather than asking the runtime to create another one:
<button id="theme-toggle" type="button" class="button is-ghost">
Toggle dark mode
</button>
Run the JavaScript after the button exists. Keep a stable label when using aria-pressed: the pressed state communicates whether dark mode is active.
The initial isDark() read matters because registering an onChange callback does not itself provide the current value. The controller restores a stored choice where available and considers the system preference when appropriate. Application controls should reflect the state chosen by the controller rather than assuming every first render is light.
CSS state and persisted preference are different
Setting the theme attribute manually changes the styling selected by CSS. It does not, by itself, perform all of DarkMode's preference handling or notify its callbacks.
Use one owner for theme changes. If your application already has its own theme manager, decide which code controls persistence, the root attribute, and event delivery. Mounting two independent managers can leave icons, storage, and visible colors out of sync.
In React, useDarkMode() provides lifecycle integration. If an icon is rendered from React state, read the initial theme and update that state through onChange; changing a document attribute alone does not update a React state variable.
Test transitions as well as screenshots
A light screenshot and a dark screenshot are useful, but they miss several common failures. Reload with a stored preference, toggle with the keyboard, navigate between pages, and inspect hover and focus states. Check whether the first paint matches the application's intended theme initialization strategy.
Readability should drive the palette. Muted text still needs to be legible, and a bright accent does not automatically make a good link or focus indicator on every surface. Test the rendered combinations rather than judging individual token values in isolation.
Hygular also uses modern color expressions in its stylesheet. Test the actual distributed CSS in your supported browsers; accepting a basic OKLCH value does not establish support for every relative color expression.
Continue with theme customization and compatibility. For the wider architecture, read how Hygular organizes CSS.