platform-widget-generate

Generating a Widget Bundle

Author a complete WidgetBundle: a UEM tree (tile/widget), a JSON Schema describing the widget's input contract, and the .uiwidget-meta.xml that registers the bundle.

When to Use This Skill

Use when the user asks for a widget, mosaic, fragment, or card-style rich UI surface. Do not use this skill for custom-LWC renderers or for renderer.json files inside a Custom Lightning Type bundle — those belong to platform-custom-lightning-type-generate.

Inputs

• `widgetName` (required) — camelCase identifier; becomes the directory name under uiWidgets/.
• A shape — what data the widget renders. The widget cannot be generated without it. The shape arrives one of two ways, in priority order:

1. `lightningTypeSchema` — { path, apexClassFqn } for an existing Apex-backed Lightning Type. The FQN takes one of two forms: outer-class (<namespace>__<ClassName>) where the outer class is the payload, or inner-class (<namespace>__<ClassName>$<InnerClass>) where the named inner class is the payload. Passed in by the platform-lightning-type-widget-coordinate orchestrator. When present, derive per references/schema-from-lightning-type.md.
2. Extracted from the user's prompt — when no lightningTypeSchema is passed, infer the shape directly from what the user wrote: a pasted JSON payload, an enumerated field list ("id as string, total as number"), or descriptive prose. The output is the same ordered list of { name, type, required } either way.

If neither source yields a shape, STOP and ask the user before proceeding.

Output

Three files in <pkgDir>/uiWidgets/<widgetName>/:

See references/widget-bundle-layout.md for the <pkgDir> resolution procedure and the exact <widgetName>.uiwidget-meta.xml shape.

Composition

A widget body is a UEM tree of blocks nested under contentBody.widgetBody. The root node is tile/widget. Every node — root and non-root — has the same shape: no type key; just definition, optional attributes, optional meta, and optional children. Block shape:

interface Block {
  definition: string  // {namespace}/{blockName} — root is "tile/widget"
  attributes?: Record<string, any>
  meta?: { // see references/widget-meta-directives.md
    forEach?: string
    forItem?: string
    if?: string
  }
  children?: Block[]
}

The first child of tile/widget.children SHOULD be a single tile/column. All widget content typically goes inside that first child for predictable vertical structure across surfaces.

Available Invocable Actions

Both are standard invocable actions on the target org.

Calling Convention

Fire each action with whichever mechanism is available: the H360 MCP dispatch tool (a POST to the endpoint path with the request body) or sf api request rest. Use v{version} = this skill's minApiVersion. Never use curl, and never extract the org's access token.

sf api request rest '/services/data/v{version}/actions/standard/<actionName>' --method POST --body '<request body>' --target-org <org>

Response Handling

Each response is an array with one envelope (dispatch nests it under body). Check three failure layers, in order:

On success, read [0].outputValues.

discoverUiComponents

Purpose: Discover the palette of blocks available for composition.

Endpoint: POST /services/data/v{version}/actions/standard/discoverUiComponents

Request body: {"inputs":[{"pageType":"FRAGMENT"}]}

Returns: outputValues.componentDefinitions[] — list of { definition, description, label }.

getUiComponentSchemas

Purpose: Fetch schemas (property types, required vs optional, validation) for selected blocks.

Endpoint: POST /services/data/v{version}/actions/standard/getUiComponentSchemas

Request body: {"inputs":[{"pageType":"FRAGMENT","componentDefinitions":["namespace/definition", ...]}]}

Returns: outputValues.componentSchemas[] — list of { definition, success, schema } (schema is a YAML string). Partial failures are supported.

Never pass tile/widget to getUiComponentSchemas — it is a fixed wrapper, not a queryable component.

Attribute Binding

• Bind a block property to runtime data with {!$attrs.<attrName>}. <attrName> MUST match a property name in schema.json.
• Inside a forEach, reference the loop variable instead — e.g. "text": "{!$item.name}". See references/widget-meta-directives.md.
• A binding may be a formula expression instead of a bare field reference. See references/widget-formulas.md for the full supported-function list, syntax, and gotchas.
• Localization: only when the user asks for localized or translated text (or names Custom Labels / $Label), write static, user-visible strings as Custom Label references — {!$Label.c.<LabelName>}. See references/widget-labels.md.

Actions

tile/button supports an actions attribute that dispatches an action node on an event. Two action definitions are supported:

See references/widget-actions.md for complete sendMessage and openLink button JSON.

A `tile/button` with no `actions` attribute renders disabled — a button exists to trigger an action, so always attach a click action to a button meant to be interactive.

Layout Best Practices

These conventions cover widget structure — how blocks are grouped and stacked.

• Nesting: Prefer flat layouts. Only nest a tile/column inside a tile/row (or vice versa) when the visual orientation actually changes for that subgroup.
• Authoritative palette: the table above lists typical layout primitives. Always confirm a block exists by inspecting discoverUiComponents output — do not assume a block name from this table without seeing it in the discovery response.

