Skip to Content
AI IntegrationOverview

@raydenui/ai

AI compatibility layer for Rayden UI — enables LLMs to reliably generate UI code without hallucinating components, props, or patterns that don’t exist.

Overview

@raydenui/ai provides:

  • Component Manifests — Machine-readable JSON schemas for every Rayden UI component
  • Component Anatomy — Figma layer structures for building components in Figma
  • Design Tokens — Color, typography, spacing, and shadow tokens in JSON and W3C DTCG formats
  • Composition Rules — Rules for correctly nesting compound components
  • Layout Recipes — Pre-defined patterns for common UI layouts
  • MCP Server — Model Context Protocol server for AI tool integration
  • Skills — Claude Code skills for specialized workflows

Installation

pnpm add @raydenui/ai

Quick Start

Using RAYDEN_RULES.md

The simplest way to integrate with AI is to include the rules file in your context:

import rules from "@raydenui/ai/RAYDEN_RULES.md";
 
// Include in AI system prompt
const systemPrompt = `You are a UI generator using Rayden UI.\n\n${rules}`;

Programmatic Access

import { manifests, tokens, recipes, rules } from "@raydenui/ai";
 
// Get all component manifests
const allComponents = manifests.getAll();
 
// Get specific component props
const buttonProps = manifests.getComponent("Button");
 
// Get design tokens
const colorTokens = tokens.colors;
const shadowTokens = tokens.shadows;
 
// Get layout recipes
const formRecipe = recipes.get("form-layout");

MCP Server

The package includes an MCP (Model Context Protocol) server for AI tool integration:

Starting the Server

npx rayden-ai-mcp

Available Tools

ToolDescription
getComponentsList all available components with descriptions
getComponentPropsGet detailed props for a specific component
getTokensGet design tokens (colors, typography, etc.)
getLayoutRecipesGet pre-defined layout patterns

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rayden-ai": {
      "command": "npx",
      "args": ["@raydenui/ai"]
    }
  }
}

Claude Code Integration

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "rayden-ai": {
      "command": "npx",
      "args": ["@raydenui/ai"]
    }
  }
}

Component Manifests

Each component has a JSON manifest with:

{
  "name": "Button",
  "description": "Primary action trigger with variants, appearances, sizes, icons",
  "props": {
    "variant": {
      "type": "string",
      "enum": ["primary", "secondary", "grey", "destructive", "text", "success", "warning", "info"],
      "default": "primary",
      "description": "Visual variant of the button"
    },
    "size": {
      "type": "string",
      "enum": ["sm", "lg"],
      "default": "sm",
      "description": "Button size (no 'md' - only sm and lg)"
    },
    "icon": {
      "type": "ReactNode | IconName",
      "description": "Icon to display"
    },
    "iconPosition": {
      "type": "string",
      "enum": ["leading", "trailing", "icon-only", "none"],
      "default": "none",
      "description": "Position of the icon"
    }
  },
  "examples": [
    "<Button variant=\"primary\">Click me</Button>",
    "<Button icon=\"plus\" iconPosition=\"leading\">Add Item</Button>"
  ],
  "commonMistakes": [
    { "wrong": "color=\"primary\"", "correct": "variant=\"primary\"" },
    { "wrong": "size=\"md\"", "correct": "size=\"sm\" (only sm and lg exist)" }
  ]
}

Design Tokens

Tokens are exported in JSON format:

{
  "colors": {
    "primary": {
      "50": "#FFECE5",
      "100": "#FCB59A",
      "400": "#F56630",
      "500": "#EB5017",
      "600": "#CC400C",
      "700": "#AD3307"
    },
    "grey": {
      "50": "#F9FAFB",
      "100": "#F0F2F5",
      "200": "#E4E7EC",
      "300": "#D0D5DD",
      "400": "#98A2B3",
      "500": "#667185",
      "600": "#475367",
      "700": "#344054",
      "800": "#1D2739",
      "900": "#101928"
    }
  },
  "shadows": {
    "soft": {
      "xxs": "0px 1px 2px 0px rgba(16, 25, 40, 0.06)",
      "xs": "0px 2px 4px -2px rgba(16, 25, 40, 0.06)",
      "sm": "0px 4px 6px -2px rgba(16, 25, 40, 0.05)",
      "md": "0px 6px 8px -2px rgba(16, 25, 40, 0.05)",
      "lg": "0px 8px 10px -2px rgba(16, 25, 40, 0.05)"
    }
  },
  "typography": {
    "display-lg": { "fontSize": "56px", "lineHeight": "1.2" },
    "h1": { "fontSize": "40px", "lineHeight": "1.2" },
    "body-md": { "fontSize": "16px", "lineHeight": "1.5" }
  }
}

Composition Rules

Rules for correctly nesting compound components:

{
  "Table": {
    "structure": "Table > TableHeader/TableBody > TableRow > TableHead/TableCell",
    "rules": [
      "TableHeader must be direct child of Table",
      "TableRow must be inside TableHeader or TableBody",
      "TableHead goes in TableHeader rows, TableCell in TableBody rows"
    ]
  },
  "DropdownMenu": {
    "structure": "DropdownMenu > DropdownMenuTrigger + DropdownMenuContent > DropdownMenuItem",
    "rules": [
      "DropdownMenuTrigger wraps the trigger element",
      "DropdownMenuContent contains menu items",
      "Use DropdownMenuSeparator between groups"
    ]
  }
}

