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