WUI logo

Theming

BasicsCustomize

By default, we use our default theme create by createTheme() function. We also also create a dark theme and a welcome theme for our products.

You can customize your theme with some options:

  • customize the theme values like colors, fonts, spacing etc.
  • customize the component styles, changing the variants, sizes etc.
  • customize the global style if you want to disable or not our reset css

Customize theme values

To create your theme, use need to add some values from object on createTheme() function.

import React from 'react'
// import the theme provider and create theme util
import { createTheme, WuiProvider } from '@welcome-ui/core'
import { Button } from '@welcome-ui/button'


// Create your theme with specific colors, spacing etc.
const theme = createTheme({
  colors: {
    primary: {
      500: '#FF0000'
    },
    secondary: {
      500: '#00FF00'
    }
  },
  spacing: {
    3xl: 50,
    4xl: 70
  },
  space: {
    lg: 24
  },
  breakpoints: {
    xl: 1024
  }
})


export default function Root() {
  return (
    // Wrap your components with <WuiProvider /> and your theme at the root of your app
    // Here we add reset styles to have consistency across different browsers (https://github.com/WTTJ/welcome-ui/tree/main/packages/Core/utils/reset.ts)
    <WuiProvider theme={theme} useReset>
      <Button variant="secondary">Welcome!</Button>
    </WuiProvider>
  )
}

Reset styles

To provide consistency across browsers we provide two options:

  1. Pass useReset in the WuiProvider to use a custom reset
  2. Don't pass useReset to just reset box-sizing e.g.
const baseBoxSizing = css`
  * {
    &,
    &::before,
    &::after {
      box-sizing: border-box;
    }
  }
`

Customizing component

An example of the theme.js file for the Tag component. You can customize the variants, sizes and shapes.

{
  default: {
    fontWeight: fontWeights.medium,
    backgroundColor: colors['light-900'],
    color: colors['nude-900'],
  },
  variants: {
    default: {
      backgroundColor: colors['nude-200'],
      borderColor: colors['nude-400'],
      ...border,
    },
    primary: { ...withoutVisibleBorder(colors['primary-500']), color: colors['dark-900'] },
    secondary: {
      backgroundColor: colors['sub-5'],
      color: colors['dark-900'],
      borderColor: colors['dark-100'],
      ...border,
    },
    success: {
      backgroundColor: colors['success-100'],
      color: colors['success-500'],
      borderColor: colors['success-200'],
      ...border,
    },
    error: {
      backgroundColor: colors['danger-100'],
      color: colors['danger-500'],
      borderColor: colors['danger-200'],
      ...border,
    },
    warning: {
      backgroundColor: colors['warning-100'],
      color: colors['warning-500'],
      borderColor: colors['warning-200'],
      ...border,
    },
    info: {
      backgroundColor: colors['info-100'],
      color: colors['info-500'],
      borderColor: colors['info-300'],
      ...border,
    },
    ...
  },
  hover: {
    default: {
      borderColor: colors['nude-600'],
    },
    primary: {},
    secondary: {
      borderColor: colors['dark-400'],
    },
    success: {
      borderColor: colors['success-500'],
    },
    error: {
      borderColor: colors['danger-500'],
    },
    warning: {
      borderColor: colors['warning-500'],
    },
    info: {
      borderColor: colors['info-500'],
    },
    ...
  },
  sizes: {
    xs: {
      padding: `${space.xxs} ${space.xs}`,
      height: sizes.xs,
      fontSize: fontSizes.xs,
      gap: space.xs,
    },
    sm: {
      padding: `${space.xs} ${space.sm}`,
      height: sizes.sm,
      fontSize: fontSizes.xs,
      gap: space.xs,
    },
    md: {
      padding: `${space.xs} ${space.sm}`,
      height: sizes.md,
      fontSize: fontSizes.sm,
      gap: space.sm,
    },
  },
  icon: {
    xs: toRem(12),
    sm: toRem(12),
    md: toRem(16),
  },
  shape: {
    xs: {
      width: sizes.xs,
      height: sizes.xs,
    },
    sm: {
      width: sizes.sm,
      height: sizes.sm,
    },
    md: {
      width: sizes.md,
      height: sizes.md,
    },
  },
}

You can check all our theme objects on each packages/component on file theme.js.

How to customize the component

The entry is always in plurial (tags, buttons, etc.)

import React from 'react'
import { createTheme, WuiProvider } from '@welcome-ui/core'
import { Button } from '@welcome-ui/button'


const yourTheme = {
  tags: {
    variants: {
      default: {
        backgroundColor: '#010101',
        color: '#FFF',
      },
      primary: {
        backgroundColor: '#FFF000',
        color: '#000',
      },
    },
    sizes: {
      sm: {
        padding: 10,
        height: 10,
        fontSize: 12,
      },
      md: {
        padding: 10,
        height: 14,
        fontSize: 14,
      },
    },
  },
}
const theme = createTheme(yourTheme)


export default function Root() {
  return (
    <WuiProvider theme={theme}>
      <Button variant="secondary">Welcome!</Button>
    </WuiProvider>
  )
}

Change fonts

If you want to change the url path for the fonts, you can change the property fontsUrl on createTheme(). By default the fonts are served from the welcome-ui.com domain. In our case at Welcome to the Jungle, we want to have the fonts served from the same domain name as our main website.

const theme = createTheme({ fontsUrl: 'https://cdn.welcometothejungle.com/fonts', ...yourTheme })

You can also overload the fonts used (for example to subset the fonts) by merging a font object with the theme. For example to replace the work-sans font with subsetted versions, host your subsetted versions somewhere then update the fontFaces object:

const fontFaces = {
  'work-sans': [
    {
      url: 'https://my_website.com/public/work-sans-variable-latin-ext',
      uniCodeRange:
        'U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF',
      weight: '400-600',
    },
    {
      url: 'https://my_website.com/public/work-sans-variable-latin',
      uniCodeRange:
        'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
      weight: '400-600',
    },
  ],
}
const theme = createTheme({ fontFaces, ...yourTheme })

All theme values

Here are all the possible values for your theme.

These will be merged with the default theme.

Theming/basicsUpgrades/v2