feat(root): added dark mode guidance

added explaination of dark mode terminology, and gave examples of how to apply through theme and across a larger app through a pattern page
mi6 · Dec 5, 2024 · 100daff · 100daff
1 parent 4348d0c
commit 100daff
Show file tree

Hide file tree

Showing 5 changed files with 606 additions and 7 deletions.
diff --git a/src/content/structured/get-started/custom-theme.mdx b/src/content/structured/get-started/custom-theme.mdx
@@ -3,24 +3,29 @@ path: "/get-started/install-components/custom-theme"
 
 navPriority: 9
 
-date: "2024-02-05"
+date: "2024-12-02"
 
 title: "Custom theme"
 
-subTitle: "How to change the theme colour of some components."
+subTitle: "How to change the colours of some components."
 
 contribute: "https://github.com/mi6/ic-design-system/tree/main/src/content/structured/get-started/custom-theme.mdx"
 ---
 
+import { useState } from "react";
+import { IcAlert, IcButton, IcTheme } from "@ukic/react";
+
 ## Customising component colours
 
-Some components can have their theme colour changed by using either of the methods below. When the theme colour is changed, components will automatically update.
+Some components can have their 'brand' colour changed by using either of the methods below. When the 'brand' colour is changed, components will automatically update.
 
 Other styles on affected components will also adapt accordingly, such as the colour of text or icons.
 
+Components that follow the 'brand' colour will not update in the same way as other components when adapting to dark mode. Instead their appearance will only adjust to match the contrast of the 'brand' colour.
+
 ## CSS variables
 
-You can set the theme colour by using the three CSS variables (one for each of the RGB values for the colour) shown below:
+You can set the 'brand' colour by using the three CSS variables (one for each of the RGB values for the colour) shown below:
 
 ```css
 :root {
@@ -39,9 +44,144 @@ Alternatively, you can include the `ic-theme` component and set the `color` prop
 <ic-theme color="#5c0949"></ic-theme>
 ```
 
-### Components that use the theme colour
+### Components that use the 'brand' colour
 
 - [Footer](/components/footer)
 - [Hero](/components/hero)
 - [Side navigation](/components/side-navigation)
 - [Top navigation](/components/top-navigation)
+
+## Dark mode
+
+Each component's variants can be displayed using dark mode colours. This creates better colour contrast with backgrounds, borders and text for when components need to be used on dark backgrounds.
+
+Each component has been given a `theme` prop, taking values of `inherit` (default), `light` and `dark`. By setting the value to either `light` or `dark` at the component level, those components will display dark mode colours, independent of any higher level themes or system settings.
+
+By leaving the theme prop as the default value (`inherit`), it will decide the colours based on either a high-level `ic-theme` component, or if one does not exist, the browser/system settings.
+
+### Dark mode example
+
+See the [Dark mode pattern](/patterns/dark-mode) for an example of how to implement dark mode into an application.
+
+export const snippetsDefault = [
+  {
+    technology: "Web component",
+    snippets: {
+      short: `<ic-button onclick="handleClick()">Update ic-theme</ic-button>
+<ic-theme class="theme-container" theme="light">
+  <ic-alert heading="Set at component level" variant="info" theme="light"></ic-alert>
+  <ic-alert heading="Inherits from ic-theme" variant="info"></ic-alert>
+</ic-theme>
+<ic-alert heading="Inherits from system/browser settings" variant="info"></ic-alert>`,
+      long: `.theme-container {
+    border: "1px solid var(--ic-architectural-white)",
+    padding: "var(--ic-space-sm)"
+  }
+</style>
+<body>
+  <div>
+    {shortCode}
+  </div>
+  <script>
+    function handleClick() {
+      theme = document.querySelector("ic-theme");
+      theme.theme = theme.theme === "light" ? "dark" : "light";
+    }
+  </script>`,
+    },
+  },
+  {
+    technology: "React",
+    snippets: {
+      short: `<IcButton onClick={handleClick}>Update ic-theme</IcButton>
+<IcTheme theme={theme} className={classes.themeContainer}>
+  <IcAlert heading="Set at component level" variant="info" theme="light" />
+  <IcAlert heading="Inherits from ic-theme" variant="info" />
+</IcTheme>
+<IcAlert heading="Inherits from system/browser settings" variant="info" />`,
+      long: [
+        {
+          language: "Typescript",
+          snippet: `const [theme, setTheme] = useState<"light" | "dark">("light");
+const handleClick = () => {
+  setTheme(theme === "light" ? "dark" : "light");
+};
+const useStyles = createUseStyles({
+  themeContainer: {
+    border: "1px solid var(--ic-architectural-white)",
+    padding: "var(--ic-space-sm)"
+  },
+});
+const classes = useStyles();
+<>
+  {shortCode}
+</>`,
+        },
+        {
+          language: "Javascript",
+          snippet: `const [theme, setTheme] = useState("light");
+const handleClick = () => {
+  setTheme(theme === "light" ? "dark" : "light");
+};
+const useStyles = createUseStyles({
+  themeContainer: {
+    border: "1px solid var(--ic-architectural-white)",
+    padding: "var(--ic-space-sm)"
+  },
+});
+const classes = useStyles();
+<>
+  {shortCode}
+</>`,
+        },
+      ],
+    },
+  },
+];
+
+export const DarkModeExample = () => {
+  const [theme, setTheme] = useState("light");
+  const handleClick = () => {
+    setTheme(theme === "light" ? "dark" : "light");
+  };
+  return (
+    <>
+      <IcButton onClick={handleClick}>Update ic-theme</IcButton>
+      <IcTheme
+        theme={theme}
+        style={{
+          border: "1px solid var(--ic-architectural-white)",
+          padding: "var(--ic-space-sm)",
+        }}
+      >
+        <IcAlert
+          heading="Set at component level"
+          variant="info"
+          theme="light"
+        />
+        <IcAlert heading="Inherits from ic-theme" variant="info" />
+      </IcTheme>
+      <IcAlert heading="Inherits from system/browser settings" variant="info" />
+    </>
+  );
+};
+
+<ComponentPreview
+  style={{
+    flexDirection: "column",
+    gap: "var(--ic-space-sm)",
+    background: "#333333",
+  }}
+  snippets={snippetsDefault}
+>
+  <DarkModeExample />
+</ComponentPreview>
+
+## Monochrome
+
+The `monochrome` prop can be set to `true` to remove the colour from components to help them display on certain backgrounds. It will display as black and white whilst adjusting to the dark mode inheritance mentioned above.
+
+<ComponentPreview style={{ gap: "var(--ic-space-sm)" }}>
+  <IcButton>Regular</IcButton>
+  <IcButton monochrome>Monochrome</IcButton>
+</ComponentPreview>