Constellation content guidelines

The Constellation design system provides designers the right combination of workflows, patterns, and components needed for end-users to complete work quickly and accurately. But Constellation still offers you flexibility to communicate in ways that make sense for your business and your users. To communicate effectively, it’s important to follow standardized best practices to create intuitive and understandable language within your application.

Refer to the below guidelines to ensure your applications follow best practices for a clear end-user experience. These guidelines were compiled with the Constellation design system in mind, but may also be applied to Theme Cosmos and UI-Kit applications.

For additional guidelines on writing for UI, refer to the Microsoft Style Guide.

Ensure text is direct and conversational, without sounding too casual or using slang. Use simple, easy to understand, common terms.

• Incorrect: “Elaborate”, “Modify”
• Correct: "Describe", "Edit"

Write crisply. Keep text short and to the point, while still being clear. Avoid filler words, such as: “itself”, “quite”, “very”, “mostly”, “definitely”, “actual”, and “particular”.

• Incorrect: “Select the particular service the customer needs.”
• Correct: “Select the service the customer needs.”

Avoid overusing pronouns, such as “it”, “they”, “these”, and “those”. Repeat the term the pronoun is referring to, if necessary.

• Incorrect: “The service is tied to your account. It will be deactivated if you cancel it.”
• Correct: “The service is tied to your account. Your account will be deactivated if you cancel the service.”

Generally, avoid using the word "please". Save this for initial pleasantry (such as in a customer service script), but avoid repeating after, unless there is an explicit need to be polite in that context, such as when the user is in a difficult situation and may be frustrated.

• Incorrect: “For more information, please refer to the Pega Documentation site.”
• Correct: “For more information, refer to the Pega Documentation site.”

Avoid using exclamation marks within the UI, especially in error messages. In confirmation messages, such as toast messages, use exclamation marks only when confirming a positive action that makes progress for the user.

• Incorrect: “An error occurred!”
• Correct: “An error occurred.”
• Correct: “Changes saved!”

Avoid using acronyms that are not well-defined within your organization. When in doubt, spell out the full acronym.

• Incorrect: “DB”, “BAP”
• Correct: “Database”, “Business auto policy”

Do not use emotive language. Use alternatives with neutral or no other connotations.

• Incorrect: “Terminate the service”
• Correct: “Cancel the service”

In a list, ensure list items follow parallel structure. For example, all list items must begin with a noun or a verb, and should not alternate between the two.

• Incorrect: “Location change, Was not satisfied with provider, Other"
• Correct: "Location change, Dissatisfaction with provider, Other"

Avoid ending nouns with an “(s)” when the noun may be singular or plural. Include the “s” without parentheses.

• Incorrect: “Select the service(s) to cancel.”
• Correct: “Select the services to cancel.”

Place the word “only” directly before what you want it to modify. Consider how the meaning changes in the following sentences, based on where “only” is placed within them:

• “Only an administrator can open the XML files.” This means administrators are the only users who can open the XML files.
• “An administrator can only open XML files.” This means the only thing that Administrators can do is open XML files.

Use em dashes (—) in place of parentheses to add additional emphasis to a phrase.

• Incorrect: “Design patterns-configured combinations of components-are used within the Constellation design system.” This example uses hyphens (-) instead of em dashes.
• Correct: “Design patterns—configured combinations of components—are used within the Constellation design system.“

Use en dashes (–) for mathematical purposes (as a minus sign, to show negative numbers, to show a range, etc).

• Incorrect: “The school accepts children ages 5-10.” This example uses a hyphen (-) instead of an en dash.
• Correct: “The school accepts children ages 5–10.”

Use hyphens after prefixes and to connect words in a sentence or phrase, when appropriate. For additional guidance on when it is necessary to use hyphens, see the Microsoft Style Guide.

• Incorrect: “The Constellation design system provides out–of–the–box components and patterns.” This example uses en dashes (–) instead of hyphens.
• Correct: “The Constellation design system provides out-of-the-box components and patterns.”

Use colons when introducing words or phrases in a sentence. Use colons in table headers to indicate filters that have been set on the table, or what information the table is displaying (for example, “Assignments: All”).

• Incorrect: “Select one of the following—red, blue, green, yellow."
• Correct: “Select one of the following: red, blue, green, yellow."

For more guidelines on grammar, refer to the Microsoft Style Guide.

Use sentence case as the default standard for most non-user generated text in UI.

Use title case for:

• Proper nouns
• Application names
• Case Types
• Branded product names (such as Pega Platform)
• Unique Pega concepts (such as Case Designer)

You may use CamelCase within code, but do not expose CamelCase to end-user interfaces.

Avoid using all caps, as screen readers interpret hand-typed caps as abbreviations. Instead, you can use italics (sparingly) to bring attention to certain words. Additionally, avoid using CSS to transform to 'uppercase'.

Use lower case when spelling out acronyms. Only use title case when the acronym is a proper noun.

• Incorrect: UI (User Interface)
• Correct: UI (user interface)
• Correct: CDT (California Department of Technology)

For more guidelines on capitalization, refer to the Microsoft Style Guide.

Repeat terms previously mentioned in the UI for consistency, when possible.

• Incorrect: "Add a vehicle”, “Enter an additional driver"
• Correct: “Add a vehicle”, “Add a driver”

