Lolly
앱 열기

자동화도구와 디자인 시스템 제작

Build a tool

A Lolly tool is a small folder of data. tool.json lists what people can change. template.html draws the result. A hooks.js file is added only when the picture needs a calculation the template cannot do.

From that folder Lolly builds the sidebar, draws the canvas and offers the export formats you allow. The same folder runs unchanged in the web app, the desktop apps and the command line, because each of them reads the folder through one engine.

tool.json, template.html and the optional hooks.js feed one engine, which builds the sidebar controls, draws the live canvas and writes the exported files.tool.json, template.html and the optional hooks.js feed one engine, which builds the sidebar controls, draws the live canvas and writes the exported files.Open this in Diagram Builder

You do not need code to make a tool. If you already have a finished design, Share with rules turns a Lolly Design document into a tool when you choose the parts people may edit. Those tools are ordinary tool folders too, compiled for you and run by the strict sideload runtime; Design tool contract covers how.

This guide is for writing the folder yourself. Start with the two-file tool below, then use the reference pages for each part.

Your first tool

A working tool needs two files. This one makes a social card with a heading and a background colour.

tool.json

{
  "id": "hello-card",
  "name": "Hello card",
  "version": "1.0.0",
  "engineVersion": "^1.0.0",
  "status": "community",
  "render": {
    "width": 1200, "height": 630,
    "formats": ["svg", "png", "pdf"]
  },
  "inputs": [
    { "id": "heading", "type": "text",
      "label": "Heading", "default": "Hello" },
    { "id": "background", "type": "color",
      "label": "Background", "default": "#2a1a5e" }
  ]
}

template.html

<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 1200 630"
     width="1200" height="630">
  <rect width="1200" height="630"
        fill="{{background}}"/>
  <text x="600" y="350"
        text-anchor="middle"
        font-size="96" font-weight="700"
        font-family="sans-serif"
        fill="#ffffff">{{heading}}</text>
</svg>

Each declared input becomes a control in the sidebar, a URL parameter and a CLI flag, all with the same id. The template prints the current values into {{heading}} and {{background}}, escaped for you. The seven top-level fields in tool.json are the ones the schema requires; Tool manifests covers the rest.

Hello, Lolly

The hello card rendered with --heading="Hello, Lolly": one rectangle in the background colour and one line of text.

signed by Lollyauthoring-tools-first-tool.svgvector SVG3 elements4 KBAI generatedgenerated by Claude Opus 5.5Check it yourself서명된 파일 받기

Try the folder in one of two ways:

  • On any Lolly, with no clone. Zip the folder and drop the zip on lolly.tools or another Lolly. Choose Install this tool and accept the trust prompt; the tool opens on that device. Drop an edited zip again to replace your copy. Try it without the monorepo has the details.
  • In a clone, from the terminal. Put the folder at community/hello-card/ and run pnpm run cli hello-card --heading="Hello, Lolly" --output=hello.svg. Run pnpm run cli hello-card alone to list its inputs.

The template's root is an <svg>, so the command line renders it with no browser. A template built from HTML renders the same way in the web and desktop apps, and needs the CLI's browser tier on the command line (Render with the CLI).

What each file does

Only tool.json and template.html are required. Add the others when the tool needs them.

FileWhat it doesGuide
tool.jsonIdentity, inputs, export formats and gallery details. The gallery's About card reads it back to people.Tool manifests, Tool inputs
template.htmlHandlebars markup for the canvas and every export.Templates and rendering
styles.cssStyles scoped to the tool canvas (#tool-canvas).Templates and rendering
hooks.jsComputed values, live camera or audio, file transforms and allowed network access.Tool hooks and host capabilities
template.<ext>Sibling templates for text and data formats such as .ics, .csv and .vtt.Data formats
presentation.jsThe playback runtime for a portable HTML export (render.portable).Animated HTML
icon.svgThe gallery icon, drawn in currentColor so the app can colour the icon to match its theme. Recommended.
card.svg, card.html, card.png or card.webmA gallery card of your own. Without one, the gallery shows a preview of the tool's output, rendered by pnpm run previews.
templates/Curated starting points.Tool templates
i18n/<lang>.jsonTranslated labels, help and options.Publish and localize a tool
SKILL.md, skill.json, skill/Guidance for agents that use the tool.Tool skills
intents.jsonThe purposes the tool serves. Without this file the tool is not offered for an intent.Tool manifests
lib/Vendored scripts and data the tool loads.
assets/Tool-local images and fonts.Assets and file utilities

Draw in the design system's colours

A tool written for any design system takes its colours from seven CSS variables on the canvas, each with a fallback for a design system that leaves one out: var(--brand-primary, #2a1a5e) for the lead colour, then --brand-on-primary, --brand-secondary, --brand-surface, --brand-text, --brand-muted and --brand-edge. Lolly fills them from the design system the person has open, in the piece's look and colourway, in the web app, the desktop apps and the command line alike.

Some design systems call their colours by their own words, such as a textile brand's Main, Accent, Supporting and Tertiary. These are colour roles, and a tool needs no change for them. The design system says which role Lolly reads as each slot, so --brand-primary holds whichever role is read as the lead colour. A role that fills no slot is read by name only: no tool draws that role unless a person chooses it in a colour field. A pick stays linked to the role, and the template and hooks receive the role's colour for the piece's look and colourway, never the link.

Templates and rendering lists every variable, including each role's own --brand-<id>, and which token paints each one.

Find the part you need

Each guide below has a public reference tool in community/ that you can open in Lolly and read in the repository.

When you want toGuideReference tools
Declare identity, export formats, examples and a walkthroughTool manifestschart, qr-code, certificate
Choose input types, show inputs conditionally, prefill from the profileTool inputsqr-code, color-palette, stationery
Repeat rows, edit on the canvas or frame an imageStructured inputs and canvas controlsmeeting-planner, deck-studio, diagram-builder, org-chart, frame
Accept a library asset or the person's own fileAssets and file utilitiesstrip-data, filter
Write the template, the styles and data formatsTemplates and renderingwordmark, meeting-planner, snippet
Ship starting pointsTool templatesdesign, qr-code
Add logic, live media, recording or network accessTool hooks and host capabilitiesqr-code, filter, voice-recorder, record
Embed one tool in another, pick the design system's logo or adjust a community tool for a brandComposition and brand overlayslink-card, certificate
Test, share, publish and translatePublish and localize a toolqr-code
Help agents use the toolTool skillsdesign, diagram-builder

Build with an agent

An AI agent can write the folder for you. Give it the intended output, a few representative input values, the design system and any source artwork. Ask it to build ordinary tool data against the manifest and host contracts, then to validate and render the result with the CLI. The guides above are what you review its work against. AI agents covers connecting an agent to Lolly, and Tool skills covers the guidance a tool gives the agents that use the tool.

Section links from the earlier guide