component-contracts

component-contracts

Two MCP servers that form the authority layer for design-to-code component lifecycles.

Overview

Variant Authority is the engineering contract for your component library. It defines what variants exist on a component, what slots are required, how design tokens map between Figma and code, and what happens when a component is deprecated. When a variant surface changes, it classifies the diff as major, minor, or patch so consumers know the impact before shipping.

Radix Primitives is the accessibility foundation. It maps component types to Radix UI primitives, exposes the ARIA contracts and keyboard interactions that come free with each primitive, and documents known caveats and workarounds. Together, these two servers are the source of truth that d2c operates on -- one for structural correctness, the other for accessible composition.

Tool surface

Variant Authority (5 tools)

| Tool | Description | |---|---| | get_manifest(component) | Returns the full variant manifest | | set_manifest(component, manifest) | Writes or updates a manifest, validates with isVariantManifest() | | get_usage(component) | Scans workspace for files importing the component | | diff_manifests(component, before, after) | Classifies changes as major/minor/patch | | validate_usage(component, props) | Validates variant values and required slots |

Radix Primitives (4 tools)

| Tool | Description | |---|---| | get_primitive(name) | Returns accessibility contract, composition pattern, caveats | | get_composition_pattern(component) | Maps a component type to its Radix primitive | | get_caveats(primitive) | Returns known issues and workarounds | | list_primitives() | Enumerates all 16 available primitives |

VariantManifest schema

interface VariantManifest {
  component: string;
  version: string;
  figmaFileKey: string;
  figmaNodeId: string;
  variants: Record<string, VariantDefinition>;
  slots: SlotDefinition[];
  tokens: Record<string, TokenBinding>;
  authority: AuthorityMap;
  deprecated?: DeprecationInfo;
  semanticTokenFile?: string;
  createdAt: string;
  updatedAt: string;
}

interface VariantDefinition {
  values: string[];
  defaultValue: string;
  type: "string" | "boolean" | "number";
  description?: string;
}

interface SlotDefinition {
  name: string;
  required: boolean;
  description?: string;
}

interface TokenBinding {
  figmaValue: string;
  codeValue: string;
  dtcgPath: string;
  category: "color" | "spacing" | "typography" | "border" | "shadow" | "opacity";
}

interface AuthorityMap {
  structure: "figma" | "cva";
  visual: "figma" | "cva";
  conflictStrategy: "escalate" | "figma-wins" | "cva-wins";
}

interface DeprecationInfo {
  deprecated: true;
  replacedBy: string;
  migrationGuide: string;
  deprecatedAt: string;
  removalTarget?: string;
}

PrimitiveCapability schema

interface PrimitiveCapability {
  name: string;
  radixPackage: string | null;
  vuePackage: string | null;
  accessibilityContract: {
    role: string;
    keyboardInteractions: string[];
    ariaAttributes: string[];
  };
  compositionPattern: string;
  caveats: string[];
  recommendedFor: string[];
  avoidFor: string[];
  version: string;
}

Installation

Claude Code

claude mcp add variant-authority -- npx tsx src/variant-authority/server.ts
claude mcp add radix-primitives -- npx tsx src/radix-primitives/server.ts

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "variant-authority": {
      "command": "npx",
      "args": ["tsx", "src/variant-authority/server.ts"]
    },
    "radix-primitives": {
      "command": "npx",
      "args": ["tsx", "src/radix-primitives/server.ts"]
    }
  }
}

Codex CLI

codex mcp add variant-authority -- npx tsx src/variant-authority/server.ts
codex mcp add radix-primitives -- npx tsx src/radix-primitives/server.ts

Development

npm scripts

| Script | Purpose | |---|---| | npm run build | Compile TypeScript with tsc | | npm test | Run tests with Vitest | | npm run dev:va | Start variant-authority server in dev mode | | npm run dev:rp | Start radix-primitives server in dev mode |

Project structure

component-contracts/
  src/
    variant-authority/
      server.ts             MCP server entry point
      registry.ts           JSON registry read/write
    radix-primitives/
      server.ts             MCP server entry point
      capability-map.ts     Static primitive data
    shared/
      schemas.ts            TypeScript interfaces + validation
      errors.ts             Shared error types
  dist/                     Compiled output
  .variant-authority/       Registry storage (gitignored in consuming repos)

Relationship to d2c

component-contracts provides the authority layer. d2c provides the lifecycle operator. During its phases, d2c calls these MCP servers to read and write variant manifests, query primitive mappings, and validate component usage. The two packages are designed to work together but can be used independently -- any tooling that needs a persistent variant registry or a Radix capability map can consume these servers directly.

License

MIT