Skip to content
Monday Morning Monday Morning
⌘K

Design Tokens

Monday Morning is a black application. There is no light mode, no skins, no theme picker — one look, defined entirely by a token namespace in src/styles/tokens/. This page covers how that system works, and how the design-tokens plugin applies the same idea to your project’s design system.

One theme, two layers

Section titled “One theme, two layers”

The token namespace has two layers, and only one of them is for authoring against:

LayerShapeExampleAuthor against it?
Value scaleNumbered, describes a value--mm-ink-8, --mm-text-3, --mm-rule-7No
Semantic aliasNamed, describes a job--mm-surface-input, --mm-text-body, --mm-state-needsYes

The one rule: author against semantic aliases — never numbered scales, never raw hues, never a hex.

/* Do */
background: var(--mm-surface-panel);
color: var(--mm-text-body);
border: 1px solid var(--mm-rule);


/* Don't */
background: var(--mm-ink-2);      /* scale step, not a job */
color: var(--mm-signal);          /* raw hue */
border: 1px solid #1c1c1c;        /* raw hex */

Both render identically today. The difference is what happens next: swapping to a sanctioned alternate should change one line in the token file and nothing else. Every component that reaches past an alias to a scale step is a line someone has to find by hand later.

The scales

Section titled “The scales”
  • Ink (--mm-ink-0 through --mm-ink-12) — surfaces, darkest to lightest, from the true-black canvas up to meter wells. The steps are optical, not mathematical: they’re ordered but not evenly spaced, so arithmetic on them is meaningless.
  • Rules (--mm-rule-1 through --mm-rule-10) — every division in the app is a 1px line, never a shadow.
  • Text (--mm-text-1 through --mm-text-8) — bone white down to a hard contrast floor at #828282. Hierarchy is carried by brightness, so the ramp is load-bearing — but every step clears 4.5:1 on #161616, the lightest surface text ever sits on, and therefore everywhere. Steps 9–13 are deprecated and pinned to the floor.
  • Decoration (--mm-deco-*) — legitimately below the floor because nothing here is read: unlit meter segments, separator dots, spinner tracks. Deco tokens may never carry a word or a glyph.

Key aliases you’ll see throughout the app’s styles: --mm-canvas, the --mm-surface-* family, --mm-text-primary / --mm-text-body / --mm-text-label, --mm-rule / --mm-border-control, and --mm-bone — the brand white used for chrome and inverted fills.

Exactly two hues

Section titled “Exactly two hues”

Color is never decoration in Monday Morning — it is state, and nothing else. The system contains exactly two hues:

  • --mm-signal — warm. An agent needs you. Unmissable, and ideally one per screen.
  • --mm-running — cool. An agent is working. Calm, ignorable.

Everything else is greyscale. Sanctioned alternates exist for both hues (clay, ember, mint, and a monochrome build where state is carried by weight alone) — they swap whole-system, never mix.

The CI ratchet

Section titled “The CI ratchet”

scripts/check-design-tokens.mjs runs the design package’s checks as a CI gate on every PR — raw hex literals, leftover skin variables, transitions, non-zero radii, stray animations, rgba/opacity, blur, deprecated text steps, stray font families, and raw hue usage are all greppable violations.

The gate is a baseline ratchet: it records the existing violation count per check and fails only on regression — a count above baseline. The baseline only ever shrinks (--update lowers it and refuses to raise it), so migration happens surface by surface, and every rebuilt component ratchets the numbers toward zero.

One check is deliberately not automated: “one warm mark per screen” needs judgment. When a screen shows two signals, the question is not “which do we tone down” but “which of these is not actually blocked on a person” — that’s a review item, not a grep.

The token files themselves are ported verbatim from the design package and verified byte-identical against a port manifest. The one editable exception is a local aliases file, where a repo-added semantic alias lives until it earns a place in the design package upstream.

Your project’s tokens: the design-tokens plugin

Section titled “Your project’s tokens: the design-tokens plugin”

The same principle — agents should generate code against your real design system, not invented values — is available for your own projects via the design-tokens plugin (free tier).

Point it at any token JSON in your project — Style Dictionary output, a Tokens Studio export from your Figma workflow, or your own format — and:

  • Agents use your design system. The mm_get_design_tokens tool (listed in the core catalog) returns the full token structure, so generated code references your actual colors, spacing, and typography instead of plausible-looking substitutes.
  • Browse the library in the app. The plugin contributes a token-library page — every token, grouped by category, with search and filtering — rendered on the stage as a plugin page.
  • Generate descriptions. Optionally produce human-readable descriptions for each token so the library doubles as documentation.

The configured token file path lives per project at .mm/plugins/design-tokens/config.json; if no file is configured, mm_get_design_tokens returns a clear error telling you to pick one rather than guessing.

Section titled “Related”