Assessment and survey

Question shell

<forma-question>

A stable prompt, help, selector, and validation structure for assessment questions.

Authoring tag
<forma-question>
Behavior owner
Application content
Canonical source
patterns/question.html

Purpose

The question shell is the frame every assessment item shares: an optional number or identifier, the prompt as a heading, help text, the answer selector and any validation message. It is a section labelled by its prompt, so each question is a navigable region with a stable structure regardless of which selector sits inside. The shell carries no applicability, branching, scoring or persistence meaning; the application decides whether a question is rendered and what its answer means.

Use when

  • An assessment, survey or onboarding form presents a sequence of questions that should all read the same way.
  • A question needs a visible number or identifier, help text and a place for a question-level validation message.
  • Several selector types (scales, binary choices, matrices, free text) appear in one flow and need one consistent frame.

Avoid when

  • The input is an ordinary form field with a label and description: use Text field or the selector on its own.
  • The content is a settings row or preference: use Switch or Checkbox inside a fieldset.
  • You want to hide a question that does not apply: do not render it with CSS hidden; the application decides applicability and omits the shell.

Behavior to know

  • The prompt is a real heading referenced by aria-labelledby, so the section has an accessible name and appears in heading navigation.
  • The number badge is decorative (aria-hidden); the heading carries the meaning.
  • The body column is minmax(0, 1fr) with min-inline-size: 0, so wide selectors cannot push the page sideways.
  • A subtle bottom rule separates consecutive questions; spacing is fixed by Forma, not by the selector.

Basic example

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

Canonical

Minimal question shell

Rendered from the canonical pattern file.

How consistently is this practice followed?

Choose the response that best describes the current state.

HTML · Minimal question shell Raw HTML for HTML · Minimal question shell
<forma-question class="forma-component-tag">
<section class="forma-question" aria-labelledby="question-example-title">
  <header class="forma-question__header">
    <span class="forma-question__number" aria-hidden="true">7</span>
    <div>
      <h2 class="forma-question__prompt" id="question-example-title">How consistently is this practice followed?</h2>
      <p class="forma-question__help" id="question-example-help">Choose the response that best describes the current state.</p>
    </div>
  </header>

  <div class="forma-question__body" aria-describedby="question-example-help">
    <!-- Insert a selector pattern here. -->
  </div>
</section>
</forma-question>

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

Examples

Scenario

Required question with a validation error

The application rendered a question-level error after an attempted advance. The error sits below the selector and is referenced from the inputs with aria-describedby, alongside the help text.

How often are production changes reviewed by a second person?

Consider the last three months of changes.

Choose one response before continuing.

HTML · Required question with a validation error Raw HTML for HTML · Required question with a validation error
<forma-question class="forma-component-tag">
  <section class="forma-question" aria-labelledby="question-error-title">
    <header class="forma-question__header">
      <span class="forma-question__number" aria-hidden="true">4</span>
      <div>
        <h2 class="forma-question__prompt" id="question-error-title">How often are production changes reviewed by a second person?</h2>
        <p class="forma-question__help" id="question-error-help">Consider the last three months of changes.</p>
      </div>
    </header>
    <div class="forma-question__body">
      <fieldset class="forma-ordinal-scale forma-ordinal-scale--3" aria-labelledby="question-error-title" aria-describedby="question-error-help question-error-message">
        <div class="forma-ordinal-scale__options">
          <label class="forma-ordinal-option">
            <input type="radio" name="question-error-review" value="rarely" required aria-invalid="true">
            <span class="forma-ordinal-option__marker" aria-hidden="true">1</span>
            <span class="forma-ordinal-option__label">Rarely</span>
          </label>
          <label class="forma-ordinal-option">
            <input type="radio" name="question-error-review" value="sometimes" aria-invalid="true">
            <span class="forma-ordinal-option__marker" aria-hidden="true">2</span>
            <span class="forma-ordinal-option__label">Sometimes</span>
          </label>
          <label class="forma-ordinal-option">
            <input type="radio" name="question-error-review" value="always" aria-invalid="true">
            <span class="forma-ordinal-option__marker" aria-hidden="true">3</span>
            <span class="forma-ordinal-option__label">Always</span>
          </label>
        </div>
      </fieldset>
      <p class="forma-validation-message" id="question-error-message">
        <span class="forma-validation-message__mark" aria-hidden="true">!</span>
        Choose one response before continuing.
      </p>
    </div>
  </section>
