tsquare 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 David Vogeleer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The Inter font (the @fontsource/inter dependency) is licensed separately under
+the SIL Open Font License 1.1.

package/README.md

@@ -0,0 +1,135 @@
+<p align="center"><img src="https://raw.githubusercontent.com/tsquare-js/tsquare/main/assets/logo.png" alt="tsquare" width="160"></p>
+
+# tsquare
+
+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.
+
+```tsquare
+board "Login"
+  screen phone "Sign in"
+    heading "Welcome back"
+    input "Email" placeholder="you@example.com"
+    input password "Password"
+    checkbox "Remember me" checked
+    button primary "Sign in" fullWidth
+```
+
+Save that as `login.tsq`, then:
+
+```bash
+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](docs/getting-started.md) · [The language](docs/language.md) · [Components](docs/components/README.md) · [Icons](docs/icons.md) · [Colors](docs/colors.md) · [Using it with AI](docs/ai.md)
+
+## Playground
+
+```bash
+npm run playground   # http://localhost:4321
+```
+
+- **Editor:** live render as you type, problems listed by line (click one to jump there), and SVG/PNG export. Paste a whole model reply and it keeps just the code block.
+- **Components:** every component with its props and a rendered example you can open in the editor. It's generated from the catalog, so it can't drift from what the renderer accepts.
+- **Prompt:** the system prompt for models, with a copy button.
+
+It renders on a local Node server using the same code as the CLI.
+
+## The language
+
+One element per line; children are indented two spaces under their parent. The first line is the board.
+
+| You write | It means |
+|---|---|
+| `button "Sign in"` | a quoted string sets the main text (label, title, text…) |
+| `button primary lg` | bare words set options: `phone`, `desktop`, `primary`, `ghost`, `row`, `sm`, `left`, `bottom`, `password`… |
+| `checkbox checked`, `toggle off` | a prop name turns a boolean on; `off` / `unchecked` / `no-<prop>` turn it off |
+| `stack width=240 gap=8` | `key=value` sets any prop |
+| `tabs items=[All notes, Pinned]` | lists in `[ ]`, items separated by commas; an item can contain spaces |
+| `data=[["$1,200", "Smith, J"]]` | quote an item that contains a comma (`\"` for a quote inside quotes) |
+| `tabbar items=[{label=Home icon=home}]` | objects in `{ }` |
+| `# note to self` | comment |
+
+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:
+
+| You write | It colors |
+|---|---|
+| `board "App" accent=blue` | primary buttons, solid badges, checked checkboxes and radios, toggles that are on, the active tab and tab-bar item, ghost button text |
+| `badge "Failed" tone=danger` | one badge: `success`, `warning` or `danger` |
+| `input "Email" error helper="Required"` | the field's border and helper text, in red |
+
+`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](docs/colors.md) for more.
+
+## Components
+
+| Group | Components |
+|---|---|
+| Canvas | board, screen (`phone` 390×844, `tablet` 820×1180, `desktop` 1280×800, `custom`), note |
+| Layout | stack, grid, card, divider, spacer |
+| Content | heading, text (`lines=3` draws placeholder lines), image (X-box placeholder), icon (any [Lucide](https://lucide.dev/icons) name, see [Icons](docs/icons.md)), avatar, badge |
+| Controls | button, input (`multiline=4` for a textarea), checkbox, radio, toggle, select |
+| Navigation & data | navbar, tabbar, tabs, list, listitem, table |
+| Overlays | modal, drawer (`left`, `right`, `bottom` sheet) |
+
+Each component has its own page with a rendered example and its props: see [Components](docs/components/README.md).
+
+## CLI
+
+```bash
+tsquare render <file.tsq|-> [-o out.svg|out.png] [--scale 2]
+tsquare check  <file.tsq|->        # problems by line number
+tsquare fmt    <file.tsq|-> [-w]   # canonical formatting (drops comments)
+tsquare prompt                     # system prompt for models
+```
+
+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.
+
+## 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 the `tsquare` command available (`npm link` in this repo). Rebuild it after catalog changes with `npm run skill`.
+
+## How it works
+
+Text is parsed into a [json-render](https://github.com/vercel-labs/json-render) spec and validated against Zod schemas. It's then laid out and drawn by [Satori](https://github.com/vercel/satori) into SVG; PNG output goes through resvg.
+
+| File | Contents |
+|---|---|
+| `src/text.ts` | parser |
+| `src/print.ts` | formatter (spec → text) |
+| `src/compile.ts` | parse + validate with line numbers, `renderWireframe` |
+| `src/prompt.ts` | model prompt, generated from the catalog |
+| `src/catalog.ts` | components and their props |
+| `src/components.tsx` | Satori renderers |
+| `src/render.ts` | validation, board sizing, SVG/PNG |
+| `src/layout.ts` | colors, device sizes, spacing |
+
+## Measured
+
+How often models write valid tsquare on the first try, with no repair round:
+
+| | Sonnet | Haiku |
+|---|---|---|
+| Valid on the first try (20 requests) | 100% | 85% |
+| Median tokens per wireframe (JSON took about 4× as many) | 184 | 210 |
+| Color checks passed (7 requests) | 11/11 | 11/11 |
+
+How it was measured, the tasks, every model output, and the scripts: [`eval/`](eval/).
+
+## License
+
+MIT. The Inter font comes from the `@fontsource/inter` dependency, under the SIL Open Font License 1.1. Icons are from [Lucide](https://lucide.dev), under the ISC license.

package/bin/tsquare.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The CLI is TypeScript (with JSX components); tsx loads it at runtime so
+// `npm link` and `npx tsquare` work without a build step.
+import { register } from "tsx/esm/api";
+
+register();
+await import("../src/cli.ts");

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "tsquare",
+  "version": "0.1.0",
+  "description": "Wireframes in plain text: easy for LLMs to write, fast to render as SVG or PNG.",
+  "keywords": [
+    "wireframe",
+    "mockup",
+    "ui",
+    "diagram",
+    "llm",
+    "ai",
+    "svg",
+    "text-to-diagram",
+    "claude"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tsquare-js/tsquare.git"
+  },
+  "homepage": "https://github.com/tsquare-js/tsquare#readme",
+  "bugs": {
+    "url": "https://github.com/tsquare-js/tsquare/issues"
+  },
+  "type": "module",
+  "bin": {
+    "tsquare": "bin/tsquare.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skill/tsquare/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "render": "tsx src/cli.ts render",
+    "check": "tsx src/cli.ts check",
+    "fmt": "tsx src/cli.ts fmt",
+    "prompt": "tsx src/cli.ts prompt",
+    "playground": "tsx playground/server.ts",
+    "skill": "tsx skill/build.ts",
+    "docs": "tsx docs/build.ts",
+    "typecheck": "tsc",
+    "examples": "for f in examples/*.tsq; do tsx src/cli.ts render $f -o ${f%.tsq}.png --scale 2; done",
+    "eval:prompts": "tsx eval/prompts.ts",
+    "eval:score": "tsx eval/score.ts"
+  },
+  "dependencies": {
+    "@fontsource/inter": "5.3.0",
+    "@json-render/core": "^0.21.0",
+    "@json-render/image": "^0.21.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "lucide": "1.48.0",
+    "react": "^19.3.0",
+    "tsx": "^4.23.15",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "gpt-tokenizer": "^4.0.0",
+    "typescript": "^7.0.2"
+  }
+}

package/skill/tsquare/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: tsquare
+description: Create low-fidelity UI wireframes and mockups (app screens, several devices side by side, boards for specs and docs) as tsquare text, then render them to PNG or SVG with the tsquare CLI. Use when asked to wireframe, mock up or sketch a UI screen, page or flow, or to add a UI mockup to a document.
+---
+
+# tsquare wireframes
+
+tsquare is a small text language for UI wireframe boards. You write a `.tsq` file; the `tsquare` CLI checks it and renders it to a clean, grayscale PNG or SVG.
+
+## Workflow
+
+1. **Write** the wireframe to `<name>.tsq`, following the syntax below. Every component and prop is listed in [reference.md](reference.md); read it before using a component you haven't used yet.
+2. **Check:** `tsquare check <name>.tsq`. It lists problems by line, with the valid options or a "did you mean". Fix every one and check again until it says the file is valid.
+3. **Render:** `tsquare render <name>.tsq -o <name>.png --scale 2` (use `-o <name>.svg` for docs that take SVG).
+4. **Look at the PNG** before showing it. The checker can't see layout, so check for:
+   - content cut off at the bottom of a screen (screens have a fixed height; nothing warns about clipping). Remove content, split it into another screen, or use `device=custom` with a larger `height`.
+   - cramped rows, or text squeezed into narrow columns.
+   - anything the request asked for that's missing.
+   Fix the `.tsq` and render again.
+5. **Deliver** the image path and the `.tsq` source, so the user can edit it later.
+
+If `tsquare` isn't found, stop and ask the user how it's installed. From a checkout of the repo, `npm link` makes the command available.
+
+## Keep in mind
+
+- One wireframe is one **board**: several **screens** side by side (phone, tablet, desktop or custom sizes), plus **notes** beside them. Show states or steps of a flow as separate screens.
+- Wireframes are low fidelity: placeholders (`image`, `text lines=3`) beat invented copy, unless the copy matters.
+- Stay grayscale unless the user asks for color or a brand. Then set `accent` on the board; don't look for other color props, there aren't any.
+
+## Output format: wireframe text
+One element per line. Indent children two spaces under their parent. The first line is the board.
+
+A line is the component name in lowercase, followed by arguments separated by spaces:
+- "a quoted string" sets the component's main text prop (marked "main text" in reference.md)
+- a bare word that is one of the component's option values sets that option: phone, desktop, primary, ghost, row, sm, left, bottom, password, …
+- a bare prop name sets a boolean prop to true: checked, fullWidth, grow, muted. `off` and `unchecked` set on/checked to false
+- key=value sets any prop. Values: "string", number, true/false, bare word, [list, of, values], {key=value key=value}
+- # starts a comment
+
+Lists: items are separated by commas, and an item can contain spaces without quotes: [All notes, Pinned, Shared]. To put a comma inside an item, quote the item: ["$1,200", "Smith, J"]. Inside quotes, write \" for a quote character. Numbers in a list of text are fine: [2023, 2024].
+
+If a bare word could mean more than one prop, write it as key=value.
+
+## Rules
+1. The top element is a Board. The Board's children are Screens, plus optional Notes beside them.
+2. Each Screen is one view of the product. Use several Screens to show several views or states.
+3. A Screen lays out its children top to bottom. Use Stack (direction row or column) and Grid to arrange content.
+4. NavBar is pinned to the top of its Screen and TabBar to the bottom.
+5. Modal and Drawer are overlays. They must be direct children of a Screen.
+6. This is a low-fidelity wireframe. Prefer placeholders (Image boxes, Text with lines) over invented copy unless the copy matters.
+7. Only use the components and props listed below. All props are optional unless marked required.
+8. Wireframes are grayscale. The only UI colors: Board accent (one color for primary buttons, checked controls, toggles, active tabs and ghost buttons), Badge tone (success, warning, danger) and Input error. Only add an accent if the request asks for color or a brand.
+
+## Example
+
+Request: Two phone screens for a recipe app: a browse screen with search, category tabs, a grid of recipe cards and a tab bar; and a recipe detail screen with its options sheet open.
+
+```tsquare
+board "Recipe app"
+  screen phone "Browse"
+    navbar "Recipes" leading=menu actions=[bell]
+    input search placeholder="Search recipes"
+    tabs items=[All, Quick, Vegetarian] active=0
+    grid columns=2 gap=12
+      card padding=10
+        image height=110
+        text "Tomato soup" bold
+        text sm "25 min" muted
+      card padding=10
+        image height=110
+        text lines=2
+    tabbar items=[{label=Browse icon=book-open}, {label=Saved icon=heart}, {label=Profile icon=user}] active=0
+  screen phone "Recipe"
+    navbar leading=back actions=[share, more-horizontal]
+    image "Photo" height=200
+    heading "Tomato soup" level=1
+    stack row gap=8
+      badge outline "25 min"
+      badge outline "Vegan"
+    text lines=4
+    button primary "Start cooking" fullWidth
+    drawer bottom "Options" size=260
+      toggle "Metric units" on
+      select "Servings" value="4"
+      checkbox "Add to shopping list"
+  note "Detail screen shown with the options sheet open."
+```

package/skill/tsquare/reference.md

@@ -0,0 +1,196 @@
+# tsquare components
+
+Every component and its props, generated from the catalog. All props are optional unless marked required. "main text" is the prop a quoted string fills.
+
+### Board
+Root canvas (artboard). Holds Screens side by side, plus optional Notes. Must be the root element.
+- title: string (main text)
+- layout: "row" | "grid" — row = all screens side by side; grid = wrap every `columns` screens
+- columns: number
+- gap: number
+- padding: number
+- accent: string — The one UI color: primary buttons, solid badges, checked controls, toggles, active tabs, ghost buttons. blue, indigo, violet, pink, red, orange, green, teal, or a hex color like #1a73e8. Omit for grayscale.
+
+### Screen
+One view of the product in a device frame. Children stack vertically.
+- name: string (main text) — Label shown above the screen
+- device: "phone" | "tablet" | "desktop" | "custom"
+- width: number — Only for device=custom
+- height: number — Only for device=custom
+- chrome: boolean — Phone status bar / desktop browser bar. Default true for phone and desktop.
+- padding: number
+- gap: number
+
+### Note
+Sticky-note annotation. Put it on the Board beside screens, or inside a Screen next to what it explains.
+- text (required): string (main text)
+- color: "yellow" | "blue" | "pink" | "green"
+- width: number
+
+### Stack
+Flex container. The main layout primitive (rows, columns, sidebars, toolbars).
+- direction: "row" | "column"
+- gap: number
+- padding: number
+- align: "start" | "center" | "end" | "stretch"
+- justify: "start" | "center" | "end" | "between" | "around"
+- wrap: boolean
+- grow: boolean — Fill remaining space in the parent
+- width: number | string — Fixed width, e.g. 240 for a sidebar
+- border: "none" | "right" | "left" | "top" | "bottom" | "all"
+- fill: boolean — Light gray background
+
+### Grid
+Equal-width columns that wrap. Good for card grids and galleries.
+- columns (required): number
+- gap: number
+- padding: number
+
+### Card
+Bordered container with optional title. Children stack vertically.
+- title: string (main text)
+- padding: number
+- gap: number
+- variant: "outline" | "filled"
+- grow: boolean
+- width: number | string — Fixed width, e.g. 320. Default fills the space.
+
+### Divider
+Thin separator line.
+- vertical: boolean
+
+### Spacer
+Empty space. Without a size it grows to push siblings apart.
+- size: number — Fixed size in px. Omit to fill remaining space.
+
+### Heading
+Heading text, level 1 (largest) to 3.
+- text (required): string (main text)
+- level: 1 | 2 | 3
+- align: "left" | "center" | "right"
+
+### Text
+Body text, or placeholder lines when `lines` is set and `text` is not.
+- text: string (main text)
+- lines: number — Draw N placeholder lines instead of real text
+- size: "sm" | "md" | "lg"
+- muted: boolean
+- bold: boolean
+- align: "left" | "center" | "right"
+
+### Image
+Image placeholder: a box with an X through it.
+- height: number
+- width: number | string — Default fills the container width
+- label: string (main text)
+- rounded: boolean
+
+### Icon
+Line icon from Lucide.
+- name: string (main text) — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+- size: number
+
+### Avatar
+Round avatar with initials or a person silhouette.
+- initials: string (main text)
+- size: number
+
+### Badge
+Small pill label for counts or statuses.
+- label (required): string (main text)
+- variant: "solid" | "outline"
+- tone: "neutral" | "success" | "warning" | "danger" — Status color. Default neutral (the accent for solid badges)
+
+### Button
+Button. Primary is filled, secondary is outlined, ghost is text only.
+- label: string (main text)
+- variant: "primary" | "secondary" | "ghost"
+- size: "sm" | "md" | "lg"
+- icon: string — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+- fullWidth: boolean
+
+### Input
+Text field with optional label. Set multiline for a textarea.
+- label: string (main text)
+- placeholder: string
+- value: string
+- type: "text" | "password" | "search" | "email"
+- multiline: number — Number of rows; 2 or more makes a textarea
+- helper: string
+- error: boolean — Validation error: red border and red helper text
+- grow: boolean — Fill the remaining space in a row
+- width: number | string — Fixed width, e.g. 320. Default fills the space.
+
+### Checkbox
+Checkbox with label.
+- label: string (main text)
+- checked: boolean
+
+### Radio
+Radio button with label.
+- label: string (main text)
+- checked: boolean
+
+### Toggle
+On/off switch with label on the left.
+- label: string (main text)
+- on: boolean
+
+### Select
+Dropdown field (closed state).
+- label: string (main text)
+- value: string
+- placeholder: string
+- width: number | string — Fixed width, e.g. 320. Default fills the space.
+
+### NavBar
+Top app bar. Place first in a Screen.
+- title: string (main text)
+- leading: "none" | "menu" | "back" | "close" | "logo"
+- actions: array of string — Icon names shown on the right
+- align: "left" | "center"
+
+### TabBar
+Bottom tab bar for mobile. Place last in a Screen (before overlays).
+- items (required): array of { label: string, icon: string }
+- active: number
+
+### Tabs
+In-page tabs with an underline on the active one.
+- items (required): array of string
+- active: number
+
+### List
+Vertical list of ListItems.
+- dividers: boolean
+- grow: boolean
+
+### ListItem
+Row in a List. Omit title for a placeholder bar.
+- title: string (main text)
+- subtitle: string
+- leading: "none" | "icon" | "avatar" | "image" | "checkbox"
+- icon: string — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+- trailing: "none" | "chevron" | "toggle" | "text" | "badge" | "icon"
+- trailingText: string
+- trailingIcon: string — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+
+### Table
+Table with headers. Rows are placeholder bars unless `data` is given.
+- columns (required): array of string
+- rows: number — Placeholder rows when `data` is not given
+- data: array of array of string
+
+### Modal
+Centered dialog over the screen. Must be a direct child of a Screen, listed last.
+- title: string (main text)
+- width: number
+- scrim: boolean — Dim the screen behind. Default true.
+
+### Drawer
+Panel sliding in from an edge: side nav (left), filters/details (right), or bottom sheet. Must be a direct child of a Screen, listed last.
+- side: "left" | "right" | "bottom"
+- title: string (main text)
+- size: number — Width for left/right, height for bottom
+- scrim: boolean — Dim the screen behind. Default true.
+- handle: boolean — Grab handle on bottom sheets. Default true for bottom.