# Greyhaven Design System

A framework-agnostic React component library built on Radix UI, Tailwind CSS v4, and shadcn/ui patterns. Designed for LLM consumption with a Claude Skill, MCP server, and Storybook documentation.

![Screenshot](docs/screenshot.png)

## Quick Start

```bash
pnpm install        # Install dependencies
pnpm dev            # Start showcase dev server (Next.js)
pnpm build          # Tokens + SKILL.md + production build
pnpm storybook      # Component catalog on http://localhost:6006
```

## Project Structure

```
greyhaven-design-system/
├── components/ui/          # 37+ framework-agnostic React components
├── tokens/                 # W3C DTCG design tokens (source of truth)
│   ├── color.json
│   ├── typography.json
│   ├── spacing.json
│   ├── radii.json
│   ├── shadows.json
│   └── motion.json
├── skill/                  # Claude Skill (auto-generated)
│   ├── SKILL.md
│   └── install.sh
├── mcp/                    # MCP server for AI agents
│   └── server.ts
├── stories/                # Storybook stories (23 files, 8 categories)
├── lib/
│   ├── utils.ts            # cn() utility
│   └── catalog.ts          # Shared component catalog (used by MCP + SKILL.md)
├── scripts/
│   └── generate-skill.ts   # SKILL.md generator
├── app/                    # Next.js showcase app (demo only)
└── style-dictionary.config.mjs
```

## Tech Stack

- **Components**: React 19, Radix UI, Tailwind CSS 4, CVA, tailwind-merge, clsx
- **Icons**: Lucide React
- **Forms**: React Hook Form + Zod
- **Tokens**: Style Dictionary v4 (W3C DTCG format)
- **Docs**: Storybook 10, auto-generated SKILL.md
- **AI Integration**: MCP server, Claude Skill

> **Framework-agnostic**: Components have zero Next.js imports. They work with Vite, Remix, Astro, CRA, or any React framework.

---

## Using the Design System with AI

The design system provides three things for AI agents:

| File | What it is | Where it goes |
|------|-----------|---------------|
| **SKILL.md** | Full design system reference (tokens, all components, composition rules, extension protocol) | `.claude/skills/` — works in Claude Code, Cursor, OpenCode, Anigravity, etc. |
| **AGENT.md** | Short project instructions telling the AI *how* to use the design system (like CLAUDE.md but portable) | Project root — copy as `AGENT.md`, `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md` |
| **MCP Server** | Runtime tools for looking up components, validating colors, suggesting components | Configured in `.mcp.json` |

All are auto-generated from the same sources (`tokens/*.json` and `lib/catalog.ts`).

### Quick Install (all at once)

```bash
./skill/install.sh /path/to/your/project
```

This will:
1. Symlink `SKILL.md` into `.claude/skills/` (full reference for any AI agent)
2. Copy `AGENT.md` into the project root (project-level instructions)
3. Copy Aspekta font files into `public/fonts/`
4. Print CSS import instructions

### SKILL.md (full reference)

The skill file gives any AI agent full design system context — every token, every component with props/variants/examples, composition rules, font setup, and the extension protocol.

**It's a global standard** — works with Claude Code, Cursor, OpenCode, Anigravity, and any tool that reads skill files.

```bash
# Via install script
./skill/install.sh /path/to/your/project

# Or manually
mkdir -p /path/to/your/project/.claude/skills
ln -sf /absolute/path/to/greyhaven-design-system/skill/SKILL.md \
       /path/to/your/project/.claude/skills/greyhaven-design-system.md
```

### AGENT.md (project instructions)

Short, directive instructions that tell the AI agent *how* to work in the project — use TypeScript, use semantic tokens, reference the MCP tools, etc. This is the equivalent of `CLAUDE.md` but portable across tools.

**Copy it to your project root** under whichever name your tool reads:

