Rationale

Purpose

• Semantic tokens help design components with consistent visuals and behaviors.
  We may find a color that works better in a component, but making this specific change alone can bring inconsistency and a usability cost. To carefully decide on a color, we need visibility on how this type of element is usually colored. This is why we have semantic color tokens for each of the known use cases that colors have in the Admin.
• The visual weight of an element should be proportional to its relevance.
  When designing pages, we first conduct research to understand what users need frequently, occasionally, and rarely. Then, we choose a style for the interface element (including size, position, and colors) that reflects the prominence it deserves. This is why action colors, for example, vary in contrast (primary, secondary, tertiary) and saturation (accent, neutral).
• Color hues carry meaning and improve usability if applied consistently.
  When we are presented with any object, the next characteristic our eyes perceive is color after perceiving its shape. If a product applies color meaningfully, users will quickly learn this relationship, improving their experience. This is why we consistently use orange if there is something to be cautious about, green to indicate it's working well, and so on.

Application

• A larger breadth of color hues gives space to experimentation.
  Just like red means error and green means success, designers should easily experiment with attributing meaning to color hues. However, since these colors should follow the same tones and saturation as the rest of the interface, defining values can be time-consuming. This is why we have absolute tokens, such as purple and teal, without a clear usage description.
• The improper use of semantic tokens hinders the visibility of new use cases.
  There are a lot of semantic tokens already, but they are all based on the known use cases for color in the Admin. If tokens were applied where they weren't intended, we would have a time-consuming process of analyzing each color application to identify new use cases. This is why we also have absolute tokens to be used when none of the semantic tokens apply.

Visual

• Admin interfaces must look like enterprise-grade work tools.
  During a sales demo, we learned how the visual of an interface sets expectations for what it does. The single control panel for organizations with thousands of employees must look like a serious and robust product that can be trusted. This is why we sparingly use the VTEX Rebel Pink color in interfaces, such as for product marketing content.
• Efficiency is usually more important than delight in Admin interfaces.
  Both dark and saturated colors draw attention, so when they are used merely for delight, they distract users and impede their productivity. A colored background, for example, can even make the text less legible. This is why we use semantic colors in small quantities and prioritize delight sparingly, such as in large colored backgrounds in the extensions store.
• All colors should support mild vision impairments and low-quality monitors by default.
  Most merchants' monitors show a limited color spectrum, don't get very bright, and have low resolutions. Even users with retina displays and perfect eyesight are not always in optimal conditions. This is why we ensure that even $fg-muted achieves WCAG AA and that even $bg-muted is discernible in low-quality monitors.
• A color tone should look like it has the same lightness across hues.
  Even though the RGB color space is more common, CIELUV is a more human option because it's based on how we perceive colors. In RGB, if you choose the same brightness for color in a red and an orange hue, they won't look like they have the same brightness. This is why we use the OKLCH color space (opens in a new tab) to guarantee that colors are perceptually uniform.