Salesforce Lightning Pages

Lightning Record Pages (Flexipages)

When to Use

• Adding quick actions to a record page
• Moving fields, components, or tabs on a Lightning page
• Modifying highlights panel actions
• Adding or rearranging related lists

Critical Knowledge

Flexipages Live in the Org, Not Just the Repo

Most flexipages are NOT in your local repo. You must retrieve first:

# Find the flexipage name for an object
sf project retrieve start --metadata FlexiPage --target-org 

# Or retrieve a specific one
sf project retrieve start --metadata "FlexiPage:Case_Record_Page" --target-org 

The file lands in: force-app/main/default/flexipages/.flexipage-meta.xml

Flexipage XML Structure (Key Sections)

    
        
        header
        
            
                highlights
                
            
        
        
        
        main
        
        
        
        sidebar
        
    

Recipes

Add Quick Actions to Highlights Panel

Step 1: Retrieve the flexipage (see above)

Step 2: Find the highlights panel action list. Search for:

highlights

Inside that component, find the ` with actionNames`. The value is a comma-separated list of action API names.

Step 3: Add your action to the comma-separated list:

    actionNames
    Case.Post_Email_Prompt,Case.Propose_Solution,Case.ChangeOwner,Case.Close

⚠️ CRITICAL: Actions must be object-scoped (e.g., Case.Post_Email_Prompt), NOT global. See salesforce-quick-actions skill for how to create them correctly.

Step 4: Deploy the flexipage:

sf project deploy start --source-dir force-app/main/default/flexipages/Case_Record_Page.flexipage-meta.xml --target-org 

Add a Component to a Tab

Find the tab's ` section, then add an ` block:

    
        YOUR_COMPONENT_NAME
        
            propertyName
            propertyValue
        
    

Move Fields Between Sections

Fields on flexipages are in `` within field section components. To move a field:

1. Find its current `` block
2. Cut it
3. Paste into the target section's `` list
4. Field order = display order

Remove a Component from a Tab (Full Facet Chain Cleanup)

Removing a component from a flexipage is NOT as simple as deleting its `` block. Flexipages use nested facet chains, and leaving orphaned facets breaks the XML silently.

Step 1: Map the full facet chain BEFORE making any edits

Search the flexipage for the component you want to remove. Note its containing facet ID. Then trace upward:

Component (e.g., quickActionListItem for "Escalate_to_Jira")
  └── contained in Facet-abf7c7ae (the immediate wrapper)
       └── referenced by fieldSection16 (a tab or section)
            └── contained in Facet-3307d075 (section wrapper)
                 └── referenced by column28 (a column)
                      └── contained in Facet-e850b2e3 (column wrapper)

Step 2: Identify ALL elements to remove

You must remove:

1. The `` block containing your component
2. The tab/section `` that references the component's facet
3. ALL intermediate facet `` blocks in the chain
4. Any `` references pointing to removed facets

Step 3: Remove from bottom up

Start with the innermost element (the component itself) and work outward:

1. Remove the component's itemInstance
2. Remove the facet region that contained only that component (if it's now empty)
3. Remove the section/tab item that referenced the now-empty facet
4. Continue up the chain, removing any facet regions that are now empty

Step 4: Verify XML integrity

After all edits:

• Every ` reference should point to an existing ` name
• No orphaned facet regions (facets not referenced by anything)
• Tab counts and column counts still make sense

Step 5: Deploy and verify

sf project deploy start --source-dir force-app/main/default/flexipages/YourPage.flexipage-meta.xml --target-org 

If deploy fails with XML errors, you likely left an orphaned facet or removed a facet still referenced elsewhere.

Common Pitfalls

| Pitfall | Fix | |---------|-----| | Quick action "not found" during deploy | Action must be object-scoped with ` — see quick-actions skill | | Flexipage not in repo | Must retrieve from org first: sf project retrieve start --metadata FlexiPage | | Related list actions vs highlights panel actions | They're different XML sections — search for highlights for the main action bar | | Deploy fails with unrelated errors | Use targeted deploy: --source-dir` pointing only to the flexipage file | | Removing component leaves orphaned facets | Trace FULL facet chain before editing — remove all facets in the chain | | Tab removed but section/column facets remain | Map parent→child facet relationships first, remove bottom-up |

Gotchas

Publisher Surfaces: Lightning vs Classic (HIGH-RISK)

Editing `` on a Lightning org is a no-op. Casechek is 100% Lightning. This has burned multiple sessions — always verify the surface before editing.

| Surface | XML location | Visible in Lightning? | |---|---|---| | Lightning Feed publisher tabs (Post/Email/Task inside Feed) | Page Layout ` | **YES — edit this** | | **Lightning top action bar** (Accept/Edit/Close buttons) | Flexipage force:highlightsPanel → actionNames (or falls back to layout ) | YES | | Salesforce Classic publisher | Page Layout | **NO — invisible** | | Global Publisher (Home/Chatter tab) | Global Layout ` | Only in non-record contexts |

Hard rules:

1. ` only accepts feed-item-producing actions. Deploying a Flow action there fails with: You can't add QuickActionType Flow to a QuickActionList`. That error means you're on the wrong surface.
2. To remove items from the Lightning Feed publisher, delete `` blocks from the page layout (not flexipage).
3. To change the top action bar buttons, edit the flexipage highlightsPanel actionNames. If unset, layout `` provides the fallback.

Diagnosis recipe — "I deployed but Lightning UI didn't change": It is almost never browser cache. Before recommending hard-refresh/incognito, query the live layout via Tooling API and confirm platformActionList matches what you deployed:

# Get layout Id
sf data query --query "SELECT Id, Name FROM Layout WHERE TableEnumOrId='Case'" --target-org  --tooling-api --json

# Inspect both lists
curl -s -H "Authorization: Bearer $TOKEN" \
  "$INSTANCE/services/data/v64.0/tooling/sobjects/Layout//" | \
  jq '.Metadata | {quickActionList, platformActionList}'

9 times out of 10 the deploy hit the wrong element.

Pre-Edit Checklist (Avoid the 4-Rev Cycle)

Before editing any layout/flexipage to change publisher actions:

1. Identify the surface — feed tabs (platformActionList), top action bar (flexipage highlights), or Classic (quickActionList)?
2. Confirm the user is in Lightning — Casechek is. So quickActionList edits are almost always wrong.
3. Read the live metadata first via Tooling API (above) — don't trust the file in the repo if you haven't pulled recently.

Validation After Deploy

1. Open a record in sandbox
2. Verify the action appears in the highlights panel (top action bar)
3. Click it to verify it launches correctly
4. Check that existing actions still work (regression)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jhillock1
• Source: jhillock1/salesforce-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.