docs(experimental): improve the move to stable checklist (carbon-desi…

…gn-system#18401) * docs(experimental): improve the move to stable checklist * chore: remove errant formatting * Update docs/experimental-code.md Co-authored-by: Alison Joseph <[email protected]> * chore: yarn format --------- Co-authored-by: Alison Joseph <[email protected]>
lee-chase · Feb 6, 2025 · fb4f8f5 · fb4f8f5
1 parent 3727760
commit fb4f8f5
Showing 1 changed file with 93 additions and 24 deletions.
diff --git a/docs/experimental-code.md b/docs/experimental-code.md
@@ -136,41 +136,110 @@ Over time it becomes apparent an experimental API has stabilized and suits the
 needs of most users. If it isn't a breaking change, and there hasn't been much
 movement, it can be moved from "experimental" status to be "stable".
 
-To initiate a move to stable, open a new issue to request the team to evaluate
-if it can be moved. The issue should contain the following criteria that need to
-be met to move a component from experimental to stable:
-
-- [ ] All files have a copyright banner
-- [ ] All components exported in `src/index.js` and should not be `unstable_`
-      prefixed
-- [ ] Component has a label in the GitHub repository
-- [ ] Component should be documented on the website
-  - [ ] Component should have a usage, style, and code tab
-  - [ ] Component may have a component demo
-- [ ] For each component exported:
-  - [ ] Component is written as a function declaration or uses `forwardRef`
-  - [ ] Component has `propTypes` defined
+> [!IMPORTANT]  
+> To initiate a move to stable:
+>
+> 1. [Open a new issue](https://github.com/carbon-design-system/carbon/issues/new?template=Blank+issue)
+>    to request the team to evaluate if it can be moved.
+> 2. Copy and paste the following snippet into the issue - it contains all the
+>    criteria that must be met to move a component from experimental to stable.
+
+```md
+### Requirements to move to stable
+
+- [ ] The experimental code has stabilized
+  - [ ] A consuming project has given feedback on the visual design, UX, and dev
+        API/implementation
+  - [ ] The experimental code has been available for a reasonable amount of time
+        (~3 months) in aim to catch potential defects with spec, implementation,
+        accessibility, etc.
+
+---
+
+- [ ] Component is documented on the website
+  - [ ] Component has a usage, style, and code tab
+  - [ ] Component has a component demo
+
+---
+
+- [ ] React implementation is complete
+  - [ ] All components exported in `src/index.js` and should not be `unstable_`
+        prefixed
+  - [ ] Component is written as a function declaration and uses `forwardRef`
+  - [ ] Component has `propTypes`
     - [ ] Each prop type has a comment (used in storybook)
     - [ ] Prop types are as specific as needed, prefer `PropTypes.shape` over
           `PropTypes.object` if possible
+  - [ ] Component has a TypeScript interface that mirrors `propTypes`
+  - [ ] API comments (in propTypes and TS interface) are the exact same
   - [ ] Default props are listed as default args in the function definition (not
         in defaultProps)
     - [ ] Note: default props should be stable, in other words props like
           `onClick = () => {}` can cause re-renders since the function identity
           is not stable
   - [ ] Component has a story in `<ComponentName>.stories.js`
-    - [ ] Component has an mdx document that follows our outline
-    - [ ] mdx document coverages at least common use-cases and provides a prop
-          table
-    - [ ] Stories cover at least common use-cases
-    - [ ] Stories may include a `Playground` story for controls
+    - [ ] Stories show the intended usage of the component and are examples of
+          the most common use-cases
+    - [ ] All stories utilize controls
       - [ ] Controls with no meaningful change to the component visuals should
             be hidden from the controls panel, eg. `className`
       - [ ] Props of type `node` with no proper controls available for
             configuration should be hidden from the controls panel, eg.
             `children`
-    - [ ] Stories should mirror intended usage of the component
-  - [ ] Component has unit/integration tests written in RTL for testing the
-        component API
-  - [ ] Component is tested via VRT for at least the initial render state
-  - [ ] Component is tested via AVT for at least the initial render state
+    - [ ] Component has an `.mdx` document that
+      - [ ] Follows the established outline
+      - [ ] Documents and explains the most common use-cases
+      - [ ] Provides a prop table
+  - [ ] All required tests are present
+    - [ ] Unit/integration tests written with `@testing-library/react` that
+          cover the entire component API
+      - [ ] Popover's test file is a good example that can be used as a guide
+    - [ ] Visual regression tests (VRT) are present in
+          `e2e/components/ComponentName/ComponentName-test.e2e.js` that:
+      - [ ] Snapshot every storybook story
+      - [ ] Snapshot important discrete states (open, selected, enabled,
+            autoAlign etc.) by setting controls/args on a story
+    - [ ] Accessibility Verifiction Tests (AVT) are present in
+          `e2e/components/ComponentName/ComponentName-test.avt.e2e.js` that:
+      - [ ] Ensure every story `.toBeAccessible()`
+      - [ ] Ensure important discrete states (open, selected, etc.) are covered
+            by arranging/interacting with component before calling
+            `.toBeAccessible()`
+- [ ] Component is connected with Figma Code Connect and has a
+      `<ComponentName>.figma.tsx` file in the code-connect folder.
+
+---
+
+- [ ] Web Component implementation is complete (full details TBD)
+  - [ ] ... Various implementation details specific to WC
+  - [ ] ... API is documented (ts interface, etc.)
+  - [ ] ... Component story(s) are present
+  - [ ] ... All required tests are present
+
+---
+
+- [ ] Component styles are available through `@carbon/styles`
+  - [ ] Component styles are housed in a `ComponentName/_componentName.scss`
+        file
+  - [ ] Component styles are defined within a `@mixin`
+  - [ ] Component has an entrypoint file `ComponentName/_index.scss` that has at
+        minimum:
+    - [ ] `@forward 'componentName';`
+    - [ ] `@use 'componentName';`
+    - [ ] `@include componentName.componentName;`
+
+---
+
+- [ ] React and Web Components implementation mirror one another and have full
+      parity
+  - [ ] 100% visual parity
+  - [ ] 100% functional parity
+  - [ ] 100% documentation parity
+  - [ ] 100% testing parity
+
+---
+
+- [ ] Misc details are complete
+  - [ ] All files have a copyright banner
+  - [ ] Component has a label in the GitHub repository
+```