add docs

README.md

@@ -34,3 +34,4 @@ ESLint rules for Primer React
 - [no-system-props](https://github.com/primer/eslint-plugin-primer-react/blob/main/docs/rules/no-system-props.md)
 - [a11y-tooltip-interactive-trigger](https://github.com/primer/eslint-plugin-primer-react/blob/main/docs/rules/a11y-tooltip-interactive-trigger.md)
 - [a11y-explicit-heading](https://github.com/primer/eslint-plugin-primer-react/blob/main/docs/rules/a11y-explicit-heading.md)
+- [new-css-color-vars](https://github.com/primer/eslint-plugin-primer-react/blob/main/docs/rules/new-css-color-vars.md)

docs/rules/new-css-color-vars.md

@@ -0,0 +1,35 @@
+## Upgrade legacy color CSS variables to Primitives v8 in sx prop
+
+CSS variables are allowed within the `sx` prop in Primer React components. However, the legacy color CSS variables are deprecated in favor of the new CSS variables introduced in Primitives v8. This rule will warn you if you are using the deprecated color CSS variables in the `sx` prop, and autofix it including a fallback to the old value.
+
+## Rule Details
+
+This rule looks inside the `sx` prop for the following properties:
+
+```
+'bg',
+'backgroundColor',
+'color',
+'borderColor',
+'borderTopColor',
+'borderRightColor',
+'borderBottomColor',
+'borderLeftColor',
+'border',
+'boxShadow',
+'caretColor'
+```
+
+The rule references a static JSON file called `css-variable-map.json` that matches the old color CSS variables to a new one based on the property. We only check `sx` because `stylelint` is used to lint other forms of CSS-in-JS.
+
+👎 Examples of **incorrect** code for this rule
+
+```jsx
+<Button sx={{color: 'var(--color-fg-muted)'}}>Test</Button>
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+<Button sx={{color: 'var(--fgColor-muted, var(--color-fg-muted))'}}>Test</Button>
+```