Design Tokens

A design token is one named brand value, such as a colour, a radius or a typeface, kept in one place. Change it once and every tool that uses it follows: the colour in a render, the swatch in the colour picker and the value you hand to Penpot all come from the same entry. This page is for the designer or developer who brings tokens into Lolly or takes them out, and for the tool author who wants to know how tokens reach a tool.

Open this in Diagram Builder

Lolly stores tokens in the W3C Design Tokens (DTCG) format, the same format Penpot imports and exports, so a brand defined in Lolly round-trips with Penpot and Tokens Studio. Tokens carry the brand's values both ways. A finished Figma or Penpot file comes in through Design's Import a design instead.

Where your tokens come from

Design System Setup (#/start) is where you make and edit tokens. Its Colours, Type and Tokens rooms write colour, typography and dimension tokens (radius, spacing, sizing, stroke, opacity, rotation and shadows), and its import reads W3C DTCG, Tokens Studio and Penpot files. You can also hydrate a pack from a token file with ingest:brand.

signed by Lolly2026-10-21vector SVG341 paths~38k nodes567 groups1 image490 KBI-check mo mismoKunin ang signed na file signed by Lolly2026-10-21vector SVG341 paths~38k nodes567 groups1 image490 KBI-check mo mismoKunin ang signed na file

Each brand pack ships its design system as a tokens asset in its catalog, and the active content profile decides which pack is in use:

• Lolly Demo (lolly/tokens/demo) is the design system lolly.tools opens with. Its catalog also offers Lolly Starter beside it, through the index's companionDesignSystems field.
• Lolly Starter (lolly/tokens/brand) is the blank brand's design system.
• Your own pack, built by ingest:brand, uses <brand>/tokens/brand.

A pack's design system is the asset its index's brandTokens field points at, or its only tokens asset when the field is absent. The asset is core tier, so it is always available offline, and it is validated against schemas/tokens.schema.json by pnpm run validate:catalog, versioned and checksummed like any asset.

Tokens you make or import live on your device, travel as the tokens.json part of a LollyBrand pack and go into the full data backup as a user asset (Data transfer). A device can hold several design systems, and a link can name one with ds (Reserved URL parameters). Brand architectures shows how several brands can share a system or keep their own.

The corner radius is the plainest dimension token: one slider writes one shape.radius value, and the app chrome, the panels and every tool that opts in follow that value.

signed by Lolly2026-10-21vector SVG8 paths~4.2k nodes12 groups47 KBI-check mo mismoKunin ang signed na file signed by Lolly2026-10-21vector SVG8 paths~4.2k nodes12 groups47 KBI-check mo mismoKunin ang signed na file

The format (a DTCG profile)

A token document is DTCG JSON. A token is an object with $value (required) and $type. Groups are objects without $value, and they pass their $type down to the tokens inside. One token refers to another with a curly-brace alias, {dotted.path}.

{
  "color": {
    "$type": "color",
    "brand": {
      "spearmint": {
        "$value": "#033633",
        "$description": "Spearmint",
        "$extensions": { "com.suse.lolly": { "cmyk": [100, 31, 59, 79] } }
      }
    },
    "semantic": {
      "primary": { "$value": "{color.brand.spearmint}" }
    }
  }
}

Two choices keep Lolly compatible with Penpot while serving print:

• Colours: read every form, store perceptually, resolve to hex. DTCG's newer colour object ({colorSpace, components, alpha, hex}) is parsed, and so is every CSS Color 4 string: #hex, rgb(), hsl(), hwb(), lab(), lch(), oklab(), oklch() and color(<space> …) across 14 colour spaces (engine/src/css-color.ts). That covers everything Penpot writes and more. A value resolves to a hex string (#rrggbb, #rrggbbaa or transparent) for rendering, except a bare colour keyword, which comes back as written. Storage is a separate choice: a derived brand writes oklch() into $value, and a swatch's Stored as control can pin lch (the default), hex, rgb() or hsl() instead. Penpot reads all of these.
• CMYK rides in $extensions. Print anchors live under the vendor key com.suse.lolly. DTCG keeps $extensions for exactly this, and Penpot passes it through untouched, so a colour stays right for print without breaking compatibility. The key is written in DTCG's reverse-domain form, and token files already carry it, so it does not change.

Sets and themes

Top-level keys can be token sets. A $themes array selects and orders sets for each theme, with later sets overriding earlier ones in the Tokens Studio way, and $metadata.tokenSetOrder fixes the order. A document with no $themes is one implicit set, and its paths keep their color.brand.x shape.

Themes with the same group are one choice, and a piece picks one option per group. A group can say what kind of choice it is, such as light and dark (mode) or a choice of lead colour (colourway). Colourways covers several lead colours in one design system.

What a theme group means

A Tokens Studio $themes group is only a name. A design system can also say what choosing between the group's options changes, so Lolly can treat light and dark differently from a choice of lead colour. The statement goes on each entry of the group, under the com.suse.lolly extension key:

{ "name": "Beach", "group": "colourway", "selectedTokenSets": { "colourway/beach": "enabled" },
  "$extensions": { "com.suse.lolly": { "axis": { "kind": "colourway" } } } }

Every entry that states kind or rotation must agree; a disagreement is reported and the first statement is used. A file whose theme entries cannot carry extensions can state the group facts once at the document root instead, as "$extensions": { "com.suse.lolly": { "themeAxes": { "colourway": { "kind": "colourway", "canonical": "spearmint" } } } }. An entry's own statement wins over the root.

Lolly gives behaviour to mode and colourway today. The other kinds are kept, shown and resolved as plain theme choices. A group with no kind, or a kind this version does not know, resolves exactly as it did before kinds existed, and the inspector reports an unknown kind. lolly system inspect --json and host.tokens.inspect() list each group with its kind and canonical option, and host.tokens.themes() gives each theme its id, when the file has one, and its group's kind.

How tools use tokens

Tools reach tokens three ways:

• Inputs, through the platform. The colour field takes its swatches from host.tokens.colors() for the active theme, labelled and grouped by token. Choosing a token swatch stores a reference, not a frozen hex, so a later token edit reaches every linked value.
• Hooks, through host.tokens. A hook can read the token set, resolve a reference or list every colourway's lead with family(). Chart, Mesh Gradient, Filter and Wordmark are among the community tools that do. When the document's theme or colourway changes, the runtime runs onInput once with the id __tokens, so a hook that keeps colours it read can read them again.
• Templates and styles, through canvas variables. The canvas carries the design system's semantic colours as CSS custom properties (--brand-primary and the rest), plus --brand-lead-1 onwards when the design system has two or more colourways. Templates and rendering lists them.

Handing the resolved token tree to a template's context, through the extras mechanism and opted into from the manifest, is not built yet. Fields other than colour link through each field's Input actions menu; Token workflows covers that.

The value model: reference + cached value

When you pick a token-backed colour, the stored value is a reference plus the hex it last resolved to:

{ "ref": "{color.brand.spearmint}", "value": "#033633" }

In the sidebar, a token-backed swatch shows the swatch's name instead of a hex code, which is the visible difference between a linked value and one typed in by hand.

signed by Lolly2026-10-21vector SVG4 paths179 nodes7 groups6 KBI-check mo mismoKunin ang signed na file signed by Lolly2026-10-21vector SVG4 paths179 nodes7 groups6 KBI-check mo mismoKunin ang signed na file

The ref keeps the value tied to the token: editing the token, or switching themes, resolves it again everywhere. The cached value is the fallback for a device where that token is absent. A plain colour string, from a custom pick or any older tool, passes through untouched.

• On load, each token-backed colour resolves again against the live token set and its cached hex is refreshed (resolveTokenRefs in runtime.ts, which mirrors how asset references resolve). modelToValues then hands the template a plain hex string, so templates and data exports never see an object.
• Hooks see the plain hex too (modelForHooks in inputs.ts). The { ref, value } shape never reaches a tool's onInit or onInput, so the common (inputs.x || '').trim() pattern keeps working.
• In a link, a token colour is written as its reference (?bg={color.brand.spearmint}), so a shared link resolves against the recipient's tokens (url-mode.ts). Parsing a {path} gives an unresolved token value that the runtime then resolves.
• Editing past a token, by typing a hex or dragging alpha, writes a plain string, which unlinks the value: you have chosen a colour of your own.

The link behind the next picture holds no colour values at all. Its three colour parameters are token paths from Lolly Demo ({color.spectrum.green-apple}, {color.spectrum.reef} and {color.spectrum.honey}), resolved at render time against whatever brand the device carries.

signed by Lolly2026-10-21vector SVG54 paths378 nodes44 groups42 KBI-check mo mismoKunin ang signed na file signed by Lolly2026-10-21vector SVG54 paths378 nodes44 groups42 KBI-check mo mismoKunin ang signed na file

Round-trip with Penpot

signed by Lolly2026-10-21vector SVG3 paths~1.1k nodes5 groups1 image16 KBI-check mo mismoKunin ang signed na file signed by Lolly2026-10-21vector SVG3 paths~1.1k nodes5 groups1 image16 KBI-check mo mismoKunin ang signed na file

CMYK survives Lolly-to-Lolly round trips through $extensions, and Penpot ignores it, as the standard intends. Two more paths go beyond the token file. Once Penpot is connected under Settings → Connected services, a finished render can be sent from Lolly into a Penpot project as an image. And the Lolly bridge plugin for Penpot, installed by URL from a Lolly instance, can place a working Lolly session on the Penpot canvas as editable shapes.

Theme the app itself

Your design system describes your brand. It can also dress Lolly's own interface, in two ways: lolly.ui.* roles that hold one value in every theme, and a color.chrome group that sets the app's surfaces separately for light and dark.

Lolly UI tokens

Lolly carries a small application UI system, so menus, fields, panels and editor chrome stay coherent even when a brand has no full component library. It travels under a reserved namespace:

lolly.foundation.*  # Lolly's compatible base scale
lolly.ui.*          # stable application roles a design system may override
brand.*             # your identity tokens

The Tokens room's App appearance (advanced) fold lists the Lolly roles, each marked Lolly default until you save a value of your own, which then reads Your value. The defaults affect the app and the Penpot UI-library export, but opening a brand document does not write them into the document. Saving one value adds only that lolly.ui.* leaf, and Reset removes the leaf again.

The supported roles are few: text, surface, action, selection, border and focus colours; control, panel and page spacing; radius by role; elevation, edge and focus effects; UI fonts and type sizes; feedback, overlay and navigation motion; and chrome, overlay and toast layers. Lolly checks each value before it reaches CSS. Unknown paths, unsafe CSS, the wrong type and unresolved aliases stay out of the live app rather than half applying.

Two foundation values are especially useful when you start from a token library:

• shape.radius drives the derived radius scale. Set it to 0px for square controls, or high for round ones; the pill and round roles follow the same value.
• space.base drives Lolly's spacing rhythm (.25×, .5×, .75×, 1×, 1.25×, 1.5×, 2×, 3×), so a system's base unit reaches panels and controls without copying each gap.

Choose Download visible collection in Components to get the components on show as one .penpot archive of editable frames, with both token layers in its tokens.json. Each card's Download as .penpot takes one component, and Download tokens.json takes the tokens alone. The components hold sample data, not your sessions or content. A property Penpot cannot bind natively stays an editable resolved value rather than claiming a live binding.

App chrome from a design pack

A design pack can set the app's room for each theme: the page, the cards and side panels, the top bar, the menus and the text on them. Put a color.chrome group inside a theme set, beside the semantic slots. Every slot is an optional colour, and an alias into your own palette is the usual way to write one.

The app reads its colours in the canonical option of every theme group that declares a kind, apart from light and dark. A design system with colourways therefore keeps the app on its canonical lead while a piece on the canvas uses another. Lolly's blank starter brand states a warm newsprint room this way in its light and dark sets, and a design system with no color.chrome group shows Lolly's own cool room.

Lolly Demo's dark set shows the group in place:

{
  "dark": {
    "color": {
      "$type": "color",
      "chrome": {
        "page": { "$value": "{color.brand.liquorice}" },
        "raised": { "$value": "{color.brand.liquorice-raised}" },
        "overlay": { "$value": "{color.brand.liquorice-panel}" },
        "muted": { "$value": "{color.brand.liquorice-panel}" },
        "hover": { "$value": "#263239" },
        "edge": { "$value": "{color.brand.basalt}" },
        "ink": { "$value": "{color.brand.sugar}" },
        "muted-ink": { "$value": "{color.brand.pebble}" },
        "unsaved": { "$value": "{color.brand.honey}" }
      }
    }
  }
}

The slots set the same properties Lolly's own tokens.css sets, so everything in the app that reads a surface follows the pack. Four things are never set from here:

• the ink of the render canvas (--foreground-canvas): the canvas and the export stages always take the theme's own ink back at their edge, whatever ink the pack states, so a pack's chrome cannot move a pixel of an export;
• the accent (--primary and --ring), which the semantic primaries own;
• the destructive fills;
• the radius and spacing.

*When to use lolly.ui. instead.* The lolly.ui.color. roles hold one value in every theme and set the app's --ui-color- properties directly on the page, so High contrast does not undo them. They suit one fixed colour, such as a single canvas or border colour. Use color.chrome. when the pack has a light room and a dark room, since each theme reads its own set, and when High contrast should still bring back Lolly's measured room.

How the token engine is built

Four layers carry a token from a file to a tool:

1. Engine: engine/src/tokens.ts. Platform-agnostic, like units.ts. createTokenSet(doc, { theme }) parses a document, passes group $type down, resolves {} aliases (chains included, safe against cycles), applies the theme and returns a flat lookup with get, resolve, query({type}), colors() and themes(). It knows DTCG and nothing else: no DOM, no storage and no brand.
2. Catalog: the pack's tokens asset, described above.
3. User tokens: the device-local store for tokens you create or import.
4. Bridge: host.tokens, an optional v1 capability: get, colors, resolve and themes, plus the optional inspect, axes, family, list, active and snapshot (Host API lists them). Each shell implements it over the engine model and its sources; a shell that does not is simply not token-driven. Loading works offline: it prefers the prefetched core asset, then a direct fetch, then the built-in palette.

Open this in Diagram Builder

Token workflows covers inspecting tokens, choosing themes for one document, linking fields and reviewing changes.

Reference

• Engine model: engine/src/tokens.ts: createTokenSet, resolveColorValue, colorToHex, isAlias, isTokenValue, TOKEN_EXT. The format contract is pinned by tests/tokens.test.ts.
• Tests: tests/tokens.test.ts (model) and tests/tokens-value-path.test.ts (URL and hydration round trip).
• Schema: schemas/tokens.schema.json. The SUSE pack's document is generated by scripts/build-brand-tokens.ts.
• Bridge contract: TokensAPI in packages/core/src/host-v1/tokens.ts, re-exported through engine/src/bridge/host-v1.ts. Web implementation: shells/web/src/bridge/tokens.ts.