> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Record Experiences

> Design stage-specific layouts and list views, then verify the deployed experience in a browser.

<Warning>
  **Limited Release.** The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you're on the latest EDK version before starting new projects.
</Warning>

Design the work a person must complete before deciding which fields or sections to show. A record experience should make the current responsibility, decision, and next action clear without hiding supporting evidence.

The commands below assume the organization workspace selects one matching saved profile. See [Authentication](/edk/authentication) if the target is ambiguous.

Use the `/elementum-design` coding-agent playbook when you want an assistant to apply this workflow. See [Playbooks](/edk/playbooks).

## Map the Process

Create a stage matrix before editing the App. For each materially different stage, answer:

* **Persona:** Who is responsible at this stage?
* **Primary job:** What single outcome must that person produce?
* **Decision:** What must they understand or decide?
* **Required inputs:** What must they review or edit now?
* **Evidence:** What supports the decision?
* **Primary action:** What advances or closes the work?
* **Failure path:** What blocks, rejects, or returns the work?

Two stages can usually share a layout when they have the same persona, decision, required fields, and action. A separate layout is useful when the person's job changes, not merely when the same field list can be reordered.

Common stage needs include:

* **Intake:** scope, requester, ownership, category, and completeness.
* **Assessment:** context, risk factors, evidence sufficiency, and rationale.
* **Remediation:** open findings, owners, dates, plans, and exceptions.
* **Approval:** decision summary, material findings, residual risk, and approval notes.
* **Monitoring or completion:** outcome, ownership, health indicators, and next review.

Keep distinct outcomes such as completed, rejected, cancelled, and retired. Collapsing them into one closed state removes information that later reporting and automation may need.

## Build an Information Hierarchy

Order each stage around the current job:

1. **Orientation:** the few facts needed to identify the record and understand its risk.
2. **Work area:** the fields the current persona must review or change.
3. **Decision and action:** the primary outcome and any required confirmation.
4. **Evidence:** attachments, relationships, findings, approvals, and source material.
5. **History:** activity and audit details, available but visually secondary.

Do not duplicate the title, status, stage, owner, or actions already supplied by the native record header. Prefer one clearly labeled primary action for each stage. Use text labels and status information rather than color alone.

The first viewport should answer three questions: What is this record? What matters now? What should I do next?

## Author Layouts and List Views

Pull the current App before changing its record experience:

```bash theme={null}
elementum pull app <namespace>
```

Preserve unrelated `layouts`, `listViews`, and `viewOrder` entries from the pulled source.

Use `layouts` to define ordered sections for each stage. Keep fields that support the current task in the main work area, and place evidence or history in supporting sections. Preserve platform-owned sections already present in the source.

Use `listViews` for repeatable record-finding tasks and `viewOrder` for navigation order. A useful list view normally includes:

* A record identifier.
* Current status or stage.
* Ownership, urgency, or risk.
* One or two fields needed to prioritize the next action.

Choose columns for scanning, not for reproducing the entire record. Preserve pulled filters and sorts rather than inventing their configuration.

<Warning>
  Changing an existing stage layout may replace that layout. Run a plan and review the replacement before applying it.
</Warning>

## Review Before Deployment

Validate the complete organization workspace:

```bash theme={null}
npx tsc --noEmit
elementum plan
```

`plan` builds the current source automatically. Review layout replacement, list-view changes, ordering, and any unrelated removals. Apply only after the plan is approved.

## Verify in a Browser

Typechecking and a clean plan do not prove that a user-visible design works. After applying the approved change, open deployed records in an authenticated browser.

Prepare uniquely named test records for:

1. A normal record with representative values.
2. A risk or exception record with important warnings.
3. A sparse record with optional values empty.
4. A record with long text and many related items.
5. A later stage with a materially different layout.

For each applicable stage, verify:

* Loading, empty, normal, exceptional, and long-content states.
* Read, edit, invalid, corrected, saved, and discarded field states.
* Expanded and collapsed supporting sections.
* Enabled, disabled, confirmation, cancelled, successful, and rejected actions.
* Wide desktop, normal desktop, and reduced content widths.
* Keyboard order, visible focus, labels, required fields, validation messages, and dialog behavior.

Wait for picklists, conditional content, and platform-owned blocks to finish loading before judging the result. Check for clipping, overlap, nested scrolling, unreachable content, and actions that lose context at narrower widths.

Capture only the states needed to demonstrate the final behavior. Revise the TypeScript, repeat typecheck, plan, and apply review, then reload the same records and retest affected states.

## Design Acceptance Criteria

A record experience is ready when:

* Each stage shows only information relevant to the current job.
* The first viewport establishes identity, priority, and next action.
* The primary action is obvious and labels its outcome.
* Evidence and history remain accessible without dominating the work area.
* Sparse, exceptional, and long records preserve the intended hierarchy.
* List views support scanning and prioritization.
* Content remains reachable at tested widths.
* Keyboard interaction and visible validation remain usable.
* Browser evidence demonstrates the deployed behavior.