Avoid industry-specific terminology your users may not be familiar with. Ensure you are using clear, generic terms that are understandable for your audience.

• Incorrect: “Enter any sound bites used to sell the product.”
• Correct: “Enter any points you made to describe the value of the product.”

Avoid using acronyms your users may not know. If using an uncommon acronym, spell out the acronym first.

• Incorrect: “View the ATR.”
• Correct: “View the average time to respond (ATR).”

When referencing a named item in the UI, such as a Branch name, Assignment name, or Case Type name, put the name in quotes to improve readability.

• Incorrect: Merge branch test-branch.
• Correct: Merge branch “test-branch”.

Use “Select” when the user is selecting from provided options, and use “Choose” when the user is choosing the outcome themselves, with no options to choose from.

• Incorrect: “Choose a package from the options below.”
• Correct: "Select a package from the options below.”

Avoid using “could”, “should”, and “would” to avoid ambiguity.

• Incorrect: “The start date should be in the format mm/dd/yyyy.”
• Correct: “The start date must be in the format mm/dd/yyyy.”

For guidance on selecting the right components to use in a form for different use cases, see Constellation design system component documentation.

When presenting options in a field group for users to select from (e.g., radio buttons, combobox) evaluate if an "other" option is necessary.

• Example: "Reason for return: Received wrong item, Received broken item, Was not satisfied with purchase, Other (enter details below)"

Display action items only after you have provided appropriate context for the action the user is about to take.

• Example: Provide a "modify payment" option only after the user is shown the current payment options.

Group related fields together in a form. Include a header for your field group to visually categorize information.

• Example: If the user must select from a set of radio buttons, and then describe their selection in a text input, place these two fields together.

Avoid using verbs in field labels. Instead, simply state the noun.

• Incorrect: "Provide accident details"
• Correct: "Accident details"

Generally, word field labels as statements instead of questions. Use questions sparingly, such as in customer service contexts.

• Incorrect: “What is the reason for your payment?”
• Correct: “Reason for payment”

When writing field label text, be specific about what the field is collecting from the user.

• Example: For a "move service" Case Type, address input fields should specify what address to enter: “New address” or “Old address”.

Optimize for fewer words or characters in your labels, as long as doing so doesn’t alter meaning.

• Example: "Enter card details" has the same meaning as "Enter your card details", but is more concise.

• Example: "Details of accident" has the same meaning as "Details of the accident”, but is more concise.

Use form instructions to provide general instructions for how to complete a form flow.

• Example: “Enter the vehicle information below. Some information may be automatically added if on-file”.

Use field group instructions to provide additional details specific to completing a field group within a form.

• Example: “Download and complete the vehicle document below, then upload the completed file.”

Use a tooltip to show the title of an item that has no text (e.g icon button) or to show supplemental overflow text (in cases where single line text is very long).

• Example: A pencil icon may have a tooltip that reads “Edit” when hovered.

Use a toast to inform users that an event related to an action they took has happened off-screen (e.g., a change was saved, records were successfully uploaded, an import failed, etc).

• Example: “Changes saved!”
• Example: "Records failed to upload. View error."

Use helper text to help users understand how to complete an input.

• Example: “Select two options below”.

Use an additional information button (coming soon) to provide reasoning on why information is needed or where to find information.

• Example: "Your account number is located at the bottom left of your billing statement."

Ensure language in toasts is concise and straightforward, because toasts appear for only a given number of milliseconds before they disappear.

• Incorrect: “The changes were successfully saved!”
• Correct: “Changes saved!”

When appropriate, link toast message content to the page the message is referring to, so users can see the full context.

• Example: In the following toast message: “Records failed to upload. View error.”, the user can select “View error” to go to the page where the failure occurred and see the error details.

Punctuate toast messages with an exclamation mark only when confirming a positive action that makes progress for the user. In all other cases, use a period.

• Incorrect: “An error occurred!”
• Correct: “An error occurred.”
• Correct: “Changes saved!”

In an error message, first describe how to resolve the error. Then, if needed, describe what the error is/how it occurred.

• Incorrect: “The password you entered is too long.”
• Correct: “Enter a password between 3-5 characters.”

Use a banner error message when displaying errors that occur at the system, field group, or form level.

• Example: “Resubmit when you are online. You are currently offline and cannot submit your request” is a high-level system error.

Use field error messages when displaying errors specific to one field.

• Example: “Date entered must be before June 2023” is an error specific to a date input field.

Split terms and conditions into bullets or separate paragraphs to break up large blocks of text and make it easier to read. Avoid displaying the text as one large paragraph.

Order columns in a table so that the most general and important information comes first, when possible.

• Example: When listing available care providers in a table, you may display the following information in this order: provider name, specialty, location, phone number.

Use badges in tables only when displaying a case’s status. Use plain text for all other information.

• Example: In a status column, you may have a badge that reads “Active” or “In-progress”.

Use the address field type to collect address formats by country. For displaying addresses, view guidance on how to format addresses by country.

Avoid writing dates in MM/DD/YYYY or DD/MM/YYYY format, as the format varies by country and the date can be misinterpreted. Refer to guidance on date formatting.

Use bullet points to separate pieces of metadata in the UI.

• Correct: “File format: CSV • File size: 5KB"

Reference the Pega glossary for a list of common Pega terms and definitions.