2026-06-26 19:35 UTCIn-site rewrite5 min readUpdated: 2026-06-26 20:17 UTC

Framesmith 1.7 – a quality gate that tells an AI agent when a UI is done

Framesmith 1.7 is an open-source MCP server that gives AI coding agents a visual canvas to sketch and review UI before writing code. It includes a viewer, quality evaluation panel, design system inheritance, and multi-breakpoint previews, integrating easily with various MCP-compatible clients.

SourceHacker News AIAuthor: vicvelazquez

Notifications You must be signed in to change notification settings

Fork 0

Star 2

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

262 Commits

.framesmith

benchmark

docs

scripts

src

.gitignore

LICENSE

README.md

VISION.md

package-lock.json

package.json

test-animations.ts

test-apply-structure.ts

test-archive-view.ts

test-auto-relative.ts

test-autofix.ts

test-backdrop-filter.ts

test-batch-design-idmap.ts

test-build-log.ts

test-cliche.ts

test-component-structures.ts

test-correctness-fixes.ts

test-critique.ts

test-custom-fonts.ts

test-default-font.ts

test-design-md-tolerant.ts

test-design-md.ts

test-design-system-inheritance.ts

test-discoverability.ts

test-diversification.ts

test-empty-thumbnail.ts

test-env.ts

test-evaluate.ts

test-fluid-widths.ts

test-fonts-by-name.ts

test-gradient-shadow-move-fixes.ts

test-guidelines.ts

test-import-core.ts

test-import-html.ts

test-import-structure.ts

test-import-url.ts

test-init.ts

test-llm-judge.ts

test-material-icons.ts

test-ops-parser.ts

test-patterns.ts

test-phase2.ts

test-phase3.ts

test-primitives.ts

test-repo-assets.ts

test-repo-canvases.ts

test-repo-external-change.ts

test-responsive-reflow.ts

test-responsive.ts

test-root-centering.ts

test-structures.ts

test-style-attr-escape.ts

test-svg-paths.ts

test-sync-drift.ts

test-tailwind-map.ts

test-text-props.ts

test-viewer-compare.ts

test-viewer-logo-favicon.ts

test-viewer-navbar.ts

test-viewer-panels.ts

test-viewer-repo-aggregation.ts

test-viewer-repo-lifecycle.ts

test-viewer-resolves-workspace-tokens.ts

test-viewer-sidebar.ts

test-viewer-watch.ts

test-viewer.ts

test-visual.ts

test-workspace-mcp-tools.ts

test-workspace-migration.ts

tsconfig.json

Repository files navigation

An open-source MCP server that gives your AI coding agent a visual canvas. Sketch the UI, review it in a browser, agree on the design — before any framework code gets written.

Contents: Viewer · Installation · Tools · Usage Example · Workflow · Development

Above: the framesmith viewer. Workspaces and projects in the sidebar, canvases as live thumbnails on the right. AI agents create canvases via MCP tools; you browse them like Figma files.

MCP Client → stdio → framesmith server ↓ Scene Graph (in-memory JSON tree) ↓ HTML/CSS Renderer (inline styles) ↓ Puppeteer (headless Chromium → PNG)

Viewer

Run npx -p framesmith framesmith-viewer to start the standalone browser viewer (default port 3001). Open any canvas to review it at multiple breakpoints, compare them side-by-side, inspect the underlying JSON, or archive / delete.

Above: a single canvas in the detail view. The toolbar across the top exposes the breakpoint preview modes, Compare for side-by-side rendering, Fit for max-width, JSON for the raw scene graph, and lifecycle actions.

Quality panel. The canvas detail view shows a read-only quality inspector on the right: the heuristic canvas_evaluate score (0–100), per-category bars, and the issue list — each cliché tell with its category · tell badge, severity, and suggestion. Issues that canvas_autofix can resolve carry an auto-fixable tag, and clicking any issue highlights its node in the live preview. Every gallery card also shows a color-coded score badge so weak canvases stand out at a glance. The score matches what your agent sees over MCP (same fast-mode evaluation, genre-relaxed by the canvas's preset) — it's computed for display only and never written back.

Design-system panel. A second inspector tab shows the canvas's effective design tokens — color swatches, type scale, spacing, and radius — resolved through the full workspace ▸ project ▸ canvas inheritance chain. Each section notes its dominant source layer, and any token that overrides it is tagged (canvas / project) so you can see at a glance what a given canvas customized versus inherited.

The viewer is purely read-only — every canvas is authored through MCP tool calls from your AI assistant. Files persist to ~/.framesmith/canvases/ so the viewer keeps showing them across sessions.

Installation

No clone or build needed — register framesmith with your MCP client via npx (requires Node 20+).

Claude Code

claude mcp add framesmith -- npx -y framesmith

Codex

Add to ~/.codex/config.toml:

[mcp_servers.framesmith] command = "npx" args = ["-y", "framesmith"]

Cursor

Add to ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{ "mcpServers": { "framesmith": { "command": "npx", "args": ["-y", "framesmith"] } } }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "framesmith": { "command": "npx", "args": ["-y", "framesmith"] } } }

