npm package: @magicpatterns/shadcn-demo-template
Description: Shadcn-based design system preset for Tailwind CSS
Latest version: 0.0.3

# @magicpatterns/shadcn-demo-template

A reusable, shadcn-based design system built on Tailwind CSS v3. Ships as an npm package with components, design tokens, Storybook documentation, and an MCP server for AI agent integration.

## Quick Start

```bash
yarn install
yarn build
```

## Project Structure

```
├── src/
│   ├── index.ts              # Barrel exports for all components
│   ├── styles.css            # Main stylesheet entry
│   ├── preset.css            # CSS custom property token definitions
│   ├── SETUP.md              # Consumer setup instructions (served by MCP)
│   ├── lib/
│   │   └── utils.ts          # cn() helper (clsx + tailwind-merge)
│   └── components/
│       ├── Button/            # Each component has:
│       │   ├── Button.tsx     #   - Component source
│       │   ├── Button.stories.tsx  #   - Storybook stories
│       │   ├── context.md    #   - Usage guidelines / docs
│       │   └── index.ts      #   - Barrel export
│       ├── Input/
│       ├── Card/
│       ├── Badge/
│       └── Dialog/
├── guidelines/               # System-wide design guidelines
├── recipes/                  # Curated composition examples
├── .storybook/               # Storybook configuration
├── scripts/
│   └── build-css.js          # PostCSS + Tailwind CSS build
├── tailwind-preset.js        # Tailwind preset (exported for consumers)
├── tailwind.config.js        # Local Tailwind config (uses preset)
├── tsconfig.json             # Base TypeScript config
├── tsconfig.esm.json         # ESM build config → lib/esm/
├── tsconfig.cjs.json         # CJS build config → lib/cjs/
└── mcp/                      # MCP server (nested subfolder)
    ├── src/
    │   ├── index.ts           # Express + MCP endpoint
    │   ├── catalog.ts         # Filesystem-backed component catalog
    │   ├── tools.ts           # MCP tool registrations
    │   └── config.ts          # Server config
    └── MP_DS_MCP_SPEC.md      # MCP specification
```

## Scripts

| Command                | Description                             |
| ---------------------- | --------------------------------------- |
| `yarn build`           | Build ESM + CJS + CSS artifacts         |
| `yarn build:css`       | Rebuild only the CSS stylesheet         |
| `yarn dev`             | Watch mode — rebuilds on source changes |
| `yarn storybook`       | Start Storybook dev server on port 6009 |
| `yarn build-storybook` | Build static Storybook site             |
| `yarn dev:mcp`         | Start MCP server in watch mode          |
| `yarn clean`           | Remove build artifacts                  |

## Consuming in an App

### 1. Install

```bash
yarn add @magicpatterns/shadcn-demo-template
```

### 2. Add the Tailwind Preset

In your app's `tailwind.config.js`, add the preset so all design tokens are available as Tailwind utilities:

```js
module.exports = {
  presets: [require("@magicpatterns/shadcn-demo-template/tailwind")],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@magicpatterns/shadcn-demo-template/lib/**/*.{js,mjs}",
  ],
};
```

### 3. Import Styles

```tsx
import "@magicpatterns/shadcn-demo-template/styles.css";
```

### 4. Use Components

```tsx
import {
  Button,
  Card,
  CardTitle,
  Input,
} from "@magicpatterns/shadcn-demo-template";
```

See [`src/SETUP.md`](src/SETUP.md) for the full setup guide.

## Color Token System

All colors use HSL channel values as CSS custom properties, allowing composition with Tailwind's opacity modifier:

```css
bg-primary         → hsl(var(--primary))
bg-primary/50      → hsl(var(--primary) / 0.5)
```

### Token Groups

| Group           | Tokens                                  | Purpose                        |
| --------------- | --------------------------------------- | ------------------------------ |
| **Global**      | `background`, `foreground`              | Page background, body text     |
| **Card**        | `card`, `card-foreground`               | Elevated surfaces              |
| **Popover**     | `popover`, `popover-foreground`         | Floating surfaces              |
| **Primary**     | `primary`, `primary-foreground`         | Main CTA, brand color          |
| **Secondary**   | `secondary`, `secondary-foreground`     | Supporting actions             |
| **Muted**       | `muted`, `muted-foreground`             | Subdued backgrounds, hint text |
| **Accent**      | `accent`, `accent-foreground`           | Hover highlights, selections   |
| **Destructive** | `destructive`, `destructive-foreground` | Danger actions, errors         |
| **Borders**     | `border`, `input`, `ring`               | Borders, inputs, focus rings   |

### Dark Mode

Add the `dark` class to a parent element to activate dark tokens:

```html
<html class="dark"></html>
```

## Development

### Adding a Component

1. Create `src/components/<Name>/<Name>.tsx` with the component.
2. Create `src/components/<Name>/<Name>.stories.tsx` with Storybook stories.
3. Create `src/components/<Name>/context.md` with usage docs.
4. Create `src/components/<Name>/index.ts` barrel export.
5. Add the export to `src/index.ts`.
6. Run `yarn build` to verify.

### Publishing

```bash
yarn build
npm publish
```

## MCP Server

The `mcp/` directory contains a read-only MCP server that exposes the design system's components, tokens, guidelines, and recipes to AI agents. See [`mcp/MP_DS_MCP_SPEC.md`](mcp/MP_DS_MCP_SPEC.md) for the full specification.

```bash
cd mcp && yarn dev
# Server starts at http://localhost:3009/mcp
```