Workflow and diagrams

Spatial canvas

<forma-spatial-canvas>

Provides a bounded spatial exploration surface with orientation and a non-spatial access path.

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

Purpose

A spatial canvas frames a surface that is larger than the screen, such as a system map, floor plan or board of related objects, inside a bounded, keyboard-scrollable viewport. Around it Forma places three things spatial views usually lack: a text orientation line that says what part of the space is in view, a control area for application-owned view actions (zoom, reset), and a native details index that lists the objects in view as ordinary links. Zoom level, panning, selection and what counts as "in view" belong to the application or Limen; Forma only draws the frame and keeps a non-spatial path to every object.

Use when

  • Relationships between objects are easier to understand in space, but the space does not fit on screen.
  • Users need to know where they are in a larger map and get back to a known view.
  • Every object on the surface must also be reachable without panning, for keyboard, screen-reader and phone users.

Avoid when

Behavior to know

  • The viewport is a focusable, bordered scroll region with an 18rem minimum height and a visible focus outline.
  • The surface is at least 48rem by 28rem and lays objects out in a three-column grid; it is not a coordinate system.
  • The object index is a native disclosure with a 2.75rem summary and a wrapping list of links.
  • Orientation is plain text, so scope never depends on reading position or size.

Basic example

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

Canonical

Minimal spatial canvas

Rendered from the canonical pattern file.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

System map

Viewport: services / billing

Billing

Selected node

Chrona

Time source

Objects in this view
HTML · Minimal spatial canvas Raw HTML for HTML · Minimal spatial canvas
<forma-spatial-canvas class="forma-component-tag">
<section class="forma-spatial-canvas" aria-labelledby="canvas-title">
  <header class="forma-spatial-canvas__header">
    <div><h2 id="canvas-title">System map</h2><p class="forma-spatial-canvas__orientation">Viewport: services / billing</p></div>
    <div class="forma-cluster" aria-label="Canvas controls"><button type="button">Zoom out</button><button type="button">Reset view</button><button type="button">Zoom in</button></div>
  </header>
  <div class="forma-spatial-canvas__viewport" tabindex="0" aria-label="Scrollable system map">
    <div class="forma-spatial-canvas__surface">
      <article class="forma-surface" id="billing"><h3>Billing</h3><p>Selected node</p></article>
      <article class="forma-surface" id="chrona"><h3>Chrona</h3><p>Time source</p></article>
    </div>
  </div>
  <details class="forma-spatial-canvas__index"><summary>Objects in this view</summary><nav aria-label="Canvas objects"><a href="#billing">Billing</a><a href="#chrona">Chrona</a></nav></details>
</section>
</forma-spatial-canvas>

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

Examples

Scenario

Scoped view with a scope trail

A facilities map zoomed into one floor. A Scope trail shows ancestry, the orientation line states zoom and region in words, the view controls are grouped and named, and the index is open so every desk in view is one link away.

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.

Floor 3 desks

Zoom: floor level · showing east wing

C-301

Available

C-302

Booked · Priya Raman

C-303

Out of service

