Language and text

Language

Language, voice, and tone have a large effect on the usability of an application. Clear, concise language is essential and should be the guiding principle for all language in an application.

Last updated: May 2017

Grammar

Pega interfaces are grammatically correct, friendly, and professional. Below are a few items to consider when writing for Pega applications:

  • Use the active voice, not the passive voice.
  • Be concise. Do not use flowery language, but strive to be clear.
  • Use a positive tone. When writing error messages, do not assign or take blame.
  • Use full words instead of contractions (e.g., “do not” instead of “don’t”)
  • Avoid abbreviations and jargon.
  • When an object could be singular or plural, use the plural version for its label.
Grammar examples

For more information on correct grammar in Pega applications, check out the technical writing resource library.

Last updated: May 2017

Tone

Pega’s tone can be summed up in three words:

  • Passion
  • Power
  • Partnership

While these are the guiding principles, the tone within a user interface may vary based on the role it serves. This diagram shares how the tone of various elements relate in an interface.

Tone examples

Last updated: Jun 2017

Text standards

Ordered and structured text reveals what to expect and how to complete goals.

Text size

  • Standard (14px) is used for input text, descriptive paragraphs, help text, header level 3, in-card accordions, fieldset legends, navigation, buttons, and the application name.
  • Large (16px) is used for the header level 2, card headers, chart titles, and mobile input text (to prevent iOS zooming).
  • X-large (18px) is used for the header level 1, and page headers.
  • XX-large (24px) is used for the scorecard, and heads-up display status text.
  • Small (13px) is used for labels, field-level errors, field descriptions, tooltip text, and placeholders.
  • X-small (11px) is used for the chart legend text, and sparkline text.
  • XX-small (9px) is used for the statuses, tags, and the mobile fixed bottom nav text.

Font weight

  • Normal (400) is used in everything but headers at level 2 & 3, application name, statuses, tags, and primary buttons.
  • Bold (700) is used for headers at level 2 & 3, primary buttons, statuses, tags, stand-alone status messages.
  • Extrabold (800) is used for application names.

Capitalization

  • Sentence case is the default casing for anything not listed below.
  • Title case is used for case types (e.g., “User Story”, not “User story”), page headers and navigation items referencing those pages (e.g., "My Worklist" and "Go to My Worklist"), people, places, things, and book, speech, or article titles (e.g., “War and Peace”, not “War and peace”).
  • All caps is used for statuses, tags, and the application name. NOTE: Type “All caps” items in sentence case. Use formats / CSS to transform to “uppercase” as some screen readers read hand-typed caps as an abbreviation.

Numbers

  • Numbers typically should be represented by no more than 2 decimal places.
  • Stand-alone numeric values are typically aligned to the right, especially when showing decimal places. When the numeric value is paired with text, the value should follow the application locale’s text alignment practices.
  • If an application or data item does not have a defined currency type, it should be represented by the user’s local currency.
  • Numbers should use the proper separators whenever possible (e.g. 1,000 not 1000).

Presentation and overflow

  • A line’s maximum length in a paragraph should be no more than 35em long (about 35 characters).
  • All text uses a line-height of 1.5 times the size of itself (e.g. 10px font has a 15px line-height). First-level headers use a line height that is 1.25 times its size.
  • Single-line text that overflows its max-length should be condensed down into an ellipsis. Multi-line text that overflows its line should never use hyphenation to wrap words. Additionally, a set height should be determined for that multi-line text, which should also end in an ellipsis. Any condensed text must have an alternative way to review the full text that has been masked.
  • All text should be left-aligned, except for text on buttons (not navigation) or tabs, which will be center-aligned. Never use justified text. Additionally, RTL languages use right-alignment by default.

Last updated: Jun 2017

User messages

Instructions, help, and tooltips

Design your experience so that reading the instructions is not required for completing a task. Instructions should let the user know what to do as part of a task. They should offer more information than the title of the task.

Instructions at the top of a page should be relevant to the entire action or assignment. Tooltips on a specific field should be contextual only to that field.

Instructions, and tooltips for actions should be written as actions or commands. Examples for a tooltip would be: "View item", "Edit record", or "Configure section". Instruction examples

For more information on correct grammar in Pega applications, check out the technical writing resource library.

Errors

Error messages should precisely state what the problem is, and how the user can solve it. They do not place blame on users or the application. Messages should end in a period. Examples: "Name is required. Fill in a value for name." "Event cannot be in the past. Choose a future date."

Do not show property names in an error message unless it is a development application. Override error messages to be more descriptive and understandable to non-technical users.

Error examples

Confirmation

Confirmation messages should succinctly state to the user what has happened. Messages should end in a period. These can be configured to be dismissed.

Examples: "Your loan application has been submitted." "The expense has been approved."

Confirmation example

Last updated: Jun 2017

Work areas and containers

Work areas

Work areas (or assignment areas) should have descriptive names that state precisely what the result of an action should be. The structure should be [Action verb] [item having action taken on it].

Examples: "Approve expense", "Edit location details".

Work example

Modal dialogs

Modal dialogs should use the same standards as work areas because they are actions. The heading should be [Action verb] [item having action taken on it].

Examples: "Review location details", "Add variable".

Modal example

Containers, cards and sections

Container, card, and section names should be noun-based descriptors of the content.

Examples: "Loan terms", "Expenses for this week".

Container example

Tabs

Tabs should be one-word descriptions of the content. If a tab has only one “section” of information in it, the name of the tab can function as the header. If a tab has more than one “section” of information, name each section.

Examples: "Loans", "Expenses".

Tab example

Last updated: May 2017

Labelling

Inputs

Labels should accurately and uniquely describe a field. Understanding the label should not be dependent on reading the other labels in a form or on the screen.

  • Not: "End”, it is too contextual.
  • Do: "Start date of event", is much more clear.
Input label examples

Buttons and links

Buttons are used to perform actions. They should be named as [Verb][Object]. In some cases, only [Verb] is necessary.

Button examples

Links are used to direct users to a new location. They should be named as [Verb][Destination or object] or as the name of an object or destination.

Link examples

Stages and steps

Stage names should describe the contents of the actions taken in that stage. Stage names should be nouns, gerunds, or adjectives. Examples are "Approval", "Active", and "Processing".

Stage label examples

Steps inside a stage (usually shown in a screen flow) should describe the action being taken in that particular step. Step names should usually be nouns or gerunds; however clarity and reducing unneeded words is more important than sticking strictly to a noun. Examples are "Repayment plan setup", and "Review and submit".

Step label examples

Last updated: Jun 2017

Localization considerations

Pega applications need to support the needs of users who speak different languages and from different cultures. Some languages tend to be longer than others (French and German for example). When writing labels and headers in your UI, make sure that there is space if the label or header were 150-200% larger.

Last updated: Jun 2017

Next: Interaction