Language

Clear, consistent, and concise language is the guiding principle for all content in a Cosmos application. Cosmos provides UI content best practices within your application, including standards around capitalization, number formatting, presentation, and more. Whenever possible, follow Cosmos default standards for language – unless you are following contextual requirements from a specific business, industry, or user group.

  • Sentence case is the default standard for most non-user generated text in UI, including page titles (e.g. “Data and integrations”) and application names (e.g. “Loan application”). Sentence case is also used for component names (e.g. “Summary panel”)
  • Title case is used for branded product names (e.g. Pega Platform)
  • CamelCase should never be used
  • All caps should be used for status badges

NOTE: Screen readers interpret hand-typed caps as abbreviations, so use CSS to transform to 'uppercase' instead.

Cosmos generally follows other capitalization guidelines as referenced in the Microsoft Style Guide.

Decimals

  • Numbers should have no more than 2 decimal places
  • 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)

Separators

  • Numbers should use the proper separators whenever possible (e.g., 1,000 not 1000)

Locale guidelines

  • Text alignment— 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 are aligned to the right (e.g., $100.00)
  • Reading direction— Numbers paired with text must follow the reading direction of the application locale's language. In English, this means to the left (e.g., 1 million)
  • Currency— If an application or data item does not have a defined currency type, it should be represented by the user’s local currency

Cosmos prioritizes the right amount of text to display with the goal of helping users find and digest the information they need.

Presentation

  • Line length— A line’s maximum length in a paragraph should be no more than 80em long (about 80 characters)
  • Alignment— All button and badge text should be center aligned
  • Reading direction— Text should align to the reading direction of the application locale's language. In English, this means it would be aligned to the left
  • Justification— Text should never be justified in any direction
  • Label/line display— Read-only labels and single-line values should display side-by-side, instead of being stacked

Text overflow

  • Single-line text— Single-line text that overflows its max-length should be condensed down into an ellipsis
  • Multi-line text— Multi-line text that overflows its line should avoid hyphenation to wrap words. A set height should be determined for that multi-line text
  • Condensed text— Condensed text must have a user-driven method to expand that text (e.g., tooltips, modals, popovers, expandable height or width, etc.)

Cosmos interfaces are grammatically correct, friendly, and professional. Consider the following best practices:

  • Use the active voice, not the passive voice
  • Be concise
  • Use a positive tone. Error messages must be clear about the cause of the error, and if possible, provide the user with information about how to resolve it
  • Use full words instead of contractions (e.g., “do not” instead of “don’t”)
  • Avoid abbreviations and jargon
  • Read aloud and test content decisions with users

Each field on a form should be accompanied by a label that describes it (e.g., First name, Phone number). Field labels should be concise, follow a standard format, and be descriptive enough for screen reader users to understand.

When an object could be singular or plural, use the plural version for its label (e.g., '0 items', '1 items', '2 items').

Grammar examples

Additionally, when using labels, avoid words that describe what the user may grasp from the value's format. For example:

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 by following these guidelines:

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

Standard naming conventions for application components ensure that an application and its components are universally understood.

Pega Cosmos encourages application designers and developers to consistently name application items, including stages and steps. Learn more about recommended naming conventions at Pega Community.