- CSS
- Architecture
- Design Tokens
How Hygular Organizes CSS Utilities, Components, and Theme Tokens
Understand Hygular’s CSS layers, design tokens, utility classes, and optional compiler workflow without confusing component styles with utility CSS.
A CSS framework becomes harder to maintain when every visual change needs a different override. A new brand color should not require hunting through each button, link, and form control. A page-specific layout should not require duplicating a component.
Hygular separates these jobs through theme tokens, base styles, component styles, and utilities. The separation is visible in the stylesheet, which makes it useful to understand before writing custom rules.
Tokens describe shared decisions
Tokens are CSS custom properties such as --primary, --body, --body-text, and --surface. Components reference them where shared values belong. An application can override those tokens in its own stylesheet.
: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);
}
These values are an example palette, not a contrast certification. Check the combinations actually used by your interface, including hover, focus, disabled, and dark states.
Changing a token affects the declarations that reference it. It does not override a component with its own explicit color, nor does it change every unrelated color in the application.
Layers make the cascade intentional
The core stylesheet separates theme, base, components, and utilities. The compiler can also emit configured additions in a custom layer.
For normal declarations in named layers, a later layer takes precedence over an earlier one before selector specificity is compared. Important declarations reverse layer precedence, and unlayered rules have their own position in the cascade. Layer order is therefore useful structure, not a reason to ignore how the cascade works.
Keep application overrides in a deliberate place. Loading unlayered application CSS after the framework is a straightforward option for token overrides, but broad selectors can affect more than the component you intended.
Components establish structure; utilities adjust composition
A component class such as button carries a reusable visual contract. A utility such as gap-3 handles a narrow layout property. They can be used together without pretending they serve the same purpose.
<section class="p-4 bg-surface rounded-2">
<p class="text-base leading-relaxed">
Review the settings before saving your changes.
</p>
<div class="is-flex gap-3">
<button type="button" class="button is-primary">Save</button>
<button type="button" class="button is-ghost">Cancel</button>
</div>
</section>
Typography utilities can set more than one property. In this version, text-small sets both font size and line height. Pairing it with leading-normal makes the intended reading rhythm explicit. The order of class names in HTML does not determine which CSS declaration wins; stylesheet order and the cascade do.
Start with distributed CSS
Most integration work can begin with one import:
import '@hygular/core/css';
This gives you the distributed stylesheet without setting up a scanner. It is a useful baseline when checking markup, component behavior, and application styling.
@hygular/core/css/source is a package export for the unminified distributed CSS. It is not a physical folder you need to create in your application.
Treat compilation as a separate decision
The optional @hygular/cli scans project files and builds a stylesheet from detected usage and its dependency rules. Use a CLI release that supports @hygular/core; the compiler is not bundled into the core runtime.
A scanner needs complete class names to make reliable decisions. If an application assembles class names from external values, declare the permitted complete names explicitly, including through the compiler's safelist where appropriate. Do not assume every runtime string can be inferred from source code.
Compiled output still needs testing. A file being smaller does not establish that every runtime state is covered. Check interactions that create markup, toggle state classes, or show content after initial rendering. Compare output sizes only after equivalent behavior has been preserved.
The compiler guide covers configuration. For the visual system itself, continue with theme tokens and dark mode.