Survey design playbook

This is the playbook Motivation Form ships so that agents and developers build forms that get completed, not just forms that capture every field someone asked for. The renderer already supports the field types, conditional logic, and multi-page flows referenced below (Field types, Survey syntax). This page is about which of them to reach for, and when.

The single rule behind everything here: every field is friction. A form's value is the responses it collects, and each additional question, each wrong input type, each unnecessary "required" lowers the completion rate. Design for the respondent's next action.

The defaults

When building any form, apply these unless the use case demands otherwise.

1. Choose the narrowest input type for each question

The right type makes a question faster to answer and the data cleaner to analyze. Reach for the most specific type that fits:

Free text (textarea) is the most expensive field to answer and the hardest to analyze — use it for the one place you genuinely want a respondent's own words, not as a catch-all.

2. Put identity fields first, and make them optional

Name, email, company, and role go before the substantive questions, grouped on the first page. Keep them optional unless the response is worthless without attribution. Put (optional) directly in the label, not only in help text:

- id: name
  type: text
  label: Name (optional)
  required: false
- id: email
  type: email
  label: Email (optional)
  required: false

Every required identity field is friction the respondent hits before they reach the actual task.

3. Minimize required fields

Mark a field required: true only when a missing answer makes the whole response useless. Optional-by-default raises completion and still collects the answer when the respondent has one.

4. Keep choice lists short

On mobile, aim for ~5 options or fewer in a radio/checkbox. Past ~6, switch to select so the list doesn't dominate the screen. If a list is long and unordered, alphabetize or group it.

5. Capture the "why" with a conditional follow-up

The highest-value qualitative data comes from pairing a rating with a targeted follow-up that only appears when it's relevant. This is the single best lever for useful free-text volume:

- id: recommend
  type: nps
  label: How likely are you to recommend us?
- id: detractor_reason
  type: textarea
  label: What would need to change for a higher score?
  show_if:
    field: recommend
    op: lte
    value: 6

Ask the open question only of the people whose answer makes it worth asking.

6. One question per page for long or high-stakes flows

For long surveys and quizzes, give each scored/substantive question its own page (page: per field) so the respondent sees one focused prompt at a time. Group short, low-effort intake fields together on one page. Turn on a progress bar so they always know where they are:

settings:
  progress_bar: true

Show progress as current / total — orientation and momentum, not a wall of page links.

7. Randomize options when order could bias the answer

For preference, ranking, and opinion questions, set randomize_options: true so the first option doesn't win by position. Do not randomize when order is meaningful (e.g. Likert scales, or quiz answer banks where the owner wants stable order).

Quiz-specific guidance

• Preserve the source quiz exactly. Keep every question number, option label, and answer key. Verify counts before launch: question count, first/last question, and score total.
• Keep identity capture light and before the first scored question.
• Enable post-submit feedback for training quizzes — score, answer reveal, and a retake path (settings.show_score, settings.show_answers).
• Stable option order for study banks unless the owner explicitly wants randomization.

Anti-patterns to avoid

• A wall of required fields on a single page.
• Free-text boxes where a choice or scale would do.
• Asking everyone an open follow-up that only applies to some (use show_if).
• A long radio list that should be a select.
• Collecting identity you'll never use "just in case."
• A progress bar that prints every page label instead of a compact N of M.

Before you publish — quick checklist

• Is every required: true field truly load-bearing?
• Are identity fields first, optional, and labelled (optional)?
• Does each question use the narrowest input type that fits?
• Are all choice lists ≤~5 on mobile (or a select past ~6)?
• Does every rating that needs a "why" have a show_if follow-up?
• For long flows: one question per page + progress bar on?
• For opinion/preference questions: options randomized?
• For quizzes: counts and answer key verified against the source?