Most changes need no build: override a CSS variable in your own stylesheet. When you need a different bundle (fewer modules, another theme, a scope), use the CLI or the integrations.
Every value that matters is a --pico-* custom property, declared on :root. Override it after the Pico stylesheet:
:root {
--pico-border-radius: 0;
--pico-font-family: Georgia, serif;
--pico-spacing: 0.75rem;
}Overrides can sit on any element and apply to its subtree:
article.compact {
--pico-spacing: 0.5rem;
--pico-form-element-spacing-vertical: 0.5rem;
}The tokens are in src/tokens/ (core.css for fonts, spacing, radius and sizes, scheme.css for colors) and in the module that owns a component, for example --pico-modal-overlay-background-color in src/components/modal.css. The names are the same as in v2.1.1. The full OKLCH palette is in css/pico.colors.css (--pico-color-azure-550 and so on) together with the .pico-color-* and .pico-background-* classes.
The root font size is 100% (16px) and steps up once, to 106.25%, from 1536px. responsiveTypography: false (--no-responsive-typography) keeps it at 100% everywhere. Controls are 42px tall at the default size.
--pico-border-radius (0.5rem) rounds controls and code blocks. --pico-card-border-radius (1.5 times that) rounds cards, menus, dialogs, alerts and toasts. Set both to 0 for square corners.
The sans-serif stack starts with Inter, but Pico Reforged ships no font. When the page loads Inter it is used, otherwise the stack falls through to Segoe UI Variable on Windows 11 and the system font elsewhere. To pair with Inter, install @fontsource-variable/inter and import it before Pico:
@import "@fontsource-variable/inter";
@import "@rusticstack/pico-reforged";In the dark scheme each raised surface is a little lighter than the one under it, so edges show without heavy borders. The steps are OKLCH lightness on a near-neutral blue grey (hue 265):
| Surface | Token | Lightness |
|---|---|---|
| Page | --pico-background-color |
0.165 |
| Field | --pico-form-element-background-color |
0.195 |
| Card | --pico-card-background-color |
0.205 |
| Code | --pico-code-background-color |
0.215 |
| Card header and footer | --pico-card-sectioning-background-color |
0.225 |
| Menu, dialog, toast | --pico-dropdown-background-color |
0.235 |
| Borders and hairlines | --pico-muted-border-color and friends |
0.29 to 0.32 |
When you change one, keep the order, or a card can end up darker than the page.
Every Pico rule is inside the pico layer, in this order:
@layer pico.tokens, pico.theme, pico.core, pico.extras, pico.utilities;Tokens come first, the theme after them, then every component, then the extras, then the color utilities. CSS you write outside a layer always beats all of it, whatever the selector weight, so you never need !important or a more specific selector:
button {
text-transform: uppercase;
}To keep your own rules organized, put them in a layer declared after Pico:
@layer app {
button {
text-transform: uppercase;
}
}A rule in an unlayered block beats a rule in @layer app, and @layer app beats pico. You can also add rules to a Pico layer, for example @layer pico.core { ... }, when you want the usual cascade between modules.
Pico selectors use :where() in many places to keep specificity low. If one of your rules does not win, check that it is not inside an earlier layer.
There are 20 themes: amber, azure (the default), blue, cyan, fuchsia, green, grey, indigo, jade, lime, orange, pink, pumpkin, purple, red, sand, slate, violet, yellow and zinc. A theme only sets the primary tokens: --pico-primary, --pico-primary-background, --pico-primary-underline, --pico-primary-hover, --pico-primary-hover-background, --pico-primary-focus, --pico-primary-inverse, --pico-text-selection-color and --pico-switch-thumb-box-shadow. The neutral colors are shared.
Use a ready-made file, css/pico.jade.min.css, or build one:
pico-reforged build --theme jade --minify --out public/pico.cssThe compiler builds a 19-step scale from one color, using the lightness curve of the azure scale, then maps the steps like a built-in theme. Text on the primary color is black or white, whichever has more contrast.
pico-reforged build --theme "#e5484d" --minify --out public/pico.cssIn a config file the same is theme: { color: "#e5484d" } or theme: { hue: 25, chroma: 0.19 } (OKLCH hue in degrees, chroma from 0 to 0.5). In a stylesheet with the Vite or PostCSS integration it is @pico { theme: "#e5484d"; }. A theme can also be the path of a CSS file: the default theme is used first, then your file, so you only write the tokens you change.
Without a build, derive the primary tokens from one color with relative color syntax. examples/custom-theme.html does this:
:root,
[data-theme] {
--brand: oklch(0.62 0.19 25);
--pico-primary: light-dark(oklch(from var(--brand) 0.5 c h), oklch(from var(--brand) 0.75 c h));
--pico-primary-background: oklch(from var(--brand) 0.5 c h);
--pico-primary-inverse: oklch(1 0 0);
}Relative color syntax needs Chrome and Edge 119, Firefox 128 or Safari 16.4, so it is newer than the Chrome and Edge 111 floor. On Chrome and Edge 111 to 118 the example above is ignored and the theme falls back to the built-in colors. light-dark() in your own CSS is native from Chrome 123, Firefox 120 and Safari 17.5. Below that, the CLI theme is the safer choice, because the compiler lowers light-dark() for the floor and your own stylesheet is not compiled.
The default is color-scheme: light dark, so the page follows the system. Colors are written once with light-dark(). To force a scheme, set data-theme on html or on any element:
<html data-theme="dark"></html>
<section data-theme="light">...</section>data-theme only sets color-scheme, and the color tokens are recomputed inside that element, so a light card on a dark page works. To let users switch, toggle the attribute in a script and keep it in localStorage.
The conditional files style only what is inside .pico, and leave the rest of the page to your own CSS or another framework:
<link rel="stylesheet" href="css/pico.conditional.min.css" />
<main class="pico">...</main>For another selector, build it: pico-reforged build --scope .docs --minify --out docs.css. :root and html rules, the *, body and .container rules and the .modal-is-* classes on html stay global, as in v2.1.1.
pico-reforged build writes one stylesheet. Combine the options you need:
pico-reforged build \
--theme "#e5484d" \
--exclude components/modal,forms/input-range \
--extras tabs,badge \
--minify \
--out public/pico.css| Flag | Effect |
|---|---|
--entry classless |
the classless build (pico, classless, colors, extras) |
--no-classes |
drop every selector that needs a class |
--semantic-container, --fluid |
style body > header, main, footer as a container, full width |
--scope <selector> |
prefix every rule |
--exclude <list> |
leave modules out, see pico-reforged modules |
--extras <list> |
add extras, or all, see pico-reforged extras |
--responsive-spacings |
scale spacings with the viewport |
--no-responsive-typography |
keep the root at 100%, without the step to 106.25% from 1536px |
--no-transitions, --no-important |
remove motion, strip !important |
--targets <query> |
browserslist query or modern, default is the browser floor |
Put the same options in pico.config.json, or a pico.config.ts that exports them, and run pico-reforged build. The compiler is also a function: import { compile } from "@rusticstack/pico-reforged/compiler".
Paths inside a config file (a theme CSS file, extrasDir, the purge.content globs) are relative to the folder of the config file, so pico-reforged build --config site/pico.config.json works from any folder. Paths given as flags (--theme ./brand.css, --purge "dist/**/*.html") are relative to the working directory.
Excluding a module also drops the custom properties that only it used. Tokens that the prebuilt extras in css/extras/ read stay, so those files still work next to the smaller build.
Purging removes the rules your pages cannot use. Three ways to do it:
- With the Vite or PostCSS integration,
@pico { purge: safe; }is the default in production. It drops a rule only when a class, an id or an attribute name it needs is not in your sources.purge: aggressivealso judges tag names and attribute values, andpurge: offturns it off. Add run-time names with@source inline("name")orsafelist. See integrations. - With the CLI, on a build:
pico-reforged build --purge "site/**/*.html" --safelist modal-is-open. This judges tags and values too, so list anything a script adds.--purge sitereads every file in the folder. When no content file can be read, the build fails instead of writing an almost empty stylesheet. - On a built site,
pico-reforged purge publicrewrites the Pico rules in the CSS files of the folder, insafemode unless you pass--mode aggressive. Use--dry-runfirst.
Custom properties are never purged, and rules outside the Pico layers, which are your own, are never touched.