@workday/canvas-kit-docs
Version:
Documentation components of Canvas Kit components
269 lines (251 loc) • 81.5 kB
text/mdx
import {StorybookInformationHighlight} from './StorybookInformationHighlight';
# Color Token Migration
<StorybookInformationHighlight
title="Use system tokens over base tokens"
description="The tables below provide mapping information for all token levels (base, system, brand) to help
you migrate your usage. For most use cases, we highly recommend migrating to system tokens to make future maintaining easier."
/>
<br />
## Table of Contents
- [Base Color Mapping](#base-color-mapping)
- [Brand Color Migration](#brand-color-migration)
- [System Color Usage Guide (Recommended)](#system-color-usage-guide-recommended)
- [Other Mapping](#other-mapping)
- [Migration Examples](#migration-examples)
## Base Color Mapping
Old base colors have a new base token value. Check
[these tables](https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v3-visual-changes-base-deprecated-palette--docs)
to see visual changes.
> **Important:** Old "fruity" color tokens are deprecated and have been mapped to new palette
> colors. Note that the v3 color scale uses `oklch`, which differs from `rgb` or `hex`, so the new
> color may not be a perfect 1:1 match with the old token. It can cause **visual breaking changes**.
>
> In some cases, there may not be a direct replacement in the new palette, and the value may remain
> a deprecated token. In these situations, you may need to manually select a new color that best
> fits your needs. You can use
> [a comparison tool](https://stackblitz.com/edit/color-comparator?file=src%2FApp.tsx) to find the
> best match.
| Old Token | New Token | CSS Variable | Surface System Color | Foreground System Color | Border System Color |
| ------------------------------ | --------------------------------- | ------------------------------------ | --------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| `colors.cinnamon100` | `base.red50` | `--cnvs-base-palette-red-50` | `system.color.brand.surface.critical.strong` | `system.color.fg.danger.default` | |
| `colors.cinnamon200` | `base.red100` | `--cnvs-base-palette-red-100` | `system.color.surface.danger.default` | | |
| `colors.cinnamon300` | `base.red300` | `--cnvs-base-palette-red-300` | | | |
| `colors.cinnamon400` | `base.red400` | `--cnvs-base-palette-red-400` | | `system.color.fg.danger.default` | |
| `colors.cinnamon500` | `base.red600` | `--cnvs-base-palette-red-600` | `system.color.brand.accent.critical` | `system.color.brand.fg.critical.default` | `system.color.border.critical.default` |
| `colors.cinnamon600` | `base.red700` | `--cnvs-base-palette-red-700` | `system.color.fg.danger.strong` | `system.color.fg.critical.strong` | |
| `colors.peach100` | `base.coral50` | `--cnvs-base-palette-coral-50` | | | |
| `colors.peach200` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
| `colors.peach300` | `base.coral300` | `--cnvs-base-palette-coral-300` | | | |
| `colors.peach400` | `base.coral400` | `--cnvs-base-palette-coral-400` | | | |
| `colors.peach500` | `base.coral600` | `--cnvs-base-palette-coral-600` | | | |
| `colors.peach600` | `base.coral700` | `--cnvs-base-palette-coral-700` | | | |
| `colors.chiliMango100` | `base.coral100` | `--cnvs-base-palette-coral-100` | | | |
| `colors.chiliMango200` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
| `colors.chiliMango300` | `base.coral300` | `--cnvs-base-palette-coral-300` | | | |
| `colors.chiliMango400` | `base.coral500` | `--cnvs-base-palette-coral-500` | | | |
| `colors.chiliMango500` | `base.coral500` | `--cnvs-base-palette-coral-500` | | | |
| `colors.chiliMango600` | `base.coral700` | `--cnvs-base-palette-coral-700` | | | |
| `colors.cantaloupe100` | `base.amber50` | `--cnvs-base-palette-amber-50` | `system.color.brand.surface.caution.strong` | | |
| `colors.cantaloupe200` | `base.amber200` | `--cnvs-base-palette-amber-200` | `system.color.surface.warning.default` | | |
| `colors.cantaloupe300` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
| `colors.cantaloupe400` | `base.amber400` | `--cnvs-base-palette-amber-400` | `system.color.brand.accent.caution` | | `system.color.brand.focus.caution.inner` |
| `colors.cantaloupe500` | `base.amber500` | `--cnvs-base-palette-amber-500` | `system.color.brand.accent.caution` | `system.color.fg.warning.default` | |
| `colors.cantaloupe600` | `base.amber600` | `--cnvs-base-palette-amber-600` | `system.color.brand.accent.caution` | | `system.color.brand.focus.caution.outer` |
| `colors.sourLemon100` | `base.amber25` | `--cnvs-base-palette-amber-25` | | | |
| `colors.sourLemon200` | `base.amber100` | `--cnvs-base-palette-amber-100` | | | |
| `colors.sourLemon300` | `base.amber200` | `--cnvs-base-palette-amber-200` | | | |
| `colors.sourLemon400` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
| `colors.sourLemon500` | `base.amber300` | `--cnvs-base-palette-amber-300` | | | |
| `colors.sourLemon600` | `base.amber500` | `--cnvs-base-palette-amber-500` | | | |
| `colors.juicyPear100` | `base.amber25` | `--cnvs-base-palette-amber-25` | | | |
| `colors.juicyPear200` | `base.amber100` | `--cnvs-base-palette-amber-100` | | | |
| `colors.juicyPear300` | `base.amber200` | `--cnvs-base-palette-amber-200` | | | |
| `colors.juicyPear400` | `base.amber200` | `--cnvs-base-palette-amber-200` | | | |
| `colors.juicyPear500` | `base.green500` | `--cnvs-base-palette-green-500` | | | |
| `colors.juicyPear600` | `base.green700` | `--cnvs-base-palette-green-700` | | | |
| `colors.kiwi100` | `base.green50` | `--cnvs-base-palette-green-50` | | | |
| `colors.kiwi200` | `base.green100` | `--cnvs-base-palette-green-100` | | | |
| `colors.kiwi300` | `base.green200` | `--cnvs-base-palette-green-200` | | | |
| `colors.kiwi400` | `base.green500` | `--cnvs-base-palette-green-500` | | | |
| `colors.kiwi500` | `base.green500` | `--cnvs-base-palette-green-500` | | | |
| `colors.kiwi600` | `base.green700` | `--cnvs-base-palette-green-700` | | | |
| `colors.greenApple50` | `base.green50` | `--cnvs-base-palette-green-50` | `system.color.brand.surface.positive.strong` | | |
| `colors.greenApple100` | `base.green100` | `--cnvs-base-palette-green-100` | `system.color.brand.surface.positive.default` | | |
| `colors.greenApple200` | `base.green200` | `--cnvs-base-palette-green-200` | | `system.color.fg.success.default` | |
| `colors.greenApple600` | `base.green600` | `--cnvs-base-palette-green-600` | `system.color.accent.success.default` | `system.color.brand.fg.positive.default` | |
| `colors.greenApple700` | `base.green700` | `--cnvs-base-palette-green-700` | `system.color.brand.accent.positive` | `system.color.brand.fg.positive.strong` | |
| `colors.greenApple800` | `base.green800` | `--cnvs-base-palette-green-800` | `system.color.brand.accent.positive` | `system.color.brand.fg.positive.strong` | |
| `colors.watermelon100` | `base.teal25` | `--cnvs-base-palette-teal-25` | | | |
| `colors.watermelon200` | `base.teal100` | `--cnvs-base-palette-teal-100` | | | |
| `colors.watermelon300` | `base.green100` | `--cnvs-base-palette-green-100` | | | |
| `colors.watermelon400` | `base.green600` | `--cnvs-base-palette-green-600` | | | |
| `colors.watermelon500` | `base.green700` | `--cnvs-base-palette-green-700` | | | |
| `colors.watermelon600` | `base.green900` | `--cnvs-base-palette-green-900` | | | |
| `colors.jewel100` | `base.teal25` | `--cnvs-base-palette-teal-25` | | | |
| `colors.jewel200` | `base.teal200` | `--cnvs-base-palette-teal-200` | | | |
| `colors.jewel300` | `base.teal400` | `--cnvs-base-palette-teal-400` | | | |
| `colors.jewel400` | `base.teal500` | `--cnvs-base-palette-teal-500` | | | |
| `colors.jewel500` | `base.teal600` | `--cnvs-base-palette-teal-600` | | | |
| `colors.jewel600` | `base.teal700` | `--cnvs-base-palette-teal-700` | | | |
| `colors.toothpaste100` | `base.azure50` | `--cnvs-base-palette-azure-50` | | | |
| `colors.toothpaste200` | `base.azure200` | `--cnvs-base-palette-azure-200` | | | |
| `colors.toothpaste300` | `base.azure300` | `--cnvs-base-palette-azure-300` | | | |
| `colors.toothpaste400` | `base.azure500` | `--cnvs-base-palette-azure-500` | | | |
| `colors.toothpaste500` | `base.azure700` | `--cnvs-base-palette-azure-700` | | | |
| `colors.toothpaste600` | `base.azure800` | `--cnvs-base-palette-azure-800` | | | |
| `colors.blueberry100` | `base.blue100` | `--cnvs-base-palette-blue-100` | | | |
| `colors.blueberry200` | `base.blue100` | `--cnvs-base-palette-blue-100` | `system.color.brand.surface.primary.default` | | |
| `colors.blueberry300` | `base.blue400` | `--cnvs-base-palette-blue-400` | | `system.color.fg.info.default` | |
| `colors.blueberry400` | `base.blue600` | `--cnvs-base-palette-blue-600` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.default` | `system.color.border.primary.default` |
| `colors.blueberry500` | `base.blue700` | `--cnvs-base-palette-blue-700` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.strong` | |
| `colors.blueberry600` | `base.blue800` | `--cnvs-base-palette-blue-800` | `system.color.brand.accent.primary` | `system.color.brand.fg.primary.strong` | |
| `colors.plum100` | `base.blue100` | `--cnvs-base-palette-blue-100` | | | |
| `colors.plum200` | `base.blue200` | `--cnvs-base-palette-blue-200` | | | |
| `colors.plum300` | `base.blue300` | `--cnvs-base-palette-blue-300` | | | |
| `colors.plum400` | `base.blue400` | `--cnvs-base-palette-blue-400` | | | |
| `colors.plum500` | `base.blue500` | `--cnvs-base-palette-blue-500` | | | |
| `colors.plum600` | `base.blue600` | `--cnvs-base-palette-blue-600` | | | |
| `colors.berrySmoothie100` | `base.indigo50` | `--cnvs-base-palette-indigo-50` | | | |
| `colors.berrySmoothie200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | | | |
| `colors.berrySmoothie300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | | | |
| `colors.berrySmoothie400` | `base.blue500` | `--cnvs-base-palette-blue-500` | | | |
| `colors.berrySmoothie500` | `base.blue700` | `--cnvs-base-palette-blue-700` | | | |
| `colors.berrySmoothie600` | `base.blue800` | `--cnvs-base-palette-blue-800` | | | |
| `colors.blackberry100` | `base.indigo25` | `--cnvs-base-palette-indigo-25` | | | |
| `colors.blackberry200` | `base.indigo200` | `--cnvs-base-palette-indigo-200` | | | |
| `colors.blackberry300` | `base.indigo400` | `--cnvs-base-palette-indigo-400` | | | |
| `colors.blackberry400` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | | | |
| `colors.blackberry500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | | | |
| `colors.blackberry600` | `base.indigo900` | `--cnvs-base-palette-indigo-900` | | | |
| `colors.islandPunch100` | `base.purple25` | `--cnvs-base-palette-purple-25` | | | |
| `colors.islandPunch200` | `base.purple200` | `--cnvs-base-palette-purple-200` | | | |
| `colors.islandPunch300` | `base.purple500` | `--cnvs-base-palette-purple-500` | | | |
| `colors.islandPunch400` | `base.purple500` | `--cnvs-base-palette-purple-500` | | | |
| `colors.islandPunch500` | `base.purple700` | `--cnvs-base-palette-purple-700` | | | |
| `colors.islandPunch600` | `base.purple800` | `--cnvs-base-palette-purple-800` | | | |
| `colors.grapeSoda100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | | | |
| `colors.grapeSoda200` | `base.magenta200` | `--cnvs-base-palette-magenta-200` | | | |
| `colors.grapeSoda300` | `base.purple400` | `--cnvs-base-palette-purple-400` | | | |
| `colors.grapeSoda400` | `base.purple500` | `--cnvs-base-palette-purple-500` | | | |
| `colors.grapeSoda500` | `base.purple600` | `--cnvs-base-palette-purple-600` | | | |
| `colors.grapeSoda600` | `base.purple800` | `--cnvs-base-palette-purple-800` | | | |
| `colors.pomegranate100` | `base.magenta50` | `--cnvs-base-palette-magenta-50` | | | |
| `colors.pomegranate200` | `base.magenta100` | `--cnvs-base-palette-magenta-100` | | | |
| `colors.pomegranate300` | `base.magenta500` | `--cnvs-base-palette-magenta-500` | | | |
| `colors.pomegranate400` | `base.magenta400` | `--cnvs-base-palette-magenta-400` | | | |
| `colors.pomegranate500` | `base.red700` | `--cnvs-base-palette-red-700` | | | |
| `colors.pomegranate600` | `base.red800` | `--cnvs-base-palette-red-800` | | | |
| `colors.fruitPunch100` | `base.red25` | `--cnvs-base-palette-red-25` | | | |
| `colors.fruitPunch200` | `base.red200` | `--cnvs-base-palette-red-200` | | | |
| `colors.fruitPunch300` | `base.red300` | `--cnvs-base-palette-red-300` | | | |
| `colors.fruitPunch400` | `base.red400` | `--cnvs-base-palette-red-400` | | | |
| `colors.fruitPunch500` | `base.red400` | `--cnvs-base-palette-red-400` | | | |
| `colors.fruitPunch600` | `base.red700` | `--cnvs-base-palette-red-700` | | | |
| `colors.rootBeer100` | `base.coral25` | `--cnvs-base-palette-coral-25` | | | |
| `colors.rootBeer200` | `base.coral100` | `--cnvs-base-palette-coral-100` | | | |
| `colors.rootBeer300` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
| `colors.rootBeer400` | `base.coral200` | `--cnvs-base-palette-coral-200` | | | |
| `colors.rootBeer500` | `base.amber900` | `--cnvs-base-palette-amber-900` | | | |
| `colors.rootBeer600` | `base.amber950` | `--cnvs-base-palette-amber-950` | | | |
| `colors.toastedMarshmallow100` | `base.amber25` | `--cnvs-base-palette-amber-25` | | | |
| `colors.toastedMarshmallow200` | `base.orange100` | `--cnvs-base-palette-orange-100` | | | |
| `colors.toastedMarshmallow300` | `base.orange200` | `--cnvs-base-palette-orange-200` | | | |
| `colors.toastedMarshmallow400` | `base.orange300` | `--cnvs-base-palette-orange-300` | | | |
| `colors.toastedMarshmallow500` | `base.amber500` | `--cnvs-base-palette-amber-500` | | | |
| `colors.toastedMarshmallow600` | `base.amber600` | `--cnvs-base-palette-amber-600` | | | |
| `colors.licorice100` | `base.slate400` | `--cnvs-base-palette-slate-400` | `system.color.accent.muted.soft` | `system.color.fg.disabled` | `system.color.fg.disabled` |
| `colors.licorice200` | `base.slate500` | `--cnvs-base-palette-slate-500` | `system.color.accent.muted.soft` | `system.color.fg.muted.default` | `system.color.border.input.default` |
| `colors.licorice300` | `base.slate600` | `--cnvs-base-palette-slate-600` | `system.color.accent.muted.default` | `system.color.fg.muted.default` | |
| `colors.licorice400` | `base.slate700` | `--cnvs-base-palette-slate-700` | `system.color.accent.muted.default` | `system.color.fg.muted.strong ` |
| `colors.licorice500` | `base.slate800` | `--cnvs-base-palette-slate-800` | `system.color.accent.muted.default` | `system.color.fg.muted.strong ` | `system.color.border.input.hover` |
| `colors.licorice600` | `base.slate900` | `--cnvs-base-palette-slate-900` | | | |
| `colors.blackPepper100` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | | | |
| `colors.blackPepper200` | `base.neutral700` | `--cnvs-base-palette-neutral-700` | | | |
| `colors.blackPepper300` | `base.neutral900` | `--cnvs-base-palette-neutral-900` | | `system.color.fg.default` | |
| `colors.blackPepper400` | `base.neutral950` | `--cnvs-base-palette-neutral-950` | `system.color.surface.contrast.default ` | `system.color.fg.strong` | `system.color.border.contrast.default` |
| `colors.blackPepper500` | `base.neutral975` | `--cnvs-base-palette-neutral-975` | `system.color.surface.contrast.strong` | `system.color.fg.stronger` | `system.color.border.contrast.strong` |
| `colors.blackPepper600` | `base.neutral1000` | `--cnvs-base-palette-neutral-1000` | | | |
| `colors.frenchVanilla100` | `base.neutral0` | `--cnvs-base-palette-neutral-0` | `system.color.surface.default` | `system.color.fg.inverse` | `system.color.border.inverse` |
| `colors.frenchVanilla200` | `base.neutral100` | `--cnvs-base-palette-neutral-100` | | | |
| `colors.frenchVanilla300` | `base.neutral200` | `--cnvs-base-palette-neutral-200` | | | |
| `colors.frenchVanilla400` | `base.neutral300` | `--cnvs-base-palette-neutral-300` | | | |
| `colors.frenchVanilla500` | `base.neutral400` | `--cnvs-base-palette-neutral-400` | | | |
| `colors.frenchVanilla600` | `base.neutral500` | `--cnvs-base-palette-neutral-500` | | | |
| `colors.soap100` | `base.slate25` | `--cnvs-base-palette-slate-25` | `system.color.surface.raised` | | |
| `colors.soap200` | `base.slate50` | `--cnvs-base-palette-slate-50` | `system.color.surface.alt.default` | | |
| `colors.soap300` | `base.slate100` | `--cnvs-base-palette-slate-100` | `system.color.surface.alt.default` | `system.color.border.input.inverse` | |
| `colors.soap400` | `base.slate200` | `--cnvs-base-palette-slate-200` | `system.color.surface.alt.default` | `system.color.border.default` | |
| `colors.soap500` | `base.slate300` | `--cnvs-base-palette-slate-300` | `system.color.surface.alt.default` | `system.color.border.strong` | |
| `colors.soap600` | `base.slate300` | `--cnvs-base-palette-slate-300` | | | |
| `colors.coconut100` | `base.coconut100` (deprecated) | `--cnvs-base-palette-coconut-100` | | | |
| `colors.coconut200` | `base.coconut200` (deprecated) | `--cnvs-base-palette-coconut-200` | | | |
| `colors.coconut300` | `base.coconut300` (deprecated) | `--cnvs-base-palette-coconut-300` | | | |
| `colors.coconut400` | `base.coconut400` (deprecated) | `--cnvs-base-palette-coconut-400` | | | |
| `colors.coconut500` | `base.coconut500` (deprecated) | `--cnvs-base-palette-coconut-500` | | | |
| `colors.coconut600` | `base.coconut600` (deprecated) | `--cnvs-base-palette-coconut-600` | | | |
| `colors.cappuccino100` | `base.cappuccino100` (deprecated) | `--cnvs-base-palette-cappuccino-100` | | | |
| `colors.cappuccino200` | `base.cappuccino200` (deprecated) | `--cnvs-base-palette-cappuccino-200` | | | |
| `colors.cappuccino300` | `base.cappuccino300` (deprecated) | `--cnvs-base-palette-cappuccino-300` | | | |
| `colors.cappuccino400` | `base.cappuccino400` (deprecated) | `--cnvs-base-palette-cappuccino-400` | | | |
| `colors.cappuccino500` | `base.cappuccino500` (deprecated) | `--cnvs-base-palette-cappuccino-500` | | | |
| `colors.cappuccino600` | `base.cappuccino600` (deprecated) | `--cnvs-base-palette-cappuccino-600` | | | |
| `colors.dragonFruit100` | `base.purple25` | `--cnvs-base-palette-purple-25` | | | |
| `colors.dragonFruit200` | `base.purple100` | `--cnvs-base-palette-purple-100` | | | |
| `colors.dragonFruit300` | `base.indigo500` | `--cnvs-base-palette-indigo-500` | | | |
| `colors.dragonFruit400` | `base.indigo600` | `--cnvs-base-palette-indigo-600` | | | |
| `colors.dragonFruit500` | `base.indigo700` | `--cnvs-base-palette-indigo-700` | | | |
| `colors.dragonFruit600` | `base.indigo800` | `--cnvs-base-palette-indigo-800` | | | |
## Brand Color Migration
Brand colors move from the Emotion theme object to direct CSS variables:
| Old Token | v3 Token | v4 New Token | CSS Variable |
| ------------------------------------------ | :-------------------------: | :-----------------------: | --------------------------- |
| `theme.canvas.palette.primary.lightest` | `brand.primary.lightest` | `brand.primary25` | `--cnvs-brand-primary-25` |
| `theme.canvas.palette.primary.light` | `brand.primary.light` | `brand.primary200` | `--cnvs-brand-primary-200` |
| `theme.canvas.palette.primary.main` | `brand.primary.base` | `brand.primary600` | `--cnvs-brand-primary-600` |
| `theme.canvas.palette.primary.dark` | `brand.primary.dark` | `brand.primary700` | `--cnvs-brand-primary-700` |
| `theme.canvas.palette.primary.darkest` | `brand.primary.darkest` | `brand.primary800` | `--cnvs-brand-primary-800` |
| `theme.canvas.palette.primary.contrast` | `brand.primary.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.error.lightest` | `brand.error.lightest` | `brand.critical25` | `--cnvs-brand-error-25` |
| `theme.canvas.palette.error.light` | `brand.error.light` | `brand.critical200` | `--cnvs-brand-error-200` |
| `theme.canvas.palette.error.main` | `brand.error.base` | `brand.critical600` | `--cnvs-brand-error-600` |
| `theme.canvas.palette.error.dark` | `brand.error.dark` | `brand.critical700` | `--cnvs-brand-error-700` |
| `theme.canvas.palette.error.darkest` | `brand.error.darkest` | `brand.critical800` | `--cnvs-brand-error-800` |
| `theme.canvas.palette.error.contrast` | `brand.error.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.alert.lightest` | `brand.alert.lightest` | `brand.caution.5` | `--cnvs-brand-alert-25` |
| `theme.canvas.palette.alert.light` | `brand.alert.light` | `brand.caution200` | `--cnvs-brand-alert-200` |
| `theme.canvas.palette.alert.main` | `brand.alert.base` | `brand.caution600` | `--cnvs-brand-alert-600` |
| `theme.canvas.palette.alert.dark` | `brand.alert.dark` | `brand.caution700` | `--cnvs-brand-alert-700` |
| `theme.canvas.palette.alert.darkest` | `brand.alert.darkest` | `brand.caution800` | `--cnvs-brand-alert-800` |
| `theme.canvas.palette.alert.contrast` | `brand.alert.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.success.lightest` | `brand.success.lightest` | `brand.positive25` | `--cnvs-brand-success-25` |
| `theme.canvas.palette.success.light` | `brand.success.light` | `brand.positive200` | `--cnvs-brand-success-200` |
| `theme.canvas.palette.success.main` | `brand.success.base` | `brand.positive600` | `--cnvs-brand-success-600` |
| `theme.canvas.palette.success.dark` | `brand.success.dark` | `brand.positive700` | `--cnvs-brand-success-700` |
| `theme.canvas.palette.success.darkest` | `brand.success.darkest` | `brand.positive800` | `--cnvs-brand-success-800` |
| `theme.canvas.palette.success.contrast` | `brand.success.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.neutral.lightest` | `brand.neutral.lightest` | `brand.neutral25` | `--cnvs-brand-neutral-25` |
| `theme.canvas.palette.neutral.light` | `brand.neutral.light` | `brand.neutral200` | `--cnvs-brand-neutral-200` |
| `theme.canvas.palette.neutral.main` | `brand.neutral.base` | `brand.neutral600` | `--cnvs-brand-neutral-600` |
| `theme.canvas.palette.neutral.dark` | `brand.neutral.dark` | `brand.neutral700` | `--cnvs-brand-neutral-700` |
| `theme.canvas.palette.neutral.darkest` | `brand.neutral.darkest` | `brand.neutral800` | `--cnvs-brand-neutral-800` |
| `theme.canvas.palette.neutral.contrast` | `brand.neutral.accent` | `system.color.fg.inverse` | `--cnvs-brand-fg-inverse` |
| `theme.canvas.palette.common.focusOutline` | `brand.common.focusOutline` | `brand.common.focus` | `--cnvs-brand-common-focus` |
## System Color Usage Guide (Recommended)
**System color tokens are organized into semantic "blocks" that represent their intended use in your
UI. Instead of referencing raw base colors, use these system tokens to ensure your application is
themeable, understandable, and consistent.**
- **Surface/background (`system.color.surface.*`, `system.color.brand.surface.*`,
`system.color.accent.*`)**: For all surface and container backgrounds, including pages, cards,
banners, and input fields. Choose the appropriate variant based on the visual prominence and
interaction state (default, hover, active, disabled).
- **Foreground (`system.color.fg.*`, `system.color.brand.fg.*`)**: For text and icon colors. Use
variants for body text, headings, links, disabled states, and inverse (light-on-dark) content.
- **Border (`system.color.border.*`, `system.color.brand.focus.*`)**: For outlines, dividers, and
input borders. Select the variant that matches the required emphasis or interaction state.
### Background colors
| Use Case | System Token (v4) | Old Token / React tokens | Example Usage |
| -------------------------------------- | :-------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------- |
| **Background Colors** | | | |
| Main page background | `system.color.surface.default` | `colors.frenchVanilla100` <br/> `inputColors.background` <br/> `commonColors.background` | Page layout base background |
| Disabled elements | `system.color.brand.surface.primary.default` | `colors.blueberry200` | Disabled primary buttons |
| Brand default background