# Introduction

Theming dictates basically every GUI inside of Breeze. If you have Breeze+, you are able to use custom themes, made by you or others in the community. If not, you can select a theme you like from the built-in themes in the `Themes` tab.

However, if you have Breeze+ and want to create your own theme, you can follow this guide.

A theme is created inside of a TOML file. If you aren't familiar with the syntax of a TOML file, we highly suggest looking up. It's a very minimalistic and easy to understand format, so it shouldn't be too difficult.

To start, we need to understand a bit about how Breeze infers different data types. TOML by default does not include some of the features that we have, so we had to make some changes.

Colors are represented by arrays of either 3 or 4 integers. The fourth value can represent an alpha value, if you need it. The other three are simply red, green and blue respectively.

Now, to make customizing your experience easier, we implemented a way to reference other values. You can also modify them slightly, if you want to. To refer to another value, simply type the value's key in a string.

```toml
[a]
value = [128, 128, 128]

[b]
value = "a.value" # this will reference a's value
```

Now, we can also modify this value using Breeze's built-in modifiers. These are `brighter`, `darker` and `alpha`.

You can modify the value by using `::` after the value's key, and then the modifier name. You can chain as many modifiers as you want.

You can also change the value that the modifier changes by adding `;` after the modifier name, and then the value.

```toml
[a]
value = [128, 128, 128, 30]

[b]
value = "a.value::alpha;150" # this will reference a's value, but with an alpha value of 150
```

```toml
[a]
value = [128, 128, 128]

[b]
value = "a.value::darker;50" # this will reference a's value, but make each value decrease by 50
```

| Modifier | Effect                                                       | Default Value |
| -------- | ------------------------------------------------------------ | ------------- |
| brighter | Raises a colour's brightness by a value (up to 255)          | 10            |
| darker   | Lowers a colour's brightness by a value (down to 0)          | 10            |
| alpha    | Changes a colour's brightness to a value (between 0 and 255) | 255           |

Breeze includes a `default` section, that contains all shared values between each GUI element, to try and make it easier to change the overall look of the GUIs.

<table><thead><tr><th width="232.20001220703125">Key</th><th width="199.13338216145831">Default Value</th><th>description</th></tr></thead><tbody><tr><td>default.accent</td><td>[13, 98, 225]</td><td>The main accent of the client</td></tr><tr><td>default.corner-radius</td><td>25</td><td>The corner radius used for rounded rectangles</td></tr><tr><td>default.border-thickness</td><td>2</td><td>The border radius for the borders around the UI elements</td></tr><tr><td>default.text-primary</td><td>[245, 245, 245]</td><td>The primary text color, used for highlighted or hovered text pieces.</td></tr><tr><td>default.text-secondary</td><td>[192, 192, 192]</td><td>The secondary text shade, most of the things in the ui have this color.</td></tr><tr><td>default.text-tertiary</td><td>[128, 128, 128]</td><td>The background text shade.</td></tr><tr><td>default.layer-zero</td><td>[17, 17, 17, 252]</td><td>The background that the UI uses</td></tr><tr><td>default.layer-one</td><td>[30, 30, 30, 150]</td><td>The second background the UI uses (for smaller parts within the main panel)</td></tr><tr><td>default.layer-two</td><td>[40, 40, 40, 150]</td><td>For highlighted top parts of the UI.</td></tr><tr><td>default.hovered</td><td>default.layer-one::brighter</td><td>For hovered parts of the UI.</td></tr></tbody></table>

That should be all you need for you to get started making your own themes. An exhaustive list of all keys and their default values can be found below.


# UI Themables

#### default

| Key              |               Default Value | Description |
| ---------------- | --------------------------: | ----------- |
| accent           |                \[13,98,225] |             |
| corner-radius    |                          25 |             |
| border-thickness |                           2 |             |
| text-primary     |              \[245,245,245] |             |
| text-secondary   |              \[192,192,192] |             |
| text-tertiary    |              \[128,128,128] |             |
| layer-zero       |             \[17,17,17,248] |             |
| layer-one        |             \[30,30,30,150] |             |
| layer-two        |             \[40,40,40,150] |             |
| hovered          | default.layer-one::brighter |             |

#### icon

| Key                |               Default Value | Description |
| ------------------ | --------------------------: | ----------- |
| color              |      default.text-secondary |             |
| color-hovered      |        default.text-primary |             |
| color-disabled     |       default.text-tertiary |             |
| background         |           default.layer-one |             |
| background-hovered | default.layer-one::brighter |             |

#### tooltip

| Key           |        Default Value | Description |
| ------------- | -------------------: | ----------- |
| background    |       default.accent |             |
| text          | default.text-primary |             |
| corner-radius |                    5 |             |

#### textbox

| Key              |                Default Value | Description |
| ---------------- | ---------------------------: | ----------- |
| corner-radius    | default.corner-radius::div;2 |             |
| border           |            default.layer-one |             |
| border-thickness |                            3 |             |
| text-placeholder |        default.text-tertiary |             |
| text             |       default.text-secondary |             |
| selection        |              \[89,89,89,230] |             |