</forma-question>

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

Scenario

Long prompt with a binary answer

A long policy prompt wraps inside the heading column while the number badge stays aligned to the first line. The body holds a Binary choice; the shell does not change for a different selector.

Does every service that stores customer data have a documented, tested restore procedure that has been exercised within the last twelve months?

A restore that was planned but not performed counts as No.

Tested restore procedure in place
HTML · Long prompt with a binary answer Raw HTML for HTML · Long prompt with a binary answer
<forma-question class="forma-component-tag">
  <section class="forma-question" aria-labelledby="question-binary-title">
    <header class="forma-question__header">
      <span class="forma-question__number" aria-hidden="true">12</span>
      <div>
        <h2 class="forma-question__prompt" id="question-binary-title">Does every service that stores customer data have a documented, tested restore procedure that has been exercised within the last twelve months?</h2>
        <p class="forma-question__help" id="question-binary-help">A restore that was planned but not performed counts as No.</p>
      </div>
    </header>
    <div class="forma-question__body">
      <fieldset class="forma-binary-choice" aria-describedby="question-binary-help">
        <legend class="forma-binary-choice__legend">Tested restore procedure in place</legend>
        <div class="forma-binary-choice__options">
          <label class="forma-binary-option"><input type="radio" name="question-binary-restore" value="yes" required><span>Yes</span></label>
          <label class="forma-binary-option"><input type="radio" name="question-binary-restore" value="no"><span>No</span></label>
        </div>
      </fieldset>
    </div>
  </section>
</forma-question>

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

Scenario

Optional free-text follow-up

Not every question is a scale. An optional follow-up uses an ordinary labelled textarea inside the same shell, so numbering, prompt and help stay consistent across selector types.

What would most improve your recovery process?

Optional. Two or three sentences are enough.

HTML · Optional free-text follow-up Raw HTML for HTML · Optional free-text follow-up
<forma-question class="forma-component-tag">
  <section class="forma-question" aria-labelledby="question-text-title">
    <header class="forma-question__header">
      <span class="forma-question__number" aria-hidden="true">13</span>
      <div>
        <h2 class="forma-question__prompt" id="question-text-title">What would most improve your recovery process?</h2>
        <p class="forma-question__help" id="question-text-help">Optional. Two or three sentences are enough.</p>
      </div>
    </header>
    <div class="forma-question__body">
      <div class="forma-field">
        <label class="forma-field__label" for="question-text-answer">Your answer</label>
        <textarea id="question-text-answer" name="question-text-answer" rows="3" aria-describedby="question-text-help"></textarea>
      </div>
    </div>
  </section>
</forma-question>

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

Question on a phone

A five-point agreement question at phone width. The header keeps the number beside the wrapping prompt and the scale below reflows to a vertical list.

Viewport width

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

What changes at narrow widths

  • The header grid keeps the number in an auto column and gives the prompt the remaining width, so long prompts wrap instead of overflowing.
  • The prompt font size is fluid (clamped between 1rem and 1.2rem), so it shrinks slightly on phones without dropping below body size.
  • The selector in the body reflows on its own: the ordinal scale stacks its options into full-width 52px rows below 44rem.
  • No part of the shell scrolls horizontally at 320px; portrait and landscape only change line breaks.
