Skip to content

docs(components): update ConfirmationModal content guidelines #3016

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
George-W-M wants to merge 1 commit into
base: master
Choose a base branch
from
+71 −23
Open

docs(components): update ConfirmationModal content guidelines #3016

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 71 additions & 23 deletions packages/site/src/content/ConfirmationModal/ConfirmationModal.stories.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,29 +29,77 @@ presents a confirm modal.

## Content guidelines

Keep language in a ConfirmationModal clear, concise, and consistent.

Verbs in the title should directly relate to the `confirmLabel`.

| **✅ Do** | **❌ Don't** |
| ---------------------------- | ------------------- |
| **Discard unsaved changes?** | **Cancel editing?** |
| Cancel / Discard | No / Yes |

Only use **Cancel** as a label to allow the user to exit the current action.

| **✅ Do** | **❌ Don't** |
| --------------------- | ----------------------- |
| **Stop file upload?** | **Cancel file upload?** |
| Cancel / Stop | Exit / Cancel |

Avoid using generic or verbose titles.

| **✅ Do** | **❌ Don't** |
| --------------------------------------------------- | --------------------------------------------------- |
| **Delete job #2121?** | **Are you sure?** |
| Deleting this job will remove all associated visits | Deleting this job will remove all associated visits |
| Cancel / Delete Job | Cancel / Delete Job |
Keep language in a ConfirmationModal clear, concise, and consistent. Every word
should help the user make a confident decision — not slow them down or cause
unnecessary anxiety.

### Title

The title should clearly state the action being confirmed. It gives the user
immediate context about what they're being asked to decide.

- Write as a statement, not a question. Do not use question marks.
- Lead with a verb that matches the `confirmLabel`.
- Be specific — include the object where possible (e.g. the job number, client
name, or item being affected).
- Avoid generic titles like "Are you sure?" or "Confirm action."

| **✅ Do** | **❌ Don't** |
| --------------------------- | ---------------------------- |
| **Discard unsaved changes** | **Discard unsaved changes?** |
| **Delete job #2121** | **Are you sure?** |
| **Remove Acme Corp** | **Confirm removal** |
| **Leave without saving** | **Cancel editing?** |

### Body copy

Use the body to explain what will happen as a result of the action — especially
if the consequences aren't immediately obvious from the title alone.

- Focus on consequences, not instructions. The user already knows what they're
about to do.
- Be specific about what will be lost, removed, or changed.
- Keep it to one or two short sentences.
- Omit body copy entirely if the title is already self-explanatory.

| **✅ Do** | **❌ Don't** |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Deleting this job will remove all associated visits and invoices | Are you sure you want to delete this job? |
| Your changes will be lost and can't be recovered | This action cannot be undone |
| Acme Corp will be removed from your client list. You will still be able to view their job history. | Confirm you want to remove this client. |

### Button labels

Button labels are the most important content in a ConfirmationModal. They must
be clear, specific, and match the action being taken.

- Use a specific verb for the `confirmLabel` that mirrors the title (e.g. if the
title is "Delete job #2121", the label should be "Delete Job").
- Always use **Cancel** as the dismiss label — not "No", "Go back", or "Exit".
- Avoid generic labels like "OK", "Yes", or "Confirm".
- For destructive actions, the `confirmLabel` should reinforce the severity of
the action without being alarming.

| **Action** | **✅ confirmLabel** | **❌ Don't use** |
| ---------------------- | ------------------- | ----------------- |
| Deleting a job | Delete Job | Yes / OK |
| Discarding changes | Discard | Leave / Exit |
| Removing a client | Remove Client | Confirm / Proceed |
| Stopping a file upload | Stop Upload | Yes / OK |

### Destructive actions

When a ConfirmationModal is used for a destructive action — one that will
permanently delete or remove something — use the destructive variant. The
language should be direct and honest about the impact without being alarming.

- Do not soften the language with phrases like "just" or "simply".
- Do not over-explain or repeat the same information across the title and body.
- Make the `confirmLabel` the same verb as the title action.

| **✅ Do** | **❌ Don't** |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Delete job #2121** / Deleting this job will remove all associated visits. / Cancel / Delete Job | **Are you sure?** / Deleting the job will remove it forever. Are you absolutely sure you want to continue? / No / Yes, delete it |

## Related components

Expand Down
Loading