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.