Lolly
Apri l'app

AutomatizzaCrea strumenti e design system

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.

One colour token feeds a tool's render, the swatches in the colour picker and a Penpot export, so a single edit reaches all three.One colour token feeds a tool's render, the swatches in the colour picker and a Penpot export, so a single edit reaches all three.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. A token file carries the brand's values; a finished Figma or Penpot file comes in through Lolly Design's Import a design instead.

Where your tokens come from

Lolly 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.

The Tokens room on a fresh system - a card with the ways to start, the shape and spacing sliders, More tokens and the two advanced folds signed by Lollyvector SVG58 paths~30k nodes80 groups2 images324 KBCheck it yourselfScarica il file firmatoThe Tokens room on a fresh system - a card with the ways to start, the shape and spacing sliders, More tokens and the two advanced folds signed by Lollyvector SVG58 paths~30k nodes80 groups2 images324 KBCheck it yourselfScarica il file firmato

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:

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.

The Rounded corners control in the Tokens room - a live preview square, a slider and the value it writes, all standing for a single dimension token signed by Lollyvector SVG8 paths~4.2k nodes12 groups47 KBCheck it yourselfScarica il file firmatoThe Rounded corners control in the Tokens room - a live preview square, a slider and the value it writes, all standing for a single dimension token signed by Lollyvector SVG8 paths~4.2k nodes12 groups47 KBCheck it yourselfScarica il file firmato

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:

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. 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" } } } }
FieldDescribesMeaning
kindthe groupmode (light, dark and similar looks), colourway (which lead colour fills the primary role), or one of expression, medium, contrast, density, campaign, brand
rotationthe groupThe rule pickColourway applies when given none: canonical, cycle, by-key, shuffle or by-date (Rules for a series)
canonicalone optiontrue on the option a piece uses when it chooses none. Without it, the first option is canonical
windowone option{ "from": "2026-12-01", "to": "2026-12-31" }, inclusive ISO dates, read by by-date

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.

Motion tokens

A design system can define motion for Sequence: durations, curves and springs. Lolly reads three DTCG types and one extension:

Token$valueWhat Lolly does with it
duration{ "value": 200, "unit": "ms" }, or "200ms" / "0.2s"Offered as a suggestion in length fields: a clip's Enter (ms) and Exit (ms), and Choreograph's Length
cubicBezier[x1, y1, x2, y2], x between 0 and 1Listed as a curve a keyframe can follow
transition{ duration, delay, timingFunction }Its timingFunction is listed as a curve; its duration is shown beside the curve and never changes keyframe times

DTCG has no spring type, so a spring is any token that carries spring under the com.suse.lolly extension key. Give it a transition type with a curve that resembles the spring, so a tool that does not read springs still gets a sensible curve:

{
  "motion": {
    "spring": {
      "bouncy": {
        "$type": "transition",
        "$value": { "duration": { "value": 700, "unit": "ms" }, "delay": { "value": 0, "unit": "ms" }, "timingFunction": [0.3, 1.3, 0.6, 1] },
        "$extensions": { "com.suse.lolly": { "spring": { "stiffness": 400, "damping": 20, "mass": 1 } } }
      }
    }
  }
}

stiffness is required. Give damping directly, or dampingRatio (1 means no bounce) and Lolly works out the damping; mass is 1 when absent. Lolly Demo and Lolly Starter ship a small scale: motion.duration.short, medium and long; motion.curve.standard, emphasised and exit; and motion.spring.gentle and bouncy.

A keyframe follows a curve or spring by its token path, so the path has to fit in a link: letters, digits and hyphens between dots, at most 64 characters. A token with any other path is left out of the list. Animating covers following a token from the Keyframes popup.

How tools use tokens

Tools reach tokens three ways:

Nota: The token tree does not reach a template yet

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.

A tool's colour row holding a token-backed value, the trigger showing the swatch circle and its name instead of a hex code signed by Lollyvector SVG4 paths179 nodes7 groups6 KBCheck it yourselfScarica il file firmatoA tool's colour row holding a token-backed value, the trigger showing the swatch circle and its name instead of a hex code signed by Lollyvector SVG4 paths179 nodes7 groups6 KBCheck it yourselfScarica il file firmato

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.

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.