VS Code + MCP extension

Add to .vscode/mcp.json (project-scoped) or your global MCP settings:

{ "servers": { "framesmith": { "command": "npx", "args": ["-y", "framesmith"] } } }

Any other MCP-compatible client

framesmith speaks standard stdio MCP. Point your client at npx -y framesmith using whatever config shape your client expects.

Optional: set FRAMESMITH_VIEWER_URL=http://localhost:3001 in the MCP server env to pin it to a long-lived standalone viewer process — see Running the viewer.

Build from source (for development)

git clone https://github.com/vicmaster/framesmith.git cd framesmith npm install npm run build

then point your client at: node /path/to/framesmith/dist/index.js

Tools

init

One-call onboarding — the recommended first call each session, and safe to run repeatedly (idempotent). Binds the current repo if it isn't already (canvases become checked-in JSON under .framesmith/), ensures the convention projects exist, and returns the live state you need to start working.

Param Type Description

dir string? Directory to bind / detect. Defaults to the nearest git repo root above the server working directory.

workspaceName string? Name for the workspace when binding fresh. Defaults to the repo folder name.

projects string[]? Projects to ensure exist (default: ["Foundations", "UI"]). Existing projects are never removed, so it's safe for adding feature/area projects like Onboarding.

Returns the bound workspace + project IDs (binding re-keys IDs to repo-* — use the ones init returns), the on-disk layout, the workspace-layer token count, a workflow cheatsheet, the current gotchas, the framesmith://guidelines URI, and the viewer URL. It does not seed design tokens — set those at the workspace layer with workspace_set_design_system. The default Foundations project is just a canvas that visualizes the workspace tokens (which is where the design system actually lives).

canvas_create

Create a new canvas. If projectId is omitted, it lands in the built-in Untitled project of the Personal workspace.

Param Type Description

name string? Canvas name

projectId string? Target project. Defaults to the built-in Untitled project. See project_list.

The response also carries a diversification signal for the target project: the recently-built structures (newest first) and a hint to differ on at least one taxonomy axis, so successive canvases don't converge on the same layout. It's advisory — never blocking.

canvas_list

List canvases. Excludes archived canvases by default.

Param Type Description

projectId string? Scope to one project

includeArchived bool? Include archived canvases (default false)

Returns [{ id, name, createdAt, lastModified, projectId, archived }].

canvas_move / canvas_archive / canvas_unarchive / canvas_delete

Canvas lifecycle. canvas_move reassigns a canvas to a different project. canvas_archive sets a soft-delete flag (canvas stays on disk, hidden from default canvas_list); canvas_unarchive clears it. canvas_delete removes the canvas and its file permanently — irreversible.

viewer_url

Get the URL of the live viewer plus per-canvas URLs. Share these with the user so they can open the design in their browser. No params.

{ "url": "http://localhost:3001", "gallery": "http://localhost:3001", "canvases": [ { "name": "Login", "viewer": "http://localhost:3001/canvas/abc123" } ] }

canvas_create already returns the per-canvas viewer URL in its response; reach for viewer_url when you want the gallery URL or to enumerate every existing canvas's URL in one call.

workspace_create / workspace_list / workspace_rename / workspace_delete

Top-level container CRUD. The built-in Personal workspace cannot be deleted, and workspace_delete refuses if the workspace still contains projects (move or delete them first).

project_create / project_list / project_rename / project_delete

Mid-level container CRUD inside a workspace. The built-in Untitled project cannot be deleted. project_delete refuses if the project still contains any canvases (archived ones still count — move or delete them first).

canvas_bind

Bind a workspace to the current project directory so its canvases live in the repo as open JSON — a .framesmith/ directory checked in alongside the code, instead of the global ~/.framesmith store. Run it once per repo.

Param Type Description

workspaceId string? Workspace whose projects + canvases migrate into the repo. Defaults to the built-in Personal workspace.

dir string? Directory to bind. Defaults to the nearest git repo root above the server's working directory.

It creates .framesmith/workspace.json (the binding plus the design system, so a fresh clone resolves tokens identically) and one subdirectory per project holding one slug-named file per canvas:

.framesmith/ workspace.json # workspace + projects[] + design system design-system/ design-tokens.json ui/ bloom-landing.json login-form.json

It migrates the workspace's projects + canvases in and makes the repo the source of truth for the rest of the session. A canvas is either repo-bound or global, never both. Afterwards the server auto-detects .framesmith/ on startup (walking up from its working directory). Commit .fra

[truncated for AI cost control]