With the release of Stacks v2, we've made some breaking changes to the library. The purpose of this guide is to help you prepare your code be compatible with the changes in Stacks v2.
- Upgrading dependencies
- Using Stacks v2 colors
- Deprecation of Less color variables
- Using legacy colors
- Custom theme generation
- Deprecation of
.s-btn__primary
While updating to Stacks v2, you must also update other Stacks dependencies you may have included in your project. Below is a table of Stacks dependencies and the corresponding minimum versions compatible with Stacks v2.
| Dependency | Minimum version |
|---|---|
| stacks | 2.0.0 |
| stacks-editor | 0.9.0 |
| stacks-icons | 6.0.0 |
In Stacks v2, all components and atomic classes have been updated to use new color sets optimized for accessibility. In the process, the previous colors have been deprecated and the number of color stops has been reduced. This section will help you migrate to use the new colors.
Stacks v2 reduces and unifies the number of color stops for each set of colors. Below, you'll find a series of tables that map the old color stops to the new color stops. Update your color references by mapping them to the new stop values.
Note The
powdercolor set has been deprecated and is not included in the updated colors. See the deprecation of powder color set section for more information.
| Stacks v1 | Stacks v2 |
|---|---|
| 025*† | 100 |
| 050, 075* | 200 |
| 100, 150*, 200 | 300 |
| 300, 350*, 400, 500 | 400 |
| 600, 700 | 500 |
| 800, 900 | 600 |
- *only applies to theme colors
- †only applies to green and red
| Stacks v1 | Stacks v2 |
|---|---|
| N/A | 050 |
| 025 | 100 |
| 050 | 150 |
| 075 | 200 |
| 100 | 225 |
| 150 | 250 |
| 200 | 300 |
| 300, 350 | 350 |
| 400, 500 | 400 |
| 600, 700 | 500 |
| 750, 800, 900 | 600 |
| Stacks v1 | Stacks v2 |
|---|---|
| [color]-lighter | 100 |
| N/A | 200 |
| [color] | 300 |
| [color]-darker | 400 |
Below is just one example of a regular expression that can help you find and replace color references. Swap the color names and stop suffixes to update different remappings.
(theme-primary|theme-secondary|orange|blue|green|red|yellow)-(100|150|200)$1-300Stacks v2 no longer includes the powder color set. We recommend you replace all references to powder with blue. If you need to continuing referencing powder, you can use the -legacy suffix until the library permanently removes legacy colors. See the using legacy colors section for more information.
We've removed the -color suffix from the default theme variable custom properties. Previously, you could reference the 400 stop of theme colors with theme-(primary|secondary)-color. Now, you should reference the 400 stop of theme colors with theme-(primary|secondary). Below is a table showing the old and new custom property names, though this pattern also applies to color, background, and border utility classes.
| Variable | Stacks v1 | Stacks v2 |
|---|---|---|
| Primary | --theme-primary-color |
--theme-primary |
| Secondary | --theme-secondary-color |
--theme-secondary |
Stacks v2 deprecates the usage of Less variables outside of Stacks. Although there's no way to make these variables truly private, we now discourage referencing them directly unless otherwise stated in our official documentation and advise that changes to psuedo-private variables may break your code if you reference them.
Stacks v2 includes new CSS custom properties to replace a handful of commonly referenced Less variables. Update your Less variable references to the new CSS custom properties where possible.
| Stacks v1 | Stacks v2 |
|---|---|
@black |
var(--_black-static) |
@white |
var(--_white-static) |
In rare circumstances, you may need to reference a color value directly in order to operate on it and generate a new color or extract some value. In these cases, you can reference colors within a given color set. We advise against this and don't guarantee that these variables will remain stable. Nevertheless, here's how you would reference a Less color variable in Stacks v2.
| Stacks v1 | Stacks v2 |
|---|---|
@black-350 |
.set-black()[350] |
Legacy colors are deprecated and will be removed January 2024. We strongly recommend you migrate to the new colors as soon as possible. With that said, you may have a need to reference legacy colors in the short term. This section gives an overview of how to reference legacy colors.
Stacks v2 replaces v1 colors, but you can still reference the v1 colors by adding the -legacy label to your color references. The -legacy suffix will generally come after the color name and before a color stop suffix (if it exists). This applies to atomic color classes (such as .bc-*, .bg-*, and .fc-*), CSS custom properties, and Less variables. See the legacy color documentation for more information.
| Stacks v1 | Stacks v2 |
|---|---|
.bc-red-800 |
.bc-red-legacy-800 |
--theme-secondary-400 |
--theme-secondary-legacy-400 |
--theme-base-primary-color-h |
--theme-base-primary-color-legacy-h |
.fc-light |
.fc-light-legacy |
.fc-white__forced |
.fc-white-legacy__forced |
@black |
@black-legacy |
Below you'll find a set of regular expressions to help you find and replace existing color references with corresponding legacy reference.
Note Even with these regular expressions, you'll may still need to find and replace some color references manually. For example, this regex will not alter references to
blackthat don't contain a numeric stop suffix.
(theme-primary|theme-secondary|black|orange|blue|green|red|yellow|powder|fog)-(025|050|075|100|150|200|300|350|400|500|600|700|750|800|900)// Replace
$1-legacy-$2(bc|fc|bg)-(lightest|lighter|light|medium|darker|dark)$1-$2-legacyStacks v2 has deprecated the Less function .generate-calculated-themed-variables() in favor of the newly added .create-custom-theme-hsl-variables() function. This new function works differently behind the scenes, but it accepts the same arguments and generates the same CSS custom properties as its deprecated equivelent. See the theming documentation.
To update to the new custom theme variable generation function, simply search for .generate-calculated-themed-variables in your codebase and replace it with .create-custom-theme-hsl-variables.
Stacks v2 deprecates the .s-btn__primary variant. To retain a similar style, we recommend replacing all instances of .s-btn__primary with .s-btn__filled. See the button documentation for more information.