Lolly Beta
Launch App
  1. Automate
  2. Author tools and design systems

Token workflows

A design system owner can trace where a colour comes from, see what moves when the colour changes and make one poster dark or in the Beach colourway without changing the system. Each task works in the app, in the terminal and over MCP.

Start in the Tokens room of Lolly Design System Setup (#/start?area=tokens). Pick any token to see its value as written and as resolved, which set it came from and every token that reads the value. Opening a token changes nothing. Changes go through a review you apply, and you can undo them.

To follow along, download the Beacon example system. It has independent appearance and density choices, custom vocabulary and semantic aliases. Its border.exampleOutline changes colour and stroke style with appearance, and width with density.

Inspect a token

The Tokens room lists every token definition in the design system, including custom paths and inactive source sets. For each token it shows:

Declared brand roles and consumer slots appear apart from those dependents. A declaration does not prove that anything uses the token, and it is not a rule check. A read-only system offers the same inspection. The list shows 100 tokens a page.

Lolly Design System Setup reads the editable head. A document reads its render version, which can differ from the head when a published version is active.

In Lolly Design

In Lolly Design, open the inspector's Canvas tab. Its Style & look section shows a context strip above the theme rows: Mode for light and dark, Colourway when the design system has colourways and a row for any other theme group. The strip shows the design system and render version the document draws with and where the system came from. It reads Chosen for this document when the document made its own theme choices, and Follows the design system when it has none.

Source and fallbacks lists every theme choice, marks a read-only system and lists any choice this design system does not offer, with the default used in its place. Inspect tokens opens the render version with the document's choices. Trying another choice there is labelled Preview. Return to render choices restores the captured ones. The inspector edits neither the document nor the design system. Follow the design system removes the document's own choices, and its linked values follow the design system's stored choices again. On a design system with colour roles, each role's colour in every colourway and look is listed under the role, not as a separate token. Choose the role's token to see them.

The same strip labels each side of a comparison and the version a release records. A token review labels its before and after renders Editable head and Candidate, each with its theme choices. Publish a version in the Versions room shows the editable head that publishing records. Tool sidebars do not show the strip. In a tool sidebar, token details stay in each field's Input actions menu.

In the terminal and over MCP

In the TUI, press t in the System view. The inspector reads the design system a terminal render uses: the active terminal system, or the content profile's tokens when none is active. Its header shows the source, a short revision digest, one choice per theme group, the set order in effect and any issues.

KeyWhat it does
g, then oPick a theme group, then step its choice. The header reads Preview, and nothing is written.
/Search token paths.
xList only tokens with issues.
EnterOpen a token's trace: its values, winning set and override order, issues and declared roles, then what it reads and what reads this token. Enter on a step opens that token; Esc goes back.
s, then yReview the previewed choices, with a count of the resolved values that change, then store them in $metadata.activeThemeSelection on the active terminal system, so later CLI and TUI renders use them.

A content profile is read-only here. If another shell changes the system after the review starts, the review stores nothing and shows the current choices again.

Agents call lolly_inspect_tokens on the MCP server for the same report as JSON. It reads the server's design system (the one lolly://design-context describes), or a tokens document given with the call. selection takes the _themes object and theme takes one theme name. The answer holds the effective and stored choices, a preview flag, the diagnostics, a page of tokens and, with token, a trace in both directions: up to depth steps (8 by default, at most 16) and at most 200 tokens each way. With Beacon as tokens, selection: {"appearance": "night"} and token: "border.exampleOutline" return the night border, which reads color.semantic.primary and stroke.exampleWidth.

Note: What the counts cover

Counts in the Tokens room, the TUI and MCP cover token references and declared roles inside the token document. Tool hooks and other documents are not counted. Find what uses a token looks further when you ask.

Choose themes for one document

Each imported theme group has its own control, using the source's group names and theme ids, or the theme name when the source has no id. A choice can belong to the design system or to one document.

A session's choices go wherever the session is drawn: a Lolly multi-edit card, a Lolly batch row and the batch CSV's _themes column, a Lolly Design document export and every tool link composed inside the document. Colourways covers choosing a lead colour for a piece.

lolly system inspect --file=beacon.tokens.json --_themes='{"appearance":"night","density":"roomy"}' --json
lolly qr-code --url=https://example.com --_themes='{"appearance":"night","density":"roomy"}' --output=qr.svg

The app's own light or dark appearance and your accessibility preferences stay separate from these design choices.

When a tool asks for one theme by name

A tool can ask for one theme by name, as in host.tokens.colors({ theme: 'light' }). That request picks the theme in the group that declares it, and every other group keeps its choice. For each of those groups the order is: its entry in an explicit selection when one is given (a given selection replaces the document's stored choices whole), otherwise the document's stored choice; then activeThemes; then the group's canonical option. A hook that asks for light therefore still draws the piece's colourway. Engine versions before 1.265 reset every other group to its first option on such a request. A theme name that no group declares is reported and changes nothing else.

Documents store the design system's choices in $metadata.activeThemeSelection, render links use _themes (a JSON object in the reserved underscore namespace) and sessions carry __tokenSelection.

A field linked to a token redraws when the token or the theme changes. The three-dot Input actions menu beside a field's label has its Design token status, a picker of compatible tokens and the link actions, next to Use as a tool input (or Reset this input in a generated tool). Number, text and font-family select controls can link compatible tokens.

Two actions appear throughout:

Undo and redo keep the right remembered link for each custom value. Edit source value in the inspector makes a separate reviewed change to the token. A missing or incompatible link keeps a labelled cached value where one exists. Hooks and templates always receive resolved values.

A number field accepts number tokens and absolute dimensions, converted at CSS 96 DPI. It refuses relative units, which need a reference size. Select controls keep their own list of allowed choices.

In Lolly Design, select a layer and expand Token links inside its property group. Choose a property, then Link a token. Adjust the value in the usual number, colour or font editor. Editing a linked value makes a local override. Opening or filtering a picker changes nothing. Each link or custom action has its own undo step.

For several selected layers, common paint and compatible text groups offer the same actions. Linking applies one chosen value to every selected layer. Make custom keeps each layer's own value. Restore link appears when every selected layer remembers the same token. Geometry follows the inspector's single-layer rules.

ConsumerWhat can link today
Tool inputsNumber, text, long text and compatible select or font-family inputs. Colour controls keep their own picker.
Lolly Design geometryDeclared position, size and rotation in a single-layer selection.
Lolly Design paint and effectsColour, opacity, corner radius, stroke width and each number in a shadow. Colour links use the document's SDR or wide-gamut colour face.
Lolly Design textFont family and declared size, spacing and padding. Whole typography sets family, size, weight, tracking and line height in one undo step.
Lolly Design compositesOne shadow with zero spread and no inset; a gradient of 2 to 12 resolved sRGB stops, written as a rightward linear gradient. Layered shadows and unsupported gradients are refused.
Lolly Design bordersWhole borders: colour, absolute width and solid, dashed or dotted style in one undo step. Custom stroke styles and relative widths are refused.
Lolly Design motionDuration tokens convert to the field's seconds or milliseconds; easing tokens become checked cubic Bezier curves. A zero-delay transition links Enter duration and easing for one layer that is not a frame.
Composed paragraphsLine height, the space before and after and the start, end and first-line indents, at the caret, range or story. Whole typography sets font, size, weight, tracking and line height together.
Not yetTransition delay, Exit and frame or deck consumers.
Linking typography, borders and motion in Lolly Design

Composites keep separate links. A whole composite keeps its own reference and adapter on each property. Editing one property keeps the other links. A missing or incompatible source value keeps its last value. Composed paragraphs store their links with the paragraph settings, and linking across paragraphs keeps their other links.

Whole typography on composed text records the exact face. Linking finds an installed face for the token's family at its exact weight, plus an italic face when the text has italic runs. It stores those faces with the text by content digest. When a design version with published fonts is active, the faces come from that version's pinned files. A nearer weight or another family is never substituted, even for a brand font that ships one file per weight. The link is refused and the field shows the missing face.

Linking clears size, weight, tracking and font overrides inside the linked paragraphs, so they cannot hide the link. Other formatting stays. Undo restores the overrides in the same step. Italic runs take the italic face. A theme change refreshes the text only when every face the new values need was pinned for this link earlier. Otherwise the text keeps its last values and the field reports the missing face. Linking the token again in that theme pins the missing face. Changing the size, weight, tracking, font or line height of a whole linked paragraph makes the link custom. Formatting one word inside the paragraph does not. A named character style that sets its own size, weight, tracking or font, such as a code style, keeps that value without making the link custom.

Borders. Border and stroke-style links clear an authored dash array and custom dash and gap lengths in the same step, so the linked style reaches the renderer. Editing any dash setting makes the style custom. Colour and width still follow their tokens. Make custom keeps the rendered values. Restore link checks the source again and clears the local dash overrides. Undo restores them together. An incompatible border refresh keeps every active property from its last usable source.

Motion. In a layer's Motion group, choose Enter transition inside Token links, pick a candidate and check its status, then Link token applies duration and easing in one undo step. The transition needs zero delay, a duration within the Enter field's 100 to 3000 ms and a valid cubic Bezier curve. Candidates that do not qualify stay visible with the reason and a disabled Link action. Selecting one changes nothing. The curve sets the Enter preset's geometry. Opacity keeps the preset's own behaviour, and timeline placement stays separate. Editing one linked field makes that field custom. A valid easing link can still refresh while duration stays custom. If any active part is incompatible or unresolved, every active property keeps its cached value. Restore link for the whole transition checks both fields and applies them together. An unsupported source leaves the layer unchanged.

Where links are kept. Lolly Design keeps links in an appended metadata field beside the ordinary properties. Links, custom values and remembered links survive saved URLs, sessions and portable document snapshots. Opening through the engine refreshes linked properties and keeps intentional overrides and cached values.

Token formats. Typography, shadow, border, transition and gradient composites accept bounded nested aliases in the supported composite fields. An incompatible reference type stays visible in the inspector. Unknown token types, $ref and $extends are kept as source data and reported where unsupported.

In links, typed references travel as _ref.<inputId> with a plain companion value for older hosts. Literal text such as {title} stays literal. Colour links keep their own form (Design Tokens). A custom value keeps its remembered link in _restore.<inputId> and in the saved session.

Batch and Lolly Multi-edit can link one token across many rows or sessions. In Lolly Batch, open a column's Fill popover. Number, text and choice columns have a Design token section beside the fill value. In Lolly Multi-edit, each session card has the same Input actions menu as a tool sidebar and acts on that session only. The Shared card's menu reaches every session that declares the input.

Choosing a token opens a review before anything changes. Each row or session shows its current value and the value it would get, resolved in that document's own theme choices and checked against its own input.

Apply writes only the selected documents. Cancel writes nothing. Make custom and Restore link work across the selection. The Restore review selects the documents that remember the same link.

In the Batch grid, a linked cell is shaded and its accessible name includes the token path. Typing, picking, pasting or filling over a linked cell makes a custom value that remembers the link, as in a tool sidebar.

Warning: Copying cells drops the link

Cell copy and CSV export carry the value shown, not the link.

Rows opened from saved sessions keep the session's theme choices and links, and render with those choices.

Review a change

  • Make the change. Edit a token, generate a scale from a recipe or bring in an updated file from upstream.
  • Read the review. It lists your changes and every resolved value they move. It can render an existing piece before and after.
  • Apply or discard. Apply reviewed change commits it through the usual saving and undo. Discard preview writes nothing.

Source edits, generated scales and upstream comparisons capture the document as it is.

Note: A change in the meantime blocks Apply

A token edit, a system switch or a change to a referenced resource in the meantime makes Apply unavailable.

When a production host is available, the review can render one existing poster, title slide, content slide or Lolly Chart before and after. Renders run one at a time, with a cancel and a deadline. The shared comparison controls handle alignment and the noise threshold. A result describes those two outputs, not every theme combination or every document.

Registered recipes generate colour ramps, pixel spacing scales and modular type scales. A recipe's settings, version, outputs and overrides travel in the Lolly extension. Its outputs stay ordinary DTCG tokens that older readers can use. Regenerating keeps recorded local overrides and refuses to overwrite a hand-made token.

lolly system diff incoming.tokens.json --file=local.tokens.json --json
lolly system generate --recipe=recipe.json --file=local.tokens.json --output=candidate.tokens.json
lolly system sync incoming.tokens.json --base=earlier.tokens.json --revision=release-42 --json

sync compares base, local and incoming, and records the source revision and digests. By default it only reviews. --apply updates the active terminal system after a revision check. Conflicts need --keep-local. External files take --output. The web review accepts exact earlier and incoming JSON files. Each conflict shows the earlier, local and incoming definitions and needs Keep local or Use incoming before Apply.

Fonts in a published version

New font pins made when you publish a version locally record family, weight, slant and subset. Replacing or deleting a pinned face keeps its exact bytes in the existing copy-on-write store. Web rendering uses separate release family names for CSS and vector shaping. The Node resolver checks the pinned bytes and supplies variable weights and subset fallback faces.

Missing or changed bytes for these pins fail visibly. Portable snapshots keep the family names as authored. Worker rendering uses a separate release projection. Earlier pins that only recorded names keep their old behaviour. The guarantee covers declared local faces you pinned. It does not promise identical raster bytes across platforms or pin every platform font.

Find what uses a token

The inspector's Used by list covers references inside the token document. Below the list, Check saved work and tools looks for the selected token in two more places on this device: saved sessions in this browser and the tool manifests in the mounted catalog. One check covers every token in the workspace. Choosing another token shows its results without checking again. The check runs only when you ask, can be cancelled and writes nothing.

Counts cover direct links only. A session that links another token which reads the selected one is counted under that other token, which Used by shows. Each count says how many sessions or tools were read. Anything that could not be read or fell past the size limits is reported as not counted, not as zero.

Shared projects, other devices, earlier versions in History, the defaults of tools added from files and values that hooks compute are outside the check. A result describes this device at the time shown. When saved sessions change afterwards, the section notes the change and offers Check again. Sessions record which design system was active when they were saved. The result separates sessions saved with this system from those saved with another.

Components shows the workspace, the context strip and linked fields in their linked, custom, unresolved, mixed and read-only states.

Section links from the earlier guide