[Major] New neutral scales (#1016)

* base

* dark

* light

* kick off ci

* Create funny-llamas-hunt.md

* github-actions[bot] Regenerated snapshots

* shadows

* adjustments per vrt

* github-actions[bot] Regenerated snapshots

* fix hover state

* adr

* lint

* changelog

* lint

* cleanup

* fix

* fix missing type

* cleanup

* github-actions[bot] Regenerated snapshots

* fix danger button rest border

* github-actions[bot] Regenerated snapshots

* update transparent selected bg

* reset

* fix

* github-actions[bot] Regenerated snapshots

* change invisible to muted

* reset

* github-actions[bot] Regenerated snapshots

---------

Co-authored-by: langermank <langermank@users.noreply.github.com>

.changeset/funny-llamas-hunt.md

@@ -0,0 +1,91 @@
+---
+"@primer/primitives": major
+---
+
+# Updated neutral base color scales
+
+## Changes
+
+- Theme specific neutral scales have been replaced with two new scales: `light` and `dark`.
+- The new `light` and `dark` scales are inverted, where 0 is the lightest shade in `light` and the darkest shade in `dark`.
+- Functional color tokens have been updated to use the new `light` and `dark` scales, and several overrides have been removed due to the new inverted design.
+
+## Migration
+
+- Functional color tokens all work as expected and have been tested to meet minimum contrast requirements.
+- If you are using `primer/primitives` base color scales directly, you may need to update how those colors are applied. See the migration table which outlines approximately how the new colors map to the old colors.
+
+### Light scale migration
+
+| Old color | New color |
+| --------- | --------- |
+| `0`       | `0`       |
+| `1`       | `2`       |
+| `2`       | `5`       |
+| `3`       | `7`       |
+| `4`       | `7`       |
+| `5`       | `8`       |
+| `6`       | `8`       |
+| `7`       | `9`       |
+| `8`       | `10`      |
+| `9`       | `11`      |
+
+### Dark scale migration
+
+| Old color | New color |
+| --------- | --------- |
+| `9`       | `0`       |
+| `8`       | `1`       |
+| `7`       | `2`       |
+| `6`       | `4`       |
+| `5`       | `6`       |
+| `4`       | `7`       |
+| `3`       | `8`       |
+| `2`       | `9`       |
+| `1`       | `10`      |
+| `0`       | `11`      |
+
+### Dark high contrast scale migration
+
+| Old color | New color |
+| --------- | --------- |
+| `9`       | `0`       |
+| `8`       | `3`       |
+| `7`       | `5`       |
+| `6`       | `6`       |
+| `5`       | `7`       |
+| `4`       | `8`       |
+| `3`       | `9`       |
+| `2`       | `10`      |
+| `1`       | `11`      |
+
+### Dark dimmed scale migration
+
+| Old color | New color |
+| --------- | --------- |
+| `9`       | `1`       |
+| `8`       | `2`       |
+| `7`       | `4`       |
+| `6`       | `5`       |
+| `5`       | `6`       |
+| `4`       | `7`       |
+| `3`       | `7`       |
+| `2`       | `8`       |
+| `1`       | `9`       |
+| `0`       | `10`      |
+
+
+### Light high contrast scale migration
+
+| Old color | New color |
+| --------- | --------- |
+| `0`       | `white`   |
+| `1`       | `2`       |
+| `2`       | `5`       |
+| `3`       | `7`       |
+| `4`       | `7`       |
+| `5`       | `8`       |
+| `6`       | `9`       |
+| `7`       | `10`      |
+| `8`       | `11`      |
+| `9`       | `black`   |

contributor-docs/adrs/adr-002-neutral-scales.md

@@ -0,0 +1,55 @@
+# Title
+
+## Status
+
+| Stage    | Status      |
+| -------- | ----------- |
+| Approved | <!-- ✅ --> |
+| Adopted  | <!-- 🚧 --> |
+
+## Decision
+
+Individual theme neutral scales will be replaced with two new neutral scales: `light` and `dark`. These scales have additional values (12 total) to accommodate contrast adjustments and state.
+
+This document outlines key design decisions made for these new neutral scales.
+
+## Context
+
+### General scale generation
+
+The goal was to make adjustments with minimal impact on the existing theme designs. For light default, shade 0 remains the same value as it's a prominent background color used throughout GitHub. All other steps are based on this value by adjusting saturation and lightness.
+
+### Saturation adjustments
+
+**Light**
+
+Shade 0 leans blue with roughly 30% saturation and is the most blue shade of the scale. The saturation gradually declines with a more abrupt drop at shade 7 where the lightness is 55%. Therefore, the darker shades lean more neutral.
+
+**Dark**
+
+Shade 11 leans blue with roughly 70% saturation. The saturation gradually declines until shade 6 where it begins to increase eventually landing at roughly 30%.
+
+### Each step serves a purpose
+
+0 – 5: Backgrounds
+6 – 7: Borders
+8 – 11: Text and icons
+
+### Increase background shades
+
+The new scales accommodate component states such as rest, hover, and active for all levels of contrast (dimmed, default, high) by providing additional shades with subtle lightness adjustments. A lower contrast theme may start at shade 0 for rest, 1 for hover and 2 for active, while a higher contrast theme may start at shade 3 for rest, 4 for hover and 5 for active.
+
+### Add minimum shade for 3:1 contrast
+
+Step 7 in both light and dark is the minimum border contrast for interactive controls against `bgColor-muted` or shade 0 in default themes. This is a 3:1 contrast ratio for WCAG AA compliance. We don't use this shade for all interactive borders today, but it's available for use in the future.
+
+### Impact
+
+- Maintaining 2 scales is easier than 5 scales
+- We can remove color mix hacks and overrides for state colors
+- We can adjust light default to be WCAG compliant and still have room to add a new "light bright" theme with these scales
+- High contrast themes have more flexibility
+
+### Alternatives
+
+We add a 6th neutral scale for a future "light bright" theme.

docs/storybook/stories/Color/Functional/Foreground.stories.tsx

@@ -9,7 +9,14 @@ export default {
   },
 }
 
-const fgColors = ['fgColor-default', 'fgColor-muted', 'fgColor-onEmphasis', 'fgColor-disabled', 'fgColor-link']
+const fgColors = [
+  'fgColor-default',
+  'fgColor-muted',
+  'fgColor-onEmphasis',
+  'fgColor-disabled',
+  'fgColor-link',
+  'fgColor-white',
+]
 
 export const Foreground = () => {
   return (

docs/storybook/stories/Demo/BorderColorTesting.stories.tsx

@@ -194,6 +194,7 @@ export const BorderDemo = () => {
                 <Button>A default button</Button>
                 <Button variant="invisible">An invisible button</Button>
                 <Button variant="primary">A primary button</Button>
+                <Button variant="danger">A danger button</Button>
               </Box>
 
               <Box

scripts/color-contrast.config.ts

@@ -43,10 +43,14 @@ const baseRequirements: ContrastRequirementBlueprint[] = [
   ['contrast.text', 'control-fgColor-rest', 'bgColor-inset'],
   // control colors
   ['contrast.text', 'control-fgColor-rest', 'control-bgColor-rest'],
-  ['contrast.text', 'control-fgColor-placeholder', 'control-bgColor-rest'],
+  ['contrast.text', 'control-fgColor-placeholder', 'bgColor-default'],
   ['contrast.text', 'control-fgColor-rest', 'control-bgColor-active'],
   ['contrast.text', 'control-fgColor-rest', 'control-bgColor-hover'],
   ['contrast.text', 'control-fgColor-rest', 'control-bgColor-selected'],
+  ['contrast.text', 'button-invisible-fgColor-rest', 'bgColor-muted'],
+  ['contrast.text', 'button-invisible-fgColor-hover', 'button-invisible-bgColor-hover'],
+  ['contrast.text', 'button-invisible-iconColor-rest', 'bgColor-muted'],
+  ['contrast.text', 'button-invisible-iconColor-hover', 'button-invisible-bgColor-hover'],
   // default text on role bg
   // TODO: contrast does not work with semi-transparent colors
   ['contrast.text', 'fgColor-default', 'bgColor-neutral-muted'],

src/tokens/base/color/dark/dark.dimmed.json5

@@ -43,148 +43,6 @@
           },
         },
       },
-      neutral: {
-        '0': {
-          $value: '#cdd9e5',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '1': {
-          $value: '#adbac7',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '2': {
-          $value: '#909dab',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '3': {
-          $value: '#768390',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '4': {
-          $value: '#636e7b',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '5': {
-          $value: '#545d68',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '6': {
-          $value: '#444c56',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '7': {
-          $value: '#373e47',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '8': {
-          $value: '#2d333b',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-        '9': {
-          $value: '#22272e',
-          $type: 'color',
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-          $extensions: {
-            'org.primer.figma': {
-              collection: 'base/color/dark-dimmed',
-            },
-          },
-        },
-      },
       blue: {
         '0': {
           $value: '#c6e6ff',