Layout Recipes

Pre-defined patterns for common layouts:

import { recipes } from "@raydenui/ai";
 
const formRecipe = recipes.get("form-layout");
// Returns:
// {
//   name: "form-layout",
//   description: "Standard form with labeled inputs",
//   template: `
//     <form className="space-y-4 max-w-md">
//       <Input label="..." />
//       <Input label="..." />
//       <Button variant="primary" className="w-full">Submit</Button>
//     </form>
//   `
// }

Component Anatomy (Figma)

For building Rayden UI components in Figma using use_figma, use the anatomy module:

import {
  getAnatomy,
  getAvailableComponents,
  getComponentsByCategory,
  registry
} from "@raydenui/ai/anatomy";
 
// Get Figma layer structure for a component
const buttonAnatomy = getAnatomy("Button");
// Returns: { name, figmaName, anatomy, variants, componentProperties }
 
// List all components with anatomy specs
const components = getAvailableComponents();
 
// Get components by category
const formComponents = getComponentsByCategory("Forms & Inputs");
 
// Get all variant combinations for a component
import { getVariantCombinations } from "@raydenui/ai/anatomy";
const buttonVariants = getVariantCombinations("Button");
// Returns: [{ Variant: "Primary", Appearance: "Solid", Size: "SM", State: "Default" }, ...]

W3C DTCG Tokens

Tokens are also available in W3C Design Tokens Community Group format:

import dtcgTokens from "@raydenui/ai/tokens/dtcg";
 
// Tokens follow the DTCG spec with $value, $type, $description
console.log(dtcgTokens.color.primary["500"]);
// { $value: "#EB5017", $type: "color", $description: "Primary brand color" }

Skills (Claude Code)

Skills provide specialized workflows for Claude Code. Include the skill in your context for guided assistance.

rayden-use Skill

Build and maintain Rayden UI components directly in Figma:

import skill from "@raydenui/ai/skills/rayden-use";
 
// The skill provides instructions for:
// - Building new components in Figma from anatomy specs
// - Adding variants to existing components
// - Syncing React components to Figma
// - Composing screens using Rayden components
// - Auditing files for design system compliance

Exports

ExportDescription
@raydenui/aiMain entry with manifests, tokens, recipes, rules
@raydenui/ai/manifestsComponent prop definitions
@raydenui/ai/tokensDesign tokens (JSON)
@raydenui/ai/tokens/dtcgW3C DTCG format tokens
@raydenui/ai/anatomyFigma layer structures
@raydenui/ai/recipesLayout patterns
@raydenui/ai/rulesComposition rules
@raydenui/ai/mcpMCP server handlers
@raydenui/ai/RAYDEN_RULES.mdHuman-readable rules file
@raydenui/ai/skills/rayden-useFigma component building skill
// Main export
import { manifests, tokens, recipes, rules } from "@raydenui/ai";
 
// Individual exports
import { getComponent, getAllComponents } from "@raydenui/ai/manifests";
import { colors, shadows, typography } from "@raydenui/ai/tokens";
import { getAnatomy, getAvailableComponents } from "@raydenui/ai/anatomy";
import { getRecipe, getAllRecipes } from "@raydenui/ai/recipes";
import { compositionRules, aliases } from "@raydenui/ai/rules";
import { createServer } from "@raydenui/ai/mcp";

Use Cases

AI Code Generation

// In your AI prompt engineering
const context = `
You are generating React code using Rayden UI.
 
Available components:
${JSON.stringify(manifests.getAll())}
 
Design tokens:
${JSON.stringify(tokens)}
 
Rules:
${rules.compositionRules}
`;

IDE Extensions

// Provide autocomplete suggestions
import { manifests } from "@raydenui/ai";
 
function getPropsForComponent(componentName: string) {
  return manifests.getComponent(componentName)?.props;
}

Documentation Generation

// Generate docs from manifests
import { manifests } from "@raydenui/ai";
 
for (const component of manifests.getAll()) {
  console.log(`## ${component.name}`);
  console.log(component.description);
  console.log("### Props");
  for (const [name, prop] of Object.entries(component.props)) {
    console.log(`- \`${name}\`: ${prop.type}`);
  }
}

Package Structure

@raydenui/ai/
├── dist/
│   ├── index.js          # Main exports
│   ├── manifests/        # Component manifests
│   ├── anatomy/          # Figma layer structures
│   ├── tokens/           # Design tokens (JSON + DTCG)
│   ├── recipes/          # Layout patterns
│   ├── rules/            # Composition rules
│   └── mcp/              # MCP server
├── skills/
│   └── rayden-use/       # Figma component building skill
├── references/           # Documentation for skills
├── RAYDEN_RULES.md       # Human-readable rules file
└── package.json

Configuration

The package exposes an ai field in package.json for discovery:

{
  "ai": {
    "type": "design-system",
    "rulesFile": "RAYDEN_RULES.md",
    "manifestsDir": "dist/manifests",
    "tokensFile": "dist/tokens/tokens.json",
    "tokensDTCGFile": "dist/tokens/tokens.dtcg.json",
    "anatomyDir": "dist/anatomy",
    "skillsDir": "skills",
    "referencesDir": "references",
    "mcpServer": "dist/mcp/server.js"
  }
}

This allows AI tools to automatically discover and use Rayden UI’s capabilities.

Last updated on
Token Reference