Forms - Pega UX Design System

The UX design system’s primary goal is to streamline business processes, ensuring the fastest path to an accurate outcome. Because of that, forms are a UI of last resort – critical, yet inherently slow. They often require human effort, research, and manual input.

Where they appear

The design system provides forms in four different ways throughout the experience. Some are configurable, and some are built into widgets users use day in and day out.

Design system assets – Built into components or widgets. Examples include adding attachments or updating insights. These are standardized, continuously improved, and not configurable.
‘Create’ forms – Used to create a new work object (what Pega calls a Case). Displayed in modals which support minimization they allow multitasking and flexibility without disrupting workflow – unlike our former process of creating within the context of an empty Case. This form is highly configurable, and typically the first step found within the Create Stage in authoring. This form by default contains a Case’s primary fields (a collection of fields critical for the Case to be understood). And while this form can support multiple steps, it is not best practice to create a very heavy flow to get work started.
Optional actions and processes – Configurable forms for specific updates or conditional workflows, enhancing adaptability. Optional actions open in a modal on top of the case, whereas Optional processes become part of the Assignments work area, as they may require follow-up, hand-off, or complex workflows that may not be finished in a single setting. These are highly configurable.
Assignments – Core to business process flows, these guide users through necessary steps to completion. These are highly configurable and some of the most important forms within your workflow.

Choices designers and developers make

While the system makes strategic design decisions to optimize flow, increase usability, and reduce friction – there are some design decisions your forms should consider taking to help accelerate time to value.

Minimize required inputs, avoid optional inputs or input warnings – Collect only essential data.
Prioritize clarity – Use our writing guidelines to present just enough text for users to understand what they must do, taking advantage of form descriptions, labels, helper text, error messages, and additional information.
Progressive disclosure – Show only necessary fields at the right time. Use steps, groups, tabs (known as a hierarchical form), and conditionally revealed fields to reduce cognitive load & prevent neurodivergent users from feeling overwhelmed.
Optimize data input – Use the right data types to prevent bad data, find ways to provide pre-defined or pre-filled values, and use the right input types to speed up completion. More on this later.
Prefill or auto-populate fields – If a value is known, expected, or is a smart default, provide that content up front within the field.

Structure considerations

When considering the workflows and forms for your app, having a good structure can make the work move faster. Try each idea below only if you’ve already tried the one before it. You can use more than one idea together if needed.

Stages: If you are considering the assignments needed to get work done, first consider the logical phases of the work to be completed. Three to seven stages, and potentially an alternate stage or two, are common in most workflows.
Parallel Process: Considering assignments again, determine if there are items of work in a particular stage that can be worked on in any order (e.g. ‘Approve expense’ and ‘Pay bill’) or can be completed by any group of users at the same time (e.g. Bob is assigned to ‘Approve expense’, while Janice is assigned to ‘Pay bill’). This helps accelerate or break up the work.
Conditional fields: Show relevant fields only when needed to reduce cognitive load.
Field Groups: When fields share a similar theme, consider using Field Groups to organize the structure of your form. Field Groups may also have their own unique instructions, making it easier to explain complex topics. Once Field Groups are used, it’s best not to reintroduce fields not within Field Groups, as the form’s hierarchy becomes confusing. Additionally, avoid collapsible Field Groups if they contain required fields – Field groups cannot be collapsed by default, as the only form fields that should be included are critical ones.
Multi-step forms: For complex forms over seven to ten fields or where completing large sets of data in order is essential – consider if the form can be shorter or completed in smaller parts. If not, break forms into multiple steps. Steps may be laid out horizontally (shows only the title of the current step), vertically (shows all step titles) or hidden altogether (recommended for two step forms). Avoid having more than five to seven steps in a form if possible. Sometimes referred to as screen flows.
Hierarchical forms: Finally, if a form is still highly complex, and the work is not sequential, a hierarchical form template (which renders as tabs) helps break down critical work into ad-hoc sections of things to be done. Again, design patterns recommend no more than three to seven tabs at most. Additionally, don’t use hierarchical forms within a multi-step form. The Next button may imply to some users they will move to the next tab, instead of the next step of the flow.

Picking the right inputs

Fields within the design system are linked to the type of data that needs to be collected. This choice can either speed up or slow down your users, so choose wisely. Below is a helpful guideline to consider which data type or pattern to use, with the fastest to complete at the top of this list, and the slowest and most cumbersome at the bottom.

Boolean: Checkboxes for quick true/false selections.
Picklists: Use radio buttons for short lists of one to five items and combo boxes (also known as search boxes) for larger or complex lists. Avoid using dropdowns, as they cannot be searched.
Restricted inputs: Date, time, date and time, attachments, phone, currency, percentage, decimals, and integers all prevent incorrect data.
Guided inputs: Email and URL types provide some out-of-the-box verification but are otherwise generally unrestricted. Address type can be helpful but may fall back to a collection of inputs in some cases.
Text inputs (single): Unrestricted format, but the size implies less time is required to complete than a paragraph.
Text inputs (paragraphs): Unrestricted and one of the slowest forms of input. Text areas are simpler than Rich Text Editors, but formatting of text styles and insertion of links or imagery are a common expectation on longer fields.

Using advanced inputs

In addition to standard inputs, you may need to choose, display, or edit data within tables or repeated groups for additional context. Since these patterns are a little more complicated to set up and much slower to work with, it may be helpful to read more about implementing the patterns here. Again, the list below moves from the fastest advanced interactions to the most cumbersome.

