{"id":30201601,"url":"https://github.com/mocksi/design-system-mcp","last_synced_at":"2025-10-27T11:02:27.519Z","repository":{"id":308969783,"uuid":"1034752097","full_name":"Mocksi/design-system-mcp","owner":"Mocksi","description":"simple MCP for exploring Design Tokens","archived":false,"fork":false,"pushed_at":"2025-08-09T01:12:26.000Z","size":153,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T01:13:52.512Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mocksi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T23:29:41.000Z","updated_at":"2025-08-09T01:12:30.000Z","dependencies_parsed_at":"2025-08-09T01:13:54.789Z","dependency_job_id":"f6d3c0a5-d4c1-4bc2-833d-9fe6680b2a47","html_url":"https://github.com/Mocksi/design-system-mcp","commit_stats":null,"previous_names":["mocksi/design-system-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Mocksi/design-system-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fdesign-system-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fdesign-system-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fdesign-system-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fdesign-system-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mocksi","download_url":"https://codeload.github.com/Mocksi/design-system-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fdesign-system-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270228440,"owners_count":24548818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-13T10:51:10.416Z","updated_at":"2025-10-27T11:02:27.425Z","avatar_url":"https://github.com/Mocksi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Design System MCP\n\n\u003e 🎨 **Model Context Protocol server that gives AI assistants direct access to your design tokens**\n\nPrevent AI assistants from hallucinating design tokens by giving them read‑only access to your W3C Design Token JSON files. No more `#ff0000` when you have a perfectly good `colors.primary.500` token.\n\n[![npm version](https://img.shields.io/npm/v/design-system-mcp)](https://www.npmjs.com/package/design-system-mcp) [![npm downloads](https://img.shields.io/npm/dm/design-system-mcp)](https://www.npmjs.com/package/design-system-mcp) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![node \u003e= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n\n## 🚀 Getting Started\n\n**Requirements:** Node \u003e= 18 • Compatible with Claude Code, Cursor, Claude Desktop\n\n### 1. Install\n\n```bash\nnpm install -g design-system-mcp\n```\n\n### 2. Export your tokens (W3C format)\n\nExport your design tokens to W3C Design Token JSON format and place them in a folder:\n```\n[your-path]/tokens/\n├── colors-primitives.json\n├── colors-semantic.json\n├── typography.json\n├── spacing.json\n└── components.json\n```\n\n**Don't have tokens yet?** Initialize with sample tokens:\n```bash\nnpx design-system-mcp init\n```\n\n### 3. Validate your tokens\n\nMake sure your tokens can be read:\n```bash\nDESIGN_TOKENS_PATH=./your-tokens-directory npx design-system-mcp validate\n```\nExpected output:\n```\n✓ Token files found: 5 files in [your-path]/tokens\n✓ Categories discovered: colors, typography, spacing, components\n```\n\n### 4. Hook up the MCP\n\nConfigure your AI client to use your token path. See [MCP Setup Guide](./MCP-SETUP.md) for detailed configurations.\n\nQuick example:\n```json\n{\n  \"mcpServers\": {\n    \"design_system\": {\n      \"command\": \"npx\",\n      \"args\": [\"design-system-mcp\", \"start\"],\n      \"env\": { \"DESIGN_TOKENS_PATH\": \"./your-tokens-directory\" }\n    }\n  }\n}\n```\n\n## 📦 Installation\n\n| Method | Command | When to use |\n|--------|---------|-------------|\n| **Project-local** | `npm install design-system-mcp` | Recommended for team projects |\n| **Global** | `npm install -g design-system-mcp` | Personal use across projects |\n\nBoth methods work with `npx design-system-mcp` - no difference in usage.\n\n## ✨ Features\n\n- 🚫 **Stop token hallucination** - AI uses your actual design tokens, not made-up values\n- 📁 **Multi-file support** - Merge tokens from multiple JSON files automatically  \n- 🔄 **Token references** - Resolve `{colors.primary}` aliases between tokens\n- ✅ **Validation** - Catch malformed tokens before AI sees them\n- 🔧 **Tool integration** - Works with Figma Tokens, Style Dictionary, manual JSON\n- 🔒 **Read-only access** - AI can discover and use tokens but never modify them\n\n## 🎯 Why this exists\n\n- Ensures AI assistants use your real tokens instead of hallucinating values\n- Normalizes various token sources (Figma Tokens, Style Dictionary, manual JSON) into W3C JSON\n- Adds validation, discovery, and safe read‑only access via the MCP protocol\n\n\n## 📄 Token File Format\n\nThis MCP server works with **W3C Design Token JSON** files. Place your token files in `./design-system-mcp/tokens/` (or set `DESIGN_TOKENS_PATH`):\n\n### File Structure\n```\n[your-path]/tokens/\n├── colors-primitives.json\n├── colors-semantic.json\n├── typography.json\n├── spacing.json\n└── components.json\n```\n\n### Example Token File\n```json\n{\n  \"colors\": {\n    \"primary\": {\n      \"50\": {\n        \"$type\": \"color\",\n        \"$value\": \"#eff6ff\",\n        \"$description\": \"Primary color light variant\"\n      },\n      \"500\": {\n        \"$type\": \"color\", \n        \"$value\": \"#3b82f6\",\n        \"$description\": \"Primary color base\"\n      }\n    }\n  }\n}\n```\n\n### Key Conventions\n- **Format**: W3C Design Tokens (community group spec)\n- **Structure**: One or many `.json` files with categories like `colors`, `typography`, `spacing`, `components`\n- **Discovery**: All `.json` files under `DESIGN_TOKENS_PATH` are merged by category\n- **Aliases**: Reference other tokens with `{path.to.token}` syntax (e.g., `\"$value\": \"{colors.primary.500}\"`)\n\nFor detailed MCP setup instructions for different AI clients, see [MCP Setup Guide](./MCP-SETUP.md).\n\n## 💬 Usage Examples\n\nOnce configured, your AI assistant has access to your design tokens. Here are some example interactions:\n\n### 🔍 Discovery\n**You:** \"What colors are available in our design system?\"  \n**AI:** *Lists all color categories and tokens from your JSON files*\n\n**You:** \"Show me all typography tokens with their values\"  \n**AI:** *Displays typography tokens with font families, sizes, weights, etc.*\n\n### 🎨 Component Development\n**You:** \"Create a React button component using our design system tokens\"  \n**AI:** \n```jsx\nconst Button = ({ variant = 'primary', children }) =\u003e (\n  \u003cbutton \n    style={{\n      backgroundColor: 'var(--colors-primary-500)', // Uses your actual token\n      color: 'var(--colors-neutral-50)',\n      padding: 'var(--spacing-md) var(--spacing-lg)',\n      fontFamily: 'var(--typography-body-fontFamily)',\n      fontSize: 'var(--typography-body-fontSize)',\n      borderRadius: 'var(--radius-md)'\n    }}\n  \u003e\n    {children}\n  \u003c/button\u003e\n);\n```\n\n### 🔧 Token Debugging  \n**You:** \"What's the exact hex value of our primary-500 color?\"  \n**AI:** *Returns the exact value from your token files, e.g., \"#3b82f6\"*\n\n**You:** \"Are there any typography tokens that reference other tokens?\"  \n**AI:** *Shows tokens with `{path.to.token}` references and their resolved values*\n\n---\n\n## 🔄 Replacing Sample Tokens\n\nReady to use your real tokens? Here's how:\n\n### 📁 Token Location Options\n\n| Option | Path | Configuration |\n|--------|------|---------------|\n| **Default** | `./design-system-mcp/tokens/` | No setup needed |\n| **Custom** | Any folder | Set `DESIGN_TOKENS_PATH` env variable |\n\n**Example with custom path:**\n```bash\nDESIGN_TOKENS_PATH=./your-tokens-directory npx design-system-mcp validate\n```\n\n### 🗂️ Supported File Layouts\n\n| Layout | Example | Benefits |\n|--------|---------|----------|\n| **Single file** | `tokens.json` | Simple for small token sets |\n| **Multiple files** ⭐ | `colors.json`, `typography.json`, `spacing.json` | Better organization, team collaboration |\n\nThe server automatically discovers all `.json` files and merges categories.\n\n### Required format (W3C Design Tokens)\n\n- Files must follow the W3C Design Token JSON format (latest community group spec)\n- Top‑level keys should be standard categories such as `colors`, `typography`, `spacing`, `components`, etc.\n\nMinimal examples:\n\n```json\n{\n  \"colors\": {\n    \"primary\": { \"$type\": \"color\", \"$value\": \"#3b82f6\" }\n  }\n}\n```\n\n```json\n{\n  \"typography\": {\n    \"heading\": {\n      \"large\": {\n        \"$type\": \"typography\",\n        \"$value\": { \"fontFamily\": \"Inter\", \"fontSize\": \"32px\", \"fontWeight\": 600, \"lineHeight\": \"1.2\" }\n      }\n    }\n  }\n}\n```\n\n### Using references/aliases\n\n- You can reference other tokens with `{path.to.token}` syntax, e.g. `\"$value\": \"{colors.primary}\"`\n- The server can optionally resolve references when returning category/token data\n\n### Common workflows\n\n- Figma Tokens / Tokens Studio: export to W3C JSON and copy into your tokens directory\n- Style Dictionary: output W3C-compatible JSON and direct output to your tokens directory\n- Manual JSON: follow the minimal examples above\n\n### Validate Your Token Setup\n\n1. **Test your tokens:** `npx design-system-mcp validate`\n2. **Expected success output:**\n   ```\n   ✓ Token files found: 3 files in ./design-system-mcp/tokens\n   ✓ Categories discovered: colors, typography, spacing\n   ```\n3. **If no tokens found:** Verify the directory exists and contains `.json` files, or set `DESIGN_TOKENS_PATH`\n\n### Quick checklist\n\n- Tokens are in your selected directory (default `./design-system-mcp/tokens/`)\n- Files end with `.json` and contain valid JSON\n- Top‑level categories use standard names (`colors`, `typography`, `spacing`, `components`, ...)\n- Optional: references use `{...}` syntax and point to existing tokens\n- Validation shows files and expected categories\n\n---\n\n## 🔧 Token Creation Workflows\n\n| Tool | Process | Notes |\n|------|---------|-------|\n| **Figma Tokens** | Export → W3C JSON → Copy to tokens folder | Use `{path.to.token}` aliases |\n| **Style Dictionary** | Build → W3C JSON output → Point `DESIGN_TOKENS_PATH` | Keep aliases in output |\n| **Design Token Studio** | Export → W3C JSON → Copy to folder | - |\n| **Manual JSON** | Write JSON files → Follow W3C format | See examples above |\n\n### Quick Setup: Figma Tokens\n\n1. Export your tokens as W3C JSON format\n2. Copy files to `./design-system-mcp/tokens/`\n3. **Test the setup:** `npx design-system-mcp validate` (checks file format and discovery)\n\n\n---\n\n## 🛠️ Commands\n\n| Command | Purpose |\n|---------|---------|\n| `npx design-system-mcp init` | Copy sample tokens to ./design-system-mcp/tokens/ |\n| `npx design-system-mcp validate` | Check token files are valid W3C format and discoverable |\n| `npx design-system-mcp start` | Start the MCP server (used by AI clients) |\n\n### Command Examples\n\n**Initialize sample tokens:**\n```bash\n$ npx design-system-mcp init\n✓ Copied sample tokens to ./design-system-mcp/tokens/\n✓ Ready to test!\n```\n\n**Validate token setup:**\n```bash\n$ npx design-system-mcp validate\n✓ Token files found: 5 files in ./design-system-mcp/tokens\n✓ Categories discovered: colors, typography, spacing, components\n```\n\n---\n\n## 🔍 Troubleshooting\n\n### No tokens found\n```\nNo tokens found in ./design-system-mcp/tokens/. \n```\n\n**Solutions:**\n- Install the package first: `npm install design-system-mcp`\n- Initialize sample tokens: `npx design-system-mcp init`\n- Or test with built-in examples: `DESIGN_TOKENS_PATH=node_modules/design-system-mcp/examples/tokens npx design-system-mcp validate` (verifies token format)\n\n### AI client can't connect\n1. Restart your AI client completely after configuration changes\n2. Check that the config file is in the correct location for your platform\n3. Verify the token directory path in your configuration\n\n### Invalid token files\nThe validate command will show specific errors:\n```\ncolors.json line 15: Missing required '$type' field for token 'primary-500'\n```\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhere do my tokens go?\u003c/strong\u003e\u003c/summary\u003e\nDefault: \u003ccode\u003e./design-system-mcp/tokens/\u003c/code\u003e. Or set \u003ccode\u003eDESIGN_TOKENS_PATH\u003c/code\u003e to any folder with W3C Design Token JSON files.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDo I need Figma Tokens or Style Dictionary?\u003c/strong\u003e\u003c/summary\u003e\nNo. Any valid W3C Design Token JSON works. Those tools are just convenient producers.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I split tokens across multiple files?\u003c/strong\u003e\u003c/summary\u003e\nYes. All \u003ccode\u003e.json\u003c/code\u003e files under \u003ccode\u003eDESIGN_TOKENS_PATH\u003c/code\u003e are discovered and merged by category.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow do aliases work?\u003c/strong\u003e\u003c/summary\u003e\nUse \u003ccode\u003e{path.to.token}\u003c/code\u003e in \u003ccode\u003e\"$value\"\u003c/code\u003e. Aliases can be resolved when returning category/token data.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow do I test the MCP server without setting up my own tokens?\u003c/strong\u003e\u003c/summary\u003e\nUse the built-in sample tokens to validate the setup works:\n\n```bash\n# Test with built-in examples (automatic)\nnpx design-system-mcp validate\n\n# Or explicitly point to installed examples  \nDESIGN_TOKENS_PATH=node_modules/design-system-mcp/examples/tokens npx design-system-mcp validate\n```\n\nBoth will show you what successful validation looks like before you add your own tokens.\n\u003c/details\u003e\n\n## Contributing\n\n1. Node \u003e= 18\n2. Install dependencies:\n   ```bash\n   npm i\n   ```\n3. Run tests and typecheck:\n   ```bash\n   npm run test\n   npm run build\n   ```\n4. Dev loop:\n   ```bash\n   npm run dev\n   ```\n5. Open a PR with a clear description and tests for changes.\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmocksi%2Fdesign-system-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmocksi%2Fdesign-system-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmocksi%2Fdesign-system-mcp/lists"}