decocms / decocms-ui

decocms product design system (@decocms/ui)

React 19 components built on Radix primitives, styled with Tailwind CSS v4
semantic tokens. Light and dark themes work out of the box. Browse every
component and token at https://designsystem.decocms.com/

Install (new project)

bun add @decocms/ui react react-dom

Requirements: React 19 and Tailwind CSS v4 (bun add -d tailwindcss @tailwindcss/vite
plus the tailwindcss() plugin in vite.config.ts).

Make the design-system stylesheet the FIRST import of the app's CSS entry point —
it pulls in Tailwind itself, all tokens, and the bundled fonts (Inter + Commit Mono).
Do NOT also @import "tailwindcss" yourself:

@import "@decocms/ui/styles/global.css";

Tailwind only scans app source by default; if the app's classes come exclusively
from @decocms/ui components this already works — the package declares its own
@source.

Peers: install react-hook-form if you use the form component, and sonner
if you use toasts (sonner component). They are peers so the app and the design
system share one instance — never bundle a second copy.

Imports

No barrel export. Import each component from its subpath, extensionless:

import { Button } from "@decocms/ui/components/button";
import { Dialog, DialogContent, DialogTrigger } from "@decocms/ui/components/dialog";
import { cn } from "@decocms/ui/lib/utils";
import { useIsMobile } from "@decocms/ui/hooks/use-mobile";

Exception — inside the decocms/studio monorepo, workspace imports keep the
source extension: @decocms/ui/components/button.tsx.

Rules

1. Semantic tokens only, never raw palette. bg-primary, text-muted-foreground,
   bg-destructive, border-border — never bg-red-500 or text-zinc-400.
   Available color roles: background, foreground, card, popover, primary,
   secondary, muted, accent, destructive, success, warning, special
   (AI/highlight moments), brand, border, input, ring, sidebar-*
   (sidebar surfaces), chart-1..5 (data viz). Most roles pair with a
   *-foreground text token.

2. Dark mode is automatic via the .dark class on a root element — never
   hardcode colors or write dark: overrides that bypass tokens.

3. Compose, don't fork. Extend components with className + cn(); add
   variants through the component's cva config rather than wrapping with
   custom styles.

4. font-bold renders at weight 650 (custom scale); body text is 450.
   Radius scale derives from --radius (default 0.375rem).

5. User-facing copy comes from the app, passed as props — components ship
   only overridable English defaults.

Component inventory

• Forms: button, input, textarea, label, checkbox, radio-group, switch,
  slider, select, form (react-hook-form), input-otp, password-input,
  datetime-input, email-tags-input, multi-select, search-input, combobox,
  time-range-picker

• Overlays: dialog, alert-dialog, sheet, drawer, popover, hover-card,
  tooltip, command (palette), context-menu, dropdown-menu, menubar,
  responsive-dropdown, responsive-select (desktop/mobile adaptive)

• Feedback: alert, badge, progress, skeleton, spinner, sonner (toasts),
  empty-state, empty-state-illustrations

• Layout & navigation: card, separator, tabs, accordion, collapsible,
  breadcrumb, navigation-menu, pagination, scroll-area, aspect-ratio, table,
  sidebar (full app sidebar system), sidebar-footer-shell, app-topbar,
  topbar-switcher, user-menu, step-indicator

• Data & content: avatar, calendar, carousel, chart (recharts + chart tokens),
  markdown, entity-card, entity-grid, filter-bar, collection-search,
  view-mode-toggle, button-group, toggle, toggle-group

Before using a component, read its source in node_modules/@decocms/ui/src/components/<name>.tsx
(shipped in the package) to see its exact exports and props, or check its page
in the Storybook.

Icons

Components use @untitledui/icons (comes as a dependency). Prefer it in
consuming apps for visual consistency:

import { Plus, SearchMd, Trash01 } from "@untitledui/icons";