|
| 1 | +--- |
| 2 | +title: custom-logos |
| 3 | +authors: |
| 4 | + - "@cajieh" |
| 5 | +reviewers: |
| 6 | + - "@jhadvig " |
| 7 | + - "@spadgett" |
| 8 | + - "@everettraven" |
| 9 | + - "@JoelSpeed" |
| 10 | +approvers: |
| 11 | + - "@spadgett" |
| 12 | +api-approvers: |
| 13 | + - "@JoelSpeed" |
| 14 | +creation-date: 2025-02-11 |
| 15 | +last-updated: 2025-03-24 |
| 16 | +--- |
| 17 | + |
| 18 | +# Console Customization Logos |
| 19 | + |
| 20 | +## Summary |
| 21 | + |
| 22 | +The OpenShift Container Platform (OCP) web console was upgraded to PatternFly 6. In PatternFly 6, the masthead color changes based on light or dark theme mode. As a result, a single custom logo may not be suitable for both theme modes. |
| 23 | + |
| 24 | +This proposal is to add the ability to specify custom logos to support light and dark theme modes for the masthead and favicon in the Console UI. |
| 25 | + |
| 26 | +## Background info |
| 27 | + |
| 28 | +The OpenShift Container Platform (OCP) web console was upgraded to PatternFly 6. In PatternFly 6, the masthead color changes based on light or dark theme mode. As a result, a single custom logo may not be suitable for both theme modes. |
| 29 | + |
| 30 | +To address this, we need to allow users to add custom logos compatible with light and dark theme modes for both the masthead and favicon. This ensures that the logos are always visible and aesthetically pleasing, regardless of the theme mode. |
| 31 | + |
| 32 | +The custom logos feature will enable users to specify different logos for the masthead and favicon based on the theme mode. This will involve exposing a new API endpoint to support custom logos for both light and dark theme modes. |
| 33 | + |
| 34 | +## Motivation |
| 35 | + |
| 36 | +The existing OKD and OpenShift logos are designed for a dark masthead background and include white text, making them ineffective in a light theme mode. To ensure logos remain visible and visually appealing in both light and dark theme modes, users need the ability to add custom logos for the masthead and favicon that adapt to the theme mode. To support this, a new API endpoint will be introduced, allowing users to specify different logos for light and dark theme modes. |
| 37 | + |
| 38 | +### User Stories |
| 39 | + |
| 40 | +* As an OpenShift web console user, I want to be able to add different custom logos for light and dark theme modes in the masthead and favicon. |
| 41 | + |
| 42 | +### Goals |
| 43 | + |
| 44 | +This feature will allow users to add custom logos for the masthead and favicon that are compatible with both light and dark theme modes in the OpenShift web console. |
| 45 | + |
| 46 | +### Non-Goals |
| 47 | + |
| 48 | +This feature does not aim to address other customization aspects of the web console outside of logos. |
| 49 | + |
| 50 | +## Proposal |
| 51 | + |
| 52 | +The proposal introduces a new API schema that allows users to configure custom logos for the masthead and favicon. The configuration will support specifying separate logos for light and dark theme modes, ensuring compatibility with the PatternFly 6 theme switching. |
| 53 | + |
| 54 | +### API Design Details |
| 55 | + |
| 56 | +The configuration for custom logos will include support for both masthead and favicon types with separate files for light and dark theme modes. The following schema will be used: |
| 57 | + |
| 58 | +#### Console Customization Logo API Schema |
| 59 | + |
| 60 | +#### ThemeMode |
| 61 | +- **Description**: Specifies the theme mode for the console UI. |
| 62 | +- **Values**: `"Dark"`, `"Light"` |
| 63 | + |
| 64 | +#### LogoType |
| 65 | +- **Description**: Specifies the type of logo for the console UI. |
| 66 | +- **Values**: `"Masthead"`, `"Favicon"` |
| 67 | + |
| 68 | +#### SourceType |
| 69 | +- **Description**: Defines the source type of the file reference. |
| 70 | +- **Values**: `"ConfigMap"` |
| 71 | + |
| 72 | +#### ConfigMapFileReference |
| 73 | +- **Fields**: |
| 74 | + - `name`: The name of the ConfigMap containing the custom logo file. |
| 75 | + - `key`: The key inside the ConfigMap that references the logo file. |
| 76 | + |
| 77 | +#### FileReferenceSource |
| 78 | +- **Fields**: |
| 79 | + - `from`: Specifies the source type of the file reference (e.g., `ConfigMap`). |
| 80 | + - `configMap`: Contains the ConfigMap name and key for the logo file. |
| 81 | + |
| 82 | +#### Theme |
| 83 | +- **Fields**: |
| 84 | + - `mode`: Specifies the theme mode (`Dark` or `Light`). |
| 85 | + - `source`: Specifies the file reference source for the logo. |
| 86 | + |
| 87 | +#### Logo |
| 88 | +- **Fields**: |
| 89 | + - `type`: Specifies the type of logo (`Masthead` or `Favicon`). |
| 90 | + - `themes`: A list of themes for the logo, each specifying a mode and source. |
| 91 | + |
| 92 | +#### ConsoleCustomization |
| 93 | +- **Fields**: |
| 94 | + - `logos`: A list of custom logos for the console UI. |
| 95 | + - `customLogoFile`: Deprecated field for a single custom logo. |
| 96 | + |
| 97 | +#### Example Configuration |
| 98 | + |
| 99 | +```yaml |
| 100 | +logos: |
| 101 | + - type: Masthead |
| 102 | + themes: |
| 103 | + - mode: Light |
| 104 | + source: |
| 105 | + from: ConfigMap |
| 106 | + configMap: |
| 107 | + name: custom-logos-config |
| 108 | + key: masthead-light-logo.svg |
| 109 | + - mode: Dark |
| 110 | + source: |
| 111 | + from: ConfigMap |
| 112 | + configMap: |
| 113 | + name: custom-logos-config |
| 114 | + key: masthead-dark-logo.svg |
| 115 | + - type: Favicon |
| 116 | + themes: |
| 117 | + - mode: Light |
| 118 | + source: |
| 119 | + from: ConfigMap |
| 120 | + configMap: |
| 121 | + name: custom-logos-config |
| 122 | + key: favicon-light-logo.png |
| 123 | + - mode: Dark |
| 124 | + source: |
| 125 | + from: ConfigMap |
| 126 | + configMap: |
| 127 | + name: custom-logos-config |
| 128 | + key: favicon-dark-logo.png |
| 129 | +``` |
| 130 | +
|
| 131 | +### Workflow Description |
| 132 | +
|
| 133 | +├── spec |
| 134 | +│ ├── customization |
| 135 | +│ ├── logos |
| 136 | +│ ├── type |
| 137 | +│ ├── themes |
| 138 | +│ ├── mode |
| 139 | +│ ├── source |
| 140 | +│ ├── from |
| 141 | +│ ├── configMap |
| 142 | +│ ├── name |
| 143 | +│ ├── key |
| 144 | +└── ... |
| 145 | +
|
| 146 | +### Risks and Mitigations |
| 147 | +
|
| 148 | +1. Each of the Console supported theme modes can be configured individually by setting either the Light or Dark theme mode. If a theme is not specified, the default OpenShift logo will be displayed for that theme. |
| 149 | +
|
| 150 | +2. Users might experience confusion with the introduction of new logo configuration options. The previous method, represented by `CustomLogo`, will be deprecated. Provide comprehensive documentation to guide users through the transition, including clear instructions about the changes and their benefits. |
| 151 | + |
| 152 | +### Attributes Description |
| 153 | + |
| 154 | +#### ConsoleCustomization |
| 155 | +- `logos`: A list of custom logos used to replace the OpenShift Masthead and Favicon logos in the console UI. Only one of `logos` or `customLogoFile` can be set at a time. Each logos type must appear only once in the list, and there must be at least one entry and no more than two entries. |
| 156 | + |
| 157 | +#### Logo |
| 158 | +- `type`: Specifies the type of the logo for the console UI. Allowed values are `Masthead` and `Favicon`. |
| 159 | + - `Masthead`: The logo is displayed in the masthead and about modal of the console UI. |
| 160 | + - `Favicon`: The logo is used as the favicon of the console UI. |
| 161 | +- `themes`: A list of themes for the logo. Each theme must have a unique mode (`Light` or `Dark`) and a source field. If a theme is not specified, the default OpenShift logo will be displayed for that theme. |
| 162 | + |
| 163 | +#### Theme |
| 164 | +- `mode`: Specifies the theme mode for the logo. Allowed values are: |
| 165 | + - `Light`: The logo is used when the console UI is in light mode. |
| 166 | + - `Dark`: The logo is used when the console UI is in dark mode. |
| 167 | +- `source`: Specifies the file reference source for the logo. This is a required field that references a ConfigMap name and key containing the custom logo file in the `openshift-config` namespace. |
| 168 | + |
| 169 | +#### FileReferenceSource |
| 170 | +- `from`: Specifies the source type of the file reference. Allowed value is `ConfigMap`. |
| 171 | +- `configMap`: Contains the ConfigMap sourcing details, such as the name of the ConfigMap and the key for the file. The ConfigMap must exist in the `openshift-config` namespace. |
| 172 | + |
| 173 | +#### ConfigMapFileReference |
| 174 | +- `name`: The name of the ConfigMap containing the custom logo file. Must consist of lowercase alphanumeric characters, `-`, or `.`, and must start and end with an alphanumeric character. Maximum length is 253 characters. |
| 175 | +- `key`: The key inside the ConfigMap that references the logo file. Must consist of alphanumeric characters, dashes (`-`), underscores (`_`), and periods (`.`). Must end with a valid file extension (2 to 5 letters) and have a maximum length of 253 characters. |
| 176 | + |
| 177 | + |
| 178 | +## Test Plan |
| 179 | + |
| 180 | +Provide tests as part of the console logos implementation and verify that they are shown in the UI. The following tests will be added: |
| 181 | + - Unit tests for API |
| 182 | + - Unit and E2E tests for console-operator |
| 183 | + - E2E tests for console |
| 184 | + |
| 185 | +#### Deprecated Feature |
| 186 | + |
| 187 | +The current custom logo field in `customization.customLogo` is deprecated and will be removed in a future release. Users are encouraged to transition to the new custom logos configuration that supports light and dark theme modes for the masthead and favicon. |
0 commit comments