;
}
};
They should be clear, concise, and respectful of the user's workflow, minimizing disruption while maximizing clarity.
### Guiding principles for confirmation messages
**Be selective with confirmation prompts**
* **Purpose:** Use confirmation messages only when the action is significant, irreversible, or could lead to data loss. Avoid overusing them, as this can interrupt the user experience and lead to "confirmation fatigue," where users dismiss messages without fully engaging.
* **Efficiency:** Prioritize the user's time by only presenting confirmations when absolutely necessary. This shows respect for their workflow and confidence in their decisions.
* **Example:**
* **Do:** Use a confirmation prompt when a user is about to delete an account or data that cannot be recovered.
* **Don’t:** Prompt for confirmation when saving settings that can easily be changed back.
**Ensure clarity and simplicity**
* **Directness:** The confirmation message should directly state what the user is confirming, using a simple and straightforward verb+noun structure. Avoid unnecessary words or jargon.
* **Tone:** Use a tone that is confident and reassuring, aligned with ServiceTitan's brand voice. The language should be simple, bold, and authentic, resonating with the direct communication style of the trades professionals who use the product.
**Communicate consequences clearly**
* **Transparency:** Clearly explain what will happen as a result of the action, especially if it is irreversible. Users should understand the implications without needing to read lengthy explanations.
* **Brevity:** Keep the explanation short, focusing on the most critical information that the user needs to know to make an informed decision.
**Align CTA labels with action**
* **Consistency:** The primary CTA (Call to Action) should mirror the action described in the confirmation message. This ensures that even if a user only reads the title and the CTA, they will understand the action they are confirming.
* **Verb-noun structure:** Use a clear verb+noun structure for CTA labels to reinforce the action, e.g., "Delete Job" instead of just "Delete."
**Minimize Disruption**
* **User Flow:** Confirmation messages should be as non-intrusive as possible. Design them to fit seamlessly into the user journey, providing necessary checks without breaking the flow.
* **Visual Design:** Ensure that the confirmation message is visually aligned with the rest of the UI, using clear buttons and intuitive layouts that guide the user naturally.
**Examples**
#### Ensure clarity and simplicity
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
Delete this job?
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
Are you sure you want to delete this job?
);
}
export default App;
```
**Don't**
#### Communicate consequences clearly
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
This action cannot be undone.
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Text, Flex } from "@servicetitan/anvil2";
function App() {
return (
Are you sure you want to proceed? If you delete this, it will be gone
forever, and there’s no way to recover it.
);
}
export default App;
```
**Don't**
#### Align CTA labels with action
```tsx lines theme={null}
import { Dialog, Flex, Button } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**Don't**
### Structure of a Confirmation Message
**Title: Action-oriented and direct**
* Use a clear verb+noun format (e.g., "Delete this job?").
* Keep it concise, typically one sentence in sentence case.
* Maintain a straightforward, confident tone.
**Context: Brief and relevant**
* Provide essential information in 1-2 sentences.
* Avoid repeating the title and focus on what the user needs to know.
**Consequence: Clear and unambiguous**
* State the impact of the action, especially if irreversible.
* Use simple, direct language (e.g., "This action cannot be undone.").
**Primary CTA: Reflect the action**
* Match the CTA label with the title (e.g., "Delete Job").
* Ensure the primary action is prominent, with a clear verb+noun structure.
