> ## 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.

# Storybook: Clementine DS Components and Token Bindings

> Clementine DS includes a live Storybook at clementine-ds-storybook.vercel.app — every component, interaction state, and token binding in one sandbox.

Clementine DS includes a live Storybook sandbox with stories for every component and every interaction state. Every paint you see in the sandbox traces back to a component-tier token — there are no hardcoded values in the stories or the components they render.

**Live Storybook:** [clementine-ds-storybook.vercel.app](https://clementine-ds-storybook.vercel.app)

## Run Storybook locally

Clone the repo, install dependencies, and start the dev server:

```bash theme={null}
git clone https://github.com/tishsingh399/clementine-ds.git
cd clementine-ds
pnpm install
pnpm storybook
# → http://localhost:6006
```

Storybook starts at `http://localhost:6006`. Hot reload is on by default.

## What the sandbox contains

The sandbox covers all 10 components, each with a story per interaction state.

| Component | Stories |
| - | - |
| Button | Default, Outline, Light, Subtle, Loading, Disabled, Small, Large, Destructive |
| Badge | Per intent (success, error, warning, info, neutral, and more) |
| Checkbox | Default, checked, indeterminate, disabled |
| Radio | Default, selected, disabled |
| Switch | Off, on, disabled |
| TextInput | Default, focus, error, disabled |
| Select | Default, open, error, disabled |
| Textarea | Default, focus, error, disabled |
| Tabs | Default, active tab, disabled tab |
| Modal | Closed, open |

## The contract between specs and stories

Every state listed under `interaction_states:` in a component spec must have a corresponding Storybook story. This is a hard gate — a component cannot be promoted to `AI-Ready` status until all stories exist.

For Button, the spec declares:

```yaml theme={null}
interaction_states: [default, hover, focus, active, disabled, loading]
```

All six states have stories in `apps/storybook/stories/Button.stories.tsx`. The AI-Ready gate checks this correspondence mechanically.

## Example story structure

Stories live in `apps/storybook/stories/<Component>.stories.tsx`. Here is the structure for Button:

```tsx theme={null}
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from '@clementine-ds/ui';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['filled', 'outline', 'light', 'subtle'],
    },
    disabled: { control: 'boolean' },
    loading: { control: 'boolean' },
  },
  args: {
    children: 'Button',
    variant: 'filled',
    size: 'md',
    disabled: false,
    loading: false,
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Default: Story = {};

export const Outline: Story = {
  args: { variant: 'outline' },
};

export const Loading: Story = {
  args: { loading: true },
};

export const Disabled: Story = {
  args: { disabled: true },
};
```

Each named export is one story. Each story corresponds to one row in the component spec's `interaction_states` list. Add a state to the spec, add a story to the file.

## Promoting a component to AI-Ready

Before you set `status: AI-Ready` in a component spec, confirm:

1. Every entry in `interaction_states:` has a named export in the component's `.stories.tsx` file.
2. The story renders correctly in the live sandbox (run `pnpm storybook` and check).
3. `checks.states_complete: true` in the spec frontmatter.

A component with missing stories fails the `ai-ready-gate` validation rule.

## Auto-deploy

Storybook auto-deploys to [clementine-ds-storybook.vercel.app](https://clementine-ds-storybook.vercel.app) on every push to `main` after CI passes. You do not need to trigger a manual deploy. Push your branch, merge, and the live sandbox reflects your changes within minutes.


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