Using a Style Book to Standardize Site Appearance
Available 7.3+
A site’s Style Book provides visual rules for applying a consistent experience across its pages. Style books determine various visual settings, including spacing between elements (such as widgets), colors, and fonts. Each of these settings applies equally to every page using the style book.
A page’s theme determines the categories available for styling and the default style for each token, via its frontend token definition. A page’s style book customizes the style values for each token. Because a style book relies on the frontend token definition in the theme, the theme and style book must be compatible. There are notable differences in the enforcement of this relationship between Liferay versions.
The theme is provided by a theme CSS client extension or a legacy theme (e.g., Classic or Dialect). Either theme type can provide a frontend token definition to be used with style books. Wherever the word theme is mentioned below, either a theme CSS client extension or a legacy theme can apply.
Style Book and Theme Compatibility
Before Liferay DXP 2025.Q2, style books automatically inherited their options from the theme or theme CSS client extension assigned to a site’s public pages. As a result, for style books to work correctly on a page, a page had to inherit the same theme from the public pages of the site.
From Liferay DXP 2025.Q2+, you can enable a dependent relationship between style books and the underlying theme. Enable the release feature flag Theme Scoped Style Books (LPD-30204) to leverage the new behavior, which includes
-
The style book creator must specify which theme CSS client extension or theme the style book is targeting.
-
The page editor cannot choose a style book that uses a frontend token definition incompatible with the page theme.
In addition to protecting you from style book and theme incompatibility, now you can provide a unique theme and style book per page.
Creating a New Style Book
-
Navigate to the Site Menu → Design → Style Books.
-
Click Add (
) near the top of the page. -
Select the theme or theme CSS client extension; then enter a name for the style book. Click Save.
-
Change the options from the categories in the drop-down box in the menu on the right side of the screen.
These options come from the theme you selected while creating the style book. See the default Classic theme categories for more information on the categories available for the default Classic theme.
-
Customize any of the provided fields given under the chosen category. Color fields specifically give you multiple ways to choose a color.
-
Click Publish.
The style book can now be applied to any page using the same theme.
To make this style book the new default for the theme, open the Actions menu (
) beside the newly-created style book and click Mark as Default for X Theme.
If you don’t enable the release feature flag Theme Scoped Style Books (LPD-30204) (available from Liferay DXP 2025.Q2+), you can select a style book incompatible with the theme. This can occur when you create a style book with one theme set in the site and later change the theme while continuing to use the style book.
Choosing a Style Book for a Page
If you do not choose a specific style book for a page, the page uses the Master Page’s style book. If neither is set, the page uses the theme’s default style book.
With the release feature flag Theme Scoped Style Books (LPD-30204) enabled, changing the theme when a page is configured to use a custom style book also changes the style book. The new theme’s default style book is set.
Every site has at least one style book available per theme, called Styles from X Theme. This style book uses the token definition defined in the theme, with all of the default values. This style book cannot be edited, and it is used as the site default if no other style book is configured.
To apply a style book on the page, follow these steps:
-
Click Edit (
) near the top of the page. -
Click Page Design Options (
) on the sidebar. -
Open the Style Book tab.
-
Select a style book that corresponds with the applied theme.
-
Click Publish.
The page is published using the new style book.
Previewing a Style Book
Available 7.4 DXP U9+ or GA13+
While you are creating or editing a style book, you can preview the way it affects the look of various components of your site, including pages, Page Templates, and Page Fragments.
Use the two drop-down menus at the top of the screen to select what components to preview. The left drop-down menu determines the overall type to display (pages, Page Templates, Master Page Templates, Display Page Templates, or Page Fragments). The right drop-down menu determines which specific instance of the chosen type to display (or category, if applicable); only the four most recently used options are shown in the right drop-down menu, unless you click More from the list.
Previewing a Collection of Page Fragments shows all Fragments in the Collection. The preview displays Fragments with multiple (selectable) configuration options with an instance of each option, so that you can preview your style book with any of them.
Customizing Your Style Book’s Colors
When you are choosing a color for any color field in your style book, you can choose the color in multiple ways:
-
Click the color on the left side to open a color picker, and choose any color.
-
Enter the hex code for the desired color into the text box to change to any color.
-
Click the Value from Stylebook button to open a menu of pre-defined colors to choose from. You can choose to reuse colors from each of the general categories that you can customize.
If you click the Value from Stylebook button and select a style book token value (that is also defined in another category), then that color field is linked to the chosen style book token. Any future changes to the token value for this style book also change this color field.
When a color field is tied to a style book token, the Value from Stylebook button is replaced with a Detach Token button. Click this button to detach the color field from the token (but keep the same color value).
Attaching or detaching a color value to a style book token requires Liferay DXP 7.4 U10+ or GA14+.
Click the Clear Selection button on the right side to reset the color back to the default value defined in the theme.
When you are editing colors from a style book on a specific page, you have the same options to choose a color. However, clicking the Clear Selection button instead resets the color value to the default defined in the chosen style book.
Using the Color Picker
While customizing your style book, use the color picker to search for colors and filter your search results.
The use of the color picker is not restricted to style books. You can also find it in other parts of Liferay (e.g., while editing a content page).
To access the color picker, click Value from Style Book (
) next to a color value (for backgrounds or borders, for example) or click on the color value when the icon is not available (e.g., text color).
In the color picker, existing colors are divided by categories and token sets. You can see a color’s token value by hovering the cursor over the color.
Use the search bar to search for a specific color case-insensitively. You can search by category, token set, token value, or hex color values.
Default Classic Theme Categories
When you are editing a style book, the categories available from the drop-down box show different options for styling your pages. The options available in each category are defined by the theme or theme CSS client extension through its Frontend Token Definition.
You can place the Style Guide Sample widget on your pages to help test out the various options in your style book categories. This sample widget contains many different UI elements that leverage most of the features in the Classic theme, so you can use it to test your page styles.
The categories listed here are available as options for the Classic theme.
When modifying sizing options like width, margins, and padding, you can choose from a set of predefined units or specify a custom unit. Some options include pixels(PX), percentages(%), em width(EM), and root em(REM).
Color System
The colors used for fonts and visual elements defined in your theme are customizable in the Color System category. Generally, this means you can modify the body, background, and text colors on your pages.
Changing the colors for alert-related elements (such as Success or Warning) may not affect the color of incoming alerts on your site because each type of alert may use one of many colors. To fully customize the color of alerts, you must define customizable colors and use them in your own theme’s categories.
Spacing
Adjust the spacing between the main elements on your pages with the options in the Spacing category. When you configure a Page Fragment using the corresponding style book, these values are given as options for the Fragment’s margin and padding sizes.
When modifying tokens like width, margins, and padding that aren’t related to colors, you can choose from a set of predefined units or specify a custom unit. This flexibility allows for more precise control over the styling. Some options include pixels(PX), percentages(%), em width(EM), and root em(REM).
General
These options modify color and spacing on elements that appear on every page of your site. For example, the Body Background option changes the background color of all pages.
Layout
These options modify the width of containers on your pages. For example, the default container on new Blank pages is configurable via the size of the Extra Large setting.
Typography
These options define new fonts for your pages. You can also adjust the size of headers via the options in this category.
Buttons
These options modify the style for the default types of buttons. You can customize the background, foreground, and border colors for each of the buttons used in the Classic theme.