A mesh gradient whose green, turquoise and gold all arrived as token references in the link rather than as hex values signed by Lollyvector SVG54 paths378 nodes44 groups42 KBCheck it yourselfScarica il file firmatoA mesh gradient whose green, turquoise and gold all arrived as token references in the link rather than as hex values signed by Lollyvector SVG54 paths378 nodes44 groups42 KBCheck it yourselfScarica il file firmato

Round-trip with Penpot

  • Export from Lolly. In Lolly Design System Setup, open the Tokens room. Its format menu offers several formats; choose Design tokens (JSON) and press Download. Faces you chose in the Type room (Primary, Headings, Code, Italic) travel in the same file as font tokens, and roles left on the platform default stay out of the file.
  • Import into Penpot. Open a Penpot file, switch to the Tokens panel in the left sidebar and import the JSON. Your sets appear in the panel.
  • Apply them. Apply the colours and fonts to shapes and text from Penpot's Tokens panel.
  • Bring them back. Import a Penpot single file, ZIP or multi-file export ($themes.json, $metadata.json and one file per set) in Lolly Design System Setup or with ingest:brand.

The Tokens room's download tools: the format menu, Download, Copy CSS and Add from…, which carry the same colours back out as DTCG JSON signed by Lollyvector SVG11 paths~8.3k nodes11 groups1 image93 KBCheck it yourselfScarica il file firmatoThe Tokens room's download tools: the format menu, Download, Copy CSS and Add from…, which carry the same colours back out as DTCG JSON signed by Lollyvector SVG11 paths~8.3k nodes11 groups1 image93 KBCheck it yourselfScarica il file firmato

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.

DESIGN.md

DESIGN.md is a format for describing a visual identity to coding agents, with YAML tokens and a Markdown body. It is at version alpha, and Lolly targets that version.

In. lolly system import DESIGN.md reads the tokens into a new design system and keeps the file beside the system. --dry-run reads the file and changes nothing. Colours, type families, sizes, radii and spacing map to tokens. The format's component entries have no token form in Lolly, so they stay out of the tokens. The reader refuses a file it cannot read, such as one with anchors, a repeated key or no tokens, and it reports a single value it cannot read and leaves that value out. Prose stays text: nothing in the file is acted on.

Out. A brand page holds one DESIGN.md per colourway and mode, because the format has no theme or mode of its own. Named colours sit in a table in the body.

A design system that declares colour roles adds its own words: each role's name, what it is for and what Lolly reads it as, in the format's own bullet form under Colors. A subsection, Colour roles, adds a table of both looks and a fenced json block holding the same facts. The tokens above the block stay complete, so a reader that does not know the block loses nothing it asked for. When Lolly reads the file back, the block is what restores the roles.

Colour roles in other formats

A design system can name its colours in its own words, with a role per word. Each format below has a different amount of room for those words. A design system with no declared roles writes exactly the bytes it wrote before, on every route.

FormatWhat comes back from a round tripWhat does not, and why
DTCG and Tokens Studio JSONEverything: roles, names, descriptions, brand order, what each role fills, and every value in every colourway and look.Nothing. The record travels in the file's $extensions.
DESIGN.mdRole names, descriptions, brand order and what each role fills. Both looks of the file's colourway, which values follow another look, and which on-colours Lolly worked out.Other colourways, because the format holds one per file: a brand page keeps one file for each. A link to a named colour comes back as its value, and the named colours themselves stay in the prose, since a token no component uses counts as a mistake to the format's linter. A role that is not a colour, a binding to one tool's own field, a house rule's structure and the mark on a copied value have no place in the block.
Penpot (.penpot)Names, values, links, sets and themes. Each role's name, description and place in the brand's order sit in the description of its color.semantic.<id> token, and any description the token already had stays on the lines after. Lolly takes the role's words back out on import, on every route, and what each role fills comes back from the links.A role that is not a colour, a binding to one tool's own field, house rules, the mark on a copied value and CMYK anchors, because Penpot's token keeps a value, a type and a description and nothing else. A colourway group's kind comes back from its name, colourway, so a group renamed in Penpot stays a plain theme group.
Penpot's Tokens panelNames, values, links, sets and themes, when you import Lolly's JSON there.The role record sits at the top of the JSON, and Penpot's panel has no place for that record. Use a .penpot file to carry a role's words.
PowerPoint (.pptx)The brand's order: the theme's six accents read the roles in that order, for the colourway the deck is drawn in.Names and descriptions, because a theme has slots and no words. A role that fills the background, text, quiet text or hairlines takes that slot instead of an accent, and a seventh role has no accent to fill.

