Customizing theme colors with Restyle

Restyle can utilize user-supplied theme color configurations.

These configurations, known as palette definitions internally, are stored in the Restyle Configuration Store.

Understanding Restyle Palette Definitions

Restyle palette definitions are JSON documents that define the color scheme used by a theme. The palette definition also contains an optional "mapping" section that controls how Restyle calculates color mapping values based on the hue of an existing color in an application.

Prerequisites

  1. HCL Domino Designer installed on your machine.
  2. Understand the JSON (JavaScript Object Notation) format at a basic level.
  3. A JSON-compatible editor.
  4. A local replica of restyle.nsf. For more information, see Restyle Configuration Store.

Exporting Themes from Restyle.nsf

The best way to create a custom palette file is to start with one of the HCL-supplied palette files and modify it as needed. The following steps describe the process:

  1. Create a directory to use as a destination for the theme and schema files.
  2. Launch Domino Designer.
  3. Open the local replica of restyle.nsf.
  4. Navigate to Resources/Files and double-click the Files entry.
  5. Select reserved/schema/palette-<version>.json and click Export. This is the "palette schema".
  6. Select the directory created in step 1 and click Save to save the schema file.
  7. Select any document under reserved/palette/<name>.json to use as a starting palette and click "Export".
Note: The file names contain the sequence 2f instead of the '/'. You can rename the files to remove 2f if you wish, as these files won't be imported after modification.

Creating a Custom Palette

There are two options possible when creating a new palette file. The first is to create a complete copy and modify all parameters, the second is to include an existing complete palette and override specific properties in the customized palette definition.

Creating a complete copy

  1. With your JSON-capable editor, open the exported palette file and save as a new palette file, for example: my_custom_palette.json.
  2. For best results, configure your editor to associate the palette schema with your new palette. This provides auto-complete functionality and validates the document before Restyle uses it.
  3. Modify the palette document as needed.
Overriding an existing configuration
  1. With your JSON-capable editor, open the exported palette file and "save as" a new palette file, for example: my_custom_palette.json.
  2. Remove the "$schema" property found at the top of the document.
  3. Add the following property to the top level of the document: "include" : "<palette_name>"
  4. Any properties defined in this file will override properties with the same name from the included file.
    Note: The "standard" property is required, but the "mapping" property is not. Here is an example that overrides a few of the background properties of the creamy_taupe palette:
    {
    "name": "partial_palette",
    "version": "1.0.0",
    "include": "creamy_taupe",
    "standard": {
        "background.paper": "#FFF",
        "background.light.primary": "#F7FAFF",
        "background.light.secondary": "#F2E8F0",
        "background.border": "#CAF0DF",
        "background.dark.primary": "#0F253C",
        "background.dark.secondary": "#273F61",
        "background.outline": "#FDF7FD"
    }
}

Saving Results to Configuration

To import the new palette document into restyle.nsf:
  1. Launch Domino Designer.
  2. Open the local replica of restyle.nsf.
  3. Navigate to Resources/Files and double-click the Files entry.
  4. At the top of the "Files" collection, click New File Resource.
  5. Enter palette/my_custom-palette.json (or whatever you named your palette file) as the name.
    Note: The "palette/" prefix is required to allow the Restyle feature to find the custom palette.
  6. Enter a user-friendly display name as the alias value.
  7. Comment is not currently used but may be useful for documentation purposes.
  8. In your JSON editor, select the entire document and copy to the clipboard.
  9. Paste the contents of the clipboard into the newly created file resource in Domino Designer.

Using the Customized Palette

Whenever you launch the Restyle wizard, you will now see your custom palette listed in the "Theme Color" drop down.