MCP Design System

The Vayu UI MCP (Model Context Protocol) server exposes the complete design system and component registry to AI assistants and automated tools. This documentation covers how to access design tokens, components, hooks, and patterns through the MCP interface.

Overview

The Vayu UI MCP server provides programmatic access to:

• Component Registry - All components and hooks with metadata
• Design Tokens - CSS variables and their usage
• Component Examples - Ready-to-use code snippets
• Accessibility Data - ARIA roles, keyboard navigation, focus management
• Pattern Documentation - Composition, anti-patterns, and best practices

All design system data is available through MCP tools, enabling AI assistants to understand and use Vayu UI components correctly.

Getting Started

Installing the MCP Server

Add the Vayu UI MCP server to your Claude Desktop or MCP-compatible client:

{
  "mcpServers": {
    "vayu-ui": {
      "command": "node",
      "args": ["/path/to/vayu-ui/packages/mcp/dist/index.js"]
    }
  }
}

Available MCP Tools

Color System

Accessing Colors via MCP

The color system is organized into semantic color groups. Use get_design_tokens to access color tokens for any component.

{
  "name": "list_components",
  "arguments": {
    "category": "action",
    "type": "component"
  }
}

[
  {
    "name": "Button",
    "slug": "button",
    "category": "action",
    "type": "component",
    "description": "A button component with variants"
  }
]

Primary - Lime

Brand identity color for CTAs, active states, key highlights.

// Request design tokens for a component
{
  "name": "get_design_tokens",
  "arguments": {
    "name": "Button",
    "overridableOnly": false
  }
}

Available Shades: 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

Usage Rules:

• 100-300 → backgrounds & decorative surfaces
• 400-600 → interactive elements & primary actions
• 700-950 → text on light bg / inverted surfaces in dark mode

Ground - Zinc

Neutral foundation for backgrounds, surfaces, borders, text.

Available Shades: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

Usage Rules:

• 50-300 → surfaces, cards, borders (light mode)
• 400-600 → text, icons, labels
• 700-950 → headings in light / become surfaces in dark

Semantic Colors

Typography

Font Families

Access typography information through component metadata:

{
  "name": "get_component_full",
  "arguments": {
    "name": "Typography"
  }
}

Type Scale

Spacing & Shape

Border Radius

Consistent 12px border radius across all components.

// Get design tokens
{
  "name": "get_design_tokens",
  "arguments": {
    "name": "Card",
    "overridableOnly": true
  }
}

Token: --radius: 12px

Shadows

Available shadow tokens for depth and hierarchy:

--shadow-outer: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.1);
--inset-shadow-inner: inset 0 2px 4px 0 rgba(0, 0, 0, 0.1);

Transitions

Smooth transition timing functions for consistent animations:

{
  "name": "get_design_tokens",
  "arguments": {
    "name": "Button",
    "overridableOnly": false
  }
}

Component Discovery

List All Components

Discover all available components and hooks:

{
  "name": "list_components",
  "arguments": {}
}

Filters:

• category: "action" | "input" | "layout" | "overlay" | "display" | "navigation" | "feedback" | "utility"
• type: "component" | "hook"

Find Components by Use Case

Search for components based on what you need:

{
  "name": "find_component",
  "arguments": {
    "query": "countdown timer"
  }
}

Searches across:

• Component names
• Descriptions
• Categories
• Tags
• Variants

Component Props

Get Props with Types

Retrieve all props with TypeScript types and descriptions:

{
  "name": "get_component_props",
  "arguments": {
    "name": "Button",
    "includeDeprecated": false
  }
}

Response Structure:

{
  "variant": {
    "type": "\"solid\" | \"outline\" | \"ghost\"",
    "required": false,
    "default": "\"solid\"",
    "description": "Visual style variant of the button"
  },
  "size": {
    "type": "\"small\" | \"medium\" | \"large\"",
    "required": false,
    "default": "\"medium\"",
    "description": "Size of the button"
  }
}

