ADR: Use Box + sx to author components - DEADLINE: Friday 22 April (#2020)

* ADR: Use Box to author new components

* replace long example with PR link

* add ADRs to eslint ignore

* better phrasing of intro, thanks Cole!

Co-authored-by: Cole Bemis <colebemis@github.com>

* sentence case, thanks Cole!

Co-authored-by: Cole Bemis <colebemis@github.com>

* Apply suggestions from code review

thanks Cole!

Co-authored-by: Cole Bemis <colebemis@github.com>

* Apply suggestions from code review, thanks @talum

Co-authored-by: Tracy Lum <11878752+talum@users.noreply.github.com>

* Remove overriding styles from this ADR

* Link sx API research

* use BetterSystemStyleObject for types

* Change status to Approved

Co-authored-by: Cole Bemis <colebemis@github.com>
Co-authored-by: Tracy Lum <11878752+talum@users.noreply.github.com>

Author: 3 people

.eslintrc.json

@@ -23,7 +23,8 @@
     "lib/**/*",
     "lib-*/**/*",
     "types/**/*",
-    "consumer-test/**/*"
+    "consumer-test/**/*",
+    "contributor-docs/adrs/*"
   ],
   "globals": {
     "__DEV__": "readonly"

contributor-docs/adrs/adr-005-box-sx.md

@@ -0,0 +1,62 @@
+# ADR 005: Use Box as a building block for all other components
+
+## Status
+
+Approved
+
+## Context
+
+In Primer React and consuming applications, we use many different patterns for creating React components. Two common patterns are:
+
+1. Creating components with styled-components
+
+    ```tsx
+    const Avatar = styled.img.attrs<StyledAvatarProps>(props => ({
+      height: props.size,
+      width: props.size
+    }))<StyledAvatarProps>`
+      display: inline-block;
+      overflow: hidden;
+      line-height: ${get('lineHeights.condensedUltra')};
+      border-radius: ${props => getBorderRadius(props)};
+      ${sx}
+    `
+    ```
+
+    [Show full code example →](https://github.com/primer/react/pull/2019/files?diff=split&w=0)
+
+2.  Creating components with Box
+
+    ```tsx
+    const Avatar: React.FC<AvatarProps> = ({size = 20, alt = '', square = false, sx = {}, ...props}) => {
+      const styles:BetterSystemStyleObject = {
+        display: 'inline-block',
+        overflow: 'hidden',
+        lineHeight: 'condensedUltra',
+        borderRadius: getBorderRadius({size, square})
+      }
+
+      return (
+        <Box
+          as="img"
+          alt={alt}
+          sx={merge<BetterSystemStyleObject>(styles, sx)} // styles needs to merge with props.sx
+          {...props}
+        />
+      )
+    }
+    ```
+
+    [Show full code example →](https://github.com/primer/react/pull/2019/files?diff=split&w=0)
+
+&nbsp;
+
+## Decision
+
+Prefer using method #2: Creating components with Box for the following reasons:
+
+- Better authoring experience with Typescript. With Box, we can improve the API and autocomplete for consuming primitives. [See research](https://github.com/github/primer/discussions/755#discussioncomment-2318144)
+- The styling library (i.e. styled-components) becomes an implementation detail and can be changed later with minimal breaking changes for consumers. (Avoids leaky abstractions)
+- We have had issues with exporting types, we can increase confidence by keeping the exported types close to what we author.
+
+See diff for moving Avatar from approach 1 to 2: https://github.com/primer/react/pull/2019/files?diff=split&w=0