From 650135502d3a13e083a991b684a057567d744ba8 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Wed, 13 Sep 2023 16:03:04 -0700
Subject: [PATCH 01/19] Update gray scale and add black alpha scale

---
 polaris-tokens/src/colors-experimental.ts | 59 +++++++++++++++--------
 1 file changed, 39 insertions(+), 20 deletions(-)

diff --git a/polaris-tokens/src/colors-experimental.ts b/polaris-tokens/src/colors-experimental.ts
index 3f0d08bc7d3..44458fb20d3 100644
--- a/polaris-tokens/src/colors-experimental.ts
+++ b/polaris-tokens/src/colors-experimental.ts
@@ -17,30 +17,30 @@ type ColorScale =
   | '16';
 
 type Color = {
-  [Scale in ColorScale]: string;
+  [Scale in ColorScale]: `rgba(${number}, ${number}, ${number}, 1)`;
 };
 
-type ColorWithAlpha = {
-  [Scale in ColorScale]: (alpha?: string) => string;
+type ColorAlpha = {
+  [Scale in ColorScale]: `rgba(${number}, ${number}, ${number}, ${number})`;
 };
 
-export const gray: ColorWithAlpha = {
-  '1': (alpha = '1') => `rgba(255, 255, 255, ${alpha})`,
-  '2': (alpha = '1') => `rgba(253, 253, 253, ${alpha})`,
-  '3': (alpha = '1') => `rgba(250, 250, 250, ${alpha})`,
-  '4': (alpha = '1') => `rgba(247, 247, 247, ${alpha})`,
-  '5': (alpha = '1') => `rgba(243, 243, 243, ${alpha})`,
-  '6': (alpha = '1') => `rgba(241, 241, 241, ${alpha})`,
-  '7': (alpha = '1') => `rgba(235, 235, 235, ${alpha})`,
-  '8': (alpha = '1') => `rgba(227, 227, 227, ${alpha})`,
-  '9': (alpha = '1') => `rgba(212, 212, 212, ${alpha})`,
-  '10': (alpha = '1') => `rgba(204, 204, 204, ${alpha})`,
-  '11': (alpha = '1') => `rgba(181, 181, 181, ${alpha})`,
-  '12': (alpha = '1') => `rgba(138, 138, 138, ${alpha})`,
-  '13': (alpha = '1') => `rgba(97, 97, 97, ${alpha})`,
-  '14': (alpha = '1') => `rgba(74, 74, 74, ${alpha})`,
-  '15': (alpha = '1') => `rgba(48, 48, 48, ${alpha})`,
-  '16': (alpha = '1') => `rgba(26, 26, 26, ${alpha})`,
+export const gray: Color = {
+  1: 'rgba(255, 255, 255, 1)',
+  2: 'rgba(253, 253, 253, 1)',
+  3: 'rgba(250, 250, 250, 1)',
+  4: 'rgba(247, 247, 247, 1)',
+  5: 'rgba(243, 243, 243, 1)',
+  6: 'rgba(241, 241, 241, 1)',
+  7: 'rgba(235, 235, 235, 1)',
+  8: 'rgba(227, 227, 227, 1)',
+  9: 'rgba(212, 212, 212, 1)',
+  10: 'rgba(204, 204, 204, 1)',
+  11: 'rgba(181, 181, 181, 1)',
+  12: 'rgba(138, 138, 138, 1)',
+  13: 'rgba(97, 97, 97, 1)',
+  14: 'rgba(74, 74, 74, 1)',
+  15: 'rgba(48, 48, 48, 1)',
+  16: 'rgba(26, 26, 26, 1)',
 };
 
 export const azure: Color = {
@@ -270,3 +270,22 @@ export const yellow: Color = {
   '15': 'rgba(51, 46, 0, 1)',
   '16': 'rgba(31, 28, 0, 1)',
 };
+
+export const blackAlpha: ColorAlpha = {
+  1: 'rgba(0, 0, 0, 0)',
+  2: 'rgba(0, 0, 0, 0.01)',
+  3: 'rgba(0, 0, 0, 0.02)',
+  4: 'rgba(0, 0, 0, 0.03)',
+  5: 'rgba(0, 0, 0, 0.05)',
+  6: 'rgba(0, 0, 0, 0.06)',
+  7: 'rgba(0, 0, 0, 0.08)',
+  8: 'rgba(0, 0, 0, 0.11)',
+  9: 'rgba(0, 0, 0, 0.17)',
+  10: 'rgba(0, 0, 0, 0.20)',
+  11: 'rgba(0, 0, 0, 0.29)',
+  12: 'rgba(0, 0, 0, 0.46)',
+  13: 'rgba(0, 0, 0, 0.62)',
+  14: 'rgba(0, 0, 0, 0.71)',
+  15: 'rgba(0, 0, 0, 0.81)',
+  16: 'rgba(0, 0, 0, 0.90)',
+};

From 73ef1feb5e295b39bf1304dd639e611ee219bc2d Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Wed, 13 Sep 2023 16:05:30 -0700
Subject: [PATCH 02/19] Find and replace opaque gray scale references

---
 polaris-tokens/src/themes/light-uplift.ts | 124 +++++++++++-----------
 polaris-tokens/src/token-groups/color.ts  |  14 +--
 2 files changed, 69 insertions(+), 69 deletions(-)

diff --git a/polaris-tokens/src/themes/light-uplift.ts b/polaris-tokens/src/themes/light-uplift.ts
index 2e5eb408cd7..59414293eba 100644
--- a/polaris-tokens/src/themes/light-uplift.ts
+++ b/polaris-tokens/src/themes/light-uplift.ts
@@ -35,37 +35,37 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
     'shadow-2xl': {value: '0px 20px 20px -8px rgba(0, 0, 0, 0.28)'},
   },
   color: {
-    'color-bg-inverse': {value: colors.gray[16]()},
-    'color-bg-inset-strong': {value: colors.gray[15]()},
-    'color-bg-inverse-hover': {value: colors.gray[14]()},
-    'color-bg-inverse-active': {value: colors.gray[13]()},
-    'color-bg-strong-hover': {value: colors.gray[9]()},
-    'color-bg-strong-active': {value: colors.gray[10]()},
-    'color-bg-strong': {value: colors.gray[8]()},
-    'color-bg-subdued-active': {value: colors.gray[7]()},
-    'color-bg-disabled': {value: colors.gray[7]()},
-    'color-bg-interactive-disabled': {value: colors.gray[7]()},
-    'color-bg-app': {value: colors.gray[6]()},
-    'color-bg-app-hover': {value: colors.gray[2]()},
-    'color-bg-app-selected': {value: colors.gray[3]()},
-    'color-bg-active': {value: colors.gray[4]()},
-    'color-bg-subdued-hover': {value: colors.gray[6]()},
-    'color-bg-inset': {value: colors.gray[6]()},
-    'color-bg-hover': {value: colors.gray[3]()},
-    'color-bg-subdued': {value: colors.gray[4]()},
-    'color-bg-input': {value: colors.gray[1]()},
-    'color-bg': {value: colors.gray[1]()},
-    'color-bg-primary-active': {value: colors.gray[16]()},
-    'color-bg-primary-hover': {value: colors.gray[16]()},
-    'color-bg-primary': {value: colors.gray[15]()},
+    'color-bg-inverse': {value: colors.gray[16]},
+    'color-bg-inset-strong': {value: colors.gray[15]},
+    'color-bg-inverse-hover': {value: colors.gray[14]},
+    'color-bg-inverse-active': {value: colors.gray[13]},
+    'color-bg-strong-hover': {value: colors.gray[9]},
+    'color-bg-strong-active': {value: colors.gray[10]},
+    'color-bg-strong': {value: colors.gray[8]},
+    'color-bg-subdued-active': {value: colors.gray[7]},
+    'color-bg-disabled': {value: colors.gray[7]},
+    'color-bg-interactive-disabled': {value: colors.gray[7]},
+    'color-bg-app': {value: colors.gray[6]},
+    'color-bg-app-hover': {value: colors.gray[2]},
+    'color-bg-app-selected': {value: colors.gray[3]},
+    'color-bg-active': {value: colors.gray[4]},
+    'color-bg-subdued-hover': {value: colors.gray[6]},
+    'color-bg-inset': {value: colors.gray[6]},
+    'color-bg-hover': {value: colors.gray[3]},
+    'color-bg-subdued': {value: colors.gray[4]},
+    'color-bg-input': {value: colors.gray[1]},
+    'color-bg': {value: colors.gray[1]},
+    'color-bg-primary-active': {value: colors.gray[16]},
+    'color-bg-primary-hover': {value: colors.gray[16]},
+    'color-bg-primary': {value: colors.gray[15]},
     'color-bg-success-strong': {value: colors.green[12]},
     'color-bg-success': {value: colors.green[3]},
-    'color-bg-primary-subdued-active': {value: colors.gray[6]()},
+    'color-bg-primary-subdued-active': {value: colors.gray[6]},
     'color-bg-success-subdued': {value: colors.green[3]},
-    'color-bg-primary-subdued-hover': {value: colors.gray[7]()},
+    'color-bg-primary-subdued-hover': {value: colors.gray[7]},
     'color-bg-success-subdued-hover': {value: colors.green[5]},
-    'color-bg-primary-subdued': {value: colors.gray[8]()},
-    'color-bg-primary-subdued-selected': {value: colors.gray[6]()},
+    'color-bg-primary-subdued': {value: colors.gray[8]},
+    'color-bg-primary-subdued-selected': {value: colors.gray[6]},
     'color-bg-critical-strong-active': {value: colors.red[14]},
     'color-bg-critical-strong-hover': {value: colors.red[13]},
     'color-bg-critical-strong': {value: colors.red[12]},
@@ -83,13 +83,13 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
     'color-bg-info': {value: colors.azure[4]},
     'color-bg-info-subdued': {value: colors.azure[3]},
     'color-bg-info-subdued-hover': {value: colors.azure[4]},
-    'color-bg-interactive-active': {value: colors.gray[14]()},
-    'color-bg-interactive-hover': {value: colors.gray[15]()},
-    'color-bg-interactive': {value: colors.gray[16]()},
-    'color-bg-interactive-subdued-active': {value: colors.gray[6]()},
-    'color-bg-interactive-subdued-hover': {value: colors.gray[7]()},
-    'color-bg-interactive-subdued': {value: colors.gray[8]()},
-    'color-bg-interactive-selected': {value: colors.gray[6]()},
+    'color-bg-interactive-active': {value: colors.gray[14]},
+    'color-bg-interactive-hover': {value: colors.gray[15]},
+    'color-bg-interactive': {value: colors.gray[16]},
+    'color-bg-interactive-subdued-active': {value: colors.gray[6]},
+    'color-bg-interactive-subdued-hover': {value: colors.gray[7]},
+    'color-bg-interactive-subdued': {value: colors.gray[8]},
+    'color-bg-interactive-selected': {value: colors.gray[6]},
     'color-bg-warning': {value: colors.orange[7]},
     'color-bg-magic-strong': {value: colors.purple[12]},
     'color-bg-magic-hover': {value: colors.purple[7]},
@@ -98,17 +98,17 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
     'color-bg-magic-subdued-hover': {value: colors.purple[4]},
     'color-bg-magic-subdued-active': {value: colors.purple[6]},
     'color-bg-magic-subdued': {value: colors.purple[3]},
-    'color-border-input-hover': {value: colors.gray[13]()},
-    'color-border-inverse': {value: colors.gray[13]()},
-    'color-border-strong-hover': {value: colors.gray[11]()},
-    'color-border-input': {value: colors.gray[12]()},
-    'color-border-hover': {value: colors.gray[10]()},
-    'color-border-strong': {value: colors.gray[10]()},
-    'color-border': {value: colors.gray[8]()},
-    'color-border-disabled': {value: colors.gray[7]()},
-    'color-border-subdued': {value: colors.gray[7]()},
-    'color-border-interactive-disabled': {value: colors.gray[7]()},
-    'color-border-primary': {value: colors.gray[8]()},
+    'color-border-input-hover': {value: colors.gray[13]},
+    'color-border-inverse': {value: colors.gray[13]},
+    'color-border-strong-hover': {value: colors.gray[11]},
+    'color-border-input': {value: colors.gray[12]},
+    'color-border-hover': {value: colors.gray[10]},
+    'color-border-strong': {value: colors.gray[10]},
+    'color-border': {value: colors.gray[8]},
+    'color-border-disabled': {value: colors.gray[7]},
+    'color-border-subdued': {value: colors.gray[7]},
+    'color-border-interactive-disabled': {value: colors.gray[7]},
+    'color-border-primary': {value: colors.gray[8]},
     'color-border-success': {value: colors.green[5]},
     'color-border-success-subdued': {value: colors.green[5]},
     'color-border-critical-active': {value: colors.red[11]},
@@ -126,14 +126,14 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
     'color-border-interactive-subdued': {value: colors.blue[13]},
     'color-border-magic-strong': {value: colors.purple[12]},
     'color-border-magic': {value: colors.purple[10]},
-    'color-icon-hover': {value: colors.gray[15]()},
-    'color-icon': {value: colors.gray[14]()},
-    'color-icon-subdued': {value: colors.gray[12]()},
-    'color-icon-disabled': {value: colors.gray[10]()},
-    'color-icon-interactive-disabled': {value: colors.gray[10]()},
-    'color-icon-inverse': {value: colors.gray[8]()},
-    'color-icon-on-color': {value: colors.gray[1]()},
-    'color-icon-primary': {value: colors.gray[16]()},
+    'color-icon-hover': {value: colors.gray[15]},
+    'color-icon': {value: colors.gray[14]},
+    'color-icon-subdued': {value: colors.gray[12]},
+    'color-icon-disabled': {value: colors.gray[10]},
+    'color-icon-interactive-disabled': {value: colors.gray[10]},
+    'color-icon-inverse': {value: colors.gray[8]},
+    'color-icon-on-color': {value: colors.gray[1]},
+    'color-icon-primary': {value: colors.gray[16]},
     'color-icon-success': {value: colors.green[12]},
     'color-icon-critical': {value: colors.red[11]},
     'color-icon-caution': {value: colors.yellow[11]},
@@ -144,17 +144,17 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
     'color-icon-interactive': {value: colors.blue[13]},
     'color-icon-interactive-inverse': {value: colors.blue[8]},
     'color-icon-magic': {value: colors.purple[13]},
-    'color-text': {value: colors.gray[15]()},
-    'color-text-subdued': {value: colors.gray[13]()},
-    'color-text-disabled': {value: colors.gray[11]()},
-    'color-text-interactive-disabled': {value: colors.gray[10]()},
-    'color-text-inverse-subdued': {value: colors.gray[10]()},
-    'color-text-inverse': {value: colors.gray[8]()},
-    'color-text-on-color': {value: colors.gray[1]()},
+    'color-text': {value: colors.gray[15]},
+    'color-text-subdued': {value: colors.gray[13]},
+    'color-text-disabled': {value: colors.gray[11]},
+    'color-text-interactive-disabled': {value: colors.gray[10]},
+    'color-text-inverse-subdued': {value: colors.gray[10]},
+    'color-text-inverse': {value: colors.gray[8]},
+    'color-text-on-color': {value: colors.gray[1]},
     'color-text-success-strong': {value: colors.green[15]},
     'color-text-success': {value: colors.green[15]},
-    'color-text-primary': {value: colors.gray[14]()},
-    'color-text-primary-hover': {value: colors.gray[14]()},
+    'color-text-primary': {value: colors.gray[14]},
+    'color-text-primary-hover': {value: colors.gray[14]},
     'color-text-critical-strong': {value: colors.red[14]},
     'color-text-critical-active': {value: colors.red[16]},
     'color-text-critical': {value: colors.red[14]},
diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 60890d87213..ab3e2ffb170 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -771,25 +771,25 @@ export const color: {
     description: '',
   },
   'color-bg-primary-disabled-experimental': {
-    value: colorsExperimental.gray[9](),
+    value: colorsExperimental.gray[9],
     description: '',
   },
   'color-bg-secondary-experimental': {
-    value: colorsExperimental.gray[5](),
+    value: colorsExperimental.gray[5],
     description: '',
   },
   'color-bg-input-hover-experimental': {
-    value: colorsExperimental.gray[3](),
+    value: colorsExperimental.gray[3],
     description: '',
   },
   'color-border-input-active-experimental': {
-    value: colorsExperimental.gray[16](),
+    value: colorsExperimental.gray[16],
   },
   'color-border-critical-strong-experimental': {
     value: colorsExperimental.red[14],
   },
   'color-bg-input-active-experimental': {
-    value: colorsExperimental.gray[4](),
+    value: colorsExperimental.gray[4],
     description: '',
   },
   'color-bg-transparent-experimental': {
@@ -873,11 +873,11 @@ export const color: {
     description: '',
   },
   'color-avatar-background-experimental': {
-    value: colorsExperimental.gray[11](),
+    value: colorsExperimental.gray[11],
     description: '',
   },
   'color-avatar-color-experimental': {
-    value: colorsExperimental.gray[1](),
+    value: colorsExperimental.gray[1],
     description: '',
   },
   'color-avatar-style-one-background-experimental': {

From 9138dd78f4e24becae1a1ea917d45a8ea6473f10 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Wed, 13 Sep 2023 16:06:19 -0700
Subject: [PATCH 03/19] Update transparent gray scale references to use
 blackAlpha scale

---
 polaris-tokens/src/token-groups/color.ts | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index ab3e2ffb170..0e37a174162 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -767,7 +767,7 @@ export const color: {
   },
   // Experimental tokens
   'color-bg-backdrop-experimental': {
-    value: colorsExperimental.gray[16]('0.75'),
+    value: colorsExperimental.blackAlpha[14],
     description: '',
   },
   'color-bg-primary-disabled-experimental': {
@@ -793,35 +793,35 @@ export const color: {
     description: '',
   },
   'color-bg-transparent-experimental': {
-    value: colorsExperimental.gray[16]('0'),
+    value: colorsExperimental.blackAlpha[1],
     description: '',
   },
   'color-bg-transparent-subdued-experimental': {
-    value: colorsExperimental.gray[16]('0.07'),
+    value: colorsExperimental.blackAlpha[7],
     description: '',
   },
   'color-bg-transparent-hover-experimental': {
-    value: colorsExperimental.gray[16]('0.05'),
+    value: colorsExperimental.blackAlpha[5],
     description: '',
   },
   'color-bg-transparent-active-experimental': {
-    value: colorsExperimental.gray[16]('0.07'),
+    value: colorsExperimental.blackAlpha[7],
     description: '',
   },
   'color-bg-transparent-disabled-experimental': {
-    value: colorsExperimental.gray[16]('0.04'),
+    value: colorsExperimental.blackAlpha[5],
     description: '',
   },
   'color-bg-transparent-secondary-disabled-experimental': {
-    value: colorsExperimental.gray[16]('0.08'),
+    value: colorsExperimental.blackAlpha[7],
     description: '',
   },
   'color-bg-transparent-primary-disabled-experimental': {
-    value: colorsExperimental.gray[16]('0.18'),
+    value: colorsExperimental.blackAlpha[9],
     description: '',
   },
   'color-bg-transparent-primary-experimental': {
-    value: colorsExperimental.gray[16]('0.60'),
+    value: colorsExperimental.blackAlpha[13],
     description: '',
   },
   'color-bg-success-strong-hover-experimental': {

From cdcba5d9e9f324db2eddeeba1aea24dc47eb0804 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Wed, 13 Sep 2023 16:30:48 -0700
Subject: [PATCH 04/19] Add changeset entry

---
 .changeset/chatty-dryers-sneeze.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/chatty-dryers-sneeze.md

diff --git a/.changeset/chatty-dryers-sneeze.md b/.changeset/chatty-dryers-sneeze.md
new file mode 100644
index 00000000000..0bab0246919
--- /dev/null
+++ b/.changeset/chatty-dryers-sneeze.md
@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-tokens': minor
+---
+
+Updated private primitive `colors`

From 7b19898b66bbb92aaf17d438ff4b693886269293 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Thu, 14 Sep 2023 08:20:52 -0700
Subject: [PATCH 05/19] Update polaris-tokens/src/token-groups/color.ts

Co-authored-by: Sara Hill <sara.hill@shopify.com>
---
 polaris-tokens/src/token-groups/color.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 0e37a174162..0d1429f30e0 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -805,7 +805,7 @@ export const color: {
     description: '',
   },
   'color-bg-transparent-active-experimental': {
-    value: colorsExperimental.blackAlpha[7],
+    value: colorsExperimental.blackAlpha[6],
     description: '',
   },
   'color-bg-transparent-disabled-experimental': {

From 1508b183c6b6c3099fe0b87b94ab1b07a76797de Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Thu, 14 Sep 2023 09:52:37 -0700
Subject: [PATCH 06/19] Initial add new semantic color tokens

---
 polaris-tokens/src/token-groups/color.ts | 164 ++++++++++++++++++++++-
 1 file changed, 161 insertions(+), 3 deletions(-)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 0d1429f30e0..9b8148def29 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -68,7 +68,14 @@ export type ColorBackgroundAlias =
   | 'bg-success-subdued-active'
   | 'bg-success-subdued-hover'
   | 'bg-warning'
-  | ColorBackgroundAliasExperimental;
+  | ColorBackgroundAliasExperimental
+  /**
+   * Conceptual and component specific fills.
+   * TODO: Determine if we should create a separate
+   * type alias (e.g. `ColorComponentBackgroundAlias`) and
+   * union it here in `ColorFillAlias`.
+   */
+  | 'nav-bg';
 
 export type ColorBorderAlias =
   | 'border'
@@ -99,7 +106,86 @@ export type ColorBorderAlias =
   | 'border-subdued'
   | 'border-success'
   | 'border-success-subdued'
-  | ColorBorderAliasExperimental;
+  | ColorBorderAliasExperimental
+  /**
+   * Conceptual and component specific fills.
+   * TODO: Determine if we should create a separate
+   * type alias (e.g. `ColorComponentBorderAlias`) and
+   * union it here in `ColorFillAlias`.
+   */
+  | 'input-border'
+  | 'input-border-hover'
+  | 'input-border-active';
+
+export type ColorFillAlias =
+  | 'fill'
+  | 'fill-hover'
+  | 'fill-active'
+  | 'fill-selected'
+  | 'fill-disabled'
+  | 'fill-secondary'
+  | 'fill-secondary-hover'
+  | 'fill-secondary-active'
+  | 'fill-tertiary'
+  | 'fill-tertiary-hover'
+  | 'fill-tertiary-active'
+  | 'fill-brand'
+  | 'fill-brand-hover'
+  | 'fill-brand-active'
+  | 'fill-brand-selected'
+  | 'fill-brand-disabled'
+  | 'fill-emphasis'
+  | 'fill-emphasis-hover'
+  | 'fill-emphasis-active'
+  | 'fill-success'
+  | 'fill-success-hover'
+  | 'fill-success-active'
+  | 'fill-success-secondary'
+  | 'fill-critical'
+  | 'fill-critical-hover'
+  | 'fill-critical-active'
+  | 'fill-critical-selected'
+  | 'fill-critical-secondary'
+  | 'fill-caution'
+  | 'fill-caution-hover'
+  | 'fill-caution-active'
+  | 'fill-caution-secondary'
+  | 'fill-info'
+  | 'fill-info-hover'
+  | 'fill-info-active'
+  | 'fill-info-secondary'
+  | 'fill-warning'
+  | 'fill-warning-hover'
+  | 'fill-warning-active'
+  | 'fill-warning-secondary'
+  | 'fill-magic'
+  | 'fill-magic-secondary'
+  | 'fill-magic-secondary-hover'
+  | 'fill-magic-secondary-active'
+  | 'fill-inverse'
+  | 'fill-inverse-hover'
+  | 'fill-inverse-active'
+  | 'fill-transparent'
+  | 'fill-transparent-hover'
+  | 'fill-transparent-active'
+  | 'fill-transparent-selected'
+  | 'fill-transparent-secondary'
+  | 'fill-transparent-secondary-hover'
+  | 'fill-transparent-secondary-active'
+  /**
+   * Conceptual and component specific fills.
+   * TODO: Determine if we should create a separate
+   * type alias (e.g. `ColorComponentFillAlias`) and
+   * union it here in `ColorFillAlias`.
+   */
+  | 'avatar-fill'
+  | 'avatar-one-fill'
+  | 'avatar-two-fill'
+  | 'avatar-three-fill'
+  | 'avatar-four-fill'
+  | 'avatar-five-fill'
+  | 'video-thumbnail-play-button-fill'
+  | 'video-thumbnail-play-button-fill-hover';
 
 export type ColorIconAlias =
   | 'icon'
@@ -121,7 +207,76 @@ export type ColorIconAlias =
   | 'icon-subdued'
   | 'icon-success'
   | 'icon-warning'
-  | ColorIconAliasExperimental;
+  | ColorIconAliasExperimental
+  /**
+   * Conceptual and component specific fills.
+   * TODO: Determine if we should create a separate
+   * type alias (e.g. `ColorComponentIconAlias`) and
+   * union it here in `ColorFillAlias`.
+   */
+  | 'radio-button-icon-disabled'
+  | 'checkbox-icon-disabled';
+
+export type ColorLinkAlias =
+  | 'link'
+  | 'link-hover'
+  | 'link-active'
+  | 'link-inverse';
+
+export type ColorSurfaceAlias =
+  | 'surface'
+  | 'surface-hover'
+  | 'surface-active'
+  | 'surface-selected'
+  | 'surface-disabled'
+  | 'surface-secondary'
+  | 'surface-secondary-hover'
+  | 'surface-secondary-active'
+  | 'surface-secondary-selected'
+  | 'surface-tertiary'
+  | 'surface-tertiary-hover'
+  | 'surface-tertiary-active'
+  | 'surface-brand'
+  | 'surface-brand-hover'
+  | 'surface-brand-active'
+  | 'surface-brand-selected'
+  | 'surface-info'
+  | 'surface-info-hover'
+  | 'surface-info-active'
+  | 'surface-success'
+  | 'surface-success-hover'
+  | 'surface-success-active'
+  | 'surface-caution'
+  | 'surface-caution-hover'
+  | 'surface-caution-active'
+  | 'surface-critical'
+  | 'surface-critical-hover'
+  | 'surface-critical-active'
+  | 'surface-critical'
+  | 'surface-critical-hover'
+  | 'surface-critical-active'
+  | 'surface-magic'
+  | 'surface-magic-hover'
+  | 'surface-magic-active'
+  | 'surface-emphasis'
+  | 'surface-emphasis-hover'
+  | 'surface-emphasis-active'
+  | 'surface-inverse'
+  /**
+   * Conceptual and component specific fills.
+   * TODO: Determine if we should create a separate
+   * type alias (e.g. `ColorComponentIconAlias`) and
+   * union it here in `ColorFillAlias`.
+   */
+  | 'input-surface'
+  | 'input-surface-hover'
+  | 'input-surface-active'
+  | 'nav-surface'
+  | 'nav-surface-hover'
+  | 'nav-surface-active'
+  | 'nav-surface-selected'
+  | 'radio-button-surface-disabled'
+  | 'checkbox-surface-disabled';
 
 export type ColorTextAlias =
   | 'text'
@@ -206,7 +361,10 @@ type ColorAvatarAliasExperimental = Experimental<
 export type ColorTokenName =
   | `color-${ColorBackgroundAlias}`
   | `color-${ColorBorderAlias}`
+  | `color-${ColorFillAlias}`
   | `color-${ColorIconAlias}`
+  | `color-${ColorLinkAlias}`
+  | `color-${ColorSurfaceAlias}`
   | `color-${ColorTextAlias}`
   | `color-${ColorAvatarAliasExperimental}`;
 

From 99643da2c30f13e75150a2e00baf4b2d829f6a06 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Thu, 14 Sep 2023 10:33:40 -0700
Subject: [PATCH 07/19] Update comments

---
 polaris-tokens/src/token-groups/color.ts | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 9b8148def29..00eb42e7077 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -70,10 +70,10 @@ export type ColorBackgroundAlias =
   | 'bg-warning'
   | ColorBackgroundAliasExperimental
   /**
-   * Conceptual and component specific fills.
+   * Conceptual and component specific backgrounds.
    * TODO: Determine if we should create a separate
    * type alias (e.g. `ColorComponentBackgroundAlias`) and
-   * union it here in `ColorFillAlias`.
+   * union it here in `ColorBackgroundAlias`.
    */
   | 'nav-bg';
 
@@ -108,10 +108,10 @@ export type ColorBorderAlias =
   | 'border-success-subdued'
   | ColorBorderAliasExperimental
   /**
-   * Conceptual and component specific fills.
+   * Conceptual and component specific borders.
    * TODO: Determine if we should create a separate
    * type alias (e.g. `ColorComponentBorderAlias`) and
-   * union it here in `ColorFillAlias`.
+   * union it here in `ColorBorderAlias`.
    */
   | 'input-border'
   | 'input-border-hover'
@@ -209,10 +209,10 @@ export type ColorIconAlias =
   | 'icon-warning'
   | ColorIconAliasExperimental
   /**
-   * Conceptual and component specific fills.
+   * Conceptual and component specific icons.
    * TODO: Determine if we should create a separate
    * type alias (e.g. `ColorComponentIconAlias`) and
-   * union it here in `ColorFillAlias`.
+   * union it here in `ColorIconAlias`.
    */
   | 'radio-button-icon-disabled'
   | 'checkbox-icon-disabled';
@@ -263,10 +263,10 @@ export type ColorSurfaceAlias =
   | 'surface-emphasis-active'
   | 'surface-inverse'
   /**
-   * Conceptual and component specific fills.
+   * Conceptual and component specific surfaces.
    * TODO: Determine if we should create a separate
    * type alias (e.g. `ColorComponentIconAlias`) and
-   * union it here in `ColorFillAlias`.
+   * union it here in `ColorSurfaceAlias`.
    */
   | 'input-surface'
   | 'input-surface-hover'

From a485284f876dbf0893f3dc01151f0f7c3d6f2510 Mon Sep 17 00:00:00 2001
From: Sara Hill <sarashill22@gmail.com>
Date: Thu, 14 Sep 2023 11:13:59 -0700
Subject: [PATCH 08/19] Update color.ts with new color aliases

---
 polaris-tokens/src/token-groups/color.ts | 72 +++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 3 deletions(-)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 00eb42e7077..4d792323b4a 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -85,6 +85,7 @@ export type ColorBorderAlias =
   | 'border-critical-active'
   | 'border-critical-hover'
   | 'border-critical-subdued'
+  | 'border-critical-secondary'
   | 'border-disabled'
   | 'border-hover'
   | 'border-info'
@@ -98,14 +99,26 @@ export type ColorBorderAlias =
   | 'border-interactive-hover'
   | 'border-interactive-subdued'
   | 'border-inverse'
+  | 'border-inverse-hover'
+  | 'border-inverse-active'
   | 'border-magic'
   | 'border-magic-strong'
+  | 'border-magic-secondary'
   | 'border-primary'
   | 'border-strong'
   | 'border-strong-hover'
   | 'border-subdued'
   | 'border-success'
   | 'border-success-subdued'
+  | 'border-secondary'
+  | 'border-secondary-hover'
+  | 'border-tertiary'
+  | 'border-tertiary-hover'
+  | 'border-brand'
+  | 'border-warning'
+  | 'border-emphasis'
+  | 'border-emphasis-hover'
+  | 'border-emphasis-active'
   | ColorBorderAliasExperimental
   /**
    * Conceptual and component specific borders.
@@ -207,6 +220,16 @@ export type ColorIconAlias =
   | 'icon-subdued'
   | 'icon-success'
   | 'icon-warning'
+  | 'icon-secondary'
+  | 'icon-secondary-hover'
+  | 'icon-secondary-active'
+  | 'icon-brand'
+  | 'icon-emphasis'
+  /**
+   * check on emphasis state icons
+   */
+  | 'icon-emphasis-hover'
+  | 'icon-emphasis-active'
   | ColorIconAliasExperimental
   /**
    * Conceptual and component specific icons.
@@ -249,9 +272,9 @@ export type ColorSurfaceAlias =
   | 'surface-caution'
   | 'surface-caution-hover'
   | 'surface-caution-active'
-  | 'surface-critical'
-  | 'surface-critical-hover'
-  | 'surface-critical-active'
+  | 'surface-warning'
+  | 'surface-warning-hover'
+  | 'surface-warning-active'
   | 'surface-critical'
   | 'surface-critical-hover'
   | 'surface-critical-active'
@@ -281,12 +304,20 @@ export type ColorSurfaceAlias =
 export type ColorTextAlias =
   | 'text'
   | 'text-caution'
+  | 'text-caution-hover'
+  | 'text-caution-active'
+  | 'text-caution-on-fill'
   | 'text-caution-strong'
   | 'text-critical'
+  | 'text-critical-hover'
   | 'text-critical-active'
+  | 'text-critical-on-fill'
   | 'text-critical-strong'
   | 'text-disabled'
   | 'text-info'
+  | 'text-info-hover'
+  | 'text-info-active'
+  | 'text-info-on-fill'
   | 'text-info-strong'
   | 'text-interactive'
   | 'text-interactive-active'
@@ -294,16 +325,51 @@ export type ColorTextAlias =
   | 'text-interactive-hover'
   | 'text-interactive-inverse'
   | 'text-inverse'
+  | 'text-inverse-secondary'
   | 'text-inverse-subdued'
   | 'text-magic'
+  | 'text-magic-on-fill'
   | 'text-magic-strong'
   | 'text-on-color'
   | 'text-primary'
   | 'text-primary-hover'
   | 'text-subdued'
   | 'text-success'
+  | 'text-success-hover'
+  | 'text-success-active'
+  | 'text-success-on-fill'
   | 'text-success-strong'
   | 'text-warning-strong'
+  | 'text-warning'
+  | 'text-warning-hover'
+  | 'text-warning-active'
+  | 'text-warning-on-fill'
+  | 'text-secondary'
+  | 'text-brand'
+  | 'text-brand-hover'
+  | 'text-brand-on-fill'
+  | 'text-brand-on-fill-hover'
+  | 'text-brand-on-fill-active'
+  | 'text-brand-on-fill-disabled'
+  | 'text-emphasis'
+  | 'text-emphasis-hover'
+  | 'text-emphasis-active'
+  | 'text-emphasis-on-fill'
+  | 'text-emphasis-on-fill-hover'
+  | 'text-emphasis-on-fill-active'
+  /**
+   * Conceptual and component specific surfaces.
+   * TODO: Determine if we should create a separate
+   * type alias (e.g. `ColorComponentIconAlias`) and
+   * union it here in `ColorSurfaceAlias`.
+   */
+  | 'avatar-text-on-fill'
+  | 'avatar-one-text-on-fill'
+  | 'avatar-two-text-on-fill'
+  | 'avatar-three-text-on-fill'
+  | 'avatar-four-text-on-fill'
+  | 'avatar-five-text-on-fill'
+  | 'video-thumbnail-play-button-text-on-fill'
   | ColorTextAliasExperimental;
 
 type ColorBackgroundAliasExperimental = Experimental<

From 71d403d721931b850db1faf1e874b31bd774d804 Mon Sep 17 00:00:00 2001
From: Sara Hill <sarashill22@gmail.com>
Date: Thu, 14 Sep 2023 11:25:12 -0700
Subject: [PATCH 09/19] Update color.ts

---
 polaris-tokens/src/token-groups/color.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 4d792323b4a..f4563c8c9c6 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -225,6 +225,8 @@ export type ColorIconAlias =
   | 'icon-secondary-active'
   | 'icon-brand'
   | 'icon-emphasis'
+  | 'icon-emphasis-hover'
+  | 'icon-emphasis-active'
   /**
    * check on emphasis state icons
    */
@@ -246,6 +248,8 @@ export type ColorLinkAlias =
   | 'link-active'
   | 'link-inverse';
 
+export type ColorFocusAlias = 'focus-outline';
+
 export type ColorSurfaceAlias =
   | 'surface'
   | 'surface-hover'

From 7eff29d059fa95d7d134f067f270403d8ba4fa98 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Thu, 14 Sep 2023 11:54:44 -0700
Subject: [PATCH 10/19] Update bg-transparent-subdued to black-alpha-6

---
 polaris-tokens/src/token-groups/color.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/polaris-tokens/src/token-groups/color.ts b/polaris-tokens/src/token-groups/color.ts
index 0d1429f30e0..3e77568cbcd 100644
--- a/polaris-tokens/src/token-groups/color.ts
+++ b/polaris-tokens/src/token-groups/color.ts
@@ -797,7 +797,7 @@ export const color: {
     description: '',
   },
   'color-bg-transparent-subdued-experimental': {
-    value: colorsExperimental.blackAlpha[7],
+    value: colorsExperimental.blackAlpha[6],
     description: '',
   },
   'color-bg-transparent-hover-experimental': {

From 10885a5c60a1fdd03e48ccd4029893fd61d7caf5 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Fri, 15 Sep 2023 16:40:39 -0700
Subject: [PATCH 11/19] Initial color migration

---
 .../tests/transform.test.ts                   |  12 ++
 ...s-replace-custom-property-color.input.scss |   3 +
 ...-replace-custom-property-color.output.scss |   3 +
 .../transform.ts                              | 136 ++++++++++++++++++
 4 files changed, 154 insertions(+)
 create mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts
 create mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss
 create mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss
 create mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts

diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts
new file mode 100644
index 00000000000..d869f53384e
--- /dev/null
+++ b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts
@@ -0,0 +1,12 @@
+import {check} from '../../../utilities/check';
+
+const transform = 'v12-styles-replace-custom-property-color';
+const fixtures = ['v12-styles-replace-custom-property-color'];
+
+for (const fixture of fixtures) {
+  check(__dirname, {
+    fixture,
+    transform,
+    extension: 'scss',
+  });
+}
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss
new file mode 100644
index 00000000000..ca49c86d72a
--- /dev/null
+++ b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss
@@ -0,0 +1,3 @@
+.basic {
+  background: var(--p-color-bg);
+}
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss
new file mode 100644
index 00000000000..eaa3699c218
--- /dev/null
+++ b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss
@@ -0,0 +1,3 @@
+.basic {
+  background: var(--p-color-surface);
+}
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts
new file mode 100644
index 00000000000..91f3eb129c8
--- /dev/null
+++ b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts
@@ -0,0 +1,136 @@
+import type {FileInfo, API} from 'jscodeshift';
+
+import stylesReplaceCustomProperty from '../styles-replace-custom-property/transform';
+
+export default function transformer(fileInfo: FileInfo, _: API) {
+  return stylesReplaceCustomProperty(fileInfo, _, {replacementMaps});
+}
+
+const replacementMaps = {
+  '/.+/': {
+    '--p-color-bg': '--p-color-surface',
+    // '--p-color-bg-hover': '--p-color-surface-hover',
+    // '--p-color-bg-active': '--p-color-surface-active',
+    // '--p-color-bg-disabled': '--p-color-surface-disabled',
+    '--p-color-bg-subdued': '--p-color-surface-secondary',
+    '--p-color-bg-subdued-hover': '--p-color-surface-secondary-hover',
+    '--p-color-bg-subdued-active': '--p-color-surface-secondary-active',
+    '--p-color-bg-secondary-experimental': '--p-color-surface-tertiary',
+    '--p-color-bg-strong': '--p-color-fill-tertiary',
+    '--p-color-bg-strong-hover': '--p-color-fill-tertiary-hover',
+    '--p-color-bg-strong-active': '--p-color-fill-tertiary-active',
+    '--p-color-bg-input': '--p-color-input-surface',
+    '--p-color-bg-input-hover-experimental': '--p-color-input-surface-hover',
+    '--p-color-bg-input-active-experimental': '--p-color-input-surface-active',
+    // '--p-color-bg-primary': '--p-color-fill-brand',
+    // '--p-color-bg-primary-hover': '--p-color-fill-brand-hover',
+    // '--p-color-bg-primary-active': '--p-color-fill-brand-active',
+    // '--p-color-bg-primary-subdued': '--p-color-surface-brand',
+    // '--p-color-bg-primary-subdued-hover': '--p-color-surface-brand-hover',
+    // '--p-color-bg-primary-subdued-active': '--p-color-surface-brand-active',
+    // '--p-color-bg-primary-subdued-selected': '--p-color-surface-brand-selected',
+    '--p-color-bg-app-selected': '--p-color-surface-selected',
+    '--p-color-bg-success-strong': '--p-color-fill-success',
+    '--p-color-bg-success-strong-hover-experimental':
+      '--p-color-fill-success-hover',
+    '--p-color-bg-success-strong-active-experimental':
+      '--p-color-fill-success-active',
+    '--p-color-bg-success': '--p-color-fill-success-secondary',
+    '--p-color-bg-success-subdued': '--p-color-surface-success',
+    '--p-color-bg-success-subdued-hover': '--p-color-surface-success-hover',
+    '--p-color-bg-success-subdued-active': '--p-color-surface-success-active',
+    '--p-color-bg-critical-strong': '--p-color-fill-critical',
+    '--p-color-bg-critical-strong-hover': '--p-color-fill-critical-hover',
+    '--p-color-bg-critical-strong-active': '--p-color-fill-critical-active',
+    '--p-color-bg-critical': '--p-color-fill-critical-secondary',
+    '--p-color-bg-critical-subdued': '--p-color-surface-critical',
+    '--p-color-bg-critical-subdued-hover': '--p-color-surface-critical-hover',
+    '--p-color-bg-critical-subdued-active': '--p-color-surface-critical-active',
+    '--p-color-bg-caution-strong': '--p-color-fill-caution',
+    '--p-color-bg-caution': '--p-color-fill-caution-secondary',
+    '--p-color-bg-caution-subdued': '--p-color-surface-caution',
+    '--p-color-bg-caution-subdued-hover': '--p-color-surface-caution-hover',
+    '--p-color-bg-caution-subdued-active': '--p-color-surface-caution-active',
+    '--p-color-bg-info-strong': '--p-color-fill-info',
+    '--p-color-bg-info': '--p-color-fill-info-secondary',
+    '--p-color-bg-info-subdued': '--p-color-surface-info',
+    '--p-color-bg-info-subdued-hover': '--p-color-surface-info-hover',
+    '--p-color-bg-info-subdued-active': '--p-color-surface-info-active',
+    '--p-color-bg-warning-strong-experimental': '--p-color-fill-warning',
+    '--p-color-bg-warning': '--p-color-fill-warning-secondary',
+    '--p-color-bg-warning-subdued-experimental': '--p-color-surface-warning',
+    '--p-color-bg-magic-strong': '--p-color-fill-magic',
+    '--p-color-bg-magic': '--p-color-fill-magic-secondary',
+    '--p-color-bg-magic-hover': '--p-color-fill-magic-secondary-hover',
+    '--p-color-bg-magic-active': '--p-color-fill-magic-secondary-active',
+    // '--p-color-bg-magic-subdued': '--p-color-surface-magic',
+    '--p-color-bg-magic-subdued-hover': '--p-color-surface-magic-hover',
+    '--p-color-bg-inset': '--p-color-fill-secondary',
+    '--p-color-bg-inset-strong': '--p-color-fill-inverse',
+    '--p-color-bg-inverse-hover': '--p-color-fill-inverse-hover',
+    '--p-color-bg-inverse-active': '--p-color-fill-inverse-active',
+    '--p-color-bg-transparent-experimental': '--p-color-surface-transparent',
+    '--p-color-bg-transparent-hover-experimental':
+      '--p-color-fill-transparent-hover',
+    '--p-color-bg-transparent-active-experimental':
+      '--p-color-fill-transparent-active',
+    '--p-color-bg-transparent-disabled-experimental': '--p-color-fill-disabled',
+    '--p-color-bg-transparent-subdued-experimental':
+      '--p-color-fill-transparent-secondary',
+    '--p-color-bg-transparent-primary-disabled-experimental':
+      '--p-color-fill-brand-disabled',
+    '--p-color-bg-backdrop-experimental': '--p-color-backdrop-bg',
+    '--p-color-avatar-background-experimental': '--p-color-avatar-fill',
+    '--p-color-avatar-style-one-background-experimental':
+      '--p-color-avatar-one-fill',
+    '--p-color-avatar-style-two-background-experimental':
+      '--p-color-avatar-two-fill',
+    '--p-color-avatar-style-three-background-experimental':
+      '--p-color-avatar-three-fill',
+    '--p-color-avatar-style-four-background-experimental':
+      '--p-color-avatar-four-fill',
+    '--p-color-avatar-style-five-background-experimental':
+      '--p-color-avatar-five-fill',
+    '--p-color-text-subdued': '--p-color-text-secondary',
+    '--p-color-text-interactive': '--p-color-text-emphasis',
+    '--p-color-text-interactive-hover': '--p-color-text-emphasis-hover',
+    '--p-color-text-interactive-active': '--p-color-text-emphasis-active',
+    '--p-color-text-primary': '--p-color-text-brand',
+    '--p-color-text-primary-hover': '--p-color-text-brand-hover',
+    // '--p-color-text-critical-hover-experimental': '--p-color-text-critical-hover',
+    '--p-color-text-info-strong': '--p-color-text-info-on-fill',
+    // '--p-color-text-warning-experimental': '--p-color-text-warning',
+    '--p-color-text-inverse-subdued': '--p-color-text-inverse-secondary',
+    // '--p-color-text-interactive-inverse': '--p-color-link-inverse',
+    '--p-color-avatar-color-experimental': '--p-color-avatar-text-on-fill',
+    '--p-color-avatar-style-one-color-experimental':
+      '--p-color-avatar-one-text-on-fill',
+    '--p-color-avatar-style-two-color-experimental':
+      '--p-color-avatar-two-text-on-fill',
+    '--p-color-avatar-style-three-color-experimental':
+      '--p-color-avatar-three-text-on-fill',
+    '--p-color-avatar-style-four-color-experimental':
+      '--p-color-avatar-four-text-on-fill',
+    '--p-color-avatar-style-five-color-experimental':
+      '--p-color-avatar-five-text-on-fill',
+    '--p-color-icon-subdued': '--p-color-icon-secondary',
+    '--p-color-icon-interactive': '--p-color-icon-emphasis',
+    '--p-color-icon-interactive-hover': '--p-color-icon-emphasis-hover',
+    '--p-color-icon-interactive-active': '--p-color-icon-emphasis-active',
+    '--p-color-icon-primary': '--p-color-icon-brand',
+    '--p-color-border-subdued': '--p-color-border-secondary',
+    // '--p-color-border-strong': '--p-color-border-tertiary',
+    '--p-color-border-input': '--p-color-input-border',
+    '--p-color-border-input-hover': '--p-color-input-border-hover',
+    '--p-color-border-input-active-experimental':
+      '--p-color-input-border-active',
+    // '--p-color-border-interactive': '--p-color-border-emphasis',
+    '--p-color-border-interactive-hover': '--p-color-border-emphasis-hover',
+    '--p-color-border-interactive-active': '--p-color-border-emphasis-active',
+    '--p-color-border-interactive-focus': '--p-color-border-focus',
+    '--p-color-border-primary': '--p-color-border-brand',
+    '--p-color-border-critical-strong-experimental':
+      '--p-color-border-critical-secondary',
+    '--p-color-border-magic-strong': '--p-color-border-magic-secondary',
+  },
+};

From df98f90b75b630a749a3fe84d730888e8048a3f2 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Fri, 15 Sep 2023 16:43:20 -0700
Subject: [PATCH 12/19] Update color semantics

---
 polaris-tokens/src/themes/base/color.ts | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/polaris-tokens/src/themes/base/color.ts b/polaris-tokens/src/themes/base/color.ts
index ac1b6050b7e..8c34d2070e6 100644
--- a/polaris-tokens/src/themes/base/color.ts
+++ b/polaris-tokens/src/themes/base/color.ts
@@ -76,7 +76,8 @@ export type ColorBackgroundAlias =
    * type alias (e.g. `ColorComponentBackgroundAlias`) and
    * union it here in `ColorBackgroundAlias`.
    */
-  | 'nav-bg';
+  | 'nav-bg'
+  | 'backdrop-bg';
 
 export type ColorBorderAlias =
   | 'border'
@@ -89,6 +90,7 @@ export type ColorBorderAlias =
   | 'border-critical-secondary'
   | 'border-disabled'
   | 'border-hover'
+  | 'border-focus'
   | 'border-info'
   | 'border-info-subdued'
   | 'border-input'
@@ -112,9 +114,7 @@ export type ColorBorderAlias =
   | 'border-success'
   | 'border-success-subdued'
   | 'border-secondary'
-  | 'border-secondary-hover'
   | 'border-tertiary'
-  | 'border-tertiary-hover'
   | 'border-brand'
   | 'border-warning'
   | 'border-emphasis'
@@ -249,8 +249,6 @@ export type ColorLinkAlias =
   | 'link-active'
   | 'link-inverse';
 
-export type ColorFocusAlias = 'focus-outline';
-
 export type ColorSurfaceAlias =
   | 'surface'
   | 'surface-hover'
@@ -264,6 +262,7 @@ export type ColorSurfaceAlias =
   | 'surface-tertiary'
   | 'surface-tertiary-hover'
   | 'surface-tertiary-active'
+  | 'surface-transparent'
   | 'surface-brand'
   | 'surface-brand-hover'
   | 'surface-brand-active'

From aceb18c88505ed2617fadbd5b04b42cd145827dd Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Fri, 15 Sep 2023 16:44:18 -0700
Subject: [PATCH 13/19] Add net new token mappings

---
 polaris-tokens/src/themes/base/color.ts   | 303 ++++++++++++++++++++++
 polaris-tokens/src/themes/light-uplift.ts |  93 +++++++
 2 files changed, 396 insertions(+)

diff --git a/polaris-tokens/src/themes/base/color.ts b/polaris-tokens/src/themes/base/color.ts
index 8c34d2070e6..d4aec39c31a 100644
--- a/polaris-tokens/src/themes/base/color.ts
+++ b/polaris-tokens/src/themes/base/color.ts
@@ -2,6 +2,7 @@ import type {Experimental} from '../../types';
 import type {MetaTokenProperties} from '../types';
 import * as colors from '../../colors';
 import * as colorsExperimental from '../../colors-experimental';
+import {createVar as createVarName} from '../../utilities';
 
 export type ColorBackgroundAlias =
   | 'bg'
@@ -445,6 +446,304 @@ export type ColorTokenGroup = {
 export const color: {
   [TokenName in ColorTokenName]: MetaTokenProperties;
 } = {
+  // ------------------------------
+  // Net new tokens
+  // ------------------------------
+  'color-border-inverse-active': {value: colorsExperimental.gray[8]},
+  'color-border-inverse-hover': {value: colorsExperimental.gray[10]},
+  'color-border-warning': {value: colorsExperimental.orange[8]},
+  'color-checkbox-icon-disabled': {value: colorsExperimental.gray[1]},
+  'color-checkbox-surface-disabled': {value: colorsExperimental.blackAlpha[7]},
+  'color-fill-active': {value: colorsExperimental.gray[4]},
+  'color-fill-brand-selected': {value: colorsExperimental.gray[15]},
+  'color-fill-caution-active': {value: colorsExperimental.yellow[9]},
+  'color-fill-caution-hover': {value: colorsExperimental.yellow[8]},
+  'color-fill-critical-selected': {value: colorsExperimental.red[14]},
+  'color-fill-emphasis-active': {value: colorsExperimental.blue[15]},
+  'color-fill-emphasis-hover': {value: colorsExperimental.blue[14]},
+  'color-fill-emphasis': {value: colorsExperimental.blue[13]},
+  'color-fill-hover': {value: colorsExperimental.gray[3]},
+  'color-fill-info-active': {value: colorsExperimental.azure[11]},
+  'color-fill-info-hover': {value: colorsExperimental.azure[10]},
+  'color-fill-secondary-active': {value: colorsExperimental.gray[8]},
+  'color-fill-secondary-hover': {value: colorsExperimental.gray[7]},
+  'color-fill-selected': {value: colorsExperimental.gray[10]},
+  'color-fill-transparent-secondary-active': {
+    value: colorsExperimental.blackAlpha[8],
+  },
+  'color-fill-transparent-secondary-hover': {
+    value: colorsExperimental.blackAlpha[7],
+  },
+  'color-fill-transparent-selected': {value: colorsExperimental.blackAlpha[6]},
+  'color-fill-transparent': {value: colorsExperimental.blackAlpha[1]},
+  'color-fill-warning-active': {value: colorsExperimental.orange[11]},
+  'color-fill-warning-hover': {value: colorsExperimental.orange[10]},
+  'color-fill': {value: colorsExperimental.gray[1]},
+  'color-icon-secondary-active': {value: colorsExperimental.gray[14]},
+  'color-icon-secondary-hover': {value: colorsExperimental.gray[13]},
+  'color-link-active': {value: colorsExperimental.blue[15]},
+  'color-link-hover': {value: colorsExperimental.blue[14]},
+  'color-link': {value: colorsExperimental.blue[13]},
+  'color-nav-bg': {value: colorsExperimental.gray[7]},
+  'color-nav-surface-active': {value: colorsExperimental.gray[3]},
+  'color-nav-surface-hover': {value: colorsExperimental.gray[6]},
+  'color-nav-surface-selected': {value: colorsExperimental.gray[3]},
+  'color-nav-surface': {value: colorsExperimental.blackAlpha[3]},
+  'color-radio-button-icon-disabled': {value: colorsExperimental.gray[1]},
+  'color-radio-button-surface-disabled': {
+    value: colorsExperimental.blackAlpha[7],
+  },
+  'color-surface-emphasis-active': {value: colorsExperimental.blue[5]},
+  'color-surface-emphasis-hover': {value: colorsExperimental.blue[4]},
+  'color-surface-emphasis': {value: colorsExperimental.blue[3]},
+  'color-surface-inverse': {value: colorsExperimental.gray[15]},
+  'color-surface-magic-active': {value: colorsExperimental.purple[6]},
+  'color-surface-secondary-selected': {value: colorsExperimental.gray[7]},
+  'color-surface-tertiary-active': {value: colorsExperimental.gray[8]},
+  'color-surface-tertiary-hover': {value: colorsExperimental.gray[7]},
+  'color-surface-warning-active': {value: colorsExperimental.orange[5]},
+  'color-surface-warning-hover': {value: colorsExperimental.orange[4]},
+  'color-text-brand-on-fill-active': {value: colorsExperimental.gray[10]},
+  'color-text-brand-on-fill-disabled': {value: colorsExperimental.gray[1]},
+  'color-text-brand-on-fill-hover': {value: colorsExperimental.gray[8]},
+  'color-text-brand-on-fill': {value: colorsExperimental.gray[1]},
+  'color-text-caution-active': {value: colorsExperimental.yellow[16]},
+  'color-text-caution-hover': {value: colorsExperimental.yellow[15]},
+  'color-text-caution-on-fill': {value: colorsExperimental.yellow[15]},
+  'color-text-critical-on-fill': {value: colorsExperimental.red[1]},
+  'color-text-emphasis-on-fill-active': {value: colorsExperimental.blue[7]},
+  'color-text-emphasis-on-fill-hover': {value: colorsExperimental.blue[5]},
+  'color-text-emphasis-on-fill': {value: colorsExperimental.blue[1]},
+  'color-text-info-active': {value: colorsExperimental.azure[16]},
+  'color-text-info-hover': {value: colorsExperimental.azure[15]},
+  'color-text-magic-on-fill': {value: colorsExperimental.purple[1]},
+  'color-text-success-active': {value: colorsExperimental.green[16]},
+  'color-text-success-hover': {value: colorsExperimental.green[15]},
+  'color-text-success-on-fill': {value: colorsExperimental.green[1]},
+  'color-text-warning-active': {value: colorsExperimental.orange[16]},
+  'color-text-warning-hover': {value: colorsExperimental.orange[15]},
+  'color-text-warning-on-fill': {value: colorsExperimental.orange[16]},
+  'color-video-thumbnail-play-button-fill-hover': {
+    value: colorsExperimental.blackAlpha[15],
+  },
+  'color-video-thumbnail-play-button-fill': {
+    value: colorsExperimental.blackAlpha[14],
+  },
+  'color-video-thumbnail-play-button-text-on-fill': {
+    value: colorsExperimental.gray[1],
+  },
+  // ------------------------------
+  // Net new tokens (overridden in light-uplift)
+  // ------------------------------
+  'color-surface': {value: createVar('color-bg')},
+  'color-surface-hover': {value: colorsExperimental.gray[4]},
+  'color-surface-active': {value: colorsExperimental.gray[5]},
+  'color-surface-disabled': {value: colorsExperimental.blackAlpha[5]},
+  'color-surface-secondary': {value: createVar('color-bg-subdued')},
+  'color-surface-secondary-hover': {
+    value: createVar('color-bg-subdued-hover'),
+  },
+  'color-surface-secondary-active': {
+    value: createVar('color-bg-subdued-active'),
+  },
+  'color-surface-tertiary': {
+    value: createVar('color-bg-secondary-experimental'),
+  },
+  'color-fill-tertiary': {value: createVar('color-bg-strong')},
+  'color-fill-tertiary-hover': {value: createVar('color-bg-strong-hover')},
+  'color-fill-tertiary-active': {value: createVar('color-bg-strong-active')},
+  'color-input-surface': {value: createVar('color-bg-input')},
+  'color-input-surface-hover': {
+    value: createVar('color-bg-input-hover-experimental'),
+  },
+  'color-input-surface-active': {
+    value: createVar('color-bg-input-active-experimental'),
+  },
+  'color-fill-brand': {value: colorsExperimental.gray[15]},
+  'color-fill-brand-hover': {value: colorsExperimental.gray[16]},
+  'color-fill-brand-active': {value: colorsExperimental.gray[16]},
+  'color-surface-brand': {value: colorsExperimental.gray[8]},
+  'color-surface-brand-hover': {value: colorsExperimental.gray[7]},
+  'color-surface-brand-active': {value: colorsExperimental.gray[6]},
+  'color-surface-brand-selected': {value: colorsExperimental.gray[6]},
+  'color-surface-selected': {value: createVar('color-bg-app-selected')},
+  'color-fill-success': {value: createVar('color-bg-success-strong')},
+  'color-fill-success-hover': {
+    value: createVar('color-bg-success-strong-hover-experimental'),
+  },
+  'color-fill-success-active': {
+    value: createVar('color-bg-success-strong-active-experimental'),
+  },
+  'color-fill-success-secondary': {value: createVar('color-bg-success')},
+  'color-surface-success': {value: createVar('color-bg-success-subdued')},
+  'color-surface-success-hover': {
+    value: createVar('color-bg-success-subdued-hover'),
+  },
+  'color-surface-success-active': {
+    value: createVar('color-bg-success-subdued-active'),
+  },
+  'color-fill-critical': {value: createVar('color-bg-critical-strong')},
+  'color-fill-critical-hover': {
+    value: createVar('color-bg-critical-strong-hover'),
+  },
+  'color-fill-critical-active': {
+    value: createVar('color-bg-critical-strong-active'),
+  },
+  'color-fill-critical-secondary': {value: createVar('color-bg-critical')},
+  'color-surface-critical': {value: createVar('color-bg-critical-subdued')},
+  'color-surface-critical-hover': {
+    value: createVar('color-bg-critical-subdued-hover'),
+  },
+  'color-surface-critical-active': {
+    value: createVar('color-bg-critical-subdued-active'),
+  },
+  'color-fill-caution': {value: createVar('color-bg-caution-strong')},
+  'color-fill-caution-secondary': {value: createVar('color-bg-caution')},
+  'color-surface-caution': {value: createVar('color-bg-caution-subdued')},
+  'color-surface-caution-hover': {
+    value: createVar('color-bg-caution-subdued-hover'),
+  },
+  'color-surface-caution-active': {
+    value: createVar('color-bg-caution-subdued-active'),
+  },
+  'color-fill-info': {value: createVar('color-bg-info-strong')},
+  'color-fill-info-secondary': {value: createVar('color-bg-info')},
+  'color-surface-info': {value: createVar('color-bg-info-subdued')},
+  'color-surface-info-hover': {
+    value: createVar('color-bg-info-subdued-hover'),
+  },
+  'color-surface-info-active': {
+    value: createVar('color-bg-info-subdued-active'),
+  },
+  'color-fill-warning': {
+    value: createVar('color-bg-warning-strong-experimental'),
+  },
+  'color-fill-warning-secondary': {value: createVar('color-bg-warning')},
+  'color-surface-warning': {
+    value: createVar('color-bg-warning-subdued-experimental'),
+  },
+  'color-fill-magic': {value: createVar('color-bg-magic-strong')},
+  'color-fill-magic-secondary': {value: createVar('color-bg-magic')},
+  'color-fill-magic-secondary-hover': {
+    value: createVar('color-bg-magic-hover'),
+  },
+  'color-fill-magic-secondary-active': {
+    value: createVar('color-bg-magic-active'),
+  },
+  'color-surface-magic': {value: colorsExperimental.purple[3]},
+  'color-surface-magic-hover': {
+    value: createVar('color-bg-magic-subdued-hover'),
+  },
+  'color-fill-secondary': {value: createVar('color-bg-inset')},
+  'color-fill-inverse': {value: createVar('color-bg-inset-strong')},
+  'color-fill-inverse-hover': {value: createVar('color-bg-inverse-hover')},
+  'color-fill-inverse-active': {value: createVar('color-bg-inverse-active')},
+  'color-surface-transparent': {
+    value: createVar('color-bg-transparent-experimental'),
+  },
+  'color-fill-transparent-hover': {
+    value: createVar('color-bg-transparent-hover-experimental'),
+  },
+  'color-fill-transparent-active': {
+    value: createVar('color-bg-transparent-active-experimental'),
+  },
+  'color-fill-disabled': {
+    value: createVar('color-bg-transparent-disabled-experimental'),
+  },
+  'color-fill-transparent-secondary': {
+    value: createVar('color-bg-transparent-subdued-experimental'),
+  },
+  'color-fill-brand-disabled': {
+    value: createVar('color-bg-transparent-primary-disabled-experimental'),
+  },
+  'color-backdrop-bg': {value: createVar('color-bg-backdrop-experimental')},
+  'color-avatar-fill': {
+    value: createVar('color-avatar-background-experimental'),
+  },
+  'color-avatar-one-fill': {
+    value: createVar('color-avatar-style-one-background-experimental'),
+  },
+  'color-avatar-two-fill': {
+    value: createVar('color-avatar-style-two-background-experimental'),
+  },
+  'color-avatar-three-fill': {
+    value: createVar('color-avatar-style-three-background-experimental'),
+  },
+  'color-avatar-four-fill': {
+    value: createVar('color-avatar-style-four-background-experimental'),
+  },
+  'color-avatar-five-fill': {
+    value: createVar('color-avatar-style-five-background-experimental'),
+  },
+  'color-text-secondary': {value: createVar('color-text-subdued')},
+  'color-text-emphasis': {value: createVar('color-text-interactive')},
+  'color-text-emphasis-hover': {
+    value: createVar('color-text-interactive-hover'),
+  },
+  'color-text-emphasis-active': {
+    value: createVar('color-text-interactive-active'),
+  },
+  'color-text-brand': {value: createVar('color-text-primary')},
+  'color-text-brand-hover': {value: createVar('color-text-primary-hover')},
+  'color-text-critical-hover': {value: colorsExperimental.red[15]},
+  'color-text-info-on-fill': {value: createVar('color-text-info-strong')},
+  'color-text-warning': {value: colorsExperimental.orange[14]},
+  'color-text-inverse-secondary': {
+    value: createVar('color-text-inverse-subdued'),
+  },
+  'color-link-inverse': {value: colorsExperimental.blue[8]},
+  'color-avatar-text-on-fill': {
+    value: createVar('color-avatar-color-experimental'),
+  },
+  'color-avatar-one-text-on-fill': {
+    value: createVar('color-avatar-style-one-color-experimental'),
+  },
+  'color-avatar-two-text-on-fill': {
+    value: createVar('color-avatar-style-two-color-experimental'),
+  },
+  'color-avatar-three-text-on-fill': {
+    value: createVar('color-avatar-style-three-color-experimental'),
+  },
+  'color-avatar-four-text-on-fill': {
+    value: createVar('color-avatar-style-four-color-experimental'),
+  },
+  'color-avatar-five-text-on-fill': {
+    value: createVar('color-avatar-style-five-color-experimental'),
+  },
+  'color-icon-secondary': {value: createVar('color-icon-subdued')},
+  'color-icon-emphasis': {value: createVar('color-icon-interactive')},
+  'color-icon-emphasis-hover': {
+    value: createVar('color-icon-interactive-hover'),
+  },
+  'color-icon-emphasis-active': {
+    value: createVar('color-icon-interactive-active'),
+  },
+  'color-icon-brand': {value: createVar('color-icon-primary')},
+  'color-border-secondary': {value: createVar('color-border-subdued')},
+  'color-border-tertiary': {value: colorsExperimental.gray[10]},
+  'color-input-border': {value: createVar('color-border-input')},
+  'color-input-border-hover': {value: createVar('color-border-input-hover')},
+  'color-input-border-active': {
+    value: createVar('color-border-input-active-experimental'),
+  },
+  'color-border-emphasis': {value: colorsExperimental.blue[13]},
+  'color-border-emphasis-hover': {
+    value: createVar('color-border-interactive-hover'),
+  },
+  'color-border-emphasis-active': {
+    value: createVar('color-border-interactive-active'),
+  },
+  'color-border-focus': {value: createVar('color-border-interactive-focus')},
+  'color-border-brand': {value: createVar('color-border-primary')},
+  'color-border-critical-secondary': {
+    value: createVar('color-border-critical-strong-experimental'),
+  },
+  'color-border-magic-secondary': {
+    value: createVar('color-border-magic-strong'),
+  },
+  // ------------------------------
+  // Existing tokens
+  // ------------------------------
   'color-bg-inverse': {
     value: colors.gray[900],
     description: '',
@@ -1149,3 +1448,7 @@ export const color: {
     description: '',
   },
 };
+
+function createVar(colorTokenName: ColorTokenName) {
+  return `var(${createVarName(colorTokenName)})`;
+}
diff --git a/polaris-tokens/src/themes/light-uplift.ts b/polaris-tokens/src/themes/light-uplift.ts
index 59414293eba..e56e78e8d2f 100644
--- a/polaris-tokens/src/themes/light-uplift.ts
+++ b/polaris-tokens/src/themes/light-uplift.ts
@@ -35,6 +35,99 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
     'shadow-2xl': {value: '0px 20px 20px -8px rgba(0, 0, 0, 0.28)'},
   },
   color: {
+    'color-surface': {value: colors.gray[1]},
+    'color-surface-secondary': {value: colors.gray[4]},
+    'color-surface-secondary-hover': {value: colors.gray[6]},
+    'color-surface-secondary-active': {value: colors.gray[7]},
+    'color-surface-tertiary': {value: colors.gray[5]},
+    'color-fill-tertiary': {value: colors.gray[8]},
+    'color-fill-tertiary-hover': {value: colors.gray[9]},
+    'color-fill-tertiary-active': {value: colors.gray[10]},
+    'color-input-surface': {value: colors.gray[2]},
+    'color-input-surface-hover': {value: colors.gray[3]},
+    'color-input-surface-active': {value: colors.gray[4]},
+    'color-surface-selected': {value: colors.gray[3]},
+    'color-fill-success': {value: colors.green[12]},
+    'color-fill-success-hover': {value: colors.green[13]},
+    'color-fill-success-active': {value: colors.green[14]},
+    'color-fill-success-secondary': {value: colors.green[3]},
+    'color-surface-success': {value: colors.green[3]},
+    'color-surface-success-hover': {value: colors.green[4]},
+    'color-surface-success-active': {value: colors.green[5]},
+    'color-fill-critical': {value: colors.red[12]},
+    'color-fill-critical-hover': {value: colors.red[13]},
+    'color-fill-critical-active': {value: colors.red[14]},
+    'color-fill-critical-secondary': {value: colors.red[6]},
+    'color-surface-critical': {value: colors.red[4]},
+    'color-surface-critical-hover': {value: colors.red[5]},
+    'color-surface-critical-active': {value: colors.red[6]},
+    'color-fill-caution': {value: colors.yellow[6]},
+    'color-fill-caution-secondary': {value: colors.yellow[4]},
+    'color-surface-caution': {value: colors.yellow[2]},
+    'color-surface-caution-hover': {value: colors.yellow[3]},
+    'color-surface-caution-active': {value: colors.yellow[4]},
+    'color-fill-info': {value: colors.azure[9]},
+    'color-fill-info-secondary': {value: colors.azure[4]},
+    'color-surface-info': {value: colors.azure[3]},
+    'color-surface-info-hover': {value: colors.azure[4]},
+    'color-surface-info-active': {value: colors.azure[6]},
+    'color-fill-warning': {value: colors.orange[9]},
+    'color-fill-warning-secondary': {value: colors.orange[7]},
+    'color-surface-warning': {value: colors.orange[3]},
+    'color-fill-magic': {value: colors.purple[12]},
+    'color-fill-magic-secondary': {value: colors.purple[6]},
+    'color-fill-magic-secondary-hover': {value: colors.purple[7]},
+    'color-fill-magic-secondary-active': {value: colors.purple[8]},
+    'color-surface-magic-hover': {value: colors.purple[4]},
+    'color-fill-secondary': {value: colors.gray[6]},
+    'color-fill-inverse': {value: colors.gray[15]},
+    'color-fill-inverse-hover': {value: colors.gray[14]},
+    'color-fill-inverse-active': {value: colors.gray[13]},
+    'color-surface-transparent': {value: colors.blackAlpha[1]},
+    'color-fill-transparent-hover': {value: colors.blackAlpha[5]},
+    'color-fill-transparent-active': {value: colors.blackAlpha[6]},
+    'color-fill-disabled': {value: colors.blackAlpha[5]},
+    'color-fill-transparent-secondary': {value: colors.blackAlpha[6]},
+    'color-fill-brand-disabled': {value: colors.blackAlpha[9]},
+    'color-backdrop-bg': {value: colors.blackAlpha[14]},
+    'color-avatar-fill': {value: colors.gray[11]},
+    'color-avatar-one-fill': {value: colors.magenta[7]},
+    'color-avatar-two-fill': {value: colors.green[7]},
+    'color-avatar-three-fill': {value: colors.cyan[7]},
+    'color-avatar-four-fill': {value: colors.azure[7]},
+    'color-avatar-five-fill': {value: colors.rose[7]},
+    'color-text-secondary': {value: colors.gray[13]},
+    'color-text-emphasis': {value: colors.blue[13]},
+    'color-text-emphasis-hover': {value: colors.blue[14]},
+    'color-text-emphasis-active': {value: colors.blue[15]},
+    'color-text-brand': {value: colors.gray[14]},
+    'color-text-brand-hover': {value: colors.gray[15]},
+    'color-text-info-on-fill': {value: colors.azure[16]},
+    'color-text-inverse-secondary': {value: colors.gray[11]},
+    'color-avatar-text-on-fill': {value: colors.gray[1]},
+    'color-avatar-one-text-on-fill': {value: colors.magenta[14]},
+    'color-avatar-two-text-on-fill': {value: colors.green[14]},
+    'color-avatar-three-text-on-fill': {value: colors.cyan[14]},
+    'color-avatar-four-text-on-fill': {value: colors.azure[14]},
+    'color-avatar-five-text-on-fill': {value: colors.rose[14]},
+    'color-icon-secondary': {value: colors.gray[12]},
+    'color-icon-emphasis': {value: colors.blue[13]},
+    'color-icon-emphasis-hover': {value: colors.blue[14]},
+    'color-icon-emphasis-active': {value: colors.blue[15]},
+    'color-icon-brand': {value: colors.gray[16]},
+    'color-border-secondary': {value: colors.gray[7]},
+    'color-input-border': {value: colors.gray[12]},
+    'color-input-border-hover': {value: colors.gray[13]},
+    'color-input-border-active': {value: colors.gray[16]},
+    'color-border-emphasis-hover': {value: colors.blue[14]},
+    'color-border-emphasis-active': {value: colors.blue[15]},
+    'color-border-focus': {value: colors.blue[13]},
+    'color-border-brand': {value: colors.gray[8]},
+    'color-border-critical-secondary': {value: colors.red[14]},
+    'color-border-magic-secondary': {value: colors.purple[12]},
+    // ------------------------------
+    // Existing tokens
+    // ------------------------------
     'color-bg-inverse': {value: colors.gray[16]},
     'color-bg-inset-strong': {value: colors.gray[15]},
     'color-bg-inverse-hover': {value: colors.gray[14]},

From ac92cde0a9ab47d485df65db35a91d935945c6b7 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Fri, 15 Sep 2023 16:46:43 -0700
Subject: [PATCH 14/19] Add changeset entries

---
 .changeset/hip-gorillas-sparkle.md | 6 ++++++
 .changeset/hot-elephants-peel.md   | 5 +++++
 2 files changed, 11 insertions(+)
 create mode 100644 .changeset/hip-gorillas-sparkle.md
 create mode 100644 .changeset/hot-elephants-peel.md

diff --git a/.changeset/hip-gorillas-sparkle.md b/.changeset/hip-gorillas-sparkle.md
new file mode 100644
index 00000000000..09a359af6dc
--- /dev/null
+++ b/.changeset/hip-gorillas-sparkle.md
@@ -0,0 +1,6 @@
+---
+'@shopify/polaris': minor
+'@shopify/polaris-tokens': minor
+---
+
+Updated semantic `color` tokens
diff --git a/.changeset/hot-elephants-peel.md b/.changeset/hot-elephants-peel.md
new file mode 100644
index 00000000000..3e80a1e21dc
--- /dev/null
+++ b/.changeset/hot-elephants-peel.md
@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-migrator': minor
+---
+
+Added `v12-styles-replace-custom-property-color` migration

From 807c2ce4b41b01fe14429102b62337115cb6296f Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Mon, 18 Sep 2023 11:03:25 -0700
Subject: [PATCH 15/19] Remove temp color migration

---
 .changeset/hot-elephants-peel.md              |   5 -
 .../tests/transform.test.ts                   |  12 --
 ...s-replace-custom-property-color.input.scss |   3 -
 ...-replace-custom-property-color.output.scss |   3 -
 .../transform.ts                              | 136 ------------------
 5 files changed, 159 deletions(-)
 delete mode 100644 .changeset/hot-elephants-peel.md
 delete mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts
 delete mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss
 delete mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss
 delete mode 100644 polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts

diff --git a/.changeset/hot-elephants-peel.md b/.changeset/hot-elephants-peel.md
deleted file mode 100644
index 3e80a1e21dc..00000000000
--- a/.changeset/hot-elephants-peel.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@shopify/polaris-migrator': minor
----
-
-Added `v12-styles-replace-custom-property-color` migration
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts
deleted file mode 100644
index d869f53384e..00000000000
--- a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/transform.test.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import {check} from '../../../utilities/check';
-
-const transform = 'v12-styles-replace-custom-property-color';
-const fixtures = ['v12-styles-replace-custom-property-color'];
-
-for (const fixture of fixtures) {
-  check(__dirname, {
-    fixture,
-    transform,
-    extension: 'scss',
-  });
-}
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss
deleted file mode 100644
index ca49c86d72a..00000000000
--- a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.input.scss
+++ /dev/null
@@ -1,3 +0,0 @@
-.basic {
-  background: var(--p-color-bg);
-}
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss
deleted file mode 100644
index eaa3699c218..00000000000
--- a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/tests/v12-styles-replace-custom-property-color.output.scss
+++ /dev/null
@@ -1,3 +0,0 @@
-.basic {
-  background: var(--p-color-surface);
-}
diff --git a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts b/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts
deleted file mode 100644
index 91f3eb129c8..00000000000
--- a/polaris-migrator/src/migrations/v12-styles-replace-custom-property-color/transform.ts
+++ /dev/null
@@ -1,136 +0,0 @@
-import type {FileInfo, API} from 'jscodeshift';
-
-import stylesReplaceCustomProperty from '../styles-replace-custom-property/transform';
-
-export default function transformer(fileInfo: FileInfo, _: API) {
-  return stylesReplaceCustomProperty(fileInfo, _, {replacementMaps});
-}
-
-const replacementMaps = {
-  '/.+/': {
-    '--p-color-bg': '--p-color-surface',
-    // '--p-color-bg-hover': '--p-color-surface-hover',
-    // '--p-color-bg-active': '--p-color-surface-active',
-    // '--p-color-bg-disabled': '--p-color-surface-disabled',
-    '--p-color-bg-subdued': '--p-color-surface-secondary',
-    '--p-color-bg-subdued-hover': '--p-color-surface-secondary-hover',
-    '--p-color-bg-subdued-active': '--p-color-surface-secondary-active',
-    '--p-color-bg-secondary-experimental': '--p-color-surface-tertiary',
-    '--p-color-bg-strong': '--p-color-fill-tertiary',
-    '--p-color-bg-strong-hover': '--p-color-fill-tertiary-hover',
-    '--p-color-bg-strong-active': '--p-color-fill-tertiary-active',
-    '--p-color-bg-input': '--p-color-input-surface',
-    '--p-color-bg-input-hover-experimental': '--p-color-input-surface-hover',
-    '--p-color-bg-input-active-experimental': '--p-color-input-surface-active',
-    // '--p-color-bg-primary': '--p-color-fill-brand',
-    // '--p-color-bg-primary-hover': '--p-color-fill-brand-hover',
-    // '--p-color-bg-primary-active': '--p-color-fill-brand-active',
-    // '--p-color-bg-primary-subdued': '--p-color-surface-brand',
-    // '--p-color-bg-primary-subdued-hover': '--p-color-surface-brand-hover',
-    // '--p-color-bg-primary-subdued-active': '--p-color-surface-brand-active',
-    // '--p-color-bg-primary-subdued-selected': '--p-color-surface-brand-selected',
-    '--p-color-bg-app-selected': '--p-color-surface-selected',
-    '--p-color-bg-success-strong': '--p-color-fill-success',
-    '--p-color-bg-success-strong-hover-experimental':
-      '--p-color-fill-success-hover',
-    '--p-color-bg-success-strong-active-experimental':
-      '--p-color-fill-success-active',
-    '--p-color-bg-success': '--p-color-fill-success-secondary',
-    '--p-color-bg-success-subdued': '--p-color-surface-success',
-    '--p-color-bg-success-subdued-hover': '--p-color-surface-success-hover',
-    '--p-color-bg-success-subdued-active': '--p-color-surface-success-active',
-    '--p-color-bg-critical-strong': '--p-color-fill-critical',
-    '--p-color-bg-critical-strong-hover': '--p-color-fill-critical-hover',
-    '--p-color-bg-critical-strong-active': '--p-color-fill-critical-active',
-    '--p-color-bg-critical': '--p-color-fill-critical-secondary',
-    '--p-color-bg-critical-subdued': '--p-color-surface-critical',
-    '--p-color-bg-critical-subdued-hover': '--p-color-surface-critical-hover',
-    '--p-color-bg-critical-subdued-active': '--p-color-surface-critical-active',
-    '--p-color-bg-caution-strong': '--p-color-fill-caution',
-    '--p-color-bg-caution': '--p-color-fill-caution-secondary',
-    '--p-color-bg-caution-subdued': '--p-color-surface-caution',
-    '--p-color-bg-caution-subdued-hover': '--p-color-surface-caution-hover',
-    '--p-color-bg-caution-subdued-active': '--p-color-surface-caution-active',
-    '--p-color-bg-info-strong': '--p-color-fill-info',
-    '--p-color-bg-info': '--p-color-fill-info-secondary',
-    '--p-color-bg-info-subdued': '--p-color-surface-info',
-    '--p-color-bg-info-subdued-hover': '--p-color-surface-info-hover',
-    '--p-color-bg-info-subdued-active': '--p-color-surface-info-active',
-    '--p-color-bg-warning-strong-experimental': '--p-color-fill-warning',
-    '--p-color-bg-warning': '--p-color-fill-warning-secondary',
-    '--p-color-bg-warning-subdued-experimental': '--p-color-surface-warning',
-    '--p-color-bg-magic-strong': '--p-color-fill-magic',
-    '--p-color-bg-magic': '--p-color-fill-magic-secondary',
-    '--p-color-bg-magic-hover': '--p-color-fill-magic-secondary-hover',
-    '--p-color-bg-magic-active': '--p-color-fill-magic-secondary-active',
-    // '--p-color-bg-magic-subdued': '--p-color-surface-magic',
-    '--p-color-bg-magic-subdued-hover': '--p-color-surface-magic-hover',
-    '--p-color-bg-inset': '--p-color-fill-secondary',
-    '--p-color-bg-inset-strong': '--p-color-fill-inverse',
-    '--p-color-bg-inverse-hover': '--p-color-fill-inverse-hover',
-    '--p-color-bg-inverse-active': '--p-color-fill-inverse-active',
-    '--p-color-bg-transparent-experimental': '--p-color-surface-transparent',
-    '--p-color-bg-transparent-hover-experimental':
-      '--p-color-fill-transparent-hover',
-    '--p-color-bg-transparent-active-experimental':
-      '--p-color-fill-transparent-active',
-    '--p-color-bg-transparent-disabled-experimental': '--p-color-fill-disabled',
-    '--p-color-bg-transparent-subdued-experimental':
-      '--p-color-fill-transparent-secondary',
-    '--p-color-bg-transparent-primary-disabled-experimental':
-      '--p-color-fill-brand-disabled',
-    '--p-color-bg-backdrop-experimental': '--p-color-backdrop-bg',
-    '--p-color-avatar-background-experimental': '--p-color-avatar-fill',
-    '--p-color-avatar-style-one-background-experimental':
-      '--p-color-avatar-one-fill',
-    '--p-color-avatar-style-two-background-experimental':
-      '--p-color-avatar-two-fill',
-    '--p-color-avatar-style-three-background-experimental':
-      '--p-color-avatar-three-fill',
-    '--p-color-avatar-style-four-background-experimental':
-      '--p-color-avatar-four-fill',
-    '--p-color-avatar-style-five-background-experimental':
-      '--p-color-avatar-five-fill',
-    '--p-color-text-subdued': '--p-color-text-secondary',
-    '--p-color-text-interactive': '--p-color-text-emphasis',
-    '--p-color-text-interactive-hover': '--p-color-text-emphasis-hover',
-    '--p-color-text-interactive-active': '--p-color-text-emphasis-active',
-    '--p-color-text-primary': '--p-color-text-brand',
-    '--p-color-text-primary-hover': '--p-color-text-brand-hover',
-    // '--p-color-text-critical-hover-experimental': '--p-color-text-critical-hover',
-    '--p-color-text-info-strong': '--p-color-text-info-on-fill',
-    // '--p-color-text-warning-experimental': '--p-color-text-warning',
-    '--p-color-text-inverse-subdued': '--p-color-text-inverse-secondary',
-    // '--p-color-text-interactive-inverse': '--p-color-link-inverse',
-    '--p-color-avatar-color-experimental': '--p-color-avatar-text-on-fill',
-    '--p-color-avatar-style-one-color-experimental':
-      '--p-color-avatar-one-text-on-fill',
-    '--p-color-avatar-style-two-color-experimental':
-      '--p-color-avatar-two-text-on-fill',
-    '--p-color-avatar-style-three-color-experimental':
-      '--p-color-avatar-three-text-on-fill',
-    '--p-color-avatar-style-four-color-experimental':
-      '--p-color-avatar-four-text-on-fill',
-    '--p-color-avatar-style-five-color-experimental':
-      '--p-color-avatar-five-text-on-fill',
-    '--p-color-icon-subdued': '--p-color-icon-secondary',
-    '--p-color-icon-interactive': '--p-color-icon-emphasis',
-    '--p-color-icon-interactive-hover': '--p-color-icon-emphasis-hover',
-    '--p-color-icon-interactive-active': '--p-color-icon-emphasis-active',
-    '--p-color-icon-primary': '--p-color-icon-brand',
-    '--p-color-border-subdued': '--p-color-border-secondary',
-    // '--p-color-border-strong': '--p-color-border-tertiary',
-    '--p-color-border-input': '--p-color-input-border',
-    '--p-color-border-input-hover': '--p-color-input-border-hover',
-    '--p-color-border-input-active-experimental':
-      '--p-color-input-border-active',
-    // '--p-color-border-interactive': '--p-color-border-emphasis',
-    '--p-color-border-interactive-hover': '--p-color-border-emphasis-hover',
-    '--p-color-border-interactive-active': '--p-color-border-emphasis-active',
-    '--p-color-border-interactive-focus': '--p-color-border-focus',
-    '--p-color-border-primary': '--p-color-border-brand',
-    '--p-color-border-critical-strong-experimental':
-      '--p-color-border-critical-secondary',
-    '--p-color-border-magic-strong': '--p-color-border-magic-secondary',
-  },
-};

From da25f30ff2aaa5e38c5d11bcec3d2853cf0fcfd0 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Mon, 18 Sep 2023 14:21:46 -0700
Subject: [PATCH 16/19] Cleanup comments

---
 polaris-tokens/src/themes/base/color.ts | 52 +++++--------------------
 1 file changed, 10 insertions(+), 42 deletions(-)

diff --git a/polaris-tokens/src/themes/base/color.ts b/polaris-tokens/src/themes/base/color.ts
index d4aec39c31a..e51870b21c7 100644
--- a/polaris-tokens/src/themes/base/color.ts
+++ b/polaris-tokens/src/themes/base/color.ts
@@ -71,12 +71,7 @@ export type ColorBackgroundAlias =
   | 'bg-success-subdued-hover'
   | 'bg-warning'
   | ColorBackgroundAliasExperimental
-  /**
-   * Conceptual and component specific backgrounds.
-   * TODO: Determine if we should create a separate
-   * type alias (e.g. `ColorComponentBackgroundAlias`) and
-   * union it here in `ColorBackgroundAlias`.
-   */
+  /** Specialty and component backgrounds. */
   | 'nav-bg'
   | 'backdrop-bg';
 
@@ -122,12 +117,7 @@ export type ColorBorderAlias =
   | 'border-emphasis-hover'
   | 'border-emphasis-active'
   | ColorBorderAliasExperimental
-  /**
-   * Conceptual and component specific borders.
-   * TODO: Determine if we should create a separate
-   * type alias (e.g. `ColorComponentBorderAlias`) and
-   * union it here in `ColorBorderAlias`.
-   */
+  /** Specialty and component borders. */
   | 'input-border'
   | 'input-border-hover'
   | 'input-border-active';
@@ -187,12 +177,7 @@ export type ColorFillAlias =
   | 'fill-transparent-secondary'
   | 'fill-transparent-secondary-hover'
   | 'fill-transparent-secondary-active'
-  /**
-   * Conceptual and component specific fills.
-   * TODO: Determine if we should create a separate
-   * type alias (e.g. `ColorComponentFillAlias`) and
-   * union it here in `ColorFillAlias`.
-   */
+  /** Specialty and component fills. */
   | 'avatar-fill'
   | 'avatar-one-fill'
   | 'avatar-two-fill'
@@ -229,18 +214,11 @@ export type ColorIconAlias =
   | 'icon-emphasis'
   | 'icon-emphasis-hover'
   | 'icon-emphasis-active'
-  /**
-   * check on emphasis state icons
-   */
+  | ColorIconAliasExperimental
+  /** Check on emphasis state icons. */
   | 'icon-emphasis-hover'
   | 'icon-emphasis-active'
-  | ColorIconAliasExperimental
-  /**
-   * Conceptual and component specific icons.
-   * TODO: Determine if we should create a separate
-   * type alias (e.g. `ColorComponentIconAlias`) and
-   * union it here in `ColorIconAlias`.
-   */
+  /** Specialty and component icons. */
   | 'radio-button-icon-disabled'
   | 'checkbox-icon-disabled';
 
@@ -290,12 +268,7 @@ export type ColorSurfaceAlias =
   | 'surface-emphasis-hover'
   | 'surface-emphasis-active'
   | 'surface-inverse'
-  /**
-   * Conceptual and component specific surfaces.
-   * TODO: Determine if we should create a separate
-   * type alias (e.g. `ColorComponentIconAlias`) and
-   * union it here in `ColorSurfaceAlias`.
-   */
+  /** Specialty and component surfaces. */
   | 'input-surface'
   | 'input-surface-hover'
   | 'input-surface-active'
@@ -362,20 +335,15 @@ export type ColorTextAlias =
   | 'text-emphasis-on-fill'
   | 'text-emphasis-on-fill-hover'
   | 'text-emphasis-on-fill-active'
-  /**
-   * Conceptual and component specific surfaces.
-   * TODO: Determine if we should create a separate
-   * type alias (e.g. `ColorComponentIconAlias`) and
-   * union it here in `ColorSurfaceAlias`.
-   */
+  | ColorTextAliasExperimental
+  /** Specialty and component surfaces. */
   | 'avatar-text-on-fill'
   | 'avatar-one-text-on-fill'
   | 'avatar-two-text-on-fill'
   | 'avatar-three-text-on-fill'
   | 'avatar-four-text-on-fill'
   | 'avatar-five-text-on-fill'
-  | 'video-thumbnail-play-button-text-on-fill'
-  | ColorTextAliasExperimental;
+  | 'video-thumbnail-play-button-text-on-fill';
 
 type ColorBackgroundAliasExperimental = Experimental<
   | 'bg-backdrop'

From d86b112fb8a4f61a7b25e79d909c343557a2f362 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Mon, 18 Sep 2023 17:11:03 -0700
Subject: [PATCH 17/19] Consolidate surface and fill to background alias

---
 polaris-tokens/src/themes/base/color.ts | 555 ++++++++++++------------
 1 file changed, 274 insertions(+), 281 deletions(-)

diff --git a/polaris-tokens/src/themes/base/color.ts b/polaris-tokens/src/themes/base/color.ts
index e51870b21c7..850b98b99e0 100644
--- a/polaris-tokens/src/themes/base/color.ts
+++ b/polaris-tokens/src/themes/base/color.ts
@@ -70,10 +70,120 @@ export type ColorBackgroundAlias =
   | 'bg-success-subdued-active'
   | 'bg-success-subdued-hover'
   | 'bg-warning'
+  | 'bg-surface'
+  | 'bg-surface-hover'
+  | 'bg-surface-active'
+  | 'bg-surface-selected'
+  | 'bg-surface-disabled'
+  | 'bg-surface-secondary'
+  | 'bg-surface-secondary-hover'
+  | 'bg-surface-secondary-active'
+  | 'bg-surface-secondary-selected'
+  | 'bg-surface-tertiary'
+  | 'bg-surface-tertiary-hover'
+  | 'bg-surface-tertiary-active'
+  | 'bg-surface-transparent'
+  | 'bg-surface-brand'
+  | 'bg-surface-brand-hover'
+  | 'bg-surface-brand-active'
+  | 'bg-surface-brand-selected'
+  | 'bg-surface-info'
+  | 'bg-surface-info-hover'
+  | 'bg-surface-info-active'
+  | 'bg-surface-success'
+  | 'bg-surface-success-hover'
+  | 'bg-surface-success-active'
+  | 'bg-surface-caution'
+  | 'bg-surface-caution-hover'
+  | 'bg-surface-caution-active'
+  | 'bg-surface-warning'
+  | 'bg-surface-warning-hover'
+  | 'bg-surface-warning-active'
+  | 'bg-surface-critical'
+  | 'bg-surface-critical-hover'
+  | 'bg-surface-critical-active'
+  | 'bg-surface-magic'
+  | 'bg-surface-magic-hover'
+  | 'bg-surface-magic-active'
+  | 'bg-surface-emphasis'
+  | 'bg-surface-emphasis-hover'
+  | 'bg-surface-emphasis-active'
+  | 'bg-surface-inverse'
+  | 'bg-fill'
+  | 'bg-fill-hover'
+  | 'bg-fill-active'
+  | 'bg-fill-selected'
+  | 'bg-fill-disabled'
+  | 'bg-fill-secondary'
+  | 'bg-fill-secondary-hover'
+  | 'bg-fill-secondary-active'
+  | 'bg-fill-tertiary'
+  | 'bg-fill-tertiary-hover'
+  | 'bg-fill-tertiary-active'
+  | 'bg-fill-brand'
+  | 'bg-fill-brand-hover'
+  | 'bg-fill-brand-active'
+  | 'bg-fill-brand-selected'
+  | 'bg-fill-brand-disabled'
+  | 'bg-fill-emphasis'
+  | 'bg-fill-emphasis-hover'
+  | 'bg-fill-emphasis-active'
+  | 'bg-fill-success'
+  | 'bg-fill-success-hover'
+  | 'bg-fill-success-active'
+  | 'bg-fill-success-secondary'
+  | 'bg-fill-critical'
+  | 'bg-fill-critical-hover'
+  | 'bg-fill-critical-active'
+  | 'bg-fill-critical-selected'
+  | 'bg-fill-critical-secondary'
+  | 'bg-fill-caution'
+  | 'bg-fill-caution-hover'
+  | 'bg-fill-caution-active'
+  | 'bg-fill-caution-secondary'
+  | 'bg-fill-info'
+  | 'bg-fill-info-hover'
+  | 'bg-fill-info-active'
+  | 'bg-fill-info-secondary'
+  | 'bg-fill-warning'
+  | 'bg-fill-warning-hover'
+  | 'bg-fill-warning-active'
+  | 'bg-fill-warning-secondary'
+  | 'bg-fill-magic'
+  | 'bg-fill-magic-secondary'
+  | 'bg-fill-magic-secondary-hover'
+  | 'bg-fill-magic-secondary-active'
+  | 'bg-fill-inverse'
+  | 'bg-fill-inverse-hover'
+  | 'bg-fill-inverse-active'
+  | 'bg-fill-transparent'
+  | 'bg-fill-transparent-hover'
+  | 'bg-fill-transparent-active'
+  | 'bg-fill-transparent-selected'
+  | 'bg-fill-transparent-secondary'
+  | 'bg-fill-transparent-secondary-hover'
+  | 'bg-fill-transparent-secondary-active'
   | ColorBackgroundAliasExperimental
   /** Specialty and component backgrounds. */
   | 'nav-bg'
-  | 'backdrop-bg';
+  | 'backdrop-bg'
+  | 'input-bg-surface'
+  | 'input-bg-surface-hover'
+  | 'input-bg-surface-active'
+  | 'nav-bg-surface'
+  | 'nav-bg-surface-hover'
+  | 'nav-bg-surface-active'
+  | 'nav-bg-surface-selected'
+  | 'radio-button-bg-surface-disabled'
+  | 'checkbox-bg-surface-disabled'
+  | 'avatar-bg-fill'
+  | 'avatar-one-bg-fill'
+  | 'avatar-two-bg-fill'
+  | 'avatar-three-bg-fill'
+  | 'avatar-four-bg-fill'
+  | 'avatar-five-bg-fill'
+  | 'video-thumbnail-play-button-bg-fill'
+  | 'video-thumbnail-play-button-bg-fill-hover';
 
 export type ColorBorderAlias =
   | 'border'
@@ -122,71 +232,6 @@ export type ColorBorderAlias =
   | 'input-border-hover'
   | 'input-border-active';
 
-export type ColorFillAlias =
-  | 'fill'
-  | 'fill-hover'
-  | 'fill-active'
-  | 'fill-selected'
-  | 'fill-disabled'
-  | 'fill-secondary'
-  | 'fill-secondary-hover'
-  | 'fill-secondary-active'
-  | 'fill-tertiary'
-  | 'fill-tertiary-hover'
-  | 'fill-tertiary-active'
-  | 'fill-brand'
-  | 'fill-brand-hover'
-  | 'fill-brand-active'
-  | 'fill-brand-selected'
-  | 'fill-brand-disabled'
-  | 'fill-emphasis'
-  | 'fill-emphasis-hover'
-  | 'fill-emphasis-active'
-  | 'fill-success'
-  | 'fill-success-hover'
-  | 'fill-success-active'
-  | 'fill-success-secondary'
-  | 'fill-critical'
-  | 'fill-critical-hover'
-  | 'fill-critical-active'
-  | 'fill-critical-selected'
-  | 'fill-critical-secondary'
-  | 'fill-caution'
-  | 'fill-caution-hover'
-  | 'fill-caution-active'
-  | 'fill-caution-secondary'
-  | 'fill-info'
-  | 'fill-info-hover'
-  | 'fill-info-active'
-  | 'fill-info-secondary'
-  | 'fill-warning'
-  | 'fill-warning-hover'
-  | 'fill-warning-active'
-  | 'fill-warning-secondary'
-  | 'fill-magic'
-  | 'fill-magic-secondary'
-  | 'fill-magic-secondary-hover'
-  | 'fill-magic-secondary-active'
-  | 'fill-inverse'
-  | 'fill-inverse-hover'
-  | 'fill-inverse-active'
-  | 'fill-transparent'
-  | 'fill-transparent-hover'
-  | 'fill-transparent-active'
-  | 'fill-transparent-selected'
-  | 'fill-transparent-secondary'
-  | 'fill-transparent-secondary-hover'
-  | 'fill-transparent-secondary-active'
-  /** Specialty and component fills. */
-  | 'avatar-fill'
-  | 'avatar-one-fill'
-  | 'avatar-two-fill'
-  | 'avatar-three-fill'
-  | 'avatar-four-fill'
-  | 'avatar-five-fill'
-  | 'video-thumbnail-play-button-fill'
-  | 'video-thumbnail-play-button-fill-hover';
-
 export type ColorIconAlias =
   | 'icon'
   | 'icon-active'
@@ -222,80 +267,23 @@ export type ColorIconAlias =
   | 'radio-button-icon-disabled'
   | 'checkbox-icon-disabled';
 
-export type ColorLinkAlias =
-  | 'link'
-  | 'link-hover'
-  | 'link-active'
-  | 'link-inverse';
-
-export type ColorSurfaceAlias =
-  | 'surface'
-  | 'surface-hover'
-  | 'surface-active'
-  | 'surface-selected'
-  | 'surface-disabled'
-  | 'surface-secondary'
-  | 'surface-secondary-hover'
-  | 'surface-secondary-active'
-  | 'surface-secondary-selected'
-  | 'surface-tertiary'
-  | 'surface-tertiary-hover'
-  | 'surface-tertiary-active'
-  | 'surface-transparent'
-  | 'surface-brand'
-  | 'surface-brand-hover'
-  | 'surface-brand-active'
-  | 'surface-brand-selected'
-  | 'surface-info'
-  | 'surface-info-hover'
-  | 'surface-info-active'
-  | 'surface-success'
-  | 'surface-success-hover'
-  | 'surface-success-active'
-  | 'surface-caution'
-  | 'surface-caution-hover'
-  | 'surface-caution-active'
-  | 'surface-warning'
-  | 'surface-warning-hover'
-  | 'surface-warning-active'
-  | 'surface-critical'
-  | 'surface-critical-hover'
-  | 'surface-critical-active'
-  | 'surface-magic'
-  | 'surface-magic-hover'
-  | 'surface-magic-active'
-  | 'surface-emphasis'
-  | 'surface-emphasis-hover'
-  | 'surface-emphasis-active'
-  | 'surface-inverse'
-  /** Specialty and component surfaces. */
-  | 'input-surface'
-  | 'input-surface-hover'
-  | 'input-surface-active'
-  | 'nav-surface'
-  | 'nav-surface-hover'
-  | 'nav-surface-active'
-  | 'nav-surface-selected'
-  | 'radio-button-surface-disabled'
-  | 'checkbox-surface-disabled';
-
 export type ColorTextAlias =
   | 'text'
   | 'text-caution'
   | 'text-caution-hover'
   | 'text-caution-active'
-  | 'text-caution-on-fill'
+  | 'text-caution-on-bg-fill'
   | 'text-caution-strong'
   | 'text-critical'
   | 'text-critical-hover'
   | 'text-critical-active'
-  | 'text-critical-on-fill'
+  | 'text-critical-on-bg-fill'
   | 'text-critical-strong'
   | 'text-disabled'
   | 'text-info'
   | 'text-info-hover'
   | 'text-info-active'
-  | 'text-info-on-fill'
+  | 'text-info-on-bg-fill'
   | 'text-info-strong'
   | 'text-interactive'
   | 'text-interactive-active'
@@ -306,7 +294,7 @@ export type ColorTextAlias =
   | 'text-inverse-secondary'
   | 'text-inverse-subdued'
   | 'text-magic'
-  | 'text-magic-on-fill'
+  | 'text-magic-on-bg-fill'
   | 'text-magic-strong'
   | 'text-on-color'
   | 'text-primary'
@@ -315,35 +303,39 @@ export type ColorTextAlias =
   | 'text-success'
   | 'text-success-hover'
   | 'text-success-active'
-  | 'text-success-on-fill'
+  | 'text-success-on-bg-fill'
   | 'text-success-strong'
   | 'text-warning-strong'
   | 'text-warning'
   | 'text-warning-hover'
   | 'text-warning-active'
-  | 'text-warning-on-fill'
+  | 'text-warning-on-bg-fill'
   | 'text-secondary'
   | 'text-brand'
   | 'text-brand-hover'
-  | 'text-brand-on-fill'
-  | 'text-brand-on-fill-hover'
-  | 'text-brand-on-fill-active'
-  | 'text-brand-on-fill-disabled'
+  | 'text-brand-on-bg-fill'
+  | 'text-brand-on-bg-fill-hover'
+  | 'text-brand-on-bg-fill-active'
+  | 'text-brand-on-bg-fill-disabled'
   | 'text-emphasis'
   | 'text-emphasis-hover'
   | 'text-emphasis-active'
-  | 'text-emphasis-on-fill'
-  | 'text-emphasis-on-fill-hover'
-  | 'text-emphasis-on-fill-active'
+  | 'text-emphasis-on-bg-fill'
+  | 'text-emphasis-on-bg-fill-hover'
+  | 'text-emphasis-on-bg-fill-active'
+  | 'text-link'
+  | 'text-link-hover'
+  | 'text-link-active'
+  | 'text-link-inverse'
   | ColorTextAliasExperimental
-  /** Specialty and component surfaces. */
-  | 'avatar-text-on-fill'
-  | 'avatar-one-text-on-fill'
-  | 'avatar-two-text-on-fill'
-  | 'avatar-three-text-on-fill'
-  | 'avatar-four-text-on-fill'
-  | 'avatar-five-text-on-fill'
-  | 'video-thumbnail-play-button-text-on-fill';
+  /** Specialty and component text colors. */
+  | 'avatar-text-on-bg-fill'
+  | 'avatar-one-text-on-bg-fill'
+  | 'avatar-two-text-on-bg-fill'
+  | 'avatar-three-text-on-bg-fill'
+  | 'avatar-four-text-on-bg-fill'
+  | 'avatar-five-text-on-bg-fill'
+  | 'video-thumbnail-play-button-text-on-bg-fill';
 
 type ColorBackgroundAliasExperimental = Experimental<
   | 'bg-backdrop'
@@ -400,10 +392,7 @@ type ColorAvatarAliasExperimental = Experimental<
 export type ColorTokenName =
   | `color-${ColorBackgroundAlias}`
   | `color-${ColorBorderAlias}`
-  | `color-${ColorFillAlias}`
   | `color-${ColorIconAlias}`
-  | `color-${ColorLinkAlias}`
-  | `color-${ColorSurfaceAlias}`
   | `color-${ColorTextAlias}`
   | `color-${ColorAvatarAliasExperimental}`;
 
@@ -421,226 +410,230 @@ export const color: {
   'color-border-inverse-hover': {value: colorsExperimental.gray[10]},
   'color-border-warning': {value: colorsExperimental.orange[8]},
   'color-checkbox-icon-disabled': {value: colorsExperimental.gray[1]},
-  'color-checkbox-surface-disabled': {value: colorsExperimental.blackAlpha[7]},
-  'color-fill-active': {value: colorsExperimental.gray[4]},
-  'color-fill-brand-selected': {value: colorsExperimental.gray[15]},
-  'color-fill-caution-active': {value: colorsExperimental.yellow[9]},
-  'color-fill-caution-hover': {value: colorsExperimental.yellow[8]},
-  'color-fill-critical-selected': {value: colorsExperimental.red[14]},
-  'color-fill-emphasis-active': {value: colorsExperimental.blue[15]},
-  'color-fill-emphasis-hover': {value: colorsExperimental.blue[14]},
-  'color-fill-emphasis': {value: colorsExperimental.blue[13]},
-  'color-fill-hover': {value: colorsExperimental.gray[3]},
-  'color-fill-info-active': {value: colorsExperimental.azure[11]},
-  'color-fill-info-hover': {value: colorsExperimental.azure[10]},
-  'color-fill-secondary-active': {value: colorsExperimental.gray[8]},
-  'color-fill-secondary-hover': {value: colorsExperimental.gray[7]},
-  'color-fill-selected': {value: colorsExperimental.gray[10]},
-  'color-fill-transparent-secondary-active': {
+  'color-checkbox-bg-surface-disabled': {
+    value: colorsExperimental.blackAlpha[7],
+  },
+  'color-bg-fill-active': {value: colorsExperimental.gray[4]},
+  'color-bg-fill-brand-selected': {value: colorsExperimental.gray[15]},
+  'color-bg-fill-caution-active': {value: colorsExperimental.yellow[9]},
+  'color-bg-fill-caution-hover': {value: colorsExperimental.yellow[8]},
+  'color-bg-fill-critical-selected': {value: colorsExperimental.red[14]},
+  'color-bg-fill-emphasis-active': {value: colorsExperimental.blue[15]},
+  'color-bg-fill-emphasis-hover': {value: colorsExperimental.blue[14]},
+  'color-bg-fill-emphasis': {value: colorsExperimental.blue[13]},
+  'color-bg-fill-hover': {value: colorsExperimental.gray[3]},
+  'color-bg-fill-info-active': {value: colorsExperimental.azure[11]},
+  'color-bg-fill-info-hover': {value: colorsExperimental.azure[10]},
+  'color-bg-fill-secondary-active': {value: colorsExperimental.gray[8]},
+  'color-bg-fill-secondary-hover': {value: colorsExperimental.gray[7]},
+  'color-bg-fill-selected': {value: colorsExperimental.gray[10]},
+  'color-bg-fill-transparent-secondary-active': {
     value: colorsExperimental.blackAlpha[8],
   },
-  'color-fill-transparent-secondary-hover': {
+  'color-bg-fill-transparent-secondary-hover': {
     value: colorsExperimental.blackAlpha[7],
   },
-  'color-fill-transparent-selected': {value: colorsExperimental.blackAlpha[6]},
-  'color-fill-transparent': {value: colorsExperimental.blackAlpha[1]},
-  'color-fill-warning-active': {value: colorsExperimental.orange[11]},
-  'color-fill-warning-hover': {value: colorsExperimental.orange[10]},
-  'color-fill': {value: colorsExperimental.gray[1]},
+  'color-bg-fill-transparent-selected': {
+    value: colorsExperimental.blackAlpha[6],
+  },
+  'color-bg-fill-transparent': {value: colorsExperimental.blackAlpha[1]},
+  'color-bg-fill-warning-active': {value: colorsExperimental.orange[11]},
+  'color-bg-fill-warning-hover': {value: colorsExperimental.orange[10]},
+  'color-bg-fill': {value: colorsExperimental.gray[1]},
   'color-icon-secondary-active': {value: colorsExperimental.gray[14]},
   'color-icon-secondary-hover': {value: colorsExperimental.gray[13]},
-  'color-link-active': {value: colorsExperimental.blue[15]},
-  'color-link-hover': {value: colorsExperimental.blue[14]},
-  'color-link': {value: colorsExperimental.blue[13]},
+  'color-text-link-active': {value: colorsExperimental.blue[15]},
+  'color-text-link-hover': {value: colorsExperimental.blue[14]},
+  'color-text-link': {value: colorsExperimental.blue[13]},
   'color-nav-bg': {value: colorsExperimental.gray[7]},
-  'color-nav-surface-active': {value: colorsExperimental.gray[3]},
-  'color-nav-surface-hover': {value: colorsExperimental.gray[6]},
-  'color-nav-surface-selected': {value: colorsExperimental.gray[3]},
-  'color-nav-surface': {value: colorsExperimental.blackAlpha[3]},
+  'color-nav-bg-surface-active': {value: colorsExperimental.gray[3]},
+  'color-nav-bg-surface-hover': {value: colorsExperimental.gray[6]},
+  'color-nav-bg-surface-selected': {value: colorsExperimental.gray[3]},
+  'color-nav-bg-surface': {value: colorsExperimental.blackAlpha[3]},
   'color-radio-button-icon-disabled': {value: colorsExperimental.gray[1]},
-  'color-radio-button-surface-disabled': {
+  'color-radio-button-bg-surface-disabled': {
     value: colorsExperimental.blackAlpha[7],
   },
-  'color-surface-emphasis-active': {value: colorsExperimental.blue[5]},
-  'color-surface-emphasis-hover': {value: colorsExperimental.blue[4]},
-  'color-surface-emphasis': {value: colorsExperimental.blue[3]},
-  'color-surface-inverse': {value: colorsExperimental.gray[15]},
-  'color-surface-magic-active': {value: colorsExperimental.purple[6]},
-  'color-surface-secondary-selected': {value: colorsExperimental.gray[7]},
-  'color-surface-tertiary-active': {value: colorsExperimental.gray[8]},
-  'color-surface-tertiary-hover': {value: colorsExperimental.gray[7]},
-  'color-surface-warning-active': {value: colorsExperimental.orange[5]},
-  'color-surface-warning-hover': {value: colorsExperimental.orange[4]},
-  'color-text-brand-on-fill-active': {value: colorsExperimental.gray[10]},
-  'color-text-brand-on-fill-disabled': {value: colorsExperimental.gray[1]},
-  'color-text-brand-on-fill-hover': {value: colorsExperimental.gray[8]},
-  'color-text-brand-on-fill': {value: colorsExperimental.gray[1]},
+  'color-bg-surface-emphasis-active': {value: colorsExperimental.blue[5]},
+  'color-bg-surface-emphasis-hover': {value: colorsExperimental.blue[4]},
+  'color-bg-surface-emphasis': {value: colorsExperimental.blue[3]},
+  'color-bg-surface-inverse': {value: colorsExperimental.gray[15]},
+  'color-bg-surface-magic-active': {value: colorsExperimental.purple[6]},
+  'color-bg-surface-secondary-selected': {value: colorsExperimental.gray[7]},
+  'color-bg-surface-tertiary-active': {value: colorsExperimental.gray[8]},
+  'color-bg-surface-tertiary-hover': {value: colorsExperimental.gray[7]},
+  'color-bg-surface-warning-active': {value: colorsExperimental.orange[5]},
+  'color-bg-surface-warning-hover': {value: colorsExperimental.orange[4]},
+  'color-text-brand-on-bg-fill-active': {value: colorsExperimental.gray[10]},
+  'color-text-brand-on-bg-fill-disabled': {value: colorsExperimental.gray[1]},
+  'color-text-brand-on-bg-fill-hover': {value: colorsExperimental.gray[8]},
+  'color-text-brand-on-bg-fill': {value: colorsExperimental.gray[1]},
   'color-text-caution-active': {value: colorsExperimental.yellow[16]},
   'color-text-caution-hover': {value: colorsExperimental.yellow[15]},
-  'color-text-caution-on-fill': {value: colorsExperimental.yellow[15]},
-  'color-text-critical-on-fill': {value: colorsExperimental.red[1]},
-  'color-text-emphasis-on-fill-active': {value: colorsExperimental.blue[7]},
-  'color-text-emphasis-on-fill-hover': {value: colorsExperimental.blue[5]},
-  'color-text-emphasis-on-fill': {value: colorsExperimental.blue[1]},
+  'color-text-caution-on-bg-fill': {value: colorsExperimental.yellow[15]},
+  'color-text-critical-on-bg-fill': {value: colorsExperimental.red[1]},
+  'color-text-emphasis-on-bg-fill-active': {value: colorsExperimental.blue[7]},
+  'color-text-emphasis-on-bg-fill-hover': {value: colorsExperimental.blue[5]},
+  'color-text-emphasis-on-bg-fill': {value: colorsExperimental.blue[1]},
   'color-text-info-active': {value: colorsExperimental.azure[16]},
   'color-text-info-hover': {value: colorsExperimental.azure[15]},
-  'color-text-magic-on-fill': {value: colorsExperimental.purple[1]},
+  'color-text-magic-on-bg-fill': {value: colorsExperimental.purple[1]},
   'color-text-success-active': {value: colorsExperimental.green[16]},
   'color-text-success-hover': {value: colorsExperimental.green[15]},
-  'color-text-success-on-fill': {value: colorsExperimental.green[1]},
+  'color-text-success-on-bg-fill': {value: colorsExperimental.green[1]},
   'color-text-warning-active': {value: colorsExperimental.orange[16]},
   'color-text-warning-hover': {value: colorsExperimental.orange[15]},
-  'color-text-warning-on-fill': {value: colorsExperimental.orange[16]},
-  'color-video-thumbnail-play-button-fill-hover': {
+  'color-text-warning-on-bg-fill': {value: colorsExperimental.orange[16]},
+  'color-video-thumbnail-play-button-bg-fill-hover': {
     value: colorsExperimental.blackAlpha[15],
   },
-  'color-video-thumbnail-play-button-fill': {
+  'color-video-thumbnail-play-button-bg-fill': {
     value: colorsExperimental.blackAlpha[14],
   },
-  'color-video-thumbnail-play-button-text-on-fill': {
+  'color-video-thumbnail-play-button-text-on-bg-fill': {
     value: colorsExperimental.gray[1],
   },
   // ------------------------------
   // Net new tokens (overridden in light-uplift)
   // ------------------------------
-  'color-surface': {value: createVar('color-bg')},
-  'color-surface-hover': {value: colorsExperimental.gray[4]},
-  'color-surface-active': {value: colorsExperimental.gray[5]},
-  'color-surface-disabled': {value: colorsExperimental.blackAlpha[5]},
-  'color-surface-secondary': {value: createVar('color-bg-subdued')},
-  'color-surface-secondary-hover': {
+  'color-bg-surface': {value: createVar('color-bg')},
+  'color-bg-surface-hover': {value: colorsExperimental.gray[4]},
+  'color-bg-surface-active': {value: colorsExperimental.gray[5]},
+  'color-bg-surface-disabled': {value: colorsExperimental.blackAlpha[5]},
+  'color-bg-surface-secondary': {value: createVar('color-bg-subdued')},
+  'color-bg-surface-secondary-hover': {
     value: createVar('color-bg-subdued-hover'),
   },
-  'color-surface-secondary-active': {
+  'color-bg-surface-secondary-active': {
     value: createVar('color-bg-subdued-active'),
   },
-  'color-surface-tertiary': {
+  'color-bg-surface-tertiary': {
     value: createVar('color-bg-secondary-experimental'),
   },
-  'color-fill-tertiary': {value: createVar('color-bg-strong')},
-  'color-fill-tertiary-hover': {value: createVar('color-bg-strong-hover')},
-  'color-fill-tertiary-active': {value: createVar('color-bg-strong-active')},
-  'color-input-surface': {value: createVar('color-bg-input')},
-  'color-input-surface-hover': {
+  'color-bg-fill-tertiary': {value: createVar('color-bg-strong')},
+  'color-bg-fill-tertiary-hover': {value: createVar('color-bg-strong-hover')},
+  'color-bg-fill-tertiary-active': {value: createVar('color-bg-strong-active')},
+  'color-input-bg-surface': {value: createVar('color-bg-input')},
+  'color-input-bg-surface-hover': {
     value: createVar('color-bg-input-hover-experimental'),
   },
-  'color-input-surface-active': {
+  'color-input-bg-surface-active': {
     value: createVar('color-bg-input-active-experimental'),
   },
-  'color-fill-brand': {value: colorsExperimental.gray[15]},
-  'color-fill-brand-hover': {value: colorsExperimental.gray[16]},
-  'color-fill-brand-active': {value: colorsExperimental.gray[16]},
-  'color-surface-brand': {value: colorsExperimental.gray[8]},
-  'color-surface-brand-hover': {value: colorsExperimental.gray[7]},
-  'color-surface-brand-active': {value: colorsExperimental.gray[6]},
-  'color-surface-brand-selected': {value: colorsExperimental.gray[6]},
-  'color-surface-selected': {value: createVar('color-bg-app-selected')},
-  'color-fill-success': {value: createVar('color-bg-success-strong')},
-  'color-fill-success-hover': {
+  'color-bg-fill-brand': {value: colorsExperimental.gray[15]},
+  'color-bg-fill-brand-hover': {value: colorsExperimental.gray[16]},
+  'color-bg-fill-brand-active': {value: colorsExperimental.gray[16]},
+  'color-bg-surface-brand': {value: colorsExperimental.gray[8]},
+  'color-bg-surface-brand-hover': {value: colorsExperimental.gray[7]},
+  'color-bg-surface-brand-active': {value: colorsExperimental.gray[6]},
+  'color-bg-surface-brand-selected': {value: colorsExperimental.gray[6]},
+  'color-bg-surface-selected': {value: createVar('color-bg-app-selected')},
+  'color-bg-fill-success': {value: createVar('color-bg-success-strong')},
+  'color-bg-fill-success-hover': {
     value: createVar('color-bg-success-strong-hover-experimental'),
   },
-  'color-fill-success-active': {
+  'color-bg-fill-success-active': {
     value: createVar('color-bg-success-strong-active-experimental'),
   },
-  'color-fill-success-secondary': {value: createVar('color-bg-success')},
-  'color-surface-success': {value: createVar('color-bg-success-subdued')},
-  'color-surface-success-hover': {
+  'color-bg-fill-success-secondary': {value: createVar('color-bg-success')},
+  'color-bg-surface-success': {value: createVar('color-bg-success-subdued')},
+  'color-bg-surface-success-hover': {
     value: createVar('color-bg-success-subdued-hover'),
   },
-  'color-surface-success-active': {
+  'color-bg-surface-success-active': {
     value: createVar('color-bg-success-subdued-active'),
   },
-  'color-fill-critical': {value: createVar('color-bg-critical-strong')},
-  'color-fill-critical-hover': {
+  'color-bg-fill-critical': {value: createVar('color-bg-critical-strong')},
+  'color-bg-fill-critical-hover': {
     value: createVar('color-bg-critical-strong-hover'),
   },
-  'color-fill-critical-active': {
+  'color-bg-fill-critical-active': {
     value: createVar('color-bg-critical-strong-active'),
   },
-  'color-fill-critical-secondary': {value: createVar('color-bg-critical')},
-  'color-surface-critical': {value: createVar('color-bg-critical-subdued')},
-  'color-surface-critical-hover': {
+  'color-bg-fill-critical-secondary': {value: createVar('color-bg-critical')},
+  'color-bg-surface-critical': {value: createVar('color-bg-critical-subdued')},
+  'color-bg-surface-critical-hover': {
     value: createVar('color-bg-critical-subdued-hover'),
   },
-  'color-surface-critical-active': {
+  'color-bg-surface-critical-active': {
     value: createVar('color-bg-critical-subdued-active'),
   },
-  'color-fill-caution': {value: createVar('color-bg-caution-strong')},
-  'color-fill-caution-secondary': {value: createVar('color-bg-caution')},
-  'color-surface-caution': {value: createVar('color-bg-caution-subdued')},
-  'color-surface-caution-hover': {
+  'color-bg-fill-caution': {value: createVar('color-bg-caution-strong')},
+  'color-bg-fill-caution-secondary': {value: createVar('color-bg-caution')},
+  'color-bg-surface-caution': {value: createVar('color-bg-caution-subdued')},
+  'color-bg-surface-caution-hover': {
     value: createVar('color-bg-caution-subdued-hover'),
   },
-  'color-surface-caution-active': {
+  'color-bg-surface-caution-active': {
     value: createVar('color-bg-caution-subdued-active'),
   },
-  'color-fill-info': {value: createVar('color-bg-info-strong')},
-  'color-fill-info-secondary': {value: createVar('color-bg-info')},
-  'color-surface-info': {value: createVar('color-bg-info-subdued')},
-  'color-surface-info-hover': {
+  'color-bg-fill-info': {value: createVar('color-bg-info-strong')},
+  'color-bg-fill-info-secondary': {value: createVar('color-bg-info')},
+  'color-bg-surface-info': {value: createVar('color-bg-info-subdued')},
+  'color-bg-surface-info-hover': {
     value: createVar('color-bg-info-subdued-hover'),
   },
-  'color-surface-info-active': {
+  'color-bg-surface-info-active': {
     value: createVar('color-bg-info-subdued-active'),
   },
-  'color-fill-warning': {
+  'color-bg-fill-warning': {
     value: createVar('color-bg-warning-strong-experimental'),
   },
-  'color-fill-warning-secondary': {value: createVar('color-bg-warning')},
-  'color-surface-warning': {
+  'color-bg-fill-warning-secondary': {value: createVar('color-bg-warning')},
+  'color-bg-surface-warning': {
     value: createVar('color-bg-warning-subdued-experimental'),
   },
-  'color-fill-magic': {value: createVar('color-bg-magic-strong')},
-  'color-fill-magic-secondary': {value: createVar('color-bg-magic')},
-  'color-fill-magic-secondary-hover': {
+  'color-bg-fill-magic': {value: createVar('color-bg-magic-strong')},
+  'color-bg-fill-magic-secondary': {value: createVar('color-bg-magic')},
+  'color-bg-fill-magic-secondary-hover': {
     value: createVar('color-bg-magic-hover'),
   },
-  'color-fill-magic-secondary-active': {
+  'color-bg-fill-magic-secondary-active': {
     value: createVar('color-bg-magic-active'),
   },
-  'color-surface-magic': {value: colorsExperimental.purple[3]},
-  'color-surface-magic-hover': {
+  'color-bg-surface-magic': {value: colorsExperimental.purple[3]},
+  'color-bg-surface-magic-hover': {
     value: createVar('color-bg-magic-subdued-hover'),
   },
-  'color-fill-secondary': {value: createVar('color-bg-inset')},
-  'color-fill-inverse': {value: createVar('color-bg-inset-strong')},
-  'color-fill-inverse-hover': {value: createVar('color-bg-inverse-hover')},
-  'color-fill-inverse-active': {value: createVar('color-bg-inverse-active')},
-  'color-surface-transparent': {
+  'color-bg-fill-secondary': {value: createVar('color-bg-inset')},
+  'color-bg-fill-inverse': {value: createVar('color-bg-inset-strong')},
+  'color-bg-fill-inverse-hover': {value: createVar('color-bg-inverse-hover')},
+  'color-bg-fill-inverse-active': {value: createVar('color-bg-inverse-active')},
+  'color-bg-surface-transparent': {
     value: createVar('color-bg-transparent-experimental'),
   },
-  'color-fill-transparent-hover': {
+  'color-bg-fill-transparent-hover': {
     value: createVar('color-bg-transparent-hover-experimental'),
   },
-  'color-fill-transparent-active': {
+  'color-bg-fill-transparent-active': {
     value: createVar('color-bg-transparent-active-experimental'),
   },
-  'color-fill-disabled': {
+  'color-bg-fill-disabled': {
     value: createVar('color-bg-transparent-disabled-experimental'),
   },
-  'color-fill-transparent-secondary': {
+  'color-bg-fill-transparent-secondary': {
     value: createVar('color-bg-transparent-subdued-experimental'),
   },
-  'color-fill-brand-disabled': {
+  'color-bg-fill-brand-disabled': {
     value: createVar('color-bg-transparent-primary-disabled-experimental'),
   },
   'color-backdrop-bg': {value: createVar('color-bg-backdrop-experimental')},
-  'color-avatar-fill': {
+  'color-avatar-bg-fill': {
     value: createVar('color-avatar-background-experimental'),
   },
-  'color-avatar-one-fill': {
+  'color-avatar-one-bg-fill': {
     value: createVar('color-avatar-style-one-background-experimental'),
   },
-  'color-avatar-two-fill': {
+  'color-avatar-two-bg-fill': {
     value: createVar('color-avatar-style-two-background-experimental'),
   },
-  'color-avatar-three-fill': {
+  'color-avatar-three-bg-fill': {
     value: createVar('color-avatar-style-three-background-experimental'),
   },
-  'color-avatar-four-fill': {
+  'color-avatar-four-bg-fill': {
     value: createVar('color-avatar-style-four-background-experimental'),
   },
-  'color-avatar-five-fill': {
+  'color-avatar-five-bg-fill': {
     value: createVar('color-avatar-style-five-background-experimental'),
   },
   'color-text-secondary': {value: createVar('color-text-subdued')},
@@ -654,28 +647,28 @@ export const color: {
   'color-text-brand': {value: createVar('color-text-primary')},
   'color-text-brand-hover': {value: createVar('color-text-primary-hover')},
   'color-text-critical-hover': {value: colorsExperimental.red[15]},
-  'color-text-info-on-fill': {value: createVar('color-text-info-strong')},
+  'color-text-info-on-bg-fill': {value: createVar('color-text-info-strong')},
   'color-text-warning': {value: colorsExperimental.orange[14]},
   'color-text-inverse-secondary': {
     value: createVar('color-text-inverse-subdued'),
   },
-  'color-link-inverse': {value: colorsExperimental.blue[8]},
-  'color-avatar-text-on-fill': {
+  'color-text-link-inverse': {value: colorsExperimental.blue[8]},
+  'color-avatar-text-on-bg-fill': {
     value: createVar('color-avatar-color-experimental'),
   },
-  'color-avatar-one-text-on-fill': {
+  'color-avatar-one-text-on-bg-fill': {
     value: createVar('color-avatar-style-one-color-experimental'),
   },
-  'color-avatar-two-text-on-fill': {
+  'color-avatar-two-text-on-bg-fill': {
     value: createVar('color-avatar-style-two-color-experimental'),
   },
-  'color-avatar-three-text-on-fill': {
+  'color-avatar-three-text-on-bg-fill': {
     value: createVar('color-avatar-style-three-color-experimental'),
   },
-  'color-avatar-four-text-on-fill': {
+  'color-avatar-four-text-on-bg-fill': {
     value: createVar('color-avatar-style-four-color-experimental'),
   },
-  'color-avatar-five-text-on-fill': {
+  'color-avatar-five-text-on-bg-fill': {
     value: createVar('color-avatar-style-five-color-experimental'),
   },
   'color-icon-secondary': {value: createVar('color-icon-subdued')},

From 872104e3eee541b9cdaad7328eceabd22f062f99 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Mon, 18 Sep 2023 18:04:33 -0700
Subject: [PATCH 18/19] Consolidate surface and fill to background alias in
 light-uplift theme

---
 polaris-tokens/src/themes/light-uplift.ts | 134 +++++++++++-----------
 1 file changed, 67 insertions(+), 67 deletions(-)

diff --git a/polaris-tokens/src/themes/light-uplift.ts b/polaris-tokens/src/themes/light-uplift.ts
index fba7dd22599..ea7122aea2e 100644
--- a/polaris-tokens/src/themes/light-uplift.ts
+++ b/polaris-tokens/src/themes/light-uplift.ts
@@ -22,81 +22,81 @@ export const metaThemeLightUpliftPartial = createMetaThemePartial({
   },
   color: {
     // v12.0.0
-    'color-surface': {value: colors.gray[1]},
-    'color-surface-secondary': {value: colors.gray[4]},
-    'color-surface-secondary-hover': {value: colors.gray[6]},
-    'color-surface-secondary-active': {value: colors.gray[7]},
-    'color-surface-tertiary': {value: colors.gray[5]},
-    'color-fill-tertiary': {value: colors.gray[8]},
-    'color-fill-tertiary-hover': {value: colors.gray[9]},
-    'color-fill-tertiary-active': {value: colors.gray[10]},
-    'color-input-surface': {value: colors.gray[2]},
-    'color-input-surface-hover': {value: colors.gray[3]},
-    'color-input-surface-active': {value: colors.gray[4]},
-    'color-surface-selected': {value: colors.gray[3]},
-    'color-fill-success': {value: colors.green[12]},
-    'color-fill-success-hover': {value: colors.green[13]},
-    'color-fill-success-active': {value: colors.green[14]},
-    'color-fill-success-secondary': {value: colors.green[3]},
-    'color-surface-success': {value: colors.green[3]},
-    'color-surface-success-hover': {value: colors.green[4]},
-    'color-surface-success-active': {value: colors.green[5]},
-    'color-fill-critical': {value: colors.red[12]},
-    'color-fill-critical-hover': {value: colors.red[13]},
-    'color-fill-critical-active': {value: colors.red[14]},
-    'color-fill-critical-secondary': {value: colors.red[6]},
-    'color-surface-critical': {value: colors.red[4]},
-    'color-surface-critical-hover': {value: colors.red[5]},
-    'color-surface-critical-active': {value: colors.red[6]},
-    'color-fill-caution': {value: colors.yellow[6]},
-    'color-fill-caution-secondary': {value: colors.yellow[4]},
-    'color-surface-caution': {value: colors.yellow[2]},
-    'color-surface-caution-hover': {value: colors.yellow[3]},
-    'color-surface-caution-active': {value: colors.yellow[4]},
-    'color-fill-info': {value: colors.azure[9]},
-    'color-fill-info-secondary': {value: colors.azure[4]},
-    'color-surface-info': {value: colors.azure[3]},
-    'color-surface-info-hover': {value: colors.azure[4]},
-    'color-surface-info-active': {value: colors.azure[6]},
-    'color-fill-warning': {value: colors.orange[9]},
-    'color-fill-warning-secondary': {value: colors.orange[7]},
-    'color-surface-warning': {value: colors.orange[3]},
-    'color-fill-magic': {value: colors.purple[12]},
-    'color-fill-magic-secondary': {value: colors.purple[6]},
-    'color-fill-magic-secondary-hover': {value: colors.purple[7]},
-    'color-fill-magic-secondary-active': {value: colors.purple[8]},
-    'color-surface-magic-hover': {value: colors.purple[4]},
-    'color-fill-secondary': {value: colors.gray[6]},
-    'color-fill-inverse': {value: colors.gray[15]},
-    'color-fill-inverse-hover': {value: colors.gray[14]},
-    'color-fill-inverse-active': {value: colors.gray[13]},
-    'color-surface-transparent': {value: colors.blackAlpha[1]},
-    'color-fill-transparent-hover': {value: colors.blackAlpha[5]},
-    'color-fill-transparent-active': {value: colors.blackAlpha[6]},
-    'color-fill-disabled': {value: colors.blackAlpha[5]},
-    'color-fill-transparent-secondary': {value: colors.blackAlpha[6]},
-    'color-fill-brand-disabled': {value: colors.blackAlpha[9]},
+    'color-bg-surface': {value: colors.gray[1]},
+    'color-bg-surface-secondary': {value: colors.gray[4]},
+    'color-bg-surface-secondary-hover': {value: colors.gray[6]},
+    'color-bg-surface-secondary-active': {value: colors.gray[7]},
+    'color-bg-surface-tertiary': {value: colors.gray[5]},
+    'color-bg-fill-tertiary': {value: colors.gray[8]},
+    'color-bg-fill-tertiary-hover': {value: colors.gray[9]},
+    'color-bg-fill-tertiary-active': {value: colors.gray[10]},
+    'color-input-bg-surface': {value: colors.gray[2]},
+    'color-input-bg-surface-hover': {value: colors.gray[3]},
+    'color-input-bg-surface-active': {value: colors.gray[4]},
+    'color-bg-surface-selected': {value: colors.gray[3]},
+    'color-bg-fill-success': {value: colors.green[12]},
+    'color-bg-fill-success-hover': {value: colors.green[13]},
+    'color-bg-fill-success-active': {value: colors.green[14]},
+    'color-bg-fill-success-secondary': {value: colors.green[3]},
+    'color-bg-surface-success': {value: colors.green[3]},
+    'color-bg-surface-success-hover': {value: colors.green[4]},
+    'color-bg-surface-success-active': {value: colors.green[5]},
+    'color-bg-fill-critical': {value: colors.red[12]},
+    'color-bg-fill-critical-hover': {value: colors.red[13]},
+    'color-bg-fill-critical-active': {value: colors.red[14]},
+    'color-bg-fill-critical-secondary': {value: colors.red[6]},
+    'color-bg-surface-critical': {value: colors.red[4]},
+    'color-bg-surface-critical-hover': {value: colors.red[5]},
+    'color-bg-surface-critical-active': {value: colors.red[6]},
+    'color-bg-fill-caution': {value: colors.yellow[6]},
+    'color-bg-fill-caution-secondary': {value: colors.yellow[4]},
+    'color-bg-surface-caution': {value: colors.yellow[2]},
+    'color-bg-surface-caution-hover': {value: colors.yellow[3]},
+    'color-bg-surface-caution-active': {value: colors.yellow[4]},
+    'color-bg-fill-info': {value: colors.azure[9]},
+    'color-bg-fill-info-secondary': {value: colors.azure[4]},
+    'color-bg-surface-info': {value: colors.azure[3]},
+    'color-bg-surface-info-hover': {value: colors.azure[4]},
+    'color-bg-surface-info-active': {value: colors.azure[6]},
+    'color-bg-fill-warning': {value: colors.orange[9]},
+    'color-bg-fill-warning-secondary': {value: colors.orange[7]},
+    'color-bg-surface-warning': {value: colors.orange[3]},
+    'color-bg-fill-magic': {value: colors.purple[12]},
+    'color-bg-fill-magic-secondary': {value: colors.purple[6]},
+    'color-bg-fill-magic-secondary-hover': {value: colors.purple[7]},
+    'color-bg-fill-magic-secondary-active': {value: colors.purple[8]},
+    'color-bg-surface-magic-hover': {value: colors.purple[4]},
+    'color-bg-fill-secondary': {value: colors.gray[6]},
+    'color-bg-fill-inverse': {value: colors.gray[15]},
+    'color-bg-fill-inverse-hover': {value: colors.gray[14]},
+    'color-bg-fill-inverse-active': {value: colors.gray[13]},
+    'color-bg-surface-transparent': {value: colors.blackAlpha[1]},
+    'color-bg-fill-transparent-hover': {value: colors.blackAlpha[5]},
+    'color-bg-fill-transparent-active': {value: colors.blackAlpha[6]},
+    'color-bg-fill-disabled': {value: colors.blackAlpha[5]},
+    'color-bg-fill-transparent-secondary': {value: colors.blackAlpha[6]},
+    'color-bg-fill-brand-disabled': {value: colors.blackAlpha[9]},
     'color-backdrop-bg': {value: colors.blackAlpha[14]},
-    'color-avatar-fill': {value: colors.gray[11]},
-    'color-avatar-one-fill': {value: colors.magenta[7]},
-    'color-avatar-two-fill': {value: colors.green[7]},
-    'color-avatar-three-fill': {value: colors.cyan[7]},
-    'color-avatar-four-fill': {value: colors.azure[7]},
-    'color-avatar-five-fill': {value: colors.rose[7]},
+    'color-avatar-bg-fill': {value: colors.gray[11]},
+    'color-avatar-one-bg-fill': {value: colors.magenta[7]},
+    'color-avatar-two-bg-fill': {value: colors.green[7]},
+    'color-avatar-three-bg-fill': {value: colors.cyan[7]},
+    'color-avatar-four-bg-fill': {value: colors.azure[7]},
+    'color-avatar-five-bg-fill': {value: colors.rose[7]},
     'color-text-secondary': {value: colors.gray[13]},
     'color-text-emphasis': {value: colors.blue[13]},
     'color-text-emphasis-hover': {value: colors.blue[14]},
     'color-text-emphasis-active': {value: colors.blue[15]},
     'color-text-brand': {value: colors.gray[14]},
     'color-text-brand-hover': {value: colors.gray[15]},
-    'color-text-info-on-fill': {value: colors.azure[16]},
+    'color-text-info-on-bg-fill': {value: colors.azure[16]},
     'color-text-inverse-secondary': {value: colors.gray[11]},
-    'color-avatar-text-on-fill': {value: colors.gray[1]},
-    'color-avatar-one-text-on-fill': {value: colors.magenta[14]},
-    'color-avatar-two-text-on-fill': {value: colors.green[14]},
-    'color-avatar-three-text-on-fill': {value: colors.cyan[14]},
-    'color-avatar-four-text-on-fill': {value: colors.azure[14]},
-    'color-avatar-five-text-on-fill': {value: colors.rose[14]},
+    'color-avatar-text-on-bg-fill': {value: colors.gray[1]},
+    'color-avatar-one-text-on-bg-fill': {value: colors.magenta[14]},
+    'color-avatar-two-text-on-bg-fill': {value: colors.green[14]},
+    'color-avatar-three-text-on-bg-fill': {value: colors.cyan[14]},
+    'color-avatar-four-text-on-bg-fill': {value: colors.azure[14]},
+    'color-avatar-five-text-on-bg-fill': {value: colors.rose[14]},
     'color-icon-secondary': {value: colors.gray[12]},
     'color-icon-emphasis': {value: colors.blue[13]},
     'color-icon-emphasis-hover': {value: colors.blue[14]},

From 2d87db3c7e15699ca56b4fd61a38ed8ed7222873 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Date: Tue, 19 Sep 2023 14:04:12 -0700
Subject: [PATCH 19/19] Update comments

---
 polaris-tokens/src/themes/base/color.ts | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/polaris-tokens/src/themes/base/color.ts b/polaris-tokens/src/themes/base/color.ts
index 850b98b99e0..d0ebd086e7f 100644
--- a/polaris-tokens/src/themes/base/color.ts
+++ b/polaris-tokens/src/themes/base/color.ts
@@ -164,7 +164,7 @@ export type ColorBackgroundAlias =
   | 'bg-fill-transparent-secondary-hover'
   | 'bg-fill-transparent-secondary-active'
   | ColorBackgroundAliasExperimental
-  /** Specialty and component backgrounds. */
+  /** Specialty and component background colors. */
   | 'nav-bg'
   | 'backdrop-bg'
   | 'input-bg-surface'
@@ -227,7 +227,7 @@ export type ColorBorderAlias =
   | 'border-emphasis-hover'
   | 'border-emphasis-active'
   | ColorBorderAliasExperimental
-  /** Specialty and component borders. */
+  /** Specialty and component border colors. */
   | 'input-border'
   | 'input-border-hover'
   | 'input-border-active';
@@ -260,10 +260,7 @@ export type ColorIconAlias =
   | 'icon-emphasis-hover'
   | 'icon-emphasis-active'
   | ColorIconAliasExperimental
-  /** Check on emphasis state icons. */
-  | 'icon-emphasis-hover'
-  | 'icon-emphasis-active'
-  /** Specialty and component icons. */
+  /** Specialty and component icon colors. */
   | 'radio-button-icon-disabled'
   | 'checkbox-icon-disabled';