Skip to main content
Clementine DS is a pnpm + Turborepo monorepo with two publishable packages — @clementine-ds/ui and @clementine-ds/tokens — plus a Storybook app and a specs/ directory that holds the machine-readable contracts for every component. The steps below take you from a fresh clone to a running component and a passing spec validation.
1

Clone and install

Clone the repository and install all workspace dependencies with pnpm. Node 18 or newer is required.
This installs four workspaces:
2

Run Storybook

Start the local Storybook dev server to browse every component and all of its interaction states:
Every story binds exclusively to component-tier tokens — no hex values, no raw primitives. Open any story’s Controls panel and inspect the theme to see the token names in action. The live deployment is also available at clementine-ds-storybook.vercel.app if you prefer not to run it locally.
3

Wrap your app in ClementineDSProvider

ClementineDSProvider injects the Clementine Mantine theme and the CSS variables resolver into your React tree. Render it once at the root of your app and pass the colorScheme you want as the default.The provider’s full signature, straight from packages/ui/src/ClementineDSProvider.tsx:
Wrap your application entry point:
Pass colorScheme="dark" to start in dark mode, or "auto" to follow the OS preference. All semantic tokens — surface.elevated, text.primary, border.subtle — flip automatically when the scheme changes.
4

Import and use a component

Import any component from @clementine-ds/ui. Every export is listed in packages/ui/src/index.ts. Here is a complete working example using Button:
The full component export surface includes:
Every component is backed by a spec in specs/<component>/index.md. If you are writing code with an AI agent, point it at the relevant spec file first — it contains the closed token contract, required ARIA, and interaction states the agent needs to produce correct output.
5

Build all packages

Compile the full workspace in dependency order using the Turborepo pipeline:
This runs tsc --noEmit for @clementine-ds/ui and style-dictionary build for @clementine-ds/tokens, producing compiled token outputs in packages/tokens/dist/.

Validate specs with the CLI

The agentic-spec CLI validates spec files against five gates: token completeness, interaction state coverage, ARIA requirements, contract integrity, and AI-Ready status consistency. Install it globally and run it against any spec directory:
Run it across every spec at once:
See the agentic-spec repository for the full command surface, including agentic-spec init for scaffolding new specs.

Required environment variables

There are no required environment variables for local development. Storybook, builds, and spec validation all work without any configuration. One optional variable exists for the Figma token-sync workflow: