Croquis

AI-native web production platform — sitemap, content drafts and visual review, unified around pages.

Croquis (クロッキー, "quick sketch") takes a web project from structure to sign-off in one place:

• 🗺 Sitemap — plan the page tree (hierarchy, purpose, audience, status)

• ✍️ Content — draft each page as typed blocks (heading / body / image / CTA)

• 💬 Review — clients right-click any element on the live site to leave comments, captured with rich element metadata (CSS selector, computed styles, DOM context, heading trail, screenshot)

• 🤖 AI-first — generate sitemap drafts and page copy from a brief, digest open comments into a prioritized action plan, export everything as LLM-ready JSON/Markdown, and operate it all from Claude Code via the bundled MCP server

Self-hosted on Cloudflare (Workers + D1 + R2) — runs comfortably in the free tier.

📖 日本語の使い方ガイド: docs/usage.ja.md

Tour

Reviewers right-click any element on the live site — the widget (isolated in a shadow root) captures the CSS selector, computed styles, surrounding heading context and viewport along with the comment. That's the screenshot above.

Plan the sitemap — pages form a tree with per-page purpose/audience/status. This one was generated by POST /ai/sitemap from a one-paragraph brief in Japanese:

Draft content per page — typed blocks (heading / body / image / cta), with AI drafts marked as such:

Work through review comments — filter by status, see the exact target selector, reply and resolve:

Hand everything to an AI — one click copies the whole project as LLM-ready Markdown (or JSON):

Related MCP server: Balzac MCP Server

Why Croquis?

The loop this enables: a client right-clicks "make this CTA bigger" → the comment lands with the exact selector and computed styles → you (or Claude Code, via MCP) read it, fix it, reply and resolve — without leaving the editor.

Architecture

┌────────────────────────────────────────────┐
│ Any website                                │
│   <script src="croquis-widget.js"          │  @croquis/widget
│           data-croquis-ingest-key="ing_…"> │  Shadow DOM, right-click → comment
└──────────────┬─────────────────────────────┘
               │ POST /ingest/comments (write-only ingest key)
               ▼
┌────────────────────────────────────────────┐
│ Cloudflare Workers (Hono) + D1 + R2        │  @croquis/api
│  multi-tenant: admin / project token /     │
│  ingest key / share link (+password)       │
└──────┬─────────────────────┬───────────────┘
       │                     │
       ▼                     ▼
┌──────────────┐   ┌─────────────────────────┐
│ Dashboard    │   │ MCP server (stdio)      │  @croquis/mcp
│ Preact+Vite  │   │ 14 tools for Claude Code│
└──────────────┘   └─────────────────────────┘

Monorepo (pnpm workspaces):

Quickstart (local)

Prerequisites: Node ≥ 22, pnpm ≥ 10.

git clone <this repo> croquis && cd croquis
pnpm install
pnpm build                       # generates tokens + builds everything

# 1. API (terminal A)
cd packages/api
cp .dev.vars.example .dev.vars   # set ADMIN_TOKEN
pnpm migrate:local               # apply D1 migrations locally
pnpm dev                         # http://localhost:8787

# 2. Dashboard (terminal B)
pnpm dev:dashboard               # http://localhost:5173
# connect with API URL + your ADMIN_TOKEN, create a project

Embed the widget on any page you want reviewed:

<script
  src="/path/to/croquis-widget.js"
  data-croquis-api="http://localhost:8787"
  data-croquis-ingest-key="ing_…"   <!-- from project creation -->
></script>

Right-click any element → comment → it appears in the dashboard's Review tab.

Deploy to Cloudflare

cd packages/api
wrangler d1 create croquis            # put database_id into wrangler.jsonc
wrangler r2 bucket create croquis-screenshots
wrangler d1 migrations apply croquis --remote
wrangler secret put ADMIN_TOKEN
wrangler deploy

Host the dashboard anywhere static (Cloudflare Pages works well: pnpm --filter @croquis/dashboard build → deploy packages/dashboard/dist). Serve packages/widget/dist/croquis-widget.js from any static host or R2.

Claude Code / MCP

// .mcp.json
{
  "mcpServers": {
    "croquis": {
      "command": "node",
      "args": ["<repo>/packages/mcp/dist/index.js"],
      "env": {
        "CROQUIS_API_URL": "https://croquis-api.<you>.workers.dev",
        "CROQUIS_TOKEN": "<admin or project token>"
      }
    }
  }
}

17 tools: croquis_list_projects, croquis_get_project, croquis_create_project, croquis_list_pages, croquis_create_page, croquis_update_page, croquis_list_content_blocks, croquis_create_content_block, croquis_list_comments, croquis_get_comment, croquis_resolve_comment, croquis_reply_comment, croquis_export_project, croquis_export_project_markdown, croquis_generate_sitemap, croquis_generate_content, croquis_digest_comments.

Typical prompts: "list the open review comments and fix each one in the code, then resolve them" / "generate the sitemap for a bakery brand site and draft the homepage copy".

AI generation

Configure a provider on the API (Wrangler secret / .dev.vars):

Design system: no hardcoded values

Croquis enforces its own design discipline mechanically:

• All design values live in DTCG token JSON (packages/tokens/src/*.tokens.json) — a dependency-free generator emits --cq-* CSS custom properties (namespaced to survive injection into third-party pages) and a typed TS map.

• Component CSS follows ITCSS layering (via native @layer) with BEM naming.

• pnpm check:tokens fails CI on any raw color / absolute length in component CSS.

• Tokens attach to :where(:root, :host) so the same sheet works in the document and inside the widget's shadow root.

API surface (summary)

Development

pnpm test          # Vitest 4 everywhere; API tests run in workerd via @cloudflare/vitest-pool-workers
pnpm typecheck     # strict TS across the monorepo
pnpm check:tokens  # design-token enforcement

Roadmap

• Widget screenshot capture (html-to-image) — the API/storage path already supports it

• Slack / GitHub / Linear notifications

• Full user accounts & roles (schema already carries members)

License

AGPL-3.0. You can self-host freely; if you run a modified version as a service, you must publish your changes. For a commercial license, open an issue.