Majin

Pixel-perfect design parity between Figma and browser. Select an element in your app, select the matching node in Figma, and get an instant diff report in the Majin dock (with a “Copy prompt” button for Claude/Codex).

60-Second Setup (One Command, No MCP)

In your React project:

npx -y @thxlion/majin-mcp@latest dev

This starts the Majin hub (ws://localhost:3847), starts your dev server, and shows the Majin dock in your browser.

Non-Technical Install (Copy/Paste)

If you use Claude/Codex as your “installer”, paste this:

In my React project, run npx -y @thxlion/majin-mcp@latest dev. If it can’t auto-add the overlay, add <MajinOverlay /> to my root component. Then help me verify the Majin dock is connected and I can compare.

Packages (npm)

Package	npm	Description
@thxlion/majin-schema	npm	Core types, validators, gradient conversion
@thxlion/majin-react	npm	React <MajinOverlay> component
@thxlion/majin-diff-engine	npm	Comparison engine with tolerances
@thxlion/majin-mcp	npm	MCP server with WebSocket hub

Architecture

┌─────────────────┐              ┌─────────────────┐
│   Browser App   │              │  Figma Plugin   │
│ <MajinOverlay>  │              │                 │
└────────┬────────┘              └────────┬────────┘
         │ WebSocket :3847                │ WebSocket :3847
         │                                │
         └────────────┬───────────────────┘
                      │
            ┌─────────▼─────────┐
            │   Majin Hub       │
            │ @thxlion/majin-mcp│
            └───────────────────┘

Quick Start

Step 1 (One Command): Start Majin

Run this in your React project:

npx -y @thxlion/majin-mcp@latest dev

This single command:

• Installs @thxlion/majin-react (if needed)
• Best-effort adds <MajinOverlay /> to your app (common setups)
• Starts the Majin hub (ws://localhost:3847)
• Starts your app dev server (dev script)

Step 2: Add the Overlay to Your App

If dev couldn’t inject it automatically, add this once near your root:

import { MajinOverlay } from "@thxlion/majin-react";

function App() {
  return (
    <>
      <YourApp />
      <MajinOverlay />
    </>
  );
}

This renders the Majin dock. Use it to connect, pick elements, compare, and copy prompts.

Step 3: Install the Figma Plugin

Recommended: Install from Figma Community:

https://www.figma.com/community/plugin/1597066716629047399

If you can’t find it yet (pending review), use the dev install steps below.

Dev install (today):

1. Clone this repo: git clone https://github.com/thxlion/majin
2. Build: cd majin && pnpm install && pnpm build
3. In Figma: Plugins → Development → Import plugin from manifest
4. Select packages/figma-plugin/manifest.json

Step 4: Compare Elements

1. Browser: In the dock, click Connect → Pick → click the element to select
2. Figma: Select matching layer → click "Confirm" in plugin
3. Browser: Click Compare in the dock to see the diff
4. (Optional) Click Copy prompt and paste into Claude/Codex

Advanced Setup (Manual)

If you prefer not to use dev, you can run the hub and add the overlay manually.

Start the Hub

npx -y @thxlion/majin-mcp@latest hub

Install the Overlay

npm install @thxlion/majin-react

Add the Overlay

import { MajinOverlay } from "@thxlion/majin-react";

<MajinOverlay />

Optional: MCP Tools (Claude/Codex)

You don’t need MCP anymore to compare — the browser dock can run diffs and copy a prompt. If you still want agent tools like majin_compare, configure MCP:

Claude Code (CLI)

Add to ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "majin": {
      "command": "npx",
      "args": ["-y", "@thxlion/majin-mcp@latest"]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.majin]
command = "npx"
args = ["-y", "@thxlion/majin-mcp@latest"]

MCP Tools (Optional)

Tool	Description	Usage
majin_status	Check pairing state and connected clients	Call anytime to see what's connected
majin_compare	Run diff between paired browser/Figma selections	Call anytime (waits for both selections by default)
majin_clear	Reset pairing state	Call to start fresh

Example Claude Code Usage

User: Check if Majin is ready

Claude: [calls majin_status]
→ Status: ready
→ Browser: element ".hero-button" selected
→ Figma: node "Primary Button" selected

Claude: [calls majin_compare]
→ Returns diff report with errors, warnings, and CSS fixes

Diff Output Format

# Design Parity Report

❌ Found **5 difference(s)**: 3 errors, 2 warnings

## Errors (Critical - must fix)

  ❌ `width`: expected 200px, got 196px (Δ4px)
  ❌ `background`: expected #667EEAFF, got #6B73EAFF
  ❌ `borderRadius.topLeft`: expected 16px, got 12px

## Warnings (Should fix)

  ⚠️ `text.runs[0].lineHeight`: expected 24px, got 22px

## Suggested CSS Fixes

```css
width: 200px;
background-color: #667EEA;
border-top-left-radius: 16px;
line-height: 24px;

## Tolerances

The diff engine uses these tolerances to avoid noise:

| Property | Tolerance |
|----------|-----------|
| Dimensions (width/height) | ±1px |
| Colors (RGB channels) | ±2 |
| Opacity | ±0.01 |
| Border radius | ±1px |
| Font size | ±1px |
| Line height | ±2px |
| Letter spacing | ±0.5px |

## ExtractedNode Schema

Both browser and Figma extract to this common format:

```typescript
interface ExtractedNode {
  name: string;
  type: "container" | "text" | "image" | "shape" | "component" | "group";
  source: "figma" | "browser";

  // Dimensions
  width: number;
  height: number;

  // Visual
  opacity: number;
  background: string | null;        // CSS color or gradient
  borderRadius: BorderRadius | null;
  boxShadow: BoxShadow[];
  border: Border | null;

  // Layout
  layout: {
    mode: "flex" | "grid" | "absolute" | "none";
    direction: "row" | "column";
    gap: number;
    padding: BoxSpacing;
    alignItems: string;
    justifyContent: string;
  } | null;

  // Text (for text nodes)
  text: {
    content: string;
    runs: TextRun[];  // Supports mixed formatting
  } | null;

  // Children
  children: ExtractedNode[];

  // Source mapping (browser only, for React/Vue/Svelte)
  sourceLocation: {
    fileName: string;
    lineNumber: number;
    columnNumber: number;
  } | null;
}

Development

git clone https://github.com/thxlion/majin
cd majin
pnpm install
pnpm build
pnpm test  # 174 tests

# Run example app
pnpm --filter @thxlion/majin-example dev

# Run MCP server in dev mode
pnpm --filter @thxlion/majin-mcp dev

Troubleshooting

"Waiting for Figma..." won't go away

• Make sure Figma plugin is running and connected (check plugin UI for connection status)
• Both browser and Figma must connect to the same MCP server (port 3847)

Claude Code doesn't see majin tools

• Check ~/.claude/mcp_servers.json config
• Restart Claude Code after adding the config
• Run majin_status to verify connection

Diff shows too many differences

• Make sure you selected the correct matching elements
• Some Figma properties (like auto-layout) may render differently in browser

License

MIT