# Colours

Colour palettes, semantic usage and accessibility requirements.

Section: foundations
Docs: https://nebula.kaluza.com/foundations/colour

---

import { ColorPanel } from '../../src/components/docs-helpers/ColorPanel';

## Palettes
Colours that are grouped into semantic groups are called **palettes**. Context determines which palette colour should be used and the contrast requirements that need to be met.

### Palette colours
Each palette has six colours, except the Primary palette, which has four.

`{base}` represents the palette name. For instance, in the success palette, the `{base}` token is success and the `on{Base}` token is onSuccess.
- `{base}` - saturated fill, or for use on canvas
- `on{Base}` - text and icon colour on `{base}` or `alt` surfaces (meets 4.5:1 contrast against both)
- `alt` - saturated fill, slightly darker than `{base}`; used for hover state when a component using `{base}` is interactive; never used as a static colour
- `subtle` - very light background, suitable for larger fill areas
- `muted` - light background, suitable for smaller fill areas
- `onMuted` - text and icon colour on `subtle` or `muted` surfaces (meets 4.5:1 contrast against both)

Note: `infoContrast`, `successContrast`, `warningContrast`, and `errorContrast` are deprecated aliases for their respective `on{Base}` tokens. `primaryContrast` is not deprecated.

### Primary
Establishes visual hierarchy and draws attention to the most important action on a page. The main signal of interactivity in the system. May be the brand colour, but not necessarily.

<Stack spaceBetween={4}>
  <Stack spaceBetween={1}>
    <ColorPanel
      title="Primary"
      color="primary"
      textColor="primaryContrast"
      aaColours={[
        "canvas",
        "canvasMuted",
        "primaryContrast",
        "primaryMuted",
      ]}
    />
    <ColorPanel
        title="Primary Alt"
        color="primaryAlt"
        textColor="primaryContrast"
        aaColours={[
          "canvas",
          "canvasMuted",
          "primaryContrast",
          "primaryMuted",
        ]}
      />
    <ColorPanel
      title="Primary Muted"
      textColor="body"
      color="primaryMuted"
      aaColours={[
        "body",
        "heading",
        "primary",
        "primaryAlt",
      ]}
    />
    <ColorPanel
      title="Primary Contrast"
      textColor="body"
      color="primaryContrast"
      aaColours={["primary", "primaryAlt"]}
    />
  </Stack>
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

### Error
Signals that something has gone wrong or will cause a problem if the user proceeds.

