platform-widget-generate

Generating a Widget Bundle Author a complete WidgetBundle: a UEM tree ( ), a JSON Schema describing the widget's input contract, and the 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 files inside a Custom Lightning Type bundle — those belong to . Inputs - (required) — identifier; becomes the directory name under . - A shape — what data the widget renders. The widget cannot be generated without it. The shape arrives one of two ways, in priority order:…

), 'match', 'no-match')}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"REGEX airline ^[A-Za-z ]+$: {!IF(REGEX($attrs.airline, '^[A-Za-z ]+

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

), 'match', 'no-match')}\" } }\n ]\n },\n\n { \"definition\": \"tile/spacer\", \"attributes\": { \"size\": \"sm\" } },\n\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"xs\" },\n \"children\": [\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"9. Locale format functions\", \"variant\": \"h3\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"FORMATNUMBER: {!FORMATNUMBER($attrs.price)} | precision 0: {!FORMATNUMBER($attrs.price, 0)}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"FORMATCURRENCY: {!FORMATCURRENCY($attrs.price)}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"FORMATPERCENT: {!FORMATPERCENT($attrs.winProbability)} | precision 1: {!FORMATPERCENT($attrs.winProbability, 1)}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"FORMATDATE: {!FORMATDATE($attrs.departureDate)} | long: {!FORMATDATE($attrs.departureDate, 'long')}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"FORMATDATETIME: {!FORMATDATETIME($attrs.departureDateTime)} | medium: {!FORMATDATETIME($attrs.departureDateTime, 'medium')}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"FORMATTIME: {!FORMATTIME($attrs.departureDateTime)} | long: {!FORMATTIME($attrs.departureDateTime, 'long')}\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"{!'Fare with tax: ' & FORMATCURRENCY($attrs.price * (1 + $attrs.taxRate))}\", \"variant\": \"h4\" } }\n ]\n },\n\n { \"definition\": \"tile/spacer\", \"attributes\": { \"size\": \"sm\" } },\n\n {\n \"definition\": \"tile/column\",\n \"meta\": { \"if\": \"{!AND($attrs.isPriority, $attrs.price > 500)}\" },\n \"children\": [\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"gap\": \"sm\", \"align\": \"center\" },\n \"children\": [\n { \"definition\": \"tile/icon\", \"attributes\": { \"name\": \"lightning\", \"color\": \"warning\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"10. Formula-driven meta.if: priority fare over $500 — expedited handling\" } }\n ]\n }\n ]\n },\n\n { \"definition\": \"tile/spacer\", \"attributes\": { \"size\": \"sm\" } },\n\n {\n \"definition\": \"tile/column\",\n \"meta\": { \"forEach\": \"{!$attrs.flights}\", \"forItem\": \"$flight\" },\n \"attributes\": { \"gap\": \"xs\" },\n \"children\": [\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"11. forEach + per-row formula\", \"variant\": \"h3\" } },\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"justify\": \"between\", \"align\": \"center\" },\n \"children\": [\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"xs\" },\n \"children\": [\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"{!$flight.airline} — {!$flight.flightId}\", \"variant\": \"h4\" } },\n { \"definition\": \"tile/text\", \"attributes\": { \"text\": \"Total with tax: ${!$flight.price * (1 + $flight.taxRate)}\", \"color\": \"muted\" } }\n ]\n },\n {\n \"definition\": \"tile/badge\",\n \"meta\": { \"if\": \"{!$flight.price > 1000}\" },\n \"attributes\": { \"label\": \"PREMIUM\", \"variant\": \"primary\" }\n }\n ]\n }\n ]\n }\n\n ]\n }\n ]\n }\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":13844,"content_sha256":"60ae10ff9a77c539e80554f107952954c3e512751c6f57eca43d271940126a29"},{"filename":"examples/list-with-foreach.json","content":"{\n \"type\": \"lightning__agentforceWidget\",\n \"contentBody\": {\n \"widgetBody\": {\n \"definition\": \"tile/widget\",\n \"children\": [\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"md\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.title}\", \"variant\": \"h1\" }\n },\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"sm\" },\n \"meta\": { \"forEach\": \"{!$attrs.products}\", \"forItem\": \"$product\" },\n \"children\": [\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"gap\": \"md\", \"justify\": \"between\", \"align\": \"center\" },\n \"children\": [\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"xs\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$product.name}\", \"variant\": \"h3\" }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$product.category}\", \"variant\": \"caption\", \"color\": \"muted\" }\n }\n ]\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$product.price}\", \"variant\": \"h4\", \"color\": \"primary\" }\n }\n ]\n },\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"gap\": \"sm\", \"align\": \"center\" },\n \"meta\": { \"forEach\": \"{!$product.features}\", \"forItem\": \"$feature\" },\n \"children\": [\n {\n \"definition\": \"tile/icon\",\n \"attributes\": { \"name\": \"{!$feature.icon}\", \"size\": \"sm\", \"color\": \"success\" }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$feature.label}\", \"variant\": \"caption\", \"color\": \"muted\" }\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":2408,"content_sha256":"325e606f8bec0d42bd84ab216a9ad93e6dff2137b344881d74680b4bc18a17fb"},{"filename":"examples/localized-labels.json","content":"{\n \"type\": \"lightning__agentforceWidget\",\n \"contentBody\": {\n \"widgetBody\": {\n \"definition\": \"tile/widget\",\n \"children\": [\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"md\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$Label.c.OrderStatus_Heading}\", \"variant\": \"h1\" }\n },\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"gap\": \"sm\", \"align\": \"center\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$Label.c.OrderStatus_OrderNumberCaption}\", \"variant\": \"caption\" }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.orderNumber}\" }\n }\n ]\n },\n {\n \"definition\": \"tile/badge\",\n \"attributes\": {\n \"label\": \"{!IF($attrs.isShipped, $Label.c.OrderStatus_ShippedStatus, $Label.c.OrderStatus_ProcessingStatus)}\",\n \"variant\": \"{!IF($attrs.isShipped, 'success', 'info')}\"\n }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$Label.c.OrderStatus_ItemsPrefix & ' ' & TEXT($attrs.itemCount)}\" }\n },\n {\n \"definition\": \"tile/button\",\n \"attributes\": {\n \"label\": \"{!$Label.c.OrderStatus_TrackButton}\",\n \"variant\": \"primary\",\n \"actions\": {\n \"click\": [\n { \"definition\": \"action/openLink\", \"attributes\": { \"url\": \"{!$attrs.trackingUrl}\" } }\n ]\n }\n }\n }\n ]\n }\n ]\n }\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":1889,"content_sha256":"9fdc64c2fbc6e44f286e0a505706b1506cb7db1b6698d9f6dfa4cb41e5cd70de"},{"filename":"examples/single-object.json","content":"{\n \"type\": \"lightning__agentforceWidget\",\n \"contentBody\": {\n \"widgetBody\": {\n \"definition\": \"tile/widget\",\n \"children\": [\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"md\" },\n \"children\": [\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"md\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.title}\", \"variant\": \"h2\" }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.subtitle}\", \"variant\": \"caption\", \"color\": \"muted\" }\n },\n {\n \"definition\": \"tile/column\",\n \"attributes\": { \"gap\": \"sm\" },\n \"children\": [\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"gap\": \"sm\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.field1Label}\", \"variant\": \"body\", \"weight\": \"semibold\" }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.field1Value}\", \"variant\": \"body\" }\n }\n ]\n },\n {\n \"definition\": \"tile/row\",\n \"attributes\": { \"gap\": \"sm\" },\n \"children\": [\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.field2Label}\", \"variant\": \"body\", \"weight\": \"semibold\" }\n },\n {\n \"definition\": \"tile/text\",\n \"attributes\": { \"text\": \"{!$attrs.field2Value}\", \"variant\": \"body\" }\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":2242,"content_sha256":"ed3b88710c877d88c8d251e61f68240077a2e149ddb5718fb7c288afb15872d1"},{"filename":"references/schema-from-lightning-type.md","content":"# Deriving Widget schema.json From a Lightning Type\n\nWhen the orchestrator passes a `lightningTypeSchema` (with `path` and `apexClassFqn`), the widget bundle's `schema.json` is derived from the Apex class the Lightning Type references — not invented. The Lightning Type root points at the **outer Apex class** (`@apexClassType/\u003cnamespace>__\u003cClassName>`); that outer class's `@AuraEnabled` fields define the payload shape. Inner classes appear either as a **singular field** (e.g. `InnerClass field` on the outer class) or as a **list-element type** (e.g. `List\u003cInnerClass>` on the outer class). In either case, the widget schema references the nested type by its own inner-class FQN (`@apexClassType/\u003cnamespace>__\u003cOuterClass>$\u003cInnerClass>`) — see step 4 below. This file documents the derivation rule.\n\n> **Scope:** This guide covers Apex-backed Lightning Types only. The orchestrator (`platform-lightning-type-widget-coordinate`) only routes Apex-backed types into this skill. Object/JSON-based Lightning Types (Lightning Type root `lightning:type: \"lightning__objectType\"` with primitive `properties`) are out of scope here.\n\n---\n\n## Guidance\n\n- The widget aligns to the Lightning Type's shape — it grounds on the `@AuraEnabled` fields of the Apex class the type references.\n- The widget MUST NOT introduce properties the Apex class does not expose.\n- **Default to including every `@AuraEnabled` field.** Omission is the exception, not the rule. Before dropping any field, confirm with the user — print the field, its Apex type, and the omission rationale (e.g. \"audit timestamp, not user-facing\"), and ASK before continuing. Silent omission is a hard violation; the orchestrator's P1.1 gate flags it.\n- Fields that are typically safe to propose for omission *with user confirmation*: audit timestamps (`createdDate`, `lastModifiedDate`), system IDs that duplicate a primary key, and internal flags. **Domain-meaningful fields — including `List\u003cInnerClass>` collections — are NEVER omitted silently.**\n\n---\n\n## Deriving from an Apex-backed Lightning Type\n\nThe Lightning Type root is minimal and points at the **outer Apex class**:\n\n```json\n{\n \"title\": \"\u003cTypeName>\",\n \"lightning:type\": \"@apexClassType/\u003cnamespace>__\u003cClassName>\"\n}\n```\n\nThe widget cannot mirror this directly — the widget root is a plain `type: \"object\"` whose `properties.attributes` wrapper carries `lightning:type: \"lightning__objectType\"` and the actual field map. Derive the widget shape from the Apex class's `@AuraEnabled` fields:\n\n1. Read the Apex class file (path provided by the orchestrator's Phase 4 output, or located via `\u003cpkgDir>/classes/\u003cClassName>.cls`). The `apexClassFqn` from the orchestrator names the outer class.\n2. **Enumerate every `@AuraEnabled` field on the outer class AND every field on each inner class referenced by a `List\u003cInner>` field or a singular inner-class field.** Default disposition is **include**. If you propose to drop any field, ASK the user first and record the rationale in the build plan's `Properties omitted:` section. Do not silently drop.\n3. For each retained field, map the Apex type to the matching `lightning:type`:\n\n | Apex type | `lightning:type` (in widget schema) |\n |---|---|\n | `String`, `Id` | `lightning__textType` |\n | `Decimal`, `Double`, `Integer`, `Long` | `lightning__numberType` |\n | `Boolean` | `lightning__booleanType` |\n | `Date`, `Datetime` | `lightning__dateTimeType` |\n | `List\u003cPrimitive>` (e.g. `List\u003cString>`) | `lightning__listType`, with `items.lightning:type` set to the matching primitive `lightning:type` from this table (e.g. `items.lightning:type: \"lightning__textType\"` for `List\u003cString>`). |\n | `List\u003cInnerClass>` | `lightning__listType`, with `items.lightning:type` set to the inner Apex class reference (see step 4). The widget body MUST also iterate this list with `forEach`/`forItem` and bind every `@AuraEnabled` field on `InnerClass` via `{!$item.\u003cinnerField>}`. See `references/widget-meta-directives.md`. |\n | `InnerClass` (singular field) | `lightning:type` set directly to the inner Apex class reference (see step 4). Bind its fields via `{!$attrs.\u003couterField>.\u003cinnerField>}`. |\n\n4. Build the widget `schema.json`. **Every `@AuraEnabled` field on the outer class** that survived step 2 MUST appear as an entry under `properties.attributes.properties`.\n\n For any field whose type is an inner Apex class — whether a singular field or a `List\u003cInnerClass>` — the property (or, for a list, its `items`) MUST reference the inner Apex class type directly, using the same `@apexClassType/\u003cnamespace>__\u003cOuterClass>$\u003cInnerClass>` form as the Lightning Type root, with `\u003cInnerClass>` naming the nested class as declared inside the outer class. Do not redeclare the inner class's fields inline:\n\n ```json\n \"\u003clistFieldName>\": {\n \"title\": \"\u003cList Field Label>\",\n \"description\": \"\u003cshort description>\",\n \"lightning:type\": \"lightning__listType\",\n \"items\": {\n \"lightning:type\": \"@apexClassType/\u003cnamespace>__\u003cOuterClass>$\u003cInnerClass>\"\n }\n },\n \"\u003csingularInnerFieldName>\": {\n \"title\": \"\u003cField Label>\",\n \"description\": \"\u003cshort description>\",\n \"lightning:type\": \"@apexClassType/\u003cnamespace>__\u003cOuterClass>$\u003cInnerClass>\"\n }\n ```\n\n This is the only case where a widget schema property carries an `@apexClassType/...` reference instead of a primitive `lightning:type` — it lets the runtime resolve the inner class's own `@AuraEnabled` fields without the widget schema duplicating them. For a list, inner-class fields are reached in the widget body via the `forEach`/`forItem` loop variable (`{!$item.\u003cinnerField>}`); for a singular field, via `{!$attrs.\u003couterField>.\u003cinnerField>}` — neither case gets a separate nested `properties` entry in the schema.\n\n ```json\n {\n \"title\": \"\u003cWidgetDisplayName>\",\n \"description\": \"\u003cone line about what the widget renders>\",\n \"type\": \"object\",\n \"properties\": {\n \"attributes\": {\n \"lightning:type\": \"lightning__objectType\",\n \"properties\": {\n \"\u003ctextFieldName>\": { \"title\": \"\u003cText Field Label>\", \"lightning:type\": \"lightning__textType\" },\n \"\u003cnumberFieldName>\": { \"title\": \"\u003cNumber Field Label>\", \"lightning:type\": \"lightning__numberType\" },\n \"\u003cdateTimeFieldName>\": { \"title\": \"\u003cDate/Time Field Label>\", \"lightning:type\": \"lightning__dateTimeType\" },\n \"\u003clistFieldName>\": { \"title\": \"\u003cList Field Label>\", \"lightning:type\": \"lightning__listType\", \"items\": { \"lightning:type\": \"\u003cprimitive lightning:type, or an inner-class @apexClassType/... reference>\" } }\n }\n }\n }\n }\n ```\n\n---\n\n## Reachability check\n\nBefore authoring the widget body, confirm every property you plan to bind via `{!$attrs.X}` exists in the derived widget `schema.json`. The orchestrator's P0.4 gate enforces this; the leaf skill must self-check first to avoid round-trips.\n\n---\n\n## Out of scope\n\n- Renaming Apex class fields for display. The widget schema must use the same names as the Apex class. Display labels are carried in `title` only.\n- Synthesizing properties not present on the resolved payload class. This includes computed/derived fields and any field the Apex class does not currently expose. **`platform-widget-generate` MUST NOT edit `.cls` files.** If the widget body needs a field that is missing (for example, a `lightning__booleanType` to drive `meta.if`), STOP and surface the gap to the orchestrator — name the missing field, its expected type, and why the widget needs it. The orchestrator decides whether to amend the Apex class (via `platform-apex-generate`) or revise the widget plan.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7664,"content_sha256":"47c71c8cc8c368c361b8b06a597f6737241743f8eaeea12ddfe78e892f08ec83"},{"filename":"references/widget-actions.md","content":"# Widget Actions\n\nComplete `tile/button` examples for the two supported action definitions. The action table and the action-less-button rule live in SKILL.md *Actions*.\n\n---\n\n## `action/sendMessage` and `action/openLink`\n\n```json\n{\n \"definition\": \"tile/button\",\n \"attributes\": {\n \"label\": \"Button Label\",\n \"variant\": \"primary\",\n \"actions\": { \"click\": [ { \"definition\": \"action/sendMessage\", \"attributes\": { \"content\": \"content\" } } ] }\n }\n}\n```\n\n```json\n{\n \"definition\": \"tile/button\",\n \"attributes\": {\n \"label\": \"Button Label\",\n \"variant\": \"primary\",\n \"actions\": { \"click\": [ { \"definition\": \"action/openLink\", \"attributes\": { \"url\": \"https://www.example.com\" } } ] }\n }\n}\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":711,"content_sha256":"d8eb04fe061e8d83e1a388435005124014ef3b0e6a1372de8c4378f4d202fa1e"},{"filename":"references/widget-bundle-layout.md","content":"# WidgetBundle Layout\n\nThe widget skill writes three files into one directory under the project's package directory.\n\n---\n\n## Folder layout\n\n```text\n\u003cpkgDir>/uiWidgets/\u003cwidgetName>/\n \u003cwidgetName>.json # widget envelope + UEM body\n schema.json # JSON Schema\n \u003cwidgetName>.uiwidget-meta.xml # UiWidgetBundle registration\n```\n\n`\u003cwidgetName>` is `camelCase` and matches the directory name and both `\u003cwidgetName>.json` / `\u003cwidgetName>.uiwidget-meta.xml` filenames exactly.\n\n---\n\n## Resolving `\u003cpkgDir>`\n\n`\u003cpkgDir>` resolves to `\u003cpackageDirectories[].path>/main/default` — the SFDX source-format default, where `\u003cpackageDirectories[].path>` is the `default: true` entry in `sfdx-project.json` (or the first entry if none is marked default).\n\n---\n\n## `\u003cwidgetName>.json` — Widget envelope + UEM body\n\nThe envelope has exactly two top-level keys — `type` and `contentBody`. The UEM tree lives at `contentBody.widgetBody`. Display metadata (label / description) lives in `\u003cwidgetName>.uiwidget-meta.xml`, not in the envelope.\n\n```json\n{\n \"type\": \"lightning__agentforceWidget\",\n \"contentBody\": {\n \"widgetBody\": {\n \"definition\": \"tile/widget\",\n \"children\": [\n /* every block — root and non-root — carries \"definition\", optional \"attributes\", optional \"meta\", optional \"children\". No \"type\" key on any node. */\n ]\n }\n }\n}\n```\n\nEnvelope keys:\n\n- `type` — always `\"lightning__agentforceWidget\"`.\n- `contentBody.widgetBody` — the root UEM node; this is `tile/widget`. It carries `definition` and `children` only — no `type` key on the root, no `type` key on any child.\n\nTree composition (everything inside `widgetBody.children`) is owned by `SKILL.md` *Composition*. No node — root or non-root — carries a `type` key.\n\n---\n\n## `schema.json` — Input contract\n\nJSON Schema describing what data the widget accepts at runtime. Fields are wrapped one level deep under `properties.attributes`.\n\n**Required root keys:**\n\n- `title` (string) — display name\n- `type` (string) — must equal `\"object\"`\n- `properties.attributes` (object) — must carry `lightning:type: \"lightning__objectType\"` and a nested `properties` map whose leaves each carry `lightning:type`\n\n**Optional root keys:**\n\n- `description` (string)\n\n**Each leaf under `properties.attributes.properties` MUST have `lightning:type`.** Optional per-leaf: `title`, `description`. **A `lightning__listType` leaf MUST also carry `items.lightning:type`** — set to the matching primitive `lightning:type` for a list of primitives, or to an `@apexClassType/...` reference for a list of Apex objects (see `references/schema-from-lightning-type.md`). **For a list of plain objects with no Apex-backed type**, `items.lightning:type` is `lightning__objectType` and `items` MUST also carry a nested `properties` map inlining every field the list items expose (same shape as the outer `attributes.properties` map).\n\nExample:\n\n```json\n{\n \"title\": \"Order Summary Widget\",\n \"description\": \"Displays an order's id, customer, total, and tags.\",\n \"type\": \"object\",\n \"properties\": {\n \"attributes\": {\n \"lightning:type\": \"lightning__objectType\",\n \"properties\": {\n \"orderId\": { \"title\": \"Order ID\", \"description\": \"Stable identifier shown in the header.\", \"lightning:type\": \"lightning__textType\" },\n \"customer\": { \"title\": \"Customer\", \"description\": \"Display name of the customer on the order.\", \"lightning:type\": \"lightning__textType\" },\n \"total\": { \"title\": \"Total\", \"description\": \"Order total in the order's currency.\", \"lightning:type\": \"lightning__numberType\" },\n \"tags\": { \"title\": \"Tags\", \"description\": \"Labels attached to the order.\", \"lightning:type\": \"lightning__listType\", \"items\": { \"lightning:type\": \"lightning__textType\" } }\n }\n }\n }\n}\n```\n\n`{!$attrs.X}` in the body resolves to `properties.attributes.properties.X` in the schema.\n\n---\n\n## `\u003cwidgetName>.uiwidget-meta.xml` — Registration\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\u003cUiWidgetBundle xmlns=\"http://soap.sforce.com/2006/04/metadata\">\n \u003cmasterLabel>\u003cHuman display label>\u003c/masterLabel>\n \u003cdescription>\u003cOne-line description of what the widget renders>\u003c/description>\n \u003cwidgetType>JSON\u003c/widgetType>\n\u003c/UiWidgetBundle>\n```\n\nElements:\n\n- `\u003cmasterLabel>` — required. Human-readable label shown in the runtime UI. Prefer title-case (e.g. `Account Summary Card`) — not the `camelCase` `\u003cwidgetName>`.\n- `\u003cdescription>` — required. One-line description of what the widget renders. Populates the display metadata previously carried in the envelope.\n- `\u003cwidgetType>` — required. Only the `JSON` variant is supported. The `FUNCTION` variant is out of scope.\n\n---\n\n## Validation reminders\n\n- Every `{!$attrs.X}` in `\u003cwidgetName>.json` MUST resolve to a property under `schema.json` `properties.attributes.properties` (or to a `forItem` loop variable defined upstream).\n- `\u003cwidgetName>.uiwidget-meta.xml` MUST parse as well-formed XML, have root element `\u003cUiWidgetBundle>`, and carry non-empty `\u003cmasterLabel>`, `\u003cdescription>`, and `\u003cwidgetType>JSON\u003c/widgetType>` elements.\n- The three files MUST be co-located in the same `\u003cwidgetName>/` directory under `uiWidgets/`.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5276,"content_sha256":"afdb5eb208464442106132838b8787f57f9baf960341616ad11f515c033df9fd"},{"filename":"references/widget-bundle-validation.md","content":"# Widget Bundle Validation Checks\n\nReport each check individually as `pass` or `fail (\u003creason>)`.\n\n- **`schema-parses`** — `\u003cpkgDir>/uiWidgets/\u003cwidgetName>/schema.json` parses as JSON.\n- **`schema-root-keys`** — root has `title` (string), `type: \"object\"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: \"lightning__objectType\"` and a nested `properties` map. No `unevaluatedProperties: false`.\n- **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/\u003cnamespace>__\u003cOuterClass>$\u003cInnerClass>`); the nested shape is not redeclared. `List\u003cInnerClass>` fields carry `lightning:type: \"lightning__listType\"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/\u003cnamespace>__\u003cOuterClass>$\u003cInnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: \"lightning__objectType\"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.\n- **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.\u003couterField>.\u003cinnerField>}` for nested objects) in `\u003cwidgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream. This applies to `$attrs`/`$item` references **inside formula expressions** too.\n- **`formulas-supported`** — every function name used inside a `{!...}` expression appears in the *Supported functions* list in `references/widget-formulas.md`.\n- **`body-envelope`** — `\u003cwidgetName>.json` root has `type: \"lightning__agentforceWidget\"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.\n- **`metaxml-wellformed`** — `\u003cwidgetName>.uiwidget-meta.xml` parses as well-formed XML.\n- **`metaxml-elements`** — `\u003cwidgetName>.uiwidget-meta.xml` has root `\u003cUiWidgetBundle>` and contains `\u003cmasterLabel>` (non-empty), `\u003cdescription>` (non-empty), and `\u003cwidgetType>JSON\u003c/widgetType>`.\n- **`files-present`** — all three files exist at the resolved `\u003cpkgDir>/uiWidgets/\u003cwidgetName>/` path.\n- **`button-actions-present`** — every `tile/button` in `\u003cwidgetName>.json` has an `actions.click` action node whose `definition` is `action/openLink` or `action/sendMessage`.\n- **`labels-valid`** — if the user did not ask for localization, `\u003cwidgetName>.json` contains no `$Label` (report `pass (not requested)`). Otherwise every `$Label` follows the rules in `references/widget-labels.md` and appears in the step 10 report.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2860,"content_sha256":"5ec671299ebefe0d8b9a63ee382d331acd8935399f041c78ef610a9b6622337c"},{"filename":"references/widget-formulas.md","content":"# Widget Formula Expressions\n\nA formula expression can appear anywhere a `{!...}` binding is written — `attributes` values, string interpolation, and `meta.if`. Read this file when a widget needs formulas.\n\n---\n\n## Syntax\n\nEvery formula expression is wrapped in `{!...}`, similar to a plain binding:\n\n```text\n{!FUNCTION($attrs.fieldName)}\n```\n\n- **Field references inside a formula** use the same `$attrs.\u003cpath>` convention as plain bindings.\n- Inside a `forEach`, use the loop variable instead of `$attrs` — e.g. `{!UPPER($item.property)}`. Formulas inside `forEach` evaluate once per iteration against the current loop item — not the whole array.\n- Functions and operators are case-sensitive UPPERCASE.\n- A formula can nest functions and mix functions with operators: `{!TEXT(ROUND($attrs.property, 2))}`, `{!LEFT($attrs.property, 5) & \"...\"}`.\n- A formula-bearing attribute is still bound to schema properties the same way as a plain binding — every `$attrs.X` / `$item.X` referenced inside a formula must resolve to a real schema property or loop variable, per the `bindings-resolve` self-validation check.\n- A Custom Label reference `$Label.c.\u003cLabelName>` can be used as a text value inside a formula. See `references/widget-labels.md`.\n\n---\n\n## Supported functions and operators, by category\n\nOnly the operators/functions listed here are confirmed supported — do not invent variants.\n\n### 1. Arithmetic operators\n\n| Operator | Meaning | Example |\n|---|---|-------------------------------------|\n| `+` | Add | `$attrs.operand1 + $attrs.operand2` |\n| `-` | Subtract | `$attrs.operand1 - $attrs.operand2` |\n| `*` | Multiply | `$attrs.operand1 * $attrs.operand2` |\n| `/` | Divide | `$attrs.operand1 / $attrs.operand2` |\n| `^` | Exponent | `$attrs.operand1 ^ $attrs.operand2` |\n\nUnary minus (`-$attrs.fieldName`) is also supported. Precedence, lowest to highest: `||`, `&&`, equality, relational, `+` `-` `&`, `^`, `*` `/`, unary. Note that `*` and `/` bind tighter than `^`, so `2 * 3 ^ 2` is `(2 * 3) ^ 2`; parenthesize to be explicit.\n\n### 2. Comparison operators\n\nReturn `true`/`false`; commonly used inside `IF()` or `meta.if`.\n\n| Operator | Meaning | Example |\n|---|---|----------------------------------------|\n| `=` | Equal | `$attrs.property = 'constantValue'` |\n| `\u003c>` | Not equal | `$attrs.property \u003c> 'constantValue'` |\n| `>` / `\u003c` | Greater / less than | `$attrs.property > 1000` |\n| `>=` / `\u003c=` | Greater-or-equal / less-or-equal | `$attrs.property1 >= $attrs.property2` |\n\n`==` and `!=` are accepted as aliases for `=` and `\u003c>`. Both operands must have the same type; text is never compared with a number.\n\n### 3. Logical functions\n\n| Function | Description | Example |\n|---|---|------------------------------------------------------------------------------------------------------|\n| `IF(cond, then, else)` | Conditional value; nests for multi-branch logic. `cond` must be a boolean (`IF($attrs.count > 0, …)`, not `IF($attrs.count, …)`) and both branches must have the same type | `IF($attrs.property > value, 'result1', 'result2')` |\n| `CASE(expr, val1, res1, val2, res2, ..., default)` | Multi-way match, cleaner than nested `IF` for 3+ branches | `CASE($attrs.property, 'value1', 'result1', 'value2', 'result2', 'value3', 'result3', 'defaultResult')` |\n| `AND(...)` | All conditions true | `AND($attrs.property1, $attrs.property2 > value)` |\n| `OR(...)` | Any condition true | `OR($attrs.property1, $attrs.property2 > value)` |\n| `NOT(val)` | Negate a boolean | `NOT($attrs.property)` |\n| `&&` / `\\|\\|` / `!` (operators) | Aliases for `AND` / `OR` / `NOT` | `$attrs.property1 && !$attrs.property2` |\n| `ISNULL(val)` | True if the value is null. Always false for text — use `ISBLANK` for strings | `IF(ISNULL($attrs.property), 'null', 'has-value')` |\n| `ISBLANK(val)` | True if null or empty string | `IF(ISBLANK($attrs.property), 'blank', 'has-value')` |\n\n### 4. Text functions\n\n| Function | Description | Example |\n|---|---|-----------------------------------------------------|\n| `UPPER(str[, locale])` / `LOWER(str[, locale])` | Case conversion, optionally for a locale such as `'tr'` | `UPPER($attrs.property)` |\n| `LEFT(str, n)` / `RIGHT(str, n)` | First/last `n` characters | `LEFT($attrs.property, 3)` |\n| `MID(str, start, len)` | Substring, **1-based** start index (first character is position 1, not 0) | `MID($attrs.property, 1, 3)` |\n| `SUBSTR(str, start[, len])` | Substring with a **1-based** start; a negative `start` counts from the end; without `len`, runs to the end | `SUBSTR($attrs.property, -4)` |\n| `LEN(val)` | Length of a string | `LEN($attrs.property)` |\n| `TRIM(str)` | Strip leading/trailing whitespace | `TRIM($attrs.property)` |\n| `REVERSE(str)` | Reverse a string | `REVERSE($attrs.property)` |\n| `SUBSTITUTE(str, old, new)` | Replace all occurrences | `SUBSTITUTE($attrs.property, 'string1', 'string2')` |\n| `FIND(search, str[, start])` | 1-based index of `search` in `str`, or `0` if absent; optional 1-based `start` position | `FIND('string', $attrs.property)` |\n| `LPAD(str, len, pad)` / `RPAD(str, len, pad)` | Pad to a fixed width | `LPAD($attrs.property, 12, '.')` |\n| `TEXT(val)` | Coerce a non-string value to text (commonly paired with `ROUND`) | `TEXT(ROUND($attrs.property, 2))` |\n| `VALUE(str)` | Parse text to a number (inverse of `TEXT`) | `VALUE($attrs.property)` |\n| `CONTAINS(str, sub)` | String contains substring — boolean, pair with `IF` | `CONTAINS($attrs.property, 'string')` |\n| `BEGINS(str, prefix)` | String starts with — boolean, pair with `IF` | `BEGINS($attrs.property, 'string')` |\n| `&` (operator) | Concatenate strings. Both sides must be text, so wrap numbers and dates in `TEXT()` — `'Total: ' & TEXT($attrs.total)` | `$attrs.property1 & ' — ' & $attrs.property2` |\n\n### 5. Math functions\n\n| Function | Description | Example |\n|---|---|------------------------------------------------|\n| `MOD(num, div)` | Remainder | `MOD($attrs.fieldName, 100)` |\n| `MAX(...)` / `MIN(...)` | Largest/smallest of the arguments | `MAX($attrs.fieldName, 2000)` |\n| `ROUND(num, digits)` | Round to `digits` decimal places | `ROUND($attrs.fieldName, 1)` |\n| `ABS(num)` | Absolute value | `ABS($attrs.fieldName)` |\n| `SQRT(num)` | Square root | `SQRT($attrs.fieldName)` |\n| `CEILING(num)` / `FLOOR(num)` | Round away from / toward zero on the *magnitude* | `CEILING($attrs.fieldName)`|\n| `MCEILING(num)` / `MFLOOR(num)` | Round toward +∞ / −∞ (\"mathematical\" ceiling/floor) — matters for negative numbers | `MCEILING($attrs.fieldName)`, `MFLOOR($attrs.fieldName)`|\n| `LOG(num)` / `EXP(num)` / `LN(num)` | Base-10 log, e^x, natural log | `LOG($attrs.fieldName)` |\n\n### 6. Date & time functions\n\n| Function | Description | Example |\n|---|---|-------------------------------------------------|\n| `DATEVALUE(str)` / `DATETIMEVALUE(str)` / `TIMEVALUE(str)` | Parse a date/datetime/time string into a value | `DATEVALUE($attrs.fieldName)` |\n| `DAY(date)` / `MONTH(date)` / `YEAR(date)` | Extract date components | `DAY(DATEVALUE($attrs.fieldName))` |\n| `WEEKDAY(date)` | Day of week, `1`=Sunday … `7`=Saturday | `WEEKDAY(DATEVALUE($attrs.fieldName))` |\n| `ADDMONTHS(date, n)` | Add `n` whole months to a date | `ADDMONTHS(DATEVALUE($attrs.fieldName), 3)` |\n| `TODAY()` / `NOW()` / `TIMENOW()` | Current date / datetime / time in UTC — no arguments | `TODAY()` |\n| `DATE(year, month, day)` | Construct a date literal | `DATE(2026, 12, 31)` |\n| `HOUR(dt)` / `MINUTE(dt)` / `SECOND(dt)` / `MILLISECOND(dt)` | Extract time components from a datetime | `HOUR(NOW())` |\n\nA raw date/datetime **string** attribute (e.g. an ISO string from `$attrs`) must be parsed with `DATEVALUE`/`DATETIMEVALUE`/`TIMEVALUE` before date-math or extractor functions can operate on it.\n\n### 7. Validation & encoding functions\n\n| Function | Description | Example |\n|---|---|----------------------------------------------|\n| `NULLVALUE(val, fallback)` | `fallback` only when `val` is null | `NULLVALUE($attrs.fieldName, 'fallback')` |\n| `BLANKVALUE(val, fallback)` | `fallback` when `val` is null or an empty string | `BLANKVALUE($attrs.fieldName, 'fallback')` |\n| `HTMLENCODE(str)` | Escape for literal HTML display — use on any text binding that must render literally rather than as markup | `HTMLENCODE($attrs.fieldName & ' \u003cb>tag\u003c/b>')` |\n| `JSENCODE(str)` | Escape for safe embedding in a JS-string context | `JSENCODE($attrs.fieldName & \"'quote\")` |\n\n### 8. Pattern matching functions\n\n| Function | Description | Example |\n|---|---|---|\n| `ISNUMBER(val)` | True if the value parses as a number | `ISNUMBER($attrs.fieldName)` |\n| `REGEX(str, pattern)` | True if `str` matches the regex `pattern` (standard regex string) | `REGEX($attrs.fieldName, '^[A-Z]{2} [0-9]+

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)` |\n\n### 9. Locale formatting functions\n\nFormat values for the viewer's locale. A null or blank input returns null. The optional last argument is a decimal count for the number functions and `'short'` (default), `'medium'` or `'long'` for the date and time functions.\n\n| Function | Description | Example |\n|---|---|---|\n| `FORMATNUMBER(num[, decimals])` | Locale-formatted number | `FORMATNUMBER($attrs.fieldName, 2)` |\n| `FORMATPERCENT(num[, decimals])` | Locale-formatted percent (`0.25` → `25%`) | `FORMATPERCENT($attrs.fieldName, 1)` |\n| `FORMATCURRENCY(num)` | Currency code followed by the amount, e.g. `USD 1,234.50` (no currency symbol) | `FORMATCURRENCY($attrs.fieldName)` |\n| `FORMATDATE(date[, style])` | Locale date | `FORMATDATE($attrs.fieldName, 'medium')` |\n| `FORMATDATETIME(dt[, style])` | Locale date and time | `FORMATDATETIME($attrs.fieldName, 'long')` |\n| `FORMATTIME(time[, style])` | Locale time | `FORMATTIME($attrs.fieldName)` |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":10903,"content_sha256":"48fed984c8df1bc4c18a1ac5d524a40a5853f8efac06b44ce291ef472924629a"},{"filename":"references/widget-gotchas.md","content":"# Widget Generation Gotchas\n\n| Issue | Resolution |\n|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `getUiComponentSchemas` returns a partial-failure entry | Pick a different block from `discoverUiComponents`; do not silently continue without a schema |\n| Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference |\n| Output written outside `\u003cpkgDir>/uiWidgets/\u003cwidgetName>/` | `\u003cpkgDir>` = `\u003cpackageDirectories[].path>/main/default` (see `references/widget-bundle-layout.md`). Dropping the `main/default/` segment is the common cause of widgets landing at `force-app/uiWidgets/...` instead of `force-app/main/default/uiWidgets/...` |\n| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean |\n| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see SKILL.md *Actions*) |\n| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2584,"content_sha256":"87eaa24270e4c73a2f9121236b2a70e930a33c6091456f8f8339e9f4b600b228"},{"filename":"references/widget-labels.md","content":"# Widget Localization with Custom Labels\n\nA widget shows translated text by referencing a Salesforce Custom Label instead of a hardcoded string.\n\n---\n\n## Syntax\n\n```text\n{!$Label.c.\u003cLabelName>}\n```\n\n- `c` is the org's default namespace. Always write it.\n- The label name is static. Never build it from data — `{!$Label.c.$attrs.key}` can't be validated when the widget is saved.\n- A `$Label` reference is not a `$attrs` binding and has no entry in `schema.json`.\n\n---\n\n## What to localize\n\nReplace every static, user-visible string in an allowed attribute, unless the user limited the request to specific strings.\n\n**Allowed**\n\n- Display text: `text`, `label`, `placeholder`, `title`, and other free-form string attributes (per `getUiComponentSchemas`)\n- Text results inside a formula, e.g. the branches of an `IF` or `CASE`\n\n**Not allowed**\n\n- `meta` directives (`if`, `forEach`, `forItem`)\n- Enum-valued attributes (`variant`, `size`, `color`, `gap`, `align`, `justify`) and icon names\n- Anything inside `actions` (`url`, `target`, `sendMessage` `content`)\n- Data bound with `$attrs` / `$item` — payload values are not translated\n- `schema.json` and the `-meta.xml`\n\n---\n\n## Label names\n\nReuse existing labels first. If the user names labels, or the project's CustomLabels file (`labels/CustomLabels.labels-meta.xml`) already has a label whose value matches the text, reference that label's `fullName` verbatim. Otherwise propose `\u003cWidgetName>_\u003cRole>`.\n\n---\n\n## Combining labels with data\n\n- Join a label and data with `&` (see `references/widget-formulas.md`):\n `\"text\": \"{!$Label.c.\u003cLabelName> & ' ' & TEXT($attrs.\u003cattrName>)}\"`\n- Choose between labels with `IF` / `CASE`:\n `\"label\": \"{!IF($attrs.\u003cbooleanAttr>, $Label.c.\u003cLabelWhenTrue>, $Label.c.\u003cLabelWhenFalse>)}\"`\n\n---\n\n## Creating labels\n\nThis skill gives no guidance on authoring label metadata, and the widget is complete without it. Create labels only when the user asks you to. When you do, add them to the project's existing CustomLabels file instead of overwriting it, and never redefine a label that already exists. The user is responsible for checking the labels and any translations in the org and for deploying them with or before the widget.\n\n---\n\n## Label report\n\nEnd the response with this report:\n\n```markdown\n### Custom Labels used by this widget\n\nThese labels must exist in the target org before you deploy — deploying a widget that references a missing label fails.\n\n| Label name | Value (default language) | Status | Used in |\n|---|---|---|---|\n| OrderStatus_Heading | Order status | Existing | `tile/text` `text` (widget heading) |\n| OrderStatus_TrackButton | Track order | To create | `tile/button` `label` |\n```\n\n- List each distinct label once, in the order it first appears in the widget.\n- **Label name** is the `fullName`, without the `c.` prefix.\n- **Value** is the literal text the label replaced.\n- **Status** is `Existing` (already in the project or named by the user), `Created` (you wrote it), or `To create` (the user must create it).\n- **Used in** names the block definition and attribute.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3090,"content_sha256":"dd5ecf8e66843022012ae59e3b0a326b79ef7be5a09db520cabf27462e6a1166"},{"filename":"references/widget-meta-directives.md","content":"# Widget Meta Directives\n\nThe `meta` object on a UEM block carries runtime directives for iteration (`forEach` / `forItem`) and conditional rendering (`if`). Read this file when a widget needs either.\n\n---\n\n## Iteration with forEach / forItem\n\n`forEach` iterates over an array; the block and ALL its children repeat for each item.\n\n### Rules\n\n- Place `forEach` on the `meta` object of the REPEATING block (e.g. a row or card).\n- The value is an expression referencing an array: `{!$attrs.\u003carrayAttr>}` (or `{!$\u003couterForItem>.\u003carrayField>}` for nested loops).\n- `forItem` is required alongside `forEach`. It names the variable bound to the current item and must start with ` platform-widget-generate — Skillopedia .\n- Inside the `forEach` block, reach the **current item** through the loop variable (`{!$item.X}`) — not by traversing the array path (`{!$attrs.items.X}`, which does not unfold to the current iteration). Top-level references for values that don't change across iterations (`{!$attrs.\u003cunrelatedField>}`) are still valid.\n- `forEach` blocks can be nested — inner loops use their own `forItem` name.\n\n### Example — top-level list\n\n```json\n{\n \"definition\": \"namespace/repeatingBlock\",\n \"meta\": { \"forEach\": \"{!$attrs.items}\", \"forItem\": \"$item\" },\n \"children\": [\n { \"definition\": \"namespace/childBlock1\", \"attributes\": { \"content\": \"{!$item.id}\" } },\n { \"definition\": \"namespace/childBlock2\", \"attributes\": { \"content\": \"{!$item.total}\" } }\n ]\n}\n```\n\n### Example — container holds repeating child\n\nWhen a container holds repeating items, `forEach` goes on the child — not on the container.\n\n```json\n{\n \"definition\": \"namespace/block\",\n \"children\": [\n {\n \"definition\": \"namespace/repeatingBlock\",\n \"meta\": { \"forEach\": \"{!$attrs.items}\", \"forItem\": \"$item\" },\n \"children\": [\n { \"definition\": \"namespace/childBlock\", \"attributes\": { \"content\": \"{!$item.name}\" } }\n ]\n }\n ]\n}\n```\n\n### Example — nested loops\n\nThe inner `forEach` references an array on the outer loop variable and uses a distinct `forItem` name.\n\n```json\n{\n \"definition\": \"namespace/repeatingBlock\",\n \"meta\": { \"forEach\": \"{!$attrs.orders}\", \"forItem\": \"$order\" },\n \"children\": [\n { \"definition\": \"namespace/childBlock\", \"attributes\": { \"content\": \"{!$order.id}\" } },\n {\n \"definition\": \"namespace/repeatingChildBlock\",\n \"meta\": { \"forEach\": \"{!$order.lineItems}\", \"forItem\": \"$line\" },\n \"children\": [\n { \"definition\": \"namespace/childBlock1\", \"attributes\": { \"content\": \"{!$line.name}\" } },\n { \"definition\": \"namespace/childBlock2\", \"attributes\": { \"content\": \"{!$line.count}\" } }\n ]\n }\n ]\n}\n```\n\n---\n\n## Conditional rendering with if\n\n`if` conditionally renders a block. When the expression is `false`, the block and all its children are excluded from the rendered output.\n\n### Rules\n\n- Place `if` on the `meta` object of the block.\n- `if` accepts either a bare `lightning__booleanType` property (or a loop variable holding one) OR a **formula expression** that evaluates to a boolean — comparisons (`{!$attrs.fieldName > 1000}`) and logical functions (`{!AND($attrs.fieldName1, $attrs.fieldName2 > 500)}`) are both valid. See `references/widget-formulas.md` for the full formula syntax and supported-function list.\n- Do not lean on the truthiness of a raw string (`\"\"` vs `\"value\"`) or number (`0` vs `1`) bound directly — that relies on implicit coercion and is unreliable. Bind to a real boolean property, or use an explicit formula comparison instead.\n- `if` may coexist with `forEach` on the same `meta`. `if` is evaluated first — if `false`, the loop is skipped entirely.\n\n### Example — top-level boolean\n\n```json\n{\n \"definition\": \"namespace/block\",\n \"meta\": { \"if\": \"{!$attrs.isVerified}\" },\n \"attributes\": { \"label\": \"Verified user\" }\n}\n```\n\n### Example — boolean nested inside a schema object\n\n```json\n{\n \"definition\": \"namespace/block\",\n \"meta\": { \"if\": \"{!$attrs.features.showBanner}\" },\n \"attributes\": { \"text\": \"Promo banner\" }\n}\n```\n\n### Example — boolean inside a forEach loop\n\n```json\n{\n \"definition\": \"namespace/repeatingBlock\",\n \"meta\": { \"forEach\": \"{!$attrs.tasks}\", \"forItem\": \"$task\" },\n \"children\": [\n { \"definition\": \"namespace/block1\", \"attributes\": { \"content\": \"{!$task.title}\" } },\n {\n \"definition\": \"namespace/block2\",\n \"meta\": { \"if\": \"{!$task.completed}\" },\n \"attributes\": { \"label\": \"Done\" }\n }\n ]\n}\n```\n\n---\n\n## Gotchas\n\n| Issue | Resolution |\n|---|---|\n| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean — see `references/widget-formulas.md` |\n| Nested loops share the same `forItem` name | Pick distinct names (e.g. `$item` outer, `$line` inner) — there is no validation error on collision |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4856,"content_sha256":"236e95e72a38c821b93926008626b800128734834e8d00b1ec0eb92c9763da84"},{"filename":"references/widget-styling.md","content":"# Widget Styling Best Practices\n\nWidgets express *intent*, not pixels. Each surface provides a default look and feel; brand/theme overrides apply automatically.\n\n- **Style semantically.** Use `variant`, `size`, and other enum-typed attributes (`primary`, `destructive`, `success`, `warning`). Do not pin literal colors or pixel values.\n- **One primary action per visible group.** At most one `tile/button` with `variant: primary`. Use `secondary` or `destructive` for additional actions (see the `tile/button` schema for the full variant enum).\n- **Every `tile/button` needs a `click` action.** See SKILL.md *Actions* — an action-less button renders disabled.\n- **One `h1` per widget.** Use `h2`/`h3` for sub-section headings, `body` for prose, `caption` for helper text.\n- **Use semantic state variants on state-bearing blocks** (`tile/badge`, `tile/callout`).\n- **Omit attributes that equal the schema default.** Check each property's `default` in the `getUiComponentSchemas` metadata (step 4). If the value you would write matches it — e.g. `gap`, `size`, or `action/openLink` `target: \"_blank\"` — leave the attribute out. Set an attribute only to change it.\n- **Don't pin `width`** unless a content constraint requires it.\n- **Use the Lucide icon set.** Pass the Lucide name (`\"check\"`, `\"alert-circle\"`); other icon libraries are not supported.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1356,"content_sha256":"0bd9e1568216fb825388d79f596cd31d5287c299547eea4130597546cef1a080"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Generating a Widget Bundle","type":"text"}]},{"type":"paragraph","content":[{"text":"Author a complete WidgetBundle: a UEM tree (","type":"text"},{"text":"tile/widget","type":"text","marks":[{"type":"code_inline"}]},{"text":"), a JSON Schema describing the widget's input contract, and the ","type":"text"},{"text":".uiwidget-meta.xml","type":"text","marks":[{"type":"code_inline"}]},{"text":" that registers the bundle.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use This Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"renderer.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" files inside a Custom Lightning Type bundle — those belong to ","type":"text"},{"text":"platform-custom-lightning-type-generate","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Inputs","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"widgetName","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (required) — ","type":"text"},{"text":"camelCase","type":"text","marks":[{"type":"code_inline"}]},{"text":" identifier; becomes the directory name under ","type":"text"},{"text":"uiWidgets/","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"shape","type":"text","marks":[{"type":"strong"}]},{"text":" — what data the widget renders. The widget cannot be generated without it. The shape arrives one of two ways, in priority order:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"lightningTypeSchema","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"{ path, apexClassFqn }","type":"text","marks":[{"type":"code_inline"}]},{"text":" for an existing Apex-backed Lightning Type. The FQN takes one of two forms: outer-class (","type":"text"},{"text":"\u003cnamespace>__\u003cClassName>","type":"text","marks":[{"type":"code_inline"}]},{"text":") where the outer class is the payload, or inner-class (","type":"text"},{"text":"\u003cnamespace>__\u003cClassName>$\u003cInnerClass>","type":"text","marks":[{"type":"code_inline"}]},{"text":") where the named inner class is the payload. Passed in by the ","type":"text"},{"text":"platform-lightning-type-widget-coordinate","type":"text","marks":[{"type":"code_inline"}]},{"text":" orchestrator. When present, derive per ","type":"text"},{"text":"references/schema-from-lightning-type.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extracted from the user's prompt","type":"text","marks":[{"type":"strong"}]},{"text":" — when no ","type":"text"},{"text":"lightningTypeSchema","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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 ","type":"text"},{"text":"{ name, type, required }","type":"text","marks":[{"type":"code_inline"}]},{"text":" either way.","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"If neither source yields a shape, STOP and ask the user before proceeding.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output","type":"text"}]},{"type":"paragraph","content":[{"text":"Three files in ","type":"text"},{"text":"\u003cpkgDir>/uiWidgets/\u003cwidgetName>/","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Content","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cwidgetName>.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Widget envelope — ","type":"text"},{"text":"{ \"type\": \"lightning__agentforceWidget\", \"contentBody\": { \"widgetBody\": { UEM tree rooted at tile/widget } } }","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"schema.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"JSON Schema — root has ","type":"text"},{"text":"type: \"object\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"properties.attributes","type":"text","marks":[{"type":"code_inline"}]},{"text":" wrapper carrying ","type":"text"},{"text":"lightning:type: \"lightning__objectType\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the field ","type":"text"},{"text":"properties","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cwidgetName>.uiwidget-meta.xml","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cUiWidgetBundle>","type":"text","marks":[{"type":"code_inline"}]},{"text":" element with ","type":"text"},{"text":"\u003cmasterLabel>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cdescription>","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"\u003cwidgetType>JSON\u003c/widgetType>","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/widget-bundle-layout.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the ","type":"text"},{"text":"\u003cpkgDir>","type":"text","marks":[{"type":"code_inline"}]},{"text":" resolution procedure and the exact ","type":"text"},{"text":"\u003cwidgetName>.uiwidget-meta.xml","type":"text","marks":[{"type":"code_inline"}]},{"text":" shape.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Composition","type":"text"}]},{"type":"paragraph","content":[{"text":"A widget body is a UEM tree of blocks nested under ","type":"text"},{"text":"contentBody.widgetBody","type":"text","marks":[{"type":"code_inline"}]},{"text":". The root node is ","type":"text"},{"text":"tile/widget","type":"text","marks":[{"type":"code_inline"}]},{"text":". Every node — root and non-root — has the same shape: no ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code_inline"}]},{"text":" key; just ","type":"text"},{"text":"definition","type":"text","marks":[{"type":"code_inline"}]},{"text":", optional ","type":"text"},{"text":"attributes","type":"text","marks":[{"type":"code_inline"}]},{"text":", optional ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code_inline"}]},{"text":", and optional ","type":"text"},{"text":"children","type":"text","marks":[{"type":"code_inline"}]},{"text":". Block shape:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"ts"},"content":[{"text":"interface Block {\n definition: string // {namespace}/{blockName} — root is \"tile/widget\"\n attributes?: Record\u003cstring, any>\n meta?: { // see references/widget-meta-directives.md\n forEach?: string\n forItem?: string\n if?: string\n }\n children?: Block[]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"The first child of ","type":"text"},{"text":"tile/widget.children","type":"text","marks":[{"type":"code_inline"}]},{"text":" SHOULD be a single ","type":"text"},{"text":"tile/column","type":"text","marks":[{"type":"code_inline"}]},{"text":". All widget content typically goes inside that first child for predictable vertical structure across surfaces.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Available Invocable Actions","type":"text"}]},{"type":"paragraph","content":[{"text":"Both are standard invocable actions on the target org.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Calling Convention","type":"text"}]},{"type":"paragraph","content":[{"text":"Fire each action with whichever mechanism is available: the H360 MCP ","type":"text"},{"text":"dispatch","type":"text","marks":[{"type":"code_inline"}]},{"text":" tool (a ","type":"text"},{"text":"POST","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the endpoint path with the request body) or ","type":"text"},{"text":"sf api request rest","type":"text","marks":[{"type":"code_inline"}]},{"text":". Use ","type":"text"},{"text":"v{version}","type":"text","marks":[{"type":"code_inline"}]},{"text":" = this skill's ","type":"text"},{"text":"minApiVersion","type":"text","marks":[{"type":"code_inline"}]},{"text":". Never use ","type":"text"},{"text":"curl","type":"text","marks":[{"type":"code_inline"}]},{"text":", and never extract the org's access token.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"sf api request rest '/services/data/v{version}/actions/standard/\u003cactionName>' --method POST --body '\u003crequest body>' --target-org \u003corg>","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Response Handling","type":"text"}]},{"type":"paragraph","content":[{"text":"Each response is an array with one envelope (","type":"text"},{"text":"dispatch","type":"text","marks":[{"type":"code_inline"}]},{"text":" nests it under ","type":"text"},{"text":"body","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Check three failure layers, in order:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layer","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Signal","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Transport / auth","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"dispatch","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"status_code","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not 200, or CLI exits non-zero","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Surface the error","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"[0].isSuccess","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"[0].errors","type":"text","marks":[{"type":"code_inline"}]},{"text":" is non-empty","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Surface ","type":"text"},{"text":"errors[].message","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Per-entry (","type":"text"},{"text":"getUiComponentSchemas","type":"text","marks":[{"type":"code_inline"}]},{"text":" only)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"any ","type":"text"},{"text":"componentSchemas[].success","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code_inline"}]},{"text":", even when ","type":"text"},{"text":"[0].isSuccess","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Treat that block as unavailable","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"On success, read ","type":"text"},{"text":"[0].outputValues","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"discoverUiComponents","type":"text"}]},{"type":"paragraph","content":[{"text":"Purpose:","type":"text","marks":[{"type":"strong"}]},{"text":" Discover the palette of blocks available for composition.","type":"text"}]},{"type":"paragraph","content":[{"text":"Endpoint:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"POST /services/data/v{version}/actions/standard/discoverUiComponents","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Request body:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"{\"inputs\":[{\"pageType\":\"FRAGMENT\"}]}","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Returns:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"outputValues.componentDefinitions[]","type":"text","marks":[{"type":"code_inline"}]},{"text":" — list of ","type":"text"},{"text":"{ definition, description, label }","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"getUiComponentSchemas","type":"text"}]},{"type":"paragraph","content":[{"text":"Purpose:","type":"text","marks":[{"type":"strong"}]},{"text":" Fetch schemas (property types, required vs optional, validation) for selected blocks.","type":"text"}]},{"type":"paragraph","content":[{"text":"Endpoint:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"POST /services/data/v{version}/actions/standard/getUiComponentSchemas","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Request body:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"{\"inputs\":[{\"pageType\":\"FRAGMENT\",\"componentDefinitions\":[\"namespace/definition\", ...]}]}","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Returns:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"outputValues.componentSchemas[]","type":"text","marks":[{"type":"code_inline"}]},{"text":" — list of ","type":"text"},{"text":"{ definition, success, schema }","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"schema","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a YAML string). Partial failures are supported.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Never pass ","type":"text"},{"text":"tile/widget","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"getUiComponentSchemas","type":"text","marks":[{"type":"code_inline"}]},{"text":" — it is a fixed wrapper, not a queryable component.","type":"text"}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Attribute Binding","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bind a block property to runtime data with ","type":"text"},{"text":"{!$attrs.\u003cattrName>}","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"\u003cattrName>","type":"text","marks":[{"type":"code_inline"}]},{"text":" MUST match a property name in ","type":"text"},{"text":"schema.json","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inside a ","type":"text"},{"text":"forEach","type":"text","marks":[{"type":"code_inline"}]},{"text":", reference the loop variable instead — e.g. ","type":"text"},{"text":"\"text\": \"{!$item.name}\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". See ","type":"text"},{"text":"references/widget-meta-directives.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A binding may be a ","type":"text"},{"text":"formula expression","type":"text","marks":[{"type":"strong"}]},{"text":" instead of a bare field reference. See ","type":"text"},{"text":"references/widget-formulas.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full supported-function list, syntax, and gotchas.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Localization:","type":"text","marks":[{"type":"strong"}]},{"text":" only when the user asks for localized or translated text (or names Custom Labels / ","type":"text"},{"text":"$Label","type":"text","marks":[{"type":"code_inline"}]},{"text":"), write static, user-visible strings as Custom Label references — ","type":"text"},{"text":"{!$Label.c.\u003cLabelName>}","type":"text","marks":[{"type":"code_inline"}]},{"text":". See ","type":"text"},{"text":"references/widget-labels.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Actions","type":"text"}]},{"type":"paragraph","content":[{"text":"tile/button","type":"text","marks":[{"type":"code_inline"}]},{"text":" supports an ","type":"text"},{"text":"actions","type":"text","marks":[{"type":"code_inline"}]},{"text":" attribute that dispatches an action node on an event. Two action definitions are supported:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Timing","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Required attributes","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Effect","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action/openLink","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"synchronous","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"url","type":"text","marks":[{"type":"code_inline"}]},{"text":" (string). Optional ","type":"text"},{"text":"target","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"_blank","type":"text","marks":[{"type":"code_inline"}]},{"text":"|","type":"text"},{"text":"_self","type":"text","marks":[{"type":"code_inline"}]},{"text":", default ","type":"text"},{"text":"_blank","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Opens a URL","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"action/sendMessage","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"asynchronous","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"content","type":"text","marks":[{"type":"code_inline"}]},{"text":" (string)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Posts a new user message back to the agent and earns a fresh turn","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/widget-actions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for complete ","type":"text"},{"text":"sendMessage","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"openLink","type":"text","marks":[{"type":"code_inline"}]},{"text":" button JSON.","type":"text"}]},{"type":"paragraph","content":[{"text":"A ","type":"text","marks":[{"type":"strong"}]},{"text":"tile/button","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" with no ","type":"text","marks":[{"type":"strong"}]},{"text":"actions","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" attribute renders disabled","type":"text","marks":[{"type":"strong"}]},{"text":" — a button exists to trigger an action, so always attach a ","type":"text"},{"text":"click","type":"text","marks":[{"type":"code_inline"}]},{"text":" action to a button meant to be interactive.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Layout Best Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"These conventions cover widget ","type":"text"},{"text":"structure","type":"text","marks":[{"type":"em"}]},{"text":" — how blocks are grouped and stacked.","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Primitive","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"tile/column","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Vertical stack of children","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Root wrapper, and any group of blocks that should stack","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"tile/row","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Horizontal stack of children","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Two or more blocks that belong on the same line","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"tile/spacer","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Whitespace between blocks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When extra space is needed between content groups","type":"text"}]}]}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Nesting:","type":"text","marks":[{"type":"strong"}]},{"text":" Prefer flat layouts. Only nest a ","type":"text"},{"text":"tile/column","type":"text","marks":[{"type":"code_inline"}]},{"text":" inside a ","type":"text"},{"text":"tile/row","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or vice versa) when the visual orientation actually changes for that subgroup.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Authoritative palette:","type":"text","marks":[{"type":"strong"}]},{"text":" the table above lists ","type":"text"},{"text":"typical","type":"text","marks":[{"type":"em"}]},{"text":" layout primitives. Always confirm a block exists by inspecting ","type":"text"},{"text":"discoverUiComponents","type":"text","marks":[{"type":"code_inline"}]},{"text":" output — do not assume a block name from this table without seeing it in the discovery response.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Styling Best Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"Style semantically (variants, not literal colors or pixels), one primary button per group, one ","type":"text"},{"text":"h1","type":"text","marks":[{"type":"code_inline"}]},{"text":" per widget, Lucide icons only. Read ","type":"text"},{"text":"references/widget-styling.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" before assigning variants, sizes, or icons.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve the widget spec","type":"text","marks":[{"type":"strong"}]},{"text":" — an ordered list of ","type":"text"},{"text":"{ name, type, required }","type":"text","marks":[{"type":"code_inline"}]},{"text":". Source depends on which input was provided (see ","type":"text"},{"text":"Inputs","type":"text","marks":[{"type":"em"}]},{"text":"):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"lightningTypeSchema","type":"text","marks":[{"type":"code_inline"}]},{"text":" was passed by the orchestrator → derive per ","type":"text"},{"text":"references/schema-from-lightning-type.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Otherwise → infer the list directly from the user prompt (pasted JSON payload, enumerated field list, or descriptive prose).","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discover blocks (REQUIRED — do NOT skip).","type":"text","marks":[{"type":"strong"}]},{"text":" Call the ","type":"text"},{"text":"discoverUiComponents","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocable action (see ","type":"text"},{"text":"Available Invocable Actions","type":"text","marks":[{"type":"em"}]},{"text":") and match widget-spec property types against the returned ","type":"text"},{"text":"label","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" values. ","type":"text"},{"text":"If ","type":"text","marks":[{"type":"strong"}]},{"text":"isSuccess","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is ","type":"text","marks":[{"type":"strong"}]},{"text":"false","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", ","type":"text","marks":[{"type":"strong"}]},{"text":"errors","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is non-empty, or ","type":"text","marks":[{"type":"strong"}]},{"text":"componentDefinitions","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is empty, STOP and surface the error verbatim — do not improvise block names from memory, prior runs, or training data.","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select blocks.","type":"text","marks":[{"type":"strong"}]},{"text":" Choose one block per widget-spec property, plus structural primitives from ","type":"text"},{"text":"Layout Best Practices","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Get block schemas (REQUIRED — do NOT skip).","type":"text","marks":[{"type":"strong"}]},{"text":" Call the ","type":"text"},{"text":"getUiComponentSchemas","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocable action for the selected blocks. Review property metadata, including each property's ","type":"text"},{"text":"default","type":"text","marks":[{"type":"code_inline"}]},{"text":" — omit any attribute whose value would equal it (see ","type":"text"},{"text":"references/widget-styling.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"). ","type":"text"},{"text":"If ","type":"text","marks":[{"type":"strong"}]},{"text":"isSuccess","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is ","type":"text","marks":[{"type":"strong"}]},{"text":"false","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", ","type":"text","marks":[{"type":"strong"}]},{"text":"componentSchemas","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is empty, or any entry has ","type":"text","marks":[{"type":"strong"}]},{"text":"success: false","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", 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.","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build the UEM tree (example reads REQUIRED — do NOT skip).","type":"text","marks":[{"type":"strong"}]},{"text":" First, identify which patterns match the widget spec and read each matching example file from this skill's own ","type":"text"},{"text":"examples/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory (","type":"text"},{"text":"\u003cskill-root>/examples/","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pattern in the spec","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Example to read","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Single object (no iteration)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cskill-root>/examples/single-object.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any list iteration (root-level array, nested list, or list embedded in a single-object widget)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cskill-root>/examples/list-with-foreach.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Conditional rendering (","type":"text"},{"text":"if","type":"text","marks":[{"type":"code_inline"}]},{"text":" bound to a boolean or formula)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cskill-root>/examples/conditional.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Computed values, text/number transforms, locale-formatted numbers/currency/dates, or ","type":"text"},{"text":"if","type":"text","marks":[{"type":"code_inline"}]},{"text":" driven by a formula (not a bare boolean field)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cskill-root>/examples/formulas.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The user asked for localized / translated text (Custom Labels)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cskill-root>/examples/localized-labels.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"A spec may match multiple patterns (e.g. a list of items where some items render conditionally reads both ","type":"text"},{"text":"list-with-foreach.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"conditional.json","type":"text","marks":[{"type":"code_inline"}]},{"text":"). ","type":"text"},{"text":"Read every matching example, and only those — do not skip the read because the pattern feels familiar.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Before writing any formula","type":"text","marks":[{"type":"strong"}]},{"text":", read ","type":"text"},{"text":"references/widget-formulas.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before writing any ","type":"text","marks":[{"type":"strong"}]},{"text":"$Label","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" reference","type":"text","marks":[{"type":"strong"}]},{"text":", read ","type":"text"},{"text":"references/widget-labels.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in full.","type":"text"}]},{"type":"paragraph","content":[{"text":"Then:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Map each widget-spec property to a block property; preserve spec order.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Decide root iteration:","type":"text","marks":[{"type":"strong"}]},{"text":" single object → properties directly under root ","type":"text"},{"text":"tile/column","type":"text","marks":[{"type":"code_inline"}]},{"text":". Collection → wrap repeating block in ","type":"text"},{"text":"forEach","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"forItem","type":"text","marks":[{"type":"code_inline"}]},{"text":". See ","type":"text"},{"text":"references/widget-meta-directives.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bind values with ","type":"text"},{"text":"{!$attrs.X}","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"{!$item.X}","type":"text","marks":[{"type":"code_inline"}]},{"text":" inside ","type":"text"},{"text":"forEach","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For conditional blocks, add ","type":"text"},{"text":"\"if\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" on ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code_inline"}]},{"text":" — either a bare ","type":"text"},{"text":"lightning__booleanType","type":"text","marks":[{"type":"code_inline"}]},{"text":" property, or a formula expression that evaluates to boolean. See ","type":"text"},{"text":"references/widget-formulas.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When the widget spec calls for a computed value","type":"text","marks":[{"type":"strong"}]},{"text":" (a total, a derived label, a formatted string) rather than a raw field, express it as a formula inside ","type":"text"},{"text":"{!...}","type":"text","marks":[{"type":"code_inline"}]},{"text":" per ","type":"text"},{"text":"references/widget-formulas.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — do not invent a new schema property to hold a value that can be computed from existing ones.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Author ","type":"text","marks":[{"type":"strong"}]},{"text":"schema.json","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" Build the JSON Schema from the widget spec. Fields live one level deep under an ","type":"text"},{"text":"attributes","type":"text","marks":[{"type":"code_inline"}]},{"text":" wrapper:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"title\": \"\u003cWidget Display Name>\",\n \"description\": \"\u003cone line about what the widget shows>\",\n \"type\": \"object\",\n \"properties\": {\n \"attributes\": {\n \"lightning:type\": \"lightning__objectType\",\n \"properties\": {\n \"\u003cpropertyName>\": {\n \"title\": \"\u003clabel>\",\n \"description\": \"\u003cshort description>\",\n \"lightning:type\": \"\u003clightning__textType | lightning__numberType | ...>\"\n }\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Required root keys:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"type: \"object\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"properties.attributes","type":"text","marks":[{"type":"code_inline"}]},{"text":" (with ","type":"text"},{"text":"lightning:type: \"lightning__objectType\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and a nested ","type":"text"},{"text":"properties","type":"text","marks":[{"type":"code_inline"}]},{"text":" map). See ","type":"text"},{"text":"references/schema-from-lightning-type.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for full primitive type guidance.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Author ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003cwidgetName>.uiwidget-meta.xml","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" See ","type":"text"},{"text":"references/widget-bundle-layout.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the exact shape.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003cpkgDir>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" and write the bundle.","type":"text","marks":[{"type":"strong"}]},{"text":" Follow the procedure in ","type":"text"},{"text":"references/widget-bundle-layout.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"## Resolving \u003cpkgDir>","type":"text","marks":[{"type":"code_inline"}]},{"text":"). A widget bundle is a ","type":"text"},{"text":"three-file set","type":"text","marks":[{"type":"strong"}]},{"text":" — all three files must be written in the same step; a bundle with fewer than three files is incomplete and will not deploy.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"\u003cpkgDir>/uiWidgets/\u003cwidgetName>/\u003cwidgetName>.json # widget envelope — UEM tree (primary artifact)\n\u003cpkgDir>/uiWidgets/\u003cwidgetName>/schema.json # attribute contract for the envelope\n\u003cpkgDir>/uiWidgets/\u003cwidgetName>/\u003cwidgetName>.uiwidget-meta.xml # UiWidgetBundle registration","type":"text"}]},{"type":"paragraph","content":[{"text":"Each file has a distinct role:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003cwidgetName>.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the widget envelope with the ","type":"text"},{"text":"tile/widget","type":"text","marks":[{"type":"code_inline"}]},{"text":" UEM tree. This is the primary artifact; ","type":"text"},{"text":"schema.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" is its companion contract, not a substitute.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"schema.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the JSON Schema for the attributes referenced by ","type":"text"},{"text":"{!$attrs.X}","type":"text","marks":[{"type":"code_inline"}]},{"text":" bindings in the envelope.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003cwidgetName>.uiwidget-meta.xml","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the ","type":"text"},{"text":"UiWidgetBundle","type":"text","marks":[{"type":"code_inline"}]},{"text":" element that registers the bundle for source tracking and deployment.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Write all three before proceeding to self-validation.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Self-validate.","type":"text","marks":[{"type":"strong"}]},{"text":" Before reporting, run the checks and report each result individually (","type":"text"},{"text":"pass","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"fail (\u003creason>)","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" summarize as a single \"all passed\" line — list every check so a reviewer can spot a silent skip. Run every check in ","type":"text"},{"text":"references/widget-bundle-validation.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report labels.","type":"text","marks":[{"type":"strong"}]},{"text":" If the widget uses ","type":"text"},{"text":"$Label","type":"text","marks":[{"type":"code_inline"}]},{"text":", end the response with the label report described in ","type":"text"},{"text":"references/widget-labels.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Rules / Constraints","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Constraint","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Rationale","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Block definitions follow ","type":"text"},{"text":"{namespace}/{blockName}","type":"text","marks":[{"type":"code_inline"}]},{"text":" and must match ","type":"text"},{"text":"discoverUiComponents","type":"text","marks":[{"type":"code_inline"}]},{"text":" output","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Runtime resolves blocks by exact definition string","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Never pass ","type":"text"},{"text":"tile/widget","type":"text","marks":[{"type":"code_inline"}]},{"text":" to ","type":"text"},{"text":"getUiComponentSchemas","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"It is a fixed wrapper, not a queryable component","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"examples/","type":"text","marks":[{"type":"code_inline"}]},{"text":" files only at the step that names them","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Upfront reads waste context and precede the discovery result that determines which files are needed","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Every ","type":"text"},{"text":"{!$attrs.X}","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the body resolves to a property in the widget ","type":"text"},{"text":"schema.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No invented fields","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Every ","type":"text"},{"text":"tile/button","type":"text","marks":[{"type":"code_inline"}]},{"text":" carries an ","type":"text"},{"text":"actions.click","type":"text","marks":[{"type":"code_inline"}]},{"text":" entry using ","type":"text"},{"text":"action/openLink","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"action/sendMessage","type":"text","marks":[{"type":"code_inline"}]},{"text":" only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"These are the only two supported tile action definitions; an action-less button renders disabled","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No ","type":"text"},{"text":"$(…)","type":"text","marks":[{"type":"code_inline"}]},{"text":", backticks, ","type":"text"},{"text":"\u003c(…)","type":"text","marks":[{"type":"code_inline"}]},{"text":", brace expansion ","type":"text"},{"text":"{a,b,c}","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"eval","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"exec","type":"text","marks":[{"type":"code_inline"}]},{"text":" in any Bash tool call","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Vibes' safe-shell filter forces manual approval on these patterns even in Bypass mode. Emit separate commands (","type":"text"},{"text":"mkdir -p a && mkdir -p b","type":"text","marks":[{"type":"code_inline"}]},{"text":") or print each value with its own command and reason about the output — do not capture into a shell variable","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Gotchas","type":"text"}]},{"type":"paragraph","content":[{"text":"Known failure modes and fixes (partial schemas, unresolved bindings, wrong output path, ","type":"text"},{"text":"if","type":"text","marks":[{"type":"code_inline"}]},{"text":" truthiness, dead buttons, action choice): see ","type":"text"},{"text":"references/widget-gotchas.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference File Index","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to read","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-meta-directives.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"forEach","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"forItem","type":"text","marks":[{"type":"code_inline"}]},{"text":" (iteration) and ","type":"text"},{"text":"if","type":"text","marks":[{"type":"code_inline"}]},{"text":" (conditional rendering), including nested loops","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/schema-from-lightning-type.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"lightningTypeSchema","type":"text","marks":[{"type":"code_inline"}]},{"text":" is provided; how to derive the widget ","type":"text"},{"text":"schema.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" from an Apex-backed Lightning Type","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-bundle-layout.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Folder layout, ","type":"text"},{"text":"-meta.xml","type":"text","marks":[{"type":"code_inline"}]},{"text":" shape, ","type":"text"},{"text":"\u003cpkgDir>","type":"text","marks":[{"type":"code_inline"}]},{"text":" resolution rules","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-bundle-validation.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Step 9 — the checks to run before reporting","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-formulas.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Supported formula functions and operators, including locale format functions (","type":"text"},{"text":"FORMATNUMBER","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"FORMATCURRENCY","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"FORMATDATE","type":"text","marks":[{"type":"code_inline"}]},{"text":", …)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-labels.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Localization — ","type":"text"},{"text":"$Label","type":"text","marks":[{"type":"code_inline"}]},{"text":" syntax, naming and reuse, allowed attributes, combining with data, creating labels, and the label report","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-actions.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Complete ","type":"text"},{"text":"tile/button","type":"text","marks":[{"type":"code_inline"}]},{"text":" JSON for ","type":"text"},{"text":"action/sendMessage","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"action/openLink","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-styling.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Variant, size, heading, and icon conventions","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/widget-gotchas.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Known failure modes and their fixes","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"examples/single-object.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Single-object pattern (root binding via ","type":"text"},{"text":"{!$attrs.X}","type":"text","marks":[{"type":"code_inline"}]},{"text":", no iteration)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"examples/list-with-foreach.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any list-iteration case — root-level collections, nested lists, and lists embedded inside a single-object widget (e.g. iterating a ","type":"text"},{"text":"List\u003cInnerClass>","type":"text","marks":[{"type":"code_inline"}]},{"text":" inside an outer Apex payload)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"examples/conditional.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Conditional pattern (","type":"text"},{"text":"if","type":"text","marks":[{"type":"code_inline"}]},{"text":" on ","type":"text"},{"text":"meta","type":"text","marks":[{"type":"code_inline"}]},{"text":", including ","type":"text"},{"text":"if","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"forEach","type":"text","marks":[{"type":"code_inline"}]},{"text":" together)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"examples/formulas.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Formula usage — text/arithmetic/date transforms, locale format functions, ","type":"text"},{"text":"IF","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"AND","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"NOT","type":"text","marks":[{"type":"code_inline"}]},{"text":" driving both a ","type":"text"},{"text":"tile/text","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"meta.if","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"examples/localized-labels.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Localization — ","type":"text"},{"text":"$Label","type":"text","marks":[{"type":"code_inline"}]},{"text":" in a heading, caption, badge (","type":"text"},{"text":"IF","type":"text","marks":[{"type":"code_inline"}]},{"text":" choosing between labels), button label, and a label joined with data","type":"text"}]}]}]}]}]},"metadata":{"date":"2026-11-02","name":"platform-widget-generate","author":"@skillopedia","source":{"stars":1139,"repo_name":"sf-skills","origin_url":"https://github.com/forcedotcom/sf-skills/blob/HEAD/skills/platform-widget-generate/SKILL.md","repo_owner":"forcedotcom","body_sha256":"d7263c02fe0ed3bf37411e779a9abeff3c284d1566615b942b4cecb75ceebbb7","cluster_key":"f7f9dc8c1fdb6b1209caa58ce6fc9075488ab60ca96dbd47a5f8c10babcde3d7","clean_bundle":{"format":"clean-skill-bundle-v1","source":"forcedotcom/sf-skills/skills/platform-widget-generate/SKILL.md","text_bytes":62286,"source_commit":"a8a18ce1e4ba12e69b4073eab98ce31bfbd8271e","skills_sh_rank":6085,"attachment_count":14,"text_attachments":14,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/platform-widget-generate/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"web-development","category_label":"Web"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"web-development","metadata":{"domains":["Platform","Agentforce"],"version":"1.5","cliTools":[{"tool":["sf"],"semver":">=2.0.0"}],"minApiVersion":"68.0","relatedSkills":["platform-apex-generate","platform-custom-lightning-type-generate","platform-lightning-type-widget-coordinate"]},"import_tag":"skills-sh-top20k-2026-11","description":"Use this skill to author a complete HXL WidgetBundle (UEM body + schema.json + -meta.xml). TRIGGER when: user asks for a widget, mosaic, fragment, card, or rich UI surface for any subject, domain, feature, or entity noun; the prompt names only an entity or data shape without invoking Lightning Types, CLTs, or Apex-backed types. DO NOT TRIGGER when: the prompt explicitly says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', or references '@apexClassType/...' (use platform-lightning-type-widget-coordinate); authoring a custom-LWC renderer for a Custom Lightning Type (use platform-custom-lightning-type-generate); or editing only an LWC component."}},"renderedAt":1793661503321}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.