design system token v0.1
This commit is contained in:
Juan
212
README.md
212
README.md
@@ -1,47 +1,201 @@
|
||||
# Greyhaven Design System
|
||||
|
||||
A modern design system built with Next.js, shadcn/ui, and Radix UI primitives.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## Getting Started
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# Build for production
|
||||
pnpm build
|
||||
|
||||
# Start production server
|
||||
pnpm 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/
|
||||
├── app/ # Next.js app directory
|
||||
│ ├── layout.tsx # Root layout with fonts
|
||||
│ ├── page.tsx # Design system showcase
|
||||
│ └── globals.css # Global styles
|
||||
├── components/
|
||||
│ ├── ui/ # Reusable UI components (57 components)
|
||||
│ ├── design-system/ # Showcase components
|
||||
│ └── theme-provider.tsx # Theme context
|
||||
├── hooks/ # Custom React hooks
|
||||
├── 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 # Utility functions
|
||||
├── styles/ # Additional styles
|
||||
└── public/ # Static assets
|
||||
│ ├── 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
|
||||
|
||||
- **Framework:** Next.js 16, React 19, TypeScript
|
||||
- **Styling:** Tailwind CSS 4, shadcn/ui, Radix UI
|
||||
- **Forms:** React Hook Form, Zod
|
||||
- **Theming:** next-themes (light/dark mode)
|
||||
- **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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
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:**
|
||||
|
||||
```bash
|
||||
pnpm mcp:start
|
||||
```
|
||||
|
||||
**Install in Claude Code (`~/.claude/settings.json`):**
|
||||
|
||||
```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 |
|
||||
|
||||
Reference in New Issue
Block a user