chore(Box): Mark Box and its props as deprecated (#5763)

Author: hussam-i-am

.changeset/dry-crabs-train.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+chore(Box): Mark Box and its props as deprecated

contributor-docs/migration-from-box.md

@@ -0,0 +1,54 @@
+# Migration away from `Box`
+
+## Why Migrate?
+
+The `Box` component is a utility component that provides a convenient way to apply styles to elements and is simply a `div` element by default. However, it can be less performant than using standard HTML elements with CSS Modules. It has now been deprecated.
+
+### Box using the `sx` prop
+
+Replace the Box component with a standard HTML element such as `div`.
+
+```jsx
+<Box sx={{p: 3, bg: 'gray.1'}}>Content here</Box>
+```
+
+```jsx
+<div className={classes.example}>Content here</div>
+```
+
+### Box using the `as` prop
+
+If the Box is currently using the `as` prop to render a different HTML element, make sure to use that element instead.
+
+```jsx
+<Box as="section" sx={{p: 3, bg: 'gray.1'}}>
+  Content here
+</Box>
+```
+
+```jsx
+<section className={classes.example}>Content here</section>
+```
+
+### Box using style attributes
+
+If the Box is using style attributes, you can replace it with a standard HTML element and use CSS Modules to apply the styles.
+
+```jsx
+<Box minWidth={200} maxWidth={400} sx={{p: 3, bg: 'gray.1'}}>
+  Content here
+</Box>
+```
+
+```jsx
+<div className={clsx(classes.example)}>Content here</div>
+```
+
+```css
+.example {
+  padding: 16px;
+  background-color: var(--gray-1);
+  min-width: 200px;
+  max-width: 400px;
+}
+```

packages/react/src/Box/Box.docs.json

@@ -1,7 +1,7 @@
 {
   "id": "box",
   "name": "Box",
-  "status": "beta",
+  "status": "deprecated",
   "a11yReviewed": false,
   "stories": [],
   "importPath": "@primer/react",

packages/react/src/Box/Box.features.stories.tsx

@@ -3,7 +3,7 @@ import type {Meta} from '@storybook/react'
 import Box from './Box'
 
 export default {
-  title: 'Components/Box/Features',
+  title: 'Deprecated/Components/Box/Features',
   component: Box,
 } as Meta<typeof Box>
 

packages/react/src/Box/Box.stories.tsx

@@ -3,7 +3,7 @@ import type {Meta, StoryFn} from '@storybook/react'
 import Box from './Box'
 
 export default {
-  title: 'Components/Box',
+  title: 'Deprecated/Components/Box',
   component: Box,
 } as Meta<typeof Box>
 

packages/react/src/Box/Box.tsx

@@ -12,13 +12,12 @@ import type {
   TypographyProps,
 } from 'styled-system'
 import {background, border, color, flexbox, grid, layout, position, shadow, space, typography} from 'styled-system'
-import type {BetterSystemStyleObject} from '../sx'
+import type {SxProp} from '../sx'
 import sx from '../sx'
 import type {ComponentProps} from '../utils/types'
 
-type StyledBoxProps = {
-  sx?: BetterSystemStyleObject
-} & SpaceProps &
+type StyledBoxProps = SxProp &
+  SpaceProps &
   ColorProps &
   TypographyProps &
   LayoutProps &
@@ -29,6 +28,11 @@ type StyledBoxProps = {
   PositionProps &
   ShadowProps
 
+/**
+ * @deprecated The Box component is deprecated. Replace with a `div` or
+ * appropriate HTML element instead, with CSS modules for styling.
+ * @see https://github.com/primer/react/blob/main/contributor-docs/migration-from-box.md
+ */
 const Box = styled.div<StyledBoxProps>(
   space,
   color,
@@ -43,5 +47,10 @@ const Box = styled.div<StyledBoxProps>(
   sx,
 )
 
+/**
+ * @deprecated The Box component is deprecated. Replace with a `div` or
+ * appropriate HTML element instead, with CSS modules for styling.
+ * @see https://github.com/primer/react/blob/main/contributor-docs/migration-from-box.md
+ */
 export type BoxProps = ComponentProps<typeof Box>
 export default Box