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>
);
}