Design System Team/Color/Design documentation

Overview

The Codex design system color palette adds visual meaning and accents key interface elements. It also helps communicate specific messages when needed. Over time, the palette has evolved to meet the growing needs of the design system, and it's expanding again now. This page will document design goals, learnings, and thought processes in the journey of expanding the Codex color palette.

Note: this documentation refers to Codex and not the Wikimedia Foundation brand colors.

Updates

September 2024: Initial color palette expansion

The Codex color palette has been revised to include a range of new colors, requiring slight changes to existing colors and their application. The most notable changes are listed below:

1. Progressive and Destructive elements such as links and buttons in dark mode, plus visited links in light and dark modes, are now lighter and less saturated. This is meant to improve readability specifically in dark mode, with this new shade of blue and red specifically requested by community members.
2. The Message background colors have also been updated in both light and dark modes. This is also an intentional shift, as the new palette enables us to bring a bit more saturation to these status colors, since they are meant to help convey meaning through the color.

Most Noticeable Color Changes Before/After

Element	Mode	Previous HEX color	New HEX color
Base Link (text)	Dark	#6d8af2	#88a3e8
Visited Link (text)	Light	#6b4ba1	#6a60b0
Visited Link (text)	Dark	#977dbd	#a799cd
Red Link (text)	Light	#d73333	#bf3c2c
Red Link (text)	Dark	#ff4242	#fd7865
Visited Red Link (text)	Light	#a55858	#9f5555
Visited Red Link (text)	Dark	#b97876	#c99391
Progressive Normal & Quiet Button (text)	Dark	#6d8af2	#88a3e8
Destructive Normal & Quiet Button (text)	Dark	#ff4242	#fd7865
Error Message (background)	Light	#fee7e6	#ffe9e5
Error Message (background)	Dark	#421211	#612419
Warning Message (background)	Light	#fef6e7	#fdf2d5
Warning Message (background)	Dark	#301d00	#453217
Success Message (background)	Light	#d5fdf4	#dff2eb
Success Message (background)	Dark	#00261e	#153D31
Notice Message (background)	Dark	#202122	#27292d

A comparison of previous token values and hex colors to the new tokens and hex colors can be found in this Phabricator task.

Why more colors?

Codex recently added more colors to the previous palette to support dark mode. The colors added were meant to serve only the purpose of supporting dark mode, and fitting into the numerical value structure that had already existed (100 being the lowest value of any color and 800 being the highest). The values for these new colors were based on the current palette and other Wiki environments where Codex wasn’t used.

We knew this process was not perfect, and would benefit from follow-up task of further expanding the color palette, while cleaning up the numerical value structure to make things more consistent and cohesive, meaning visibly aligning each value of every color in a saturation and luminance sense.

Expansion goals

1. At the foundational color level, create a more complete set of colors, spanning a larger range of the color spectrum, with equivalent values for each color. For example, every color (gray, red, blue, green, etc.) all have values ranging from 50 to 1000.
2. At the application level, maintain at least Web Content Accessibility Guidelines (WCAG) 2.2 Level AA color contrast, and improve visual accessibility where possible.
3. Limit the amount of prominent visual changes. For example, reduce changes to colors like the gray palette and the main progressive blue.

Usage guidance

With this color expansion, we can provide the community with guidance on what colors can be used when and with what other colors, as well as consider more holistic guidance for things like data visualization.

Accessibility and APCA

The current WCAG version 2.2 at this iteration of the color expansion measures the differences between colors using perceived luminance, commonly referred to as "simple color contrast". An example of this can be found here.

Advanced Perceptual Contrast Algorithm (APCA), takes into consideration font weight and size, color (or perceived lightness differences between two colors), and context (visual surroundings and intended purposes of text) to measure the visual accessibility of color. Though we have this current understanding of this form of color measurement in the future version of WCAG 3, there is not enough information to influence a major affect on the current color expansion. Therefore, the way application colors will be applied at this point will continue to be based off of WCAG 2 standards and criteria.

Considering dark mode

When adding new color values which will commonly be used in dark mode, i.e. the lighter values, we want to be careful that these colors find a balance between conveying the hue they are meant to without being too saturated or bright. This will help readability in dark mode as the brighter, more saturated colors can cause eye strain. The same reasoning applies to what color we assign to application tokens used for text, primarily in the gray palette. We want to avoid using the lightest gray, and especially white, for primary uses of text in dark mode.

Changing existing color values

The expansion will not only include adding new colors, but changing existing colors. This is to ensure we can have a palette that creates consistent perceived lightness, brightness, and saturation across colors of similar values. In changing existing values, we will start from any existing, primary value and adjust until we find the right balance across all colors and values. Choosing colors cannot happen at a micro level but at a macro one, to ensure the palette as a whole is cohesive. This also helps us make blanket accessibility statements in both light and dark modes, such as:

• In light mode, the darkest that a background can be is the 100 value of Gray, and the 50 value of all other colors. Then, the lightest any text can be on that those backgrounds is the 600 value of Gray, and the 700 value of all other colors.
• In dark mode, the lightest that a background can be is the 800 value of Gray, and the 900 value of all other colors. Then, the darkest any text can be on that those backgrounds is the 400 value of all colors.
• In both light and dark modes, the 500 value of all colors can be used for graphical elements, such as icons and borders/dividers.

Naming new colors

There are a few new colors we will be adding into the Codex palette, to help achieve the first goal and support more broader color palette needs. These colors include Orange, Lime, and Pink. When naming new colors, we want to consider ease of spelling and familiarity, as well as existing naming conventions.

Orange and Pink are entirely new colors, spectrum-wise. When naming Lime, we could consider using the name "Green" instead, and renaming the existing green color. However, this introduces more complexity and confusion than necessary. So we are moving forward with the name Lime.

Other considerations

Color organization

As we add more colors, we’re rethinking how to organize the whole set in a more logical way. The approach we are moving forward with is based on the visual color spectrum, starting with Red and ending with Maroon. The organization of these colors in this way occurs in Figma, code, and the Codex docs site.

Sepia mode

In the near future, we will need to consider a more warmly toned gray palette to support Sepia mode not only in its current existence within mobile apps, as the apps begin to use Codex, but also the potential of a Sepia mode on web. We will need to consider the name of this color. Currently, there are uses of a "Taupe" and "Beige" in the mobile apps color system. One problem with both of these names is that they can be difficult to spell. We could name this color "Sepia". While that is the name of the mode, it is also the name of the color. The familiarity of the mode name could be a reason that we move forward with this name.

Disabled elements

When it comes to choosing colors for disabled elements, we have determined that it is more important to convey that a disabled element is visibly different than an enabled element than to try and make the disabled element meet any sort of WCAG 2 contrast ratio criteria. This decision has resulted in making the disabled styles use a few degrees of the Gray palette, instead of ever using white or black within disabled elements.

Frequently Asked Questions

Using Codex colors in article content?

At this time we are not providing explicit recommendations for using Codex palette colors in article content. We are focussing on their usage for user-interface elements. Guidance on how to best use various colors and tools to make them easier to maintain in article content will be provided in the future. For template maintainers, Codex design tokens can be used as CSS variables to ensure compatibility with dark mode. For other uses, you are welcome to copy the hex values of the Codex palette colors from the Codex Style Guide page.