HTML · Question on a phone Raw HTML for HTML · Question on a phone
<forma-question class="forma-component-tag">
  <section class="forma-question" aria-labelledby="question-mobile-title">
    <header class="forma-question__header">
      <span class="forma-question__number" aria-hidden="true">2</span>
      <div>
        <h2 class="forma-question__prompt" id="question-mobile-title">Releases can be rolled back without a code change.</h2>
        <p class="forma-question__help">Choose the response that best matches your team.</p>
      </div>
    </header>
    <div class="forma-question__body">
      <fieldset class="forma-ordinal-scale forma-ordinal-scale--5" aria-labelledby="question-mobile-title">
        <div class="forma-ordinal-scale__options">
          <label class="forma-ordinal-option"><input type="radio" name="question-mobile-rollback" value="0" required><span class="forma-ordinal-option__marker" aria-hidden="true">1</span><span class="forma-ordinal-option__label">Strongly disagree</span></label>
          <label class="forma-ordinal-option"><input type="radio" name="question-mobile-rollback" value="1"><span class="forma-ordinal-option__marker" aria-hidden="true">2</span><span class="forma-ordinal-option__label">Disagree</span></label>
          <label class="forma-ordinal-option"><input type="radio" name="question-mobile-rollback" value="2"><span class="forma-ordinal-option__marker" aria-hidden="true">3</span><span class="forma-ordinal-option__label">Neither agree nor disagree</span></label>
          <label class="forma-ordinal-option"><input type="radio" name="question-mobile-rollback" value="3"><span class="forma-ordinal-option__marker" aria-hidden="true">4</span><span class="forma-ordinal-option__label">Agree</span></label>
          <label class="forma-ordinal-option"><input type="radio" name="question-mobile-rollback" value="4"><span class="forma-ordinal-option__marker" aria-hidden="true">5</span><span class="forma-ordinal-option__label">Strongly agree</span></label>
        </div>
      </fieldset>
    </div>
  </section>
</forma-question>

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.

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-labelledbysection.forma-questionid of .forma-question__prompt—Names the question region by its prompt. The same id can label the inner fieldset when the prompt replaces a visible legend.
aria-describedbyselector fieldset or inputids of help and error text—Associates help and validation text with the control that receives focus. Put it on the fieldset or inputs; a plain div does not reliably expose a description.
aria-hidden.forma-question__numbertrue—Keeps the decorative number badge out of the accessibility tree; the heading already names the question.
aria-invalidinputstrueabsentSet by the application when the question fails validation so assistive technology reports the error state.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-questionBlock class—Root section. A grid with vertical padding and a subtle bottom rule that separates consecutive questions.
.forma-question__bodyElement class—Container for the selector and validation message. It is allowed to shrink so wide selectors cannot overflow.
.forma-question__headerElement class—Two-column grid: number badge and the prompt/help column.
.forma-question__helpElement class—Secondary instruction text under the prompt; reference it with aria-describedby.
.forma-question__numberElement class—Circular monospace badge for a question number or short identifier. Decorative.
.forma-question__promptElement class—The prompt heading. Use a heading level that fits the page outline.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves into and out of the selector inside the body. The shell itself adds no focus stops.
Selector keysWhatever the embedded selector provides natively, for example arrow keys within a radio group.

Form behavior

The shell does not participate in forms. The selector inside it submits its own native values.

States

Question shell states
StateHow it is expressedPresentation
Unansweredno checked input in the bodyNothing in the shell changes; the selector shows no selection.
Invalidapplication renders .forma-validation-message and sets aria-invalidA text error with a non-color mark appears under the selector and is associated with the inputs.
Not applicableapplication omits the sectionForma has no hidden or skipped state. The application decides applicability and does not render the question.

Accessibility

Forma provides

  • Provides a section labelled by a heading, so each question is a named region and appears in heading navigation.
  • Keeps the number badge decorative and the prompt as the single source of the question's name.
  • Lays out validation as text with a visible mark, not color alone.

Your application supplies

  • Choose the heading level that fits the page outline and keep prompt ids unique per question.
  • Associate help and error text with the focusable control or its fieldset using aria-describedby.
  • Move focus to a Validation summary after a failed advance when there are several errors.
  • Decide applicability and branching in application state; never hide a required question with CSS.

Responsive behavior

  • The header is a two-column grid (auto minmax(0, 1fr)), so long prompts wrap beside the badge.
  • The prompt size is fluid with clamp(); help text stays at 0.875rem.
  • The body has min-inline-size: 0; the embedded selector owns its own narrow-screen recomposition.
  • There are no breakpoints in the shell itself.

Motion

  • No animation: the shell is static. Selection feedback inside the body comes from the selector (for example the shared 120ms perceptual color interpolation on assessment options).

Usage guidance

Do

  • Write the prompt as the complete question, and keep help text short and specific.
  • Use the same shell for every selector type in a flow so numbering and spacing stay consistent.

Avoid

  • Encoding scoring, weight or applicability in the number badge or its styling.
  • Putting required instructions only in a tooltip; place them in .forma-question__help.

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.