SemianiakaVY/openpencil
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity

Restructure README: lead with screenshot and features, show CLI/AI output, move contributor docs down

Browse source
This commit is contained in:
Danila Poyarkov 2026-03-08 10:46:38 +03:00
parent af2f65b390
commit c6c681c25a
1 changed files with 92 additions and 163 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

255
README.md
View file

@ -1,100 +1,21 @@
# OpenPencil
Open-source, AI-native design editor. Figma-compatible, AI-first, fully local.
Open-source design editor. Opens Figma files, built-in AI, fully programmable.
> **Status:** Active development. Not ready for production use.
**[Try it online →](https://app.openpencil.dev/demo)** · [Download](https://github.com/open-pencil/open-pencil/releases/latest) · [Documentation](https://openpencil.dev)
> **What's next**
>
> - 100% .fig compatibility — full rendering parity with Figma
> - Shader effects (SkSL) — custom visual effects via GPU shaders
> - Skewing and OkHCL color support
> - Raster tile caching — instant zoom/pan for complex documents
> - Component libraries — publish, share, and consume design systems
> - CI tools — design linting, code export, visual regression in pipelines
> - Code signing (Apple & Azure certificates for properly signed binaries)
> - Experimental WebGPU/Graphite rendering backend
![OpenPencil](packages/docs/public/screenshot.png)
## Why
## What it does
Figma is a closed platform that actively fights programmatic access. Their [MCP server](https://www.figma.com/blog/introducing-figma-mcp-server/), launched in June 2025, was read-only — you could pull design context but not create or modify anything. [figma-use](https://github.com/dannote/figma-use) filled that gap in January 2026 with full read/write design automation via CDP. A month later, [Figma 126.1.2 started stripping `--remote-debugging-port`](https://forum.figma.com/report-a-problem-6/remote-debugging-port-not-working-in-figma-desktop-126-1-2-50858) on startup — killing CDP-based tools. Figma has since added UI-to-Figma capture via their MCP server, but it still can't programmatically create or modify design nodes.
This is a supply chain problem. Designers and developers build workflows on top of their design tool. When that tool is closed-source, the vendor controls what's possible. They can break your tooling overnight with a point release. Your design files are in a proprietary binary format that only their software can fully read.
Coding tools went through the same shift. VS Code opened the editor. LLMs opened code generation. Projects like [pi](https://github.com/mariozechner/pi-coding-agent) opened the AI coding agent. Design tools are next.
OpenPencil is:
- **Open source** — MIT license, read and modify everything
- **Figma-compatible** — opens .fig files natively, copy & paste nodes between apps
- **AI-native** — built-in chat with tool use, bring your own API key, no vendor lock-in
- **Free forever** — no account, no subscription, no internet required, ~7 MB install
- **Programmable** — headless CLI, every operation is scriptable
Your design files are yours. Your tools should be too.
## Features
- **Figma .fig file import and export** — read and write native Figma files
- **Copy & paste with Figma** — select nodes in Figma, paste into OpenPencil (and vice versa). Uses the same Kiwi binary format as .fig files
- **Real-time collaboration** — P2P via WebRTC, no server required. Cursors, presence, follow mode
- **Drawing tools** — shapes, pen tool with vector networks, rich text with system fonts, auto-layout, components with live sync, variables with modes and collections
- **AI chat** — describe what you want, the AI builds it. 87 tools wired to chat, CLI, and MCP
- **MCP server** — connect Claude Code, Cursor, or any MCP client to read/write .fig files headlessly
- **Headless CLI** — inspect, search, analyze, and render .fig files without a GUI. Run against live app via RPC bridge or standalone against .fig files
- **Tailwind CSS export** — export selections as HTML with Tailwind v4 utility classes from the Code panel, CLI, or programmatically
- **Mobile & PWA** — responsive editor with touch-optimized toolbar, swipeable drawer, installable as a Progressive Web App
- **Documentation** — full docs at [openpencil.dev](https://openpencil.dev) with 6 locales
- **~7 MB desktop app** — Tauri v2, macOS/Windows/Linux. Also runs in the browser
## Tech Stack
| Layer | Tech |
|-------|------|
| UI | Vue 3, VueUse, Reka UI |
| Styling | Tailwind CSS 4 |
| Rendering | Skia (CanvasKit WASM) |
| Layout | Yoga WASM |
| File format | Kiwi binary (vendored) + Zstd + ZIP |
| Color | culori |
| Collaboration | Trystero (WebRTC P2P) + Yjs (CRDT) + y-indexeddb |
| Desktop | Tauri v2 |
| CLI | citty, agentfmt |
| MCP | @modelcontextprotocol/sdk, Hono |
| Testing | Playwright (visual regression), bun:test (unit) |
| Tooling | Vite 7, oxlint, oxfmt, typescript-go |
## Installation
**macOS (Homebrew):**
```sh
brew install open-pencil/tap/open-pencil
```
Or download the latest release from the [releases page](https://github.com/open-pencil/open-pencil/releases/latest), or [use the web app](https://app.openpencil.dev) — no install needed.
## Getting Started
```sh
bun install
bun run dev
```
## Collaboration
Share a link to co-edit in real time. No server, no account — peers connect directly via WebRTC.
1. Click the share button in the top-right panel
2. Share the generated link (`app.openpencil.dev/share/<room-id>`)
3. Collaborators see your cursor, selection, and edits in real time
4. Click a peer's avatar to follow their viewport
All sync happens peer-to-peer via [Trystero](https://github.com/dmotz/trystero). Document state is persisted locally in IndexedDB — refreshing the page keeps your work.
- **Opens .fig files** — read and write native Figma files, copy & paste nodes between apps
- **AI builds designs** — describe what you want in chat, 90 tools create and modify nodes. Bring your own API key
- **Fully programmable** — headless CLI, Figma Plugin API via `eval`, MCP server for AI agents
- **Real-time collaboration** — P2P via WebRTC, no server, no account. Cursors, presence, follow mode
- **Tailwind CSS export** — export any selection as HTML with Tailwind v4 utility classes
- **~7 MB desktop app** — Tauri v2 for macOS, Windows, Linux. Also runs in the browser as a PWA
## CLI
@ -184,11 +105,17 @@ open-pencil eval -c "figma.currentPage.name" # Query the editor
All commands support `--json` for machine-readable output.
## MCP Server
## AI & MCP
Connect AI coding tools to read and modify `.fig` files headlessly. [Full docs →](https://openpencil.dev/reference/mcp-tools)
### Built-in chat
**Stdio** (Claude Code, Cursor, Windsurf) — add to your MCP config:
Press <kbd>⌘</kbd><kbd>J</kbd> to open the AI assistant. It has 87 tools that can create shapes, set fills and strokes, manage auto-layout, work with components and variables, run boolean operations, analyze design tokens, and export assets. Bring your own OpenRouter API key — no backend, no account.
### MCP server
Connect Claude Code, Cursor, Windsurf, or any MCP client to read and write `.fig` files headlessly. 90 tools (87 core + 3 file management). [Full docs →](https://openpencil.dev/reference/mcp-tools)
**Stdio** (Claude Code, Cursor, Windsurf):
```sh
bun add -g @open-pencil/mcp
@ -204,22 +131,13 @@ bun add -g @open-pencil/mcp
}
```
**HTTP** (scripts, browser extensions, CI):
**HTTP** (scripts, CI):
```sh
openpencil-mcp-http # http://localhost:3100/mcp
```
Security defaults for HTTP transport:
- Binds to `127.0.0.1` by default (`HOST` to override)
- `eval` tool is disabled
- File access is restricted to `OPENPENCIL_MCP_ROOT` (defaults to current working directory)
- Optional auth: set `OPENPENCIL_MCP_AUTH_TOKEN` and send `Authorization: Bearer <token>` (or `x-mcp-token`)
- CORS is disabled by default; set `OPENPENCIL_MCP_CORS_ORIGIN` to allow a specific origin
90 tools: create shapes, set fills/strokes/layout, variables, vectors, boolean ops, viewport, find nodes, open/save `.fig` files, render JSX to design nodes.
## AI Agent Skill
### AI agent skill
Teach your AI coding agent to use OpenPencil — inspect designs, export assets, analyze tokens, modify .fig files:
@ -229,81 +147,92 @@ npx skills add open-pencil/skills@open-pencil
Works with Claude Code, Cursor, Windsurf, Codex, and any agent that supports [skills](https://skills.sh).
## Scripts
## Collaboration
Share a link to co-edit in real time. No server, no account — peers connect directly via WebRTC.
1. Click the share button in the top-right panel
2. Share the generated link (`app.openpencil.dev/share/<room-id>`)
3. Collaborators see your cursor, selection, and edits in real time
4. Click a peer's avatar to follow their viewport
## Why
Figma is a closed platform that actively fights programmatic access. Their MCP server is read-only. [figma-use](https://github.com/dannote/figma-use) added full read/write automation via CDP — then [Figma 126 killed CDP](https://forum.figma.com/report-a-problem-6/remote-debugging-port-not-working-in-figma-desktop-126-1-2-50858). Your design files are in a proprietary binary format that only their software can fully read. Your workflows break when they decide to ship a point release.
OpenPencil is the alternative: open source (MIT), reads .fig files natively, every operation is scriptable, and your data never leaves your machine.
## Roadmap
- 100% .fig compatibility — full rendering parity with Figma
- Shader effects (SkSL) — custom visual effects via GPU shaders
- Skewing and OkHCL color support
- Raster tile caching — instant zoom/pan for complex documents
- Component libraries — publish, share, and consume design systems
- CI tools — design linting, code export, visual regression in pipelines
- Windows code signing (Azure certificates for properly signed binaries)
- Experimental WebGPU/Graphite rendering backend
## Installation
**macOS (Homebrew):**
```sh
brew install open-pencil/tap/open-pencil
```
Or download from the [releases page](https://github.com/open-pencil/open-pencil/releases/latest), or [use the web app](https://app.openpencil.dev) — no install needed.
## Contributing
### Setup
```sh
bun install
bun run dev # Dev server at localhost:1420
bun run tauri dev # Desktop app (requires Rust)
```
### Quality gates
| Command | Description |
|---------|-------------|
| `bun run dev` | Dev server at http://localhost:1420 |
| `bun run build` | Production build |
| `bun run check` | Lint + typecheck |
| `bun run test` | E2E visual regression |
| `bun run test:update` | Regenerate screenshot baselines |
| `bun run test:unit` | Unit tests |
| `bun run tauri dev` | Desktop app (requires Rust) |
| `bun run format` | Code formatting |
## Desktop App
Requires [Rust](https://rustup.rs/), the Tauri CLI, and platform-specific prerequisites ([Tauri v2 guide](https://v2.tauri.app/start/prerequisites/)).
```sh
bun run tauri dev # Dev mode with hot reload
bun run tauri build # Production build
bun run tauri build --target universal-apple-darwin # macOS universal
```
Cross-compilation to other platforms requires their respective toolchains or CI (e.g. GitHub Actions).
### Platform Prerequisites
#### macOS
Install Xcode Command Line Tools:
```sh
xcode-select --install
```
#### Windows
1. Install [Rust](https://rustup.rs/) — make sure the default toolchain is `stable-msvc`:
```sh
rustup default stable-msvc
```
2. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the "Desktop development with C++" workload (MSVC compiler + Windows SDK)
3. WebView2 is pre-installed on Windows 10 (1803+) and Windows 11. If missing, download from [Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
#### Linux
Install system dependencies (Debian/Ubuntu):
```sh
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
```
For other distros, see the [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/).
## Project Structure
### Project structure
```
packages/
core/ @open-pencil/core — engine (scene graph, renderer, layout, codec)
cli/ @open-pencil/cli — headless CLI (info, tree, find, export)
cli/ @open-pencil/cli — headless CLI
mcp/ @open-pencil/mcp — MCP server (stdio + HTTP)
docs/ VitePress documentation site (openpencil.dev)
src/
ai/ AI tool wiring
automation/ CLI-to-app RPC bridge (WebSocket + HTTP)
components/ Vue SFCs (canvas, panels, collaboration, color picker)
composables/ Canvas input, keyboard shortcuts, collaboration, rendering
views/ Route views
stores/ Editor state (Vue reactivity)
engine/ Re-export shims from @open-pencil/core
docs/ Documentation site (openpencil.dev)
src/ Vue app (components, composables, stores)
desktop/ Tauri v2 (Rust + config)
tests/
e2e/ Playwright E2E tests (188 tests)
engine/ Unit tests (764 tests)
helpers/ Test utilities (canvas interaction, store access)
tests/ E2E (188 tests) + unit (764 tests)
```
### Tech stack
| Layer | Tech |
|-------|------|
| Rendering | Skia (CanvasKit WASM) |
| Layout | Yoga WASM |
| UI | Vue 3, Reka UI, Tailwind CSS 4 |
| File format | Kiwi binary + Zstd + ZIP |
| Collaboration | Trystero (WebRTC P2P) + Yjs (CRDT) |
| Desktop | Tauri v2 |
| AI/MCP | OpenRouter, @modelcontextprotocol/sdk, Hono |
### Desktop builds
Requires [Rust](https://rustup.rs/) and platform-specific prerequisites ([Tauri v2 guide](https://v2.tauri.app/start/prerequisites/)).
```sh
bun run tauri build
```
## Acknowledgments