Language

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.

  • 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 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).
  • 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.

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

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 that describe what the user may grasp from the value's format.

Do thisNot this
Last statement: Mar 31, 2020Last statement date: Mar 31, 2020
Next month's bill: $1,200.00Next month's bill total: $1,200.00

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.

Standard naming conventions for application components ensure that application and its components are universally understood. Pega Cosmos encourages application designers and developers to follow a process-design paradigm based on consistently named stages and steps. Learn more about recommended naming conventions at Pega Community.