Colors in Monster
Monster uses a token-based color system that always thinks in pairs: foreground, background and, where needed, border. The goal is not to pick isolated colors, but to compose surfaces that stay readable in light mode and dark mode without manual corrections.
Design principle
Use Monster colors as semantic building blocks. theme classes already define a complete visual pair. The lower-level custom properties are there for layouts, custom shells and component-specific polish.
If you define a background, always define the matching foreground as well. That is the core rule for clean theming and the reason we avoid raw hex values in the documentation.
Prefer semantic pairs
Use monster-theme-primary-*, monster-theme-secondary-* or monster-theme-tertiary-* when you want a complete color decision in one class.
Use custom properties for composition
Use --monster-bg-color-*, --monster-color-* and --monster-color-border-* when you build custom shells, cards, callouts, split layouts or component wrappers.
Let dark mode do its job
Monster ships color tokens for both schemes. If you stay on the token layer, the same markup remains usable in light and dark mode without maintaining two separate palettes.
Contrast and accessibility
Readable contrast is a functional requirement, not decoration. Normal text should stay at least around 4.5:1; large or bold text should still stay around 3:1. The safest way to stay within that range is to use Monster theme classes or matching foreground/background token pairs.
That is also why the docs avoid examples that set only a text color or only a background color. Partial color decisions tend to break first in dark mode and under custom branding.
Theme classes
Theme classes are the fastest way to get a safe foreground/background combination. They are ideal for badges, notices, callouts, cards and demo blocks where you want a stable visual outcome with minimal CSS.
<div class="monster-theme-primary-1">Primary 1</div>
<div class="monster-theme-primary-2">Primary 2</div>
<div class="monster-theme-primary-3">Primary 3</div>
<div class="monster-theme-primary-4">Primary 4</div>div {
display: flex;
justify-content: center;
align-items: center;
text-align: center;
padding: 1rem;
}monster-theme-* is the preferred API for “give me a finished color treatment”.
Each class already defines the text color and the background together, which is why it remains stable across light mode, dark mode and downstream theming.
Theme palette
The theme palette is grouped by semantic families and intensities. Use it when a component or surface needs a ready-made visual treatment.
Working with token pairs
When you need more control than the theme classes provide, compose a surface from custom properties. In practice that means choosing a background token, its matching text token and optionally a border token from the same visual level.
Base surface
bg primary-1 + color primary-1 + border-2Highlighted section
bg secondary-2 + color secondary-2Status callouts
bg success-2 + color success-2bg warning-2 + color warning-2bg error-2 + color error-2.custom-shell {
background: var(--monster-bg-color-primary-1);
color: var(--monster-color-primary-1);
border: 1px solid var(--monster-color-border-2);
}
.custom-callout {
background: var(--monster-bg-color-secondary-2);
color: var(--monster-color-secondary-2);
}Combined colors
The examples below show typical combinations when you compose custom surfaces yourself. The important part is not the individual token, but the complete pair.
Border colors
Borders are supporting tokens. In most cases they should reinforce the depth or emphasis level of a surface, not compete with the content.
Do and don’t
Do
- Use
monster-theme-*for complete, safe color treatments. - Combine foreground and background tokens together.
- Use state families like
success,warninganderrorsemantically. - Keep borders on the same intensity level as the surrounding surface.
Don’t
- Don’t introduce raw hex colors into component docs when a Monster token exists.
- Don’t set only
coloror onlybackgroundfor custom shells. - Don’t use aggressive border colors where depth can be expressed with token levels.
- Don’t optimize only for light mode; always assume dark mode is active somewhere.
Practical default
If you need a neutral custom wrapper, this is the safest default:
background: var(--monster-bg-color-primary-1);
color: var(--monster-color-primary-1);
border: 1px solid var(--monster-color-border-2);Color properties
The complete token list is exposed through CSS custom properties. These properties are the foundation for custom theming, wrappers, shells and advanced component compositions. The table below lists the currently available Monster color variables.