Content style guide

What's new for content

This page describes the content updates to the content style guide and Design System (components, patterns, and IA) from the most recent 6 months.

We have a list of all updates dating back to May 2025 in GitHub.

Learn more on the Style guide and Design System updates page

August 2025

Dates, times, phone numbers, and addresses

Added an exception to time zone formatting for automated time stamps:

For automated time stamps from the time library used in vets-website (date-fns), the time zone uses the 3-letter format (ex. EDT).

Numbers, signs, and symbols

Changed the page title to Numbers, signs, and symbols
Added the ampersand information (moved from the Punctuation page; no changes to the guidance)
Clarified that there are no spaces around degree symbols or percent signs
Revised the guidance on using “1” versus “one” to only use “one” with certain expressions:

Spell out “one” when it’s used in expressions like one-to-one, one-on-one, one-time, and “one of the reasons…” Use the numeral “1” for all other instances.
Made edits to the rest of the page to align with our style (these edits don’t affect guidance)

Punctuation

Removed the information on ampersands (moved this to the Numbers, signs, and symbols page)
Added an exception for using quotes when referring to buttons, section titles, etc. if the text is already bold:

Note: If the text is already bold (like in some error messages), we can use quotation marks to reference buttons, screens, or section headers.
Made edits to the rest of the page to align with our style (these edits don’t affect guidance)

July 2025

Bulleted and numbered lists

Changed the page title to Bulleted and numbered lists.
Added a new section on links in lists:

Links in lists
• List items can be links in certain situations. But we don’t want to overwhelm people with a long list of links, if possible.
• Not all items in a list need to be a link. It’s okay to have only 1 or 2 items in a list linked.
• If every item in a list is a link, keep the list short (less than 7 items). Every link should go to a different location—don’t link to the same page multiple times in the list.
• When a list item is a link, the entire list item must be part of the link. Don’t link just 1 or 2 words.
Added guidance around when to use conjunctions:

Example of bulleted list with conjunctions
For complex eligibility criteria, we use the conjunctions “and” or “or” at the end of each individual requirement in the list to help make the relationship between the requirements clear. In these cases, use a comma before the conjunction and bold the “and” or “or” at the end of each bullet point. Always separate out lists of “and” and “or” requirements.
We also revised the examples and made edits to the current guidance to fit our style, but these changes don’t impact the guidance itself.

Title tags

Added PII/PHI information

Alternative text for images

Added PII/PHI information

Links

Added PII/PHI information

Button labels

Added PII/PHI information

Page titles and section titles

Added PII/PHI information

Components

Additional info

Specified that titles should be one sentence with no ending punctuation.
Clarified what formatting is okay to use in body copy (lists and links are okay). Removed mentions of using headings in the component (these might be better as accordions).
Updated the guidance on the length of the content to fewer than 500 characters (with spaces) when possible. The component won’t cut off the content at 500, but we should aim to keep these on the shorter side.

Breadcrumbs

Added PII/PHI information

Button, Button group, Button - Segmented, and Button - Icon

Added PII/PHI information

Link, Action, and Collection

Added PII/PHI information

Checkbox, Combo box, Radio button, and Select

Added PII/PHI information

Text input and Textarea

Added PII/PHI information

Search input

Added PII/PHI information

IA

URL Standards

Added PII/PHI information

June 2025

Neutral language

Added “see” and “listen” to the section title: We avoid “view,” “see,” “hear,” and “listen”
Added:

Because we don’t know how a person is accessing the content, we should avoid any interaction-based language.

Bulleted lists

Added numbered lists to the current guidance. We follow the same guidance as with bulleted lists, except that we should only use numbered lists for steps in a process or anything that needs to be in a specific order.
Clarified that ordered list = numbered list and unordered list = bulleted list. You’ll see both terms used interchangeably across the Design System.
Added:

Avoid using “the following” in the list introduction and use a less formal phrase instead. For example, instead of “You’ll need the following documents,” use “You’ll need these documents.”
Added:

Don’t combine the list items’ starting word or phrase with the introduction. For example, don’t introduce the list with “All of these must be true. You’re:” In this case, each item should start with “You’re.” This helps when the content needs to be translated into another language.
Added:

Avoid using sub-bullets. Sub-bullets can make the content harder to scan. If possible, make the item with sub-bullets a separate list.
Note: Bulleted lists can be used in step-by-step lists.
Added:

Note: Don’t use “and/or” in lists. Instead, restructure the content to list all options (for example, “your income and/or net worth” should be “your income, your net worth, or both”).

Punctuation

Added guidance for hint text:

• If the hint text has 1 or more full sentences, add a period to the end of each sentence
• If the hint text is a sentence fragment, don’t add a period
Added guidance for error messages:

• For error messages in individual form fields, don’t add a period at the end of the message unless it has 2 or more full sentences
• For error messages that use the Alert component, add a period at the end of each sentence

Button labels

Removed contradictory CTA examples at the end of the page

Capitalization

Added mobile app capitalization info/exceptions: interface buttons are sentence case and native actions are title case for iOS and all caps for Android

Dates, times, phone numbers, and addresses

Times and time zones: Added mobile app exceptions to times/time zone formatting:

Note: For the mobile app, when times/time zones aren’t hardcoded, the formatting differs from VA.gov due to default formatting in React Native. For example, React Native formats as AM and PM (both letters capitalized and no punctuation) and EST (three-letter format). We make an exception to our style guide for this default formatting.
Times and time zones: Flipped the “We’re open…” example so it follows how we currently word it: “We’re open Monday through Friday, 9:00 a.m. to 6:00 p.m. ET.”
Times and time zones: Combined the two like this/not this examples into one at the end of the bulleted list.
Zip codes: Updated guidance around the extra 4 digits:

• When Veterans fill out their address, we don’t require them to include the extra 4 digits of their zip code. They only need to provide the 5-digit zip code.
• When we provide an address to Veterans, we sometimes include the extra 4 digits of the zip code. If we include the extra 4 digits, use a hyphen (ex. 12345-6789).

Word list

Added the “MFA” acronym to “multifactor authentication”
Updated these existing entries:

condition vs. disability: Added: For non-Veterans, like beneficiaries and dependents, we use “disability” (or “disabled” depending on the context) to describe an illness or injury that affects your mind or body. Default to people-first language in general content that describes individuals with a disability. For example, “Was this trust created for a Veteran’s child who was seriously disabled before age 18?”
Learn more in the Health content section

disability rating: Specifying this is for Veterans only

Added these new entries:

and/or: Don’t use “and/or” in lists or body copy. Instead, restructure the content to list all options (for example, “your income and/or net worth” should be “your income, your net worth, or both”).

illegal: Avoid using the term “illegal.” Instead, our preferred term is “not allowed by law.” Don’t use “illegal” to describe a person.

please: We’re moving away from using “please” in most cases. Avoid using “please” as a default and only if needed in a specific situation. This is a change that we’re working to address across our current components.

power of attorney (POA): “POA” is capitalized. Contact the subject matter experts or legal before using this term to make sure we’re using it correctly.

required by law and not allowed by law: These are our preferred terms to describe a legal requirement or something that is against the law.

user: We should avoid the term “user” or “users” and instead use “Veterans” or “people” (when referring to a more general audience). “Users” can have a negative connotation and focuses only on how people are using our products. This is a change that we’re working to address across our current content.

Removed the “Premium” entry

Button, Button group, Button - Segmented, and Button - Icon

Removed contradictory CTA examples at the end of the content considerations

Address block

Zip codes: Updated guidance around the extra 4 digits:

• When Veterans fill out their address, we don’t require them to include the extra 4 digits of their zip code. They only need to provide the 5-digit zip code.
• When we provide an address to Veterans, we sometimes include the extra 4 digits of the zip code. If we include the extra 4 digits, use a hyphen (ex. 12345-6789).

