Color and Typography Updates in v9

Everything you need to know about the latest style updates in Base Web
Graham Murdoch - 9 September 2019
updated base web components with black highlights
Base Web has an updated look

The Base design system has undergone a small makeover. baseui v9 updates the component library to meet these latest specs. This includes black as the new primary color, a more accessible color palette, and an update to the typography sizing ramp.

Migration Guide

After bumping to v9, your app will probably look a little different. Don't panic! If you address each of the points below your app will look right in no time!

  • Customize your theme if the color changes in v9 are not to your liking. Read more 📖
  • Update usage of typography theme values (font100 for example) to the new scale. Read more 📖
  • Update usage of typography components (Paragraph1, H1) to the new scale. Read more 📖

Be sure to check out our codemod for automatically migrating your codebase to v9! Or, read on for more detail on all of the changes included in this new major.

Black is the New Blue

We have changed the primary color in our default light theme from blue to black. Blue still lives on in our components as the new accent color but has a greatly reduced role. Also, note that the dark theme now uses white as the default color for primary.

These changes are most noticeable in our buttons and the highlights on various inputs (controls). So what should you do if you aren't ready for full on black & white?

Default Branding

If you use our default colors and you want to use blue as the primary color still, you can simply set primary back to blue in your theme primitives object.

// myTheme.js
import {createTheme, lightThemePrimitives} from 'baseui/themes';
import {colors} from 'baseui/tokens';
const myThemePrimitives = {
...lightThemePrimitives,
primary: colors.blue400,
primary50: colors.blue50,
primary100: colors.blue100,
primary200: colors.blue200,
primary300: colors.blue300,
primary400: colors.blue400,
primary500: colors.blue500,
primary600: colors.blue600,
primary700: colors.blue700,
};
const myTheme = createTheme(myThemePrimitives);
export default myTheme;

Custom branding

If you use custom colors in your theme, v9 will change how your colors are applied to components. In a few cases primary has been replaced by the new accent color so you will want to assign accent to something from your brand in your theme primitives object. If you do not need the additional theme variable, the easiest thing to do will be to set accent to the same color as primary.

// myTheme.js
import {createTheme} from 'baseui/themes';
const myTokens = {
// define various brand colors here...
colors: {
neonPink400: '#FF69B4',
},
};
const myThemePrimitives = {
// define all the various primitives for my theme...
// adding in custom "accent" primitives
accent: myTokens.colors.neonPink400,
accent50: myTokens.colors.neonPink50,
accent100: myTokens.colors.neonPink100,
accent200: myTokens.colors.neonPink200,
accent300: myTokens.colors.neonPink300,
accent400: myTokens.colors.neonPink400,
accent500: myTokens.colors.neonPink500,
accent600: myTokens.colors.neonPink600,
accent700: myTokens.colors.neonPink700,
};
const myTheme = createTheme(myThemePrimitives);
export default myTheme;

For more on how our theme system works, including how to override default theme values, check out this page.

In summary, use the primitives object to assign semantic meaning to your project's colors. If you need more fine grained control over how colors are used you may need to do some reassignments within createTheme's overrides parameter.

Using overrides

// myTheme.js
import {createTheme} from 'baseui/themes';
const myTokens = {
// define various brand colors here...
};
const myThemePrimitives = {
// define all the various primitives for my theme...
};
const myThemeOverrides = {
// override baseui default theme assignments...
colors: {
borderFocus: myThemePrimitives.accent,
},
};
const myTheme = createTheme(myThemePrimitives, myThemeOverrides);
export default myTheme;
We do a deep merge of your overrides with our default values.

The following sections detail theme variables you can override to adjust the look of your app after bumping to v9.

Button Group

The ButtonGroup component has been updated to use buttons with kind={KIND.secondary} rather than the previous tertiary. If you still want to use tertiary you can now use kind as a top-level prop on ButtonGroup:

<ButtonGroup kind={KIND.tertiary} />

This will set the children buttons to whatever kind you have passed to ButtonGroup. You can then theme these various button group kinds with a set of new theme variables:

buttonPrimarySelectedText
buttonPrimarySelectedFill
buttonSecondaySelectedText // default selected kind
buttonSecondaySelectedFill // default selected kind
buttonTertiarySelectedText
buttonTertiarySelectedFill
buttonMinimalSelectedText
buttonMinimalSelectedFill

A note on the minimal Button