Desks in this view (3)
HTML · Scoped view with a scope trail Raw HTML for HTML · Scoped view with a scope trail
<forma-spatial-canvas class="forma-component-tag">
  <section class="forma-spatial-canvas" aria-labelledby="spatial-canvas-floor-plan-scope-title">
    <header class="forma-spatial-canvas__header">
      <div>
        <nav class="forma-scope-trail" aria-label="Map scope"><ol><li><a href="#spatial-canvas-floor-plan-scope-campus">Campus</a></li><li><a href="#spatial-canvas-floor-plan-scope-building">Building C</a></li><li aria-current="page">Floor 3</li></ol></nav>
        <h2 id="spatial-canvas-floor-plan-scope-title">Floor 3 desks</h2>
        <p class="forma-spatial-canvas__orientation">Zoom: floor level · showing east wing</p>
      </div>
      <div class="forma-cluster" role="group" aria-label="Map view controls"><button type="button">Zoom out to building</button><button type="button">Reset view</button></div>
    </header>
    <div class="forma-spatial-canvas__viewport" tabindex="0" role="group" aria-label="Floor 3 map, scrollable">
      <div class="forma-spatial-canvas__surface">
        <article class="forma-surface" id="spatial-canvas-floor-plan-scope-c301"><h3>C-301</h3><p>Available</p></article>
        <article class="forma-surface" id="spatial-canvas-floor-plan-scope-c302"><h3>C-302</h3><p>Booked · Priya Raman</p></article>
        <article class="forma-surface" id="spatial-canvas-floor-plan-scope-c303"><h3>C-303</h3><p>Out of service</p></article>
      </div>
    </div>
    <details class="forma-spatial-canvas__index" open>
      <summary>Desks in this view (3)</summary>
      <nav aria-label="Desks in view"><a href="#spatial-canvas-floor-plan-scope-c301">C-301</a><a href="#spatial-canvas-floor-plan-scope-c302">C-302</a><a href="#spatial-canvas-floor-plan-scope-c303">C-303</a></nav>
    </details>
  </section>
</forma-spatial-canvas>

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

Scenario

Empty region

The user has panned to an area with no objects. The orientation line says so in text and offers a way back, so the empty surface is not mistaken for a loading failure; the index states that nothing is in view.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Service map

Viewport: north-west edge · no services in view

Objects in this view (0)

Nothing here. Use Reset view to return to the billing cluster.

HTML · Empty region Raw HTML for HTML · Empty region
<forma-spatial-canvas class="forma-component-tag">
  <section class="forma-spatial-canvas" aria-labelledby="spatial-canvas-empty-region-title">
    <header class="forma-spatial-canvas__header">
      <div><h2 id="spatial-canvas-empty-region-title">Service map</h2><p class="forma-spatial-canvas__orientation">Viewport: north-west edge · no services in view</p></div>
      <div class="forma-cluster" role="group" aria-label="Service map controls"><button type="button">Reset view</button></div>
    </header>
    <div class="forma-spatial-canvas__viewport" tabindex="0" role="group" aria-label="Service map, scrollable">
      <div class="forma-spatial-canvas__surface"></div>
    </div>
    <details class="forma-spatial-canvas__index">
      <summary>Objects in this view (0)</summary>
      <p>Nothing here. Use Reset view to return to the billing cluster.</p>
    </details>
  </section>
</forma-spatial-canvas>

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 map with object index

At phone width the surface scrolls inside its viewport and the index is the practical way to reach objects.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. 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

  • The surface keeps its 48rem minimum width and scrolls inside .forma-spatial-canvas__viewport; the page does not scroll sideways at 320px.
  • The header wraps: title and orientation above, controls below, each button at the 2.75rem base height.
  • The object index summary is a 2.75rem touch target and its links wrap, so every object is reachable without panning.
  • Panning with touch scrolls the viewport; there is no pinch-zoom behavior unless the application provides it, so offer zoom as buttons.
HTML · Mobile map with object index Raw HTML for HTML · Mobile map with object index
<forma-spatial-canvas class="forma-component-tag">
  <section class="forma-spatial-canvas" aria-labelledby="spatial-canvas-mobile-title">
    <header class="forma-spatial-canvas__header">
      <div><h2 id="spatial-canvas-mobile-title">Warehouse zones</h2><p class="forma-spatial-canvas__orientation">Viewport: dock side</p></div>
      <div class="forma-cluster" role="group" aria-label="Zone map controls"><button type="button">Zoom out</button><button type="button">Zoom in</button></div>
    </header>
    <div class="forma-spatial-canvas__viewport" tabindex="0" role="group" aria-label="Warehouse zone map, scrollable">
      <div class="forma-spatial-canvas__surface">
        <article class="forma-surface" id="spatial-canvas-mobile-dock"><h3>Dock A</h3><p>2 trucks unloading</p></article>
        <article class="forma-surface" id="spatial-canvas-mobile-cold"><h3>Cold store</h3><p>At capacity</p></article>
      </div>
    </div>
    <details class="forma-spatial-canvas__index">
      <summary>Zones in this view</summary>
      <nav aria-label="Zones in view"><a href="#spatial-canvas-mobile-dock">Dock A</a><a href="#spatial-canvas-mobile-cold">Cold store</a></nav>
    </details>
  </section>
