@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: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 The full component export surface includes:Every component is backed by a spec in
@clementine-ds/ui. Every export is listed in packages/ui/src/index.ts. Here is a complete working example using Button: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
Theagentic-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:
agentic-spec init for scaffolding new specs.