MarkAll documentation

Overview

A DESIGN.md is human-readable prose plus exactly one fenced ```json markall token block. The block is the source of truth and validates against a versioned JSON Schema; the prose around it is documentation. Everything — the web app, the CLI, exporters — reads and writes that one shape.

Install

The CLI needs Node ≥ 18. Once published, run it with npx — no install:

$ npx markall --help

Or install globally:

$ npm install -g markall
$ markall --help

Run from source (works today, before publish): git clone …/MarkAll && cd MarkAll/cli && npm link

Quickstart

Three ways to get a DESIGN.md into your project:

# 1 · scan your own design
$ export ANTHROPIC_API_KEY=sk-ant-...
$ markall scan ./homepage.png --provider anthropic

# 2 · scaffold from scratch
$ markall init "Acme" --primary "#FF6B00"

# 3 · install from the registry
$ markall add stripe

# then, in any project:
$ markall validate
$ markall export tailwind.config.js

Then tell your AI: “Use DESIGN.md for all UI work. Never invent colors.”

The DESIGN.md format

One file, two audiences. Humans read the prose; tools parse the token block.

# Acme — DESIGN.md

## Tokens (source of truth)

```json markall
{
  "schemaVersion": "1.0",
  "name": "Acme",
  "fonts": { "heading": "'Inter', sans-serif", "body": "..." },
  "colorGroups": [
    { "group": "Brand",   "items": [{ "name": "primary", "hex": "#FF6B00", "role": "CTA" }] },
    { "group": "Surface", "items": [{ "name": "bg", "hex": "#FFFFFF", "role": "background" }] },
    { "group": "Text",    "items": [{ "name": "fg", "hex": "#111111", "role": "body" }] }
  ],
  "typeSpec": [ ... ], "spacing": [ ... ], "radius": [ ... ], "buttons": [ ... ]
}
```

Rules: exactly one json markall block per file; it must validate against the schema; prose may summarize but must not contradict the block. Required keys: name, fonts (heading + body), colorGroups, typeSpec.

markall scan <image>

Read a local design image and reverse-engineer a schema-v1 DESIGN.md with a vision model.

$ markall scan ./screenshot.png --provider anthropic --tokens --out ./design

Images: png · jpg · webp · gif. The browser app (Open app) does the same scan client-side via Puter + Llama 4 — no key needed.

Vision providers

Provider-agnostic. Pick one and supply its key:

OPENAI_BASE_URL points the OpenAI path at OpenRouter, a local server, or any compatible endpoint.

markall init [name]

Scaffold a complete, valid design system from a few inputs — no model needed. Interactive by default, or fully flag-driven:

$ markall init "Acme" --primary "#FF6B00" --bg "#0E0E10" --fg "#F5F5F5" --radius 12px --yes

Produces brand/surface/text colors, a type scale, spacing, radius scale, buttons and components. Button text color is auto-picked for WCAG contrast on your primary. Edit the tokens, then markall export.

markall add <brand> · the registry

Fetch a verified, versioned design system into your repo. Writes DESIGN.md, tokens.json, and a version-locked markall.lock.

$ markall add stripe
✓ added stripe@1.0.0 — DESIGN.md · tokens.json · markall.lock

In the registry today: stripe · linear · bmw. The catalog is served at /registry/index.json.

markall validate [file]

Check a DESIGN.md (default ./DESIGN.md) against schema v1: required tokens, valid color values, spacing consistency, and WCAG contrast on body text vs background. Exits 1 on errors — drop it in CI.

$ markall validate
✓ DESIGN.md is valid DESIGN.md v1

markall export <target> [file]

One source of truth → every stack. A single target prints to stdout (pipe-friendly); all or --out writes files.

$ markall export tailwind.config.js > tailwind.config.js
$ markall export all --out ./design

markall diff <a> <b>

Token-level diff between two DESIGN.md files — added, removed, changed. The basis for design-system versioning.

$ markall diff old/DESIGN.md DESIGN.md
+ color.brand-accent = #FF8800
~ color.brand-primary #3B5BFF → #2244EE

AI tool integration

Commit DESIGN.md to your repo, then point your AI at it. It reads the token block and builds in your style.

• Claude Code / Cursor — add a rule: “Never invent colors, fonts, or spacing. Use only the tokens in DESIGN.md.”
• v0 / Lovable / Bolt — paste the prompts block from the scan, or the DESIGN.md itself, as context.
• Each scanned system ships per-tool prompts under the prompts key.