/platform-flexipage-generate

name: platform-flexipage-generate
description: "Use 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."
allowed-tools: Bash Read Write
metadata:
  version: "1.1"
  domains: ["Platform"]
  minApiVersion: "60.0"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.126.4"
  mcpTools:
    metadata-experts:
      tools: ["execute_metadata_action"]
      semver: ">=1.0.0"

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

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.

**`<packageDirectory>`** = the `path` value from `sfdx-project.json` → `packageDirectories[0]` (e.g., `force-app`). Read it from the project file before running commands.

sf template generate flexipage \
  --name <PageName> \
  --template <RecordPage|AppPage|HomePage> \
  --sobject <SObject> \
  --primary-field <Field1> \
  --secondary-fields <Field2,Field3> \
  --detail-fields <Field4,Field5,Field6,Field7> \
  --output-dir <packageDirectory>/main/default/flexipages

**CRITICAL:** If the `sf template generate flexipage` command fails, **STOP**.

1. Install the templates plugin:

   sf plugins install templates

2. Retry the `sf template generate flexipage` command 3. 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 to validate the page and dependencies (use the default package directory from `sfdx-project.json`):

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

**Critical:** Fix any deployment errors before proceeding. The page must validate successfully.

Step 3: Add Components Dynamically (if requested)

After the base page deploys successfully, if the user wants additional components, follow the **Adding Components Dynamically** workflow below. All component additions MUST go through the discovery and inference pipeline — never write component XML from memory alone.

---

Critical XML Rules

**Read `references/xml_rules.md`** for all XML encoding rules, field reference format, region/facet types, fieldInstance structure, unique identifier requirements, and common deployment error resolutions.

**Key rules (quick reminder):**

• Encode HTML in `<value>` tags: `&` first, then `<`, `>`, `"`, `'`
• Field references: `Record.{FieldApiName}` (never `Object.Field`)
• Every `<identifier>` and region `<name>` must be unique across the file
• Multiple components in same facet → combine in ONE region with multiple `<itemInstances>`

---

Identifiers, Regions, and Containers

**Read `references/identifiers_and_regions.md`** for the identifier generation algorithm, facet naming patterns (named vs UUID), region selection rules, and container component facet structure.

---

Component-Specific Tips

dynamicHighlights (RecordPage Header)

**Location:** `header` region only. See `references/record_flexipage_dynamicHighlights.md` for full structure. CLI generates Facets automatically from `--primary-field` and `--secondary-fields`.

fieldSection

**Use for:** Displaying fields in columns. Three-level nesting: Region →