Preprocessor to allow token overrides within one token definition mainly for component tokens

[lukasoppermann]

Summary

Using a pre-processor allows us to define value overwrites on a token using the $extensions['org.primer.overrides'] property.

Schema

type themeString = "light" | "dark" | "dark-high-contrast" // | ...
type overrideObject = {
  $value?: DesignTokenValue
  $alpha?: number
}
  
{
  $extensions: {
    'org.primer.overrides': 
      {
        [theme: themeString]: overrideObject | string
      }
    
  }
}

topicTag: {
    borderColor: {
      $value: '{base.color.transparent}',
      $type: 'color',
      $extensions: {
        'org.primer.overrides': 
          {
          "light": {
              $value: '{base.color.neutral.10}',
            },
            dark: '{base.color.neutral.7}',
          },
      },
    },
  },

When building the tokens we need to provide a theme to the PlatformConfig options property, e.g.:

css: css(`css/${filename}.css`, options.prefix, options.buildPath, {
        themed: options.themed,
        themeOverrides: {
          theme: options.theme
        },
      }),

If a value with this theme is defined on the token, it will be used, otherwise the "default" $value will be used.

The benefit of using a pre-processor to other solutions is, that the token can still be transformed normally in the transformation flow. No custom code is required, contributors don't need to understand preprocessors or how this works, to add contributions to other parts.

List of notable changes:

[changeset-bot]

🦋 Changeset detected

Latest commit: e5d5522

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/primitives	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Design Token Diff (Figma)

/figma/figma.json

+++ /home/runner/work/primitives/primitives/dist/figma/figma.json	2024-12-05 13:43:54.049376057 +0000
@@ -101,14 +101,6 @@
     "groups": [
       "typography"
     ]
-    },
-    "undefined": {
-      "modes": [
-        null
-      ],
-      "groups": [
-        null
-      ]
   }
 },
 "files": [