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.

Quick Start

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 complementary ways for AI agents to consume it:

	Claude Skill (SKILL.md)	AGENT.md	MCP Server
What it is	Claude Code skill file	Generic AI agent instructions	Running process with tools
Stays in sync	Yes -- auto-generated	Yes -- auto-generated	Yes -- reads source at runtime
Setup	Symlink to .claude/skills/	Symlink to project root	Configure in settings
Best for	Claude Code	Cursor, Copilot, Windsurf, Codeium	Programmatic access, validation

All three read from the same sources (tokens/*.json and lib/catalog.ts), so they always agree.

Quick Install (all at once)

The install script sets up everything -- Claude Skill, AGENT.md, and fonts:

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

This will:

1. Symlink SKILL.md into .claude/skills/ (for Claude Code)
2. Symlink AGENT.md into the project root (for Cursor, Copilot, etc.)
3. Copy Aspekta font files into public/fonts/
4. Print CSS import instructions

Option A: Claude Skill (SKILL.md)

The skill file gives any Claude Code session full design system context -- tokens, all components with props/examples, composition rules, font setup, and the extension protocol.

Install into a consuming project:

# From the design system repo
./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.md

Regenerate after changes:

pnpm skill:build

This is run automatically as part of pnpm build. If you add a component, add it to lib/catalog.ts and regenerate.

Option B: AGENT.md (non-Claude AI agents)

For Cursor, GitHub Copilot, Windsurf, Codeium, and other AI coding assistants that read project-root markdown files:

# Via install script (also sets up fonts + Claude Skill)
./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:

pnpm mcp:start

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

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

Install in Claude Desktop (claude_desktop_config.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:

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

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.

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