Include the generated dist/mono.css stylesheet in your page or import it into your bundler.
Package scripts
After installing the local dependency, merge these entries into the scripts object in your application's package.json. Run npm run css:dev while editing and npm run css:build for production.
Creates mono.config.mjs if the file does not already exist.
--content '<glob>'
Sets a source pattern. Repeat to add patterns. Prefix a pattern with ! to exclude matches.
--output <path>
Sets the stylesheet path. Defaults to ./dist/mono.css.
--config <path>
Sets the config file path. Defaults to ./mono.config.mjs.
--minify
Produces compact CSS.
--watch
Rebuilds when source files or the config file change.
--help, -h
Prints help.
--version, -v
Prints the CLI version.
The default source patterns are ./index.html and ./src/**/*.{html,js,jsx,ts,tsx,vue,svelte,astro}. Mono supports *, **, ?, and alternatives such as {html,js}. Run commands from your project directory because relative paths resolve against the working directory. Quote glob patterns so the shell passes them directly to the CLI.
From the Mono checkout, build your HTML and JSX into one CSS file. The final content argument excludes archived components. Use --watch in place of --minify during development, or combine both flags.
The spacing scale uses increments of 0.25rem. For example, p-1 adds 0.25rem of padding, p-4 adds 1rem, and p-8 adds 2rem. Use the px token for 1px or a half step such as p-0.5.
Mono’s color palette uses OKLCH. The black, white, transparent, current, and inherit tokens are available individually. The red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, slate, gray, zinc, neutral, and stone families provide shades 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, and 950.
Add a variant prefix and a colon before a utility, as in hover:bg-emerald-700. Stack variants, as in md:hover:underline or dark:focus-visible:ring-2.
Breakpoints
Standard breakpoints apply from their minimum width. Use unprefixed classes for the base styles on smaller screens.
Prefix
Minimum width
sm:
640 px
md:
768 px
lg:
1024 px
xl:
1280 px
2xl:
1536 px
Use max-md: below the md breakpoint or specify a custom width with min-[900px]: or max-[1100px]:. The class md:max-lg:grid-cols-2 sets two columns from md up to the lg breakpoint.
starting:opacity-0 supplies a starting value through @starting-style
Text direction
ltr:text-left, rtl:text-right
Children and descendants
*:p-2 targets direct children and **:text-sm targets all descendants
CSS support
supports-[display:grid]:grid
Custom selectors
[&>a]:underline targets direct child links
When a component has multiple groups or peers, name both the marker and the variant. Pair group/menu with group-hover/menu:underline, or peer/opt-in with peer-checked/opt-in:block.
HTML
<label class="block">
<input type="checkbox" class="peer" />
Show note
<span class="hidden text-sm text-slate-600 peer-checked:block">
This note appears when you check the box.
</span>
</label>
Conditional styling with component data
Keep each possible class name in a literal string. This JSX example always includes the shared base classes, then appends the classes for the current state. Include the file in a content pattern.
Theme tokens. Use p-4, bg-slate-100, and rounded-xl to use theme values. Add your own tokens through theme.extend.
Arbitrary values. Use square brackets, as in w-[22rem], bg-[#f5f3ec], or grid-cols-[1fr_2fr]. The underscore in the last example becomes a CSS space.
Arbitrary properties. Use [property:value], as in [color-scheme:dark] or [--header-height:4rem]. Reference the custom property with h-[var(--header-height)].
Negative values. Add - before a utility that supports negative values, as in -mt-2, -translate-x-1/2, and -rotate-6.
Priority. Add ! before the utility name to apply !important, as in !block or md:!block.
Color opacity. Add a value after /, as in bg-slate-950/40 for a background at 40% opacity.
A custom grid proportion
Use an arbitrary property for the navigation width, then reference it from a custom grid template. The underscore between the tracks compiles to a space. On small screens the two regions stack vertically.
Use theme.extend to add or customize color, spacing, breakpoint, typography, radius, shadow, and animation tokens. Set content, output, and minify in the config file and override them from the CLI as needed.
Theme key
Token values
colors
CSS colors such as brand: '#252525' or a nested palette such as brand: { 500: '#252525' }
spacing, screens
Sizes such as 18: '4.5rem' or wide: '1680px'
fontFamily, fontWeight, fontSize
CSS font families, weights, and sizes. A size can include line height, as in ['1.25rem', '1.75rem'].
This config makes bg-brand, p-18, wide:grid-cols-4, and animate-appear available in templates. Set preflight to false if your project already has a CSS reset. With darkMode: 'class', dark:* applies to an element with the dark class or to one of its descendants. For example, set <html class="dark"> to enable dark mode for the page. By default, dark:* follows the system color preference.
Use the configured tokens
A color token maps to a color utility, and a screen token becomes a variant. With the configuration above, the grid gains four tracks at 1680px. The theme recipe shows the same color and animation tokens in a card.
Mono emits @keyframes for the 24 built-in presets and for configured animations when their classes are used. Use motion-safe: to respect the user’s reduced-motion preference.
The duration-*, delay-*, and ease-* utilities control CSS transitions. Prefix them with animate- to control the corresponding CSS animation properties.
This entrance animation runs for 500 ms after a 150 ms delay. The both fill mode applies the starting keyframe during the delay and keeps the final keyframe after the animation ends.
To add an effect, define theme.extend.keyframes and theme.extend.animation as shown in the configuration example. The animate-appear utility uses the appear animation token. The class animate-[appear_800ms_ease-out_both] sets the animation shorthand directly and uses the appear keyframes from the stylesheet.
In browsers that support scroll-driven animations, this example fades in the element as it enters the viewport. An auto duration follows the timeline range. The stacked variants check CSS support and the user’s motion preference.
extractCandidates(source) returns a Set of candidates found in the source text. compile takes an iterable of classes or a space-separated string of class names and returns a CSS string. defaultTheme contains the built-in tokens. If you installed Mono as a dependency, use import { compile, extractCandidates, defaultTheme } from 'mono-css'.
Compile a known class list
Save this as build-css.mjs in a project with the local Mono package installed. Run node build-css.mjs to write the output. Passing preflight: false emits just the requested utilities.
Filter the icon library by name and pack. Each result includes its SVG, source collection, and license. Use Copy SVG for inline markup or download the individual file for an image.
Pair an icon with a label
Copy an SVG into your component, keep its viewBox, and use currentColor for a stroke or fill that follows the surrounding text. An icon beside a visible label can use aria-hidden="true". Give an icon-only button an accessible name with aria-label.
Download any SVG, put it in your project’s assets directory, and reference it as an image. Use an empty alt attribute for an icon beside a label. Write a meaningful alternative when the icon carries information on its own.
To use local file imports across an app, install the optional icon package from the Mono checkout. Replace the path with the location on your computer. Vite includes assets referenced by your app in the build.
import cameraUrl from '@mono-css/icons/feather/camera.svg'
const camera = document.createElement('img')
camera.src = cameraUrl
camera.alt = 'Camera'
camera.width = camera.height = 24
document.body.append(camera)
The library links to the collections on SVG Repo and bundles versioned SVG files from their original projects. The interface icons come directly from SVG Repo’s Feather collection. License notices are available beside each icon. Icon credits and notices
Component recipes
For reusable, server-rendered components, open the Go component library. Each entry includes a live preview and the editable template.
Try the examples, then open the HTML and copy it into a file scanned by Mono. The theme card uses the configuration in Theme configuration. The other recipes use the default tokens.
Shape & space
Recreate the editorial spread from Features. Two CSS gradients draw the folded arch. The grid holds the artwork beside a serif headline and a short measure of body copy.
Shape & space.
Two columns, a folded arch, and a little breathing room. A study in contrast.
View HTMLspread.html
<article class="grid grid-cols-2 gap-4 border bg-white p-3 sm:p-5">
<div class="relative min-h-44 overflow-hidden bg-black"
role="img" aria-label="A folded arch of black and white lines">
<i class="absolute inset-x-[5%] top-[8%] bottom-0 rounded-[48%_48%_0_0]
[background:repeating-radial-gradient(ellipse_at_50%_100%,#eee_0_5%,#171717_5%_9.5%)]"></i>
<i class="absolute left-1/2 right-[5%] top-[8%] bottom-0 rounded-[0_100%_0_0]
[background:repeating-linear-gradient(143deg,#161616_0_7px,#eee_7px_13px)]"></i>
</div>
<div class="flex flex-col justify-center">
<h4 class="font-serif text-[clamp(1.8rem,6vw,4.5rem)] leading-[.9] tracking-tight">
Shape <em class="block">& space.</em>
</h4>
<p class="mt-3 max-w-[26ch] text-sm leading-relaxed">
Two columns, a folded arch, and a little breathing room. A study in contrast.
</p>
</div>
</article>
Responsive reading list
Use one track on a phone. From the small breakpoint (640px), the three articles share a row. Resize your browser to see the tracks change.
Combine a monospace label, serif heading, and restrained line length. The heading grows at the medium breakpoint.
Field notes
An architecture of light
A guide to working with natural light.
View HTMLHTML
<header class="max-w-lg">
<span class="font-mono text-xs uppercase tracking-wide">Field notes</span>
<h4 class="mt-2 font-serif text-3xl leading-tight md:text-4xl">
An architecture of light
</h4>
<p class="mt-2 text-sm leading-relaxed">A guide to working with natural light.</p>
</header>
Accessible form state
Tab to the checkbox and press Space, or select its label. A checked peer reveals the helper text. The label stays visible and the native input handles keyboard interaction.
Let the icon inherit the text color through its stroke. The visible label conveys the status, so the decorative SVG stays out of the accessibility tree.
Use this snippet with the theme configuration above. The brand token sets the background, the motion token supplies its entrance animation, and the dark variant changes the border color when a parent has class dark.
Theme preview
Colors and motion come from the project configuration.
View HTMLHTML
<article class="rounded-lg border border-black bg-brand p-4 text-white
dark:border-white motion-safe:animate-appear">
<h4 class="font-semibold">Theme preview</h4>
<p class="mt-2 text-sm">Colors and motion come from the project configuration.</p>
</article>
Expandable motion panel
Open the panel to run the entrance animation. The content remains available when the operating system requests reduced motion.
View build result
The stylesheet is ready.
View HTMLHTML
<details class="rounded-md border p-4">
<summary class="cursor-pointer font-semibold">View build result</summary>
<p class="mt-3 text-sm motion-safe:animate-slide-in-up motion-safe:animate-duration-300">
The stylesheet is ready.
</p>
</details>
Common questions
Why is a class missing from the stylesheet?
Check that the source path matches a content pattern and the class name appears as a complete string. Write each possible state as a literal or add runtime-generated names to safelist.
How do I style a component from JavaScript data?
Map each state to a complete utility string before selecting a value in your template. For example, use { ready: "opacity-100", pending: "opacity-50" }.
How does dark mode work?
By default, dark: follows the system color preference. Set darkMode: "class" and add class="dark" to the page root to control the theme yourself.
Can I use my existing CSS reset?
Set preflight: false in your configuration to generate utilities alongside your existing reset.
Which browsers can run the generated CSS?
Mono targets modern browsers with support for OKLCH, media query range syntax, and @property. Utilities such as animate-timeline-[view()] also rely on scroll-driven animation support. Use the supports-[…]: variant to apply a utility only when the browser supports the relevant CSS.