Assessment and survey

Ranking

<forma-ranking>

Ordered-choice presentation with non-drag movement controls and visible positions.

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

Purpose

Ranking shows items in an ordered list with a visible position number and Move up / Move down buttons on each row. Forma supplies the visual contract only: the list, the position badges, 44px move buttons, and a visually hidden live region for announcements. The application (Limen) owns reordering: it moves the item in the DOM, renumbers positions, disables moves that are not possible at the ends, keeps focus on the moved control, and writes an announcement. Drag-and-drop may be layered on, but the buttons must always remain.

Use when

  • Users must put every item in a complete order of preference or priority.
  • The list is short enough to reorder with buttons (typically up to about eight items).
  • A keyboard- and touch-operable path to reorder is required, with or without drag.

Avoid when

Behavior to know

  • An ordered list (ol), so position is also conveyed by list semantics.
  • Position badges are aria-hidden; each button's name states the item and direction.
  • Move buttons are native button type="button" elements at least 44 by 44px.
  • The announcement paragraph is visually hidden but remains in the accessibility tree as a polite live region.

Basic example

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

Canonical

Minimal ranking

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.

Rank the priorities from most to least important.

Use the move controls to change the order. Drag-and-drop may be added only as an optional Limen enhancement.

  1. Reliability
  2. Delivery speed
  3. Cost efficiency

HTML · Minimal ranking Raw HTML for HTML · Minimal ranking
<forma-ranking class="forma-component-tag">
<fieldset class="forma-ranking">
  <legend class="forma-ranking__legend">Rank the priorities from most to least important.</legend>
  <p class="forma-field__description">Use the move controls to change the order. Drag-and-drop may be added only as an optional Limen enhancement.</p>

  <ol class="forma-ranking__list">
    <li class="forma-ranking__item" data-forma-rank="1">
      <span class="forma-ranking__position" aria-hidden="true">1</span>
      <span class="forma-ranking__label">Reliability</span>
      <span class="forma-ranking__actions">
        <button type="button" disabled aria-label="Move Reliability up">↑</button>
        <button type="button" aria-label="Move Reliability down">↓</button>
      </span>
    </li>
    <li class="forma-ranking__item" data-forma-rank="2">
      <span class="forma-ranking__position" aria-hidden="true">2</span>
      <span class="forma-ranking__label">Delivery speed</span>
      <span class="forma-ranking__actions">
        <button type="button" aria-label="Move Delivery speed up">↑</button>
        <button type="button" aria-label="Move Delivery speed down">↓</button>
      </span>
    </li>
    <li class="forma-ranking__item" data-forma-rank="3">
      <span class="forma-ranking__position" aria-hidden="true">3</span>
      <span class="forma-ranking__label">Cost efficiency</span>
      <span class="forma-ranking__actions">
        <button type="button" aria-label="Move Cost efficiency up">↑</button>
        <button type="button" disabled aria-label="Move Cost efficiency down">↓</button>
      </span>
    </li>
  </ol>
  <p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true"></p>
</fieldset>
</forma-ranking>

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

Examples

Scenario

After moving an item up

Delivery speed has just been moved to first place with its Move up button. The application renumbered the list, disabled the impossible moves at the ends and wrote the announcement.

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.

Rank these goals for the next release.
  1. Delivery speed
  2. Reliability
  3. Accessibility fixes
  4. Cost efficiency

Delivery speed moved to position 1 of 4.

HTML · After moving an item up Raw HTML for HTML · After moving an item up
<forma-ranking class="forma-component-tag">
  <fieldset class="forma-ranking">
    <legend class="forma-ranking__legend">Rank these goals for the next release.</legend>
    <ol class="forma-ranking__list">
      <li class="forma-ranking__item" data-forma-rank="1">
        <span class="forma-ranking__position" aria-hidden="true">1</span>
        <span class="forma-ranking__label">Delivery speed</span>
        <span class="forma-ranking__actions">
          <button type="button" disabled aria-label="Move Delivery speed up">↑</button>
          <button type="button" aria-label="Move Delivery speed down">↓</button>
        </span>
      </li>
      <li class="forma-ranking__item" data-forma-rank="2">
        <span class="forma-ranking__position" aria-hidden="true">2</span>
        <span class="forma-ranking__label">Reliability</span>
        <span class="forma-ranking__actions">
          <button type="button" aria-label="Move Reliability up">↑</button>
          <button type="button" aria-label="Move Reliability down">↓</button>
        </span>
      </li>
      <li class="forma-ranking__item" data-forma-rank="3">
        <span class="forma-ranking__position" aria-hidden="true">3</span>
        <span class="forma-ranking__label">Accessibility fixes</span>
        <span class="forma-ranking__actions">
          <button type="button" aria-label="Move Accessibility fixes up">↑</button>
          <button type="button" aria-label="Move Accessibility fixes down">↓</button>
        </span>
      </li>
      <li class="forma-ranking__item" data-forma-rank="4">
        <span class="forma-ranking__position" aria-hidden="true">4</span>
        <span class="forma-ranking__label">Cost efficiency</span>
        <span class="forma-ranking__actions">
          <button type="button" aria-label="Move Cost efficiency up">↑</button>
          <button type="button" disabled aria-label="Move Cost efficiency down">↓</button>
        </span>
      </li>
    </ol>
    <p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true">Delivery speed moved to position 1 of 4.</p>
  </fieldset>
