Use this skill when users are losing time before they even open a record. List views, compact layouts, and search layouts all shape how quickly a user can browse, triage, and select the next record, but they solve different problems and should not be treated as interchangeable UI settings.
Before Starting
Gather this context before working on anything in this domain:
- Are users browsing a working queue, opening a record from mobile, or searching globally for a known record?
- Which fields must be visible in the first five seconds, and which fields only matter after the record is open?
- Is the pain caused by information density, ownership of shared views, or confusion between search results and list-based work queues?
- Are the views that matter already in source control, or do they live only in the org? Metadata API cannot see a Visible only to me view at all, so an org comparison that reports no drift may still be missing what users rely on.
Questions to Ask Before Configuring
Ask these before opening Setup. Each one maps to a behaviour in references/gotchas.md that turns a reasonable-looking configuration into a broken one.
| Ask | Why it matters | What a good answer adds |
|---|
| "Who is the audience for this view, and did anyone decide it should be public?" | A list view with no sharedTo element is public; the broadest audience is encoded as an absence, so nobody reviews it | An explicit sharing target (group, role, roleAndSubordinates, queue) or a written decision that public is intended |
| "Is this view meant to follow a queue?" | filterScope = Queue plus a queue developer name is a different object from a filtered view, and every queue already auto-creates one | Either a queue name that must deploy first, or a decision to use the auto-created view instead of authoring a rival |
| "What are the exact column tokens on this object?" | Standard-field columns are legacy tokens, not API names (PC_Email for PersonEmail), so hand-written columns render blank | A retrieved list view to harvest tokens from, instead of guesses |
| "Which record types exist, and which compact layout does each one get?" | compactLayoutAssignment sits on the object and on every record type; an unassigned layout renders nowhere | An assignment map: object default plus one line per record type |
| "Does any field we want in the highlights panel hold free text?" | Text area, long text area, rich text area, and multi-select picklist cannot go in a compact layout — the deploy fails | A short formula or text field to carry the summary, with the long field left on the record page |
| "Are these views migrating between orgs, and by what mechanism?" | ListView and SearchLayouts reject the package.xml wildcard and ListView members need Object.ViewUniqueName | A manifest that retrieves the encompassing object rather than a wildcard that silently returns nothing |
| "Which manifest member form does each type need — bare or object-qualified?" | Everything nested in an object takes <Object>.<Name>; CompactLayout is the one the guide never spells out, so the bare fullName looks right and fails the manifest deploy | A manifest written as Case.Case_Intake, and a plan to validate it with --manifest, not only --source-dir |
| "Who owns list-view creation on this object after go-live?" | Sprawl is a permission decision: "Manage Public List Views" also lets a user edit or delete every public view in the org | A named owner and the narrower "Manage Shared List Views" permission where it fits |
What a proper configuration adds over just doing it: views that survive a sandbox refresh because they are in source, a highlights panel that actually deploys and renders on every record type, and a public-view inventory small enough that the next admin can tell which queue is authoritative.
Core Concepts
List views, compact layouts, and search layouts each own a different stage of user navigation. List views are for browsing and filtering record sets. Compact layouts are for fast record recognition in highlights and mobile contexts. Search layouts shape how search results present records. When teams blur those responsibilities, they keep editing the wrong metadata and users still cannot find what they need.
List Views Are Working Surfaces
List views help users answer "what should I work on next?" They need a clear audience, strong filters, and only the columns required for triage. The best list view is not the one with the most data. It is the one that lets the intended persona decide quickly whether to open the record or move on.
Compact Layouts Are Scan Layers
Compact layouts are not mini page layouts. They should expose the few fields that identify the record and its current state, especially in highlights panels and mobile-first experiences. If a compact layout tries to summarize everything, it stops helping anyone.
Search Layouts And List Views Are Separate Concerns
Search results answer "which record is this?" while list views answer "which set of records should I process?" Changing search result columns does not fix a weak list view, and adding more list view columns does not improve global search behavior.
None Of These Features Are Security Controls
Fields appearing or not appearing in a compact layout or list view do not change object, field, or record access. Good UX configuration depends on security, but it does not replace it.
All Three Live Inside The Object
None of these is a standalone folder in Metadata API terms. Everything below is nested in the object's own definition, which is why "retrieve the object" is usually the right move and a wildcard usually is not.
| Metadata type | package.xml <name> | <members> | Wildcard * | Key elements |
|---|
ListView | ListView | Object.ViewUniqueName | No | filterScope (required), columns, filters, booleanFilter, queue, sharedTo, label, language, division |
CompactLayout | CompactLayout | Object.LayoutName | Yes | fields (ordered by priority), label |
SearchLayouts | via CustomObject | object name | No | listViewButtons, searchResultsAdditionalFields, lookupDialogsAdditionalFields, customTabListAdditionalFields, searchFilterFields, massQuickActions, excludedStandardButtons |
ProfileSearchLayouts | via CustomObject | object name | — | profileName, fields |
Enumerated members for the first two are object-qualified: Case.My_Open_Cases, Case.Case_Intake. The guide documents that form for ListView and not for CompactLayout — the compact-layout half is verified by a failed --manifest dry-run rather than by documentation (references/metadata-examples.md § Manifest member form, and gotcha 10 below).
filterScope is the one required element on a list view. Its enumeration is Everything, Mine, MineAndMyGroups, AssignedToMe (ServiceAppointment only), Queue, Delegated, MyTerritory, MyTeamTerritory, Team, SalesTeam, and ScopingRule — and a ScopingRule view only applies its rule when the user selects Filter by scope in Lightning Experience (admin/scoping-rules). Deployable XML for all four types is in references/metadata-examples.md.
Assignment Is Separate From Definition
A compact layout is inert until something names it. compactLayoutAssignment appears twice: once on the CustomObject as the object default, and once inside each RecordType. A record type with no assignment does not inherit visibly in the metadata, so the assignment map has to be written down per record type rather than inferred from the layout list.
Common Patterns
Persona-Specific Working Lists
When to use: Sales, service, or operations teams repeatedly work a filtered subset of records.
How it works: Create a small set of role-oriented list views with meaningful ownership, narrow filters, and only the columns needed for triage. Reserve broad "all records" views for admins or specialized troubleshooting.
Why not the alternative: A long list of near-duplicate public list views creates clutter and weakens trust in every queue.
Five-Second Compact Layout Design
When to use: Users need to recognize status, priority, owner, and key identifiers before opening the record.
How it works: Put the fields that answer "what is this and what state is it in?" into the compact layout. Keep the set short and stable. Use the full page or record page for deep context.
Why not the alternative: Stuffing the highlights area with every useful field makes the scan layer unreadable, especially on mobile.
Search Versus Browse Deliberately Split
When to use: Teams are trying to solve both search discovery and queue processing on the same object.
How it works: Tune search-result presentation for recognition, and tune list views for workflow. Review both with the same persona, but do not assume one setting replaces the other.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|
| Users need a filtered queue or worklist | List View | The primary need is browsing a record set and taking action on the next item |
| Users need to identify a record quickly after opening or in mobile | Compact Layout | The need is high-signal recognition, not detailed editing |
| Users are finding the wrong records from search | Search Layout or search-result configuration | Search result presentation is a separate surface from list views |
| Users need to edit or rearrange many fields on the record itself | Page Layout or Lightning Record Page | That is full-record design, not browse-and-scan configuration |
| The team wants to hide data from unauthorized users | Fix security model instead | These features do not enforce access controls |
Recommended Workflow
- Inventory what exists, from two directions. Retrieve the encompassing object (
sf project retrieve start --metadata CustomObject:<Object>) to get every list view, compact layout, and the searchLayouts block in one pull, then query SELECT DeveloperName, Name, SobjectType, IsSoqlCompatible FROM ListView WHERE SobjectType = '<Object>' in the org. The query returns views the retrieve cannot — private and auto-created queue views — and the difference between the two lists is the real inventory.
- Fill in
templates/list-views-and-compact-layouts-template.md. One row per existing view with audience, filters, columns, share scope, and a keep / merge / retire call; then the compact-layout field set and the assignment per record type. This is the artefact the rest of the workflow edits.
- Harvest tokens before writing any XML. Copy standard-field
columns and searchResultsAdditionalFields values from the retrieved files. Custom fields use their API name; standard fields do not, and guessing produces a blank column or a failed deploy.
- Author the metadata from
references/metadata-examples.md. Take the queue-scoped view, the booleanFilter + sharedTo view, the compact layout, and the object-level compactLayoutAssignment / recordTypes / searchLayouts block as the starting shapes, and follow the "How to read it" notes rather than editing them by analogy.
- Run the checker from the project root — not from inside
force-app/ — so the manifest is in scope alongside the source: python3 skills/admin/list-views-and-compact-layouts/scripts/check_list_views_and_compact_layouts.py --manifest-dir . (add --strict to fail on WARN and INFO as well as ERROR). It flags unfiltered public views, dangling booleanFilter indices, filterScope / queue mismatches, compact layouts holding an unsupported field type, compact layouts that no compactLayoutAssignment names, and the package.xml member form — CL-MEM-01 (a bare CompactLayout / ListView member whose file is in the tree) and CL-MEM-02 (a compact layout no manifest declares).
- Dry-run both ways —
--source-dir and --manifest — then confirm on a phone-width viewport. Open one record of each record type and one list view per persona; re-run the ListView query to confirm DeveloperName and IsSoqlCompatible match what was authored. Re-check references/gotchas.md if the retrieved file differs from what you sent — the search layout's Name field is added back by design.
- Record the governance decision. Who may create public views on this object, which auto-created queue views are authoritative, and when the inventory is reviewed again.
Review Checklist
Run through these before marking work in this area complete:
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
- Compact layouts do not replace page layouts - they support recognition and highlights, not full editing or detailed field placement.
- Search layout fixes do not change list views - teams often edit the wrong metadata because both features display columns.
- List-view sprawl is a governance problem, not just a UX problem - once everyone can create broad public views freely, the object becomes harder to navigate and harder to support.
- Field visibility in the UI is still bounded by security - if a user cannot access a field, layout design alone will not make it usable.
- "Manage Public List Views" is no longer the only permission for sharing a view - since Summer '26, grant "Manage Shared List Views" so a user can share their own list views with the roles, groups, and territories they belong to; "Manage Public List Views" still works, but it also lets them edit or delete every public list view in the org.
- A missing
sharedTo element means public, not unshared - the guide states SharedTo is present for shared and private views and absent for public ones, so the widest audience is the one with no markup to review.
- "Visible only to me" views are outside Metadata API entirely - they never appear in a retrieve, so a clean org diff is not evidence that users kept their views.
- Compact layouts reject four field types at deploy - text area, long text area, rich text area, and multi-select picklist, which is exactly the shortlist an admin reaches for when asked to show "what this record is about".
ListView and SearchLayouts reject the package.xml wildcard while CompactLayout accepts it - the same manifest can therefore ship half the design.- A bare
CompactLayout member in package.xml fails the deploy, and --source-dir never tells you - the member has to be Case.Case_Intake, not the layout's own fullName; --source-dir derives the member from the file so it always passes, while --manifest fails with "An object 'Case_Intake' of type CompactLayout was named in package.xml, but was not found in zipped directory".
Deeper treatment, with what happens / when it occurs / how to avoid, in references/gotchas.md.
Output Artifacts
| Artifact | Description |
|---|
| Browse-and-scan UX recommendation | Guidance on which surfaces should use list views, compact layouts, or search-result tuning |
| Configuration review findings | Issues such as over-wide columns, weak filters, and missing high-signal highlight fields |
| Object worksheet | Persona-specific inventory of list views, compact layouts, and search-result intent |
objects/<Object>/listViews/*.listView-meta.xml | Deployable list views with filterScope, filters, booleanFilter, and an explicit sharedTo |
objects/<Object>/compactLayouts/*.compactLayout-meta.xml plus assignments | Compact layouts and the compactLayoutAssignment lines that make them render |
| Checker output | ERROR / WARN / INFO lines from scripts/check_list_views_and_compact_layouts.py on the source tree |
Reference Files
| File | Read it when |
|---|
references/metadata-examples.md | Writing deployable ListView, CompactLayout, and searchLayouts XML, the package.xml for them, and the post-deploy ListView query |
references/gotchas.md | A view or layout deployed cleanly and still behaves wrong, or a retrieve keeps producing a diff nobody wrote |
references/examples.md | Designing the working set for a persona before any XML exists — queue triage and a mobile compact layout, end to end |
references/well-architected.md | Justifying the governance tradeoff between user freedom and view sprawl, and locating the official sources behind each claim |
references/llm-anti-patterns.md | Reviewing output an AI assistant produced in this domain, especially "edit the page layout to change the highlights panel" |
templates/list-views-and-compact-layouts-template.md | Running the inventory in workflow step 2 |
Related Skills
admin/record-types-and-page-layouts - use when the real design issue is record type separation, page layouts, or Dynamic Forms; record types are also where compactLayoutAssignment is set per type.admin/queues-and-public-groups - use when a filterScope = Queue view or a sharedTo group has to exist before the view deploys; its references/queue-behaviour-matrix.md covers the auto-created queue list view.admin/scoping-rules - use when the view uses filterScope = ScopingRule and the rule only applies once the user picks Filter by scope.admin/dynamic-forms-and-actions - use when the ask is really about the record detail region rather than the highlights panel above it.admin/lightning-page-performance-tuning - use when the record page is slow to render rather than hard to scan.admin/reports-and-dashboards - use when the team needs analytics, summarization, or scheduled reporting rather than operational list navigation.lwc/lwc-data-table - use when a custom component is replacing standard list experiences and needs deliberate column and action design.