Action sheet component

A context-anchored set of choices for the current task — slides up from the bottom on phones, presented as a popover on larger screens — used especially to confirm a destructive action with an explicit Cancel. Distinct from a dialog (which interrupts for an unrelated decision) and from a sheet (which holds content, not a choice list). Apple HIG parity (action sheets / activity-style confirmation).

Status: v0.1.0 — Draft. Promoted from the Apple HIG parity scan (metadocsstack #080). Source: https://developer.apple.com/design/human-interface-guidelines/action-sheets

R1 — When to use (vs dialog / menu / sheet)

  • Action sheet: 2–~5 mutually exclusive actions *about the current

    context*, anchored to the task — most importantly, confirming a destructive action. Originates from the user tapping a control.

  • Dialog (specs/components/dialogs.kmd): interrupts with an unrelated

    or system-initiated decision; centered/modal.

  • Menu (specs/components/menus.kmd): many navigational/command items,

    non-destructive, anchored inline.

  • Sheet (specs/components/sheets.kmd): holds content/forms, not a

    short action list.

If there is no destructive or context-bound choice, prefer a menu.

R2 — Anatomy

Element Required Notes
Title Optional Short context ("Delete 3 files?")
Message Optional One line of consequence/clarification
Action buttons Yes (1..~5) Verb-labeled; one MAY be destructive (R3)
Cancel Yes Visually separated from the actions; dismisses with no effect

R3 — Destructive action styling

  • A destructive action uses the danger semantic token (red text/fill per

    specs/themes/verge.kmd) and a clear verb ("Delete", not "OK").

  • The destructive action is never the default/auto-focused control;

    Cancel is the safe default.

  • At most one destructive action per sheet.

R4 — Placement by form factor

  • Compact / phone: slides up anchored to the bottom safe-area

    (specs/app-layout/safe-area.kmd); a scrim dims the content; tapping the scrim = Cancel.

  • Regular / tablet-desktop: presented as a popover anchored to the

    triggering control (no full-width bottom bar). The choice set is identical; only the presentation adapts.

R5 — Dismissal

  • Cancel, scrim tap, Esc (desktop), and the system back gesture all

    dismiss with no side effect.

  • A destructive action requires a deliberate tap; it is never triggered by

    dismissal.

R6 — Accessibility & i18n

  • Focus moves into the sheet on open; focus is trapped until dismissal;

    on close it returns to the trigger.

  • The destructive action is announced as such (its label carries the

    meaning; color is not the only signal — WCAG 1.4.1).

  • Reachable and operable by keyboard and screen reader; Cancel is always

    reachable.

  • All labels translatable per specs/i18n/contract.kmd; destructive verbs

    stay specific across locales.

Não-escopo

  • Share/activity sheets (OS-provided share UI) — a platform integration.
  • Content-bearing sheets (specs/components/sheets.kmd).
  • Unrelatedsystem modals (`specscomponents/dialogs.kmd`).