Choose and structure the UI layer of a Salesforce solution for Spring '26 — the build-vs-configure ladder from Dynamic Forms and screen flows to LWC, Agentforce surfaces, Experience Cloud LWR sites, Lightning Out 2.0 and off-platform apps; org-wide design-system strategy; codebase and package layout; packaging with unlocked, org-dependent and 2GP managed packages; multi-org component sharing; Aura and Visualforce migration plans; and the ADR that records the decision.
When agents use itUse this whenever the user asks whether to build something in LWC or declaratively, whether a portal should be an LWR site or an external React app, how to structure a Salesforce UI codebase or share components across teams and orgs, how to package and version them, how to plan an Aura-to-LWC or Visualforce migration, or which Experience Cloud template and licence to choose. Also apply it when a performance complaint about a record page turns out to be a page-composition decision. To write component code use `lwc-development`.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill salesforce-frontend-architecture -a github-copilot
# or with the org installer (adds .github/skills/salesforce-frontend-architecture):
npx -y github:AGCO-Global/org-skills add skill salesforce-frontend-architecture
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the salesforce-lwc-skills plugin, which bundles all Salesforce / LWC skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install salesforce-lwc-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill salesforce-frontend-architecture -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill salesforce-frontend-architecture -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill salesforce-frontend-architecture -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill salesforce-frontend-architecture -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the salesforce-frontend-architecture folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Skill contents
Salesforce Frontend Architecture
Targets: Salesforce Spring '26 (API 66.0), SLDS 2 and Lightning Out 2.0 GA since Winter '26 · Verified: 2026-09 against https://developer.salesforce.com (LWC and LWR guides, Winter/Spring '26 release blogs) and https://help.salesforce.com (Experience Cloud, External Client Apps)
The first architectural question on Salesforce is not "which framework" but how much code at all. Every custom component is something the org maintains through three releases a year, so the job is to find the highest rung of the ladder that meets the requirement and write down why the cheaper rungs were rejected.
1. The ladder
Stop at the first rung that fits.
Standard UI — page layouts, Dynamic Forms, Dynamic Actions, Dynamic Related Lists, list views. No code, works on mobile, survives upgrades.
Screen flows — guided processes and wizards; add one LWC as a single screen component rather than rebuilding the wizard.
App Builder with standard and AppExchange components — dashboards, related lists, tabs.
Agentforce — when the need is "ask and act" rather than "look at a screen", an agent action (invocable Apex or an autolaunched flow) plus the standard agent panel beats a custom UI, and lightning__AgentforceInput/Output components fill the gaps.
Experience Cloud (LWR) — external users, portals, public sites.
Lightning Out 2.0 — the supported way to render existing LWCs inside someone else's web app (LWR-based, GA Winter '26). Lightning Out 1.0 is legacy.
Off-platform app (React/Angular/Next.js) over REST, GraphQL, Pub/Sub and Data 360 — when the UX or the identity model genuinely exceeds Lightning, or most of the data lives elsewhere.
2. Decide first
Question
Default
Change when
Internal record UI
Dynamic Forms on a standard record page
Interaction the page cannot express → one focused LWC in a region
Customer or partner portal
LWR Experience site
Consumer-grade branding, non-Salesforce identity, or a design system you already own → off-platform app with a BFF
Experience Cloud template
LWR (Build Your Own / Microsite)
An Aura template only when a required standard component has no LWR equivalent — name the component and the gap in the ADR
Embedding in an existing web property
Lightning Out 2.0
Deep integration or SEO-critical pages → build the page off platform
Shared components across teams, one org
Unlocked package, source of truth in git
Legacy org whose metadata is tangled → org-dependent unlocked package
Shared components across orgs or for customers
2GP managed package with a namespace
Internal-only work never needs a namespace
Styling
One design-system package on SLDS 2 hooks
Never per-team restyling of base components
State across components
Container owns it; children take @api props
Different regions or apps → Lightning Message Service; another user changed the record → empApi on CDC/Platform Events
Mobile
Salesforce mobile app rendering the same components
Offline or device APIs → Mobile Publisher or Mobile SDK
The @AuraEnabled controller is a façade: no logic, so the same service is reachable from Flow (@InvocableMethod), triggers and batch. Layering rules live in apex-development.
Split into packages by domain (design-system, sales-orders, service-console) with explicit dependencies in sfdx-project.json; every UI package depends on the design system, never the reverse.
Circular dependencies between packages are the signal that the split is wrong, not that the tooling is.
Packaging mechanics, version promotion and pipelines belong to salesforce-devops; component code to lwc-development; Jest and browser tests to salesforce-frontend-testing.
4. Design system
A ds* component set wrapping base components with the org's patterns — page header with breadcrumbs, empty state, error panel, confirmation modal (lightning/modal), filter bar — published as an unlocked package with a changelog and a code-owner group. Product teams compose from it; nobody restyles lightning-button. Visual truth is SLDS 2 hooks plus the org theme — see slds2-and-styling.md in ../lwc-development/references/. Governance that actually holds: an ADR per new shared component, @deprecated in JSDoc one release before removal, and a showcase Lightning app with one tab per component so teams can see every state.
5. Page composition and performance
Fewer components per page beats fewer lines per component: each region is its own render and data cycle. Collapse rarely-used sections into lazily rendered tabs or accordions, prefer several small cacheable wires that the platform parallelises over one mega-controller returning page-shaped JSON, and page large lists on the server. Measure with the Lightning Usage App (EPT trends) and the per-page performance analysis in App Builder; for LWR sites use browser Lighthouse and Web Vitals — the Community Page Optimizer is an Aura-site tool. Budget EPT under ~3 s on record pages and treat a regression as a composition problem first.
6. Off-platform and identity
The browser never holds Salesforce credentials: an off-platform app talks to a backend-for-frontend that holds tokens, aggregates calls and caches. App identity is an External Client App — Connected App creation is disabled in Spring '26 orgs. Read picklists, layouts and validation through the UI API or describe calls so the external UI does not drift from the org's metadata. API limits are a shared org resource: one runaway frontend starves the integrations. Flows, credentials and limits are owned by salesforce-integration § 1–3 and 5.
7. Migration plans
Aura → LWC. Inventory and classify (replace with standard, rewrite, retire — Dynamic Forms often removes the component entirely). Convert leaves first, because LWC lives inside Aura and not the reverse. aura:method becomes @api, application events become LMS, $A.enqueueAction becomes @wire or imperative Apex with cacheable=true where possible. Retire wrappers last and compare EPT before and after. Visualforce → LWC. Many pages become flows plus Dynamic Forms with no code; PDF rendering stays on Visualforce (renderAs="pdf") or moves to a document service; controllers become Service and Selector classes the LWC controller reuses.
8. Deliverable format — a filled ADR
# ADR-014: Dealer portal runs on LWR, not a React app
Context 50 000 dealer users, order tracking and warranty claims, Salesforce is the system
of record, brand guidelines are "close to the corporate site", no mobile app planned.
Decision Experience Cloud LWR site, Partner Community licence, three custom LWCs reusing the
ds* design system; claims wizard is a screen flow with one LWC step.
Rejected React + BFF — would duplicate sharing logic off platform and add an identity provider
for no UX gain. Aura template — no reason to start on it in 2026.
Lightning Out 2.0 — there is no existing external property to embed into.
Consequences Guest and partner sharing designed up front (see salesforce-data-model);
Lighthouse budget on the two public pages; SLDS 2 theme owned by the platform team;
licence cost per dealer reviewed at 2027-03.
Review 2027-03
Checklist
The chosen rung is named and the cheaper rungs are rejected in writing
Experience Cloud template and licence chosen together with the sharing model
Package layout has no circular dependencies; the design system is a package
Design-system ownership, deprecation policy and showcase exist
Off-platform apps go through a BFF; no secrets in the browser; External Client App used
Migration plan classifies every Aura/Visualforce artefact and orders the work leaves-first
Agentforce considered before a custom screen for "ask and act" needs
ADR written and dated, with a review date
Anti-patterns
A custom LWC rebuilding what Dynamic Forms, a list view or a screen flow already does → climb the ladder back down.
New work in Aura → LWC. New Visualforce needs a stated reason (a missing LWR standard component, or an existing VF surface being extended); where it is justified, follow the VF rules in salesforce-org-conventions.
An off-platform app because "React is nicer" → name the UX or identity requirement Lightning cannot meet, or stay on platform.
Client secret in a browser bundle → backend-for-frontend.
Creating a Connected App for a new front end → External Client App.
Every team restyling base components → one design-system package.
One mega-controller returning page-shaped JSON → several cacheable wires.
Lightning Out 1.0 for a new embed → Lightning Out 2.0.
Starting an LWR portal before deciding the Experience Cloud licence → licence decides the sharing mechanism, so decide it first.
Go deeper
references/packaging-and-sharing.md — unlocked vs org-dependent vs 2GP managed, namespaces, versioning and dependency rules, multi-org sharing.
references/experience-cloud.md — LWR vs Aura templates, licences and sharing, guest-user hardening, theme layouts, audiences, SEO and performance budget.
references/migration-playbooks.md — the Aura and Visualforce inventories, classification table and step order, with EPT measurement.
Sibling skills: lwc-development to write the components, salesforce-frontend-testing for the test strategy, salesforce-devops for pipelines and package promotion, salesforce-data-model for sharing, salesforce-integration for APIs and identity, salesforce-code-review for pull requests, salesforce-org-conventions for the org's naming and mandated patterns.
---
name: salesforce-frontend-architecture
description: >
Choose and structure the UI layer of a Salesforce solution for Spring '26 — the build-vs-configure ladder from Dynamic Forms and screen flows to LWC, Agentforce surfaces, Experience Cloud LWR sites, Lightning Out 2.0 and off-platform apps; org-wide design-system strategy; codebase and package layout; packaging with unlocked, org-dependent and 2GP managed packages; multi-org component sharing; Aura and Visualforce migration plans; and the ADR that records the decision. Use this whenever the user asks whether to build something in LWC or declaratively, whether a portal should be an LWR site or an external React app, how to structure a Salesforce UI codebase or share components across teams and orgs, how to package and version them, how to plan an Aura-to-LWC or Visualforce migration, or which Experience Cloud template and licence to choose. Also apply it when a performance complaint about a record page turns out to be a page-composition decision. To write component code use `lwc-development`.
metadata:
technology: Salesforce
type: architecture
---
# Salesforce Frontend Architecture
> **Targets:** Salesforce Spring '26 (API 66.0), SLDS 2 and Lightning Out 2.0 GA since Winter '26 · **Verified:** 2026-09 against https://developer.salesforce.com (LWC and LWR guides, Winter/Spring '26 release blogs) and https://help.salesforce.com (Experience Cloud, External Client Apps)
The first architectural question on Salesforce is not "which framework" but **how much code at all**. Every custom component is something the org maintains through three releases a year, so the job is to find the highest rung of the ladder that meets the requirement and write down why the cheaper rungs were rejected.
## 1. The ladder
Stop at the first rung that fits.
1. **Standard UI** — page layouts, **Dynamic Forms**, Dynamic Actions, Dynamic Related Lists, list views. No code, works on mobile, survives upgrades.
2. **Screen flows** — guided processes and wizards; add one LWC as a single screen component rather than rebuilding the wizard.
3. **App Builder with standard and AppExchange components** — dashboards, related lists, tabs.
4. **Agentforce** — when the need is "ask and act" rather than "look at a screen", an agent action (invocable Apex or an autolaunched flow) plus the standard agent panel beats a custom UI, and `lightning__AgentforceInput`/`Output` components fill the gaps.
5. **Custom LWC on platform** — bespoke interaction, dense data, performance-critical lists.
6. **Experience Cloud (LWR)** — external users, portals, public sites.
7. **Lightning Out 2.0** — the supported way to render existing LWCs inside someone else's web app (LWR-based, GA Winter '26). Lightning Out 1.0 is legacy.
8. **Off-platform app** (React/Angular/Next.js) over REST, GraphQL, Pub/Sub and Data 360 — when the UX or the identity model genuinely exceeds Lightning, or most of the data lives elsewhere.
## 2. Decide first
| Question | Default | Change when |
|---|---|---|
| Internal record UI | Dynamic Forms on a standard record page | Interaction the page cannot express → one focused LWC in a region |
| Customer or partner portal | **LWR Experience site** | Consumer-grade branding, non-Salesforce identity, or a design system you already own → off-platform app with a BFF |
| Experience Cloud template | LWR (Build Your Own / Microsite) | An Aura template only when a required standard component has no LWR equivalent — name the component and the gap in the ADR |
| Embedding in an existing web property | **Lightning Out 2.0** | Deep integration or SEO-critical pages → build the page off platform |
| Shared components across teams, one org | **Unlocked package**, source of truth in git | Legacy org whose metadata is tangled → org-dependent unlocked package |
| Shared components across orgs or for customers | **2GP managed package** with a namespace | Internal-only work never needs a namespace |
| Styling | One design-system package on SLDS 2 hooks | Never per-team restyling of base components |
| State across components | Container owns it; children take `@api` props | Different regions or apps → Lightning Message Service; another user changed the record → `empApi` on CDC/Platform Events |
| Mobile | Salesforce mobile app rendering the same components | Offline or device APIs → Mobile Publisher or Mobile SDK |
## 3. Codebase and packages
```
force-app/ (or one package directory per package)
├── lwc/
│ ├── ds*/ design-system wrappers (dsPageHeader, dsEmptyState, dsConfirm)
│ ├── shared*/ service-only modules (sharedUtils, sharedStyles, sharedConstants)
│ └── <feature>*/ orderList, orderDetail, orderFilterBar
├── classes/ <Domain>Controller (thin @AuraEnabled façade) · Service · Selector · *Test
├── messageChannels/ versioned LMS contracts
└── flexipages/, flows/, staticresources/, customLabels/
```
- The `@AuraEnabled` controller is a façade: no logic, so the same service is reachable from Flow (`@InvocableMethod`), triggers and batch. Layering rules live in `apex-development`.
- Split into packages by domain (`design-system`, `sales-orders`, `service-console`) with explicit dependencies in `sfdx-project.json`; every UI package depends on the design system, never the reverse.
- Circular dependencies between packages are the signal that the split is wrong, not that the tooling is.
- Packaging mechanics, version promotion and pipelines belong to `salesforce-devops`; component code to `lwc-development`; Jest and browser tests to `salesforce-frontend-testing`.
## 4. Design system
A `ds*` component set wrapping base components with the org's patterns — page header with breadcrumbs, empty state, error panel, confirmation modal (`lightning/modal`), filter bar — published as an unlocked package with a changelog and a code-owner group. Product teams compose from it; nobody restyles `lightning-button`. Visual truth is SLDS 2 hooks plus the org theme — see `slds2-and-styling.md` in `../lwc-development/references/`. Governance that actually holds: an ADR per new shared component, `@deprecated` in JSDoc one release before removal, and a showcase Lightning app with one tab per component so teams can see every state.
## 5. Page composition and performance
Fewer components per page beats fewer lines per component: each region is its own render and data cycle. Collapse rarely-used sections into lazily rendered tabs or accordions, prefer several small cacheable wires that the platform parallelises over one mega-controller returning page-shaped JSON, and page large lists on the server. Measure with the **Lightning Usage App** (EPT trends) and the per-page performance analysis in App Builder; for LWR sites use browser Lighthouse and Web Vitals — the Community Page Optimizer is an Aura-site tool. Budget EPT under ~3 s on record pages and treat a regression as a composition problem first.
## 6. Off-platform and identity
The browser never holds Salesforce credentials: an off-platform app talks to a **backend-for-frontend** that holds tokens, aggregates calls and caches. App identity is an **External Client App** — Connected App creation is disabled in Spring '26 orgs. Read picklists, layouts and validation through the UI API or describe calls so the external UI does not drift from the org's metadata. API limits are a shared org resource: one runaway frontend starves the integrations. Flows, credentials and limits are owned by `salesforce-integration` § 1–3 and 5.
## 7. Migration plans
**Aura → LWC.** Inventory and classify (replace with standard, rewrite, retire — Dynamic Forms often removes the component entirely). Convert leaves first, because LWC lives inside Aura and not the reverse. `aura:method` becomes `@api`, application events become LMS, `$A.enqueueAction` becomes `@wire` or imperative Apex with `cacheable=true` where possible. Retire wrappers last and compare EPT before and after. **Visualforce → LWC.** Many pages become flows plus Dynamic Forms with no code; PDF rendering stays on Visualforce (`renderAs="pdf"`) or moves to a document service; controllers become Service and Selector classes the LWC controller reuses.
## 8. Deliverable format — a filled ADR
```
# ADR-014: Dealer portal runs on LWR, not a React app
Context 50 000 dealer users, order tracking and warranty claims, Salesforce is the system
of record, brand guidelines are "close to the corporate site", no mobile app planned.
Decision Experience Cloud LWR site, Partner Community licence, three custom LWCs reusing the
ds* design system; claims wizard is a screen flow with one LWC step.
Rejected React + BFF — would duplicate sharing logic off platform and add an identity provider
for no UX gain. Aura template — no reason to start on it in 2026.
Lightning Out 2.0 — there is no existing external property to embed into.
Consequences Guest and partner sharing designed up front (see salesforce-data-model);
Lighthouse budget on the two public pages; SLDS 2 theme owned by the platform team;
licence cost per dealer reviewed at 2027-03.
Review 2027-03
```
## Checklist
- [ ] The chosen rung is named and the cheaper rungs are rejected in writing
- [ ] Experience Cloud template and licence chosen together with the sharing model
- [ ] Package layout has no circular dependencies; the design system is a package
- [ ] Design-system ownership, deprecation policy and showcase exist
- [ ] Page composition budgeted: regions, lazy sections, server-side paging, EPT target
- [ ] Off-platform apps go through a BFF; no secrets in the browser; External Client App used
- [ ] Migration plan classifies every Aura/Visualforce artefact and orders the work leaves-first
- [ ] Agentforce considered before a custom screen for "ask and act" needs
- [ ] ADR written and dated, with a review date
## Anti-patterns
- **A custom LWC rebuilding what Dynamic Forms, a list view or a screen flow already does** → climb the ladder back down.
- **New work in Aura** → LWC. New Visualforce needs a stated reason (a missing LWR standard component, or an existing VF surface being extended); where it is justified, follow the VF rules in `salesforce-org-conventions`.
- **An off-platform app because "React is nicer"** → name the UX or identity requirement Lightning cannot meet, or stay on platform.
- **Client secret in a browser bundle** → backend-for-frontend.
- **Creating a Connected App for a new front end** → External Client App.
- **Every team restyling base components** → one design-system package.
- **One mega-controller returning page-shaped JSON** → several cacheable wires.
- **Lightning Out 1.0 for a new embed** → Lightning Out 2.0.
- **Starting an LWR portal before deciding the Experience Cloud licence** → licence decides the sharing mechanism, so decide it first.
## Go deeper
- `references/packaging-and-sharing.md` — unlocked vs org-dependent vs 2GP managed, namespaces, versioning and dependency rules, multi-org sharing.
- `references/experience-cloud.md` — LWR vs Aura templates, licences and sharing, guest-user hardening, theme layouts, audiences, SEO and performance budget.
- `references/migration-playbooks.md` — the Aura and Visualforce inventories, classification table and step order, with EPT measurement.
- Sibling skills: `lwc-development` to write the components, `salesforce-frontend-testing` for the test strategy, `salesforce-devops` for pipelines and package promotion, `salesforce-data-model` for sharing, `salesforce-integration` for APIs and identity, `salesforce-code-review` for pull requests, `salesforce-org-conventions` for the org's naming and mandated patterns.