docs(theming): note new stepped colors in ionic 8 (#3477)

Author: liamdebeasi

docs/theming/themes.md

@@ -58,10 +58,12 @@ While updating the background (`--ion-background-color`) and text (`--ion-text-c
 
 In some components we use a shade darker than the background or lighter than the text. For example, an item heading text may need to be <CodeColor color="#404040">#404040</CodeColor>, which is a few shades lighter than our default text color. Meanwhile, the loading component background is a shade darker than white, using <CodeColor color="#f2f2f2">#f2f2f2</CodeColor>. We use stepped colors in order to define these slight variations. It is important to update the stepped colors when updating the background or text color of an application.
 
-By default, the Ionic stepped colors start at the default background color value <CodeColor color="#ffffff">#ffffff</CodeColor> and mix with the text color value <CodeColor color="#000000">#000000</CodeColor> using an increasing percentage. The full list of stepped colors is shown in the generator below.
+Ionic provides separate step colors for text and background colors so they can be updated separately. This is useful for components that use both text and background stepped colors and allows us to effectively implement the [high contrast theme](./high-contrast-mode).
+
+By default, the Ionic text stepped colors start at the default text color value <CodeColor color="#000000">#000000</CodeColor> and mix with the background color value <CodeColor color="#ffffff">#ffffff</CodeColor> using an increasing percentage. The Ionic background stepped colors start at the default background color value <CodeColor color="#ffffff">#ffffff</CodeColor> and mix with the text color value <CodeColor color="#000000">#000000</CodeColor> using an increasing percentage. The full list of stepped colors is shown in the generator below.
 
 ## Stepped Color Generator
 
 Create a custom background and text color theme for your app. Update the background or text color’s hex values below, then copy and paste the generated code directly into your Ionic project.
 
-<SteppedColorGenerator />
+<SteppedColorGenerator useTextAndBackgroundStepColors={true} />

src/components/page/theming/SteppedColorGenerator/index.tsx

@@ -16,10 +16,14 @@ export default function ColorGenerator(props) {
   const [backgroundColor, setBackgroundColor] = useState('#ffffff');
   const [textColor, setTextColor] = useState('#000000');
 
-  const [steppedColors, setSteppedColors] = useState(generateSteppedColors(backgroundColor, textColor));
+  const [textSteppedColors, setTextSteppedColors] = useState(generateSteppedColors(textColor, backgroundColor));
+  const [backgroundSteppedColors, setBackgroundSteppedColors] = useState(
+    generateSteppedColors(backgroundColor, textColor)
+  );
 
   useEffect(() => {
-    setSteppedColors(generateSteppedColors(backgroundColor, textColor));
+    setTextSteppedColors(generateSteppedColors(textColor, backgroundColor));
+    setBackgroundSteppedColors(generateSteppedColors(backgroundColor, textColor));
   }, [backgroundColor, textColor]);
 
   return (
@@ -43,15 +47,53 @@ export default function ColorGenerator(props) {
           {'\t'}--ion-text-color: <CodeColor color={textColor}>{textColor}</CodeColor>;{'\n'}
           {'\t'}--ion-text-color-rgb: <CodeColor color={textColor}>{new Color(textColor).toList()}</CodeColor>;{'\n'}
           {'\n'}
-          {steppedColors.map((color, i) => (
-            <>
-              {'\t'}--ion-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
-            </>
-          ))}
+          {/*
+            Ionic v8+ uses separate step colors for text and background.
+            We use a single component here for all versions of the docs, so newer
+            versions of the docs opt-in to showing separate step colors
+            using the useTextAndBackgroundStepColors property.
+          */}
+          {props.useTextAndBackgroundStepColors &&
+            renderSeparateTextAndBackgroundColors(textSteppedColors, backgroundSteppedColors)}
+          {!props.useTextAndBackgroundStepColors && renderCombinedColors(backgroundSteppedColors)}
           {'}'}
           {'\n'}
         </code>
       </pre>
     </div>
   );
 }
+
+/**
+ * Render `--ion-text-color-step-*` and `--ion-background-color-step-*` tokens.
+ * Use this for Ionic v8+ documentation.
+ */
+const renderSeparateTextAndBackgroundColors = (textSteppedColors: string[], backgroundSteppedColors: string[]) => {
+  return [
+    textSteppedColors.map((color, i) => (
+      <>
+        {'\t'}--ion-text-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
+      </>
+    )),
+    '\n',
+    backgroundSteppedColors.map((color, i) => (
+      <>
+        {'\t'}--ion-background-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
+      </>
+    )),
+  ];
+};
+
+/**
+ * Render `--ion-color-step-*` tokens.
+ * Use this for Ionic v4-v7 documentation.
+ */
+const renderCombinedColors = (steppedColors: string[]) => {
+  return [
+    steppedColors.map((color, i) => (
+      <>
+        {'\t'}--ion-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
+      </>
+    )),
+  ];
+};