Skip to main content

How we improved our UX design through documentation

George Reyes, 6 minute read

The Pega Product Design team – while a critical center of innovation at Pega – is a surprisingly small team. Our solutions range from foundational experiences to ever-evolving, industry-specific products. We’re constantly striving to design faster and produce more.

To do that, all of Pega's product designers must access and build upon the latest version of our design system in their work. Well-documented design standards, guidelines, and patterns enable designers to work quickly and effectively and iterate in collaboration with their teams.

In our efforts to adopt a highly efficient workflow and to provide the right set of tools to support our creative and collaborative processes, we’ve built a design library that accomplishes both.

A component-based UX design library

A design library is a curated collection of design components. We use Sketch and Figma to develop and maintain our library, which also makes our user interface (UI) content easily accessible and downloadable for all designers, internally and externally. It’s widely available on, and we can place the library that users directly reference next to documentation about each component. We call our library of components Cosmos Work, after Cosmos, our design system.

All components go through an internal approval process

To build a cohesive library, we established standards through competitive analysis, internal testing, and team decisioning. Our library components go through an interdisciplinary design quality committee. This group identifies patterns, consistencies or any inconsistencies in the work. If needed, designers perfect their work after the committee and hand off to me for library integration. I build it while referencing their finished, green-lit design work and connect once more for verification.

We build according to the standard we set

Building designs isn’t as simple as duplicating them visually 1:1. I check that components and documentation adhere to our standards: This includes typography and hierarchy, color palettes and their case patterns, as well as universal spacing conventions between/within objects to make sure they follow our current grid system. I also identify duplicate/deprecated patterns that may already exist in the library as well as override needs that may have not been brought up in previous conversations.

Components must be intuitive for all users

Components need to be built to be as responsive and easy-to-use as possible while retaining flexibility for screen mockup use. They shouldn’t behave in a way that will appear wrong or inconsistent, nor should they break unintentionally. If a development team decides to detach and build, or reverse-engineer a component, it should be clear what does what. – or learnable from the component anatomy itself. This level of detail is applied to all symbol components in the library, regardless of how simple they may seem.

In addition to overall anatomy, naming of components must also be intuitive for library users. Library components should match our online documentation and the developed software components – so consistency is critical. That makes it possible for library users to research, build, and experiment with Cosmos components right out-of-the-box and easily develop their designs.

Automatic updates help consistency

We make frequent updates to the design library. The system automatically sends updates to everyone who is subscribed. Designs and library components reflect any changes to design components, which are published as soon as designers push them live. Users are also able to reference the exact release note updates on, so they can get full context on what has changed.

We document all the UX design details

Our design library, web presence, and documentation provide designers and developers with everything they need in order to fully understand design details – such as the grid system that we work with, spacing patterns and conventions, our entire color palette (with usage descriptions), our typographic conventions (with usage descriptions), and, of course, our entire (current) set of UI components and controls.

Creating all this material and processes is a lot of work, but it yields results:

  • Fewer visual errors: Our documentation system greatly reduced internal errors and roadblocks, such as the duplication of components and designs, inconsistent spacing patterns, inconsistent color usage, designs that fail to comply with our general look and feel, designs with inapplicable or deprecated Pega patterns, the accidental mixing of old and new version components, and so on. We make fewer errors in the beginning, so the final product has accurate designs.

  • Faster design work leading to faster releases: Our documentation system allows designers to complete mockups quickly and focus on key design needs or requests. All of the information they could possibly need to design is accessible, leaving designers with room to innovate quickly and construct new concepts that adhere to the Cosmos Work look, feel, and patterns. Quicker drafting allows us to move past the approval chain straight into the implementation chain and ultimately towards a product release much faster – all without sacrificing quality!

  • Stronger collaboration with our colleagues and our customers: Documentation has allowed us to be more agile and engage better with developers and product owners at Pega. Our internal partners now have full transparency into our workflow and share ownership of its contents, as well as offer channels to provide feedback on the system.

Our transparent documentation has also made it possible to engage with our clients’ needs in a new way. We’ve participated in high-level client presentations and mock-ups, have supported multiple critical company partnerships, and consistently listen to client feedback on our design system from the people that use it most … all while helping our clients learn about design best practices for B2E software.

Pega’s design library and related documentation have been more than supporting documents. They’re now strategic tools that are integral in building relationships and creating great software for businesses.

Learn more:

About the Author

George Reyes manages the Cosmos Work design system on the Pega DesignOps team. George has over 9 years of experience designing for businesses and specializes in conceptualization, strategy, rich user experiences, and constructing/maintaining atomic design systems. He cares about building tools that will help people and make a positive impact.

Share this page Share via x Share via LinkedIn Copying...

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us