Overview

The goal of this architecture change is to move the design system from being primarily:

A design system website with documentation

toward:

A structured design-system source that can later be exposed to AI through MCP.

The important distinction is that MCP does not need to be built now.

Instead, the repository should be structured so that a future MCP server can easily understand:

• Components
• Tokens
• Documentation
• Metadata
• Relationships
• Accessibility rules
• Implementation details
• Design-system conventions

The architecture should therefore prioritize predictability, machine-readable data, clear relationships, and a stable source of truth.

1. Target Architecture

System/
│
├── tokens/
│   ├── primitives/
│   │   ├── color.json
│   │   ├── spacing.json
│   │   ├── typography.json
│   │   ├── shadow.json
│   │   ├── radius.json
│   │   └── icon.json
│   │
│   └── semantic/
│       ├── color.json
│       ├── text.json
│       ├── background.json
│       ├── border.json
│       └── action.json
│
├── components/
│   ├── button/
│   │   ├── button.tsx
│   │   ├── button.mdx
│   │   └── schema.json
│   │
│   └── ...
│
├── docs/
│   ├── foundations/
│   │   ├── color.mdx
│   │   ├── spacing.mdx
│   │   ├── typography.mdx
│   │   ├── shadows.mdx
│   │   ├── icons.mdx
│   │   └── semantic-tokens.mdx
│   │
│   └── principles/
│       ├── accessibility.mdx
│       ├── localization.mdx
│       └── usage.mdx
│
├── schemas/
│   ├── component.schema.json
│   ├── token.schema.json
│   └── documentation.schema.json
│
├── registry/
│   ├── components.json
│   ├── tokens.json
│   └── registry.json
│
├── scripts/
│   ├── build-tokens.mjs
│   ├── build-docs.mjs
│   ├── generate-registry.mjs
│   └── validate.mjs
│
├── mcp/
│   └── server/
│
├── dist/
└── public/