Getting Started
Customization
Customize Minium CSS without editing the library. Load a color theme, override tokens in your own stylesheet, and put project-specific styles in @layer project. Each section below builds on the previous one, so start with a theme and add overrides only where the theme does not fit.
Use a color theme
Minium ships 31 color themes. To use one, load its stylesheet after the core stylesheet:
<link rel="stylesheet" href="minium.min.css">
<link rel="stylesheet" href="themes/blue.css">
With npm, import the theme from the package:
import "@troennes/minium";
import "@troennes/minium/themes/blue.css";
Theme files are in dist/themes/, next to minium.min.css. Each file is 1.3–2.7 KB gzipped and works in light and dark mode. Each theme file declares the full layer order, so a theme wins over the defaults even if it loads before minium.css.
A theme is named after its primary color. It also sets a matching neutral (surfaces, text, and borders), an accent, and the status colors. The default theme is indigo, matching the Radix Themes defaults (indigo with slate). To keep the current look if the default changes in a later release, load themes/indigo.css explicitly.
All themes and their color scales
| Theme (primary) | Neutral | Accent | Success | Warning | Danger | Info |
|---|---|---|---|---|---|---|
gray | gray | iris | green | amber | red | blue |
mauve | mauve | violet | green | amber | red | blue |
slate | slate | indigo | green | amber | red | sky |
sage | sage | teal | green | amber | red | blue |
olive | olive | lime | green | amber | red | blue |
sand | sand | gold | green | amber | red | blue |
bronze | sand | teal | green | amber | red | blue |
gold | sand | purple | green | amber | red | blue |
brown | sand | sky | green | amber | red | indigo |
orange | sand | indigo | green | amber | red | blue |
tomato | mauve | teal | green | amber | crimson | blue |
red | mauve | gold | green | amber | crimson | blue |
ruby | mauve | jade | grass | amber | tomato | blue |
crimson | mauve | cyan | green | amber | tomato | indigo |
pink | mauve | mint | grass | amber | red | blue |
plum | mauve | iris | green | amber | red | cyan |
purple | mauve | gold | green | amber | red | blue |
violet | mauve | pink | green | amber | red | blue |
iris | slate | plum | green | amber | red | sky |
indigo (default) | slate | orange | green | yellow | red | cyan |
blue | slate | purple | green | amber | red | cyan |
cyan | slate | violet | green | amber | red | blue |
sky | slate | pink | green | amber | red | blue |
teal | sage | orange | green | yellow | red | blue |
jade | sage | ruby | grass | amber | tomato | blue |
green | sage | gold | teal | amber | red | blue |
grass | olive | yellow | teal | orange | red | blue |
mint | sage | pink | green | amber | red | blue |
lime | olive | violet | jade | amber | red | blue |
yellow | sand | green | teal | orange | red | blue |
amber | sand | iris | green | orange | red | blue |
Color scales come from Radix Colors. See Colors for every scale.
Understand the layers
Minium uses cascade layers, so your overrides do not need higher specificity. The layer order is:
@layer tokens, theme, reset, base, layout, components, project, utilities;
The layers that matter for customization are:
tokens: Library defaults. Contains the default theme's colors, the semantic color tokens, type scale, spacing, radii, shadows, and fonts.theme: Theme files and your own token overrides. Rules here overridetokens.project: Your project's classes and component overrides. Rules here override components, but not utilities.
Unlayered rules override every layer. Prefer the named layers so that utilities keep working on top of your styles.
Change tokens
Components read custom properties instead of fixed values. To change a token, redefine it in @layer theme. The following example changes fonts, widths, spacing, and corner radii:
@layer theme {
:root {
--font: "IBM Plex Sans", system-ui, sans-serif;
--font-mono: "IBM Plex Mono", ui-monospace, monospace;
--content-width: 72ch;
--main-width: 80rem;
--gap: var(--space-m-l);
--flow-space: var(--flow-space-loose);
--border-radius-s: 0.25rem;
--border-radius-m: 0.5rem;
--border-radius-l: 0.75rem;
}
}
The main token groups are:
--size-*: Type scale.--space-*and--gap: Spacing.--flow-space*: Vertical rhythm.--content-widthand--main-width: Layout widths.--border-radius-*,--border-width, and--shadow-*: Shape and depth.--color-*: Semantic colors, such as--color-text,--color-surface, and--color-primary.
Semantic color tokens can be changed one at a time. For example, the following rule darkens the primary hover color:
@layer theme {
:root {
--color-primary-hover: var(--primary-11);
}
}
To change a whole color, change its role instead, as described in the next section.
Change color roles
Semantic color tokens do not reference color names such as orange or blue. They reference seven roles, and each role holds the values of one color scale:
| Role | Used for | Default scale |
|---|---|---|
neutral | Surfaces, text, and borders | slate |
primary | Default buttons, links, focus, and selection | indigo |
accent | .accent variants | orange |
danger | .danger variants and invalid states | red |
success | .success variants and valid states | green |
warning | .warning variants | yellow |
info | .info variants | cyan |
Role tokens are named after Radix Colors steps, so you can copy values from Radix directly. Each role defines a fixed set of steps:
neutral:1,2,3,4,5,8,11,12, anda2–a7.- Colored roles:
7,9,10,11,a2–a7,a11,text, andinverse.
Each step uses light-dark() with the light value first and the dark value second. --<role>-text is the role's text color, and --<role>-inverse is the text color on the role's solid step 9 fill.
The following example replaces the primary role with Radix blue. The a3–a7 steps are omitted here for brevity, but your theme must define them:
@layer theme {
:root {
--primary-7: light-dark(#8ec8f6, #205d9e);
--primary-9: light-dark(#0090ff, #0090ff);
--primary-10: light-dark(#0588f0, #3b9eff);
--primary-11: light-dark(#0d74ce, #70b8ff);
--primary-a2: light-dark(#008cff0b, #1166fb18);
/* --primary-a3 to --primary-a7 */
--primary-a11: light-dark(#006dcbf2, #70b8ff);
--primary-text: var(--primary-11);
--primary-inverse: white;
}
}
Define every step of a role you change. If a step is missing, it keeps the default theme's value, and the role shows a mix of two colors.
Some scales need different settings:
- Bright scales (sky, mint, lime, yellow, and amber): Step 9 is too light for white text, and step 11 drifts toward brown or olive in light mode. Set
--<role>-text: light-dark(var(--neutral-12), var(--<role>-11))and--<role>-inverse: light-dark(var(--neutral-12), var(--neutral-1)). - Gray scales as primary (gray, mauve, slate, sage, olive, and sand): Step 9 of a gray is not a usable solid color. Set
--color-primaryand--color-primary-texttovar(--neutral-12),--color-primary-inversetovar(--neutral-1), and--mark-colorto an accent value. Thegray,slate, and other gray theme files show the complete set. - Danger and success: The
--icon-invalidand--icon-validform icons have their color embedded in the SVG. If you change these roles, copy the tokens fromcss/theme.cssand replace thestrokecolor with the new step 9 value.
To start your own theme, copy the closest file from dist/themes/ and edit its values. Theme files also include Display P3 values for wide-gamut screens. The P3 block is optional; without it, browsers use the sRGB values.
Add project styles
Do not modify Minium's component styles for project-specific changes. Change tokens first. If tokens cannot represent the design, add a component override to @layer project in your own stylesheet.
Project styles also include named blocks such as .hero, .pricing-comparison, and .product-card, reusable combinations of utilities, and wrappers around Minium primitives. Rules in @layer project override component styles without higher specificity, and utilities still apply on top.
The following project.css adds a hero block:
@layer project {
.hero {
--flow-space: var(--flow-space-loose);
padding: var(--space-xl);
background-color: var(--color-primary-fill);
text-align: center;
}
}
Load integration styles
Integration stylesheets style markup that third-party tools generate, such as Prism.js syntax tokens. Load only the integrations you use. See Integrations for the available stylesheets.