Content
Clear, consistent, scannable language is as much a design decision as color or spacing. These guidelines define how we write across every surface in WS Connect.
Voice & tone
Voice is fixed — it's who we are. Tone flexes with context — it's how we sound in a given moment. WS Connect serves insurance professionals making consequential decisions, so we adopt a formal-but-human register: restrained, factual, and precise, with just enough warmth to feel like a trusted colleague rather than a cold system.
- Clear and direct — no hedging, no filler
- Precise about insurance concepts — we trust our users' expertise
- Helpful without being patronising
- Consistent in second person ("you," "your policy")
- Human — contractions are fine; robotic formality isn't
- Casual or chatty (we're not Slack)
- Corporate-stiff ("Please be advised that…")
- Jargon-heavy toward non-specialists
- Overly apologetic ("Sorry, something went wrong")
- First person from the system ("We are saving…")
Tone adjustments by context
| Context | Tone shift | Example |
|---|---|---|
| Confirmations & success | Warm, brief, affirming | "Policy saved." not "The policy record has been successfully persisted." |
| Errors & warnings | Direct, non-blaming, action-oriented | "Coverage dates overlap — adjust the end date before saving." |
| Empty states | Encouraging, helpful | "No policies yet. Add a client to get started." |
| Destructive actions | Calm, specific, no pressure | "Delete this policy? This can't be undone." |
| System outages | Apologetic but factual | "We're having trouble connecting. Try again in a few minutes." |
Writing for clarity
Every word competes for attention. Write with intention: active, second-person, jargon-free, and appropriately brief.
Capitalization
Inconsistent capitalization degrades perceived reliability. Use two patterns only — never mix them arbitrarily.
| Surface | Rule | Examples |
|---|---|---|
| Navigation tabs, menu labels, button labels, column & group headers, link text in nav | Title Case | Add Policy · Renewal Dates · Client Services · View All Claims |
| Page titles, field labels, placeholder text, body copy, bullet points, inline instructions, toast/alert messages, hyperlinks in prose | Sentence case | Policy details · Effective date · Enter the named insured · Your session will expire in 5 minutes. |
| Proper nouns, acronyms that have become words | Always capitalised | Woodruff Sawyer · ACORD · NASA · E&O |
| Insurance-specific acronyms on first use | Spell out, then abbreviate | "Errors & Omissions (E&O)" — thereafter E&O is fine |
Active vs. passive voice
Default to active voice. The exception: use passive to front-load the most important keyword in headlines, subheads, lead sentences, and link text — because users scan the first 7–11 characters.
- Add a named insured
- Review coverage limits before submitting
- Your renewal is due in 30 days
- Download the certificate
- A named insured should be added
- Coverage limits should be reviewed
- Renewal is due in 30 days for your policy
- The certificate can be downloaded
Word choice
Brief but not cryptic. Always ask: would a target user understand this without explanation?
| Instead of | Use | Why |
|---|---|---|
| Utilise | Use | Shorter, plain English |
| In order to | To | Two fewer words, same meaning |
| At this point in time | Now | Removes filler |
| Please be advised | (just say it) | Corporate filler — cut it |
| Submit | Save, Add, Send, Apply | "Submit" is a friction word; be specific about what happens |
| Click here | Download the certificate / View policy | Descriptive link text aids scanning and accessibility |
| Error occurred | Specific cause + action | Vague errors frustrate; name the problem |
| LOC (without explanation) | Line of coverage (LOC) | Spell out acronyms on first use |
Calls to action
Keep CTAs to four or five words. Lead with a verb. Convey value — what happens when the user clicks. Avoid friction words.
- Save policy
- Add client
- Download certificate
- Start renewal
- View coverage details
- Submit
- OK / Confirm
- Click here to download the insurance certificate document
- Proceed
- Yes / No (on their own)
Button labels in destructive confirmation dialogs should mirror the dialog title: if the title is "Delete policy?" the button should say "Delete policy" — not "Yes" or "Confirm." This removes any ambiguity about what the action does.
Pronouns & contractions
- Your session expires in 5 minutes.
- You don't have access to this policy.
- It's saved — you can close this tab.
- We'll notify you when it's ready.
- The user's session expires in 5 minutes.
- The system cannot locate the requested policy.
- The record has been saved successfully.
- Notifications will be sent upon completion.
Scanning & readability
Users scan, not read. Comprehension drops sharply as sentences lengthen. Design copy for scanning the same way we design layout — with hierarchy, rhythm, and deliberate density.
Sentence length
Vary sentence length between 8 and 20 words. Comprehension is ~100% under 8 words, stays above 90% at 14 words, and collapses below 10% at 43-word sentences.
Paragraph structure
- One thought per sentence — keywords first, unnecessary words cut.
- One theme per paragraph — open with a topic sentence; keep to one–four sentences maximum.
- Front-load — in headlines, subheads, and list items, put the most important word or phrase within the first 7–11 characters. That's where eyes land first on a scan path.
Coverage dates must not overlap. If two policies cover the same period, adjust the end date of the earlier policy before adding the new one.
Please note that in the event that two or more policies are found to have coverage dates that overlap in any way, it will be necessary for the user to navigate to the earlier of the two policies and manually adjust the end date so that it falls prior to the start date of the subsequently added policy record before the system will allow the save operation to proceed.
Scanning aids
- Headlines & subheads — use them to break long pages into named sections. Keep them in Sentence case for body areas, Title Case in navigation.
- Bulleted lists — use for three or more parallel items. Don't use bullets for single items or run-on sentences dressed up as bullets.
- Bold for emphasis — sparingly, for the single most critical word or phrase in a paragraph. Over-bolding is noise.
- Tables — for structured, comparative data. Not for prose formatted to look like a table.
UI message patterns
Every message the system produces — success, error, warning, empty state, confirmation — follows a consistent structure. Predictability reduces cognitive load.
Success messages
Brief, past-tense confirmation. Name what was saved. No exclamation marks.
- Policy saved
- Certificate sent to broker
- 3 documents uploaded
- Success! Your data has been saved!
- Operation completed successfully
- Done
Error messages
Name the problem specifically. Never blame the user. Always provide a next action.
- Coverage dates overlap — adjust the end date
- Effective date is required
- File size exceeds 10 MB — compress or split the document
- An error occurred
- Invalid input
- Error 422: Unprocessable entity
- You did something wrong
Warnings
Warn before a problem, not after. State the consequence first, then the action.
Empty states
Empty states are onboarding moments. Tell the user what belongs here, and give them one clear action to start.
| Situation | Title | Body | CTA |
|---|---|---|---|
| No clients yet | No clients yet | Add your first client to start building their policy portfolio. | Add client |
| No search results | No results for "Acme Widgets" | Check the spelling or try a broader search term. | — |
| No documents | No documents uploaded | Upload binders, certificates, and signed applications here. | Upload document |
| No activity | No activity yet | Changes to this policy will appear here. | — |
Inclusive language
Inclusive language expands reach and reduces cognitive friction. These aren't style preferences — they affect whether users feel the product is made for them.
- Plain language first — prefer common words over technical terms, unless technical precision is genuinely required. If an acronym has become a word (ACORD, E&O), use it; otherwise spell out first.
- Avoid idioms and metaphors — "ball in your court," "boil the ocean," and similar phrases don't translate and can confuse non-native English speakers.
- Gender-neutral defaults — use "they/them" for singular third-person references when gender is unknown. Use "broker" not "the broker and his team."
- Ability-neutral language — avoid "click" where "select" or "choose" works; avoid "see" where "view" or "find" works. This improves screen-reader copy and voice interfaces simultaneously.
- No metaphors of violence or harm — avoid "kill," "nuke," "blow up," "cripple" for system actions. Use "delete," "clear," "reset," "disable."
| Avoid | Use instead |
|---|---|
| Click the button | Select, choose, or tap the button |
| Master / slave | Primary / replica, leader / follower |
| Whitelist / blacklist | Allowlist / blocklist |
| He/she when referring to users | They / the user / brokers |
| Kill the process | Stop / cancel the process |
| Sanity check | Review, verify, confirm |
Mechanics & style reference
A quick-reference for formatting decisions that recur throughout the product. When in doubt, Chicago Manual of Style is the arbiter.
Dates & times
| Element | Format | Example |
|---|---|---|
| Full date | DD Mon YYYY | 14 Jan 2026 |
| Short date | MM/DD/YYYY | 01/14/2026 |
| Month + year | Mon YYYY | Jan 2026 |
| Time | 12-hour with am/pm lowercase | 2:30 pm, 11:00 am |
| Date + time | Full date, then time | 14 Jan 2026, 2:30 pm PST |
| Relative date (recent) | Conversational | Today, Yesterday, 3 days ago |
| Relative date (far) | Full date | 14 Jan 2026 (not "12 months ago") |
Numbers & currency
| Element | Rule | Example |
|---|---|---|
| Currency | $X,XXX — no decimals unless cents matter | $1,250,000 not $1250000.00 |
| Large numbers | Abbreviate in compact UI; spell out in prose | $1.25M (UI chip) vs $1,250,000 (detail) |
| Percentages | % with no space | 12.5% not 12.5 % |
| Numbers below 10 | Spell out in prose, digits in UI data | "three documents" in a message; "3" in a table cell |
| Phone numbers | (XXX) XXX-XXXX | (415) 391-2141 |
Punctuation
- Oxford comma — always use the serial comma: "policies, endorsements, and certificates."
- Sentence-ending punctuation in UI — use a full stop on multi-sentence alert/error body text. Omit on single-phrase labels, toast messages, and button labels.
- Ellipsis — use … (a single character, not three full stops) to indicate truncated text or in-progress states ("Saving…"). Never use for trailing off in instructions.
- Em dash — use — (no spaces) to set off a clarifying clause in prose. Avoid in UI labels.
- Ampersand (&) — acceptable in navigation labels and column headers where space is tight; spell out "and" in body copy.
- Exclamation marks — avoid in product copy. One per page maximum if tone genuinely calls for it.
Content strategy
A style guide without a scoring framework is aspirational. Content quality in WS Connect maps to five measurable dimensions of the NPCI Content model — each with objective sub-heuristics that can be audited, scored, or automated.
Clarity, scannability, actionability, and mechanics are objectively measurable — readability score (Flesch-Kincaid), average sentence length, CTA word count, and error rate can all be automated in a linting or review pipeline. Consistency and voice require human judgment but can be spot-audited against this guide.
Style guide as enforcement
A style guide is only as useful as its adoption. To keep content quality consistent across teams and over time:
- Treat content decisions like design decisions — review copy in design reviews, not just as a final check.
- Write hot, edit cold — draft freely, then return with fresh eyes. Have a second reviewer read it aloud; awkward phrasing reveals itself when spoken.
- Refer ambiguous cases to this guide first — if this guide doesn't cover it, Chicago Manual of Style is the default arbiter.
- Update the guide when a new pattern is established — don't let undocumented exceptions accumulate into inconsistency.