Installation

1Prerequisites

Your app needs a shadcn-initialized project on Tailwind v4. If you haven’t already, run pnpm dlx shadcn@latest init — it creates components.json, adds @import "tailwindcss"; to your CSS, and sets up the @/* path alias our components import through.

• Tailwind v4 with @import "tailwindcss"; in your CSS entry
• A @/* path alias (matching components.json aliases)
• React 19 / Next 16 (or compatible) and the lucide-react icon set

2Install straight from GitHub

There’s nothing to configure — no components.json entry and no token. The public repo is the registry: reference any item by its GitHub address, edgecom-ai/design-system/<name>, and the CLI fetches it plus everything it depends on. Pin to a branch, tag, or commit by appending #ref.

# address format — no config, no auth
edgecom-ai/design-system/<name>

# pin to a tag, branch, or commit
edgecom-ai/design-system/button#v1.0.0

3Add components

Add whatever you need — the theme comes with it. Every component depends on theme, so the first install automatically writes the OKLCH tokens into your globals.css and drops cn into lib/utils.ts. Cross-component dependencies, hooks, and package deps all resolve on their own — adding sidebar, for example, pulls its sub-components and the use-mobile hook too.

# theme + tokens ride along on the first component you add
pnpm dlx shadcn@latest add edgecom-ai/design-system/button edgecom-ai/design-system/card

# want just the tokens (no component)? add the theme on its own
pnpm dlx shadcn@latest add edgecom-ai/design-system/theme

Re-running is safe: files already present are skipped, so shared pieces like the theme and button are never duplicated. Pass --overwrite only when you mean to discard local edits.

4Build with semantic tokens — never hardcode

Every color is a token that tracks light/dark automatically. Use the utility, not the hex.

Token families: primary accent secondary muted success warning info destructive border ring chart-1…5 — each with a matching -foreground. See Foundations → Semantic colors.

5Compose with Base UI, not Radix

Our primitives are built on Base UI. Pass a trigger via the render prop — there is no asChild.

// ✅ Base UI — pass the trigger element via `render`
<DialogTrigger render={<Button>Open</Button>} />

// ❌ not Radix-style asChild
<DialogTrigger asChild><Button>Open</Button></DialogTrigger>

What’s inside

Browse the groups in the sidebar to preview every item in light and dark.