</forma-ranking>

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

Scenario

Long item labels with heavy motion weight

Items with sentence-length labels that wrap within the middle column. Heavy motion weight gives any application-driven settle (via the reorder hooks) a slower, more damped feel; it does not change the order logic.

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.

Order the risks from most to least urgent.

Use the arrow buttons to move a risk. The top item is the most urgent.

  1. Customer data exports are not encrypted when written to the shared archive bucket
  2. The primary database has no tested failover to the secondary region

HTML · Long item labels with heavy motion weight Raw HTML for HTML · Long item labels with heavy motion weight
<forma-ranking class="forma-component-tag">
  <fieldset class="forma-ranking" data-forma-motion-weight="heavy" aria-describedby="ranking-long-help">
    <legend class="forma-ranking__legend">Order the risks from most to least urgent.</legend>
    <p class="forma-field__description" id="ranking-long-help">Use the arrow buttons to move a risk. The top item is the most urgent.</p>
    <ol class="forma-ranking__list">
      <li class="forma-ranking__item" data-forma-rank="1">
        <span class="forma-ranking__position" aria-hidden="true">1</span>
        <span class="forma-ranking__label">Customer data exports are not encrypted when written to the shared archive bucket</span>
        <span class="forma-ranking__actions">
          <button type="button" disabled aria-label="Move unencrypted exports up">↑</button>
          <button type="button" aria-label="Move unencrypted exports down">↓</button>
        </span>
      </li>
      <li class="forma-ranking__item" data-forma-rank="2">
        <span class="forma-ranking__position" aria-hidden="true">2</span>
        <span class="forma-ranking__label">The primary database has no tested failover to the secondary region</span>
        <span class="forma-ranking__actions">
          <button type="button" aria-label="Move untested failover up">↑</button>
          <button type="button" disabled aria-label="Move untested failover down">↓</button>
        </span>
      </li>
    </ol>
    <p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true"></p>
  </fieldset>
</forma-ranking>

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

Ranking on a phone

Below 44rem the move buttons drop under the item text and split the row width, giving large touch targets.

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

  • Each row becomes a two-column grid (position, label); the actions move to their own full-width line beneath.
  • The two move buttons share that line equally, each at least 44px tall, which suits thumbs better than two small squares.
  • Labels wrap; the list never scrolls horizontally at 320px.
  • Reordering remains button-driven; any drag enhancement must not be the only path on touch devices.
HTML · Ranking on a phone Raw HTML for HTML · Ranking on a phone
<forma-ranking class="forma-component-tag">
  <fieldset class="forma-ranking">
    <legend class="forma-ranking__legend">Rank your preferred working hours.</legend>
    <ol class="forma-ranking__list">
      <li class="forma-ranking__item" data-forma-rank="1">
        <span class="forma-ranking__position" aria-hidden="true">1</span>
        <span class="forma-ranking__label">Early (7:00 to 15:00)</span>
        <span class="forma-ranking__actions">
          <button type="button" disabled aria-label="Move Early up">↑</button>
          <button type="button" aria-label="Move Early down">↓</button>
        </span>
      </li>
      <li class="forma-ranking__item" data-forma-rank="2">
        <span class="forma-ranking__position" aria-hidden="true">2</span>
        <span class="forma-ranking__label">Standard (9:00 to 17:00)</span>
        <span class="forma-ranking__actions">
          <button type="button" aria-label="Move Standard up">↑</button>
          <button type="button" aria-label="Move Standard down">↓</button>
        </span>
      </li>
      <li class="forma-ranking__item" data-forma-rank="3">
        <span class="forma-ranking__position" aria-hidden="true">3</span>
        <span class="forma-ranking__label">Late (11:00 to 19:00)</span>
        <span class="forma-ranking__actions">
          <button type="button" aria-label="Move Late up">↑</button>
          <button type="button" disabled aria-label="Move Late down">↓</button>
        </span>
      </li>
    </ol>
    <p class="forma-ranking__announcement" aria-live="polite" aria-atomic="true"></p>
  </fieldset>
