diff --git a/packages/components/CONTRIBUTING.md b/packages/components/CONTRIBUTING.md
index 3bed2829216a81..98e4422f853bf5 100644
--- a/packages/components/CONTRIBUTING.md
+++ b/packages/components/CONTRIBUTING.md
@@ -35,12 +35,64 @@ function LinkButton( { href, children } ) {
return ;
}
```
+-->
-### Composition patterns
+#### Compound components
-TBD — E.g. Using `children` vs custom render props vs arbitrary "data" props
+When creating components that render a list of subcomponents, prefer to expose the API using the [Compound Components](https://kentcdodds.com/blog/compound-components-with-react-hooks) technique over array props like `items` or `options`:
-### (Semi-)Controlled components
+```jsx
+// ❌ Don't:
+
+```
+```jsx
+// ✅ Do:
+
+
+```
+
+When implementing this pattern, avoid using `React.Children.map` and `React.cloneElement` to map through the children and augment them. Instead, use React Context to provide state to subcomponents and connect them:
+
+```jsx
+// ❌ Don't:
+function List ( props ) {
+ const [ state, setState ] = useState();
+ return (
+