The words are someone's text in every format. A name or description that speaks about permissions or running code stays out, and everything else is drawn as plain text.

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:

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.

SlotSetsForLeft out
page--backgroundthe pagethe theme keeps Lolly's room, because the other surfaces need a page
raised--cardcards, side panels and the top barworked out from page
overlay--popovermenus, dialogs and popoversthe raised colour
muted--muted and --secondarywells, tracks and quiet fillsworked out from page
hover--accenthover and active surfacesworked out from page
edge--border and --inputhairlines and field edgesworked out from page
ink--foreground and the card, popover, secondary and accent inksbody text on the chromeLolly's ink for the theme
muted-ink--muted-foregroundsecondary textLolly's muted ink for the theme
unsaved--brand-warnthe colour that marks unsaved worksee "Unsaved work" below

The app reads its colours in the canonical option of every theme group apart from light and dark, except the colourway group, where it reads the colourway the person chose in Settings → Appearance. A design system with colourways therefore keeps the app on the person's colourway, or 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:

*When to use lolly.ui. instead.* The lolly.ui.color. roles 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, and when High contrast should still bring back Lolly's measured room.

Slots you leave out

State a page and Lolly works the other surfaces out from it, in the page's hue. The steps are lightness in OKLCH, measured from the page:

SlotLight pageDark and brand page
raised0.009 darker0.037 lighter
muted0.032 darker0.117 lighter
hover0.048 darker0.155 lighter
edge0.131 darker0.155 lighter

An edge also carries more of the page's tint than the other surfaces: one and a half times the page's chroma, at least 0.01 and at most 0.04. Lightness stays between 0 and 1, and a colour that falls outside sRGB has its chroma reduced until it fits.

The checks a theme must pass

Each theme is checked whole. If any check fails, that theme keeps Lolly's own room and the browser console reports the first pair that failed. The other theme is judged on its own, and a value that does not parse counts as left out.

  1. Every surface keeps the theme's lightness band in OKLCH: 0.85 to 1 for light, 0 to 0.4 for dark and 0.2 to 0.42 for brand.
  2. The ink, yours or Lolly's, reads 4.5:1 or better on the page, raised, overlay, muted and hover.
  3. The muted ink reads 4.5:1 or better on the page, raised, overlay and muted.
  4. For the brand theme only, the inks and edge of Lolly's High contrast brand room still clear their bars on your surfaces.

Each applied theme also restates the error text colour, adjusted until it reads 4.5:1 on the pack's surfaces and on a danger wash over them.

High contrast, the brand theme and unsaved work

High contrast. The light and dark chrome steps aside while High contrast is on, and Lolly's own High contrast room shows for every pack. That room is measured against Lolly's own page, and keeping a pack's page under it would let cards sink into the page. The brand chrome stays in force, and the High contrast brand inks and edge win over the pack's own, which is why the fourth check exists. The unsaved colour is not a surface, so it applies under High contrast too.

The brand theme. Brand chrome is read only when the document's $themes declares a theme named brand, and then from that theme's set. Asking the token engine for a theme a document does not declare answers with its default sets, which would hand the brand theme the light values. Without a brand theme, the brand theme stays as Lolly builds it from the pack's primaries. Two High contrast measurements still use the brand room Lolly builds rather than a pack's brand chrome: the repair of the accent and the error text red. The checks above do not measure the accent in any theme either, because the semantic primaries own the accent. No shipped pack states brand chrome, and a pack that does should check its accent and its error text in the brand theme with High contrast on.

Unsaved work. When any theme states unsaved, the colour moves out of the app's automatic pick into a block for each theme. The brand theme takes the brand set's colour, else the dark set's, and a theme that states none takes the automatic pick. That pick is the colour in the pack nearest red to yellow, and when the pack has none Lolly's own amber stays. The label on it is black or white, whichever reads better.

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.

Catalog and user tokens feed the engine token model, which resolves themes and aliases. The shell exposes that model through host.tokens so tools can look up resolved values.Catalog and user tokens feed the engine token model, which resolves themes and aliases. The shell exposes that model through host.tokens so tools can look up resolved values.Open this in Diagram Builder

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

Reference

Section links from the earlier guide