diff --git a/.stylelintrc b/.stylelintrc
index 378cb71431bf82ba5c8803e2c01fd97f233f4598..f1576fc48c00f48b05370cc896d0471ba2305fb2 100644
--- a/.stylelintrc
+++ b/.stylelintrc
@@ -20,8 +20,8 @@
},
{
"files": [
+ "app/assets/stylesheets/application_dark.scss",
"app/assets/stylesheets/framework/**/*.scss",
- "app/assets/stylesheets/themes/dark_mode_overrides.scss",
"app/assets/stylesheets/page_bundles/_ide_theme_overrides.scss"
],
"rules": {
diff --git a/app/assets/stylesheets/application_dark.scss b/app/assets/stylesheets/application_dark.scss
index f6ff4c58c21daaf6417019e4231b0e185e2ded41..47e0dc6f66f3179126ddf6158dbec49ed59e13e3 100644
--- a/app/assets/stylesheets/application_dark.scss
+++ b/app/assets/stylesheets/application_dark.scss
@@ -1,5 +1,44 @@
-@import './themes/dark';
-
+@import './color_modes/dark';
@import './application_base';
-@import './themes/dark_mode_overrides';
+:root.gl-dark {
+ color-scheme: dark;
+
+ /**
+ * Sets fill color for status SVGs in gitlab-svgs
+ */
+ --svg-status-bg: #{$white};
+
+ /**
+ * Redefine some colors and values to prevent sourcegraph conflicts
+ */
+ --gray-10: #{$gray-10};
+ --white: #{$white};
+ --black: #{$black};
+
+ /**
+ * Invert image assets in dark mode with same hue
+ */
+ .gl-dark-invert-keep-hue {
+ filter: invert(0.8) hue-rotate(180deg);
+ }
+
+ .gl-dark-invert-keep-hue\! {
+ filter: invert(0.8) hue-rotate(180deg) !important;
+ }
+
+ /**
+ * Decrease brightness and increase contrast for GlLabel in dark mode
+ */
+ .gl-label {
+ filter: brightness(0.9) contrast(1.1);
+ }
+
+ /**
+ * Override <code> background-color in dark mode to provide higher
+ * contrast on background.color.strong surface
+ */
+ .md :not(pre.code) > code {
+ background-color: $gray-200;
+ }
+}
diff --git a/app/assets/stylesheets/application_utilities_dark.scss b/app/assets/stylesheets/application_utilities_dark.scss
index eb32cdfc444f36b186d0195491871c6578993c4f..cec31d6ec302799d12017476398c625d0a5a31b3 100644
--- a/app/assets/stylesheets/application_utilities_dark.scss
+++ b/app/assets/stylesheets/application_utilities_dark.scss
@@ -1,3 +1,3 @@
-@import './themes/dark';
+@import './color_modes/dark';
@import 'application_utilities';
diff --git a/app/assets/stylesheets/themes/_dark.scss b/app/assets/stylesheets/color_modes/_dark.scss
similarity index 100%
rename from app/assets/stylesheets/themes/_dark.scss
rename to app/assets/stylesheets/color_modes/_dark.scss
diff --git a/app/assets/stylesheets/themes/dark_mode_overrides.scss b/app/assets/stylesheets/themes/dark_mode_overrides.scss
deleted file mode 100644
index e2083671e7728acdf7817805fa9d54ccda25b8aa..0000000000000000000000000000000000000000
--- a/app/assets/stylesheets/themes/dark_mode_overrides.scss
+++ /dev/null
@@ -1,43 +0,0 @@
-@import './themes/dark';
-@import 'page_bundles/mixins_and_variables_and_functions';
-
-:root {
- color-scheme: dark;
-
- --dark-icon-color-purple-1: #524a68;
- --dark-icon-color-purple-2: #715bae;
- --dark-icon-color-purple-3: #9a79f7;
- --dark-icon-color-orange-1: #665349;
- --dark-icon-color-orange-2: #b37a5d;
-
- --svg-status-bg: #{$white};
-}
-
-:root.gl-dark {
- // redefine some colors and values to prevent sourcegraph conflicts
- color-scheme: dark;
- --gray-10: #{$gray-10};
- --white: #{$white};
- --black: #{$black};
-}
-
-.gl-dark {
- .gl-dark-invert-keep-hue {
- filter: invert(0.8) hue-rotate(180deg);
- }
-
- .gl-dark-invert-keep-hue\! {
- filter: invert(0.8) hue-rotate(180deg) !important;
- }
-}
-
-// Decrease brightness and increase contrast for GlLabel in dark mode
-.gl-label {
- filter: brightness(0.9) contrast(1.1);
-}
-
-:root.gl-dark {
- .md :not(pre.code) > code {
- background-color: $gray-200;
- }
-}
diff --git a/doc/development/fe_guide/dark_mode.md b/doc/development/fe_guide/dark_mode.md
index 072290b2346af805672a3d141d3c96d28604fe2a..e9314cdb694545609ebd4cd2564a4c69b1305639 100644
--- a/doc/development/fe_guide/dark_mode.md
+++ b/doc/development/fe_guide/dark_mode.md
@@ -10,58 +10,30 @@ This page is about developing dark mode for GitLab. For more information on how
## How dark mode works
-1. The [color palette](https://design.gitlab.com/product-foundations/color) values are reversed using [design tokens](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/design_tokens.md) to provide darker colors for smaller scales.
-1. `app/assets/stylesheets/themes/_dark.scss` imports dark mode [design tokens](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/design_tokens.md) SCSS variables for colors.
-1. `app/assets/stylesheets/themes/dark_mode_overrides.scss` imports dark mode [design tokens](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/design_tokens.md) CSS custom properties for colors.
-1. Bootstrap variables overridden in `app/assets/stylesheets/framework/variables_overrides.scss` are given dark mode values in `_dark.scss`.
-1. `_dark.scss` is loaded _before_ `application.scss` to generate separate `application_dark.css` stylesheet for dark mode users only.
-
-## SCSS variables vs CSS custom properties
-
-Design tokens generate both SCSS variables and CSS custom properties which are imported into the dark mode stylesheet.
-
-- **SCSS variables:** are used in framework, components, and utility classes and override existing color usage for dark mode.
-- **CSS custom properties:** are used for any colors within the `app/assets/stylesheets/page_bundles` directory.
+### Current approach
-As we do not want to generate separate `*_dark.css` variants of every `page_bundle` file,
-we use CSS custom properties with SCSS variables as fallbacks. This is because when we generate the `page_bundles`
-CSS, we get the variable values from `_variables.scss`, so any SCSS variables have light mode values.
+1. GitLab UI includes light and dark mode [design tokens](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/design_tokens.md) CSS custom properties for colors and components.
+1. [Semantic design tokens](https://design.gitlab.com/product-foundations/design-tokens#semantic-design-tokens) provide values for light and dark mode in general usage, for example: background, text, and border colors.
-As the CSS custom properties defined in `_dark.scss` are available in the browser, they have the correct colors for dark mode.
+### Legacy approach
-```scss
-color: var(--gray-500, $gray-500);
-```
+1. SCSS variables for the [color palette](https://design.gitlab.com/product-foundations/color) are reversed using [design tokens](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/design_tokens.md) to provide darker colors for smaller scales.
+1. `app/assets/stylesheets/color_modes/_dark.scss` imports dark mode [design tokens](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/design_tokens.md) SCSS variables for colors.
+1. Bootstrap variables overridden in `app/assets/stylesheets/framework/variables_overrides.scss` are given dark mode values in `_dark.scss`.
+1. `_dark.scss` is loaded _before_ `application.scss` to generate separate `application_dark.css` stylesheet for dark mode users only.
## Utility classes
-We generate a separate `utilities_dark.css` file for utility classes containing the inverted values. So a class
-such as `gl-text-white` specifies a text color of `#333` in dark mode. This means you do not have to
-add multiple classes every time you want to add a color.
-
-Currently, we cannot set up a utility class only in dark mode. We hope to address that
-[issue](https://gitlab.com/gitlab-org/gitlab-ui/-/issues/1141) soon.
-
-## Using different values between light and dark mode
+Design tokens for dark mode can be applied with Tailwind classes (`gl-text-subtle`) or with `@apply` rule (`@apply gl-text-subtle`).
-In most cases, we can use the same values for light and dark mode. If that is not possible, you
-can add an override using the `.gl-dark` class that dark mode adds to `body`:
+## CSS custom properties vs SCSS variables
-```scss
-color: $gray-700;
-.gl-dark & {
- color: var(--gray-500);
-}
-```
+Design tokens generate both CSS custom properties and SCSS variables which are imported into the dark mode stylesheet.
-NOTE:
-Avoid using a different value for the SCSS fallback
+- **CSS custom properties:** are preferred to update color modes without loading a color mode specific stylesheet, and are required for any colors within the `app/assets/stylesheets/page_bundles` directory.
+- **SCSS variables:** override existing color usage for dark mode and are compiled into a color mode specific stylesheet.
-```scss
-// avoid where possible
-// --gray-500 (#999) in dark mode
-// $gray-700 (#525252) in light mode
-color: var(--gray-500, $gray-700);
-```
+### Page bundles
-We [plan to add](https://gitlab.com/groups/gitlab-org/-/epics/7400) the CSS variables to light mode. When that happens, different values for the SCSS fallback will no longer work.
+To support dark mode CSS custom properties should be used in `page_bundle` styles as we do not generate separate
+`*_dark.css` variants of each `page_bundle` file.