Component Examples

Get Ready-to-Use Examples

Retrieve copy-paste ready TSX code:

{
  "name": "get_component_example",
  "arguments": {
    "name": "Button",
    "variant": "loading"
  }
}

Available Examples: Varies by component

Response:

{
  "code": "<Button variant=\"solid\" loading>Loading...</Button>",
  "description": "Button with loading state"
}

List Available Examples

Get all available example keys for a component:

{
  "name": "get_component_example",
  "arguments": {
    "name": "Button"
  }
}

Accessibility

Get A11y Information

Retrieve accessibility data for components:

{
  "name": "get_component_a11y",
  "arguments": {
    "name": "Button"
  }
}

Response Structure:

{
  "role": "button",
  "requiredAttrs": {
    "aria-label": "Descriptive label when text content is not available"
  },
  "managedAttrs": ["aria-pressed", "aria-expanded"],
  "keyboard": {
    "Enter": "Activates the button",
    "Space": "Activates the button"
  },
  "focusManagement": "Button receives focus when clicked"
}

Anti-Patterns

Get common mistakes and anti-patterns:

{
  "name": "get_component_doNot",
  "arguments": {
    "name": "Button",
    "category": "a11y"
  }
}

Categories:

• api - API usage mistakes
• a11y - Accessibility violations
• styling - Styling anti-patterns
• nesting - Incorrect nesting patterns
• perf - Performance issues
• ux - UX anti-patterns

Component States

Get Interactive States

Retrieve all visual and interactive states:

{
  "name": "get_component_states",
  "arguments": {
    "name": "Button"
  }
}

Available States:

• default - Normal state
• hover - Mouse hover
• focus - Keyboard focus
• active - Mouse press
• disabled - Disabled state
• loading - Loading state
• error - Error state
• empty - Empty state
• checked - Checked state (checkbox/radio)
• indeterminate - Indeterminate state

Response Structure:

{
  "hover": {
    "trigger": "Mouse hover",
    "visualChange": "Background color darkens, elevation increases",
    "ariaAttr": "None"
  }
}

Component Dependencies

Get Dependencies

Retrieve NPM and registry dependencies:

{
  "name": "get_component_dependencies",
  "arguments": {
    "name": "Button"
  }
}

Response:

{
  "npmDependencies": ["react", "clsx", "tailwind-merge"],
  "registryDependencies": ["Label"],
  "installCommand": "npx vayu-ui add button",
  "targetPath": "src/components/ui/button.tsx"
}

Get Peer Components

Find components frequently used together:

{
  "name": "get_component_peer_components",
  "arguments": {
    "name": "Button"
  }
}

Composition Patterns

Get Compound Component Info

Retrieve composition data for compound components:

{
  "name": "get_component_composition",
  "arguments": {
    "name": "Dialog"
  }
}

Response:

{
  "parts": {
    "Dialog.Trigger": "Button that opens the dialog",
    "Dialog.Content": "Main dialog container",
    "Dialog.Header": "Dialog header section",
    "Dialog.Body": "Dialog body content",
    "Dialog.Footer": "Dialog footer actions"
  },
  "example": "<Dialog>\n  <Dialog.Trigger>Open</Dialog.Trigger>\n  <Dialog.Content>\n    <Dialog.Header>Title</Dialog.Header>\n    <Dialog.Body>Content</Dialog.Body>\n  </Dialog.Content>\n</Dialog>",
  "partsRequired": false
}

Component Variants

Get Available Variants

Retrieve visual variant options:

{
  "name": "get_component_variants",
  "arguments": {
    "name": "Button"
  }
}

Response:

["solid", "outline", "ghost", "link"]

Component Events

Get Event Handlers

Retrieve all event handlers with TypeScript signatures:

{
  "name": "get_component_events",
  "arguments": {
    "name": "Button"
  }
}

Response Structure:

{
  "onClick": {
    "signature": "(event: MouseEvent<HTMLButtonElement>) => void",
    "description": "Fired when the button is clicked",
    "controlledBy": null
  }
}

