The napkin script language#

API hub · Reference · Quickstart · Cheatsheet

Napkin script says what to draw without a pointer. A person or an AI helper writes it as text, one instruction to a line; a program in any language builds the same thing as JSON. Both become one list of instructions, the object form, which is what the rest of the API runs.

This page is the reference for the language itself: how a script is written, what its values look like, how expressions work, what the diagnostics mean, and the functions that read, check and write scripts. What each instruction draws, and the function that runs a script, are in Drawing with napkin script.

Contents

• What this is
• The mental model
• Reference
  • A script, line by line
  • Values
  • Expressions
  • The version line
  • The budget
  • The object form
  • Verbs
  • Diagnostics
  • Functions
• Worked examples
• Limits
• For agents
• See also

What this is#

A drawing language small enough to learn from one page and strict enough to check before anything runs. A script is a list of instructions such as page, layer, color, rect, text and repeat. Each one is a verb followed by its arguments, and every verb is described in one table, verbs.json, which the parser follows and every listing of the language is generated from.

The text form is for people and for AI helpers; it reads like a list of drawing steps and is forgiving about spacing and case. The object form is for programs: an array of plain objects, one per instruction, each naming its verb. A Python script, a C program or a shell pipeline builds the object form as JSON and never has to produce the text syntax. The two are interchangeable: a script read from text and the same script built as JSON come out as exactly the same instructions.

The mental model#

 text (.napkin) --parseScript-->  instructions  <--validateScript-- JSON (.napkin.json)
                                       |
                                  formatScript
                                       |
                                       v
                                 canonical text

Neither reader throws. Each returns { ok, script, diagnostics }: script holds every instruction that was read without an error, diagnostics holds the errors and warnings in reading order, and ok is true when there were no errors. An instruction with an error is left out rather than half-read, so what comes back is always a well-formed script.

Reference#

A script, line by line#

napkin 1
page 400 300          # the page, in pixels
color #1f2328 width 3 # two paint instructions on one line
group "Figure" {
  layer "Head"
  circle 200 80 30
}
repeat 3 as i { rect (20 + i * 40) 200 30 30 }

• One instruction to a line. A newline ends an instruction, and so does ;, so line 0 0 10 10; line 10 10 20 0 is two.
• A verb first, then its arguments. Positional arguments come first, in order; keyword clauses such as at 200 70 and flags such as hidden follow in any order. The verb tables show every way of writing each verb.
• Blocks. A verb that holds other instructions - group, define, repeat and path - takes a block: { at the end of its line, the instructions, and }. A block can also sit on one line.
• Paint instructions share a line. On a line that starts with a paint verb (tool, color, width, opacity, fill, gradient, stroke, style, profile, nib, pencil, rough, font, character, paragraph, textconfig, accent), another paint verb starts the next instruction. Nothing else chains, so in layer "Sky" opacity 0.8 the opacity is the layer's own.
• Comments. # at the start of a line, or followed by a space, starts a comment that runs to the end of the line. # followed by anything else is a color, #1f2328, which is why a comment after an instruction needs its space.
• Case. Verbs, keywords and choices ignore case and are written back in lower case. Strings and let names keep theirs.
• Hyphens. Outside parentheses a hyphen with a letter after it joins a word, as in effect drop-shadow; inside, it is a minus, so (a-5) is a subtraction.

Values#

Units. A length can carry px, in, mm or pt straight after its number. A bare number is read in the units in force, which are pixels until a units instruction changes them; the print units convert at 96 pixels to the inch, the ratio every export uses.

Shares of the page. 50% is half of the page, measured along the axis the argument runs on: an x coordinate or a width against the page's width, a y coordinate or a height against its height, and a size with no direction - a radius, a stroke width, a font size - against the shorter side. A percentage is refused where there is no page to measure it against, such as the page's own size or a let.

Strings. Double-quoted. \", \\, \n and \t are escapes; any other backslash is kept as written, so "C:\art\logo.svg" survives. A newline in a text item is written \n.

Colors. # and 3, 4, 6 or 8 hex digits; any of the 148 CSS color names; or rgb(), rgba(), hsl() and hsla(), written with no space before the (. The set is exactly what every output format can paint, the PNG included. none is not a color: the verbs that accept it spell it themselves, background none and fill none.

Gradient stops. A color and an offset, separated by commas inside parentheses. Give every stop an offset, as a number from 0 to 1 or a percentage, or give none and they are spaced evenly.

