Skip to main content
Glama

gridsmith

CI License TypeScript Node.js

gridsmith generates geometric SVG logos, 24 px UI icons and magic-circle figures from a JSON construction spec, as an MCP server for AI assistants and as a TypeScript library. The spec declares circles on a grid, tangent circles, lines, arcs and regular polygons; gridsmith solves the geometry, lints it against construction rules (few radius ratios, a coarse grid, n-fold symmetry) and renders SVG and PNG with a construction sheet. A model that writes the spec gets exact tangents and intersections instead of guessed coordinates.

📖 Documentation  ·  Gallery  ·  Library API

Pre-1.0: the spec grammar and the rule thresholds may still change.

What's inside

  • Logo marks — filled regions from unions, intersections and differences of discs, polygons and half-planes, previewed at 64, 32 and 16 px. Spec format

  • Magic-circle figures — stroked rings, stars, arcs and repeated medallions, with erase layers that cut bands. Gallery

  • UI icons — 24-unit icons mixing fills and strokes, exported as SVG, PNG and per-layer path segments. Icons

  • SVG icon import — converts the paths of an existing icon into a spec rounded to the grid, with the pixel difference from the original. Icons

  • Construction rules — a lint pass reports off-grid values, too many ratios, angles off the allowed divisions and thin strokes; a spec exports only once it is clean. Rules

  • Reference matching — overlays a PNG or JPEG on the drawing and scores the overlap, so a silhouette can be traced. Outlines and underlay

  • Four MCP tools — gridsmith_guide, gridsmith_render, gridsmith_export, gridsmith_import over stdio. MCP tools

Related MCP server: icon-composer-kit

Installation

Requires Node.js 24 or later. Register the MCP server with Claude Code and/or Codex CLI:

npx -y github:libraz/gridsmith init

init asks which configs to update and writes only the gridsmith entry; uninstall removes it. In Claude Code it also installs as a plugin:

/plugin install gridsmith --marketplace libraz/gridsmith

Manual setup for other clients is in Getting started.

As a library:

npm install github:libraz/gridsmith

Quick start

MCP

Ask the assistant for a mark, a figure or an icon. It reads gridsmith_guide, writes the spec to a JSON file, iterates with gridsmith_render until the report shows no violations, then writes the files with gridsmith_export.

TypeScript

import { mkdtemp, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { render } from '@libraz/gridsmith';

const drawing = render({
  version: 1,
  mode: 'mark',
  grid: { divisions: 4 },
  shapes: [
    { id: 'body', type: 'circle', r: 'R' },
    { id: 'bite', type: 'circle', center: [1, 1], r: 3 },
  ],
  paint: [{ fill: { subtract: ['body', 'bite'] } }],
});

console.log(drawing.violations); // [] when every rule passes
const out = await mkdtemp(join(tmpdir(), 'gridsmith-'));
await writeFile(join(out, 'crescent.svg'), drawing.svg);
await writeFile(join(out, 'crescent-64.png'), drawing.png(64));

→ Library API

Build from source

yarn install && yarn build   # compiles src/ to dist/
yarn test                    # Vitest, including the examples in README.md and docs/en/
yarn check                   # Biome and tsc --noEmit
yarn gallery                 # rebuilds docs/gallery/ from src/guide/examples.ts

The files in docs/gallery/ are generated; do not edit them by hand.

Documentation

The docs are Markdown under docs/en/ and docs/ja/.

Non-goals

gridsmith draws geometry only. It does not render text: finished drawings contain no glyphs. It does not trace bitmaps automatically; an underlay is scored against a drawing the spec describes.

License

Apache-2.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides an MCP server that lets AI models build and patch typed SVG scenes, compute exact Bézier geometry, perceptual gradients and keyframe or spring motion, then rasterize the result to PNG or animated APNG and diff renders pixel-by-pixel. Ten math-backed tools replace guessed coordinates with deterministic geometry, color and animation output.
      MIT