Introduction
Monogem is a token-based design system: a shared set of design tokens (color, type, spacing, radius, shadows, grids, layout, icons) and a library of accessible, composable components built on top of them, each one documented with the reasoning behind its decisions — not just what a value is, but why.
New here? Start with this page, then the Reading order below before opening a foundation or component page. This page covers what Monogem provides, how the documentation is organized, and where to go next.
How the documentation is organized
| Group | What's in it |
|---|---|
| Getting Started | This page, the Design Approach every other decision answers to, a UX Principles decision-support layer for product and component choices, and a Quality Heuristics craft-review layer. |
| Foundations | The token foundations, in build order — start at Scale. Each references the ones before it. |
| Components | One page per component, organized into four categories — Core, Containers & Overlays, Navigation & Feedback, and Composite & Advanced (browse them all on the Components page) — alphabetized within each, every page following a fixed template with a live, interactive example alongside the code. |
| Patterns | Cross-component composition guidance, not anchored to one component's page — for example Empty States, Search, and Navigation. |
Installation
Monogem is packaged for private consumption outside this repository, but it isn't published to
the public npm registry yet — there's no npm install monogem to run. Until public distribution
ships, install it from a local package archive:
Prerequisite: your project needs Tailwind CSS v4 configured and building before installing
Monogem. monogem/styles.css is a Tailwind v4 bridge (tokens, theme mapping, dark-mode variant),
not standalone CSS — without Tailwind v4 processing it, shipped components render unstyled. Use
whichever Tailwind v4 integration fits your stack (Vite, PostCSS, etc.).
# from the Monogem repository
npm run build:package
npm pack
# produces monogem-<version>.tgz
# in your consuming project
npm install /path/to/monogem-<version>.tgz
Import components from the package root, and load the token/style bridge once from your app's global stylesheet:
/* your app's global stylesheet */
@import "monogem/styles.css";
import { Button, Dialog, DialogContent, DialogTitle } from "monogem";monogem/styles.css brings in the Tailwind v4 bridge, Monogem's tokens, and the scoped CSS a few
components need (like Slider's range-input treatment) — Tailwind's own utility classes for the
shipped components' className strings are generated automatically once this import is in place.
React, React DOM (19+), and Tailwind CSS (v4) are peer dependencies — install and configure each
in the consuming project; Monogem doesn't bundle or auto-configure any of them.
Where the tokens live
Every token described in Foundations resolves to real values in the Monogem codebase: a
primitives layer holding the raw ramps (see Scale), and a semantic
layer holding the intent tokens components actually use (--primary, --border, --sidebar…),
defined for light and dark and, where a theme applies, per theme. See
Color for the theme model.
Where to start
- Design Approach — the five values that govern everything else.
- Foundations — read in order; each builds on the last.
- Components — reference the semantic tokens only, never raw values.
- UX Principles — reach for it when a decision needs evidence, not as linear reading.
- Quality Heuristics — reach for it at review time, to check whether the result feels deliberate.