# Custom branding reference

> Change Unity Dashboard appearance with custom branding options.

Explore asset and color slots you can control with the `shared-assets` ConfigMap. To deploy the ConfigMap, refer to [Enable custom branding](enable-custom-branding).

## Customizable assets

The `shared-assets` ConfigMap holds the following assets:

| Asset            | Where it appears in Unity Dashboard                                                                          | Required |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | -------- |
| `logo.svg`       | Primary logo in the application header.                                                                      | No       |
| `label-logo.svg` | Compact logo in the sidebar footer when the navigation pane is collapsed.                                    | No       |
| `favicon.ico`    | Browser tab icon.                                                                                            | No       |
| `palette.json`   | Color palette for the light and dark themes. Applies to both Unity Dashboard and the embedded Asset Manager. | No       |
| `overrides.css`  | Stylesheet for fine-tuning logo dimensions, spacing, or other styling that the palette can't reach.          | No       |

If an asset is missing from the ConfigMap, Unity Dashboard uses the bundled default for that item.

Use the [boilerplate `shared-assets` ConfigMap](/cloud/virtual-private-cloud/admin/custom-branding/enable-custom-branding.md#boilerplate-shared-assets-configmap) as a starting point.

## CSS overrides

Use `overrides.css` to style elements the palette can't express, such as logo dimensions, brand mark spacing, or detailed data table tweaks. Unity Dashboard loads `overrides.css` after its bundled stylesheet, so any rule you provide takes effect without `!important`.

### CSS hooks for logos

The following table lists the CSS classes you can target:

| Class             | Element                                                                   |
| ----------------- | ------------------------------------------------------------------------- |
| `.vpc-logo`       | Primary logo in the application header.                                   |
| `.vpc-label-logo` | Compact logo in the sidebar footer when the navigation pane is collapsed. |

The default bundled stylesheet contains the following settings:

```css
.vpc-logo {
  height: 24px;
}

.vpc-label-logo {
  width: 51px;
  height: 24px;
}
```

### Example `overrides.css` snippets

```css
/* Taller header logo with extra right-side spacing. */
.vpc-logo {
  height: 32px;
  margin-right: 12px;
}

/* Square compact mark for the collapsed sidebar. */
.vpc-label-logo {
  width: 32px;
  height: 32px;
  object-fit: contain;
}

/* Tint a monochrome SVG to match the brand accent. Works only if the
   SVG uses fill="currentColor" or its paths are unstyled. */
.vpc-logo {
  color: #0a6ec8;
}

.vpc-logo path {
  fill: currentColor;
}

/* Reach a region the palette can't recolor: the data table pinned
   column shadow. */
.MuiDataGrid-pinnedColumns {
  box-shadow: -2px 0 4px rgba(0, 0, 0, 0.08);
}
```

### CSS override tips

* Keep the header logo height between 24 and 36 pixels. Larger values increase the header height and break the vertical alignment with the navigation icons.
* The compact logo (`.vpc-label-logo`) is only visible when the sidebar is collapsed. Verify both the expanded and collapsed states after editing.
* Prefer SVGs that use `fill="currentColor"` or unstyled paths, so a single CSS rule can recolor them and they respect the active light or dark scheme.
* For data table tweaks beyond what the palette allows, target `.MuiDataGrid-*` selectors.

## Theme palette structure

The `palette.json` file defines two color schemes, `light` and `dark`. End users switch between them from the **Theme** option in the user menu. Both schemes accept the same set of keys.

The default palette file has the following contents:

```json
{
  "colorSchemes": {
    "dark": {
      "palette": {
        "primary": {
          "main": "#0A6EC8",
          "dark": "#1361AD",
          "lighter": "#012348",
          "contrastText": "#C6E4FF"
        },
        "common": {
          "black": "#000000",
          "white": "#FFFFFF"
        },
        "divider": "rgba(255, 255, 255, 0.08)",
        "dividerElevation0": "#3a3a3a",
        "action": {
          "hover": "rgba(255, 255, 255, 0.071)",
          "selected": "#313131",
          "disabled": "#3a3a3a"
        },
        "error": { "main": "#e5484d" },
        "warning": { "main": "#ffc53d" },
        "success": { "main": "#30a46c" },
        "background": {
          "default": "#131313",
          "paper": "#191919",
          "paperElevation0": "#222222",
          "modalElevation": "#2a2a2a",
          "datagridHeader": "#222222"
        },
        "text": {
          "primary": "#eeeeee",
          "secondary": "#b4b4b4"
        },
        "grey": {
          "50": "#111111",
          "100": "#191919",
          "200": "#222222",
          "300": "#2a2a2a",
          "400": "#313131",
          "500": "#3a3a3a",
          "600": "#484848",
          "700": "#606060",
          "800": "#6e6e6e",
          "900": "#7b7b7b"
        }
      }
    },
    "light": {
      "palette": {
        "primary": {
          "main": "#0A6EC8",
          "dark": "#0060B8",
          "lighter": "#ECF5FF",
          "contrastText": "#0E345B"
        },
        "common": {
          "black": "#000000",
          "white": "#FFFFFF"
        },
        "divider": "rgba(0, 0, 0, 0.1)",
        "dividerElevation0": "#e8e8e8",
        "action": {
          "hover": "rgba(0, 0, 0, 0.059)",
          "selected": "#e8e8e8",
          "disabled": "#e0e0e0"
        },
        "error": { "main": "#e5484d" },
        "warning": { "main": "#ffc53d" },
        "success": { "main": "#30a46c" },
        "background": {
          "default": "#FFFFFF",
          "paper": "#fcfcfc",
          "paperElevation0": "#f9f9f9",
          "modalElevation": "#FFFFFF",
          "datagridHeader": "#f9f9f9"
        },
        "text": {
          "primary": "#202020",
          "secondary": "#646464"
        },
        "grey": {
          "50": "#fcfcfc",
          "100": "#f9f9f9",
          "200": "#f0f0f0",
          "300": "#e8e8e8",
          "400": "#e0e0e0",
          "500": "#d9d9d9",
          "600": "#cecece",
          "700": "#bbbbbb",
          "800": "#8d8d8d",
          "900": "#838383"
        }
      }
    }
  }
}
```

You don't need to provide every key. If you omit a key, Unity Dashboard uses the bundled default. A minimal palette can override only `primary.main`, `primary.contrastText`, `background.paper`, and `background.datagridHeader` and inherit the rest.

## Palette keys

The following keys are read from the palette and applied to Unity Dashboard.

### Brand and accent

| Key                            | Effect                                                                            |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `primary.main`                 | Brand accent for calls to action, avatars, links, and the selected-tab underline. |
| `primary.dark`                 | Hover and active state of contained primary buttons.                              |
| `primary.contrastText`         | Text color on contained primary buttons.                                          |
| `primary.lighter`              | Background of the selected row in data tables.                                    |
| `common.black`, `common.white` | Initials text on avatars and certain icon fills.                                  |

### Backgrounds and surfaces

| Key                          | Effect                                                                                                           |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `background.default`         | Application canvas behind page content.                                                                          |
| `background.paper`           | Cards, panels, headers, sidebars, popovers, modals, table body cells, and side panels. The most-visible surface. |
| `background.paperElevation0` | Background of a table row under the cursor.                                                                      |
| `background.modalElevation`  | Dialogs and modals, including the table column menu and filter panel.                                            |
| `background.datagridHeader`  | Table column header row, pagination footer, and pinned header background.                                        |

### Text

| Key              | Effect                                                                |
| ---------------- | --------------------------------------------------------------------- |
| `text.primary`   | Page titles, body text, primary navigation labels, and table content. |
| `text.secondary` | Section labels, captions, email addresses, and descriptive copy.      |

### Dividers and overlays

| Key                 | Effect                                                        |
| ------------------- | ------------------------------------------------------------- |
| `divider`           | Borders between elements, plus the chip background in tables. |
| `dividerElevation0` | Border of elevated popovers and table menus.                  |
| `action.hover`      | Translucent hover tint on icon buttons.                       |
| `action.selected`   | Background tint on the selected secondary navigation item.    |
| `action.disabled`   | Disabled control affordance.                                  |

### Status colors

| Key            | Effect                                                              |
| -------------- | ------------------------------------------------------------------- |
| `error.main`   | Notification badge, error states, and the **In review** status.     |
| `warning.main` | Warning states and the **Draft** status.                            |
| `success.main` | Success states, the organization icon, and the **Approved** status. |

### Neutral ramp

The `grey.50` through `grey.900` keys define the neutral color ramp for components that read `grey.*` directly. Provide all 10 steps to keep the ramp continuous.

## Palette tips

* Choose `background.paper` first, because it paints the most-visible surface (header, sidebars, popovers, table cells, side panels).
* Set `background.default` and `background.paper` to slightly different values (a 5–10% lightness step) so the page reads as elevated. Identical values look flat.
* Set `background.datagridHeader` to a value that differs from `background.paper`, so the table header doesn't disappear into the table body.
* `primary.main` controls more than buttons. It also paints avatars, links, and the selected-tab underline. Avoid pure-saturated brand reds because they collide with `error.main`.
* `primary.lighter` is the selected-row background. Keep it visibly tinted but soft enough that the text on top stays readable.
* `divider` doubles as the chip background in tables, so don't make it strongly chromatic.

## Where each palette key paints

The following screenshots show every region that each `palette.json` slot paints. They were captured with a demonstration palette where each slot has a unique color, so each region is visually distinct. In a real palette, regions that share a slot share the same color.

The demonstration palette uses these colors:

* `background.paper`: light amber `#fff8e1`, dark deep purple `#4a148c`
* `background.default`: light blue `#e3f2fd`, dark navy `#1a237e`
* `background.datagridHeader`: light lavender `#e1bee7`, dark deep red `#b71c1c`
* `background.paperElevation0` (row hover): light peach `#ffccbc`, dark teal-green `#00695c`
* `background.modalElevation`: light mint `#c8e6c9`, dark dark cyan `#006064`
* `primary.main`: hot pink `#ff007f` in both schemes
* `primary.lighter` (selected row): light very-light pink `#fce4ec`, dark deep magenta `#5a0030`
* `divider`: orange `#ff9800` in both schemes
* `dividerElevation0`: amber `#ffd54f` in both schemes
* `text.primary`: light navy `#1a237e`, dark yellow `#ffeb3b`
* `text.secondary`: light teal `#00695c`, dark light-teal `#80cbc4`
* `action.selected`: orange `#ff9800` translucent in both schemes
* `action.hover`: yellow `#ffeb3b` translucent in both schemes
* `error.main`: red `#f44336`. `warning.main`: amber `#ffc107`. `success.main`: green `#4caf50`

### Unity Dashboard shell

The standard signed-in view: top bar, primary navigation, secondary navigation, and content area.

![Unity Dashboard shell, light theme.](/api/media?file=/cloud/media/images/vpc-dashboard-a-shell-light.png)

![Unity Dashboard shell, dark theme.](/api/media?file=/cloud/media/images/vpc-dashboard-a-shell-dark.png)

The numbered regions in the screenshots use these palette keys:

1. Top bar: `background.paper`
2. Main content canvas behind cards and panels: `background.default`
3. Primary and secondary navigation sidebars: `background.paper`
4. Background of the selected primary navigation item: `action.selected`, applied as a translucent tint over `background.paper`
5. Section labels in the sidebars (such as **Administration**, **Organization**, and **Licensing**): `text.secondary`
6. Primary navigation labels: `text.primary`
7. Outlined call-to-action button text and border: `primary.main`
8. Borders between rows in the info card: `divider`
9. Organization icon background: `success.main`
10. Notification unread badge: `error.main`

### User menu popover

The popover that opens from the user avatar in the upper-right corner.

![User menu popover, light theme.](/api/media?file=/cloud/media/images/vpc-dashboard-b-user-menu-light.png)

![User menu popover, dark theme.](/api/media?file=/cloud/media/images/vpc-dashboard-b-user-menu-dark.png)

The numbered regions in the screenshots use these palette keys:

1. Popover surface: `background.paper`
2. Popover outer border: `divider`
3. Avatar circle when no photo is set: `primary.main`. Initials text: `common.white`
4. User display name: `text.primary`
5. Email address: `text.secondary`
6. Menu item labels: `text.primary`
7. Backdrop dim behind the popover: a semi-transparent overlay that doesn't come from `palette.json`

### Members table

The **Members** tab under **Administration** > **Settings**. This table uses the shared application table component.

![Members table, light theme.](/api/media?file=/cloud/media/images/vpc-dashboard-c1-table-members-light.png)

![Members table, dark theme.](/api/media?file=/cloud/media/images/vpc-dashboard-c1-table-members-dark.png)

The numbered regions in the screenshots use these palette keys:

1. Selected tab indicator (the **Members** underline): `primary.main`
2. Toolbar above the table (filter and search): `background.paper`
3. Column header row: `background.datagridHeader`
4. Body cells: `background.paper`
5. Border between rows: `divider`
6. Member avatar in the cell: `primary.main`
7. Member name: `text.primary`
8. Email address: `text.secondary`
9. Role and type chip background (such as **User** and **Owner**): `divider`
10. Roles list text: `text.primary`

### Groups table

The **Groups** tab under **Administration** > **Settings**.

![Groups table, light theme.](/api/media?file=/cloud/media/images/vpc-dashboard-c2-table-groups-light.png)

![Groups table, dark theme.](/api/media?file=/cloud/media/images/vpc-dashboard-c2-table-groups-dark.png)

The numbered regions in the screenshots use these palette keys:

1. Contained primary call-to-action button (**Create Group**): `primary.main` background, `primary.contrastText` text
2. Toolbar above the table (search field): `background.paper`
3. Column header row: `background.datagridHeader`
4. Body cells: `background.paper`
5. Pagination footer: `background.datagridHeader`
6. Borders between cells and rows: `divider`
7. Cell text: `text.primary`

### Asset Manager list view

The list view of **All assets** in Asset Manager. This view is rendered by the embedded Asset Manager submodule, which inherits the Unity Dashboard palette.

![Asset Manager list view, light theme.](/api/media?file=/cloud/media/images/vpc-dashboard-d-assets-list-light.png)

![Asset Manager list view, dark theme.](/api/media?file=/cloud/media/images/vpc-dashboard-d-assets-list-dark.png)

The numbered regions in the screenshots use these palette keys:

1. Contained primary call-to-action button (**+ Add**): `primary.main`
2. Toolbar (search, filters, view switcher): `background.paper`
3. Column header row: `background.datagridHeader`
4. Row under the cursor: `background.paperElevation0`
5. Pagination footer: `background.datagridHeader`
6. Right context panel (summary and recent activity): `background.paper`
7. Body cell: `background.paper`
8. Row borders: `divider`

### Selected row and side panel

The state when a row is selected in the asset list, which opens the side panel and the selection toolbar.

![Selected row and side panel, light theme.](/api/media?file=/cloud/media/images/vpc-dashboard-e-side-panel-light.png)

![Selected row and side panel, dark theme.](/api/media?file=/cloud/media/images/vpc-dashboard-e-side-panel-dark.png)

The numbered regions in the screenshots use these palette keys:

1. Selected row background: `primary.lighter`
2. Selected row checkbox: `primary.main`
3. Selection toolbar (**1 selected**, **Link**, **Download**, and so on): `background.paper`
4. Contained primary call-to-action button in the toolbar (**Open**): `primary.main`
5. Side panel surface: `background.paper`
6. Section labels in the side panel (**Description**, **Status**, **Projects**): `text.secondary`
7. Asset name: `text.primary`
8. Project chip background: `divider`