We are deprecating the minimal button. tertiary now serves the same purpose and so the two are redundant. We haven't removed the option yet to avoid an additional breaking change, so you can still set your buttons to kind={KIND.minimal} and use theme variables to target them. We encourage you to use tertiary going forward instead, however, as the minimal button may be removed in a future major.

Datepicker

The Datepicker component has a new set of theme variables that allow for much more fine-grained customization. Previously it was a little difficult to theme the Datepicker and generally required overrides. Note that the old datepicker theme variables are deprecated- they remain in the theme object for backward compatibility.

calendarBackground
calendarForeground
calendarForegroundDisabled
calendarHeaderBackground
calendarHeaderForeground
calendarHeaderBackgroundActive
calendarHeaderForegroundDisabled
calendarDayBackgroundPseudoSelected
calendarDayForegroundPseudoSelected
calendarDayBackgroundPseudoSelectedHighlighted
calendarDayForegroundPseudoSelectedHighlighted
calendarDayBackgroundSelected
calendarDayForegroundSelected
calendarDayBackgroundSelectedHighlighted
calendarDayForegroundSelectedHighlighted

The primary color values used for Link in light and dark themes have been updated to suit the new black/white aesthetic. You may want to update these theme variables to suit your own primary colors.

linkText
linkVisited
linkHover
linkActive

Progress Steps

Updating the ProgressSteps component to black required some new theme variables. Feel free to use them for your own customizations:

progressStepsCompletedText
progressStepsCompletedFill
progressStepsActiveText
progressStepsActiveFill
progressStepsIconActiveFill

Tag and Toast and Notification Kinds

The Tag, Toast, and Notification components have been updated to account for the move to black. Here is what you need to know:

The Tag component supports a new value, accent, for the kind prop, which is blue by default. You can use the following set of new theme variables to customize it:

tagAccentSolidBackground
tagAccentSolidHover
tagAccentSolidActive
tagAccentSolidDisabled
tagAccentSolidFont
tagAccentSolidFontHover
tagAccentLightBackground
tagAccentLightHover
tagAccentLightActive
tagAccentLightDisabled
tagAccentLightFont
tagAccentLightFontHover
tagAccentOutlinedBackground
tagAccentOutlinedHover
tagAccentOutlinedActive
tagAccentOutlinedDisabled
tagAccentOutlinedFont
tagAccentOutlinedFontHover
tagAccentFontDisabled

The Toast and Notification components also have a kind prop, which is info by default. The style for info can now be set with a few new theme variables:

toastInfoBackground
notificationInfoBackground
notificationInfoText // used for Toast and Notification text 🤔

Breakpoints

Unrelated to color but related to theming: we have updated the default breakpoints in the theme object. The largest breakpoint is now 1136px. You can set it back to 1280px in your theme.

const theme = {
breakpoints: {
large: 1280,
},
};

Base Color Palette

The base color primitives for both the default light and dark theme have been adjusted. These have been changed to improve the contrast ratios across our color palette.

New Black

Name
New
primary50
#F6F6F6
primary100
#EEEEEE
primary200
#E2E2E2
primary300
#CBCBCB
primary400
#AFAFAF
primary500
#757575
primary600
#545454
primary700
#333333

Blue Changes

Name
Old
New
accent50
#EDF3FE
#EEF3FE
accent100
#D2E0FC
#D4E2FC
accent200
#9CBCF8
#A0BFF9
accent300
#548BF4
#5B91F4
accent400
#276EF1
#276EF1
accent500
#174EB6
#1E54B7
accent600
#123D90
#174291
accent700
#0C2960
#102C60

Red Changes

Name
Old
New
negative50
#FDF0EF
#FDF0EF
negative100
#FADBD7
#FADBD7
negative200
#F4AFA7
#F4AFA7
negative300
#EB7567
#EB7567
negative400
#E54937
#D44333
negative500
#AE372A
#AE372A
negative600
#892C21
#892C21
negative700
#5C1D16
#5C1D16

Green Changes

Name
Old
New
positive50
#EBF8F2
#F0F9F4
positive100
#CDEDDE
#DAF0E3
positive200
#88D3B0
#AEDDC2
positive300
#43B982
#73C496
positive400
#07A35A
#3AA76D
positive500
#057C44
#368759
positive600
#046236
#2B6B46
positive700
#034124
#1C472F

Orange Changes

