Task list pattern

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.

Status: v0.1.0 — Draft. Promoted from the GOV.UK parity scan (metadocsstack #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

Element Required Notes
Page heading Yes Names the journey ("Apply for …")
Progress summary Yes "{n} of {m} sections complete" — single sentence above the list
Section group (optional) Optional Group related tasks under an <h2> when ≥ ~7 tasks
Task row Yes (1..n) Task name + status tag; the name is a link only when the task is actionable (R4)
Status tag Yes (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:

State Meaning Tag style Name is a link?
Cannot start yet A prerequisite task is incomplete (R5) muted/grey No (plain text)
Not started Actionable, no progress neutral/blue Yes
In progress Started, not finished accent/amber Yes
Completed Done; re-editable success/green Yes

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.