> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Clementine DS Quickstart: Install and Render Components

> Install Clementine DS, wrap your app in ClementineDSProvider, and render your first token-bound React component in under five minutes.

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.

```bash theme={null}
git clone https://github.com/tishsingh399/clementine-ds.git
cd clementine-ds
pnpm install
```

This installs four workspaces:

| Package | Path | Purpose |
| - | - | - |
| `clementine-ds` | root | Workspace root, Turborepo pipeline scripts |
| `@clementine-ds/tokens` | `packages/tokens` | Style Dictionary source — 52 primitives, 32 semantic tokens, 102 component tokens |
| `@clementine-ds/ui` | `packages/ui` | 10 React components, Mantine-backed |
| `storybook` | `apps/storybook` | Live component sandbox |

**2. Run Storybook**

Start the local Storybook dev server to browse every component and all of its interaction states:

```bash theme={null}
pnpm storybook
# Storybook running at http://localhost:6006
```

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](https://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`:

```tsx theme={null}
import { MantineProvider, type MantineProviderProps } from '@mantine/core';
import { clementineTheme, cssVariablesResolver } from './theme/clementine-theme';
import '@mantine/core/styles.css';

export interface ClementineDSProviderProps {
  children: React.ReactNode;
  colorScheme?: MantineProviderProps['defaultColorScheme'];
}

export function ClementineDSProvider({
  children,
  colorScheme = 'light',
}: ClementineDSProviderProps) {
  return (
    <MantineProvider
      theme={clementineTheme}
      cssVariablesResolver={cssVariablesResolver}
      defaultColorScheme={colorScheme}
    >
      {children}
    </MantineProvider>
  );
}
```

Wrap your application entry point:

```tsx theme={null}
import { ClementineDSProvider } from '@clementine-ds/ui';

export function App() {
  return (
    <ClementineDSProvider colorScheme="light">
      {/* your app */}
    </ClementineDSProvider>
  );
}
```

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`:

```tsx theme={null}
import { ClementineDSProvider, Button } from '@clementine-ds/ui';

export function App() {
  return (
    <ClementineDSProvider colorScheme="light">
      <Button variant="filled" onClick={() => console.log('clicked')}>
        Save changes
      </Button>
    </ClementineDSProvider>
  );
}
```

The full component export surface includes:

```ts theme={null}
// Components
Button, TextInput, Textarea, Select, Checkbox,
Switch, Radio, RadioGroup, Badge, Tabs, TabsList,
TabsTab, TabsPanel, Modal

// Layout helpers (re-exported from Mantine)
Stack, Group, Text, Title, Flex, Box, Container
```

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:

```bash theme={null}
pnpm build
```

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:

```bash theme={null}
npm install -g agentic-spec
agentic-spec validate specs/button
# PASS button (specs/button)
#   tokens: 15 in contract, 15 in tokens.json · states: 6 · parts: 5
```

Run it across every spec at once:

```bash theme={null}
agentic-spec validate specs/*
```

See the [agentic-spec repository](https://github.com/tishsingh399/agentic-spec) 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:

| Variable | Purpose | Required? |
| - | - | - |
| `FIGMA_FILE_KEY` | Pulling tokens from your Figma file into the spec format | Only for the Figma token-sync flow |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.