Building

Installation

Start by making sure you have an npm token from the @ovotech npm org.


                                                        
                                                        
                                                            yarn add @ovotech/element
                                                        or
                                                        yarn add @ovotech/element-native
                                                        
                                                            

Or if you prefer:


                                                        
                                                        
                                                            npm install --save @ovotech/element
                                                        or
                                                        npm install --save @ovotech/element-native
                                                        
                                                            

Element has been built with an opinionated stack of react and styled-component. This means you'll need to make sure you’ve installed the following peer dependencies:

  • react
  • styled-components (react-native)
  • react-native (react-native)
  • react-native-svg (react-native)
  • react-native-reanimated (react-native)
  • react-native-gesture-handler (react-native)
  • react-native-safe-area-context (react-native)
  • @react-native-masked-view/masked-view (react-native)

CSS reset

When using them on the web, the design system components rely on global styles to provide a CSS reset.

We export one of these that uses sensible defaults, and most crucially, responsive font sizing. It can be imported as below:


                                                        
                                                        
                                                            // Webpack will need a css-loader to import this.
                                                        import '@ovotech/element/reset.css';
                                                        
                                                            

Using the fonts

Download the font files here: 2023.04.03-OVOCircular.zip (opens in new window)

It's best to use the fonts locally to your project. Use @font-face declarations to load these and set up the family in line with the typography tokens in Element.

For example:


                                                        
                                                        
                                                            @font-face {
                                                          font-family: 'OVOCircular';
                                                          src: url('./path/to/OVOCircularWeb-Book.woff2') format('woff2');
                                                          font-weight: 400;
                                                          font-style: normal;
                                                          font-display: swap;
                                                        }
                                                        
                                                        @font-face {
                                                          font-family: 'OVOCircular';
                                                          src: url('./path/to/OVOCircularWeb-Bold.woff2') format('woff2');
                                                          font-weight: 700;
                                                          font-style: normal;
                                                          font-display: swap;
                                                        }
                                                        
                                                        @font-face {
                                                          font-family: 'OVOCircular';
                                                          src: url('./path/to/OVOCircularWeb-Black.woff2') format('woff2');
                                                          font-weight: 900;
                                                          font-style: normal;
                                                          font-display: swap;
                                                        }
                                                        
                                                            

Setting the theme

Element native uses styled-components, which need a theme - you can import from @ovotech/element-native. Use styled-component's <ThemeProvider> at the root of the app.

Element uses CSS Modules under the hood, which need a theme.css from @ovotech/element


                                                                                                                                            
                                                                                                                                            
                                                                                                                                                import '@ovotech/element/theme.css'
                                                                                                                                            
                                                                                                                                            ReactDOM.createRoot(document.getElementById('root')).render(<MyApp />)
                                                                                                                                            
                                                                                                                                                

                                                                                                                                            
                                                                                                                                            
                                                                                                                                                import { ThemeProvider } from 'styled-components/native';
                                                                                                                                            import { themeNative } from '@ovotech/element-native';
                                                                                                                                            
                                                                                                                                            <ThemeProvider theme={themeNative}>
                                                                                                                                              <MyApp />
                                                                                                                                            </ThemeProvider>;
                                                                                                                                            
                                                                                                                                                

Using the components

Element exports all components as named exports as documented throughout, for example:


                                                                                                                                            
                                                                                                                                            
                                                                                                                                                import { PrimaryCTAButton } from '@ovotech/element';
                                                                                                                                            
                                                                                                                                            const Example = () => (
                                                                                                                                              <PrimaryCTAButton onClick={() => alert('Yippee!')}>
                                                                                                                                                I ❤ Design Systems
                                                                                                                                              </PrimaryCTAButton>
                                                                                                                                            );
                                                                                                                                            
                                                                                                                                                

                                                                                                                                            
                                                                                                                                            
                                                                                                                                                import { PrimaryCTAButton } from '@ovotech/element-native';
                                                                                                                                            
                                                                                                                                            const Example = () => (
                                                                                                                                              <PrimaryCTAButton onPress={() => alert('Yippee!')}>
                                                                                                                                                I ❤ Design Systems
                                                                                                                                              </PrimaryCTAButton>
                                                                                                                                            )
                                                                                                                                            
                                                                                                                                                

Using the theme object

In an ideal scenario user interfaces (UIs) would be built entirely using Element components. However, considering the components and layout utilities provided by the system are far from a complete set, there will be times when you will need to build your UI using custom styling. In these situations, we'd recommend leveraging the theme object provided by Element in order to maintain consistency with our components, and by extension enabling themability in future.

The theme comprises of core, semantic, and component tokens, with core containing unique values that are generally aliased in the two other sub-objects. For this reason, unless modifying the underlying theme and visuals, it is recommended to always use semantic and component tokens wherever possible when working with the Element theme.


                                                                                                                                            
                                                                                                                                            
                                                                                                                                                import '@ovotech/element/theme.css'
                                                                                                                                            
                                                                                                                                            export default function Theme() {
                                                                                                                                             return (
                                                                                                                                              <div>
                                                                                                                                               <p>Some text</p>
                                                                                                                                              </div>
                                                                                                                                             );
                                                                                                                                            }
                                                                                                                                            
                                                                                                                                                

                                                                                                                                            
                                                                                                                                            
                                                                                                                                                import { createTheme } from '@ovotech/element-native';
                                                                                                                                            
                                                                                                                                            const theme = createTheme({});
                                                                                                                                            
                                                                                                                                            export default function Theme() {
                                                                                                                                             return (
                                                                                                                                              <View>
                                                                                                                                               {theme}
                                                                                                                                              </View>
                                                                                                                                             );
                                                                                                                                            }