Migrating from v2 to v3

In an attempt to make our brand more consistent and easier to design for, in 2021 we began the process of simplifying Palette to reduce the amount of visual information in the system. Less Typography choices, less spacing options, less colors. While this has largely gone smoothly, there are some things to be aware of.

For reference, check out the difference between our v2 and v3 themes below:

v2: palette-tokens/v2

v3: palette-tokens/v3

How to Migrate

While most migration work will be happening in Force, we use Palette all across Artsy, including a lighter React Native version in Eigen. Each app will likely have its own patterns for toggling between v2 and v3, but in short migrating is as simple as importing the <ThemeProviderV3> context and placing it at the top of the component tree that you'd like to migrate:

import { ThemeProviderV3 } from "@artsy/palette"

const MyApp = () => {
  return (
    <ThemeProviderV3>
      <App />
    </ThemeProviderV3>
  )
}

Alternatively, you can set the theme version using the main <Theme> component:

import { Theme } from "@artsy/palette"

const MyApp = () => {
  return (
    <Theme theme="v3">
      <App />
    </Theme>
  )
}

This is useful if you're programmatically setting things, as we do in Force via our route config.

Once the component tree is wrapped in the correct provider you should be able to access our v3 theme.

Using the useThemeConfig hook

The useThemeConfig hook can be used within components that are shared between v2 and v3 apps, and thus can't be converted wholesale to v3. (A good example of this is the Artwork Filter, which is a complex component used in a couple different places.)

import { useThemeConfig, Box, Text, TextVariant } from "@artsy/palette"

const MyComponent = props => {
  const tokens = useThemeConfig({
    v2: {
      px: 5,
      variant: "title" as TextVariant,
    },
    v3: {
      px: 2,
      variant: "lg" as TextVariant,
    },
  })

  return (
    <Box px={tokens.px}>
      <Text variant={tokens.variant}>Hi</Text>
    </Box>
  )
}

What we're doing in the above is defining an object with two keys -- v2 and v3 -- and the useThemeConfig hook will then match against the keys depending on which theme context is currently being used and return the correct values. So you can see that

<Box px={tokens.px}>
  <Text variant={tokens.variant}>Hi</Text>
</Box>

Will return dynamic values for tokens.px -- either px={5} if v2, or px={2} if v3.

(See here for a real-world example.)

Typography

We've simplified our typography choices down to six choices, as can be seen here.

Variants are now generic size values (sm, md, lg, and so on) rather than context-specific names (title, subTitle, etc.)

Palette v3
Palette v2
xxl
N/A
xl
largeTitle
lg
title
m
N/A
sm
text
xs
caption
N/A
small

If migrating from pre-v1 <Sans> or <Serif> components, note that we no longer use serif fonts and areas where those components are used should be replaced with <Text>.

Some migration examples:

We no longer use Serif
We no longer use context variants
<BorderBox display="block">
  <Serif size={4}>We no longer use Serif</Serif>
  <Text variant="subTitle">We no longer use context variants</Text>
</BorderBox>

Do this instead:

Now we use the text component across the board
<BorderBox>
  <Text variant="lg">Now we use the text component across the board</Text>
</BorderBox>

Spacing Scale

See our docs on Spacing for the full list, but in particular the often-used 3 = 30px is no longer available.

If migrating a page, v2 values that no longer exist in v3 will collapse to zero.

Colors

See our docs on Colors for the full list.

On this page
How to Migrate
Using the useThemeConfig hook
Typography
Spacing Scale
Colors