Runs. A text's runs give stretches of it styles of their own, separated by commas inside parentheses. Each is where it starts and where it ends - two whole numbers, counting the text's characters from 0, the end not included - then character's clauses and flags, and a size, a family and a color of its own: text "Acme Corp" at 20 20 runs (0 4 face "Bold", 5 9 color #c0392b underline). The text's first character sets its base, so the size, family and color font and color gave it may move to a run. A run may first name the Text Configuration it follows, config "<name>", which its other clauses override.

Text Configurations. textconfig "<name>" defines one, a vector editor's Character Style: character's clauses, but kern, with a size, a family and a color, under a name the book keeps. config "<name>" on a text has the whole text follow it, and in a run, that run; what the text or the run has of its own overrides it. A name is the same name in any case, and one no textconfig before it defined is unknown-config. Defined again, a configuration changes for every text that follows it.

Markdown Flow. The markdown flag on a text makes its text Markdown, shown as it renders: text "# Notes\n\n- one\n- **two**" at 40 60 markdown. A heading, code, a quote and a link follow the Markdown configurations, Markdown Heading 1 to 6, Markdown Code, Markdown Code Block, Markdown Quote and Markdown Link, which the book takes in; a textconfig of one of those names, before the text, restyles it. The browser-safe entry reads Markdown with the lexer it is given: importing @isocialpractice/napkin-sketch/markdown gives it marked's, as the command line and @isocialpractice/napkin-sketch/node have. With none, the text shows its Markdown as typed. as marks takes no markdown.

Clean Language Accents. accent <language> colors the next text as a language reads it - keywords, strings, numbers, comments, names - every paragraph of it: accent python then text "x = 1 # one" at 40 60. A language is its highlight.js id or a name it goes by (ts, py); one no word spells goes in quotes, accent "c++"; auto takes the language the code reads most like, and none colors nothing. It waits for the next text, and one nothing takes - another accent, the end of its block or a text drawn as marks comes first - is unused-accent. A Markdown Flow text's fenced code needs no accent: a fence that names its language is colored. The colors come from the highlighter the core is given, as the lexer does: @isocialpractice/napkin-sketch/markdown gives it highlight.js with its 36 common languages, and registerAccentLanguage installs more.

Type. A text is Sideless Typing from its anchor, the top of its first line; box sets it in a rectangle that grows to fit, inside "<path data>" in a shape, and along "<path data>" on a path, both drawn from the anchor; vertical sets it in columns that run right to left. character and paragraph set what every text after them has, as font does, until a reset; align on a text sets its paragraphs' alignment for it alone.

Expressions#

Anything computed goes in parentheses: (i * 40 + 20), (width / 2), (80 * cos(i * 30)). A bare name where a number is expected is an error that says to wrap it, (gap).

• Operators: +, -, *, / and % (the remainder), with unary minus. Unary minus binds first, then * / %, then + -, each from left to right.
• Names: a let value, a repeat counter, and the page's width and height, all in the current units.
• Units inside: (width - 20mm) converts the 20mm into the current units before subtracting.
• Shares of the page inside: (50% - 20) works as it does outside an expression. A % right after a number is a share of the page unless a value follows it, so (10%3) and (10 % 3) are both the remainder, 1.
• Functions: trigonometry is in degrees, like every angle in the language, and gives exact answers at the exact angles: sin(30) is 0.5.

let gap 24
repeat 12 as i {
  circle (200 + 80 * cos(i * 30)) (150 + 80 * sin(i * 30)) 6
}
rect 10mm 10mm (width - 20mm) (gap * 2)

An expression is checked when the script is read, so a missing operand or an unknown function is reported at its column before anything runs. A name that was never set, or a division by zero, can only be found when the expression runs.

The version line#

A script's first instruction names the language version it was written for:

napkin 1

Without it, version 1 is assumed and a version-missing warning says so. A version newer than this build reads is a version-unsupported error that names the newest it does. A version changes only when a script that ran under the old one would run differently under the new one; a new verb or a new optional field is an addition, and a script that uses one reports unknown-verb on an older build rather than drawing something else.

A snippet that is not a whole script - an example in the documentation, a block a program is assembling - is read with { fragment: true }, and then no napkin line is expected.

The budget#

One run of a script has a budget, so a loop that never ends, or a script that would draw more than any output can hold, stops rather than hanging the program that ran it:

