Docs for process for refactoring a Primer React Component to CSS modules

contributor-docs/migrating-to-css-modules.md

@@ -0,0 +1,69 @@
+# Primer React Styled Components to CSS Modules Refactoring Guide
+
+This guide outlines the steps to follow when refactoring Primer React components from Styled Components to CSS Modules.
+
+---
+
+## Table of Contents
+
+- [Primer React Styled Components to CSS Modules Refactoring Guide](#primer-react-styled-components-to-css-modules-refactoring-guide)
+  - [Table of Contents](#table-of-contents)
+  - [Before Refactoring a Component](#before-refactoring-a-component)
+  - [How to Migrate](#how-to-migrate)
+    - [Refactoring Styled-Components to CSS Modules](#refactoring-styled-components-to-css-modules)
+    - [When Refactoring a Component](#when-refactoring-a-component)
+    - [Testing the Migration](#testing-the-migration)
+  - [Releasing a Component](#releasing-a-component)
+
+---
+
+## Before Refactoring a Component
+
+- **Verify VRT (Visual Regression Testing) Coverage:**
+  - Check for missing VRT coverage. We utilize the VRT tests to make sure we're matching styling in production with current expectations.
+  - Make sure there are `dev` stories for any edge cases spotted in production for the component (ie. sx prop, custom className, styled system attributes).
+- **Ensure All Visual Changes Are Completed:**
+  - Make necessary visual changes **before** creating the CSS Modules refactor PR.
+
+---
+
+## How to Migrate
+
+### Refactoring Styled-Components to CSS Modules
+
+- **Replace `${get('...')}` Syntax:**
+  - Migrate these to CSS Modules classes.
+  - No need for fallbacks in CSS Modules.
+
+### When Refactoring a Component
+
+1. **Check for `className` Prop:**
+   - Ensure the component accepts a `className`.
+2. **Feature Flagging:**
+   - Add a feature flag to toggle the `sx` prop for controlled rollout (staff shipping).
+3. **Create CSS Module:**
+   - Add a corresponding `{Component}.module.css` file.
+4. **Import CSS Modules:**
+   - Use the CSS module in the component.
+   - Add CSS classes behind the `primer_react_css_modules_team` feature flag.
+5. **Ensure Component still accepts sx styling**
+   - Until we migrate all uses of sx, we need to ensure the component will accept sx props inside the feature flag. This will often default to using the `Box` component if an sx prop is passed in.
+
+### Testing the Migration
+
+- **Support for `className`:**
+  - Ensure the component works properly with the `className` prop.
+- **Regression Testing:**
+  - Validate that no regressions occur when the feature flag is enabled.
+- **Handling `sx` Prop:**
+  - Confirm the `sx` prop behaves correctly with the feature flag enabled.
+
+---
+
+## Releasing a Component
+
+- **Merge Process:**
+  - Once merged into dotcom, the component will be part of the `primer_react_css_modules_team` rollout.
+  - We progress components through levels of feature flags as we roll them out to make sure we address any bugs with the minimum amount of audience.
+- **Monitor Team Ship:**
+  - Watch for any issues or regressions during the team ship phase.