Styling Best Practices

Style semantically (variants, not literal colors or pixels), one primary button per group, one h1 per widget, Lucide icons only. Read references/widget-styling.md before assigning variants, sizes, or icons.

Workflow

1. Resolve the widget spec — an ordered list of { name, type, required }. Source depends on which input was provided (see Inputs):

• If lightningTypeSchema was passed by the orchestrator → derive per references/schema-from-lightning-type.md.
• Otherwise → infer the list directly from the user prompt (pasted JSON payload, enumerated field list, or descriptive prose).

1. Discover blocks (REQUIRED — do NOT skip). Call the discoverUiComponents invocable action (see Available Invocable Actions) and match widget-spec property types against the returned label/description values. If `isSuccess` is `false`, `errors` is non-empty, or `componentDefinitions` is empty, STOP and surface the error verbatim — do not improvise block names from memory, prior runs, or training data.

1. Select blocks. Choose one block per widget-spec property, plus structural primitives from Layout Best Practices.

1. Get block schemas (REQUIRED — do NOT skip). Call the getUiComponentSchemas invocable action for the selected blocks. Review property metadata, including each property's default — omit any attribute whose value would equal it (see references/widget-styling.md). If `isSuccess` is `false`, `componentSchemas` is empty, or any entry has `success: false`, do not use that block — re-select a different one from step 2's results; if none works, STOP and surface the error. Never improvise from existing widgets in the project.

1. Build the UEM tree (example reads REQUIRED — do NOT skip). First, identify which patterns match the widget spec and read each matching example file from this skill's own examples/ directory (<skill-root>/examples/):

A spec may match multiple patterns (e.g. a list of items where some items render conditionally reads both list-with-foreach.json and conditional.json). Read every matching example, and only those — do not skip the read because the pattern feels familiar.

Before writing any formula, read references/widget-formulas.md in full — it is the authoritative list of supported operators and functions; do not improvise a function name or operator that isn't documented there.

Before writing any `$Label` reference, read references/widget-labels.md in full.

Then:

• Map each widget-spec property to a block property; preserve spec order.
• Decide root iteration: single object → properties directly under root tile/column. Collection → wrap repeating block in forEach/forItem. See references/widget-meta-directives.md.
• Bind values with {!$attrs.X} (or {!$item.X} inside forEach).
• For conditional blocks, add "if" on meta — either a bare lightning__booleanType property, or a formula expression that evaluates to boolean. See references/widget-formulas.md.
• When the widget spec calls for a computed value (a total, a derived label, a formatted string) rather than a raw field, express it as a formula inside {!...} per references/widget-formulas.md — do not invent a new schema property to hold a value that can be computed from existing ones.

1. Author `schema.json`. Build the JSON Schema from the widget spec. Fields live one level deep under an attributes wrapper:

   {
     "title": "<Widget Display Name>",
     "description": "<one line about what the widget shows>",
     "type": "object",
     "properties": {
       "attributes": {
         "lightning:type": "lightning__objectType",
         "properties": {
           "<propertyName>": {
             "title": "<label>",
             "description": "<short description>",
             "lightning:type": "<lightning__textType | lightning__numberType | ...>"
           }
         }
       }
     }
   }

Required root keys: title, type: "object", properties.attributes (with lightning:type: "lightning__objectType" and a nested properties map). See references/schema-from-lightning-type.md for full primitive type guidance.

1. Author `<widgetName>.uiwidget-meta.xml`. See references/widget-bundle-layout.md for the exact shape.

1. Resolve `<pkgDir>` and write the bundle. Follow the procedure in references/widget-bundle-layout.md (## Resolving <pkgDir>). A widget bundle is a three-file set — all three files must be written in the same step; a bundle with fewer than three files is incomplete and will not deploy.

   <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json               # widget envelope — UEM tree (primary artifact)
   <pkgDir>/uiWidgets/<widgetName>/schema.json                     # attribute contract for the envelope
   <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml  # UiWidgetBundle registration

Each file has a distinct role:

• <widgetName>.json — the widget envelope with the tile/widget UEM tree. This is the primary artifact; schema.json is its companion contract, not a substitute.
• schema.json — the JSON Schema for the attributes referenced by {!$attrs.X} bindings in the envelope.
• <widgetName>.uiwidget-meta.xml — the UiWidgetBundle element that registers the bundle for source tracking and deployment.

Write all three before proceeding to self-validation.

1. Self-validate. Before reporting, run the checks and report each result individually (pass or fail (<reason>)). Do not summarize as a single "all passed" line — list every check so a reviewer can spot a silent skip.

Run every check in references/widget-bundle-validation.md.

1. Report labels. If the widget uses $Label, end the response with the label report described in references/widget-labels.md.

Rules / Constraints

Gotchas

Known failure modes and fixes (partial schemas, unresolved bindings, wrong output path, if truthiness, dead buttons, action choice): see references/widget-gotchas.md.

Reference File Index