npm package: @superduperui/context
Description: Design system context for AI coding agents — MCP server + CLI + live preview
Latest version: 0.1.6

# @superduperui/context

**Give your AI agent a design system in one command.**

[![npm version](https://img.shields.io/npm/v/@superduperui/context)](https://www.npmjs.com/package/@superduperui/context)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-blue)](https://nodejs.org)

An MCP server and CLI that gives AI coding agents structured design system context — tokens, components, rules — so they produce on-brand UI instead of generic code.

---

## Quick Start

Get set up in 60 seconds.

```bash
# Initialise your project with a starter kit
npx @superduperui/context init --kit linear-lite

# Auto-configure your AI coding agent
npx @superduperui/context install
```

That's it. The `install` command detects Claude Code, Cursor, and Windsurf automatically and configures the MCP server for the current project.

Your agent now has access to your full design system on every request.

---

## What It Does

AI coding agents don't know your design system. They produce UI that looks generic, uses hardcoded colours, ignores your spacing scale, and references components that don't exist.

`@superduperui/context` solves this by exposing your design system — tokens, components, rules — as MCP tools. Your agent calls `get_design_system` before writing UI, `get_tokens` when it needs exact values, and `check_compliance` before it finishes. The result is on-brand code from the first attempt.

---

## MCP Tools

Ten tools are registered with the MCP server automatically.

| Tool | Description |
|------|-------------|
| `get_design_system` | Returns the full DESIGN.md, or a filtered section (colours, typography, spacing, components). Use this before writing any UI. |
| `get_tokens` | Returns design tokens in CSS custom properties, W3C DTCG JSON, or Tailwind config format. |
| `get_component` | Returns the spec and code example for a named component. |
| `list_components` | Lists all components defined in the active kit. |
| `check_compliance` | Validates a code snippet against the design system — flags hardcoded colours, bad spacing, unknown tokens, and unrecognised components. |
| `preview` | Pushes a component to the local live preview canvas at `localhost:4321`. Requires the preview server to be running. |
| `push_to_figma` | Bridges to the Figma MCP server to create an editable Figma frame from component code. Requires Figma MCP to be configured separately. |
| `design_in_figma` | Takes a natural language prompt (e.g. "A pricing card with 3 tiers") and returns design tokens, component specs, and step-by-step instructions for calling Figma MCP's `generate_figma_design`. Enables AI agents to design in Figma before writing code. Inputs: `prompt` (required), `fileKey` (optional), `viewports` (optional: desktop/tablet/mobile). |
| `url_to_figma` | Captures a live website URL as editable Figma frames with auto-layout. Inputs: `url`, `viewports`, `outputMode` (newFile/existingFile/clipboard), `fileKey`. Requires both Figma MCP and Playwright MCP servers. |
| `update_tokens` | Updates token values in `tokens.css`, `tokens.json`, and `DESIGN.md` simultaneously. Use when tweaking colours, spacing, or other tokens without re-extracting. Keeps the entire design system consistent. |

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `init` | Initialise `.superduper/` in the current directory, optionally with a starter kit. |
| `init --kit <name>` | Initialise with a specific kit (e.g. `linear-lite`). |
| `serve` | Start the MCP server. This is what your AI agent connects to. |
| `install` | Auto-configure MCP settings for Claude Code, Cursor, and Windsurf in one step. |
| `install --target <tool>` | Target a specific tool: `claude`, `cursor`, or `windsurf`. |
| `install --global` | Install globally so the MCP server is available in all projects (Claude Code only). |
| `list` | List all available kits (free and pro). |
| `use <kit>` | Switch the active kit in an existing `.superduper/` directory. |
| `import <path>` | Import a design system bundle exported from SuperDuper AI Studio (`.zip`). |

**Examples:**

```bash
# Start with the Linear-inspired dark kit
npx @superduperui/context init --kit linear-lite

# Start with a blank template and write your own DESIGN.md
npx @superduperui/context init

# Auto-configure MCP settings for all supported editors
npx @superduperui/context install

# Auto-configure for Claude Code only
npx @superduperui/context install --target claude

# Install globally (available in all projects — each project uses its own .superduper/)
npx @superduperui/context install --global

# Switch to a different kit
npx @superduperui/context use stripe-lite

# See all available kits
npx @superduperui/context list

# Import a bundle from AI Studio
npx @superduperui/context import ./my-design-export.zip
```

---

## Available Kits

Three free starter kits are included. Premium kits are available at [superduperui.com/kits](https://superduperui.com/kits).

### Free

| Kit | Aesthetic | Description |
|-----|-----------|-------------|
| `linear-lite` | Dark, minimal, developer-focused | Developer tool design system inspired by Linear |
| `stripe-lite` | Light, clean, high-trust | Payment UI design system inspired by Stripe |
| `notion-lite` | Light, content-first, block-based | Productivity design system inspired by Notion |

### Pro

| Kit | Aesthetic | Components |
|-----|-----------|------------|
| `linear` | Dark, minimal, developer-focused | 24 components, all tokens |
| `stripe` | Light, clean, high-trust | 20 components, all tokens |
| `notion` | Light, content-first, block-based | 22 components, all tokens |
| `revolut` | Dark fintech, data-rich | 30 components, all tokens |
| `airbnb` | Warm, rounded, photo-forward | 25 components, all tokens |
| `tiktok` | Dark, vibrant, video-first | 28 components, all tokens |
| `netflix` | Dark, cinematic, content-forward | 18 components, all tokens |

---

## Setup Guides

The easiest way to configure any supported editor is:

```bash
npx @superduperui/context install
```

This auto-detects Claude Code, Cursor, and Windsurf and configures the MCP server. For Claude Code it uses `claude mcp add` (the reliable method); for Cursor and Windsurf it writes the appropriate config file.

### Per-Project vs Global

By default, the MCP server is registered **per-project**. Each project needs its own `install`.

For users working across multiple projects, install globally:

```bash
npx @superduperui/context install --global
```

The MCP server always reads `.superduper/` from the current working directory, so each project uses its own design system — even with a global install.

### Manual Setup

If you prefer to configure manually:

**Claude Code** (`.claude/settings.json`):

```json
{
  "mcpServers": {
    "superduper": {
      "command": "npx",
      "args": ["-y", "@superduperui/context", "serve"]
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "superduper": {
      "command": "npx",
      "args": ["-y", "@superduperui/context", "serve"]
    }
  }
}
```

**Windsurf** (`.windsurf/mcp.json`):

```json
{
  "mcpServers": {
    "superduper": {
      "command": "npx",
      "args": ["-y", "@superduperui/context", "serve"]
    }
  }
}
```

---

## Live Preview

The `preview` MCP tool and the preview canvas work together to give you visual verification without leaving your agent session.

Start the preview server alongside the MCP server:

```bash
npx @superduperui/context serve
```

The preview canvas opens at `http://localhost:4321`. It features:

- Dark UI with your active kit's design tokens applied
- WebSocket-powered live updates — components render as the agent pushes them
- Viewport toggles (mobile, tablet, desktop)
- Source code panel to inspect what was rendered
- TSX transpilation on the server — no browser-side build step

When your agent calls the `preview` tool with a component, it appears in the canvas within milliseconds. Open the canvas in a browser tab alongside your editor and you have a live design review loop without any manual copy-paste.

---

## Figma Integration

Three MCP tools bridge the gap between design and code using the [Figma MCP server](https://www.figma.com/developers/mcp): `push_to_figma`, `design_in_figma`, and `url_to_figma`.

### Setup

Add the Figma MCP server to your agent config alongside `design-context`. It uses OAuth — no API key required:

```bash
claude mcp add --transport http figma https://mcp.figma.com/mcp
```

Then authenticate when prompted. The Figma MCP server will open a browser tab for OAuth consent.

### Figma Tools

| Tool | What It Does |
|------|--------------|
| `push_to_figma` | Creates an editable Figma frame from component code. Returns a structured prompt for Figma MCP's `generate_figma_design`. |
| `design_in_figma` | Takes a natural language prompt and returns design tokens, component specs, and step-by-step instructions for `generate_figma_design`. Design in Figma before writing any code. |
| `url_to_figma` | Captures a live website URL as editable Figma frames with auto-layout. Requires Playwright MCP alongside Figma MCP. |

### The Closed Loop

```
Developer prompts AI → AI calls get_design_system → generates TSX
        ↓
AI calls preview → renders at localhost:4321
        ↓
AI calls push_to_figma → editable frame in Figma
        ↓
Designer reviews → AI reads changes via Figma MCP → updates code
```

When `push_to_figma` is called, it returns a structured prompt ready to pass to the Figma MCP's `generate_figma_design` tool, including your component code and the relevant design tokens extracted from the active kit.

---

## Custom Design Systems

You don't need a pre-built kit. You can write your own `DESIGN.md` and the MCP server will use it.

**1. Create the `.superduper/` directory:**

```bash
npx @superduperui/context init
```

This creates a blank template at `.superduper/DESIGN.md` for you to fill in.

**2. Edit `DESIGN.md` with your design system:**

```markdown
# My Design System

## Colours

| Token | Value | Usage |
|-------|-------|-------|
| --color-primary | #0F172A | Primary actions |
| --color-background | #FFFFFF | Page background |

## Typography

- **Font family:** Inter, system-ui, sans-serif
- **Base size:** 16px

## Components

### Button

Primary action button. Uses --color-primary as background.
```

**3. Optionally add token files:**

```
.superduper/
├── kit.json          # Metadata (name, version, description)
├── DESIGN.md         # Human-readable design system spec
├── tokens.css        # CSS custom properties
├── tokens.json       # W3C DTCG tokens (optional)
└── tailwind.config.js  # Tailwind theme extension (optional)
```

**4. Start the MCP server:**

```bash
npx @superduperui/context serve
```

The server reads whatever is in `.superduper/` — no configuration needed.

---

## On-Disk Structure

```
.superduper/
├── kit.json            # Kit metadata (name, version, tier, component count)
├── DESIGN.md           # Full design system spec — this is what agents read
├── tokens.css          # CSS custom properties for all tokens
├── tokens.json         # W3C DTCG tokens.json (for tooling integration)
└── tailwind.config.js  # Tailwind theme config matching the token set
```

All files are plain text and checked into version control. Your whole team gets the same design context.

---

## AI Studio Integration

[SuperDuper AI Studio](https://studio.superduperui.com) extracts design systems from Figma files and live websites, then exports them as a `.zip` bundle ready for import.

Use AI Studio to:

- Extract tokens and components from an existing Figma file
- Scrape a live website's design system (colours, typography, spacing, components)
- Generate a structured `DESIGN.md` using Claude
- Export a bundle containing `DESIGN.md`, `tokens.css`, `tokens.json`, and `tailwind.config.js`

### Importing an AI Studio Export

```bash
npx @superduperui/context import ./my-design-export.zip
```

This extracts the bundle into `.superduper/` and automatically merges design system rules into your project's root `CLAUDE.md` (using HTML comment markers for idempotent updates). Re-importing replaces the previous section cleanly.

After importing, run `npx @superduperui/context install` to connect the MCP server.

---

## Compliance Checker

The `check_compliance` tool validates a code snippet against your active kit and returns a structured result.

### Rules

| Rule | Severity | What It Catches |
|------|----------|-----------------|
| `hardcoded-colours` | Error | Hex values (`#fff`, `#6366F1`) and `rgb()`/`rgba()` that should reference tokens |
| `hardcoded-spacing` | Warning | `margin: 12px` and similar pixel values that should use the spacing scale |
| `missing-token-reference` | Warning | `var(--unknown-token)` calls not present in `tokens.css` |
| `unknown-component` | Info | JSX components not listed in the kit's component inventory |

### Response Shape

```json
{
  "passed": false,
  "issues": [
    {
      "rule": "hardcoded-colours",
      "severity": "error",
      "line": 4,
      "message": "Hardcoded colour '#6366F1' — use var(--color-accent) instead"
    },
    {
      "rule": "unknown-component",
      "severity": "info",
      "line": 12,
      "message": "Component 'Tooltip' is not in the active kit's component list"
    }
  ]
}
```

### Recommended Agent Workflow

```
1. get_design_system          — read the spec before writing
2. get_tokens(format: "css")  — get exact token values
3. [write component code]
4. check_compliance(code)     — verify before finishing
5. preview(code)              — visual check
```

---

## Contributing

PRs are welcome. The project is MIT licensed.

```bash
git clone https://github.com/superduperui/context.git
cd context
npm install
npm run build
```

The source is in `src/`. Key directories:

- `src/mcp/tools/` — MCP tool handlers (one file per tool)
- `src/kit/` — Kit loading, parsing, and registry
- `src/compliance/` — Compliance rules
- `src/preview/` — Preview server and WebSocket handler
- `src/cli/` — CLI command implementations

---

## License

MIT — see [LICENSE](./LICENSE).

---

Powered by [SuperDuper](https://superduperui.com).