Remove dark_mode_overrides.scss file

Remove linting and docs mentions of `dark_mode_overrides.scss`
Move leftover contents into `application_dark.scss`
Rename `themes/_dark.scss` to `color_modes/_dark.scss` to match model
name and update imports

.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": {

app/assets/stylesheets/application_dark.scss

-@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;
+  }
+}

app/assets/stylesheets/application_utilities_dark.scss

-@import './themes/dark';
+@import './color_modes/dark';
 
 @import 'application_utilities';

app/assets/stylesheets/themes/dark_mode_overrides.scss

-@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;
-  }
-}

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.