Skip to content
Primitiv home
Framework
Consumption mode
Search the docs

GET STARTED

Start here

Primitiv is a design system you can take in three different ways: as accessible behaviour with no styling, as finished components copied into your project, or as a Figma library. All three are built from one set of design tokens, so they agree with each other.

There are 63 components. Every interactive one follows its WAI-ARIA pattern, with full keyboard support. The colour palette is generated rather than picked, so its contrast is correct by construction. And the whole system scales between four density settings, which is what lets one set of components suit a dense dashboard and a roomy marketing page.

Which path is yours

Three ways in. You are not locked into the one you pick, and most teams end up using two.

You already have a design system, and want the behaviour.

Install @primitiv-ui/react. You get the keyboard handling, focus management and ARIA, with no styling to override. Your existing look stays exactly as it is.

You want components that already look finished.

Use the CLI. primitiv add button copies a styled component into your project as a file you own and can edit. This is the path most people want, and it is the default the docs assume.

You are designing rather than building.

Open the Figma library. It has the same components, built from the same tokens as the code, so what you draw is what gets built.

  • Already styled?

    Headless

    npm i @primitiv-ui/react

  • Want it to look finished?

    Styled

    primitiv add button

  • Designing, not building?

    Figma

    Open the Figma library

You can change your mind — most teams end up using two.

Install it

The fastest way in is a new project with everything already wired up:

$ npm create primitiv-ui@latest

To add it to an app you already have:

$ npm i -D primitiv-ui$ npx primitiv add button

That second command does the whole setup the first time you run it. It installs what it needs, writes a primitiv.json config, generates your token layer, and copies the Button component into your project.

If you only want the headless components, skip the CLI:

$ npm i @primitiv-ui/react

Your first component

After primitiv add button, you have a real file at src/components/button.tsx. Import it like anything else you wrote:

import { Button } from "@/components/button";
export function Save() {  return <Button onClick={save}>Save changes</Button>;}

Open that file. It is ordinary code, and it is yours. Change the padding, add a variant, delete a prop you will never use. Nothing upstream will overwrite it.

The headless version is the same component without the styling:

import { Button } from "@primitiv-ui/react";

Same behaviour, same accessibility, no CSS. You bring the look.

Where to go next