<Stack spaceBetween={4}>
  <Stack spaceBetween={1}>
    <ColorPanel
      title="Error"
      color="error"
      textColor="errorContrast"
      aaColours={[
        "canvas",
        "canvasMuted",
        "onError",
      ]}
    />
    <ColorPanel
      title="On Error"
      color="onError"
      textColor="body"
      aaColours={[
        "error",
        "errorAlt",
      ]}
    />
    <ColorPanel
      title="Error Alt"
      color="errorAlt"
      textColor="errorContrast"
      aaColours={[
        "canvas",
        "canvasMuted",
        "onError",
      ]}
    />
    <ColorPanel
      title="Error Subtle"
      color="errorSubtle"
      textColor="body"
      aaColours={[
        "errorOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Error Muted"
      color="errorMuted"
      textColor="body"
      aaColours={[
        "errorOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Error On Muted"
      color="errorOnMuted"
      textColor="errorMuted"
      aaColours={["errorMuted", "errorSubtle"]}
    />
  </Stack>
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

### Warning
Signals that something needs attention, but is not necessarily a problem yet.

<Stack spaceBetween={4}>
  <Stack spaceBetween={1}>
    <ColorPanel
      title="Warning"
      color="warning"
      textColor="warningContrast"
      aaLargeColours={[
        "canvas",
        "canvasMuted",
        "onWarning",
      ]}
    />
    <ColorPanel
      title="On Warning"
      color="onWarning"
      textColor="body"
      aaLargeColours={[
        "warning",
        "warningAlt",
      ]}
    />
    <ColorPanel
      title="Warning Alt"
      color="warningAlt"
      textColor="warningContrast"
      aaLargeColours={[
        "canvas",
        "canvasMuted",
        "onWarning",
      ]}
    />
    <ColorPanel
      title="Warning Subtle"
      color="warningSubtle"
      textColor="body"
      aaLargeColours={[
        "warningOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Warning Muted"
      color="warningMuted"
      textColor="body"
      aaLargeColours={[
        "warningOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Warning On Muted"
      color="warningOnMuted"
      textColor="warningContrast"
      aaLargeColours={[
        "warningMuted",
        "warningSubtle",
      ]}
    />
  </Stack>
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

### Info
Provides supporting context that is useful but not urgent.

<Stack spaceBetween={4}>
  <Stack spaceBetween={1}>
    <ColorPanel
      title="Info"
      color="info"
      textColor="infoContrast"
      aaLargeColours={[
        "canvas",
        "canvasMuted",
        "onInfo",
      ]}
    />
    <ColorPanel
      title="On Info"
      color="onInfo"
      textColor="body"
      aaLargeColours={[
        "info",
        "infoAlt",
      ]}
    />
    <ColorPanel
      title="Info Alt"
      color="infoAlt"
      textColor="infoContrast"
      aaLargeColours={[
        "canvas",
        "canvasMuted",
        "onInfo",
      ]}
    />
    <ColorPanel
      title="Info Subtle"
      color="infoSubtle"
      textColor="body"
      aaLargeColours={[
        "infoOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Info Muted"
      color="infoMuted"
      textColor="body"
      aaLargeColours={[
        "infoOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Info On Muted"
      color="infoOnMuted"
      textColor="infoMuted"
      aaLargeColours={[
        "infoMuted",
        "infoSubtle",
      ]}
    />
  </Stack>
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

### Success
Confirms that an action completed as expected or that a state is healthy.

<Stack spaceBetween={4}>
  <Stack spaceBetween={1}>
    <ColorPanel
      title="Success"
      color="success"
      textColor="successContrast"
      aaLargeColours={[
        "canvas",
        "canvasMuted",
        "onSuccess",
      ]}
    />
    <ColorPanel
      title="On Success"
      color="onSuccess"
      textColor="body"
      aaLargeColours={[
        "success",
        "successAlt",
      ]}
    />
    <ColorPanel
      title="Success Alt"
      color="successAlt"
      textColor="successContrast"
      aaLargeColours={[
        "canvas",
        "canvasMuted",
        "onSuccess",
      ]}
    />
    <ColorPanel
      title="Success Subtle"
      color="successSubtle"
      textColor="body"
      aaLargeColours={[
        "successOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Success Muted"
      color="successMuted"
      textColor="body"
      aaLargeColours={[
        "successOnMuted",
        "body",
        "heading",
      ]}
    />
    <ColorPanel
      title="Success On Muted"
      color="successOnMuted"
      textColor="successContrast"
      aaLargeColours={[
        "successMuted",
        "successSubtle",
      ]}
    />
  </Stack>
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>


## Canvas

Canvas is main colour used for backgrounds and impacts the
contrast requirements of the other colours -
**Primary**, **Body** and **Heading** for example need to be visible when
appearing with this colour.

<Stack spaceBetween={4}>
  <ColorPanel
    title="Canvas"
    textColor="body"
    color="canvas"
    aaColours={[
      "body",
      "heading",
      "primary",
      "error",
    ]}
  />
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Canvas Muted

Canvas Muted is similar to **Canvas**, but allows for
an additinal background colour to distunguish section, such as
alternating rows on a table.

<Stack spaceBetween={4}>
  <ColorPanel
    title="Canvas Muted"
    textColor="body"
    color="canvasMuted"
    aaColours={[
      "body",
      "heading",
      "primary",
      "error",
    ]}
  />
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Body

Body is used for body text. It needs to be accessible when used
with **Canvas** and **Canvas Muted**.

<Stack spaceBetween={4}>
<ColorPanel
  title="Body"
  color="body"
  textColor="canvas"
  aaColours={["canvas", "canvasMuted"]}
/>
_Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Heading

Heading is used for heading text. It needs to be accessible when
used with **Canvas** and **Canvas Muted**.

<Stack spaceBetween={4}>
<ColorPanel
  title="Heading"
  color="heading"
  textColor="canvas"
  aaColours={["canvas", "canvasMuted"]}
/>
_Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Border

Border is used the borders of important UI elements, such as text
inputs. It needs to be accessible when used with **Canvas** and **Canvas Muted**.

<Stack spaceBetween={4}>
  <ColorPanel
    title="Border"
    color="border"
    textColor="canvas"
    aaColours={["canvas", "canvasMuted"]}
  />
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Border Muted

Border Muted is used the borders of decorative UI elements, such
as cards. As it is used for decorative elements only it has no
specific requirement to be accessible.

<Stack spaceBetween={4}>
  <ColorPanel
    title="Border Muted"
    textColor="body"
    color="borderMuted"
  />
  _Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Focus
Focus is used to highlight the currently selected item when using tab navigation. It needs to be accessible when used with **Canvas** and **Canvas Muted**.

<Stack spaceBetween={4}>
<ColorPanel
  title="Focus"
  textColor="canvas"
  color="focus"
  aaColours={["canvas", "canvasMuted"]}
/>
_Theme tokens for this component are configurable via `createTheme`. See the theme guide: https://nebula.kaluza.com/guides/theme_
</Stack>

## Accessibility

We take web accessibility standards seriously. As a result, we require
all designs to meet the minimum contrast ratios specified by
**WCAG 2.1 Level AA** which requires a contrast ratio of at
least **4.5:1 for normal text** and
**3:1 for large text**. It also requires a contrast ratio
of at least
**3:1 for graphics and user interface components** (such as
form input borders).

You can check contrast at [https://webaim.org/resources/contrastchecker/](https://webaim.org/resources/contrastchecker/)

### What is large text?

Large text is defined as typically **bold text of 18.66px and larger, or regular text of 24px and larger**.
WCAG 2.1 Level AA requres a contrast ratio of 3:1 for Large Text.

### What counts as decorative use?

Just because a colour doesn’t have sufficient contrast, doesn’t mean we
can’t use it for **purely decorative** means. When using
colours in this way it’s important not to relay any important
information, as visually impared users may struggle to see it at all.

The element should have no impact on the meaning of the page - **if it were removed, it wouldn’t affect the user’s experience**.