Extend neutral scale to include white/black (0-13)

.changeset/fuzzy-ladybugs-joke.md

@@ -0,0 +1,5 @@
+---
+"@primer/primitives": major
+---
+
+Extend neutral scale to include white/black (0-13)

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

@@ -9,39 +9,39 @@
 
 ## 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.
+Individual theme neutral scales will be replaced with two new neutral scales: `light` and `dark`. These scales have additional values (13 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.
+The goal was to make adjustments with minimal impact on the existing theme designs. For light default, shade 1 (0 in legacy) 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.
+Shade 1 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 8 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%.
+Shade 12 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
+0 – 6: Backgrounds
+7 – 8: Borders
+9 – 13: 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.
+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 1 for rest, 2 for hover and 3 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.
+Step 8 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
 

docs/storybook/stories/Color/Base/Scales.stories.tsx

@@ -21,6 +21,10 @@ const bgColors = [
   'base-color-neutral-7',
   'base-color-neutral-8',
   'base-color-neutral-9',
+  'base-color-neutral-10',
+  'base-color-neutral-11',
+  'base-color-neutral-12',
+  'base-color-neutral-13',
   'base-color-blue-0',
   'base-color-blue-1',
   'base-color-blue-2',

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

@@ -13,16 +13,6 @@
             collection: 'base/color/dark-dimmed',
           },
         },
-        $extensions: {
-          'org.primer.figma': {
-            collection: 'base/color/dark-dimmed',
-          },
-        },
-        $extensions: {
-          'org.primer.figma': {
-            collection: 'base/color/dark-dimmed',
-          },
-        },
       },
       white: {
         $value: '#cdd9e5',
@@ -32,16 +22,6 @@
             collection: 'base/color/dark-dimmed',
           },
         },
-        $extensions: {
-          'org.primer.figma': {
-            collection: 'base/color/dark-dimmed',
-          },
-        },
-        $extensions: {
-          'org.primer.figma': {
-            collection: 'base/color/dark-dimmed',
-          },
-        },
       },
       blue: {
         '0': {

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

@@ -44,7 +44,7 @@
       },
       neutral: {
         '0': {
-          $value: '#0D1117',
+          $value: '{base.color.black}',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -53,7 +53,7 @@
           },
         },
         '1': {
-          $value: '#151B23',
+          $value: '#0D1117',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -62,7 +62,7 @@
           },
         },
         '2': {
-          $value: '#212830',
+          $value: '#151B23',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -71,7 +71,7 @@
           },
         },
         '3': {
-          $value: '#262C36',
+          $value: '#212830',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -80,7 +80,7 @@
           },
         },
         '4': {
-          $value: '#2A313C',
+          $value: '#262C36',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -89,7 +89,7 @@
           },
         },
         '5': {
-          $value: '#2F3742',
+          $value: '#2A313C',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -98,7 +98,7 @@
           },
         },
         '6': {
-          $value: '#3D444D',
+          $value: '#2F3742',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -107,7 +107,7 @@
           },
         },
         '7': {
-          $value: '#656C76',
+          $value: '#3D444D',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -116,7 +116,7 @@
           },
         },
         '8': {
-          $value: '#9198A1',
+          $value: '#656C76',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -125,7 +125,7 @@
           },
         },
         '9': {
-          $value: '#B7BDC8',
+          $value: '#9198A1',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -134,7 +134,7 @@
           },
         },
         '10': {
-          $value: '#D1D7E0',
+          $value: '#B7BDC8',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -143,6 +143,15 @@
           },
         },
         '11': {
+          $value: '#D1D7E0',
+          $type: 'color',
+          $extensions: {
+            'org.primer.figma': {
+              collection: 'base/color/dark',
+            },
+          },
+        },
+        '12': {
           $value: '#F0F6FC',
           $type: 'color',
           $extensions: {
@@ -151,6 +160,15 @@
             },
           },
         },
+        '13': {
+          $value: '{base.color.white}',
+          $type: 'color',
+          $extensions: {
+            'org.primer.figma': {
+              collection: 'base/color/dark',
+            },
+          },
+        },
       },
       blue: {
         '0': {

src/tokens/base/color/light/light.json5

@@ -44,7 +44,7 @@
       },
       neutral: {
         '0': {
-          $value: '#F6F8FA',
+          $value: '{base.color.white}',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -53,7 +53,7 @@
           },
         },
         '1': {
-          $value: '#EFF2F5',
+          $value: '#F6F8FA',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -62,7 +62,7 @@
           },
         },
         '2': {
-          $value: '#E6EAEF',
+          $value: '#EFF2F5',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -71,7 +71,7 @@
           },
         },
         '3': {
-          $value: '#E0E6EB',
+          $value: '#E6EAEF',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -80,7 +80,7 @@
           },
         },
         '4': {
-          $value: '#DAE0E7',
+          $value: '#E0E6EB',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -89,7 +89,7 @@
           },
         },
         '5': {
-          $value: '#D1D9E0',
+          $value: '#DAE0E7',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -98,7 +98,7 @@
           },
         },
         '6': {
-          $value: '#C8D1DA',
+          $value: '#D1D9E0',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -107,7 +107,7 @@
           },
         },
         '7': {
-          $value: '#818B98',
+          $value: '#C8D1DA',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -116,7 +116,7 @@
           },
         },
         '8': {
-          $value: '#59636E',
+          $value: '#818B98',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -125,7 +125,7 @@
           },
         },
         '9': {
-          $value: '#454C54',
+          $value: '#59636E',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -134,7 +134,7 @@
           },
         },
         '10': {
-          $value: '#393F46',
+          $value: '#454C54',
           $type: 'color',
           $extensions: {
             'org.primer.figma': {
@@ -143,6 +143,15 @@
           },
         },
         '11': {
+          $value: '#393F46',
+          $type: 'color',
+          $extensions: {
+            'org.primer.figma': {
+              collection: 'base/color/light',
+            },
+          },
+        },
+        '12': {
           $value: '#25292E',
           $type: 'color',
           $extensions: {
@@ -151,6 +160,15 @@
             },
           },
         },
+        '13': {
+          $value: '{base.color.black}',
+          $type: 'color',
+          $extensions: {
+            'org.primer.figma': {
+              collection: 'base/color/light',
+            },
+          },
+        },
       },
       blue: {
         '0': {