</forma-ranking>

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
typebuttonbutton—Required so move buttons never submit the surrounding form.
aria-labelbutton"Move <item> up" / "Move <item> down"—Required. The arrow glyph is not a name; the label states item and direction.
disabledbuttonbooleanabsentSet by the application on Move up for the first item and Move down for the last.
aria-hidden.forma-ranking__positiontrue—The badge is visual; list semantics and announcements carry position.
aria-live.forma-ranking__announcementpolite—Announces the application's movement messages.
aria-atomic.forma-ranking__announcementtrue—Reads the whole message each time it changes.
data-forma-rank.forma-ranking__iteminteger—Authoritative position written by the application for its own use. Forma does not style it.
aria-describedbyfieldsetid list—Associates instructions with the ranking.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-rankingBlock class—Root fieldset with browser border and padding removed; also a motion scope for reorder settling.
.forma-ranking__actionsElement class—Container for the move buttons; each button is at least 44 by 44px.
.forma-ranking__announcementElement class—Visually hidden live region for movement messages.
.forma-ranking__itemElement class—Bordered row: position, label and actions. At least 3.25rem tall.
.forma-ranking__labelElement class—Item text; wraps anywhere.
.forma-ranking__legendElement class—Question text.
.forma-ranking__listElement class—Unstyled ordered list stacking the items with a small gap.
.forma-ranking__positionElement class—Inverse square badge showing the current position number.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass (light, standard, heavy) for application-driven settle transitions such as data-forma-manipulation on items. Never encodes importance.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the enabled move buttons in order; disabled buttons are skipped.
Enter / SpaceActivates the focused move button (native button behavior). The application performs the move and should keep focus on the moved item's corresponding button.
Events
EventDescription
clickNative click from a move button. Limen handles it to reorder, renumber and announce.

Form behavior

The list does not submit anything natively. The application serialises the order, for example into hidden inputs, or sends it directly.

States

Ranking states
StateHow it is expressedPresentation
OrderedDOM order plus data-forma-rankPosition badges show 1 to n in list order.
End of listdisabled on the first Move up and last Move downImpossible moves are disabled and skipped by focus.
Announcedtext in .forma-ranking__announcementScreen readers hear the movement result.
Dragging / drop feedbackdata-forma-manipulation and data-forma-drop on items (application-set)Optional direct-manipulation presentation documented in Reorder states.

Accessibility

Forma provides

  • Provides 44px native buttons as the non-drag reorder path.
  • Places a polite, atomic live region in the structure, visually hidden but announced.
  • Uses an ordered list so position is conveyed without the badge.
  • Draws item borders in CanvasText under forced colors.

Your application supplies

  • Implement the move, renumber badges and data-forma-rank, and disable moves at the ends.
  • Keep focus on the moved item's button after a move, and write an announcement such as "Reliability moved to position 2 of 4."
  • Label every button with item and direction.
  • Never make drag the only way to reorder.

Responsive behavior

  • Wide: auto minmax(0, 1fr) auto columns for position, label and actions.
  • Below 44rem: actions move to a full-width second line and split into two equal buttons.
  • Labels wrap anywhere; no horizontal overflow.

Motion

  • Items do not animate on their own. When the application sets data-forma-manipulation on an item, its translate follows the pointer with no lag while dragging and settles with a damped, non-overshooting transition afterwards; data-forma-motion-weight on the ranking sets that settle duration.
  • Button hover and press use the foundation's perceptual background interpolation.
  • Under prefers-reduced-motion: reduce settle transitions are effectively instant and items appear at their final position.

Motion weights

Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:

lightpresentation only
Rank the priorities from most to least important.

Use the move controls to change the order. Drag-and-drop may be added only as an optional Limen enhancement.

  1. Reliability
  2. Delivery speed
  3. Cost efficiency

standardpresentation only
Rank the priorities from most to least important.

Use the move controls to change the order. Drag-and-drop may be added only as an optional Limen enhancement.

  1. Reliability
  2. Delivery speed
  3. Cost efficiency

heavypresentation only
Rank the priorities from most to least important.

Use the move controls to change the order. Drag-and-drop may be added only as an optional Limen enhancement.

  1. Reliability
  2. Delivery speed
  3. Cost efficiency

Usage guidance

Do

  • Start from a neutral or randomised order when order bias matters.
  • Announce each move with the item and its new position.

Avoid

  • Relying on drag-and-drop only.
  • Using motion weight to suggest which item matters most.

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.