A run that reaches a limit stops with a budget-exceeded error at the instruction that crossed it, and keeps everything it drew before. Each pass through a repeat costs an instruction of its own, so even an empty body cannot spin forever. A caller that means to draw more raises a limit deliberately: evaluate(text, { limits: { marks: 200000 } }).

Sampled points are the limit that matters for drawings with many curves. A curved segment is sampled to its size, about a point a pixel and never more than 24, so a circle of radius 14 or more comes to 97 points and a thousand of them to 97,000.

The object form#

A script in JSON is an array of instructions. Each instruction is an object with a verb and the fields that verb has; the verb tables list them, ? marking the optional ones. This is the script from A script, line by line, built as JSON:

[
  { "verb": "napkin", "version": 1 },
  { "verb": "page", "width": 400, "height": 300 },
  { "verb": "color", "color": "#1f2328" },
  { "verb": "width", "width": 3 },
  {
    "verb": "group",
    "name": "Figure",
    "body": [
      { "verb": "layer", "name": "Head" },
      { "verb": "circle", "cx": 200, "cy": 80, "r": 30 }
    ]
  },
  {
    "verb": "repeat",
    "count": 3,
    "as": "i",
    "body": [{ "verb": "rect", "x": { "expr": "20 + i * 40" }, "y": 200, "width": 30, "height": 30 }]
  }
]

• Values are encoded as the Values table shows: a length is a number, or a string when it carries a unit or a %; an expression is { "expr": "..." }, its source without the parentheses.
• Blocks are arrays: body of a group, clip, define, repeat, wipe, stack or path.
• at, { "line": 3, "column": 5 }, is where a parsed instruction came from. It is optional, and a program building JSON leaves it out.
• What a form implies is a field. fill none is { "verb": "fill", "fill": null }, rough off is { "verb": "rough", "amount": 0 }, and crop auto is { "verb": "crop", "mode": "auto" }.
• Forgiving where it is safe. An unknown field is a warning and is left out on its own. A flag set to false, such as "hidden": false, and an optional field set to null mean the field is absent.
• Canonical on the way out. validateScript returns values in the form the text parser writes them: colors in lower case, "10.50MM" as "10.5mm", expressions trimmed. A script built as JSON and the same script written as text therefore compare equal.
• Always writable. A JSON instruction whose fields together fit no way of writing its verb - crop with mode: "auto" and an x - is an invalid-value error, so every valid script can be written as text.

Verbs#

Document#

The page: its size, background and name, the unit bare numbers are read in, the seed, and more pages.

Layers#

Named layers and nested groups, with opacity, visibility and lock.

Paint#

What every mark after it is drawn with: tool, color, width, opacity, fill, gradient, outline, dash, profile, nib, pencil, font, the hand-drawn pass, and the character, paragraph, Text Configuration and code accent of the text after it.

Shapes#

Marks built from Bezier anchors: rectangles, circles, ellipses, lines, polygons, stars, arcs, spirals and the shape library, and marks combined as the Wipe Stacks and the Shape Stacker combine them.

Paths#

Marks written segment by segment, from SVG path data or from a block of steps, curves through points, and paths cut where a point lands on them.

Transforms#

Translate, rotate, scale and mirror, baked into the anchors of every mark after them, with push and pop to undo them.

Control#

Named numbers, reusable definitions, and repetition.

Text and media#

Text, placed images, linked files, and documents the host supplied.

Effects#

Effects for the next layer, group or mark - blur, color, shadows, glows, bevels, emboss and feather, Splatter, Warp and 3D - and the blend mode of the next layer or group.

Output#

Hints the renderers read: the box every output is cut to, and one box every page shares.

Diagnostics#

A diagnostic is { level, code, message, line?, column?, index?, verb?, expected? }. Text scripts point at a line and column, both 1-based; JSON scripts point at an index path, [3, 0] being the first instruction in the body of the fourth. A program matches on code, which is never renamed or reused. The message is one sentence for a person and may change.

Printed with formatDiagnostic, a diagnostic takes the shape editors and CI parsers already read:

card.napkin:3:1: error unknown-verb: `circl` is not a verb. Did you mean `circle`?
card.napkin.json[1][0]: error expected-length: `x` of `rect` at [1][0]: `ten` is not a length, such as `120`, `"10mm"` or `"50%"`.

Functions#

