Pixelcraft

Local Figma Design plugin: convert one selected illustration or frame to editable, square-grid vector art. Built with Bun, strict TypeScript and locally bundled FigUI3. No runtime CDN, server, API key or network permission.

Run locally

The repository already includes a generated dist/ in this working copy. In the Figma desktop application, open Plugins → Development → Import plugin from manifest… and select this repository's manifest.json. Run Pixelcraft Local. This is a separate local development plugin; it does not replace or publish the hosted original.

For subsequent development:

bun install --frozen-lockfile
bun run check
bun run dev

If Bun is not on your PATH, a project-local Bun is included as a development dependency. In this prepared checkout you can use npm run check and npm run dev, or ./node_modules/.bin/bun. On a fresh checkout without Bun, bootstrap with npm install, then use npm run build. Bun's lockfile is the canonical reproducible dependency lock; prefer Bun for ongoing installs.

dev rebuilds when src/ changes. Re-run the plugin in Figma after a rebuild. Source files are modular; dist/ui.html is deliberately self-contained because Figma loads a single UI HTML resource. Do not edit generated files. No local server is necessary.

Use

1. Select one source and choose Use selection.
2. Adjust grid resolution and cell size. Refresh explicitly if the original artwork changes.
3. Choose Full colour, Auto (2–64 colours), or a custom hex palette.
4. Review the preview and layer count, then Create vector art.

Full colour is the default and keeps the exact sampled 8-bit RGB values. It can produce thousands of colour layers on photographs. Auto creates a smaller palette. Source backgrounds remain part of the artwork. Remove an unwanted background in the original before capturing it. Cleanup and outline are optional; cleanup can remove isolated highlights. Output is a new frame to the right of the source, grouped into editable vector paths by colour.

Architecture

src/core/       Pure colour, palette, sampling, cleanup and vector-packing logic
src/shared/     Typed messages and data shared by host and UI
src/plugin/     Figma capture and transactional document insertion
src/ui/         FigUI3 panel, settings, decoding, preview and revision state
scripts/        Bun bundling, watch and browser smoke check
tests/         Bun regression tests (no Figma installation needed)

• Culori owns RGB → OKLab conversion, hex parsing and formatting. No handwritten colour matrices.
• ml-kmeans owns clustering. Seeded initialization and bounded iterations produce repeatable palettes. Actual sampled colours nearest the centroids become representatives.
• FigUI3 core is bundled from @rogieking/figui3, including its CSS. Editor/lab add-ons are not imported. See THIRD_PARTY.md.
• Bun builds FigUI3 as an explicit entrypoint to preserve component-registration side effects, builds the UI and host separately, bundles CSS, and embeds the UI bundle in an HTML template. A build failure exits unsuccessfully.

The pipeline captures to an explicitly sRGB PNG at 1024 pixels on the longer dimension. For each square cell, 8×8 subcell samples determine alpha coverage. The nearest visible subcell sample to the centre supplies the RGB value. Full colour retains it; Auto clusters occupied cell colours in OKLab; Custom maps to the nearest provided colour. This intentionally replaces the old palette-first dominant voting scheme: every mode now starts with the same sampled colour baseline.

Palette computation yields between clustering iterations; sampling yields between row batches. Revision tokens cancel obsolete work and disable Create as soon as settings change. Capture request IDs discard out-of-order responses. Creation uses the settings saved with the displayed grid.

Packing merges identical horizontal runs vertically and creates closed rectangle subpaths per colour (up to 512 rectangles per path). Geometry is normalized to each vector's own origin with explicit placement, avoiding accidental shifts. The host validates grid dimensions, indices and RGB ranges. Failed insertion removes the owned output frame and children.

Verification

bun run check        # strict typecheck, regression tests, production build
bun run test:browser # compiled UI in headless Chromium
bun run format

Install the Playwright Chromium browser once with bunx playwright install chromium, or set CHROME_EXECUTABLE to an existing compatible Chrome/Chromium executable. Browser smoke uses a synthetic PNG and simulated host messages; it does not claim to test the Figma document API. Screenshots are written to ignored test-results/.

Before distributing, run in Figma with a rotated group, masks, effects, a transparent icon and a photograph. Check capture bounds, vector placement, undo and failure recovery in the actual Figma runtime. Pure core tests and browser checks cannot establish those host behaviors. Very large Full colour outputs can be expensive in Figma; use Auto to reduce the displayed layer count.

Repository maintenance

Commit source, manifest and bun.lock; regenerate ignored dist/. Keep runtime dependencies focused on colour, clustering and UI. Upgrade dependencies with regression and browser checks, particularly FigUI3 custom-element contracts. This repository is private by default and has no remote configured.

Verified in this checkout

Strict type checking, 12 core regression tests (3,727 assertions), production bundling, and a headless Chromium smoke test passed. The browser test verifies FigUI3 registration, PNG decoding, a two-colour preview, automatic palette recomputation and immediate invalidation of Create. The Figma host itself has not been exercised here.