Choosing records from a table: Provides additional context and a way to either select a single record or multiple records.
Search and select: Provides a large amount of context within large lists of contextual information for users to select records from. Additionally, if privacy is a concern, it can prevent users from reviewing every record within a set of data, as specific search criteria must be first chosen to reveal data within. Also known as Advanced search.
Edit individual records within a modal: Records that are generally complete and ready to be reviewed or have small, quick edits are best presented in this form. The modal allows fields not presented in the table to also be edited as well. The single record at a time experience can keep users focused but also may become annoying if many records must be edited within the table.
Creating many records: Used if you need to collect many records of repeated inputs the same type at one time – for example: employees. They have a first name, last name, primary email and phone number, and so on. Being able to tab through the work from field to field quickly may be useful for a power user, however, comparing the added records one to another becomes difficult in this layout. Best used especially if there are a lot of fields per record that need to be completed. Also know as repeating views.
Editable tables: Similar to the previous pattern, editable tables provide a very familiar spreadsheet software experience. However, this pattern is very difficult to work with when there are many fields that must be entered, as inputs may scroll offscreen, errors may be hidden, and keyboard-only interactions become very complex. They are extremely difficult to work with on highly zoomed or smaller devices. Unless there are very few and short values to collect, avoid using these altogether.

Adding descriptions

UX design system provides the following ways to help users understand what your form or input is for, and what is expected.

Section descriptions can be set on the form itself or within field groups. Use these for special instructions or to explain why data is required.
Field labels can use property references, making them dynamic; creating more personalized, engaging experiences. Make labels short, concise, and clear.
Field descriptions can be set in two ways – Helper text, which should be used for brief messages to guide users on how to complete fields correctly and are always shown and Additional Information, which can be used to explain a field’s purpose, key data, or background information and is shown only if the user interacts with it.
Placeholders should never be used. They are often confused with prefilled values and skipped by users, creating accidental errors. Faint placeholders also fail WCAG constrast standards. Use a clear Label or Helper text instead.
Avoid using readonly fields for descriptive content.

Choosing the right validation method

Inputs may either be required, optional, or provide warnings. Using the proper one will help speed up workflow for your users.

Required: Fields generally should be required as the goal is to collect valid data.
Warnings (New): Also known as conditional contextual messages, these can provide your user information they may need to be aware of that may affect the process, but aren’t strictly an error. Example: User has set a valid appointment time, but the calculated distance estimates they will miss that appointment. Learn more about warnings
Optional: Use sparingly. Data collection should be minimal to speed up work and reduce overwhleming users.

What the design system takes care of

The UX design system minimizes settings to maximize value through design prescription. In that light, some previous form design decisions, like field layout or button interaction, are now handled for you. Our decisions take the following into account.

Usability – The design system emphasizes speed, readability, usability, scan-ability, preventing users from being overwhelmed with unnecessary data, and reusing common interaction patterns whenever possible.
Accessibility – A subset of usability, with legal implications in many countries. We target WCAG 2.2 AA – sometimes referring to AAA standards for additional guidance. This includes considerations for readability, proper tab order, and the use of standard HTML tags for compatibility with assistive technologies. We account for users with touch-only, keyboard-only, mobility issues, cognitive issues, and vision impairments.
Responsivity – Devices vary greatly in size, from small mobile phones to large displays, like jumbotrons. Additionally, users may zoom in up to 400%, as required by WCAG 2.2 1.4.10. A normal laptop display to one person renders like a mobile phone display to another user with a zoomed display. So, don’t fixate on a flow being above the fold – it assuredly will be different for everyone else. Size and layout are only a suggestion in the design system.

Input types

Input types within the design system are tied directly to the data needed or sourced. While you may have some control over configuration, trying to set a Boolean value to a standard Text Input is not allowed, as it wouldn’t make sense.

Form column layout

Readability and accessibility guide our execution here. Authors often want more columns of form fields—three, four, or even five. Internally, we have tested and have seen issues for low vision users even with a form containing a three-column layout – and while the three-column layout included out-of-the-box is now optimized for readability – it is not recommended.

Maximum content width needs to be set to something; otherwise, super-wide monitor users can’t consume critical data in a consumable way either. The design system leans on WCAG 2.2 1.4.8 – providing an optimal out-of-the-box, it-just-works experience, whether it’s for a demo or daily use by a user with low-vision.

Form field layout

The design system takes inspiration from the layout of the printed page. Sentences flow from left to right, with some lines being longer than others. Just like a paragraph with varying sentence lengths, forms should feel easy to scan and navigate. Gaps at the beginning of a row can make it hard to see if there are more form fields, often leading to bugs and feedback issues. Eye tracking patterns reinforce that users scan the leftmost side of content when interacting with it.

While most form fields stagger using the dynamic template’s suggested column number, there are some that do not.

Text areas, rich text editors, tables, radio button groups (horizontal and vertical), and checkboxes can have varying dynamic heights. Placing them next to each other in a two-column or three-column layout creates large dead zones at the left edge or center of form.

The system prevents inputs from being placed this way.

One additional note on tables. They do have the ability to fill the entirety of horizontal white space. Since the visual language provides scroll cues, and the column widths are all generally under the readability maximum width, tables meet the readability recommendations from WCAG. However, be aware that tables are difficult to work inside of a form and their editing and validation patterns are a bit cumbersome for users.

Enabled buttons only

While disabled buttons are a common pattern for incomplete forms, they pose significant accessibility and usability challenges. The disabled property in HTML makes them invisible for blind users, while the low opacity prevents users with poor vision from being able to gain the additional context. Adding contrast still won’t help, as now the button seems functional, and still doesn’t provide context as to why it can’t be used.

Instead, the design system provides error validation checking on when clicking “Submit”, helping users know what they need to do to move forward.

Configuration

To learn how to configure forms in your Pega application, visit Pega Documentation.

While components can’t be placed wherever in the UI via authoring, knowing how they work in these patterns can help you understand our center-out design practices.

General

Inputs

Selections