Language

Language guidelines

Clear, consistent, and concise language is the guiding principle for all content in an application. Application builders should avoid customizing the defaults that come from the platform, unless done so to meet the contextual needs of the industry, business, or user.


Capitalization

  • 'Title case' is used for application names, proper nouns, object and case types, app-generated page titles (e.g., "My Worklist"), and navigation items referencing those pages (e.g., "Go to My Worklist"). User-generated object and case titles (e.g., "Pick up groceries") are not proper nouns and would follow the 'Sentence case.' rule.
  • 'All caps' is used for status badges, and the application name.
    NOTE: Screen readers interpret hand-typed caps as abbreviations, so use CSS to transform to 'uppercase' instead.
  • 'Sentence case' is the default for all other non-user-generated text.
  • 'CamelCase' is never used.

Numbers

  • Numbers typically should be represented by no more than 2 decimal places.
  • Numeric values and currencies within a table cell or group of similar type values (e.g. a balance sheet) must follow the application locale’s text alignment practices. For example, in English, numbers will be aligned to the right. (e.g. $100.00)
  • Numbers paired with text follow the reading direction of the application locale's language. In English, this means to the left. (e.g. 1 million)
  • Decimal places should be uniform in compared data. (e.g. In a table column, if one cell is 1.22, the following cell should be 1.50 NOT 1.5)
  • 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 80em long (about 80 characters).
  • Read-only labels and single-line values should display side-by-side, instead of being stacked.
  • Single-line text that overflows its max-length should be condensed down into an ellipsis. Multi-line text that overflows its line should avoid hyphenation to wrap words. Additionally, a set height should be determined for that multi-line text. Condensed text must have a user-driven method to expand that text (e.g. Tooltips, Modals, Popovers, expandable height or width, etc.)
  • All button and badge text should be center aligned.
  • All remaining text should align to the reading direction of the application locale's language. In English, this means it would be aligned to the left.
  • Text should never be justified in any direction.

Last updated: Apr 2020

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.
  • 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. (e.g. '0 items', '1 items', '2 items')
  • Read aloud and test content decisions with users.
Grammar examples

Last updated: Mar 2020

Form and read-only labels

All labels must be concise and clearly written, as Pega uses them for field inputs and read-only displays. Visible and accessibly-generated fields labels are required and must match exactly for the sake of speech input users.

Finally, avoid words describing what is grasped from the value's format.

IncorrectLast statement date:
Next month's bill total:
Mar 31, 2020
$1,200.00
CorrectLast statement:
Next month:
Mar 31, 2020
$1,200.00

Last updated: Apr 2020

Internationalization

Markets, countries, and employees are no longer restricted to a language or location. Plan for these various linguistic, visual, and directional challenges at the beginning of the design process.

  • Design form fields, labels, messaging areas, buttons, headers, navigation, etc. to allow for a flexible amount of space and while maintaining readability in the more robust languages. (A good rule of thumb is to account for an extra 50-100% of length.)
  • Plan for bi-directional layouts as necessary to aid those more familiar with those patterns.
  • Show dates and times in the user's preferred format. More about date and time.

Last updated: Apr 2020