@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

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

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:

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

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

4. Use Components

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

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

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

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 for the full specification.

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