chore: Add reference tokens and replace legacy color tokens in style dictionary (#3952)

Author: jkuelz

build-tools/eslint/index.js

@@ -3,4 +3,5 @@
 module.exports.rules = {
   'ban-files': require('./ban-files'),
   'prefer-live-region': require('./prefer-live-region'),
+  'no-legacy-tokens': require('./no-legacy-tokens'),
 };

build-tools/eslint/no-legacy-tokens.js

@@ -0,0 +1,61 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+const LEGACY_TOKEN_PATTERN = /\{color(Grey|Blue|Green|Red|Yellow)\d+\}/g;
+const REFERENCE_TOKEN_SUGGESTIONS = {
+  colorGrey: 'colorNeutral',
+  colorBlue: 'colorPrimary or colorInfo',
+  colorGreen: 'colorSuccess',
+  colorRed: 'colorError',
+  colorYellow: 'colorWarning',
+};
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      'no-legacy-tokens':
+        'Direct palette token {{token}} is deprecated. Use reference tokens like {{suggestion}} instead.',
+    },
+    docs: {
+      description: 'Prevents use of legacy color palette tokens in favor of semantic reference tokens.',
+    },
+    fixable: 'code',
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (typeof node.value === 'string') {
+          const matches = node.value.match(LEGACY_TOKEN_PATTERN);
+          if (matches) {
+            matches.forEach(token => {
+              const colorFamily = token.match(/color(Grey|Blue|Green|Red|Yellow)/)?.[1];
+              const suggestion = REFERENCE_TOKEN_SUGGESTIONS[`color${colorFamily}`] || 'semantic reference tokens';
+
+              context.report({
+                node,
+                messageId: 'no-legacy-tokens',
+                data: { token, suggestion },
+              });
+            });
+          }
+        }
+      },
+      TemplateElement(node) {
+        const matches = node.value.raw.match(LEGACY_TOKEN_PATTERN);
+        if (matches) {
+          matches.forEach(token => {
+            const colorFamily = token.match(/color(Grey|Blue|Green|Red|Yellow)/)?.[1];
+            const suggestion = REFERENCE_TOKEN_SUGGESTIONS[`color${colorFamily}`] || 'semantic reference tokens';
+
+            context.report({
+              node,
+              messageId: 'no-legacy-tokens',
+              data: { token, suggestion },
+            });
+          });
+        }
+      },
+    };
+  },
+};

eslint.config.mjs

@@ -133,6 +133,7 @@ export default tsEslint.config(
           ],
         },
       ],
+      '@cloudscape-design/components/no-legacy-tokens': 'error',
     },
   },
   {

style-dictionary/classic/color-charts.ts

@@ -7,9 +7,9 @@ import { StyleDictionary } from '../utils/interfaces.js';
 import { tokens as parentTokens } from '../visual-refresh/color-charts.js';
 
 const tokens: StyleDictionary.ColorChartsDictionary = {
-  colorChartsLineGrid: { dark: '{colorGrey700}' },
-  colorChartsLineTick: { dark: '{colorGrey700}' },
-  colorChartsLineAxis: { dark: '{colorGrey700}' },
+  colorChartsLineGrid: { dark: '{colorNeutral700}' },
+  colorChartsLineTick: { dark: '{colorNeutral700}' },
+  colorChartsLineAxis: { dark: '{colorNeutral700}' },
 };
 
 const expandedTokens: StyleDictionary.ExpandedColorScopeDictionary = merge(

style-dictionary/classic/color-palette.ts

@@ -2,9 +2,21 @@
 // SPDX-License-Identifier: Apache-2.0
 import merge from 'lodash/merge.js';
 
+import { expandColorDictionary } from '../utils/index.js';
 import { StyleDictionary } from '../utils/interfaces.js';
 import { tokens as parentTokens } from '../visual-refresh/color-palette.js';
 
+/**
+ * @deprecated These color palette tokens are deprecated and may be removed in a future version.
+ * Use semantic reference tokens instead:
+ * - colorGrey* → colorNeutral*
+ * - colorBlue* → colorPrimary* or colorInfo*
+ * - colorRed* → colorError*
+ * - colorGreen* → colorSuccess*
+ * - colorYellow* → colorWarning*
+ *
+ * Reference tokens provide better semantic meaning and consistency across themes.
+ */
 const tokens: StyleDictionary.ColorPaletteDictionary = {
   colorBlue50: '#f1faff',
   colorBlue200: '#99cbe4',
@@ -38,6 +50,50 @@ const tokens: StyleDictionary.ColorPaletteDictionary = {
   colorYellow900: '#906806',
 };
 
-const expandedTokens: StyleDictionary.ExpandedGlobalScopeDictionary = merge({}, parentTokens, tokens);
+const referenceTokens: StyleDictionary.ReferenceDictionary = {
+  colorPrimary50: tokens.colorBlue50,
+  colorPrimary200: tokens.colorBlue200,
+  colorPrimary300: tokens.colorBlue300,
+  colorPrimary400: tokens.colorBlue400,
+  colorPrimary600: tokens.colorBlue600,
+  colorPrimary700: tokens.colorBlue700,
+  colorPrimary1000: tokens.colorBlue1000,
+  colorNeutral100: tokens.colorGrey100,
+  colorNeutral200: tokens.colorGrey200,
+  colorNeutral250: tokens.colorGrey250,
+  colorNeutral300: tokens.colorGrey300,
+  colorNeutral400: tokens.colorGrey400,
+  colorNeutral450: tokens.colorGrey450,
+  colorNeutral500: tokens.colorGrey500,
+  colorNeutral600: tokens.colorGrey600,
+  colorNeutral650: tokens.colorGrey650,
+  colorNeutral700: tokens.colorGrey700,
+  colorNeutral750: tokens.colorGrey750,
+  colorNeutral800: tokens.colorGrey800,
+  colorNeutral850: tokens.colorGrey850,
+  colorNeutral950: tokens.colorGrey950,
+  colorError50: tokens.colorRed50,
+  colorError400: tokens.colorRed400,
+  colorError600: tokens.colorRed600,
+  colorError1000: tokens.colorRed1000,
+  colorInfo50: tokens.colorBlue50,
+  colorInfo300: tokens.colorBlue300,
+  colorInfo400: tokens.colorBlue400,
+  colorInfo600: tokens.colorBlue600,
+  colorInfo1000: tokens.colorBlue1000,
+  colorSuccess50: tokens.colorGreen50,
+  colorSuccess500: tokens.colorGreen500,
+  colorSuccess600: tokens.colorGreen600,
+  colorSuccess1000: tokens.colorGreen1000,
+  colorWarning900: tokens.colorYellow900,
+};
+
+const expandedTokens: StyleDictionary.ExpandedColorScopeDictionary = merge(
+  {},
+  parentTokens,
+  tokens,
+  expandColorDictionary(referenceTokens)
+);
 
 export { expandedTokens as tokens };
+export const mode: StyleDictionary.ModeIdentifier = 'color';

style-dictionary/classic/color-severity.ts

@@ -7,7 +7,7 @@ import { StyleDictionary } from '../utils/interfaces.js';
 import { tokens as parentTokens } from '../visual-refresh/color-severity.js';
 
 const tokens: StyleDictionary.ColorSeverityDictionary = {
-  colorTextNotificationSeverityMedium: { light: '{colorBlack}', dark: '{colorGrey950}' },
+  colorTextNotificationSeverityMedium: { light: '{colorBlack}', dark: '{colorNeutral950}' },
 };
 
 const expandedTokens: StyleDictionary.ExpandedColorScopeDictionary = merge(