Lolly
Abrir la app
  1. Automatizar
  2. Crear herramientas y sistemas de diseño

Tool manifests

tool.json tells Lolly what a tool is: its name, what people can change, which files it can export and how it appears in the gallery. This page is the field reference; Build a tool shows a complete small manifest first.

The manifest (tool.json)

Every manifest is validated against schemas/tool.schema.json. Seven fields are required:

FieldWhat it holds
idLowercase and hyphen-separated. It never changes once published, because links, saved sessions and the CLI all address the tool by its id.
nameThe name people see.
versionSemVer. Bump it on every change.
engineVersionThe SemVer range of engines the tool runs on, such as "^1.0.0". An engine outside the range refuses to load the tool.
statusofficial, community or experimental. Experimental tools watermark their exports by default; the caller can turn the watermark off, and on-device tools never get one.
renderAt minimum { width, height, formats }. See The render block.
inputsThe input declarations. See Tool inputs.

The schema does not require description, category and tags. Give every tool all three: the gallery's About card reads the description, and search and filters use the other two.

The About card shows the manifest to people deciding whether to open the tool: name, category and status, the export chips and canvas size from render, the version and a capabilities line when the tool declares any.

The About card for the Filter tool, listing its exports grouped as vector, raster and video chips, its 1080 by 1080 canvas and its version, all read straight from the manifest signed by Lollyvector SVG41 paths~12k nodes78 groups130 KBCheck it yourselfDescarga el archivo firmadoThe About card for the Filter tool, listing its exports grouped as vector, raster and video chips, its 1080 by 1080 canvas and its version, all read straight from the manifest signed by Lollyvector SVG41 paths~12k nodes78 groups130 KBCheck it yourselfDescarga el archivo firmado

Listing and identity

templates and galleryArt are on Tool templates, extends on Composition and brand overlays and designTool on Design tool contract.

What the tool needs from the host

Design-system behaviour

The render block

Most render keys show up in the export popup: formats, page size and unit, the Convert paths toggle and the Content Credentials card.

The export popup - format and size fields, a Convert paths toggle and a pre-ticked Content Credentials card signed by Lollyvector SVG77 paths~6.0k nodes87 groups4 images88 KBCheck it yourselfDescarga el archivo firmadoThe export popup - format and size fields, a Convert paths toggle and a pre-ticked Content Credentials card signed by Lollyvector SVG77 paths~6.0k nodes87 groups4 images88 KBCheck it yourselfDescarga el archivo firmado

render carries width, height and formats. The render.formats enum in schemas/tool.schema.json is the source of truth for the format ids, which cover vector, raster, print, document, motion, audio, data and font output. URL Mode says what each id produces. The optional keys follow, grouped by what they change.

Export controls

Layout and sidebar

layout decides what surrounds the canvas.

layoutWhat people seeReference
sidebar (default)The input sidebar beside the canvas.qr-code
canvasNo sidebar: the tool fills the working area. A single file input becomes a drop zone on the canvas.strip-data
editorNo sidebar. A free-canvas editor where boxes are selected, dragged, resized, rotated and snapped. The render canvas and export controls stay.design, org-chart
documentNo sidebar. A multi-page rich-text editor with a formatting ribbon on the canvas. The render canvas and export controls stay.doc-studio
deckKeeps the sidebar and adds an on-canvas slide editor with a thumbnail rail.None in community/ yet; deck-studio uses the default layout with paged

In all five, the data stays flat and expressible as URL parameters, so the CLI and URL mode render what the editor shows.

How the editor, document and deck layouts work
  • editor drives one blocks input whose rows carry canvas geometry (x, y, width, height and rotation). The shell provides the pasteboard: boxes dragged past the artboard stay visible and selectable, faded outside the frame. The frame's shadow marks the export boundary. Exports stay bounded by the canvas in every format, with no opt-in in the template. The canvas keys are on Structured inputs and canvas controls.
  • document drives one blocks input (content) of content blocks: heading, text, lolly and table. The editor offers paragraph styles H1 to H4, bold, italic, lists and colour, per-block width, alignment, move and delete, click-to-edit text and rich HTML paste that becomes headings, lists and tables. Pagination lives in the tool's hook: blocks flow into fixed-size [data-pdf-page] boxes, which the paged export multi-page-pdf also uses, so the CLI and URL mode render the same document with no editor.
  • deck mounts a live overlay over one blocks input whose rows are slides, so a slide's text, colour and images can be edited in place. Edit mode renders one active slide plus small thumbnails. The overlay restores a full-deck render before export.

Live camera

