Aliasing

A guide to providing semantic aliases for colors.

Semantic aliases

Referencing color scales by their actual scale name can work well, like blue and red. But often, creating semantic aliases like accent, primary, neutral, or brand can be helpful, especially when it comes to theming.

/*
 * Note: Importing from the CDN in production is not recommended.
 * It's intended for prototyping only.
 */
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blue.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/green.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/yellow.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/red.css';

:root {
  --accent-1: var(--blue-1);
  --accent-2: var(--blue-2);
  --accent-3: var(--blue-3);
  --accent-4: var(--blue-4);
  --accent-5: var(--blue-5);
  --accent-6: var(--blue-6);
  --accent-7: var(--blue-7);
  --accent-8: var(--blue-8);
  --accent-9: var(--blue-9);
  --accent-10: var(--blue-10);
  --accent-11: var(--blue-11);
  --accent-12: var(--blue-12);

  --success-1: var(--green-1);
  --success-2: var(--green-2);
  /* repeat for all steps */

  --warning-1: var(--yellow-1);
  --warning-2: var(--yellow-2);
  /* repeat for all steps */

  --danger-1: var(--red-1);
  --danger-2: var(--red-2);
  /* repeat for all steps */
}

With this approach, you will likely run into issues where you need to use the same scale for multiple semantics. Common examples include:

If you map yellow to "warning", you might also need yellow to communicate "pending".
If you map red to "danger", you might also need red to communicate "error" or "rejected".
If you map green to "success", you might also need green to communicate "valid".
If you map blue to "accent", you might also need blue to communicate "info".

In this scenario, you can choose to define multiple semantic aliases which map to the same scale.

/*
 * Note: Importing from the CDN in production is not recommended.
 * It's intended for prototyping only.
 */
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blue.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/green.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/yellow.css';

:root {
  --accent-1: var(--blue-1);
  --accent-2: var(--blue-2);
  --info-1: var(--blue-1);
  --info-2: var(--blue-2);

  --success-1: var(--green-1);
  --success-2: var(--green-2);
  --valid-1: var(--green-1);
  --valid-2: var(--green-2);

  --warning-1: var(--yellow-1);
  --warning-2: var(--yellow-2);
  --pending-1: var(--yellow-1);
  --pending-2: var(--yellow-2);
}

Or you can simply recommend that your teammates defer to the original scale name for situations where there is no appropriate semantic alias.

Use case aliases

Each step in Radix Colors scales is designed for a specific use case. To help your team know which step to use, you can provide aliases based on the designed use cases.

/*
 * Note: Importing from the CDN in production is not recommended.
 * It's intended for prototyping only.
 */
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blue.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/green.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/yellow.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/red.css';

:root {
  --accent-base: var(--blue-1);
  --accent-bg-subtle: var(--blue-2);
  --accent-bg: var(--blue-3);
  --accent-bg-hover: var(--blue-4);
  --accent-bg-active: var(--blue-5);
  --accent-line: var(--blue-6);
  --accent-border: var(--blue-7);
  --accent-border-hover: var(--blue-8);
  --accent-solid: var(--blue-9);
  --accent-solid-hover: var(--blue-10);
  --accent-text: var(--blue-11);
  --accent-text-contrast: var(--blue-12);

  --success-base: var(--green-1);
  --success-bg-subtle: var(--green-2);
  /* repeat for all steps */

  --warning-base: var(--yellow-1);
  --warning-bg-subtle: var(--yellow-2);
  /* repeat for all steps */

  --danger-base: var(--red-1);
  --danger-bg-subtle: var(--red-2);
  /* repeat for all steps */
}

Again, with this approach, you will likely run into issues where you need to use the same step for multiple use cases. Common examples include:

Step 9 is designed for solid backgrounds, but it also works well for input placeholder text.
Step 8 is designed for hovered component borders, but it also works well for focus rings.

In these cases, you can choose to define multiple aliases which map to the same step.

/*
 * Note: Importing from the CDN in production is not recommended.
 * It's intended for prototyping only.
 */
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/gray.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blue.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/green.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/yellow.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/red.css';

:root {
  --gray-solid: var(--gray-9);
  --gray-placeholderText: var(--gray-9);

  --accent-border-hover: var(--blue-8);
  --accent-focus-ring: var(--blue-8);
}

Or you can simply recommend that your teammates defer to the original step number for situations where use cases don't have an alias.

Mutable aliases

When designing for both light and dark modes, you sometimes need to map a variable to one color in light mode, and another color in dark mode. Common examples include:

Components that have a white background in light mode and a subtle gray background in dark mode. For example, Card, Popover, DropdownMenu, HoverCard, Dialog etc.
Components that have a transparent black background in light mode and a transparent white background in dark mode. For example, Tooltip.
Shadows that are saturated, transparent gray in light mode, and pure black in dark mode.
An overlay that is light transparent black in light mode, and a darker transparent black in dark mode.

/*
 * Note: Importing from the CDN in production is not recommended.
 * It's intended for prototyping only.
 */
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/slate.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/slateA.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/whiteA.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blackA.css';

:root {
  --panel: white;
  --panelContrast: var(--black-a11);
  --shadow: var(--slate-a3);
  --overlay: var(--black-a8);
}

.dark {
  /* Remap your colors for dark mode */
  --panel: var(--slate-2);
  --panelContrast: var(--white-a11);
  --shadow: black;
  --overlay: var(--black-a12);
}

Avoid using specific variable names like "CardBg", or "Tooltip", because you will likely need to use each variable for multiple use cases.

Renaming scales

If you wish, you can rename scales. Reasons might include:

Rename a saturated gray to "gray" to keep things simple.
Rename "sky" or "grass" to "blue" or "green" to keep things standard.
Rename a scale to match your brand, like how Discord use "Blurple".
Just to have some fun :)

/*
 * Note: Importing from the CDN in production is not recommended.
 * It's intended for prototyping only.
 */
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/slate.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/sky.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/grass.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/violet.css';
@import 'https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/crimson.css';

:root {
  --gray-1: var(--slate-1);
  --gray-2: var(--slate-2);

  --blue-1: var(--sky-1);
  --blue-2: var(--sky-2);

  --green-1: var(--grass-1);
  --green-2: var(--grass-2);

  --blurple-1: var(--violet-1);
  --blurple-2: var(--violet-2);

  --caribbean-sunset-1: var(--crimson-1);
  --caribbean-sunset-2: var(--crimson-2);
}

PreviousUsage

NextReleases

Edit this page on GitHub.

Overview

Palette Composition

Tests

Aliasing

Semantic aliases

Use case aliases

Mutable aliases

Renaming scales