diff --git a/contributor-docs/adrs/adr-004-children-as-api.md b/contributor-docs/adrs/adr-004-children-as-api.md
new file mode 100644
index 00000000000..0dff7e8f0e8
--- /dev/null
+++ b/contributor-docs/adrs/adr-004-children-as-api.md
@@ -0,0 +1,416 @@
+# ADR 004: Strict props or Composite components
+
+## Status
+
+Approved 2022-05-10
+
+
+
+_Note: Consumer is used multiple times on this page. It refers to the developers consuming the component API and not end users._
+
+
+
+## Decision:
+
+
+1. Prefer using children for “content”
+
+2. For composite components, the API should be decided by how much customisation is available for children.
+
+For components that have design decisions baked in, should use strict props. For example, the color of the icon inside a Button component is decided by the `variant` prop on the Button. The API does not allow for changing that.
+
+```jsx
+
+```
+
+On the other hand, if we want consumers to have more control over children, a composite API is the better choice.
+
+```jsx
+
+
+
+
+ mona
+
+```
+
+## Prefer using children for “content”
+
+With React, `children` is the out-of-the-box way for putting [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#phrasing_content) inside your component. By using `children` instead of our own custom prop, we can make the API “predictable” for its consumers.
+
+
+
+```jsx
+// prefer this
+Changes saved!
+// over this
+
+```
+
+
+
+Children as an API for content is an open and composable approach. The contract here is that the `Flash` controls the container while the consumer of the component controls how the contents inside look.
+
+Take this example of composition:
+
+
+
+```jsx
+import {Flash} from '@primer/react'
+import {CheckIcon} from '@primer/octicons-react'
+
+render(
+
+ Changes saved!
+
+)
+```
+
+
+
+### Pros of this approach here:
+
+1. The component is aware of recommended use cases and comes with those design decisions backed-in. For example, using an `Icon` with `Flash` is a recognised use case. We don’t lock-in a specific icons, but we do set the size, variant-compatible color and the margin between the icon and text.
+
+ For example:
+
+
+
+ ```jsx
+
+ Changes saved!
+
+
+ Your changes were not saved!
+
+ ```
+
+2. You can bring your own icon components, the component does not depend on a specific version of octicons.
+3. When a product team wants to explore a use cases which isn’t baked into the component, they are not blocked by our team.
+
+ Example:
+
+
+
+ ```jsx
+
+
+ Changes saved!
+
+
+
+ ```
+
+
+
+### Tradeoffs of this approach / When not to use children
+
+Our goal isn't to put all content inside children though. Composition offers flexibility to the consumer of the component; this flexibility, however, can also lead to inconsistencies.
+
+
+
+```jsx
+
+ // uh oh, we don't know if that color or icon size is the right choice!
+ Changes saved!
+
+
+
+ Changes saved!
+
+```
+
+_Note: We need to assume good intent here, developers using the components aren’t trying to break the system. They are either trying to implement something that the system’s happy path does not support OR there are multiple ways of doing something with Primer and they have unintentionally picked the approach that is not recommended._
+
+
+
+The general wisdom is to _Make the right (recommended) thing easy to do and the wrong (not recommended) hard to do_. When going off the happy path, developers should feel some friction, some weight, code that “feels hacky” or feels like a workaround.
+
+In the above case, if we want to make the recommended path easier and other paths harder, we can change the API to look something like this:
+
+```jsx
+
+ Changes saved!
+
+```
+
+We are still using `children` for text content, but we have moved the `icon` back as a prop with reduced flexibility.
+
+When intentionally going off the happy path, developers can still drop down an abstraction level to add an `Icon` to `children`, though they would have to pick up the additional effort of setting compatible color, size and margin themselves. However, when it’s unintentional, it would feel like way too much work that the component should be doing automatically.
+
+```jsx
+
+
+ Changes saved!
+
+```
+
+
+
+_Sidenote: We might want to name this prop `leadingIcon`, even if there is no `trailingIcon`. Consistent names across components plays a big role in making the API predictable._
+
+
+
+---
+
+
+
+You can see this pattern used in `Button`:
+
+The icon gets its color and margin based on the variant and size of the `Button`. This is the happy path we want folks to be on, so we ask for the icon component instead of asking the developer to render the icon.
+
+
+
+```jsx
+
+
+```
+
+```jsx
+// we prefer this:
+
+// over these:
+
+
+
+```jsx
+// prefer this
+
+
+```jsx
+import {Flash} from '@primer/react'
+import {CheckIcon} from '@primer/octicons-react'
+
+render(
+ 
+
+ ```jsx
+ 
+
+ ```jsx
+ 
+
+```jsx
+
+
+```jsx
+
+
+```
+
+```jsx
+// we prefer this:
+
+// over these:
+
+