@camunda/design-system

Camunda's AI-first design system. React components built on shadcn/ui with Radix UI primitives and Tailwind CSS v4.

v0 — public API subject to change. Under active development; minor versions may introduce breaking changes before 1.0.

Claude Code plugin

Install once to get AI agents for building UI, adding components, and migrating from Carbon:

1. Open the plugin manager: /plugins
2. Marketplaces → Add → enter camunda/design-system → confirm
3. Discover → find camunda-design-system → Install
4. Choose user scope

No configuration needed — agents auto-detect the DS package via components.json.

Update notifications are built in: a banner appears at session start whenever a newer plugin version is available. To apply the update, open /plugins and click Update on the camunda-design-system tile.

| Task | How | | ------------------------------------ | ------------------------------ | | Build UI from existing DS components | Describe what you need in chat | | Add or modify a DS component | /camunda-design-system | | Migrate a file from Carbon | /migrate <file> | | Migrate a directory | /migrate <dir> --bulk |

→ Getting Started: your first task in 2 minutes

Manual setup

Install

npm install @camunda/design-system react react-dom

Peer dependencies: React 19, Node ≥ 24. @carbon/react is an optional peer dependency — only needed if migrating from Carbon Design System.

Quick start

Add the CSS import and wrap your app root with <C4Provider>:

// index.tsx / main.tsx
import "@camunda/design-system/styles.css";
import { C4Provider } from "@camunda/design-system";

createRoot(document.getElementById("root")!).render(
  <C4Provider>
    <App />
  </C4Provider>,
);

Then use components anywhere in your tree:

import { Button } from "@camunda/design-system";

export function Example() {
  return <Button variant="default">Click me</Button>;
}

<C4Provider> establishes the .c4-ui CSS scope that design tokens and Tailwind preflight require. Place it at your app root — as high up as possible.

What's included

Components (src/components/ui/) — 28 shadcn/Radix UI primitives (Button, Input, Dialog, DataTable, TreeView, ComboBox, and more), each with:

• TypeScript + Tailwind CSS implementation
• .specs.ts machine-readable contract (drives AI authoring and Storybook docs)
• Storybook story with documented variants

Design tokens (src/index.css) — CSS custom properties scoped under .c4-ui: colors, radius, shadows, typography aligned to Camunda's brand identity.

Using Geist without the npm package

The npm package bundles Geist Sans in dist/files/. Surfaces that can't install the package, such as the Auth0-hosted SaaS login page, can load the same font from https://fonts.camunda.io/geist-font/Geist/webfonts/. Don't use Google Fonts. The host has CORS open (access-control-allow-origin: *) and serves Geist Version 1.800, the same version the package ships.

@font-face {
  font-family: "Geist Sans";
  font-style: normal;
  font-display: swap;
  font-weight: 400;
  src: url("https://fonts.camunda.io/geist-font/Geist/webfonts/Geist-Regular.woff2")
    format("woff2");
}
@font-face {
  font-family: "Geist Sans";
  font-style: normal;
  font-display: swap;
  font-weight: 500;
  src: url("https://fonts.camunda.io/geist-font/Geist/webfonts/Geist-Medium.woff2")
    format("woff2");
}
@font-face {
  font-family: "Geist Sans";
  font-style: normal;
  font-display: swap;
  font-weight: 600;
  src: url("https://fonts.camunda.io/geist-font/Geist/webfonts/Geist-SemiBold.woff2")
    format("woff2");
}
@font-face {
  font-family: "Geist Sans";
  font-style: normal;
  font-display: swap;
  font-weight: 700;
  src: url("https://fonts.camunda.io/geist-font/Geist/webfonts/Geist-Bold.woff2")
    format("woff2");
}

Keep the family name "Geist Sans" so it matches --font-sans. The hosted files are the full upstream fonts, not the latin subset the package ships, and they're uploaded by hand. When the geist dependency is bumped (see scripts/build-fonts.mjs), ask SRE to re-upload the matching release (camunda/team-sre#2052).

Carbon adapter (carbon-compat/) — transitional wrappers for teams migrating off @carbon/react. Each adapter is @deprecated from birth and removed once consumers migrate.

Storybook — live component browser at camunda.github.io/design-system. Run locally with npm run storybook.

PR previews — add the deploy-preview label to a PR to publish its Storybook at camunda.github.io/design-system/pr-preview/pr-<N>/. A bot comment posts the link, later pushes republish it, and closing the PR removes it. Previews are unlisted but publicly reachable.

Reporting issues & requesting features

Use GitHub Issues to report bugs or propose new components and enhancements.

| What | Template to use | | ------------------------ | --------------------------------------------------------------------------------------------------- | | Something is broken | Bug report | | New component or variant | Feature request |

Before opening an issue:

• Search existing issues to avoid duplicates.
• For quick questions or informal requests, ping us on Slack at #design-system first.

All new issues are triaged by the DS team and added to the AI-first Design System board. Expect an initial response within one business day for urgency:immediate issues.

Contributing

Developer setup

Prerequisites: Node 24+, npm 10+.

git clone https://github.com/camunda/design-system
cd design-system
npm install

npm run storybook       # component browser at localhost:6006
npm run typecheck       # TypeScript validation
npm run build           # compile to dist/

Adding a component

Open Claude Code in this repo and describe the component. Agents route automatically:

no .specs.ts found   →  Spec Author agent (drafts the contract)
spec exists, no .tsx →  Dev agent (implements + stories)
both exist           →  Validator agent (PASS / WARN / FAIL report)

Sequence: Spec Author → human review → Dev → Validator → PR.

Full agent reference: AGENTS.md.

Releasing a new version

Agents write changesets automatically as part of PRs. If you implement a change yourself:

npx changeset    # interactive: pick patch / minor / major + one-line description

Once changesets accumulate on main, the bot opens a "Version Packages" PR that batches all bumps. Merging it publishes to npm and creates a GitHub Release.

→ Full release guide

Releasing a plugin update

Plugin agents, skills, and scripts are versioned independently of the npm package — no changeset needed, no npm publish.

Version bumps are automatic: the pre-commit hook detects staged changes to agents/, skills/, or plugins/camunda-design-system/ and runs a patch bump automatically. No manual step required for routine changes.

To bump minor or major manually (new agent added, breaking API change):

npm run version:bump-plugin minor   # or major

| Type | When | | ------- | -------------------------------------------------------- | | patch | Prompt tweaks, script fixes, copy corrections — auto | | minor | New agent or skill added | | major | Breaking change to agent API or plugin structure |

CI will block plugin-file changes that lack a version bump — add label skip-plugin-version to bypass when intentional.

Before every PR

npx tsc --noEmit -p tsconfig.app.json   # zero errors required
npm run build-storybook                  # docs page must render

Full checklist: AGENTS.md — Verification gate.

License

Apache-2.0 — see LICENSE.