fix: ensure Figma base scale output includes all tokens for override themes (#1355)

* fix: ensure Figma base scale output includes all tokens for override themes

Override themes (dark-dimmed, dark-high-contrast, light-high-contrast)
inherit tokens from their parent theme. Previously, inherited tokens
retained the parent's Figma collection name (e.g. base/color/dark
instead of base/color/dark-dimmed), causing them to be missing from the
override theme's collection in Figma output.

Add collectionOverride support to the figmaAttributes transformer and
pass collection mappings for each override theme in buildFigma.ts.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add changeset

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lukasoppermann

.changeset/figma-collection-override.md

@@ -0,0 +1,5 @@
+---
+"@primer/primitives": patch
+---
+
+Fix Figma base scale output for override themes (dark-dimmed, dark-high-contrast, light-high-contrast) to include all tokens. Previously, inherited tokens (e.g. neutral, black, transparent) retained the parent theme's collection name and were missing from the override theme's Figma collection.

package-lock.json

@@ -26,6 +26,7 @@ const buildFigma = async (buildOptions: ConfigGeneratorOptions): Promise<void> =
         `src/tokens/base/color/light/display-light.json5`,
         `src/tokens/base/color/light/light.high-contrast.json5`,
       ],
+      collectionOverride: {'base/color/light': 'base/color/light-high-contrast'},
     },
     {
       name: 'dark',
@@ -40,6 +41,7 @@ const buildFigma = async (buildOptions: ConfigGeneratorOptions): Promise<void> =
         `src/tokens/base/color/dark/display-dark.json5`,
         `src/tokens/base/color/dark/dark.high-contrast.json5`,
       ],
+      collectionOverride: {'base/color/dark': 'base/color/dark-high-contrast'},
     },
     {
       theme: 'dark-dimmed',
@@ -49,14 +51,17 @@ const buildFigma = async (buildOptions: ConfigGeneratorOptions): Promise<void> =
         `src/tokens/base/color/dark/display-dark.json5`,
         `src/tokens/base/color/dark/dark.dimmed.json5`,
       ],
+      collectionOverride: {'base/color/dark': 'base/color/dark-dimmed'},
     },
   ]
 
-  for (const {name, source} of baseScales) {
+  for (const {name, source, collectionOverride} of baseScales) {
     const extended = await PrimerStyleDictionary.extend({
       source,
       platforms: {
-        figma: figma(`figma/scales/${name}.json`, buildOptions.prefix, buildOptions.buildPath),
+        figma: figma(`figma/scales/${name}.json`, buildOptions.prefix, buildOptions.buildPath, {
+          collectionOverride,
+        }),
       },
     })
     // build

scripts/buildFigma.ts

@@ -0,0 +1,97 @@
+import {figmaAttributes} from './figmaAttributes.js'
+import type {TransformedToken, PlatformConfig} from 'style-dictionary/types'
+
+describe('figmaAttributes', () => {
+  const baseToken = {
+    $extensions: {
+      'org.primer.figma': {
+        collection: 'base/color/dark',
+        scopes: ['bgColor'],
+        group: undefined,
+        codeSyntax: undefined,
+      },
+    },
+  } as unknown as TransformedToken
+
+  it('returns collection from token extensions', () => {
+    const result = figmaAttributes.transform(baseToken, {} as PlatformConfig)
+    expect(result).toMatchObject({
+      collection: 'base/color/dark',
+      group: 'base/color/dark',
+    })
+  })
+
+  it('applies collectionOverride when collection matches', () => {
+    const platform = {
+      options: {
+        collectionOverride: {'base/color/dark': 'base/color/dark-dimmed'},
+      },
+    } as unknown as PlatformConfig
+
+    const result = figmaAttributes.transform(baseToken, platform)
+    expect(result).toMatchObject({
+      collection: 'base/color/dark-dimmed',
+      group: 'base/color/dark-dimmed',
+    })
+  })
+
+  it('does not apply collectionOverride when collection does not match', () => {
+    const token = {
+      $extensions: {
+        'org.primer.figma': {
+          collection: 'base/color/dark-dimmed',
+          scopes: ['bgColor'],
+        },
+      },
+    } as unknown as TransformedToken
+
+    const platform = {
+      options: {
+        collectionOverride: {'base/color/dark': 'base/color/dark-dimmed'},
+      },
+    } as unknown as PlatformConfig
+
+    const result = figmaAttributes.transform(token, platform)
+    expect(result).toMatchObject({
+      collection: 'base/color/dark-dimmed',
+      group: 'base/color/dark-dimmed',
+    })
+  })
+
+  it('preserves explicit group when set', () => {
+    const token = {
+      $extensions: {
+        'org.primer.figma': {
+          collection: 'base/color/dark',
+          group: 'custom-group',
+          scopes: ['bgColor'],
+        },
+      },
+    } as unknown as TransformedToken
+
+    const platform = {
+      options: {
+        collectionOverride: {'base/color/dark': 'base/color/dark-dimmed'},
+      },
+    } as unknown as PlatformConfig
+
+    const result = figmaAttributes.transform(token, platform)
+    expect(result).toMatchObject({
+      collection: 'base/color/dark-dimmed',
+      group: 'custom-group',
+    })
+  })
+
+  it('uses theme for mode when available', () => {
+    const platform = {
+      options: {
+        theme: 'dark dimmed',
+      },
+    } as unknown as PlatformConfig
+
+    const result = figmaAttributes.transform(baseToken, platform)
+    expect(result).toMatchObject({
+      mode: 'dark dimmed',
+    })
+  })
+})

src/transformers/figmaAttributes.test.ts

@@ -71,10 +71,14 @@ export const figmaAttributes: Transform = {
   transform: (token: TransformedToken, platform: PlatformConfig = {}) => {
     const {modeOverride, collection, scopes, group, codeSyntax} = token.$extensions?.['org.primer.figma'] || {}
 
+    const collectionOverride = platform.options?.collectionOverride as Record<string, string> | undefined
+    const resolvedCollection =
+      collectionOverride && collection && collection in collectionOverride ? collectionOverride[collection] : collection
+
     return {
       mode: asArray(platform.options?.theme)[0] || modeOverride || 'default',
-      collection,
-      group: group || collection,
+      collection: resolvedCollection,
+      group: group || resolvedCollection,
       scopes: getScopes(scopes),
       codeSyntax,
     }