Dependencies Update
With Element v3 we have introduced a core module to provide a shared theme between element (web) and element-native, resulting in an added dependency - see Building for information on installation.
Brand Changes
- The core theme has changed entirely in structure, and the colour pallete has been expanded as you can see in our foundations page on colour.
- Text components (P, Heading1/2/3/4) now have no in-built margins, to allow for greater control over them in layouts, but meaning you will need to add Margin and/or Stacks around them to adjust for spacing.
- Spacings were changed for multiple components, with the array expanded to include 0 and values up to 15 for greater flexibility and application.
Tokens
Check out Tokens overview page to find out more about the new theme structure.
Tokens were heavily re-designed. Now we have 3 main token groups core, semantic, and component.
- core consists of all basic tokens such as spacing, text sizes/styles, media quaries, and an extended colour palette
- semantic contains tokens imbued with meaning or indicative of state. These tokens are mainly colour aliases, mapping specific colours to elements and states for use in components. They were added for consistency and flexibility of component design. Unless you need some specific brand colour please use semantic colours wherever possible.
- component token group contains tokens specific for certain componenta. As with semantic tokens, it aliases core tokens, but is grouped by component rather than more abstract elements or meanings. Element v3 aims to reduce the reliance on extended use of component tokens unless overriding or re-using them is particularly desirable.
Token comparison table
Core tokens
|
V2 |
V3 |
|
theme.mediaQueries |
theme.core.mediaQuery |
|
theme.radii |
theme.core.radius |
|
theme.fontWeights |
theme.core.fontWeight |
|
theme.fontSizes |
No similar token, please use theme.core.fontSize |
|
theme.fonts |
theme.core.fontFamily |
|
theme.responsiveFontSizes |
theme.core.fontSize |
|
theme.responsiveLineHeights |
theme.core.lineHeight |
|
theme.colors |
theme.semantic |
|
theme.borderWidths |
theme.core.borderWidth |
|
theme.breakpoints |
theme.core.breakpoint |
|
theme.lineHeights |
No similar token, please use theme.core.lineHeight |
|
theme.space |
theme.core.space |
|
theme.transitions |
theme.core.transition |
|
theme.shadows |
Not implemented |
Check out Tokens overview for building with Element for more information.
Semantic tokens
|
V2 |
V3 |
|
theme.colors.brand.electricity.base |
theme.semantic.data.electricity[1] |
|
theme.colors.brand.electricity.dark |
theme.semantic.data.electricity[3] |
|
|
theme.semantic.data.electricity[2] |
|
|
theme.semantic.data.electricity[4] |
|
theme.colors.brand.gas.base |
theme.semantic.data.gas[1] |
|
theme.colors.gas.dark |
theme.semantic.data.gas[3] |
|
|
theme.semantic.data.electricity[2] |
|
|
theme.semantic.data.electricity[4] |
|
Combined data (elec & gas) Did not previously exist |
theme.semantic.data.branded[1] |
|
|
theme.semantic.data.branded[2] |
|
|
theme.semantic.data.branded[3] |
|
|
theme.semantic.data.branded[4] |
Component tokens
|
V2 |
V3 |
|
theme.field |
- |
|
theme.input |
- |
|
theme.card |
- |
|
theme.checkbox |
- |
|
theme.errorNotification |
- |
|
theme.modal |
- |
|
theme.text |
theme.component.lead, theme.component.body, theme.component.small, theme.component.label |
|
theme.heading |
theme.component.heading1, theme.component.heading2, theme.component.heading3, theme.component.heading4 |
|
theme.list |
- |
|
theme.textLink |
- |
|
theme.radio |
- |
|
theme.focusRing |
- |
|
theme.grid |
- |
|
theme.accordion |
- |
|
theme.badge |
theme.component.badge |
Deprecated components
- SummaryList (see DescriptionList)
- Dd (see DescriptionList)
- Dt (see DescriptionList)
- TelField (see PhoneField)
Major component changes
Instead, use an appropriate fontFamily from theme.core.fontFamily.
e.g. if you need bold text you should add font-family: ${theme.core.fontFamily.bodyBold.native}. If your font looks weird or different from other Element compoenents please check out its custom styles and remove font-weight if this is the cause.
Accordion
- headingComponent prop is Heading4 component instead of Heading3 by default
Badge
- new customVariant prop added
customVariant?: {
backgroundColor: string;
foregroundColor: string;
};
it allows you to overwrite default theme background and foreground colors
- variant prop now have more options (and Badges have new variants - core and semantic), as well as being invertible! For this, just add inverted={true}
variant: 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'success' | 'warning' | 'error' | 'info'
CTAButton
- missionPrimary and missionSecondary variants have been removed
CTALink
- missionPrimary and missionSecondary variants have been removed
ErrorSummaryNotification
- title is required prop now
Headings (1/2/3/4)
- All Heading components now have no margins, you should add it youself if you need. You can use Margin or Stack component for it.
Notification
- title prop is required now
- dismissable prop renamed to dismissible (typo fix)
Icon (native only)
- default icon color is semantic.message.base now
SelectField (new for native!)
- New SelectField component add. Check out docs on the SelectField page