These keys apply only to tools with an onFrame hook; others ignore them.

width and height are in the export's unit, and physical units come with a DPI. Reserved URL parameters covers unit, dpi, bleed and marks in links. PDF exports a true page size. The CMYK formats (pdf-cmyk, cmyk-tiff) pair with Convert paths for print files that need no installed fonts. A select option can carry width, height and unit to set the export page size from a dropdown, as wayfinding-signage's Sign size does.

What paginate gives each page

Each filled page gets a page object:

  • page.index, page.number and page.count.
  • page.first: the row's first cell, usually the page title.
  • page.cells: [{ column, value, col }] for every column. col is the cell's original column index, stable even when the template shows only some columns.
  • page.fields: the cells after the first, labelled with the person's own column headings.
  • page.byColumn: the trimmed, lower-cased column name mapped to the row's cell, for lookups such as {{lookup page.byColumn "icon"}}.

A template can make any cell editable on the canvas by stamping it data-cell="{{page.index}}:{{col}}". Add data-cell-md when the cell holds Markdown rendered with {{{markdown value}}}, so edits go back into the table as Markdown; without it the cell edits as plain text. A click-to-pick image slot takes data-cell-pick="{{page.index}}" plus data-pick-column="Icon" for the column it writes to (created if absent) and an optional data-pick-tag="icon" catalog tag filter. Pair paginate with paged: true for the scrolling all-pages canvas and filmstrip.

How a multi-page PDF is built

A template marks its page boxes with data-pdf-page. Each marked element becomes one PDF page, sized to its own CSS box. A cover, content that flows across pages and a back page render as separate pages, not one tall image. Pages are drawn as vectors with text outlined to paths, and the document can carry an open password. Without any [data-pdf-page] box the export falls back to the single-page renderer. The multi-page path skips print finishing, so pair it with printMarks: false. multi-page-pdf is the reference layout: a cover, flowing blocks content and a back page.

The recording key (capture) and the speech-to-text key are on Tool hooks and host capabilities, and portable is on Templates and rendering.

Opening catalog assets (openWith)

An optional openWith array lets Assets offer your tool as a place to edit an asset. Each entry has a permanent id, the asset types it accepts, optional lowercase formats and a binding. The whole selection must match. Leave out multiple for one source; set it to true only when the tool can receive the selection in one session. Animated rasters need animated: true, a promise to keep their animation.

For an ordinary tool input, bind its id:

{
  "openWith": [
    {
      "id": "source-photo",
      "types": ["raster"],
      "formats": ["png", "jpg", "jpeg", "webp"],
      "binding": { "kind": "input", "input": "image" }
    }
  ]
}

The binding must point at an asset, file, text or longtext input, and file limits and acceptance filters still apply. A multiple binding must point at a file input that declares multiple: true. Opening creates a fresh tool session. Asset references keep their names, versions and attribution, and file bytes stay transient under the normal file-input rules.

Editor bindings use adapters the shell supports: canvas places image references on a blank canvas, timeline places timed media and opens Sequence and text uses the Text editor's source-aware handoff. The declarations hold no route strings or executable methods. A tool without openWith stays valid and never appears through a guessed binding, and the web shell checks the loaded manifest again before opening.

Declaring an export format in render.formats does not claim the tool can convert any file into that format. Conversion in Assets is a separate feature.

What Convert in Assets offers

Assets also offers Convert, which lists the transformations the source and the device support before showing their settings. That list comes from file operations, not from openWith or render.formats. An on-device utility conversion keeps its watermark and provenance policy. PDF page splitting produces a ZIP of static single-page PDFs, and PDF page rendering produces a ZIP of PNG images. Their fidelity notes and refusal conditions appear before conversion.

Colours that are the content

A person picks one colourway per piece in the tool sidebar's Design system section, and every colour a tool links to the design system follows that choice. A tool whose colours are its content, such as a tonal ramp or a palette pinned to a dataset, can opt out:

{ "tokenAxes": { "colourway": "ignore" } }

The keys are the kinds of theme group in What a theme group means: mode, colourway, expression, medium, contrast, density, campaign and brand. The only value is "ignore". For each kind it ignores, the tool renders in that group's canonical option whatever a link, a saved session or the design system's stored choice asks for, and the sidebar does not offer that group in this tool.

The pin covers every colour the render reads, so a print export uses the CMYK or spot build the design system authored for the canonical option. "mode": "ignore" keeps a print piece in the canonical look; in a design system with no mode group, its light and dark themes with no group count as the mode.

