Files

Juan c3215945f2 design system token v0.1

2026-04-13 15:33:00 -05:00

6.6 KiB

Raw Blame History

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

	Claude Skill (SKILL.md)	MCP Server
What it is	A single markdown file with all tokens, components, and rules	A running process that reads source files in real-time
Stays in sync	Yes -- auto-generated from the same token files and component catalog	Yes -- reads source at runtime
Setup	Copy/symlink one file	Start a server process
Best for	Claude Code sessions, quick context	Programmatic access, validation, any MCP-compatible agent

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

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, 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: 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 (~/.claude/settings.json):

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

Create components/ui/my-component.tsx following the CVA pattern (see button.tsx)
Add it to the catalog in lib/catalog.ts
Create a story in stories/<Category>/MyComponent.stories.tsx
Run pnpm skill:build to regenerate SKILL.md (or just pnpm build)
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

6.6 KiB Raw Blame History