When to Use This Skill

Use this skill when you need to:

Create Lightning pages (RecordPage, AppPage, HomePage)

Generate FlexiPage metadata XML

Add components to existing FlexiPages

Troubleshoot FlexiPage deployment errors

Understand FlexiPage structure and component configuration

Work with page layouts or Lightning page customization

Edit or update ANY *.flexipage-meta.xml file

Specification

FlexiPage Generation Guide

Overview

CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command.

Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.

Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.

Quick Start Workflow

Step 1: Bootstrap with CLI

MANDATORY FOR NEW PAGES: This step is NOT optional.

Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.

sf template generate flexipage

\

--name

<

PageName

>

\

--template

<

RecordPage

|

AppPage

|

HomePage

>

\

--sobject

<

SObject

>

\

--primary-field

<

Field

1

>

\

--secondary-fields

<

Field2,Field

3

>

\

--detail-fields

<

Field4,Field5,Field6,Field

7

>

\

--output-dir force-app/main/default/flexipages

CRITICAL:

If the

sf template generate flexipage

command fails,

STOP

.

Install the templates plugin:

sf plugins

install

templates

Retry the

sf template generate flexipage

command

Verify the FlexiPage XML file was created

Do NOT continue to Step 2 until the template command succeeds. The generated XML is required for the entire workflow.

Template-specific requirements

RecordPage:

Requires

--sobject

(e.g., Account, Custom_Object__c)

Requires field parameters:

--primary-field

Most important identifying field (e.g., Name)

--secondary-fields

Record summary (recommended 4-6, max 12)

--detail-fields

Full record details, including required fields (e.g., Name)

AppPage:

No additional requirements

HomePage:

No additional requirements

Field Selection Rules

Validate fields exist

Use MCP tools or describe commands to discover available fields for the object before specifying them in the command

Prefer compound fields

Use

Name

(not

FirstName

/

LastName

),

BillingAddress

(not

BillingStreet

/

BillingCity

/

BillingState

),

MailingAddress

, etc. when available

Include required fields in detail-fields

Always include object required fields (like Name ) in the --detail-fields parameter, even if they're also used in --primary-field or --secondary-fields What you get Valid FlexiPage XML with correct structure Pre-configured regions and basic components Proper field references and facet structure Ready to deploy as-is or enhance further Step 2: Deploy Base Page Run a dry-run deployment of the entire project to validate the page and dependencies: sf project deploy start --dry-run -d "force-app/main/default" --test-level NoTestRun --wait 10 --json Critical: Fix any deployment errors before proceeding. The page must validate successfully. Step 3: STOP - No Further Modifications MANDATORY: Stop after Step 2. Do not add components or edit the FlexiPage XML. This applies even if the user requested: Additional components Page customization Component configuration What you CAN do: Suggest what components would be useful Explain what enhancements are possible Document what would need to be added manually What you CANNOT do: Modify the XML file Add any components Make any enhancements Critical XML Rules 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): 1. & → & (FIRST! Encode this before others) 2. < → < 3. > → > 4. " → " 5. ' → ' Wrong: < value

< b

Important </ b

text </ value

Correct: < value

< b > Important < /b > text </ value

Check your XML: Search for tags - they should never contain raw < or

characters. 2. Field References ALWAYS: Record.{FieldApiName} NEVER: {ObjectName}.{FieldApiName}

< fieldItem

Record.Name </ fieldItem

< fieldItem

Account.Name </ fieldItem

1. Region vs Facet Types Template Regions (header, main, sidebar): < name

header </ name

< type

Region </ type

Component Facets (internal slots like fieldSection columns): < name

Facet-12345 </ name

< type

Facet </ type

Rule: If it's a template region name → Region . If it's a component slot → Facet . 4. fieldInstance Structure Every fieldInstance requires: < itemInstances

< fieldInstance

< fieldInstanceProperties

< name

uiBehavior </ name

< value

none </ value

</ fieldInstanceProperties

< fieldItem

Record.FieldName__c </ fieldItem

< identifier

RecordFieldName_cField </ identifier

</ fieldInstance

</ itemInstances

