Overview

The Harmonica Design System is the shared visual foundation for every Harmonica surface. It ships as a single React library, @cdz/ui, plus this living documentation site.

What ships today

This is the foundation increment (Beat B-234). It covers:

• Design tokens — the shared settings that control color, typography, spacing, shape, and elevation. See Token Reference.
• Three brand themes + dark mode — Harmonica (sky), Verdant (emerald), Ember (amber). See Theming.
• Four core components — Button, Card, Badge, and Input. See Components.

Principles

• One source of truth. Every component reads from --cdz-* CSS variables, so a theme change re-themes the whole product without touching any screen.
• Token-driven plain CSS. No MUI or Tailwind at runtime — the library is portable across React 18 and React 19 apps.
• Pure renderers. Components take props and return JSX; they hold no business logic.

Use the theme switcher below — it re-themes every live example on this site: