Workspaces and shells

Master/detail workspace

<forma-master-detail>

List-and-detail composition that collapses cleanly from multi-pane desktop to mobile navigation.

Authoring tag
<forma-master-detail>
Behavior owner
Application / Limen
Canonical source
patterns/master-detail.html

Purpose

A master/detail workspace shows a list of records beside the full detail of one selected record. The list is a nav of real links, so selecting a record is navigation to a URL the application owns, and the current record is marked with aria-current="page". Forma draws the two-column frame, the selected-row cue and the narrow-screen recomposition into a horizontal record switcher above the detail. Selection, routing, browser history, loading and focus restoration are application or Limen behavior.

Use when

  • Users move between many records of one kind and need the list in view while reading or acting on one, such as invoices, tickets or cases.
  • Each record has a stable URL, so the selected record can be deep-linked, bookmarked and restored with Back.
  • The detail is substantial enough to deserve its own region, not just an expanded row.

Avoid when

  • The records need column comparison, sorting or bulk selection: use Data grid and open detail on its own page or in a Flyout.
  • Items are a short work list with inline actions: use Work queue.
  • Two regions are related but neither is a list of records: use Split pane.
  • The detail is short enough to reveal inline: use Disclosure rows.

Behavior to know

  • Each list row is a link at least 3.5rem tall with a bold identifier and a secondary line.
  • The selected row gets a thick inline-start bar and a filled background, so the cue is shape plus color, not color alone.
  • At 40rem and below the list becomes a horizontally scrolling row of 12rem cards above the detail; the detail stays in the page flow.

Basic example

The smallest correct markup: the canonical pattern from patterns/master-detail.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal master/detail workspace

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Overdue

INV-1042

Customer
Acme Manufacturing
Outstanding
$5,000
Due
October 4, 2026
HTML · Minimal master/detail workspace Raw HTML for HTML · Minimal master/detail workspace
<forma-master-detail class="forma-component-tag">
<section class="forma-master-detail" aria-label="Record workspace">
  <nav class="forma-master-detail__master" aria-label="Records">
    <a href="#record-1" aria-current="page"><strong>INV-1042</strong><span>Acme Manufacturing</span></a>
    <a href="#record-2"><strong>INV-1043</strong><span>Northstar Labs</span></a>
    <a href="#record-3"><strong>INV-1044</strong><span>Atlas Works</span></a>
  </nav>
  <article class="forma-master-detail__detail" id="record-1">
    <span class="forma-status-lozenge" data-state="attention">Overdue</span>
    <h3>INV-1042</h3>
    <dl class="forma-key-value-list">
      <div><dt>Customer</dt><dd>Acme Manufacturing</dd></div>
      <div><dt>Outstanding</dt><dd>$5,000</dd></div>
      <div><dt>Due</dt><dd>October 4, 2026</dd></div>
    </dl>
  </article>
</section>
</forma-master-detail>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

No record selected

The first visit to the list before any record is chosen. No row carries aria-current, and the detail region says what to do instead of showing stale data from a previous record.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

No case selected

Choose a case from the list to see the customer, history and next steps.

HTML · No record selected Raw HTML for HTML · No record selected
<forma-master-detail class="forma-component-tag">
  <section class="forma-master-detail" aria-label="Open support cases">
    <nav class="forma-master-detail__master" aria-label="Cases">
      <a href="#master-detail-nothing-selected-4410"><strong>CASE-4410</strong><span>Login loop after SSO change</span></a>
      <a href="#master-detail-nothing-selected-4407"><strong>CASE-4407</strong><span>Refund not received</span></a>
      <a href="#master-detail-nothing-selected-4399"><strong>CASE-4399</strong><span>Export missing columns</span></a>
    </nav>
    <section class="forma-master-detail__detail" aria-labelledby="master-detail-nothing-selected-title">
      <h3 id="master-detail-nothing-selected-title">No case selected</h3>
      <p>Choose a case from the list to see the customer, history and next steps.</p>
    </section>
  </section>
</forma-master-detail>

Click or tap the code once to select all of it, then copy.

Scenario

Blocked record with long names

A selected record in a blocked state, with long customer names wrapping inside the list rows. Status is a text lozenge with a symbol, and the only legal action shown is the one the application allows.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Blocked

PO-7782

Supplier
Hanseatische Maschinenbau- und Anlagentechnik GmbH
Blocked by
Missing tax certificate
Amount
€48,200.00

HTML · Blocked record with long names Raw HTML for HTML · Blocked record with long names
<forma-master-detail class="forma-component-tag">
  <section class="forma-master-detail" aria-label="Purchase orders">
    <nav class="forma-master-detail__master" aria-label="Purchase orders list">
      <a href="#master-detail-blocked-record-7781"><strong>PO-7781</strong><span>Consolidated Freight &amp; Warehousing Partners (EMEA)</span></a>
      <a href="#master-detail-blocked-record-7782" aria-current="page"><strong>PO-7782</strong><span>Hanseatische Maschinenbau- und Anlagentechnik GmbH</span></a>
      <a href="#master-detail-blocked-record-7790"><strong>PO-7790</strong><span>Blue Harbor Co.</span></a>
    </nav>
    <article class="forma-master-detail__detail" id="master-detail-blocked-record-7782" aria-labelledby="master-detail-blocked-record-title">
      <span class="forma-status-lozenge" data-state="blocked">Blocked</span>
      <h3 id="master-detail-blocked-record-title">PO-7782</h3>
      <dl class="forma-key-value-list">
        <div><dt>Supplier</dt><dd>Hanseatische Maschinenbau- und Anlagentechnik GmbH</dd></div>
        <div><dt>Blocked by</dt><dd>Missing tax certificate</dd></div>
        <div><dt>Amount</dt><dd>€48,200.00</dd></div>
      </dl>
      <p><button type="button">Request certificate</button></p>
    </article>
  </section>
</forma-master-detail>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile record switcher

At phone width the list becomes a horizontal switcher above the detail, and the selected record's detail follows directly underneath.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 40rem and below the grid becomes one column; the list turns into a horizontal row of 12rem-wide links that scrolls inside itself, so the page never scrolls sideways at 320px.
  • Rows keep their 3.5rem minimum block size, which exceeds the 44px touch target, and the selected row keeps its thick bar.
  • Only part of the list is visible at once; the application should scroll the selected link into view and keep the URL as the source of truth so rotation or reload restores the same record.
  • Long lists are awkward to scroll horizontally. For more than a handful of records, navigate to a separate list page on phones and use Back to return.
HTML · Mobile record switcher Raw HTML for HTML · Mobile record switcher
<forma-master-detail class="forma-component-tag">
  <section class="forma-master-detail" aria-label="Field visits">
    <nav class="forma-master-detail__master" aria-label="Visits">
      <a href="#master-detail-mobile-v12" aria-current="page"><strong>Visit 12</strong><span>Pump station 4</span></a>
      <a href="#master-detail-mobile-v13"><strong>Visit 13</strong><span>North reservoir</span></a>
      <a href="#master-detail-mobile-v14"><strong>Visit 14</strong><span>Valve house B</span></a>
    </nav>
    <article class="forma-master-detail__detail" id="master-detail-mobile-v12" aria-labelledby="master-detail-mobile-title">
      <span class="forma-status-lozenge" data-state="ok">Complete</span>
      <h3 id="master-detail-mobile-title">Visit 12</h3>
      <dl class="forma-key-value-list">
        <div><dt>Site</dt><dd>Pump station 4</dd></div>
        <div><dt>Inspector</dt><dd>Daniel Okafor</dd></div>
      </dl>
    </article>
  </section>
</forma-master-detail>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelsection, navstring—Names the workspace and the record list so the list landmark is distinguishable from site navigation.
aria-currentlist linkpageabsentMarks the selected record and draws the selected-row cue. Set by the application when the route changes.
hreflist linkrecord URL—Each record is a real link so it can be opened, bookmarked and restored with browser history.
iddetailstring—Optional fragment target for the selected record.
aria-labelledbydetailid of the detail heading—Names the detail region by its record heading.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-master-detailBlock class—Root two-column grid with a border and a 22rem minimum height.
.forma-master-detail__detailElement class—The selected record region. Padded and allowed to shrink.
.forma-master-detail__masterElement class—The record list, normally a nav of links. Each direct link is a row; a span inside it is the secondary line.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the record links, then into the detail. Native link behavior.
EnterFollows the record link. The application loads the record and decides where focus goes.

Form behavior

Not a form control.

States

Master/detail workspace states
StateHow it is expressedPresentation
Selected recordaria-current="page" on the list linkThick inline-start accent bar and filled row background.
Nothing selectedno link with aria-currentAll rows neutral; the detail region should explain what to do.
Two columnsviewport wider than 40remList column minmax(12rem, 0.4fr) beside the detail.
Stacked switcher@media (max-width: 40rem)List becomes a horizontal scrolling row above the detail.

Accessibility

Forma provides

  • Renders the selected row with a non-color cue (a 0.35rem bar) in addition to the background fill.
  • Keeps list rows at least 3.5rem tall at every width.
  • Recomposes at narrow widths without reordering the list and detail in the DOM.

Your application supplies

  • Use links with real URLs for records and keep aria-current in sync with the route.
  • After selection, move focus to the detail heading only when the user expects it (for example on phones, where the detail is below the list), and restore focus to the selected row on Back.
  • Announce loading and failure of the detail as text, for example with Skeleton or Operation status.
  • Give the list nav a name that differs from other navigation on the page.

Responsive behavior

  • Wide: list column minmax(12rem, 0.4fr) and a minmax(0, 1fr) detail column.
  • At 40rem and below: a single column; the list becomes a flex row of 12rem links with overflow-x: auto inside its own box, bordered below instead of beside.
  • Detail content shrinks with min-inline-size: 0; long values wrap in Key-value list.
  • The root keeps a 22rem minimum height so an empty detail does not collapse the workspace.

Motion

  • No animation: the selected-row cue changes instantly when aria-current moves, and the breakpoint recomposition is not transitioned. Any detail transition is application-owned and must respect reduced motion.

Usage guidance

Do

  • Show a short identifier and one distinguishing line in each row so records can be told apart without opening them.
  • Keep the detail's status as text with a symbol, using Status lozenge.

Avoid

  • Using buttons that change the detail without changing the URL; selection then cannot be shared or restored.
  • Hiding the list entirely on phones without a clear way back to it.
  • Putting row actions inside the list links; interactive content cannot be nested in a link.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.