tsquare wireframes

[tsquare]

tsquare

[CI] [npm]

Wireframes in plain text: easy for LLMs to write, fast to render as SVG or PNG. A small text language for low-fidelity screens, with several devices side by side and notes beside them. Built for LLMs to write: the prompt comes from the component catalog, and errors come back with line numbers so a model can fix its own output.

board "Login"  screen phone "Sign in"    heading "Welcome back"    input "Email" placeholder="[email protected]"    input password "Password"    checkbox "Remember me" checked    button primary "Sign in" fullWidth

Save that as login.tsq, then:

npx tsquare render login.tsq -o login.png --scale 2

Requires Node 20 or newer. To work on tsquare itself, clone the repo, run npm install, and use npm run render -- examples/notes-mobile.tsq -o notes.png --scale 2.

Docs

Getting started · The language · Components · Icons · Colors · Using it with AI

Playground

Online at tsquare.dev/playground, or locally:

npx tsquare playground   # http://localhost:4321

• Editor: syntax highlighting, autocomplete for components, options, props, icons and colors, and problems underlined by line. Paste a whole model reply and it keeps just the code block.
• Preview: renders as you type. Zoom and pan (⌘/Ctrl + scroll or pinch), jump to a single screen, or go full screen.
• Links: copy a share link that reopens the wireframe in the playground, or an image link (SVG, PNG, Markdown, HTML) to embed it anywhere.
• Examples with thumbnails, light and dark themes, a resizable split, and SVG/PNG export.
• Components: every component with its props and a rendered example. Prompt: the system prompt for models, with a copy button.

The local playground uses the same renderer as the CLI; its links point to tsquare.dev. In this repo, npm run playground runs it from source.

Image links

A wireframe can be embedded anywhere an image works (Notion, GitHub, docs sites) with a link that contains the wireframe itself:

