From 56c7371c97f8f076425127e11e3a1c6fc751eb71 Mon Sep 17 00:00:00 2001
From: langermank <18661030+langermank@users.noreply.github.com>
Date: Mon, 9 Oct 2023 10:05:08 -0700
Subject: [PATCH] add docs

---
 README.md                        |  1 +
 docs/rules/new-css-color-vars.md | 35 ++++++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+)
 create mode 100644 docs/rules/new-css-color-vars.md

diff --git a/README.md b/README.md
index de4fc024..0a17ae0e 100644
--- a/README.md
+++ b/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)
diff --git a/docs/rules/new-css-color-vars.md b/docs/rules/new-css-color-vars.md
new file mode 100644
index 00000000..e34fcf52
--- /dev/null
+++ b/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>
+```