This guide covers the optional organisation service. Configuration, console and API paths refer to your Lolly Work instance. The packaged console keeps its release-matched copy of this guide.
Connect a Penpot instance you host, and its design tokens flow into a Lolly Work design system while your designers keep working in Penpot. Boards stay in Penpot until a curator picks the ones worth keeping. Penpot remains the source of truth, and Lolly Work never writes to Penpot.
- Tokens arrive on every sync. Each file's tokens federate as one
tokensasset (DTCG JSON). The console's Design system tab lists them as token sets that the design system inherits read-only,$themesincluded. - Boards arrive only when chosen. They appear in the Search & import panel on the console's Providers page; a search matches file names and returns those files' boards. Importing one saves the board, rendered by Penpot's exporter, as an instance-owned catalog asset.
Design-system administration covers how token sources combine with the active design system.
What you need from Penpot
- Your instance URL, such as
https://design.your-host.example(thebaseUrloption). The connector is written for self-hosted instances and has not been tried against Penpot's hosted service. - The
access-tokensflag on that instance: addaccess-tokenstoPENPOT_FLAGSso Your account > Access tokens is available. - A personal access token from that page, with access to the teams and projects whose tokens you want.
- Optionally, a team, a project or explicit file ids to limit which files are read.
Credential shape
A single sealed string: the Penpot personal access token, sent as Authorization: Token ….
lw providers credential design-penpot # prompts; never argv, never shell historyinstance.json / lw providers add
{
"id": "design-penpot",
"kind": "penpot",
"label": "Design Penpot",
"options": { "baseUrl": "https://design.your-host.example", "teamId": "…", "format": "png", "scale": 2 },
"mapping": { "typeMap": { "tokens": "tokens", "board": "image" }, "defaultType": "image" },
"exposure": { "groups": ["design"], "tier": "reference" }
}Options and mapping
| Setting | What it does |
|---|---|
options.baseUrl (required) | Your Penpot origin. Every call is pinned to this origin. |
options.teamId, options.projectId | Limit which teams and projects are searched for files. |
options.fileIds | Read exactly these files and skip the search. |
options.format | How imported boards render: png (default), svg, jpeg or webp. |
options.scale | The render scale for imported boards, default 1. |
options.exporterUrl | The exporter's origin, when it differs from baseUrl. |
mapping.typeMap (required) | Maps Penpot's two types into the catalog: tokens to tokens (the design-system feed) and board to image (imported media). The console's Penpot card fills this in. |
Verify
lw providers preview --kind penpot --options '{"baseUrl":"https://design.your-host.example"}'
lw providers health design-penpotA penpot rpc get-profile <status> error means the instance URL or token is wrong, or the access-tokens flag is off.
The RPC command and field names come from Penpot's documentation and are not yet confirmed against a live instance; a failed call reports the command (penpot rpc <cmd> <status>).
Notes / limits
- Self-hosted. The connector uses Penpot's token-authenticated RPC against an origin you run, and every call goes only to that origin. Penpot is published under MPL-2.0, so no vendor terms of service apply to the connector.
- Up to 200 files. One sync or search reads at most 200 files, so a very large instance cannot stall a request.
- Board renders need the exporter. Penpot's exporter must be reachable at
exporterUrl, or atbaseUrlwhen that is not set.