![Login](https://tsquare.dev/svg/zNYwxDsIwEAT7vGJ…)

The playground's Copy link menu makes these; Embedding has the steps for Notion, GitHub and your own site. The text is compressed into the URL, not encrypted, so anyone with the link can read it; see privacy. encodeWireframe and decodeWireframe in the library produce and read the same links.

Use it with

With AI

• Claude: the tsquare skill teaches Claude the language and how to check its own wireframes.
• Any model: the system prompt, or the hosted MCP server for Claude, ChatGPT, Cursor, VS Code and other tools that take a remote MCP URL.

In your docs

• Docusaurus, Astro, MDX: remark-tsquare draws ```tsquare code blocks when the site is built.
• VitePress, Eleventy: markdown-it-tsquare, the same for sites built on markdown-it.
• Any web page: one script tag draws the code blocks in the reader's browser, with no build step.
• Notion, GitHub and anywhere an image works: image links.

In your app

• React: @tsquare-js/react shows boards, a zoomable viewer, an editor and a playground, including boards in a model's reply while it's still streaming in.
• Node or the browser: the library itself.

In your editor and notes

• VS Code (and Cursor, VSCodium, Windsurf): the tsquare extension gives .tsq files a live preview, problems as you type, highlighting and autocomplete. Also on Open VSX.
• Obsidian: the tsquare plugin draws ```tsquare code blocks in your notes, on desktop and mobile. See the Obsidian page.

The language

One element per line; children are indented two spaces under their parent. The first line is the board.

If a bare word could mean two props (for example start, which is both an align and a justify value), write it as key=value. Code fences (```) are ignored, so a model's reply can be rendered as-is.

Structure

• The top element is a board. Its children are screens, plus optional notes beside them.
• A screen stacks its children vertically. A navbar is pinned to the top and a tabbar to the bottom.
• modal and drawer are overlays and must be direct children of a screen.

Colors

Wireframes are grayscale. There are three deliberate exceptions in the UI itself:

accent takes blue, indigo, violet, pink, red, orange, green or teal, or a hex color like #1a73e8. With a light hex color, text on it switches to dark and accent-colored text is darkened so it stays readable. There are no other UI color props, on purpose.

Sticky notes beside the wireframe have their own colors, since they're annotations rather than part of the UI: note "TBD" color=pink (yellow is the default, plus blue, pink and green). See Colors for more.

Components

Each component has its own page with a rendered example and its props: see Components.

CLI

tsquare render <file.tsq|-> [-o out.svg|out.png] [--scale 2]tsquare check  <file.tsq|->        # problems by line numbertsquare fmt    <file.tsq|-> [-w]   # canonical formatting (drops comments)tsquare prompt                     # system prompt for modelstsquare playground [--port 4321]   # live editor, component reference, prompt

Run them with npx tsquare … (nothing to install), or install the tsquare command with npm install -g tsquare. Use - to read from stdin. In this repo, run them through npm: npm run check -- file.tsq. Files use the .tsq extension; the CLI reads any text file.

Library

npm install tsquare

import { renderWireframe, compileWireframe, formatIssues } from "tsquare";
const { issues } = compileWireframe(source);           // problems by line, empty when validconst png = await renderWireframe(source, { format: "png", scale: 2 });

tsquare/playground exports the playground's request handler, for hosting it inside your own Node server. tsquare/viewer is the playground's zoomable board (zoom, pan, pinch, a chip per screen) for your own page: pass it the elements, then show() the SVG from renderWireframeSvg with the size and screens from measureBoardLayout (exact; boardLayout is a synchronous estimate that can be off by a line or more on boards with notes). It sets the styles its zoom math needs itself; give the stage a size, and optionally style the classes it toggles on the stage: panning (while dragging), animate (while fitting or zooming to a screen, e.g. .animate > * { transition: transform .25s }) and stale (from setStale, e.g. .stale img { opacity: .35 }). Call destroy() when you remove it. Give it the board's measureElements entries (setElements) and it reports clicks and hovers on elements, outlines them (highlight) and zooms to them (zoomTo): see Element positions. languageData() lists every component, prop, option word, icon and accent, for editor highlighting and autocomplete. In a browser bundle (esbuild, Vite, webpack) the same imports render SVG with no setup; PNG and share links need Node. On a page without a build step, <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tsquare.min.js"></script> draws every ```tsquare code block on the page (see Embedding). See Using it with AI for the prompt and the repair loop. measureElements gives each element's box on the board and its line in the text, and elementsAt what's under a click, for making a board clickable (see Element positions).

The editor: tsquare/editor

The playground's code editor for your own page: highlighting, autocomplete for components, props, option words, icons and accents, problems underlined on their lines, Enter keeping the indentation, and pasting a whole model reply keeps just its code block. CodeMirror is bundled inside (about 125 KB compressed once your bundler minifies it), so it imports nothing and can't clash with a CodeMirror your page already has.

import { createEditor } from "tsquare/editor";import { compileWireframe, languageData } from "tsquare";
const editor = createEditor(document.getElementById("code")!, {  doc: "board\n  screen phone",  data: languageData(), // autocomplete; leave it out for none  onChange: (text) => editor.setIssues(compileWireframe(text).issues),});

Give the element a height; the editor fills it. Options: doc, data, onChange, onCursorLine (the caret's line, when it moves to another), lineNumbers (default true), lineWrapping (default false: wrap long lines instead of scrolling sideways, continuation rows indented 4 spaces past their line's indentation, so they don't look like a child element) and ariaLabel (default "Wireframe text"). The editor has getText(), setText(text) (one undoable step), setIssues(issues), goToLine(n), focus(), dom and destroy().

Its colors are CSS variables, light or dark by the page's color-scheme, defaulting to the playground's:

Using it with Claude (skill)

skill/tsquare/ is a Claude skill: the syntax, the component reference, and a workflow of write → tsquare check → tsquare render → look at the PNG and fix. Copy it to ~/.claude/skills/tsquare (all projects) or <project>/.claude/skills/tsquare, and make sure npx tsquare runs where Claude works. Rebuild it after catalog changes with npm run skill.

How it works

Text is parsed into a json-render spec and validated against Zod schemas. It's then laid out and drawn by Satori into SVG; PNG output goes through resvg.

Measured

How often models write valid tsquare on the first try, with no repair round:

How it was measured, the tasks, every model output, and the scripts: eval/.

License

MIT. The Inter font comes from the @fontsource/inter dependency, under the SIL Open Font License 1.1. Icons are from Lucide, under the ISC license. Brand logos are from Simple Icons (CC0); the logos themselves are trademarks of their owners. The browser build (dist/browser/) bundles some dependencies, Inter and satori (MPL-2.0) among them; their notices are in dist/browser/THIRD_PARTY_LICENSES.txt.