Patterns

Email addresses

Updated and added new examples for telling people why we need their contact information:

• We may use your contact information to contact you if we have questions about your application.
• We may use your contact information to contact you if there’s an issue with your application.
• We may use your contact information to contact you if we need more information.
Made other minor edits to align with our current style.

Phone numbers

Same updates as the email address pattern

Addresses

Removed “or 9-“ from the postal code error message 3: “Enter a valid 5-digit zip code”

May 2025

Destigmatizing language for weight

Added this new page to the Health content section in the content style guide

Neutral language

Revised guidance to match our current practices of using “select” instead of “click,” “tap,” etc.:

People can use several different types of interactions for the same task. So, we use “select” instead of “click,” “press,” or “tap.”<p> Examples:<p> • In buttons, use “Select Submit” instead of “Tap the Submit button”
• In links and navigation, use “Select My VA” instead of “Click on My VA“
• In phone extensions, use “Select 1” instead of “Press 1”
• In step-by-step instructions, use “Select Save” instead of “Click Save”

Word list

Added and revised entries:

click: Avoid using “click” and “click here.” Instead, follow these formats:
• Link the entire call to action where relevant, like this: Find an accredited representative to help you
• Use “select” to point someone to a specific place in the UI, like this: In your account dashboard, select Profile
Learn more in the Neutral language section of the style guide

delete: Use the word “delete” instead of “remove.” For example, “Delete file.”
Learn more in the Files pattern

upload: Use the word “upload” instead of “add.” For example, “Upload file” and “Upload another file.”
Learn more in the Files pattern

Error messages - Feedback and Writing for SEO

Removed instances of “click” on these pages and changed to “select.”

Links

Added information on why we put links on their own line instead of using embedded links:

Too many embedded links can be distracting or overwhelming to people with traumatic brain injuries or other cognitive impairments. We put links on their own line to help make the page easier to scan and the intention of the link as clear as possible.
Clarified guidance about links opening in a new tab (this should only happen under specific circumstances, explained in Components):

Note: If a link needs to open in a new tab, add “(opens in a new tab)” to notify users. Don’t use the new window icon unless there are space constraints.
Review guidance on when to open links in a new tab in the Components section

Punctuation

Added guidance on using punctuation with quotation marks:

Periods and commas go inside the quotation marks, even if they’re not part of the quoted text. All other punctuation (em dashes, question marks, colons, parentheses) go outside the quotation marks unless they’re part of the quoted text.

Bold & italic text

Added guidance on when to bold punctuation:

Punctuation with bold text
For punctuation following bold text:
• If the bold text is an introduction, the colon or period following it should also be bold (ex. the colon after “Note:” or the period after a list item introduction, “Be concise. Use as few words as possible…”).
• If the bold text is a full sentence, bold any punctuation within or at the end of the sentence.
• If the bold text is only part of a sentence, don’t bold punctuation that isn’t part of the bolded phrase (ex. “Select Continue, then answer the remaining questions).”

Dates, times, phone numbers, and addresses

Added guidance on how to write date ranges:

Write out date ranges using sentence construction in body copy: This will be available from December 1, 2025, to December 31, 2025.
Note: Be intentional when picking “from/to,” “from/through,” or “between/and” for date ranges. Each option can mean different things, so pick the option that best matches your needs.
Added guidance on commas after dates:

Add a comma after the year when using the full construction, unless the date is the end of the sentence. If the date is at the end of the sentence, use the punctuation you’d normally use (period, question mark, colon, no punctuation).

Components

Link

Clarified guidance on when links can open in a new tab (only under specific circumstances):

Open links in the same window, with exceptions. Links on VA.gov should open in a new tab only if clicking the link will cause the user to lose progress or data. This should be avoided when possible. In all other cases, links should open in the same window.
Review guidance on link text in the content style guide for more information

Last updated: Oct 15, 2025