Name
Old
New
warning50
#FEF3EC
#FEF3EF
warning100
#FBE2CF
#FBE2D6
warning200
#F6BA8B
#F7BFA5
warning300
#F19248
#F19164
warning400
#ED6F0E
#ED6E33
warning500
#B4540B
#B45427
warning600
#8E4308
#8E421F
warning700
#5F2C06
#5F2C14

The changes in most of the colors are quite subtle, but the gray (mono) palette has shifted more noticeably. Here are the updated grayscale values:

Gray Changes for Light Theme

Name
Old
New
mono100
#FFFFFF
#FFFFFF
mono200
#F7F7F7
#F6F6F6
mono300
#F0F0F0
#EEEEEE
mono400
#E5E5E5
#E2E2E2
mono500
#CCCCCC
#CBCBCB
mono600
#B3B3B3
#AFAFAF
mono700
#999999
#757575
mono800
#666666
#545454
mono900
#333333
#333333
mono1000
#000000
#000000

Gray Changes for Dark Theme

Name
Old
New
mono100
#CCCCCC
#CBCBCB
mono200
#999999
#AFAFAF
mono300
#7A7A7A
#757575
mono400
#5C5C5C
#545454
mono500
#3D3D3D
#333333
mono600
#292929
#292929
mono700
#1F1F1F
#1F1F1F
mono800
#141414
#141414
mono900
#111111
#111111
mono1000
#000000
#000000

Color Tokens

You can access any of Base Web's colors on the colors object exported by baseui/tokens. You can read more this new module here.

import {colors} from 'baseui/tokens';
const theme = {
primary: colors.blue400,
};

Typography

We have updated the typography scale included in our theme. This is the biggest breaking change in v9. We have removed values from the scale and shifted the default values upwards, so for instance, font200 is now 14px rather than 12px. We have updated all of the components in the library to use lower typography values such that component sizing is unchanged. However, references to typography values in your code will likely need updating.

A number of values have been removed from the typography scale. If you reference any of these in your code, you must update these references! Here are the removed values:

  • font460
  • font470
  • font500
  • font600
  • font700
  • font800
  • font900
  • font1000
  • font1100

Typography Mapping

All of Base Web's components have been updated to adjust to the new scale such that there is very little visual change (with regards to sizing) in the components themselves. Still, you may have built some of your components or made adjustments using the typography theme object. References in your codebase will need to be updated accordingly.

Here is the mapping of v8 to v9 typography values that we used in updating our components:

Old
New
font100
font100
font200
font100
font250
font150
font300
font200
font350
font250
font400
font300
font450
font350
font460
font400
font470
font450
font500
font550
font600
font650
font700
font750
font800
font850
font900
font950
font1000
font1050
font1100
font1450

Here is an example of updating direct uses of font theme variables in source code:

// old
// font300 used to return 14px/20px/400
const StyledFoo = styled('div', props => ({
...props.$theme.typography.font300,
}));
// new
// font200 now returns 14px/20px/400
const StyledFoo = styled('div', props => ({
...props.$theme.typography.font200,
}));

If you use the Block component to apply theme font properties, you will need to adjust those as well:

// old
<Block font="font300" />
// new
<Block font="font200" />

Note, all of this can be done automatically with our new codemod.

Comparison to v8

The following is a comparison of the old and new typographic values:

Old
Value
New
Value
font100
11px/16px/400
font100
12px/20px/400
-
-
font150
12px/20px/500
font200
12px/20px/400
font200
14px/20px/400
font250
12px/20px/500
font250
14px/20px/500
font300
14px/20px/400
font300
16px/24px/400
font350
14px/20px/500
font350
16px/24px/500
font400
16px/24px/400
font400
18px/28px/400
font450
16px/24px/500
font450
18px/28px/500
font460
18px/24px/400
-
-
font470
18px/24px/500
-
-
font500
20px/28px/500
-
-
-
-
font550
20px/28px/500
font600
24px/36px/500
-
-
-
-
font650
24px/32px/500
font700
32px/48px/500
-
-
-
-
font750
28px/36px/500
font800
40px/56px/500
-
-
-
-
font850
32px/40px/500
font900
52px/68px/500
-
-
-
-
font950
36px/44px/500
font1000
72px/96px/400
-
-
-
-
font1050
40px/52px/500
font1100
96px/116px/400
-
-
-
-
font1150
36px/44px/500
-
-
font1250
44px/52px/500
-
-
font1350
52px/64px/500
-
-
font1450
96px/112px/500

