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)NeutralAccentSuccessWarningDangerInfo
graygrayirisgreenamberredblue
mauvemauvevioletgreenamberredblue
slateslateindigogreenamberredsky
sagesagetealgreenamberredblue
oliveolivelimegreenamberredblue
sandsandgoldgreenamberredblue
bronzesandtealgreenamberredblue
goldsandpurplegreenamberredblue
brownsandskygreenamberredindigo
orangesandindigogreenamberredblue
tomatomauvetealgreenambercrimsonblue
redmauvegoldgreenambercrimsonblue
rubymauvejadegrassambertomatoblue
crimsonmauvecyangreenambertomatoindigo
pinkmauvemintgrassamberredblue
plummauveirisgreenamberredcyan
purplemauvegoldgreenamberredblue
violetmauvepinkgreenamberredblue
irisslateplumgreenamberredsky
indigo (default)slateorangegreenyellowredcyan
blueslatepurplegreenamberredcyan
cyanslatevioletgreenamberredblue
skyslatepinkgreenamberredblue
tealsageorangegreenyellowredblue
jadesagerubygrassambertomatoblue
greensagegoldtealamberredblue
grassoliveyellowtealorangeredblue
mintsagepinkgreenamberredblue
limeolivevioletjadeamberredblue
yellowsandgreentealorangeredblue
ambersandirisgreenorangeredblue

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 override tokens.
  • 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-width and --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:

RoleUsed forDefault scale
neutralSurfaces, text, and bordersslate
primaryDefault buttons, links, focus, and selectionindigo
accent.accent variantsorange
danger.danger variants and invalid statesred
success.success variants and valid statesgreen
warning.warning variantsyellow
info.info variantscyan

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, and a2–a7.
  • Colored roles: 7, 9, 10, 11, a2–a7, a11, text, and inverse.

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-primary and --color-primary-text to var(--neutral-12), --color-primary-inverse to var(--neutral-1), and --mark-color to an accent value. The gray, slate, and other gray theme files show the complete set.
  • Danger and success: The --icon-invalid and --icon-valid form icons have their color embedded in the SVG. If you change these roles, copy the tokens from css/theme.css and replace the stroke color 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.

Footer