Feedback and status

Obligation panel

<forma-obligation-panel>

Presents unresolved work, evidence needs and blocking status without making the design system authoritative.

Authoring tag
<forma-obligation-panel>
Behavior owner
Application state
Canonical source
patterns/obligation-panel.html

Purpose

An obligation panel lists work that must be resolved before something can be finalized: reconciliations, missing evidence, stale aggregates. Forma renders a bordered panel with a header (heading, explanation and a count), and a list of obligations. Each obligation has a textual status label, a title with a description, and a link or action to resolve it; data-forma-severity adds a matching border treatment. Ordo or the application decides which obligations exist, their severity, and when they are discharged.

Use when

  • A record or process has outstanding obligations that block or qualify finalization.
  • Blocking and non-blocking work must be distinguished in text and structure.
  • Each obligation has a recovery or evidence action that the application provides.

Avoid when

Behavior to know

  • Severity is written in each status label (Blocking, Required, Evidence) and repeated by border: accent for blocking, double for warning, secondary accent for information.
  • The header count is aria-hidden because the heading already states the number.
  • Unknown or unreconciled work can be listed as its own obligation with its own wording.

Basic example

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

Canonical

Minimal obligation panel

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.

HTML · Minimal obligation panel Raw HTML for HTML · Minimal obligation panel
<forma-obligation-panel class="forma-component-tag">
<aside class="forma-obligation-panel" aria-labelledby="obligation-panel-title">
  <header class="forma-obligation-panel__header">
    <div>
      <h2 id="obligation-panel-title">3 obligations require attention</h2>
      <p>These must be resolved before finalization.</p>
    </div>
    <span class="forma-obligation-panel__count" aria-hidden="true">3</span>
  </header>

  <ul class="forma-obligation-list">
    <li class="forma-obligation" data-forma-severity="blocking">
      <span class="forma-obligation__status">Blocking</span>
      <div>
        <strong>Reconcile unknown storage outcome</strong>
        <p>Verify whether the report snapshot write completed before retrying.</p>
      </div>
      <a href="#reconcile-storage">Review</a>
    </li>
    <li class="forma-obligation" data-forma-severity="warning">
      <span class="forma-obligation__status">Required</span>
      <div>
        <strong>Rebuild stale aggregate</strong>
        <p>The current aggregate does not include every accepted contribution.</p>
      </div>
      <a href="#aggregate-health">Review</a>
    </li>
    <li class="forma-obligation" data-forma-severity="information">
      <span class="forma-obligation__status">Evidence</span>
      <div>
        <strong>Supply publication evidence</strong>
        <p>A required validation fixture has not yet been recorded.</p>
      </div>
      <a href="#publication-evidence">Review</a>
    </li>
  </ul>
</aside>
</forma-obligation-panel>

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

Examples

Scenario

One blocking obligation

A single obligation that blocks publication. The heading and count agree, and the action is a button because it starts work in place rather than navigating.

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.

HTML · One blocking obligation Raw HTML for HTML · One blocking obligation
<forma-obligation-panel class="forma-component-tag">
  <aside class="forma-obligation-panel" aria-labelledby="obligation-panel-single-blocking-title">
    <header class="forma-obligation-panel__header">
      <div>
        <h2 id="obligation-panel-single-blocking-title">1 obligation blocks publication</h2>
        <p>Resolve it before the quarterly report can be published.</p>
      </div>
      <span class="forma-obligation-panel__count" aria-hidden="true">1</span>
    </header>
    <ul class="forma-obligation-list">
      <li class="forma-obligation" data-forma-severity="blocking">
        <span class="forma-obligation__status">Blocking</span>
        <div>
          <strong>Confirm the Q3 revenue restatement</strong>
          <p>Finance restated September revenue after the draft was prepared. The report still shows the earlier figure.</p>
        </div>
        <button type="button">Review restatement</button>
      </li>
    </ul>
  </aside>
</forma-obligation-panel>

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

Scenario

Unreconciled and evidence obligations

An unknown storage outcome listed as its own obligation without a severity attribute, so it keeps the neutral border, next to an evidence request. The status labels say exactly what kind of work each is.

Live demo. 2 native actions work here and are verified by an outcome test.

HTML · Unreconciled and evidence obligations Raw HTML for HTML · Unreconciled and evidence obligations
<forma-obligation-panel class="forma-component-tag">
  <aside class="forma-obligation-panel" aria-labelledby="obligation-panel-unknown-and-evidence-title">
    <header class="forma-obligation-panel__header">
      <div>
        <h2 id="obligation-panel-unknown-and-evidence-title">2 obligations are open</h2>
        <p>Neither blocks saving. Both must be resolved before final sign-off.</p>
      </div>
      <span class="forma-obligation-panel__count" aria-hidden="true">2</span>
    </header>
    <ul class="forma-obligation-list">
      <li class="forma-obligation">
        <span class="forma-obligation__status">Unknown</span>
        <div>
          <strong>Confirm whether the archive copy was written</strong>
          <p>The storage service did not acknowledge the write. It may or may not exist.</p>
        </div>
        <a href="#obligation-panel-unknown-and-evidence-title">Check archive</a>
      </li>
      <li class="forma-obligation" data-forma-severity="information">
        <span class="forma-obligation__status">Evidence</span>
        <div>
          <strong>Attach the signed vendor attestation</strong>
          <p>An unsigned draft is on file. The policy requires the signed copy.</p>
        </div>
        <a href="#obligation-panel-unknown-and-evidence-title">Upload</a>
      </li>
    </ul>
  </aside>