#### button

| Key                 |                Default Value | Description |
| ------------------- | ---------------------------: | ----------- |
| corner-radius       | default.corner-radius::div;2 |             |
| background          |               default.accent |             |
| background-hovered  |    button.background::darker |             |
| background-disabled |            default.layer-two |             |
| text                |         default.text-primary |             |
| text-disabled       |        default.text-tertiary |             |

#### tag

| Key                 |          Default Value | Description |
| ------------------- | ---------------------: | ----------- |
| text                |   default.text-primary |             |
| text-hovered        |  default.text-tertiary |             |
| text-selected       | default.text-secondary |             |
| background          |      default.layer-one |             |
| background-selected |      button.background |             |
| border-thickness    |                      2 |             |
| border              | default.accent::darker |             |
| border-hovered      |         default.accent |             |
| corner-radius       |                    7.0 |             |

#### toast

| Key              |                             Default Value | Description |
| ---------------- | ----------------------------------------: | ----------- |
| background       | default.layer-zero::brighter;2::alpha;245 |             |
| text             |                      default.text-primary |             |
| corner-radius    |              default.corner-radius::div;2 |             |
| border           |                            default.accent |             |
| border-thickness |                                         3 |             |
| title-text       |                      default.text-primary |             |
| message          |                    default.text-secondary |             |

#### panel

| Key                 |            Default Value | Description                             |
| ------------------- | -----------------------: | --------------------------------------- |
| corner-radius       |    default.corner-radius |                                         |
| background          |       default.layer-zero |                                         |
| menu                |       default.layer-zero |                                         |
| border              |          \[37,37,37,200] |                                         |
| border-thickness    | default.border-thickness |                                         |
| separator           |          \[37,37,37,200] |                                         |
| separator-thickness | default.border-thickness |                                         |
| background-img      |                          | [Background images](/background-images) |

#### branding

| Key               |          Default Value | Description |
| ----------------- | ---------------------: | ----------- |
| custom-color      |                  false |             |
| logo-color        |           \[0,180,255] |             |
| client-name       |                 Breeze |             |
| client-name-color |   default.text-primary |             |
| version           |                      % |             |
| version-color     | default.text-secondary |             |

#### user-info

| Key                |                   Default Value | Description |
| ------------------ | ------------------------------: | ----------- |
| background         |               default.layer-one |             |
| corner-radius      | default.corner-radius::mul;0.75 |             |
| icon-bar           |               default.layer-two |             |
| text               |          default.text-secondary |             |
| icon-color         |                      icon.color |             |
| icon-color-hovered |              icon.color-hovered |             |

#### tab

| Key           |         Default Value | Description |
| ------------- | --------------------: | ----------- |
| corner-radius |  button.corner-radius |             |
| selected      |     button.background |             |
| text          | default.text-tertiary |             |
| text-hovered  |  default.text-primary |             |
| text-selected |  default.text-primary |             |

#### drawer

| Key              |                 Default Value | Description |
| ---------------- | ----------------------------: | ----------- |
| border           |                default.accent |             |
| border-thickness |                           2.0 |             |
| background       | default.layer-zero::alpha;245 |             |
| hovered          |    panel.background::brighter |             |
| corner-radius    |  default.corner-radius::div;2 |             |

#### module

| Key                     |          Default Value | Description |
| ----------------------- | ---------------------: | ----------- |
| background              |      default.layer-one |             |
| background-hovered      |        default.hovered |             |
| text                    | default.text-secondary |             |
| text-hovered            |   default.text-primary |             |
| description             |  default.text-tertiary |             |
| description-hovered     | default.text-secondary |             |
| corner-radius           |  default.corner-radius |             |
| edit-background         |        default.hovered |             |
| edit-background-hovered |      default.layer-two |             |
| favourite               |             icon.color |             |
| favourite-hovered       |     icon.color-hovered |             |
| favourite-toggled       |         default.accent |             |
| enabled-background      |        default.hovered |             |
| enabled                 |         default.accent |             |
| tick                    |   default.text-primary |             |

#### settings

| Key            | Default Value | Description |
| -------------- | ------------: | ----------- |
| rounded-design |          true |             |

#### setting-group-panel

| Key           |         Default Value | Description |
| ------------- | --------------------: | ----------- |
| corner-radius | default.corner-radius |             |
| background    |     default.layer-one |             |
| text          |  default.text-primary |             |

#### slider

| Key                    |            Default Value | Description |
| ---------------------- | -----------------------: | ----------- |
| rounded-design         |  settings.rounded-design |             |
| bar                    |           default.accent |             |
| bar-hovered            | default.accent::brighter |             |
| bar-background         |        default.layer-one |             |
| bar-background-hovered |          default.hovered |             |
| knob                   |     default.text-primary |             |

