[Accepted] ADR: Use Box + sx to author components

.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