Migrating

CSS Modules/CSS Variables

With Element v4 we got away from styled-components as a styling solution for the Element web package. We replaced it with vanila css features (CSS Modules).

See Building for information on installation.

Tokens

Tokens are generated using a build tool now - Style Dictionary - and have been affected a little in terms of types, but are mostly unaffected in structure. This applies to both Element for web and native usage.

Web

If using styled-components or similar, it is still possible to use the theme object as in previous version, albeit the import would now come from @ovotech/element itself rather than a separate core package. e.g.


                                                        
                                                        
                                                            import { theme } from '@ovotech/element';
                                                        
                                                            

However, as now make use of CSS Modules, the tokens are now available as CSS variables (which are required in order to theme our components - see below and in Building), so you are able to make use of these instead of (or alongside) Javascript tokens. Our token structure follows a similar logic to the theme object, where instead of object notation (e.g. theme.core.color...) tokens are kebab-cased with an el namespace (e.g. --el-core-color...).


                                                        
                                                        
                                                            import '@ovotech/element/theme.css';
                                                        
                                                            

Note: if you're making use of the createTheme generator utility from Element with overrides, this has been "flattened" as a result of our theme being generated at build-time rather than runtime. This means that overrides of tokens don't cascade through the layers of the system, and so more specific overrides may need adding in order to affect components which would have previously been automatically affected by lower-level tokens. This is because aliases are no longer available during overriding of tokens, so replacements are only made on a 1:1 basis with this function.

Native

At this time, Element native still uses styled-components internally for styling, and so the ThemeProvider is still required with the theme supplied as before.

As with the web package, the theme is now available from the package itself (note the name), e.g.


                                                        
                                                        
                                                            import { themeNative } from '@ovotech/element-native';
                                                        
                                                            

Some token types have been affected in order to cater for a Javascript-first approach rather than compatibility with styled-components. The effect of these changes is that some tokens that were previously geared more towards CSS-in-JS frameworks are now native-first values, and so certain transformations on these tokens will need to be considered conversely.

For example, below you can see that the font size token has changed from a pixel value in a string to a number and how handling it is affected:


                                                        
                                                        
                                                            // -- PREVIOUSLY --
                                                        
                                                        /* native */
                                                        const styles = Stylesheet.create({
                                                          paragraph: {
                                                            fontSize: parseFloat(theme.core.fontSize.body.small),
                                                          }
                                                        });
                                                        
                                                        /* styled-components */
                                                        const StyledP = styled.Text(
                                                          ({ theme }) => `
                                                            font-size: ${ theme.core.fontSize.body.small };
                                                        `);
                                                        
                                                        // -- NOW --
                                                        
                                                        /* native */
                                                        const styles = Stylesheet.create({
                                                          paragraph: {
                                                            fontSize: theme.core.fontSize.body.small,
                                                          }
                                                        });
                                                        
                                                        /* styled-components */
                                                        import { numToPx } from '@ovotech/element-native';
                                                        
                                                        const StyledP = styled.Text(
                                                          ({ theme }) => `
                                                            font-size: ${ numToPx(theme.core.fontSize.body.small) };
                                                        `);
                                                        
                                                            

The affected token families are:

Token family

Change

core.borderWidth

String with 'px' -> Number

core.fontSize

String with 'px' -> Number

core.lineHeight

String with 'px' -> Number

core.radius

String with 'px' -> Number

core.space

String with 'px' -> Number

core.transition

String with 'ms ease' -> Number

New components

  • Radio Card
  • Toasts
  • Product Carousel

Component updates

Action

  • rightSlot prop removed as you can now set both iconRight and iconLeft to any of the IconName set from Element.
  • fullWidth is now a boolean rather than a union for simplicity, defaulting to false.

 

CTAButton and CTALink

  • fullWidth is now a boolean rather than a union for simplicity, defaulting to false.

 

Icon

  • Filled icons added for use in the app nav bar - help-filled, payment-card-filled, star-filled.
  • Caret icon names have been updated, e.g. from caret-up to caret-arrow-up etc.