feat: Extend ThemeBuilder with reference token processing

Author: jkuelz

src/browser/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "lib": ["es5", "es2015.collection", "dom"],
+    "lib": ["es2017", "dom"],
     "types": [],
     "module": "esnext",
     "moduleResolution": "node",

src/build/index.ts

@@ -13,4 +13,9 @@ export {
   Value,
   resolveTheme,
   resolveThemeWithPaths,
+  ReferenceTokens,
+  ColorReferenceTokens,
+  ColorPaletteInput,
+  ColorPaletteDefinition,
+  PaletteStep,
 } from '../shared/theme';

src/shared/theme/builder.ts

@@ -1,6 +1,14 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { Theme, Context, Mode } from './interfaces';
+import {
+  Theme,
+  Context,
+  Mode,
+  ReferenceTokens,
+  ColorReferenceTokens,
+  ColorPaletteInput,
+  PaletteStep,
+} from './interfaces';
 
 export type TokenCategory<T extends string, V> = Record<T, V>;
 
@@ -46,7 +54,93 @@ export class ThemeBuilder {
     return this;
   }
 
+  addReferenceTokens(referenceTokens: ReferenceTokens): ThemeBuilder {
+    this.theme.referenceTokens = referenceTokens;
+
+    // Process reference tokens and add generated tokens to theme
+    if (referenceTokens.color) {
+      const generatedTokens = this.processReferenceTokens(referenceTokens.color);
+      this.theme.tokens = { ...this.theme.tokens, ...generatedTokens };
+    }
+
+    return this;
+  }
+
   build(): Theme {
     return this.theme;
   }
+
+  private processReferenceTokens(colorTokens: ColorReferenceTokens): Record<string, string> {
+    const generatedTokens: Record<string, string> = {};
+
+    Object.entries(colorTokens).forEach(([colorName, paletteInput]) => {
+      const palette = this.processColorPaletteInput(paletteInput);
+
+      // Add generated palette tokens with naming convention: colorPrimary50, colorPrimary600, etc.
+      Object.entries(palette).forEach(([step, value]) => {
+        const tokenName = `color${this.capitalize(colorName)}${step}`;
+        generatedTokens[tokenName] = value;
+      });
+    });
+
+    return generatedTokens;
+  }
+
+  private processColorPaletteInput(input: ColorPaletteInput): Record<PaletteStep, string> {
+    if (typeof input === 'string') {
+      // Simple seed case: generate basic palette from seed
+      return this.generateBasicPalette(input);
+    } else {
+      // Complex case: object with seed and/or explicit step values
+      const validSteps = [
+        50, 100, 150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, 800, 850, 900, 950, 1000,
+      ];
+
+      // Start with generated palette if seed is provided, otherwise empty
+      const result: Record<PaletteStep, string> = input.seed
+        ? this.generateBasicPalette(input.seed)
+        : ({} as Record<PaletteStep, string>);
+
+      // Override with explicit step values
+      Object.entries(input).forEach(([step, value]) => {
+        const numStep = Number(step);
+        if (step !== 'seed' && value && validSteps.includes(numStep)) {
+          result[numStep as PaletteStep] = value;
+        }
+      });
+
+      return result;
+    }
+  }
+
+  private generateBasicPalette(seed: string): Record<PaletteStep, string> {
+    // Placeholder implementation - will be replaced with HCT generation later
+    // For now, just return the seed color for all steps to establish the plumbing
+    return {
+      50: seed,
+      100: seed,
+      150: seed,
+      200: seed,
+      250: seed,
+      300: seed,
+      350: seed,
+      400: seed,
+      450: seed,
+      500: seed,
+      550: seed,
+      600: seed,
+      650: seed,
+      700: seed,
+      750: seed,
+      800: seed,
+      850: seed,
+      900: seed,
+      950: seed,
+      1000: seed,
+    };
+  }
+
+  private capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
 }

src/shared/theme/index.ts

@@ -11,6 +11,11 @@ export {
   GlobalValue,
   ModeValue,
   TypedModeValueOverride,
+  ReferenceTokens,
+  ColorReferenceTokens,
+  ColorPaletteInput,
+  ColorPaletteDefinition,
+  PaletteStep,
 } from './interfaces';
 export { ThemeBuilder, TokenCategory } from './builder';
 export {

src/shared/theme/interfaces.ts

@@ -35,6 +35,62 @@ export interface Theme {
   modes: Record<string, Mode>;
   tokenModeMap: Record<string, string>;
   contexts: Record<string, Context>;
+  referenceTokens?: ReferenceTokens;
+}
+
+/**
+ * Reference tokens enable seed-based palette generation and semantic token organization.
+ */
+export interface ReferenceTokens {
+  color?: ColorReferenceTokens;
+}
+
+export interface ColorReferenceTokens {
+  primary?: ColorPaletteInput;
+  neutral?: ColorPaletteInput;
+  error?: ColorPaletteInput;
+  success?: ColorPaletteInput;
+  warning?: ColorPaletteInput;
+  info?: ColorPaletteInput;
+}
+
+/**
+ * Color reference tokens organized by semantic color categories.
+ * Each category can be defined using a seed color (string) or detailed palette definition.
+ */
+export type ColorPaletteInput = string | ColorPaletteDefinition;
+
+/**
+ * Palette steps available across all color types. Different color categories
+ * may use different subsets of these steps.
+ */
+export type PaletteStep =
+  | 50
+  | 100
+  | 150
+  | 200
+  | 250
+  | 300
+  | 350
+  | 400
+  | 450
+  | 500
+  | 550
+  | 600
+  | 650
+  | 700
+  | 750
+  | 800
+  | 850
+  | 900
+  | 950
+  | 1000;
+
+/**
+ * Color palette definition supporting both seed generation and explicit overrides.
+ */
+export interface ColorPaletteDefinition extends Partial<Record<PaletteStep, string>> {
+  seed?: string;
 }
 
 type Tokens = Partial<Record<string, GlobalValue | TypedModeValueOverride>>;