Scaffold Component Usage

Generate Ready-to-Use Snippets

Generate copy-paste ready code with imports and state:

{
  "name": "scaffold_component_usage",
  "arguments": {
    "name": "Dialog",
    "variant": "default",
    "withState": true
  }
}

Response:

{
  "scaffold": "import { Dialog } from \"@/components/ui/dialog\";\n\nconst [open, setOpen] = React.useState(false);\n\n<Dialog open={open} onOpenChange={setOpen}>",
  "installCommand": "npx vayu-ui add dialog"
}

Dark Mode

Dark Mode Information

Access dark mode behavior through component metadata:

{
  "name": "get_component_full",
  "arguments": {
    "name": "Button"
  }
}

Dark Mode Response:

{
  "darkMode": {
    "automatic": true,
    "tokenSwaps": {
      "--color-primary-500": "--color-primary-500"
    }
  }
}

Dark Mode Inversion Pattern

Design Tokens Reference

Token Categories

Design tokens are categorized by their scope and usage:

Overridable Tokens

Filter to get only overridable tokens:

{
  "name": "get_design_tokens",
  "arguments": {
    "name": "Button",
    "overridableOnly": true
  }
}

Overridable tokens are safe to override in consumer CSS without breaking component behavior.

Component Categories

All components are organized into categories:

AI Assistant Usage

Recommended Workflow for AI Assistants

When using the Vayu UI MCP server as an AI assistant:

1. Discovery: Use list_components or find_component to find the right component
2. Learn: Use get_component_props and get_component_a11y to understand the API
3. Examples: Use get_component_example to see usage patterns
4. Scaffold: Use scaffold_component_usage to generate code
5. Validate: Use get_component_doNot to avoid anti-patterns

Example AI Assistant Flow

// 1. Find the component
{
  "name": "find_component",
  "arguments": {
    "query": "modal dialog with overlay"
  }
}

// 2. Get props
{
  "name": "get_component_props",
  "arguments": {
    "name": "Dialog",
    "includeDeprecated": false
  }
}

// 3. Get example
{
  "name": "get_component_example",
  "arguments": {
    "name": "Dialog",
    "variant": "default"
  }
}

// 4. Scaffold usage
{
  "name": "scaffold_component_usage",
  "arguments": {
    "name": "Dialog",
    "withState": true
  }
}

Accessibility Compliance

All components in the Vayu UI registry meet WCAG 2.1 AA standards:

• Color contrast: Minimum 4.5:1 for normal text, 3:1 for large text
• Keyboard navigation: All interactive elements are keyboard accessible
• Screen reader support: Proper ARIA roles and attributes
• Focus management: Clear focus indicators and logical focus flow
• Reduced motion: Respects prefers-reduced-motion preference

Best Practices

For MCP Clients

1. Cache component lists: Call list_components once per session
2. Use specific tools: Prefer scoped tools over get_component_full
3. Handle errors: Gracefully handle "not found" errors
4. Validate props: Check required flags in prop metadata
5. Respect deprecations: Avoid using deprecated props

For AI Assistants

1. Search before assuming: Use find_component to locate appropriate components
2. Check anti-patterns: Use get_component_doNot before generating code
3. Include accessibility: Always reference get_component_a11y for A11y requirements
4. Use examples: Reference get_component_example for best practices
5. Scaffold with state: Use scaffold_component_usage for complete implementations

API Reference

Tool Parameters

All MCP tools follow a consistent parameter structure:

Error Handling

All MCP tools return errors in a consistent format:

{
  "content": [
    {
      "type": "text",
      "text": "ERROR: Component not found. Use find_component() to search."
    }
  ],
  "isError": true
}

Additional Resources

• Components - Explore all available components
• Hooks - Custom React hooks for common patterns
• Design System - Global CSS and design tokens
• Getting Started - Quick start guide for Vayu UI
• MCP Protocol - Learn about MCP