Language

Language guidelines

Clear, consistent, and concise language is the guiding principle for all application content. 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.

Pega follows the Microsoft Style Guide for language, formatting and capitalization.

Capitalization

Capitalization in software is typically treated inconsistently. This is due, we believe, to a confusion between how the objects in software programming—such as instances of classes—are often incorrectly displayed as proper nouns and title-cased. For the end-users of applications, objects and actions should be sentence-cased.

For instance, in class-based programming, a "document" object is sometimes displayed as if it is a proper noun ("Document"). However, it should not appear as a proper noun to end-users (e.g. "Create a new Document" is wrong. "Create a new document" is correct.

Pega defaults capitalization for objects so they make sense for end-users and business people, rather than as developers working in code might.

  • 'Sentence case' is the default in Pega. This standard includes:
    • Labeling of UI elements such as labels and picker choices in forms, or data in read-only formats
    • Case types and data objects
    • Individual cases titles, for instance “Johnson mortgage”
    • Assignments
    • Steps
    • Stages
  • 'Title case' is used for:
    • Application names
    • Proper nouns (names of people, product names, organizations, or places: John Adams, Boston Red Sox, New England)
    • Titles of list pages (e.g., "My Worklist")
    • Document titles
    • Names of spaces
    • Navigation items referencing title-cased pages (e.g., "Go to My Worklist")
  • 'All caps' is used for status badges. To avoid accessibility issues, always use CSS to achieve all-capitalization.
  • 'CamelCase' is never used on end-user screens

Numbers

  • Numbers typically should be represented by no more than two 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 always use proper separators (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: Jul 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