Color Guidance

Overview

Morpha UI's color system is built on tonal palettes — Primary (purple #8265bd), Secondary (blue #536b9d), Error, Neutral and Neutral Variant — each with tones from 0 (white) to 1000 (black). From these tones we derive a set of semantic roles for light and dark themes.

The semantic layer follows Material-style (MD3) roles sourced from Figma — --primary, --on-primary, --primary-container, --secondary, --surface*, --on-surface, --outline, the *-fixed family, category colors and more — for richer, app-level surfaces. Generic base tokens (--background, --foreground) keep shadcn/Base UI components working; components consume the MD3 roles directly rather than the classic shadcn --card / --muted / --accent set.

Token Contract

Every color is exposed as a CSS custom property and, where useful, as a Tailwind color utility:

• Tonal scales → --primary-500 (raw) and --color-primary-500 (utility, e.g. bg-primary-500).
• Semantic roles → --primary / --color-primary (utility bg-primary), --surface, --on-surface, …

Tonal palettes are theme-independent; semantic roles change between :root (light) and .dark. Switch to Semantic roles in the generator below for the full light/dark table.

Interactive Generator

Set a primary and a secondary color — the tonal scales and the semantic roles all regenerate from your choice. Neutral Variant auto-tints to the primary hue (so outlines and muted foregrounds follow the brand); Neutral and Error stay fixed. Use Download global.css to grab a clean, themed stylesheet that reflects your selection.

Usage

1. Install the theme with the Morpha CLI — it writes the canonical token set (the full @theme inline + :root + .dark) directly into your global CSS (resolved from components.json → tailwind.css). By default it overwrites that file, keeping your @import lines; no manual @import needed, and re-running is idempotent:

   npmpnpmbun

   npx morpha-ui@latest add theme

   pnpm dlx morpha-ui@latest add theme

   bunx --bun morpha-ui@latest add theme

   Pass --primary <#hex> (and optionally --secondary <#hex>) to apply a re-themed palette, --merge to keep your existing CSS (theme goes in a managed block instead of overwriting), or --dry-run to preview without writing.

2. Use the tokens through Tailwind utilities (bg-primary, text-on-surface, bg-primary-500) or directly as variables (background: var(--surface)).

Because the semantic set matches shadcn's, components installed from the Morpha CLI inherit this theme automatically.