#### switch-button

| Key               |                  Default Value | Description |
| ----------------- | -----------------------------: | ----------- |
| background        |              default.layer-one |             |
| background-hover  |                default.hovered |             |
| corner-radius     |           button.corner-radius |             |
| selected          |              button.background |             |
| hovered           | switch-button.selected::darker |             |
| text-selected     |           default.text-primary |             |
| text-not-selected |          default.text-tertiary |             |

#### keybind

| Key                |         Default Value | Description |
| ------------------ | --------------------: | ----------- |
| bound              |  default.text-primary |             |
| none               | default.text-tertiary |             |
| corner-radius      |  button.corner-radius |             |
| background         |     default.layer-one |             |
| background-hovered |       default.hovered |             |
| binding            |        default.accent |             |

#### boolean

| Key            |           Default Value | Description |
| -------------- | ----------------------: | ----------- |
| rounded-design | settings.rounded-design |             |
| true           |          default.accent |             |
| false          |       default.layer-two |             |
| knob           |    default.text-primary |             |

#### cloud

| Key             |                 Default Value | Description |
| --------------- | ----------------------------: | ----------- |
| corner-radius   |  default.corner-radius::div;2 |             |
| profile-picture |                   \[64,64,64] |             |
| star            |                default.accent |             |
| star-background | default.layer-two::brighter;5 |             |


# Hud Themables

### hud

| Key                   | Default Value  | Description                                                       |
| --------------------- | -------------- | ----------------------------------------------------------------- |
| text-primary          | \[245,245,245] | Color for the primary text                                        |
| text-secondary        | \[192,192,192] |                                                                   |
| text-tertiary         | \[128,128,128] |                                                                   |
| background-brightness | 0.7            | The brightness for the blurred background area.                   |
| background-tint       | \[0,0,0,50]    | The tint for the background.                                      |
| shadow-size           | 6              | Shadow size for the background.                                   |
| shadow-color          | \[0,0,0]       | Shadow color for the background.                                  |
| accent                | gradient       | You can choose out of `gradient`, `rainbow`, `pulse` and `none`.  |
| accent-color          | default.accent | Only used if you dont use one of the animations for the gradient. |

#### hud.gradient

| Key         | Default Value | Description                                      |
| ----------- | ------------- | ------------------------------------------------ |
| color-1     | \[60,140,255] | You can have up to 4 colors in your gradient.    |
| color-2     | \[110,75,255] |                                                  |
| color-3     | \[190,55,255] |                                                  |
| color-4     | \[255,75,200] |                                                  |
| color-count | 4             |                                                  |
| speed       | 3             | The speed of the animation.                      |
| step        | 600           | How many pixels it takes to lerp between colors. |

#### hud.rainbow

| Key        | Default Value | Description                                              |
| ---------- | ------------- | -------------------------------------------------------- |
| saturation | 0.5           | (between 0 and 1)                                        |
| brightness | 0.8           | (between 0 and 1)                                        |
| speed      | 5             | The speed of the animation.                              |
| step       | 600           | How many pixels it takes to lerp between rainbow colors. |

#### hud.pulse

<table><thead><tr><th width="249">Key</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td>intensity</td><td>0.4</td><td> (between 0 and 1)</td></tr><tr><td>speed</td><td>5</td><td>The speed of the animation.</td></tr><tr><td>step</td><td>600</td><td>How many pixels it takes to create the pulse effect.</td></tr></tbody></table>


# Background images

You can put a custom image behind the UI by setting `panel.background-img` &#x20;

```toml
[panel]
background-img="some.site/url/to/background.png
```

#### Requirments

* The image should preferably be **1320px by 840px**, any other size will be converted to this size by our servers.
* The image should be a **PNG** or **JPG**, other image formats are not supported.
* The image must be safe for work, anything that can be considered either NSFW or illegal will be removed swiftly and your account will be suspended.

#### Background generators

You can use whatever you want to make background images. We have found some powerful online  generators we highly recommend.&#x20;

<a href="https://app.haikei.app/" class="button primary">haikei</a><a href="https://better-gradient.com/editor" class="button primary">Better Gradient</a>

{% hint style="success" %}
We recommend experimenting with non full transparency backgrounds these can look great!
{% endhint %}


# Hello Kitty

```toml
[default]
accent = [255,20,247]
corner-radius = 25
border-thickness = 5
text-primary = [255, 215, 250]
text-secondary = [240, 190, 210]
text-tertiary = [225,210,210]
text-disabled = [100, 100, 100]
layer-zero = [47, 17,  37,  140]
layer-one = [30, 30, 30, 100]
layer-two = [40, 40, 40, 150]

[branding]
custom-color = true
logo-color = [255,80,255]

[panel]
separator = "default.accent"
border = "default.accent"
separator-thickness = 2
background-img = "<@breeze>/media/themes/81df911f-54e2-4baa-af0f-f5793a56b43d.png"
```