Lolly
Buka Aplikasi
  1. Otomatiskan
  2. Buat alat dan sistem desain

Composition and brand overlays

Tools can build on each other instead of copying each other. composes embeds another tool's output, the brand logo helper picks the design system's logo for the background and extends lets a brand pack change one file of a community tool.

Composition (composes)

A tool can embed another tool's rendered output as an image. 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

Without a manifest, people get the same result by pasting a Lolly tool link into any asset input (A pasted tool link becomes an image). Use composes for renders you wire into the layout. The pasted link is 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 like a cycle, with an empty slot. 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.

Brand logo (auto-switching)

Do 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 the slot to an asset id with host.tokens.resolve() and fetches the actual SVG image with host.assets.get(). The same tool then 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. When a slot is empty, the helper tries the other orientation and treatment:

// 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}}

An <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 the helper 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 adjusts a community tool, for example 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>/). Every reader gets the same union: 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 with an error the first time anything resolves that profile. pnpm run validate:catalog also rejects such an overlay. The validator asks the same resolver every shell asks, so the combined result is validated like any other tool.