Rules: Each fieldInstance in its own wrapper Must have fieldInstanceProperties with uiBehavior Use Record.{Field} format 5. Unique Identifiers and Region Names (CRITICAL - PREVENTS DUPLICATE ERRORS) EVERY identifier and region/facet name MUST be unique across the entire FlexiPage file. Critical Rules: ❌ NEVER create two blocks with the same ✅ If multiple components belong to same facet, combine them in ONE region with multiple ❌ NEVER reuse the same value ✅ Always read entire file first and extract ALL existing identifiers and names Wrong - This WILL FAIL with duplicate name error:

< flexiPageRegions

< itemInstances

< componentInstance

< identifier

flexipage_property_details_fieldSection </ identifier

... </ componentInstance

</ itemInstances

< name

detailTabContent </ name

< type

Facet </ type

</ flexiPageRegions

< flexiPageRegions

< itemInstances

< componentInstance

< identifier

flexipage_pricing_fieldSection </ identifier

... </ componentInstance

</ itemInstances

< name

detailTabContent </ name

< type

Facet </ type

</ flexiPageRegions

Correct - Combine itemInstances in ONE region:

< flexiPageRegions

< itemInstances

< componentInstance

< identifier

flexipage_property_details_fieldSection </ identifier

... </ componentInstance

</ itemInstances

< itemInstances

< componentInstance

< identifier

flexipage_pricing_fieldSection </ identifier

... </ componentInstance

</ itemInstances

< name

detailTabContent </ name

<

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

)

Common Deployment Errors

"We couldn't retrieve or load the information on the field"

Cause:

Invalid field API name - field doesn't exist on the object or has incorrect spelling

Fix:

Use MCP tools or describe commands to discover valid fields, then update the field reference (see Field Selection Rules)

"Invalid field reference"

Cause:

Used

ObjectName.Field

instead of

Record.Field

Fix:

Change to

Record.{FieldApiName}

"Element fieldInstance is duplicated"

Cause:

Multiple fieldInstances in one itemInstances

Fix:

Each fieldInstance needs its own

wrapper

"Missing fieldInstanceProperties"

Cause:

No uiBehavior specified

Fix:

Add

fieldInstanceProperties

with

uiBehavior

"Unused Facet"

Cause:

Facet defined but not referenced by any component

Fix:

Remove Facet or reference it in a component property

"XML parsing error"

Cause:

Unencoded HTML/XML in property values

Fix:

Manually encode

<

,

>

,

&

,

"

,

'

in all

tags

"Cannot create component with namespace"

Cause:

Invalid page name (don't use

__c

suffix in page names)

Fix:

Use "Volunteer_Record_Page" not "Volunteer__c_Record_Page"

"Region specifies mode that parent doesn't support"

Cause:

Added

tag to region

Fix:

Remove

tags - they're not needed for standard regions

Generating Unique Identifiers

CRITICAL: Before generating ANY new identifier or facet name, follow the rules in section 5 of "Critical XML Rules" above.

Identifier Generation Algorithm

:

1. Extract ALL existing AND values from XML

2. Generate base name: {componentType}_{context}

Examples: "relatedList_contacts", "richText_header", "tabs_main"

3. Find first available number:

- Try "{base}_1"

- If exists, try "{base}_2", "{base}_3", etc.

- Use first available

Examples

:

First contacts related list:

relatedList_contacts_1

Second contacts related list:

relatedList_contacts_2

Rich text in header:

richText_header_1

Field section:

fieldSection_details_1

Facet Naming - Two Patterns

:

Named facets

(for major content areas):

detailTabContent

(detail tab content)

maintabs

(main tab container)

sidebartabs

(sidebar tab container)

Use when facet represents meaningful content area

UUID facets

(for internal structure):

Format:

Facet-{8hex}-{4hex}-{4hex}-{4hex}-{12hex}

Example:

Facet-66d5a4b3-bf14-4665-ba75-1ceaa71b2cde

Use for field section columns, nested containers, anonymous slots

When adding components to existing files:

Check if target facet name already exists

If exists: Add new

to that existing region (see section 5 above for details)

If doesn't exist: Create new region with unique name

Region Selection

Parse regions from file

- don't hardcode names. Templates vary:

flexipage:recordHomeTemplateDesktop

→

header

,

main

,

sidebar

runtime_service_fieldservice:...

→

header

,

main

,

footer

Others may have different region names

Default placement

End of target region (after last ) Insertion pattern : < flexiPageRegions

< name

main </ name

< type

Region </ type

< itemInstances