```bash
# Claude Code
cp /path/to/greyhaven-design-system/skill/AGENT.md /path/to/your/project/CLAUDE.md

# Cursor
cp /path/to/greyhaven-design-system/skill/AGENT.md /path/to/your/project/.cursorrules

# GitHub Copilot
mkdir -p /path/to/your/project/.github
cp /path/to/greyhaven-design-system/skill/AGENT.md /path/to/your/project/.github/copilot-instructions.md

# Or just use the install script which symlinks AGENT.md to the root
./skill/install.sh /path/to/your/project

# Or manually
ln -sf /absolute/path/to/greyhaven-design-system/skill/AGENT.md \
       /path/to/your/project/AGENT.md
```

Some tools use different file names. You can also symlink as:
- `.cursorrules` (Cursor)
- `.github/copilot-instructions.md` (GitHub Copilot)

### Option C: MCP Server

The MCP server provides 5 tools for programmatic access:

| Tool | Description |
|------|-------------|
| `get_tokens(category?)` | Returns token values (all, or filtered by: color, typography, spacing, radii, shadows, motion) |
| `get_component(name)` | Returns full component spec + source code |
| `list_components(category?)` | Lists components (all, or by: primitives, layout, overlay, navigation, data, feedback, form, composition) |
| `validate_colors(code)` | Checks code for raw hex values that should use design tokens |
| `suggest_component(description)` | Suggests components for a described UI need |

Plus resources: `tokens://all` and `component://{name}` for each component.

**Run directly:**

```bash
pnpm mcp:start
```

**Install in Claude Code (`.mcp.json` in your project root):**

```json
{
  "mcpServers": {
    "greyhaven": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/greyhaven-design-system/mcp/server.ts"]
    }
  }
}
```

**Install in Claude Desktop (`claude_desktop_config.json`):**

```json
{
  "mcpServers": {
    "greyhaven": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/greyhaven-design-system/mcp/server.ts"]
    }
  }
}
```

After adding, restart Claude Code / Claude Desktop. The tools will appear automatically.

**Test it works:**

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | pnpm mcp:start
```

You should see a JSON response with `"serverInfo":{"name":"greyhaven-design-system"}`.

---

## Design Tokens

Tokens are defined in `tokens/*.json` using the [W3C Design Token Community Group](https://tr.designtokens.org/format/) format. Style Dictionary v4 generates:

| Output | Path | Purpose |
|--------|------|---------|
| CSS (light) | `app/tokens/tokens-light.css` | `:root` CSS custom properties |
| CSS (dark) | `app/tokens/tokens-dark.css` | `.dark` CSS custom properties |
| TypeScript | `app/tokens/tokens.ts` | Type-safe token constants |
| Markdown | `app/tokens/TOKENS.md` | Reference doc |

```bash
pnpm tokens:build   # Regenerate all outputs from tokens/*.json
```

---

## Storybook

23 story files across 8 categories with autodocs, theme switching (light/dark via toolbar), and all component variants.

```bash
pnpm storybook         # Dev server on http://localhost:6006
pnpm build-storybook   # Static build
```

---

## Adding a New Component

1. Create `components/ui/my-component.tsx` following the CVA pattern (see `button.tsx`)
2. Add it to the catalog in `lib/catalog.ts`
3. Create a story in `stories/<Category>/MyComponent.stories.tsx`
4. Run `pnpm skill:build` to regenerate SKILL.md (or just `pnpm build`)
5. The MCP server picks it up automatically (reads `lib/catalog.ts` at runtime)

---

## Scripts Reference

| Script | Description |
|--------|-------------|
| `pnpm dev` | Start Next.js showcase dev server |
| `pnpm build` | Full build: tokens + SKILL.md + Next.js |
| `pnpm storybook` | Storybook dev server on :6006 |
| `pnpm build-storybook` | Static Storybook build |
| `pnpm tokens:build` | Regenerate CSS/TS/MD from token JSON files |
| `pnpm skill:build` | Regenerate skill/SKILL.md from tokens + catalog |
| `pnpm mcp:start` | Start the MCP server (stdio transport) |
| `pnpm mcp:build` | Type-check MCP server |
| `pnpm lint` | Run ESLint |
