From c6c681c25af66f2a943fcfdec9d6791f5399e89c Mon Sep 17 00:00:00 2001 From: Danila Poyarkov Date: Sun, 8 Mar 2026 10:46:38 +0300 Subject: [PATCH] Restructure README: lead with screenshot and features, show CLI/AI output, move contributor docs down --- README.md | 255 ++++++++++++++++++++---------------------------------- 1 file changed, 92 insertions(+), 163 deletions(-) diff --git a/README.md b/README.md index aa4201243..30c69aa09 100644 --- a/README.md +++ b/README.md @@ -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/`) -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 ⌘J 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 ` (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/`) +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