Exported from @isocialpractice/napkin-sketch, the package's browser-safe entry, and DOM-free; the source is src/core/script/index.ts.

parseScript(text: string, options?: { fragment?: boolean }): ParseResult
validateScript(value: unknown, options?: { fragment?: boolean }): ParseResult
formatScript(script: Instruction[], options?: { indent?: string; comments?: Map<object, string[]> }): string

interface ParseResult {
  ok: boolean;               // no errors: every instruction is in `script`
  script: Script;            // the instructions that were read
  diagnostics: Diagnostic[]; // errors and warnings, in reading order
}

parseExpression(source: string): ExprParse   // { ok: true, node } or { ok: false, code, message, index }
evaluateExpression(node: ExprNode, scope: ExprScope): number   // throws ExpressionError
formatDiagnostic(diagnostic: Diagnostic, file?: string): string

formatScript throws on an instruction it cannot write, which only an unchecked script can contain; check a script built by hand with validateScript first. comments puts # lines before chosen instructions, keyed by the instruction object itself and written at its indent, inside a block too; the parser skips them, as it skips every comment. The verb table itself is exported as VERBS, with verbSpec(name) to look one verb up.

Worked examples#

Reading a script with mistakes. Every mistake is reported, each at its line and column, and the instructions without one are still read:

# expect: unknown-verb, missing-argument, expected-length
napkin 1
circl 50 50 10
rect 0 0 10
color #1f2328 width three
line 0 0 10 10

card.napkin:3:1: error unknown-verb: `circl` is not a verb. Did you mean `circle`?
card.napkin:4:12: error missing-argument: `rect` needs `height`: rect <x> <y> <width> <height> [r <radius>].
card.napkin:5:21: error expected-length: `width` takes a length, such as `120`, `10mm` or `50%`, and got `three`. To use a name, write it in parentheses: `(three)`.

That is what printing each diagnostic gives. The script that comes back holds napkin, color and line, and ok is false:

import { formatDiagnostic, parseScript } from '@isocialpractice/napkin-sketch';

const { ok, script, diagnostics } = parseScript(text);
for (const d of diagnostics) console.error(formatDiagnostic(d, 'card.napkin'));

Building a script in another language. A program writes JSON and hands it over; nothing in it has to know the text syntax. From Python:

import json

script = [{"verb": "napkin", "version": 1}, {"verb": "page", "paper": "slide"}]
for i in range(5):
    script.append({"verb": "rect", "x": {"expr": f"80 + {i} * 360"}, "y": 400, "width": 300, "height": 200})

with open("deck.napkin.json", "w") as f:
    json.dump(script, f)

Read back, it validates to the same instructions as the text it corresponds to, and formatScript writes that text:

napkin 1
page slide
rect (80 + 0 * 360) 400 300 200

Limits#

• No verb reads a file. An image names an asset the host supplied or carries a data URL, and a link records a path the host resolves. A script cannot open anything on its own.
• Expressions are numbers. There are no strings, comparisons or conditions in an expression, and no loop but repeat.
• A comment after an instruction needs its space. rect 0 0 10 10 #add reads #add as a color.
• One color model. Hex, the CSS names and the rgb and hsl functions. currentColor, color() and the newer CSS color spaces are not accepted, because not every output can paint them.
• Keywords are English. Verbs, clauses and choices are fixed words.

For agents#

• Write one instruction to a line, verb first, and check the verb tables for the exact spelling of each form. formatScript shows the canonical spelling of anything you are unsure of.
• Match diagnostics on code, never on message. Codes are stable; messages are for people and may be reworded.
• Most errors are a one-token fix. expected-*, missing-argument, unit-unknown, and unknown-verb with a suggestion name the exact token and what would be accepted there. unclosed-block and unexpected-close mean the braces are unbalanced; count them rather than editing the line reported.
• Fix every error before running. An instruction with an error is left out, so a script that is not ok draws less than it says.
• Read snippets with { fragment: true } so a missing napkin line is not reported.
• Prefer JSON when a program builds the script, and text when a person will read it. They are the same instructions either way.

See also#

• Drawing with napkin script: running a script, and what each instruction draws.
• Writing a drawing out: the formats, and what crop and registration do to them.
• The napkin-sketch command line: check a script, draw it, and verbs for this page's tables as JSON.
• src/core/script/verbs.json: the verb table every listing on this page is generated from.
• src/core/script/instructions.ts: the object form's types.
• The graphic design API: the composition API.