Task list pattern

patterns specs/patterns/task-list.kmd

Section-level overview for LONG, multi-part journeys split into named tasks, each carrying an explicit completion status and dependency gating. Sits one level above the step-by-step wizard: the task list is the hub a user returns to between sub-journeys. Modeled after the GOV.UK Design System "Task list" pattern. Used by onboarding, KYC/verification, provisioning, and any flow a user completes across multiple sittings.

When this pattern applies

Primary triggers

All triggers

Pattern — Task list

Status: v0.1.0 — Draft. Promoted from the GOV.UK parity scan (meta/docs/stack #096). Live URL once rendered: kds.koder.dev/<locale>/patterns/patterns-task-list.html. Source: https://design-system.service.gov.uk/patterns/task-list-pages/

R1 — When to use

Use a task list when ALL of these hold:

  • The journey is long enough to split into 3+ named sections.
  • Sections are completable independently or with partial ordering (some unlock others), AND the user benefits from seeing overall progress.
  • The user may leave and return (save-and-return — see R6).

Do NOT use a task list when:

  • The flow is a single short linear sequence → use specs/patterns/wizard-multistep.kmd (the wizard step indicator is enough; a task list adds overhead).
  • There is exactly one thing to do → a plain page (see specs/patterns/one-thing-per-page.kmd).

R2 — Anatomy

ElementRequiredNotes
Page headingYesNames the journey ("Apply for …")
Progress summaryYes"{n} of {m} sections complete" — single sentence above the list
Section group (optional)OptionalGroup related tasks under an <h2> when ≥ ~7 tasks
Task rowYes (1..n)Task name + status tag; the name is a link only when the task is actionable (R4)
Status tagYes (per task)One of the four states in R3, color-coded per specs/components/badges.kmd

The list is an ordered/unordered <ul> of rows, NOT a data-table.

R3 — Task states (closed set)

Exactly four states; no others:

StateMeaningTag styleName is a link?
Cannot start yetA prerequisite task is incomplete (R5)muted/greyNo (plain text)
Not startedActionable, no progressneutral/blueYes
In progressStarted, not finishedaccent/amberYes
CompletedDone; re-editablesuccess/greenYes

State is derived from journey data, never hand-set in the view. A Completed task stays editable (revisiting it returns to its sub-journey, then back to the list).

R4 — Link vs plain text

  • Cannot start yet → the task name is plain text (not focusable, not a link); only the status tag communicates why.
  • All other states → the task name is a link to that task's first page.
  • The status tag itself is never the link (avoid double tab-stops); the task name carries the action.

R5 — Dependency gating

  • A task in Cannot start yet lists its blocking prerequisite(s) in its description line or via the tag's accessible label ("Cannot start yet — complete Identity first").
  • When the last blocking prerequisite reaches Completed, the dependent task transitions to Not started on next render.
  • Cycles are a content-design error; the generator/spec does not resolve them (author must define a DAG).

R6 — Save-and-return

  • Progress persists server-side keyed to the user/tenant (per specs/multi-tenancy/contract.kmd); the task list is the canonical resume point.
  • Returning to the journey always lands on the task list, never mid-wizard, unless the user deep-links a specific in-progress task.

R7 — Accessibility & i18n

  • Progress summary is a real sentence in the reading order, announced before the list.
  • Each status tag has an accessible label that repeats the state in words (color is never the sole signal — WCAG 1.4.1).
  • Task name links have visible focus (Verge --kds-color-focus).
  • All strings (heading, summary, task names, state labels) are separate i18n keys per specs/i18n/contract.kmd; the "{n} of {m}" summary uses an ICU plural, not string concatenation.

Não-escopo

  • The individual sub-journeys themselves (each is a specs/patterns/wizard-multistep.kmd or a single page).
  • Visual progress bars/rings (the textual "{n} of {m}" summary is canonical; a bar is an optional product-level addition).
  • Persistence/storage mechanics beyond the multi-tenancy contract.

References