</forma-spatial-canvas>

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 buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. 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
tabindex.forma-spatial-canvas__viewport0—Makes the scroll region focusable so it can be scrolled from the keyboard.
roleviewport, control clustergroup—Gives the viewport and the control area a role so their accessible names are announced.
aria-labelviewport, controls, index navstring—Names the scroll region (say that it scrolls), the view controls and the object index.
aria-labelledbyroot sectionid of the canvas heading—Names the whole canvas region.
opendetails.forma-spatial-canvas__indexbooleanabsentInitial open state of the object index. The browser owns it afterwards.
aria-currentscope trail itempage—Marks the current scope when a Scope trail is composed in the header.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-spatial-canvasBlock class—Root grid: header, viewport, index, with a small gap. Shrinks to its container.
.forma-spatial-canvas__headerElement class—Wrapping flex row with the title and orientation on one side and view controls on the other.
.forma-spatial-canvas__indexElement class—A native details listing the objects in view; its summary is a 2.75rem target and its nav links wrap.
.forma-spatial-canvas__orientationElement class—Text line stating current scope, zoom or region.
.forma-spatial-canvas__surfaceElement class—The large surface: at least 48rem by 28rem, a three-column grid of objects with generous gaps.
.forma-spatial-canvas__viewportElement class—Bordered, focusable scroll region with an 18rem minimum height and a 2px focus outline.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through view controls, the viewport, links or controls inside objects, then the index summary and links.
Arrow keys, Page Up / Page Down (viewport focused)Scrolls the surface. Native scrolling of a focused overflow region.
Enter / Space on the index summaryOpens or closes the object index. Native details behavior.
Zoom and reset shortcutsNot provided. The view buttons are native buttons; their effect and any shortcuts are application or Limen behavior.
Events
EventDescription
toggleNative event from the index details element.
scrollNative scroll event from the viewport, which the application can use to update the orientation line and index.

Form behavior

Not a form control.

States

Spatial canvas states
StateHow it is expressedPresentation
Scopetext in .forma-spatial-canvas__orientationApplication-written description of what is in view.
Viewport focus:focus-visible on the viewport2px outline in the current text color, offset from the border.
Index opendetails[open]The list of objects in view is shown below the viewport.
Empty viewno objects on the surfaceThe application states in text that nothing is in view and how to return.

Accessibility

Forma provides

  • Provides a keyboard-focusable scroll region with a visible focus outline.
  • Provides a non-spatial object index with a 44px disclosure target so objects are reachable without panning.
  • Gives orientation a dedicated text element rather than relying on position or size.
  • Contains horizontal overflow inside the viewport so the page does not scroll sideways.

Your application supplies

  • Keep the orientation text and the index in sync with the current view.
  • Give every object a stable id or URL and link to it from the index.
  • Provide zoom and reset as buttons, never only as gestures or wheel input, and label the control group with role="group" and a name.
  • When a view change moves focus or selection, do it predictably and announce the new scope.
  • Offer a non-spatial representation, such as a Relationship index, when the spatial view is not sufficient for verification.

Responsive behavior

  • The root and viewport shrink to their container; the surface keeps its 48rem by 28rem minimum and scrolls inside the viewport.
  • The header wraps, placing controls below the title on narrow screens.
  • Index links wrap onto several lines.
  • No breakpoints: the same structure is used at every width, with the index becoming the primary path on phones.

Motion

  • No animation: scrolling is native and the index opens without transition. Any animated zoom or pan is application behavior and must respect prefers-reduced-motion.

Usage guidance

Do

  • Write orientation in the user's terms ("Floor 3 · east wing"), not in coordinates.
  • Keep a Reset view action so users can recover from getting lost.

Avoid

  • Making zoom level or position carry domain meaning.
  • Hiding objects that are off-screen from the index when they are part of the current scope.

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.