Open interchange format

Design truth needs a protocol, not another tool

Design systems live in Figma files, component code, markdown, and AI agent prompts — four copies, four versions of the truth, drifting daily. blocksmith.blocks.v1 is the neutral packet format they all meet in: any tool compiles in, any consumer compiles out, and a lockfile pins production in every repo so agents physically cannot hallucinate your design system.

Figma is Ethernet. This is TCP/IP. We don't own the design tools or the runtimes — we define the packet in the middle so everything interoperates. BlockSmith (wiki, Pipeline, MCP, device targets) is the reference implementation that dogfoods the spec.

The stack

┌─────────────────────────────────────────────────────────────┐
│  COMPILE TARGETS (outputs)                                   │
│  wiki · pulse-react · mcp · device-sim · c-header · lvgl…   │
└───────────────────────────▲─────────────────────────────────┘
                            │ read the OFFICIAL graph only
┌───────────────────────────┴─────────────────────────────────┐
│  blocksmith.lock.v1        — repo pin (agent + CI truth)     │
└───────────────────────────▲─────────────────────────────────┘
                            │ generated on promote
┌───────────────────────────┴─────────────────────────────────┐
│  blocksmith.registry.v1    — append-only versions + pointer  │
└───────────────────────────▲─────────────────────────────────┘
                            │ ingest writes versions
┌───────────────────────────┴─────────────────────────────────┐
│  blocksmith.blocks.v1      — Design IR graph (the packet)    │
└───────────────────────────▲─────────────────────────────────┘
                            │ adapters compile in
┌───────────────────────────┴─────────────────────────────────┐
│  INGEST ADAPTERS (inputs)                                    │
│  scan · markdown · governance · storybook · figma · …       │
└─────────────────────────────────────────────────────────────┘

One rule holds the whole stack together: adapters write blocks.v1 only; targets read the official graph only; the lock pins what agents see. Drafts are staging — humans preview them in the wiki, agents never do.

Why a lockfile for design

Code solved drift twenty years ago: build, release, package-lock.json, deploy, rollback. Design never got the same lifecycle — until agents started writing UI at scale and made drift catastrophic. blocksmith.lock gives every block an exact pinned version and content hash. CI fails PRs that violate it. MCP serves nothing that isn't pinned. A promote in the wiki is a release; a rollback moves a pointer and never erases history.

Start here

You are…	Read	Then
Building an ingest adapter (Figma plugin, token tool)	Ingest adapters	Emit blocks.v1, run conformance
Building a compile target (new runtime, new platform)	Compile targets	Read official graphs, register your target
Pinning agents / CI in your repo	lock.v1	Pull the lock, gate PRs on validate:ui
Evaluating the category	blocks.v1	Skim the graph spec — it fits on one page

Install

terminal

npm install @blocksmith/protocol
# types · validators · canonical hashing · schemas · conformance fixtures
# zero runtime dependencies — speak the protocol without cloning BlockSmith