forcedotcom/sf-skills / plugins/builder/salesforce-development/skills/platform-flexipage-generate
platform-flexipage-generate
VerifiedUse when users create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger on RecordPage, AppPage, HomePage, Lightning pages, adding components to a page, page customization (e.g. 'customize the record page'), or .flexipage-meta.xml files (regions, components, deployment errors). DO NOT TRIGGER for Visualforce pages, page layout assignments in the UI, UI Bundle/Experience Cloud site pages, or Aura/Lightning Web Component development without FlexiPage context.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.1 KB |
| references/cli_commands.md | markdown | 769 B |
| references/flexipage_fieldSection.md | markdown | 5.8 KB |
| references/flexipage_richText.md | markdown | 3.2 KB |
| references/identifiers_and_regions.md | markdown | 6.0 KB |
| references/mcp_action_examples.md | markdown | 3.8 KB |
| references/record_flexipage_dynamicHighlights.md | markdown | 4.7 KB |
| references/xml_rules.md | markdown | 13.7 KB |
| scripts/resolve-component-instructions.shexecutable | script | 1.2 KB |
| scripts/scan-lwc-components.shexecutable | script | 2.9 KB |
references/xml_rules.md
View on GitHub# Critical XML Rules & Deployment Errors
## Contents
0. [STOP — Read Before Writing ANY componentInstance](#stop--read-before-writing-any-componentinstance)
1. [Property Value Encoding](#1-property-value-encoding-most-common-error)
2. [Field References](#2-field-references)
3. [Region vs Facet Types](#3-region-vs-facet-types)
4. [itemInstances — ONE Child Per Wrapper](#4-iteminstances--one-child-per-wrapper-critical)
5. [Unique Identifiers and Region Names](#5-unique-identifiers-and-region-names-critical---prevents-duplicate-errors)
6. [Correct Element Names](#6-correct-element-names-critical--prevents-invalid-xml-errors)
7. [Common Deployment Errors](#common-deployment-errors)
---
## STOP — Read Before Writing ANY componentInstance
**The element name is `<componentInstanceProperties>`, NEVER `<properties>`.**
```xml
<!-- WRONG — WILL FAIL DEPLOYMENT -->
<componentInstance>
<properties>
<name>label</name>
<value>Hello</value>
</properties>
<componentName>flexipage:fieldSection</componentName>
<identifier>id1</identifier>
</componentInstance>
<!-- CORRECT — the ONLY valid element name -->
<componentInstance>
<componentInstanceProperties>
<name>label</name>
<value>Hello</value>
</componentInstanceProperties>
<componentName>flexipage:fieldSection</componentName>
<identifier>id1</identifier>
</componentInstance>
```
**There is no `<properties>` element in FlexiPage XML. It does not exist. Every time you write a property inside `<componentInstance>`, you MUST write `<componentInstanceProperties>`. If you find yourself typing `<properties>`, STOP and correct it to `<componentInstanceProperties>`.**
---
## 1. Property Value Encoding (MOST COMMON ERROR)
**Any property value with HTML/XML characters MUST be manually encoded in the following order** (wrong order causes double-encoding corruption):
```text
1. & → & (FIRST! Encode this before others)
2. < → <
3. > → >
4. " → "
5. ' → '
```
**Wrong:**
```xml
<value><b>Important</b> text</value>
```
**Correct:**
```xml
<value><b>Important</b> text</value>
```
**Check your XML:** Search for `<value>` tags - they should never contain raw `<` or `>` characters.
## 2. Field References
Use `Record.{FieldApiName}` — never `{ObjectName}.{FieldApiName}` (Salesforce resolves from Record, not object name).
```xml
<!-- Correct -->
<fieldItem>Record.Name</fieldItem>
<!-- Wrong -->
<fieldItem>Account.Name</fieldItem>
```
## 3. Region vs Facet Types
**Template Regions** (header, main, sidebar):
```xml
<name>header</name>
<type>Region</type>
```
**Component Facets** (internal slots like fieldSection columns):
```xml
<name>Facet-12345</name>
<type>Facet</type>
```
**Rule:** If it's a template region name → `Region`. If it's a component slot → `Facet`.
## 4. itemInstances — ONE Child Per Wrapper (CRITICAL)
**Each `<itemInstances>` can contain exactly ONE child element** — either one `<componentInstance>` OR one `<fieldInstance>`. Never put multiple children inside a single `<itemInstances>`.
```xml
<!-- WRONG — multiple componentInstance in one itemInstances -->
<itemInstances>
<componentInstance>
<componentName>flexipage:field</componentName>
<identifier>field1</identifier>
</componentInstance>
<componentInstance>
<componentName>flexipage:field</componentName>
<identifier>field2</identifier>
</componentInstance>
</itemInstances>
<!-- CORRECT — each componentInstance in its own itemInstances -->
<itemInstances>
<componentInstance>
<componentName>flexipage:field</componentName>
<identifier>field1</identifier>
</componentInstance>
</itemInstances>
<itemInstances>
<componentInstance>
<componentName>flexipage:field</componentName>
<identifier>field2</identifier>
</componentInstance>
</itemInstances>
```
### fieldInstance Structure
Every fieldInstance requires:
```xml
<itemInstances>
<fieldInstance>
<fieldInstanceProperties>
<name>uiBehavior</name>
<value>none</value> <!-- none|readonly|required -->
</fieldInstanceProperties>
<fieldItem>Record.FieldName__c</fieldItem>
<identifier>RecordFieldName_cField</identifier>
</fieldInstance>
</itemInstances>
```
**Valid `uiBehavior` values (lowercase only):**
| Value | Meaning |
|-------|---------|
| `none` | Field respects standard editability settings (default) |
| `readonly` | Field is permanently locked on this page |
| `required` | Field must be filled out before saving on this page |
**Rules:**
- Each `<itemInstances>` gets exactly ONE child (`<componentInstance>` or `<fieldInstance>`)
- fieldInstance must have `fieldInstanceProperties` with `uiBehavior`
- Use `Record.{Field}` format
- There is NO `edit` value — use `none` for standard editable fields
## 5. Unique Identifiers and Region Names (CRITICAL - PREVENTS DUPLICATE ERRORS)
**EVERY identifier and region/facet name MUST be unique across the entire FlexiPage file.**
- **NEVER create two `<flexiPageRegions>` blocks with the same `<name>`**
- **If multiple components belong to same facet, combine them in ONE region with multiple `<itemInstances>`**
- **NEVER reuse the same `<identifier>` value**
- **Always read entire file first and extract ALL existing identifiers and names**
- **Element order inside `<flexiPageRegions>`**: `<itemInstances>` FIRST, then `<mode>` (if needed), then `<name>`, then `<type>` — NEVER put `<name>`/`<type>` before `<itemInstances>`
**Wrong - This WILL FAIL with duplicate name error:**
```xml
<!-- First field section in detail tab -->
<flexiPageRegions>
<itemInstances>
<componentInstance>
<identifier>flexipage_property_details_fieldSection</identifier>
...
</componentInstance>
</itemInstances>
<name>detailTabContent</name> <!-- WRONG: DUPLICATE NAME -->
<type>Facet</type>
</flexiPageRegions>
<!-- Second field section in detail tab -->
<flexiPageRegions>
<itemInstances>
<componentInstance>
<identifier>flexipage_pricing_fieldSection</identifier>
...
</componentInstance>
</itemInstances>
<name>detailTabContent</name> <!-- WRONG: DUPLICATE NAME - DEPLOYMENT FAILS -->
<type>Facet</type>
</flexiPageRegions>
```
**Correct - Combine itemInstances in ONE region:**
```xml
<!-- Both field sections in same detail tab facet -->
<flexiPageRegions>
<itemInstances>
<componentInstance>
<identifier>flexipage_property_details_fieldSection</identifier>
...
</componentInstance>
</itemInstances>
<itemInstances>
<componentInstance>
<identifier>flexipage_pricing_fieldSection</identifier>
...
</componentInstance>
</itemInstances>
<name>detailTabContent</name> <!-- CORRECT: ONE REGION, MULTIPLE COMPONENTS -->
<type>Facet</type>
</flexiPageRegions>
```
**When to combine vs separate:**
- **Combine**: Components that logically belong to same tab/section (e.g., multiple field sections in detail tab)
- **Separate**: Components that belong to different tabs/sections (e.g., `detailTabContent` vs `relatedTabContent`)
---
## 6. Correct Element Names (CRITICAL — PREVENTS INVALID XML ERRORS)
**FlexiPage XML uses specific element names. Common LLM hallucinations use WRONG names that cause deployment failures.**
| WRONG (do NOT use) | CORRECT |
|---|---|
| `<entityType>` | `<sobjectType>` |
| `<properties>` | `<componentInstanceProperties>` |
| `<regions>` | `<flexiPageRegions>` |
| `<components>` | `<itemInstances>` |
| `<innerComponents>` | (does not exist — use facets for nesting) |
| `<fieldItems>` | `<itemInstances>` containing `<fieldInstance>` |
| `<template>value</template>` | `<template><name>value</name></template>` |
| `<parentFlexiPage>flexipage:templateName</parentFlexiPage>` | `<parentFlexiPage>flexipage__default_rec_L</parentFlexiPage>` |
**Do NOT invent elements or component names:**
Only use component names discovered through the 3-tier discovery process or present in the template from CLI. Do NOT add any XML element that is not present in the template structure from the CLI template. If a component name did not come from discovery or the CLI template.
| WRONG (do NOT use) | Why / What to use instead |
|---|---|
| `<apiVersion>` | Not a FlexiPage element — API version lives in `sfdx-project.json` |
| `<description>` | Not a FlexiPage element — use `<masterLabel>` for the page name |
| `flexipage:tabs` | Does not exist — use `flexipage:tabset` + `flexipage:tab` in facets |
| `flexipage:tabset2` | Does not exist — correct name is `flexipage:tabset` |
| `flexipage:facet` | Does not exist — use `flexipage:column` with `body` property |
| `flexipage:fields` | Does not exist — use individual `fieldInstance` elements in a field facet |
| `<type>String</type>` inside `componentInstanceProperties` | Remove — only valid `<type>` value is `decorator`, and only for UtilityBar pages |
**Correct top-level FlexiPage structure (element order):**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
<flexiPageRegions>...</flexiPageRegions>
<masterLabel>Page Name</masterLabel>
<parentFlexiPage>flexipage__default_rec_L</parentFlexiPage>
<sobjectType>Account</sobjectType>
<template>
<name>flexipage:recordHomeTemplateDesktop</name>
</template>
<type>RecordPage</type>
</FlexiPage>
```
**Correct componentInstance structure:**
```xml
<componentInstance>
<componentInstanceProperties>
<name>propertyName</name>
<value>propertyValue</value>
</componentInstanceProperties>
<componentName>lightning:card</componentName>
<identifier>unique_id_1</identifier>
</componentInstance>
```
**`<componentInstanceProperties>` children — `<name>`, `<value>`, and optionally `<type>`:**
```xml
<!-- WRONG — "String", "Facet", etc. are NOT valid <type> values -->
<componentInstanceProperties>
<name>fieldApiName</name>
<type>String</type>
<value>Record.Name</value>
</componentInstanceProperties>
<!-- CORRECT — omit <type> for standard properties (most cases) -->
<componentInstanceProperties>
<name>fieldApiName</name>
<value>Record.Name</value>
</componentInstanceProperties>
<!-- CORRECT — <type>decorator</type> ONLY for UtilityBar component decorators -->
<componentInstanceProperties>
<name>panelHeight</name>
<type>decorator</type>
<value>480</value>
</componentInstanceProperties>
```
**`<type>` rules:**
- If omitted (default): the property applies to the Lightning component itself
- If `decorator`: the property applies to the **component decorator** (a wrapper that adds capabilities like height/width when opened)
- The ONLY valid value is `decorator` — never `String`, `Facet`, `Integer`, etc.
- Component decorators are ONLY supported on **UtilityBar** page types — do NOT use `<type>decorator</type>` on RecordPage, AppPage, or HomePage
**Nesting is done via facets, NOT via inner elements.** Components that contain other components reference a facet name in their properties; the facet is a sibling `<flexiPageRegions>` with `<type>Facet</type>`.
| Error | Cause | Fix |
|-------|-------|-----|
| "Element regions invalid in FlexiPage" | Used `<regions>` instead of `<flexiPageRegions>` | Replace with `<flexiPageRegions>` |
| "Element components invalid in FlexiPageRegion" | Used `<components>` instead of `<itemInstances>` | Replace with `<itemInstances>` |
| "couldn't retrieve design time component information" | Used hallucinated component name (`flexipage:tabs`, `flexipage:tabset2`) | Use `flexipage:tabset` — see `identifiers_and_regions.md` for the full 3-layer tab pattern |
---
## Common Deployment Errors
| Error | Cause | Fix |
|-------|-------|-----|
| "We couldn't retrieve or load the information on the field" | Invalid field API name — field doesn't exist or has incorrect spelling | Use MCP tools or describe commands to discover valid fields |
| "Invalid field reference" | Used `ObjectName.Field` instead of `Record.Field` | Change to `Record.{FieldApiName}` |
| "Element componentInstance is duplicated at this location in type ItemInstance" | Multiple `<componentInstance>` in one `<itemInstances>` | Each `<componentInstance>` needs its own `<itemInstances>` wrapper |
| "Element fieldInstance is duplicated" | Multiple fieldInstances in one `<itemInstances>` | Each fieldInstance needs its own `<itemInstances>` wrapper |
| "Missing fieldInstanceProperties" | No uiBehavior specified | Add `fieldInstanceProperties` with `uiBehavior` |
| "Unused Facet" | Facet defined but not referenced by any component | Remove Facet or reference it in a component property |
| "XML parsing error" | Unencoded HTML/XML in property values | Encode `<`, `>`, `&`, `"`, `'` in all `<value>` tags |
| "Cannot create component with namespace" | Invalid page name (used `__c` suffix) | Use `Volunteer_Record_Page` not `Volunteer__c_Record_Page` |
| "Region specifies mode that parent doesn't support" | Added `<mode>` to a region that doesn't support it | Only use `<mode>` where required (e.g., `<mode>Replace</mode>` in `detailTabContent` for Dynamic Forms) |
| "We couldn't retrieve the design time component information for component X" | Hallucinated component name (e.g., `flexipage:tabs`, `flexipage:tabset2`) | Use correct component name — see Section 6 table and `identifiers_and_regions.md` for valid patterns |
| "'String' is not a valid value for the enum 'ComponentInstancePropertyTypeEnum'" | Used invalid `<type>` value (e.g., `String`, `Facet`, `Integer`) inside `<componentInstanceProperties>` | Remove `<type>` entirely — the only valid value is `decorator`, and only for UtilityBar page types |
| "Element apiVersion invalid at this location in type FlexiPage" | Added `<apiVersion>` to FlexiPage XML | Remove — API version belongs in `sfdx-project.json`, not in FlexiPage metadata |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |