Force UI Writing Style Guide
Layer 2 of the Force UI spec. This document defines the rules for all user-facing copy across Perforce products. It is prescriptive — follow it as written. Rules are ordered with the highest-failure-rate patterns first to help AI agents avoid the most common copy mistakes.
1. The most common mistakes — read this first
These are patterns that appear constantly in generated copy and are all wrong:
| Wrong | Right | Rule |
|---|---|---|
Save Changes |
Save changes |
Sentence case, not title case |
File saved successfully. |
File saved. |
Never use "successfully" |
Please enter a name. |
Enter a name. |
No politeness markers |
Something went wrong. |
Connection failed. Check your network and try again. |
Errors need what + why + next step |
Are you sure? |
Delete workspace? This action cannot be undone. |
Warnings state the consequence |
Yes / No buttons |
Delete workspace / Cancel |
No Yes/No buttons |
Click here links |
View API documentation |
Links must be descriptive |
Run Test (button) |
Run test |
Sentence case on buttons |
Data saved successfully! |
Changes saved. |
No exclamation points, no "successfully" |
Sorry, that didn't work. |
Integration failed. Re-authenticate and try again. |
No apologies |
2. Voice and tone
The Perforce voice is clear, professional, supportive, and confident. It does not vary. Tone adapts to context — see §7 for per-context guidance.
Never:
- Exclamation points (
!) — anywhere in UI copy - Sarcasm, playfulness, or emotional charge
- Overly casual expressions ("Hey there", "Awesome", "You nailed it")
- Academic or bureaucratic phrasing ("initiate the commencement of")
Contractions are allowed when they improve readability: You're signed in. is correct. Avoid contractions that introduce ambiguity.
3. Capitalization
This is the single most commonly violated rule. LLMs default to title case; the spec requires sentence case almost everywhere.
Sentence case (default — use everywhere except the exceptions below)
Capitalize only the first word and proper nouns. Use for:
- Button labels
- Tab names
- Field labels and descriptions
- Navigation items
- Page titles and section headers
- Error messages, warnings, and notifications
- Tooltips and placeholder text
- Empty state copy
- Loading and progress messages
✔ Run all tests / Save configuration / View results / Delete workspace
✘ Run All Tests / Save Configuration / View Results / Delete Workspace
Title case (exceptions only)
Use title case only for:
- Product names:
Puppet Enterprise,BlazeMeter - Licensable feature names:
Service Virtualization,AI Log Analysis - Proper nouns and formal event names
When a title-case product name appears in a tab row alongside generic items, it keeps its casing. Only the product name is title case; everything else is sentence case.
All caps
Acronyms only: API, RCA, CSV, URL. Never for emphasis, headers, or button labels.
4. Button labels
Rule: Sentence case. Start with a strong verb. Three words or fewer. No period.
Approved verb list
| Verb | Use when the button… | Example |
|---|---|---|
| Run | Executes a process or test | Run suite |
| Submit | Sends data | Submit feedback |
| Add | Includes new or existing content | Add test case |
| Create | Starts something new | Create project |
| View | Opens or displays content | View results |
| Save | Stores changes | Save configuration |
| Cancel | Exits or stops — standard dismiss label | Cancel |
| Delete | Removes content permanently | Delete workspace |
| Connect | Links to an external service | Connect to GitHub |
Confirmation dialogs: never use Yes/No
Always pair a specific action verb + Cancel:
✔ Delete workspace + Cancel
✔ Save changes + Cancel
✘ Yes + No
✘ OK + Cancel (OK is ambiguous — name the action)
5. Field labels and descriptions
Field labels: Sentence case. No period. Concise noun phrase.
✔ Email address / Test suite name / Retry limit
✘ Email Address / Test Suite Name / Retry Limit
Placeholder text: Sentence case. No period. Action-oriented. Do not repeat the field label.
✔ Field Email address → Placeholder Enter your work email
✘ Field Email address → Placeholder Email address
Helper text / descriptions: Full sentence with period when the text is a complete thought. Sentence case.
✔ Maximum number of retries before the test is marked as failed.
✘ Maximum Number Of Retries Before The Test Is Marked As Failed
6. Error messages
Every error message must answer three questions:
- What happened?
- Why did it happen? (if known)
- What can the user do next?
Structure: [What happened]. [Why, if known]. [Next step].
✔ Test run failed. Missing configuration file: test_env.json. Upload the file and try again.
✔ Connection to GitHub failed. Try re-authenticating.
✘ Something went wrong.
✘ Error occurred.
✘ An unexpected error has been encountered.
Tone: Calm and neutral. Never blame the user. Never use Sorry. Focus on resolution.
✘ You entered the wrong details.
✘ Sorry, something went wrong.
Case: Sentence case throughout.
7. Warning messages
Warnings appear before irreversible or high-impact actions. They must state the consequence and offer specific confirm/cancel options.
Structure: State what will happen + state the consequence + offer cancel.
✔ Delete workspace? This action cannot be undone.
✔ Stop test execution? Results will not be saved.
✔ Reset metrics? Historical data will be lost.
✘ Are you sure?
✘ This might delete stuff.
✘ Danger! You're about to lose everything!
The confirm button label must match the action: Delete workspace, not Confirm or Yes.
8. Notifications and success messages
Never use "successfully." Completion is implied by a confirmation message. Writing "saved successfully" is redundant.
✔ Changes saved.
✔ Integration complete.
✔ Test suite completed. Three tests failed. View details.
✘ Changes saved successfully.
✘ Awesome! Everything worked perfectly!
Structure: One-line summary + optional follow-up action link.
Case: Sentence case. No exclamation points.
9. Empty states
An empty state must always include two parts: a description of the state, and a suggested action.
✔ No saved tests. Create your first test to get started.
✔ No integrations configured. Add one to begin testing.
✔ No results found. Try adjusting your filters.
✘ Nothing here.
✘ Oops, looks like nothing to show.
Tone: Supportive and action-oriented. Never blame the user. Never use "Oops".
10. Loading and progress states
Use specific, progressive language. Describe what is actually happening.
✔ Loading results…
✔ Running tests (3 of 12 completed)
✔ Fetching configuration settings…
✘ Loading…
✘ Please wait…
✘ Working…
✘ Hang tight…
Use ellipses only for ongoing processes — never to express uncertainty or trail off.
Use parentheses for progress: Running tests (45% done).
11. Link text
Links must describe their destination or action. Never use generic phrases.
✔ View API documentation / Download test report / Learn how to configure alerts
✘ Click here / More info / Details / Here
Case: Sentence case. No period unless the link ends a full sentence.
Button vs. link:
- Button: triggers an action (
Run test) - Link: navigates to a reference or page (
View API documentation)
Do not style links to look like buttons, or buttons to look like links, unless the element both triggers an action and navigates.
12. Punctuation rules
| Element | Period | Notes |
|---|---|---|
| Button labels | No | ✘ Save changes. → ✔ Save changes |
| Field labels | No | ✘ Email address. → ✔ Email address |
| Placeholder text | No | ✘ Enter a name. → ✔ Enter a name |
| Navigation items | No | |
| Toast messages (short) | No | User added |
| Full-sentence notifications | Yes | Suite completed. Three tests failed. |
| Error messages | Yes | Always full sentences with periods |
| Warning messages | Yes | Always full sentences with periods |
| Tooltips and helper text | Yes | When a complete sentence |
| Tab names | No |
Oxford comma: Always use it in lists of three or more items.
✔ Run tests, view results, and download reports.
✘ Run tests, view results and download reports.
No comma splices. Two independent clauses need a period or conjunction, not a comma.
✘ The suite completed, three tests failed.
✔ Suite completed. Three tests failed.
13. Numbers, dates, and units
Numbers: Use numerals in UI text. Spell out only in conversational copy.
✔ Run 3 tests / 5 GB file / 12 retries
✘ Run three tests / five gigabyte file
✔ Conversational exception: You can add up to three integrations.
Dates and times: Use ISO format in technical contexts.
✔ 2025-12-10 14:30
✘ 12/10/2025 / 2:30 PM
Units: Always include the unit explicitly.
✔ 5 GB / 120 ms / 3 minutes
✘ 5 / 120 / 3
14. Grammar rules
Active voice. Write in active voice. Use imperative mood for instructions.
✔ Run the test suite. / Save your changes before exiting.
✘ The test suite will be run. / Changes should be saved before exiting.
Simple tenses. Avoid compound or progressive constructions.
✔ Test completed. / Integration failed.
✘ Your test has been successfully completed. / The integration is currently failing.
No politeness markers. Remove please, sorry, and thank you from all UI copy.
✔ Enter a name. / Test run failed. / Submission received.
✘ Please enter a name. / Sorry, something went wrong. / Thank you for your submission.
No modal hedging. Avoid can, may, might, should when giving instructions.
✔ Run the suite to begin testing.
✘ You may want to run the suite.
US English. Use US spellings throughout.
✔ optimization / color / canceled
✘ optimisation / colour / cancelled
15. Tone by context (quick reference)
| Context | Tone | Example |
|---|---|---|
| Onboarding / setup | Welcoming, clear | Welcome. Let's set up your first test suite. |
| Monitoring / execution | Direct, informative | Running 12 tests. Estimated time: 3 minutes. |
| Error states | Calm, solution-oriented | Connection failed. Try re-authenticating. |
| Success / completion | Positive, concise | All tests passed. |
| Empty states | Supportive, action-oriented | No tests saved. Create your first test to get started. |
| Warnings / destructive | Serious, respectful | Delete workspace? This action cannot be undone. |
16. Terminology consistency
Use one term per concept. Never introduce synonyms or informal aliases.
✔ Workspace — everywhere
✘ Work area, Project space, Workspace — mixed
Use full, approved product names. Never abbreviate unless Marketing has explicitly approved it.
✔ BlazeMeter performance test
✘ BZM test / Blaze test