</forma-obligation-panel>

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 finalization

Three obligations of different severity at phone width.

Live demo. 3 native actions work here and are verified by an outcome test.

Viewport width

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

What changes at narrow widths

  • Below 44rem the header stacks: heading and explanation first, then the count.
  • Each obligation becomes a single column: status label, then title and description, then the action link.
  • The status label stays left-aligned at its own width instead of stretching.
  • Severity borders stay on the inline-start edge at every width; nothing scrolls horizontally at 320px.
HTML · Mobile finalization Raw HTML for HTML · Mobile finalization
<forma-obligation-panel class="forma-component-tag">
  <aside class="forma-obligation-panel" aria-labelledby="obligation-panel-mobile-finalization-title">
    <header class="forma-obligation-panel__header">
      <div>
        <h2 id="obligation-panel-mobile-finalization-title">3 obligations before finalizing</h2>
        <p>The assessment cannot be finalized until blocking items are resolved.</p>
      </div>
      <span class="forma-obligation-panel__count" aria-hidden="true">3</span>
    </header>
    <ul class="forma-obligation-list">
      <li class="forma-obligation" data-forma-severity="blocking">
        <span class="forma-obligation__status">Blocking</span>
        <div>
          <strong>Answer the required encryption question</strong>
          <p>Question 12 has no response.</p>
        </div>
        <a href="#obligation-panel-mobile-finalization-title">Go to question</a>
      </li>
      <li class="forma-obligation" data-forma-severity="warning">
        <span class="forma-obligation__status">Required</span>
        <div>
          <strong>Explain the exception for legacy systems</strong>
          <p>An exception was recorded without a justification.</p>
        </div>
        <a href="#obligation-panel-mobile-finalization-title">Add justification</a>
      </li>
      <li class="forma-obligation" data-forma-severity="information">
        <span class="forma-obligation__status">Evidence</span>
        <div>
          <strong>Attach the latest penetration test summary</strong>
          <p>The attached summary is from last year.</p>
        </div>
        <a href="#obligation-panel-mobile-finalization-title">Upload</a>
      </li>
    </ul>
  </aside>
</forma-obligation-panel>

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-labelledbyaside.forma-obligation-panelid of the panel heading—Names the complementary region.
aria-hidden.forma-obligation-panel__counttrue—Hides the visual count, which duplicates the number in the heading.
data-forma-severityli.forma-obligationblocking | warning | informationabsent (neutral border)Border treatment matching the written status label. Presentation only; Ordo owns severity.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-obligation-panelBlock class—Root panel with a functional border and primary surface.
.forma-obligation-panel__countElement class—Inverse-surface square showing the number of obligations. Decorative duplicate of the heading.
.forma-obligation-panel__headerElement class—Flex header: heading and explanation at the start, count at the end. Stacks below 44rem.
.forma-obligationBlock class—One obligation: grid of status label, content and action, with a 4px inline-start border. Single column below 44rem.
.forma-obligation__statusElement class—Bordered uppercase monospace label naming the obligation's severity or type.
[data-forma-severity]Attribute hook"blocking", "information", "warning"blocking uses the primary accent border; warning a double border; information the secondary accent. Absent keeps the neutral functional border.
.forma-obligation-listBlock class—Unstyled list of obligations.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through each obligation's link or button. The panel itself is not focusable.
EnterFollows a link or activates a button (Space also activates buttons).
Events
EventDescription
clickNative click on obligation actions. The application handles navigation or the resolving action.

Form behavior

Not a form control.

States

Obligation panel states
StateHow it is expressedPresentation
Blockingdata-forma-severity="blocking" and a Blocking labelPrimary accent border; must be resolved before finalization.
Warning / requireddata-forma-severity="warning"Double border; required but not blocking the current step.
Information / evidencedata-forma-severity="information"Secondary accent border; evidence or informational work.
Unclassified / unknownno data-forma-severityNeutral border. Use for unreconciled work whose severity the authority has not assigned.

Accessibility

Forma provides

  • Requires severity in text (the status label) and repeats it with border style, so it is not communicated by color alone.
  • In forced colors every obligation border becomes CanvasText and the panel border is preserved; the labels still distinguish severity.
  • Uses a labelled complementary region and a native list.

Your application supplies

  • Keep the heading's number, the count and the list in sync.
  • Write status labels that name the kind of obligation, and match data-forma-severity to them.
  • Remove an obligation only when the authority reports it discharged.
  • If the panel is inside main, consider a section instead of aside so it is not presented as tangential content.

Responsive behavior

  • Obligations are auto minmax(0, 1fr) auto grids on wide screens; below 44rem they become one column.
  • The header is a flex row on wide screens and a column below 44rem.
  • Titles and descriptions wrap; the status label has a 5.5rem minimum width.

Motion

  • No animation: obligations appear and disappear with the application's re-render.

Usage guidance

Do

  • Order obligations by the authority's priority, typically blocking first.
  • Give each obligation one clear action that leads to its resolution.

Avoid

  • Deriving severity from position or color in the UI.
  • Hiding unknown or unreconciled work because it has no severity yet.

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.