When a link or the CLI asks for an option the tool ignores, lolly run prints a THEME_CHOICE_IGNORED warning and an MCP render adds the same sentence to its warnings.

Advertencia: Raise engineVersion with tokenAxes

Engines older than the field refuse a manifest that declares tokenAxes, so raise engineVersion to the release that added the field, as listed in engine/CHANGELOG.md.

A switch redraws the mounted tool without a reload. Linked colours and var(--brand-*) variables follow automatically. A hook that keeps colours it read from host.tokens reads them again when onInput runs with id: '__tokens', as When the theme or colourway changes shows.

How Lolly decides which theme groups a tool offers

The sidebar offers a group only when switching the group changes what the tool draws. A tool that never reads a colour a group changes needs no field. Lolly works this out from the tool's own files and current values.

The colours a tool reads are the canvas variables its template, styles, hooks and portable presentation use (var(--brand-primary) and the rest), the token references its inputs link and the references its hooks pass to host.tokens.resolve. A reference a hook finishes at run time, such as '{asset.logo.' + variant + '}', counts every token under its fixed start.

A hook that reads the colour list or the token set, a reference built from no fixed start, module hooks and a tool that composes another tool all count as reading every token, so every group that changes a token stays. A treated picture counts as changing with every choice, because a photo look can keep a variant per theme. Declare tokenAxes when the tool does read the colours a group changes and must still keep its own.

Example looks (examples)

examples lets a tool's gallery tile show range: an array of example input values, each rendered live on the device through the same off-screen path an export takes, as a horizontally scrolling preview strip. Each look is cached, and a featured tool also cross-fades the looks in the hero row. Each look is cached, so later visits are instant. Leave examples out when one preview says enough.

"examples": [
  { "label": "Launch teal",  "values": { "heading": "Ship today", "background": "#0c322c" } },
  { "label": "Reverse mark", "theme": "dark", "values": { "ink": "mono" } }
]

pnpm run validate:catalog checks every look. values keys must be declared input ids; when a urlKey is used, the error gives the right id. Catalog asset references must exist, a tool asset path must name a file in the tool's own assets/ folder, and a ?theme= suffix must be a real icon theme. Blocks row keys must be declared fields. The validator also warns when a tool declares looks but no format the gallery can show (svg, png, jpg, jpeg, webp), and when a strip has more than 8 looks: each look is a live render, so keep to a handful of different ones.

The older alias featured.variants still renders but is deprecated. Write examples.

What a tool is for (intents.json)

An optional intents.json beside the manifest says which purposes a tool serves, so someone can start from what a piece has to do rather than from the tool's name. A tool with no such file is not offered for an intent, and everything else about the tool works as before. Declare a purpose only where the tool serves that purpose well; a tool with no such file is not offered for an intent.

{
  "version": 1,
  "intents": [
    {
      "purpose": "offer",
      "needs": ["data", "recipient", "currency"],
      "roles": { "data": "lines", "recipient": "customer" },
      "set": { "number": "", "notes": "" }
    }
  ]
}

Most tools need no surfaces entry. A select option that states width and height already gives the size, and a tool that declares render.followsCanvasSize fits any size. A tool whose own size has the same shape as a surface fits that surface too.

Loading a tool never reads intents.json. Adding one needs no new manifest key and no change to engineVersion, and an older app ignores the file. A brand overlay can carry its own intents.json, which wins over the community file like any other overlay file. Signing covers the file with the rest of the tool.

validate:catalog checks every intents.json: the shape (schemas/tool-intents-v1.schema.json), then what the schema cannot check, through checkToolIntents. That catches an input that does not exist, a select value that is not on offer, a repeated purpose, a required input no role can fill and an intents.json in a folder with no manifest.

Nota: The checks do not look at the file

Render each declaration through lolly intent --render and look at the file as well: an input that takes plain text only sometimes, or falls back to a sample, passes every check here.

A short walkthrough (guide)

guide gives a few steps for work that comes after the render, such as pasting an email signature into the mail app's settings. The shell shows them in a dialog behind a help button beside the tool's name, and opens the dialog once by itself the first time a device opens the tool.

"guide": {
  "title": "Put it in Gmail",
  "tracks": [
    {
      "id": "desktop",
      "label": "On a computer",
      "steps": [
        "Open **Export**, set the format to **HTML** and press **Copy**.",
        "In Gmail, open **Settings** and choose **See all settings**.",
        "Paste into **General → Signature**, then press **Save Changes**."
      ],
      "note": "Outlook and Apple Mail take the same paste."
    },
    { "id": "mobile", "label": "On a phone", "steps": ["…"] }
  ]
}