Implement Wazuh custom UI theme

[asteriscos]

Description

As part of the objective Dashboard revamp, we want to implement a customized theme for the Wazuh dashboard UI. To achieve this, we have to follow the guidelines of a standard OpenSearch UI components library so we can integrate the theme as seamlessly as possible into the Wazuh dashboard platform.

Objective:

• Dashboard revamp #408

Functional requirements

• The Wazuh UI theme must be based on a standard OpenSearch UI library theme.

Tasks

• Design a Wazuh UI theme (selectable from ui and default theme)
• Integrate it in Wazuh dashboard

[guidomodarelli]

Research 2024/12/23

I have been researching to implement the Wazuh custom UI theme.

I reviewed the PRs (#7757) (#7775) where the v9 theme of OpenSearch-Dashboards was added, and read the Theme definitions in OUI and noted the places that would need editing to make the theme change effective.

packages/osd-ui-shared-deps/theme_config.d.ts

diff --git a/packages/osd-ui-shared-deps/theme_config.d.ts b/packages/osd-ui-shared-deps/theme_config.d.ts
index 080611cddc..d01edddd8c 100644
--- a/packages/osd-ui-shared-deps/theme_config.d.ts
+++ b/packages/osd-ui-shared-deps/theme_config.d.ts
@@ -6,7 +6,7 @@
 /**
  * Types for valid theme versions
  */
-type ThemeVersion = 'v7' | 'v8' | 'v9';
+type ThemeVersion = 'v7' | 'v8' | 'v9' | 'wazuh';
 
 /**
  * Types for valid theme color-scheme modes
@@ -17,7 +17,15 @@ type ThemeMode = 'light' | 'dark';
  * Types for valid theme tags (themeVersion + themeMode)
  * Note: used by @osd/optimizer
  */
-export type ThemeTag = 'v7light' | 'v7dark' | 'v8light' | 'v8dark' | 'v9light' | 'v9dark';
+export type ThemeTag =
+  | 'v7light'
+  | 'v7dark'
+  | 'v8light'
+  | 'v8dark'
+  | 'v9light'
+  | 'v9dark'
+  | 'wazuhlight'
+  | 'wazuhdark';
 export type ThemeTags = readonly ThemeTag[];
 
 /**

---

packages/osd-ui-shared-deps/theme_config.js

diff --git a/packages/osd-ui-shared-deps/theme_config.js b/packages/osd-ui-shared-deps/theme_config.js
index ad782d98b2..0372766ddb 100644
--- a/packages/osd-ui-shared-deps/theme_config.js
+++ b/packages/osd-ui-shared-deps/theme_config.js
@@ -16,6 +16,7 @@ const THEME_VERSION_LABEL_MAP = {
   v7: 'v7',
   v8: 'Next (preview)',
   v9: 'v9 (preview)',
+  wazuh: 'Wazuh',
 };
 const THEME_VERSION_VALUE_MAP = {
   // allow version lookup by label ...
@@ -56,4 +57,5 @@ exports.kuiCssDistFilenames = {
   v7: { dark: 'kui_dark.css', light: 'kui_light.css' },
   v8: { dark: 'kui_next_dark.css', light: 'kui_next_light.css' },
   v9: { dark: 'kui_v9_dark.css', light: 'kui_v9_light.css' },
+  wazuh: { dark: 'kui_wazuh_dark.css', light: 'kui_wazuh_light.css' },
 };

---

packages/osd-ui-shared-deps/theme.ts

diff --git a/packages/osd-ui-shared-deps/theme.ts b/packages/osd-ui-shared-deps/theme.ts
index 965e1aa928..55ca389df7 100644
--- a/packages/osd-ui-shared-deps/theme.ts
+++ b/packages/osd-ui-shared-deps/theme.ts
@@ -35,10 +35,12 @@ const globals: any = typeof window === 'undefined' ? {} : window;
 
 export type Theme = typeof LightTheme;
 
+const DEFAULT_THEME = 'wazuh';
+
 // in the OpenSearch Dashboards app we can rely on this global being defined, but in
 // some cases (like jest) the global is undefined
 export const tag: string = globals.__osdThemeTag__;
-const themeVersion = tag?.replace(/(light|dark)$/, '') || 'v7';
+const themeVersion = tag?.replace(/(light|dark)$/, '') || DEFAULT_THEME;
 export const version = parseInt(themeVersion.replace(/[^\d]+/g, ''), 10) || 8;
 export const darkMode = tag?.endsWith?.('dark');
 
@@ -50,6 +52,9 @@ if (themeVersion === 'v7') {
 } else if (themeVersion === 'v9') {
   euiLightVars = require('@elastic/eui/dist/eui_theme_v9_light.json');
   euiDarkVars = require('@elastic/eui/dist/eui_theme_v9_dark.json');
+} else if (themeVersion === DEFAULT_THEME) {
+  euiLightVars = require('@elastic/eui/dist/eui_theme_wazuh_light.json');
+  euiDarkVars = require('@elastic/eui/dist/eui_theme_wazuh_dark.json');
 } else {
   euiLightVars = require('@elastic/eui/dist/eui_theme_next_light.json');
   euiDarkVars = require('@elastic/eui/dist/eui_theme_next_dark.json');

---

packages/osd-ui-framework/Gruntfile.js

diff --git a/packages/osd-ui-framework/Gruntfile.js b/packages/osd-ui-framework/Gruntfile.js
index e6c580f91b..2c895b80d2 100644
--- a/packages/osd-ui-framework/Gruntfile.js
+++ b/packages/osd-ui-framework/Gruntfile.js
@@ -99,6 +99,8 @@ module.exports = function (grunt) {
       uiFrameworkCompile('src/kui_next_dark.scss', 'dist/kui_next_dark.css'),
       uiFrameworkCompile('src/kui_v9_light.scss', 'dist/kui_v9_light.css'),
       uiFrameworkCompile('src/kui_v9_dark.scss', 'dist/kui_v9_dark.css'),
+      uiFrameworkCompile('src/kui_wazuh_light.scss', 'dist/kui_wazuh_light.css'),
+      uiFrameworkCompile('src/kui_wazuh_dark.scss', 'dist/kui_wazuh_dark.css'),
     ]).then(done);
   });
 };

The following *.scss files need to be added, and then yarn compileCss must be run inside the packages/osd-ui-framework folder:

Add packages/osd-ui-framework/src/kui_wazuh_dark.scss

// EUI global scope is used for KUI variables till fully deprecated
@import "../../../node_modules/@elastic/eui/src/global_styling/functions/index";
@import "../../../node_modules/@elastic/eui/src/global_styling/variables/index";
@import "../../../node_modules/@elastic/eui/src/global_styling/mixins/index";

// Configuration
@import "global_styling/variables/index";

// Coreß
@import "global_styling/mixins/index";
@import "global_styling/reset/index";

// Components
@import "components/index";

Add packages/osd-ui-framework/src/kui_wazuh_light.scss

// EUI global scope is used for KUI variables till fully deprecated
@import "../../../node_modules/@elastic/eui/src/global_styling/functions/index";
@import "../../../node_modules/@elastic/eui/src/global_styling/variables/index";
@import "../../../node_modules/@elastic/eui/src/global_styling/mixins/index";

// Configuration
@import "global_styling/variables/index";

// Core
@import "global_styling/mixins/index";
@import "global_styling/reset/index";

// Components
@import "components/index";

---

src/core/server/ui_settings/ui_settings_config.ts

diff --git a/src/core/server/ui_settings/ui_settings_config.ts b/src/core/server/ui_settings/ui_settings_config.ts
index 1a0c0e48f5..98b90608b7 100644
--- a/src/core/server/ui_settings/ui_settings_config.ts
+++ b/src/core/server/ui_settings/ui_settings_config.ts
@@ -37,7 +37,7 @@ const deprecations: ConfigDeprecationProvider = ({ unused, renameFromRoot }) =>
   renameFromRoot('server.defaultRoute', 'uiSettings.overrides.defaultRoute'),
 ];
 
-export const DEFAULT_THEME_VERSION = 'v7';
+export const DEFAULT_THEME_VERSION = 'wazuh';
 
 /* There are 4 levels of uiSettings:
  *   1) defaults hardcoded in code

---

src/core/server/ui_settings/settings/theme.ts

diff --git a/src/core/server/ui_settings/settings/theme.ts b/src/core/server/ui_settings/settings/theme.ts
index 001a693d62..81328bbf1c 100644
--- a/src/core/server/ui_settings/settings/theme.ts
+++ b/src/core/server/ui_settings/settings/theme.ts
@@ -35,11 +35,11 @@ import type { Type } from '@osd/config-schema';
 import { UiSettingsParams } from '../../../types';
 import { DEFAULT_THEME_VERSION } from '../ui_settings_config';
 
-// Setup theme options to be backwards compatible with the fact that v8 was persisted with its
+// Setup theme options to be backwards compatible with the fact that `wazuh` was persisted with its
 // label rather than with the correct themeVersion value
 const THEME_VERSIONS = Object.keys(themeVersionLabelMap);
-const THEME_SCHEMA_VALUES = THEME_VERSIONS.concat(themeVersionLabelMap.v8);
-const THEME_OPTIONS = THEME_VERSIONS.map((v) => (v !== 'v8' ? v : themeVersionLabelMap.v8));
+const THEME_SCHEMA_VALUES = THEME_VERSIONS.concat(themeVersionLabelMap.wazuh);
+const THEME_OPTIONS = THEME_VERSIONS.map((v) => (v !== 'wazuh' ? v : themeVersionLabelMap.wazuh));
 
 export const getThemeSettings = (): Record<string, UiSettingsParams> => {
   return {
@@ -60,7 +60,7 @@ export const getThemeSettings = (): Record<string, UiSettingsParams> => {
         defaultMessage: 'Theme version',
       }),
       value:
-        DEFAULT_THEME_VERSION === 'v7'
+        DEFAULT_THEME_VERSION === 'wazuh'
           ? themeVersionLabelMap[DEFAULT_THEME_VERSION]
           : DEFAULT_THEME_VERSION,
       type: 'select',

It is necessary to modify some files with references to files located in @elastic/eui, which are references to compiled *.json and *.css files:

diff --git a/packages/osd-ui-shared-deps/webpack.config.js b/packages/osd-ui-shared-deps/webpack.config.js
index 8a9e50dd05..883525c692 100644
--- a/packages/osd-ui-shared-deps/webpack.config.js
+++ b/packages/osd-ui-shared-deps/webpack.config.js
@@ -49,6 +49,8 @@ exports.getWebpackConfig = ({ dev = false } = {}) => ({
     'osd-ui-shared-deps.v8.light': ['@elastic/eui/dist/eui_theme_next_light.css'],
     'osd-ui-shared-deps.v9.dark': ['@elastic/eui/dist/eui_theme_v9_dark.css'],
     'osd-ui-shared-deps.v9.light': ['@elastic/eui/dist/eui_theme_v9_light.css'],
+    'osd-ui-shared-deps.wazuh.light': ['@elastic/eui/dist/eui_theme_wazuh_light.css'],
+    'osd-ui-shared-deps.wazuh.dark': ['@elastic/eui/dist/eui_theme_wazuh_dark.css'],
   },
   context: __dirname,
   devtool: dev ? '#cheap-source-map' : false,
diff --git a/src/core/server/rendering/views/theme.ts b/src/core/server/rendering/views/theme.ts
index ee628a856f..173da48e46 100644
--- a/src/core/server/rendering/views/theme.ts
+++ b/src/core/server/rendering/views/theme.ts
@@ -22,10 +22,14 @@ export const THEME_SOURCES: {
     [ThemeColorSchemes.LIGHT]: '@elastic/eui/dist/eui_theme_v9_light.json',
     [ThemeColorSchemes.DARK]: '@elastic/eui/dist/eui_theme_v9_dark.json',
   },
-  default: {
+  v8: {
     [ThemeColorSchemes.LIGHT]: '@elastic/eui/dist/eui_theme_next_light.json',
     [ThemeColorSchemes.DARK]: '@elastic/eui/dist/eui_theme_next_dark.json',
   },
+  default: {
+    [ThemeColorSchemes.LIGHT]: '@elastic/eui/dist/eui_theme_wazuh_light.json',
+    [ThemeColorSchemes.DARK]: '@elastic/eui/dist/eui_theme_wazuh_dark.json',
+  },
 });
 
 export const getThemeDefinitionSource = (

Then, you should run yarn osd:bootstrap in packages/osd-ui-shared-deps.

The following files are required by webpack:

Add src/core/public/core_app/styles/_globals_wazuhlight.scss

@import "@elastic/eui/src/themes/wazuh/wazuh_globals";

@import "./mixins";

Add src/core/public/core_app/styles/_globals_wazuhdark.scss

@import "@elastic/eui/src/themes/wazuh/wazuh_globals";

@import "./mixins";

The files @elastic/eui/dist/eui_theme_wazuh_light.json, @elastic/eui/dist/eui_theme_wazuh_dark.json, @elastic/eui/dist/eui_theme_wazuh_light.css, and @elastic/eui/dist/eui_theme_wazuh_dark.css are generated at compile time and are not present in the source code of https://github.com/opensearch-project/oui. Therefore, I suggest creating a fork of the https://github.com/opensearch-project/oui project and making the necessary changes there to generate these files correctly and avoid potential issues from manual editing, which could lead to significant inconsistencies.

Summary

In summary, the changes made aim to implement a custom Wazuh theme in OpenSearch Dashboards. The adjustments include:

1. Theme configuration update:

   • Inclusion of the wazuh theme version and its modes (wazuhlight, wazuhdark) in relevant configuration files and types.
   • Setting the wazuh theme as the default theme in multiple locations.

2. Build process modification:

   • Addition of rules in the Gruntfile.js and creation of SCSS files (kui_wazuh_light.scss, kui_wazuh_dark.scss) to generate the theme styles.
   • Adjustment of build scripts to correctly process these new SCSS files.

3. References to EUI resources:

   • Updating references to json and css files generated from @elastic/eui to include those specific to the wazuh theme.

4. Wazuh theme resource compilation:

   • Creation of a fork of the OUI project to generate the missing resources (eui_theme_wazuh_light.json, eui_theme_wazuh_dark.json, etc.) during the build, ensuring consistency and avoiding manual errors.

[guidomodarelli]

Analysis of the pros and cons of copying generated files for manual editing versus forking the project to compile files from the code

1. Copying and manually editing the generated files

Advantages:

• Initial simplicity: It does not require familiarizing oneself with the full project build process of OUI or forking it, saving time at the start.
• Speed: Changes can be made quickly without setting up the development environment of the original project.
• Direct control: Changes are made directly in the generated files, allowing immediate adjustments to styles and configurations.

Disadvantages:

• Lack of traceability: Manual changes are not recorded in the development history of the original project, making collaboration and long-term maintenance difficult.
• High risk of errors: Manual adjustments can introduce inconsistencies or errors that are hard to debug or track.
• Lack of automation: If the original files change in future versions of the OUI project, manual adjustments will need to be repeated, which can be tedious and prone to failure.
• Third-party dependency: Without controlling the generation process of these files, any change in the base project (OUI) can invalidate the manual adjustments.

2. Forking the project and generating the compiled files

Advantages:

• Automation and consistency: The files are automatically generated from the source code of the fork, ensuring that any future changes are consistent and reproducible.
• Flexibility for future updates: Facilitates the integration of new versions of the base project, as changes can be incorporated into the fork and the files can be regenerated.
• Change tracking: Adjustments made in the fork are documented in version control (Git), making collaboration and maintenance easier.
• Scalability: If further customization is needed in the future, the development environment of the fork can be leveraged without duplicating efforts.

Disadvantages:

• Greater initial effort: It is necessary to set up the environment to compile the project fork, which can be more complex and time-consuming at first.
• Learning curve: It may require learning about the compilation process and the structure of the original project.
• Fork maintenance: You will need to keep the fork updated with changes from the original project to avoid significant divergences.

---

Conclusion

Since the goal is to maintain the customized theme long-term and ensure smooth integration with future updates of the OUI project, the best strategy is to fork, as it provides consistency, automation, and traceability.

[guidomodarelli]

Test 2024/12/24