Installation

Cadence ships two ways from the same source. Choose one for each project.

RequirementsCopy Anchor Link

• React 19
• Tailwind CSS v4
• A browser from the last two years: Chrome or Edge 111, Safari 16.4, Firefox 128, or later

Install the packagesCopy Anchor Link

pnpm add @cadence-clinical/ui

@cadence-clinical/ui brings in @cadence-clinical/tokens.

Import the stylesCopy Anchor Link

In your Tailwind entry stylesheet, import Cadence after Tailwind:

@import "tailwindcss";
@import "@cadence-clinical/ui/styles.css";

This one import loads the Cadence tokens and tells Tailwind to scan the compiled components for the classes they use.

Use a componentCopy Anchor Link

import { Button } from "@cadence-clinical/ui";

export default function Page() {
  return <Button>Save observation</Button>;
}

Install from the shadcn registryCopy Anchor Link

The registry copies component source into your project with the shadcn CLI. Your project needs a components.json, which shadcn init creates.

A component you install this way is yours to edit, and an edited copy carries no Cadence grade. Grades explains what a grade applies to.

1. Add the registryCopy Anchor Link

Add the @cadence namespace to components.json:

{
  "registries": {
    "@cadence": "https://www.cadenceclinical.dev/r/{name}.json"
  }
}

2. Add the theme by nameCopy Anchor Link

pnpm dlx shadcn@latest add @cadence/theme

This installs @cadence-clinical/tokens and imports its theme.css into your stylesheet. It also replaces the values shadcn init wrote to :root, .dark and @theme inline for the variables Cadence defines. Those stock values come after the import, so they would otherwise win in light mode. Variables Cadence does not define, such as --chart-1, are kept.

Run this command even though every component depends on the theme. The CLI replaces existing values only for an item you name. For a dependency, it adds what is missing and leaves the stock values in place.

Do not edit the values the theme writes. Set the theme attributes on <html> instead.

3. Add componentsCopy Anchor Link

pnpm dlx shadcn@latest add @cadence/button

Components install to components/cadence/, and the cn utility they share installs to lib/cn.ts. Nothing in your components/ui directory is changed, so a Cadence Button and a stock shadcn Button can sit side by side.

import { Button } from "@/components/cadence/button";

export default function Page() {
  return <Button>Save observation</Button>;
}

Each item the registry serves records the package version and the commit it was built from, under meta in its JSON. The registry follows the main branch, so it can be ahead of the latest npm release.

Work from the repositoryCopy Anchor Link

To run Cadence locally you need Node.js 22 or later and pnpm 11.

git clone https://github.com/cadence-clinical/cadence.git
cd cadence
pnpm install
pnpm build
pnpm dev

pnpm dev starts this site on port 3000 and Storybook on port 6006.