Best practices – Styling your application

Pega Support community – best practices

• Work with your UX Design group to make sure that your company has a well defined and very comprehensive design system– If you don’t have one, you can leverage the one provided by Pega using the

UI-Kit theme– See https://design.pega.com

• Get detailed mockups of every interaction in your application– Design should cover things like error handling/messages, empty pattern,

accessibility, paging…

Engage with UX designers to understand the design system

8 November 2018 2

• Not all software engineers are front-end developers

• Front-end developers have the visual eye and attention to details

• They understand how to implement a design system using the latest CSS3 specification

• They are expert in the latest Web technologies (CSS/HTM5/Javascript) and understand how to leverage flex layouts and build UI with optimized markup

• They are experts on accessibility and understand the semantic of each HTML element

Have a front-end developer in your team

8 November 2018 3

The Center Of Excellence (COE) layer is used to implement all the elements of your design system. It includes things like:– Skin– Web fonts (typography / icons)– Set of helper classes– Set of design templates– Default portal and navigation– Based page layout for cases

When building a new application, the UI-Kit theme that implements the Pega Design system is automatically added as an add-on application. Depending on the richness of your design system, you can decide to leverage the OTB UI-Kit layer or build your own COE layer.

Build the COE layer that implements your design system

8 November 2018 4

• The skin rule should be the one-stop shop for all styling needs in an application

• Your COE skin can be a standalone skin or inherit from the pyEndUSer skin available in the UI-Kit theme

• Each application can use the COE skin as is or provide a new skin that inherits from your COE skin– Can override settings from inherited skins– Can disable formats from the inherited skins

• Best practice is to define the skin at the application level and have all your portals use the application skin– You can also specify a skin at the portal level

Use the skin ruleform as much as possible

8 November 2018 5

• Disable generation for components your application is not using

Skin – Turn off CSS generation for unused components

8 November 2018 6

• Sets the base styles for all UI components– Focuses on heading styles, background color, and

layout padding– Can use mixins for headings and background

• Should inherit from parent skin unless absolutely necessary

Skin - Base settings

8 November 2018 7

• Define settings for specific styling components– Typography– Background colors– Borders

• Can also create mixins that combine styles for all three components– Good for pairing border colors, text colors, and

background colors into one mixin

• Can define new mixin styles or can inherit from existing mixin and override settings

• As a best practice, use a ‘General’ mixin for your overall typography and have all the typography mixinsinherit from General

• Can leverage mixins in other Skin settings and in custom CSS

Skin - Mixins

8 November 2018 8

• Collection of styles for specific UI components

• Leverage existing formats as much as possible

• DO create new formats:– For patterns that are repeated in the application– For patterns that require setting multiple styles at

once on a single component

• Do NOT create new formats:– To tweak one or two settings of existing formats– To only set a couple styles on a component

Skin – Formats

8 November 2018 9

• Format and mixin names should be semantically meaningful and reflecting their purpose– “Mobile card” is a good format name– “Default 2” or “Default 3” is not a good name

• Provide a detailed description that explain where to use them by clicking on the pencil icon or the ‘Update details’ menu item.

Skin – Name and Usage

8 November 2018 10

• For more advanced styling that cannot be done in the model using the skin rulefomr, you can define additional stylesheets that will be included in the generated CSS– Order of CSS files determines style precedence

It is recommended to add additional stylesheet to the skin rather than individual harnesses:- Support for RTL- Support for custom mixin variables- Reduce number of distinct CSS files to download

and parse

Skin – Included styles

8 November 2018 11

• By default, the Pega design system uses the Open Sans web font.

• To use different web fonts, follow these steps:– Create a rule-file binary for the woff2 and woff web

font files– There is no need to upload an EOT, SVG or TTF file.

WOFF2 and WOFF will work for all supported browsers (IE11 is the only one to use WOFF)

– Upload a new CSS rule-file text and attach to your skin as an additional file

– In the base settings, change your overall font

Skin – Web Fonts

8 November 2018 12

• By default, the Pega design system ships with its icon font as part of the UI-Kit theme – see py-icons.css

• To use different icon fonts, follow these steps:– Follow the same steps as the web font by uploading

the woff and woff2 files are rule-file binary. Then upload a new CSS rule-file text and attach to your skin as an additional file

– Make sure that you define a generic class that will apply the icon font-family – in the UI-Kit font, the generic class is called ‘pi’; All the other icon classes should use the same generic class as starting name (for example pi-star).

– It is important to follow this convention so that the icon font CSS file can be parsed to display the icon picker

Skin – Icon Fonts

8 November 2018 13

To check that the icon font is correctly loaded, in the skin ruleform use Action->Launch->Skin Previewand click on ‘Icons’. Make sure that all your icons are correctly rendered.

To use an icon font with a button/link or image, select ‘icon class’ and open the icon picker

https://community.pega.com/knowledgebase/articles/adding-icon-fonts-your-applicationhttps://pdn.pega.com/pegatube/implementing-icons-fonts-pega-applications

Skin – Icon Fonts

8 November 2018 14

• If you are not sure where a format is used, click on Actions->List sections to get a list of all the sectionswhere this format is used inyour application.

• You can then refactor the section to use a different format and then disable thisformat by clicking onActions->Disable

Disable unused formats

8 November 2018 15

• You can generate a complete preview of the auto-generated CSS by clicking on Action->Preview.

• Click on the ‘Download Statistics’ button to download an CSV file that can be parsed by Excel. The file will highlight how many formats are used and the number of bytes required by each format.

Review the size of the generated CSS

8 November 2018 16

• Train all the developers working on the application on what are the rules provided by the COE Layer and what are the different formats for each components

• You can generate a complete style guide of your skin by clicking on Action->Launch->Skin Preview. You can export the document as PDF or print it.

Documentation and training

8 November 2018 17