kiyas

git clone https://github.com/saiffmirza/kiyas && cd kiyas
npm install
npm run desktop        # dev mode
# or package a .app/.dmg:
cd apps/desktop && npx electron-builder --mac

                          ┌─────────────────────┐
                          │  kiyas               │
                          │  (MCP server / CLI)  │
                          │                      │
                          │  figma / design img  │
                          │  + target/component  │
                          └──────────┬───────────┘
                                     │
                      ┌──────────────┼──────────────┐
                      ▼              ▼               ▼
              ┌──────────────┐ ┌───────────┐ ┌─────────────┐
              │ 1. Auth      │ │ 2. Design │ │ 3. Resolve  │
              │              │ │  Capture  │ │  Component  │
              │ Verify       │ │           │ │             │
              │ Claude Code  │ │ Figma API │ │ AI agent    │
              │ or Codex CLI │ │ PNG export│ │ searches    │
              │ is installed │ │ — or your │ │ codebase,   │
              │ & signed in  │ │ own image │ │ finds URL + │
              │              │ │ (--design)│ │ CSS selector│
              └──────┬───────┘ └─────┬─────┘ └──────┬──────┘
                     │               │               │
                     │               ▼               ▼
                     │        ┌────────────┐  ┌────────────┐
                     │        │  Figma     │  │ Playwright │
                     │        │  design    │  │ screenshot │
                     │        │  (PNG)     │  │ (PNG)      │
                     │        └─────┬──────┘  └─────┬──────┘
                     │              │               │
                     │              └───────┬───────┘
                     │                      ▼
                     │          ┌──────────────────────┐
                     └─────────►│ 4. Vision AI Compare │
                                │                      │
                                │ Both images sent to  │
                                │ Claude Code CLI with │
                                │ a structured prompt   │
                                │                      │
                                │ Returns JSON array   │
                                │ of discrepancies     │
                                └──────────┬───────────┘
                                           │
                                           ▼
                                ┌──────────────────────┐
                                │ 5. HTML Report       │
                                │                      │
                                │ Side-by-side images  │
                                │ Severity badges      │
                                │ Interactive filters  │
                                │ HIGH / MEDIUM / LOW  │
                                │                      │
                                │ file:// link in      │
                                │ terminal output      │
                                └──────────────────────┘

npm install -g kiyas-cli
npx playwright install chromium

claude mcp add kiyas -- npx -y kiyas-cli@latest mcp

# with a Figma token (only needed for Figma-URL comparisons):
claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=figd_xxx -- npx -y kiyas-cli@latest mcp

{
  "mcpServers": {
    "kiyas": {
      "command": "npx",
      "args": ["kiyas-cli@latest", "mcp"]
    }
  }
}

[mcp_servers.kiyas]
command = "npx"
args    = ["kiyas-cli@latest", "mcp"]

claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=<your-token> -- npx -y kiyas-cli@latest mcp

{
  "mcpServers": {
    "kiyas": {
      "command": "npx",
      "args": ["kiyas-cli@latest", "mcp"],
      "env": { "FIGMA_ACCESS_TOKEN": "your-token" }
    }
  }
}

npm install -g kiyas-cli
npx playwright install chromium

kiyas setup

# Describe the component by name — kiyas finds it automatically
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "eventHeader on the redemption screen"

# Or provide a direct URL if you already know it
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --target "http://localhost:3000/redemption" \
  --selector ".event-header"

# Save the report to a specific path
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "primary button" \
  --output report.html

# Output as JSON (for CI pipelines)
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "primary button" \
  --format json

# Compare against a design screenshot instead of Figma (no Figma token needed)
kiyas --design ./design.png \
  --component "primary button" \
  --output report.html

# Use OpenAI instead of Claude
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "nav bar" \
  --model openai

# 1. Record a session — log in, then close the browser. Playwright writes auth.json.
npx playwright codegen --save-storage=auth.json https://app.example.com

# 2. Use it for kiyas screenshots
kiyas \
  --figma "https://www.figma.com/design/.../?node-id=1:234" \
  --target "https://app.example.com/dashboard" \
  --auth-state ./auth.json

