Skip to content

Commit 574acc7

Browse files
authored
docs(theming): note new stepped colors in ionic 8 (#3477)
1 parent acadcf5 commit 574acc7

File tree

2 files changed

+53
-9
lines changed

2 files changed

+53
-9
lines changed

docs/theming/themes.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,12 @@ While updating the background (`--ion-background-color`) and text (`--ion-text-c
5858

5959
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.
6060

61-
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.
61+
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).
62+
63+
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.
6264

6365
## Stepped Color Generator
6466

6567
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.
6668

67-
<SteppedColorGenerator />
69+
<SteppedColorGenerator useTextAndBackgroundStepColors={true} />

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

Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,14 @@ export default function ColorGenerator(props) {
1616
const [backgroundColor, setBackgroundColor] = useState('#ffffff');
1717
const [textColor, setTextColor] = useState('#000000');
1818

19-
const [steppedColors, setSteppedColors] = useState(generateSteppedColors(backgroundColor, textColor));
19+
const [textSteppedColors, setTextSteppedColors] = useState(generateSteppedColors(textColor, backgroundColor));
20+
const [backgroundSteppedColors, setBackgroundSteppedColors] = useState(
21+
generateSteppedColors(backgroundColor, textColor)
22+
);
2023

2124
useEffect(() => {
22-
setSteppedColors(generateSteppedColors(backgroundColor, textColor));
25+
setTextSteppedColors(generateSteppedColors(textColor, backgroundColor));
26+
setBackgroundSteppedColors(generateSteppedColors(backgroundColor, textColor));
2327
}, [backgroundColor, textColor]);
2428

2529
return (
@@ -43,15 +47,53 @@ export default function ColorGenerator(props) {
4347
{'\t'}--ion-text-color: <CodeColor color={textColor}>{textColor}</CodeColor>;{'\n'}
4448
{'\t'}--ion-text-color-rgb: <CodeColor color={textColor}>{new Color(textColor).toList()}</CodeColor>;{'\n'}
4549
{'\n'}
46-
{steppedColors.map((color, i) => (
47-
<>
48-
{'\t'}--ion-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
49-
</>
50-
))}
50+
{/*
51+
Ionic v8+ uses separate step colors for text and background.
52+
We use a single component here for all versions of the docs, so newer
53+
versions of the docs opt-in to showing separate step colors
54+
using the useTextAndBackgroundStepColors property.
55+
*/}
56+
{props.useTextAndBackgroundStepColors &&
57+
renderSeparateTextAndBackgroundColors(textSteppedColors, backgroundSteppedColors)}
58+
{!props.useTextAndBackgroundStepColors && renderCombinedColors(backgroundSteppedColors)}
5159
{'}'}
5260
{'\n'}
5361
</code>
5462
</pre>
5563
</div>
5664
);
5765
}
66+
67+
/**
68+
* Render `--ion-text-color-step-*` and `--ion-background-color-step-*` tokens.
69+
* Use this for Ionic v8+ documentation.
70+
*/
71+
const renderSeparateTextAndBackgroundColors = (textSteppedColors: string[], backgroundSteppedColors: string[]) => {
72+
return [
73+
textSteppedColors.map((color, i) => (
74+
<>
75+
{'\t'}--ion-text-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
76+
</>
77+
)),
78+
'\n',
79+
backgroundSteppedColors.map((color, i) => (
80+
<>
81+
{'\t'}--ion-background-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
82+
</>
83+
)),
84+
];
85+
};
86+
87+
/**
88+
* Render `--ion-color-step-*` tokens.
89+
* Use this for Ionic v4-v7 documentation.
90+
*/
91+
const renderCombinedColors = (steppedColors: string[]) => {
92+
return [
93+
steppedColors.map((color, i) => (
94+
<>
95+
{'\t'}--ion-color-step-{(i + 1) * 50}: <CodeColor color={color}>{color}</CodeColor>;{'\n'}
96+
</>
97+
)),
98+
];
99+
};

0 commit comments

Comments
 (0)