Lolly
Buka Aplikasi

OtomatiskanBuat alat dan sistem desain

Composition and brand overlays

Tools can build on each other instead of copying each other. A badge can embed the QR tool's real output, a card can pick whichever logo the design system offers for a dark background and a brand pack can change one file of a community tool without forking the rest. This page covers those three patterns: composes, the brand logo helper and extends.

Composition (composes)

A tool can embed another tool's rendered output as an image instead of reimplementing the other tool. Declare the child in the manifest and use it in the template like any asset, with no hook code:

// tool.json
"capabilities": ["compose"],
"composes": [
  { "id": "badgeQr", "tool": "qr-code", "format": "svg",
    "inputs": { "url": "{{url}}", "color": "#0c322c", "join": true } }
]
{{!-- template.html - guard it: composition can fail gracefully --}}
{{#if badgeQr}}<img src="{{asset badgeQr}}" alt="">{{/if}}

A parent tool's composes entry renders the child tool through the same engine path, and the result fills an image slot in the parent's template. Nesting stops at three levels, and a cycle leaves the slot empty.A parent tool's composes entry renders the child tool through the same engine path, and the result fills an image slot in the parent's template. Nesting stops at three levels, and a cycle leaves the slot empty.Open this in Diagram Builder

People get the same result without a manifest: any asset input accepts a pasted Lolly tool link (A pasted tool link becomes an image). Use composes for renders you wire into the layout, and leave the pasted link for people choosing what fills an image slot.

Composition depth and baking

Nesting stops at 3 levels: a tool composing a tool composing a tool. A deeper chain fails the same way a cycle does, gracefully, with an empty slot. When a design needs to go deeper, bake the inner render: tick Freeze as a static image in the picker's render card. A baked image is a frozen copy of the bytes. It uses no nesting depth and never renders again by itself, so it does not update when the source tool changes. Its slot shows a "baked from …" row with a Re-bake button, and a way to edit the source tool's inputs, so a stale copy is one click from fresh.

Brand logo (auto-switching)

A tool should not hard-code one logo file. A design system lists its logos as token slots under asset.logo: horizontal- (wide) or vertical- (stacked), then primary or mono, with -reverse added for a dark background. In the Lolly Demo design system, {asset.logo.vertical-primary} resolves to lolly/logo/primary and {asset.logo.vertical-primary-reverse} to lolly/logo/reverse. A hook picks the slot that fits the background and the space, resolves it to an asset id with host.tokens.resolve(), and fetches the actual SVG image with host.assets.get(), so the same tool shows the right logo on any design system that fills those slots.

The shared helper resolveBrandLogo(dark, mono) in community/_shared/brand-logo.js does this, and tries the other orientation and treatment when a slot is empty:

// hooks.js - WCAG luminance decides the reverse slot; the ink comes from an input.
async function onInit({ model }) {
  const inputs = Object.fromEntries(model.map(i => [i.id, i.value]));
  const dark = relLuminance(inputs.background) < 0.5;   // dark bg → a -reverse slot
  return { logo: await resolveBrandLogo(dark, inputs.ink === 'mono') }; // → extras.logo (an AssetRef, or null)
}
<!-- template.html - the actual SVG asset, not a font lockup -->
{{#if logo}}<image href="{{asset logo}}" .../>{{/if}}   <!-- inside an <svg> → true vector export -->
{{!-- or, in an HTML canvas: --}}
{{#if logo}}<img src="{{asset logo}}" alt="Logo">{{/if}}

Putting the <image> inside an <svg> lets the export inline the logo and write true vector SVG; an <img> in an HTML canvas exports as raster or PDF only. certificate, stationery, link-card, deck-studio and multi-page-pdf use the helper. Copy it into your own hooks with the shared-region markers and pnpm run sync:shared (Shared helper regions).

Brand overlays (extends)

A brand pack that only needs to adjust a community tool, with a different template or a few reworded translations, should not carry a whole copy that drifts from the original. Declare the brand's tool folder an overlay instead:

// brands/<brand>/tools/<id>/tool.json - same id as the community tool
{
  "id": "color-palette",
  "extends": "community",
  ...
}

and keep only the files that differ in the overlay folder. The content resolver (packages/node-shell/src/content-roots.ts) then reads the tool as a file-by-file union of the base (community/<id>/) and the overlay (brands/<brand>/tools/<id>/), the same union for every reader: a dist/ build, the CLI, the dev server and the catalog signer.

Peringatan: A broken overlay stops with an error

An overlay whose base is missing (no community/<id>/tool.json), an extends value other than "community" (the only base pack in v1) or an extends on a community tool itself fails loudly the first time anything resolves that profile, and pnpm run validate:catalog rejects it too. The combined result is validated like any other tool, because the validator asks the same resolver every shell asks.