Products built with Vitality should make use of color in meaningful ways and should avoid adding unncessary "flare". This approach allows the dimension of color to communicate meaning and direct the user's eye toward what's important in an interaction. It's okay if an interface feels plain if it is focused on supporting the user's goals.

Most colors used in Vitality components are designed to communicate particular meaning to the user.

These colors should comprise the majority of a product's interface.

Use severity colors to communicate different levels of importance to the user. Common use cases include successes, errors, urgency or overdue statuses – or generally-informative "info" content. Because the majority of the interface uses neutral colors, using these colors in key moments / areas of the interface will help direct the user's eye. Although part of the core colors, accent is also available in the severity colors.

You may notice certain components use different "amounts" of a core color (like the above examples - text uses primary color with a lighter version of that color for the background). They also have colors set for active and hovered states. Each of these core colors comprises a "scale" of color. Each scale contains different tints of a particular color.

The Magentus violet color palette is included in Vitality for instances where the brand needs to be represented. This color should be used sparingly and only in areas where the brand needs to be communicated. It can be used in conjunction with the accent color scale to make up the key Magentus colors.

If you aren't creating new components and simply using Vitality's pre-existing components, refer to each individual component's documentation for more detailed guidance on the use case for color.

Read on if you need to develop your own components or are creating new components for Vitality.

When creating new components, Vitality provides a helper function that allows you to specify a scale (eg. primary, accent, success, critical etc.) and a use case. This function returns a color name that maps to a "step" in the scale of color.

For designers, the Figma library provides a palette of the numerous color scales grouped by their use case (see below).

Usually, a designer should have already decided on the colors to be used prior to development (or in collaboration). Their tooling also has these use cases and scales available, so the conversation should be easy.

See below example:

Preview of Figma using color use cases. Here you can see a similar naming lookup to what's used in code.

import {
  getColorScaleValueByUseCase,
  colorUseCases,
} from "@vitality-ds/system";

const { backgrounds } = colorUseCases;

const Component = styled("div", {
  backgroundColor: getColorScaleValueByUseCase(
    "primary",
    backgrounds.uiElementSolid
  ),
  "&:hover": {
    backgroundColor: getColorScaleValueByUseCase(
      "primary",
      backgrounds.uiElementSolid_hovered
    ),
  },
});

Every color consists of a scale and a use case:

1. Scales - A group of "tints" of a specific color. For instance, the Primary scale has varying degrees of tints of cyan.
2. Use cases - A mapping of a use case to an individual tint for any scale. For example, solid backgrounds use a high-saturation success (green) and light app backgrounds use a low-saturation. Border use cases use a light version of the color.

Mapping a use case to a scale value allows things like dark mode to work automatically; as color values mapped to use cases are inverted/switched depending on the color mode. Try it out:

The below example utilises a number of use cases to show example Appointments. These components utilise the use cases for subtle backgrounds, borders and UI element backgrounds – as well as active and hover states.

Switch color mode for reference:

The below expands on the various use cases for color. What this illusrates is how to decide which use case should be used for styling a component. This should remove guess work and encourage consistency.

Use the below as reference. If you're using the copied tooltips below, you may need to import the getColorScaleValueByUseCase function into your file:

The below snippet outlines the mappings between use cases and their scale numbers. Most of the time you won't need to know this.

For some components, you may want to use a color with a subtle transparency. This is done by using the the neutralA scale. All of the same use cases are available for this scale, but the values are different. The neutralA scale is a set of colors that are designed to be used on top of a background image or color.

The neutralA scale is designed to be used in specific cases where you want to use a color with a semi-transparent background. As Vitality is not designed to be overly transparent, some components may behave differently when using this scale. For example, the Button component will not use the neutralA scale for its background color, but will use it for its border color.

() => {
  const TransparentContainer = styled(Flex, {
    backgroundColor: "$neutralA1",
    padding: "$xl",
    borderRadius: "$default",
  });

  return (
    <DocsBox
      css={{
        width: "100%",
        display: "flex",
        justifyContent: "center",
        alignItems: "flex-end",
        paddingBlock: "$xxl",
        backgroundImage:
          "url(https://media2.giphy.com/media/v1.Y2lkPTc5MGI3NjExd2k2NGR5YzNkZ21lNDIzcXNjM21kMzBkcmR2anI2M2cxeWpsbTczYiZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/2csuIJj6TmuKA/giphy.gif)",
      }}
    >
      <TransparentContainer spacing="lg">
        <FormField
          label="Email"
          inputProps={{ placeholder: "you@example.com" }}
        />
        <FormField type="password" label="Password" />
        <Button appearance="primary" shouldFitContainer>
          Login
        </Button>
      </TransparentContainer>
    </DocsBox>
  );
};

Vitality's complete color palette provides all the colors you should need. If you are choosing colors outside of this palette, please consult with your designer.

Whilst the use of one-off colors should be avoided, you can use these values in your styled() definitions of a component:

() => {
  const MyComponent = styled("div", {
    backgroundColor: "hsl(10, 49%, 44%)",
    padding: "$xxl",
  });

  return <MyComponent>Custom color</MyComponent>;
};