@aurigma/ui-framework/docs/styling.md

A platform which allows building print product personalization editors based on Aurigma's Customer's Canvas.

UI Framework Styling
====================

## UI Themes

The UI Framework uses a theme engine for styling. To change the styles of UI elements, this engine uses [CSS custom properties](https://developer.mozilla.org/docs/Web/CSS/Using_CSS_custom_properties) (variables).

The distribution package contains a default UI theme in the `themes` folder. You can activate themes in the `editor.json` file as follows:

```json
"imports": [
  {
    "src": "themes/au-default-theme.html",
    "check": "true"
  },
  ...
]
```

To create a custom theme, you can copy, rename, and edit the  `au-default-theme.html` file as needed. If you split a theme into different files, then you must import those files as described above.

### Icons

At the beginning of the default theme, there is an `iron-iconset-svg` element with predefined SVG icons for steps, groups, etc. Each icon is enclosed in the tag `<g>` and has a unique ID. The size of icons is 32x32 px.

```html
<iron-iconset-svg name="custom-icons" size="32">
    <svg>
        <defs>
            <g id="preloader" viewBox="0 0 32 32" ...
            <g id="front" viewBox="0 0 32 32" ...
```

Here, you can define new icons by using both vector `path` and raster `image` elements.

To add a raster image as an icon, for example in the PNG format, convert it to Base64 first. You can use such online tools as https://www.base64-image.de for the conversion. After that, paste the resulting string into the `xlink:href` attribute of the `image` element.

```html
<g id="pngIcon" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
  <image x="0" y="0" width="32" height="32"
      xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUh ...
</g>
```

### Colors

The `custom-style` element contains the `html` object with variables defining the theme colors.

```html
<custom-style>
  <style>
      html {
          --theme-primary-color: #30c2ff;
          --theme-primary-color-hover-button: rgba(48, 194, 255, 0.12);
          --theme-background-color: #ffffff;
          --theme-preloader-size: 50px;
          ...
```

For example, you may want to change the primary color `--theme-primary-color`, which will be applied to all icons, buttons, and other control elements.

As an alternative to editing variables in the HTML file, you can  redefine them directly in your config. To do this, you can use the `style` object in any widget or directly in the root of the config as follows:

```json
{
  "style": {
      "--theme-primary-color": "#30c2ff"
  }
}
```
## Custom Preloader

You can change both the color and the image of the preloader in the UI Framework.

To change the color, set a new value to the [--theme-primary-color](#colors) variable.

To change the icon, replace the content of the element [<g id="preloader" ... >](#icons). 

```html
<g id="preloader" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"> 
    ...
</g>
```
To specify the icon size, define the `viewBox` attribute depending on the size of your SVG image. In the previous example, we defined the standard size of 32x32 px. When you use a custom icon, you may need to change the size of the circular progress ring in the [--theme-preloader-size](#colors) variable.

_**NOTE:** The `design-editor` widget uses a different preloader. To customize it, refer to the [corresponding topic](https://customerscanvas.com/docs/cc/product-loading-screen.htm#custom)._

## Icons and Headers of the Panels

You can use the `drawer` object to specify icons and headers of the UI Framework panels. To enable an icon, add the `icon` property and refer to the required SVG image in the theme file through `<iconsetName>:<iconId>`.

In the following example, we set the `front` icon and the `Size` header to options in the `toolPanel`.

```json
{
  ...
  "steps": [
      {
          "name": "1. Card",
          "title": "Step 1. Card Options",
          "icon": "custom-icons:front",
          "description": "Personalize your card here.",
          "mainPanel": {
              "name": "editor"
          },
          "toolPanel": {
              "name": "options",
              "drawer": {
                  "icon": "custom-icons:front",
                  "text": "Size"
              }
          }
      },
    ...
  ]
}
```