You can see from this table that the new scale is not entirely equivalent to the old one. The new scale "resets" at font1150 for Display sizes rather than growing linearly with each step. This means when migrating to v9 you have some choices to make with regards to how you map typography variables.

Typography Components

All of the baseui/typography components have been updated according to the new typography ramps. Each typography theme value now maps one-to-one with a typography component.

Component
Font
Value
Display1
font1450
96px/112px/500
Display2
font1350
52px/64px/500
Display3
font1250
44px/52px/500
Display4
font1150
36px/44px/500
H1
font1050
40px/52px/500
H2
font950
36px/44px/500
H3
font850
32px/40px/500
H4
font750
28px/36px/500
H5
font650
24px/32px/500
H6
font550
20px/28px/500
Label1
font450
18px/28px/500
Paragraph1
font400
18px/28px/400
Label2
font350
16px/24px/500
Paragraph2
font300
16px/24px/400
Label3
font250
14px/20px/500
Paragraph3
font200
14px/20px/400
Label4
font150
12px/20px/500
Paragraph4
font100
12px/20px/400

There are a few important changes to note:

  1. There are now four levels each of Display, Paragraph, and Label (up from one, two, and two respectively).
  2. Paragraph and Label no longer increase in font-size as the digit suffix increases. This has been changed so that all of the typography components decrease in size as the suffix increases, to stay consistent with the header (h1) pattern in HTML. This means you will want to change Label1 and Paragraph1 to Label3 and Paragraph3. This can be done automatically with our new codemod.
  3. Caption1 and Caption2 have been deprecated in favor of Paragraph4 and Label4 respectively. The Caption components have not been removed but instead alias Paragraph and Label components. A future major may see these components removed, so it is best to swap your use of Caption for Paragraph and Label. This can be done automatically with our new codemod.

For reference, here is a mapping of v8 to v9 components:

Old
New
Note
Display
Display1
Aliased
Label1
Label3
Paragraph1
Paragraph3
Caption1
Paragraph4
Aliased
Caption2
Label4
Aliased

Body

These values are used for body text: Label, and Paragraph.

Name
Value
font100
12px/20px/400
font150
12px/20px/500
font200
14px/20px/400
font250
14px/20px/500
font300
16px/24px/400
font350
16px/24px/500
font400
18px/28px/400
font450
18px/28px/500
Read values as font-size/line-height/font-weight.

These values are used for various headers: H1, H2, etc.

Name
Value
font550
20px/28px/500
font650
24px/32px/500
font750
28px/36px/500
font850
32px/40px/500
font950
36px/44px/500
font1050
40px/52px/500
Read values as font-size/line-height/font-weight.

Display

These values are used for special headers, usually in association with marketing material. Internally, we assign these properties to a different font-family. This gives your app a little visual variety.

Name
Value
font1150
36px/44px/500
font1250
44px/52px/500
font1350
52px/64px/500
font1450
96px/112px/500
Read values as font-size/line-height/font-weight.

Codemod

We made a codemod to help projects migrating to v9. You can run it with a single command via npx:

$ npx @uber-web-ui/baseui-codemods --mod=v9Styles --dir=<path_to_code>

This will go through all of the *.js files in your codebase, updating any usage of theme font values or typography components to their v9 counterparts, following the various mappings in this post.

The codemod does not update your theme or colors. You should use theme variables and overrides if you want to customize the colors of various components.

Run the script, check your diff, and click through your app to make sure things look good.

Note, the codemod may not work perfectly- if we forgot any edge cases we will update the script (one more reason to use npx). Click here for more information on baseui codemods.

Inspiration

Some folks may wonder why there is a noticeable stylistic update coming to Base Web. Aren't most components already implemented?

It is important to remember that the Base design system is still evolving. The Base Web library has an ever-moving target ahead of it. Style changes are, at this point, a constant reality for the project.

We consider this to be one of the main features of Base Web. Folks who use the Base design system know that by staying on the latest version of baseui, their app remains on-brand and consistent with other products.

That said, we know these sorts of changes can be disruptive. We don't anticipate stylistic changes of this magnitude to come very often. When they do we will try to make the transition as painless as possible with migration guides (such as this blog post), codemods, and backward compatible mappings wherever possible.

Thanks for using baseui!


Feel free to reach out to us on our Slack channel or through a GitHub issue if you think something is missing from this migration guide.