# 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. | | **AGENTS.md** | Short project instructions telling the AI *how* to use the design system (follows the [agents.md](https://agents.md) convention) | Project root — copy as `AGENTS.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 **copies** (not symlinks) the following into your project: 1. `SKILL.md` → `.claude/skills/greyhaven-design-system.md` (full reference) 2. `AGENTS.md` → project root (project-level instructions) 3. Aspekta font files → `public/fonts/` The script also prints the CSS `@font-face` block and MCP server config to add next. **Re-run the script after design system updates** to refresh your copies. ### 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 (recommended — also handles fonts + AGENTS.md) ./skill/install.sh /path/to/your/project # Or copy manually mkdir -p /path/to/your/project/.claude/skills cp /path/to/greyhaven-design-system/skill/SKILL.md \ /path/to/your/project/.claude/skills/greyhaven-design-system.md ``` ### AGENTS.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. Follows the [agents.md](https://agents.md) convention so it works with most AI coding tools out of the box. **Copy it to your project root** under whichever name your tool reads: ```bash # Standard (agents.md convention — Cursor, OpenCode, Windsurf, Aider, etc.) cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/AGENTS.md # Claude Code cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/CLAUDE.md # Cursor (legacy) cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/.cursorrules # GitHub Copilot mkdir -p /path/to/your/project/.github cp /path/to/greyhaven-design-system/skill/AGENTS.md /path/to/your/project/.github/copilot-instructions.md ``` Or use the install script, which copies `AGENTS.md` to the project root automatically. ### 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//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 |