</ itemInstances

< itemInstances

</ itemInstances

< itemInstances

</ itemInstances

</ flexiPageRegions

Container Components with Facets Components like tabs, accordions, field sections require facets. Pattern :

< flexiPageRegions

< itemInstances

< componentInstance

< componentName

flexipage:tabset2 </ componentName

< identifier

tabs_main_1 </ identifier

< componentInstanceProperties

< name

tabs </ name

< value

tab1_content </ value

< value

tab2_content </ value

</ componentInstanceProperties

</ componentInstance

</ itemInstances

< name

main </ name

< type

Region </ type

</ flexiPageRegions

< flexiPageRegions

< itemInstances

</ itemInstances

< name

tab1_content </ name

< type

Facet </ type

</ flexiPageRegions

< flexiPageRegions

< itemInstances

</

itemInstances

>

<

name

>

tab2_content

</

name

>

<

type

>

Facet

</

type

>

</

flexiPageRegions

>

Critical

Facet regions are siblings of template regions at the same level, not nested inside them. Component-Specific Tips dynamicHighlights (RecordPage Header) Location: Must be in header region. Explicit Fields (via CLI): Use the most important fields to show a summary of the record. The single primary field is used to identify the record, like a name. The secondary fields (max 12, recommended 6) are used as a summary of the record. --primary-field Name --secondary-fields Phone,Industry,AnnualRevenue CLI generates Facets with field references automatically. fieldSection Use for: Displaying fields in columns. Structure: Three-level nesting: Template Region (Region type) Column Facets (Facet type) Field Facets (Facet type) Referenced in component property: < componentInstanceProperties

< name

columns </ name

< value

Facet-{uuid} </ value

</ componentInstanceProperties

rich Text component Component name: flexipage:richText Use for: Displaying HTML-formatted rich text content with support for text formatting, headings, lists, tables, images, links, forms, and multimedia elements. Preserves styling and layout. Escape all special characters in the default text. Location: Can be used in any region on any page type (Home, Record, App, Community pages). CLI generates the component directly without nested structures. User: "Add a rich text component to force-app/.../Account_Record_Page.flexipage-meta.xml" Structure: Single-level component (no facets): Component instance (flexipage:richText) with direct properties XML Structure Example: < itemInstances

< componentInstance

< componentInstanceProperties

< name

decorate </ name

< value

true </ value

</ componentInstanceProperties

< componentName

flexipage:richText </ componentName

< identifier

flexipage_richText </ identifier

</ componentInstance

</ itemInstances

Identifier Pattern: flexipage_richText or flexipage_richText_{sequence} Required Metadata Structure < FlexiPage xmlns = " http://soap.sforce.com/2006/04/metadata "

< flexiPageRegions

</ flexiPageRegions

< masterLabel

Page Label </ masterLabel

< template

< name

flexipage:recordHomeTemplateDesktop </ name

</ template

< type

RecordPage </ type

< sobjectType

Object__c </ sobjectType

</ FlexiPage

Page Types: RecordPage - requires AppPage - no sobjectType HomePage - no sobjectType Validation Checklist Before deploying: [NEW PAGES ONLY] Used CLI to bootstrap - NEVER create FlexiPage XML from scratch ALL identifiers are unique - no duplicate values anywhere in file ALL region/facet names are unique - no duplicate values in Multiple components in same facet are combined - ONE region with multiple , NOT separate regions with same name All field references use Record.{Field} format Each fieldInstance has fieldInstanceProperties with uiBehavior Each fieldInstance in own wrapper Template regions use Region Component facets use Facet Property values with HTML/XML are manually encoded No tags in regions No __c suffix in page names Each Facet referenced by exactly one component property Quick Reference: CLI Command

RecordPage with fields

sf template generate flexipage \ --name Account_Custom_Page \ --template RecordPage \ --sobject Account \ --primary-field Name \ --secondary-fields Phone,Industry,AnnualRevenue \ --detail-fields Street,City,State,Name,Phone,Email

AppPage

sf template generate flexipage \ --name Sales_Dashboard \ --template AppPage \ --label "Sales Dashboard"

HomePage

sf template generate flexipage \ --name Custom_Home \ --template HomePage \ --description "Custom home for sales team" All templates support: --output-dir (default: current directory) --api-version (default: latest) --label (default: page name) --description