# Install Claude Code if you haven't already
npm install -g @anthropic-ai/claude-code

# Sign in
claude auth login

codex auth login

Claude Code is not installed or not signed in.

kiyas uses your existing Claude Code subscription — no API keys needed.

To fix this, either:

  1. Install and sign into Claude Code:
     npm install -g @anthropic-ai/claude-code
     claude auth login

  2. Or switch kiyas to use OpenAI instead:
     kiyas set model openai
     (requires signing into Codex: codex auth login)

{
  "figmaAccessToken": "env:FIGMA_ACCESS_TOKEN",
  "model": "claude",
  "viewport": "1280x720",
  "comparisons": [
    {
      "name": "Primary Button",
      "figma": "https://www.figma.com/design/abc123/Design?node-id=1:234",
      "target": "primary button on the login page"
    },
    {
      "name": "Event Card",
      "figma": "https://www.figma.com/design/abc123/Design?node-id=5:678",
      "target": "http://localhost:6006/iframe.html?id=card--event",
      "selector": ".event-card"
    }
  ]
}

kiyas --config ./kiyas.config.json

kiyas/  (npm workspaces monorepo)
├── packages/
│   ├── core/                       # @kiyas/core — the engine (private, bundled into the CLI)
│   │   └── src/
│   │       ├── index.ts            # Public API barrel (runComparison, resolveComponent, …)
│   │       ├── config.ts           # Config file loading + Figma token resolution
│   │       ├── settings.ts         # Persisted user settings
│   │       ├── auth/
│   │       │   ├── index.ts        # Auth resolver (picks best available auth)
│   │       │   ├── claude-oauth.ts # Verify Claude Code CLI is available
│   │       │   └── openai-auth.ts  # Verify Codex CLI is available
│   │       ├── resolve/
│   │       │   └── component.ts    # AI agent: finds component in codebase → URL + selector
│   │       ├── capture/
│   │       │   ├── figma.ts        # Figma REST API: export frame as PNG + metadata
│   │       │   └── playwright.ts   # Playwright: headless screenshot of rendered component
│   │       ├── compare/
│   │       │   ├── index.ts        # Orchestrator: sends images to vision AI
│   │       │   ├── pipeline.ts     # Pure runComparison() + report persistence (shared by CLI + MCP)
│   │       │   ├── claude.ts       # Claude comparison via Claude Code CLI
│   │       │   ├── openai.ts       # OpenAI comparison via Codex CLI
│   │       │   └── prompt.ts       # The comparison prompt (shared across providers)
│   │       ├── report/
│   │       │   └── html.ts         # Generate self-contained HTML report with embedded images
│   │       └── utils/
│   │           ├── parse-figma-url.ts  # Extract file key + node ID from Figma URL
│   │           └── logger.ts       # Minimal logging utility
│   └── cli/                        # kiyas-cli — the published npm package
│       ├── src/
│       │   ├── index.ts            # CLI entry point (argument parsing, orchestration)
│       │   ├── setup.ts            # Interactive first-time setup
│       │   └── mcp/
│       │       ├── server.ts       # MCP server bootstrap (stdio transport)
│       │       └── tools.ts        # Zod schemas + handlers (compare, get_diff_report, list_issues)
│       ├── package.json
│       └── tsup.config.ts
├── apps/
│   └── desktop/                    # @kiyas/desktop — Electron app (macOS)
│       ├── src/
│       │   ├── main/               # Main process: IPC, capture flow, pty terminal
│       │   ├── preload/            # Typed context bridge (window.kiyas)
│       │   └── renderer/           # React UI (cream/navy/gold theme, dark mode)
│       ├── build/kiyas.icon        # Icon Composer bundle (Liquid Glass icon source)
│       ├── scripts/gen-icon.mjs    # Renders all icon variants from the Farisi kāf
│       └── electron-builder.yml
├── eval/                           # Golden eval set + scoring harness
├── .env.example
├── .kiyasrc.example
├── package.json                    # Workspace root
└── tsconfig.json