Merge branch 'main' into pagelayout-pane-custom-widths

primer · Aug 14, 2023 · 79e1ad9 · 79e1ad9
2 parents d4ea90b + 88c8659
commit 79e1ad9
Show file tree

Hide file tree

Showing 115 changed files with 5,274 additions and 1,111 deletions.
diff --git a/.changeset/clever-parents-bathe.md b/.changeset/clever-parents-bathe.md
@@ -0,0 +1,7 @@
+---
+'@primer/react': patch
+---
+
+Update @react-aria/ssr dependency to ^3.5.0 to address server-side rendering mismatch when using React StrictMode
+
+<!-- Changed components: FormControl -->
diff --git a/.changeset/cool-hornets-call.md b/.changeset/cool-hornets-call.md
diff --git a/.changeset/cyan-cycles-provide.md b/.changeset/cyan-cycles-provide.md
diff --git a/.changeset/eighty-islands-join.md b/.changeset/eighty-islands-join.md
diff --git a/.changeset/empty-guests-live.md b/.changeset/empty-guests-live.md
diff --git a/.changeset/four-bulldogs-hope.md b/.changeset/four-bulldogs-hope.md
diff --git a/.changeset/green-rules-tickle.md b/.changeset/green-rules-tickle.md
diff --git a/.changeset/hungry-spies-remember.md b/.changeset/hungry-spies-remember.md
diff --git a/.changeset/kind-eggs-cheer.md b/.changeset/kind-eggs-cheer.md
diff --git a/.changeset/new-impalas-attack.md b/.changeset/new-impalas-attack.md
diff --git a/.changeset/new-students-warn.md b/.changeset/new-students-warn.md
diff --git a/.changeset/new-timers-mix.md b/.changeset/new-timers-mix.md
diff --git a/.changeset/plenty-bats-shop.md b/.changeset/plenty-bats-shop.md
diff --git a/.changeset/plenty-mangos-sniff.md b/.changeset/plenty-mangos-sniff.md
diff --git a/.changeset/rotten-meals-obey.md b/.changeset/rotten-meals-obey.md
diff --git a/.changeset/silent-books-remain.md b/.changeset/silent-books-remain.md
diff --git a/.changeset/smart-points-exercise.md b/.changeset/smart-points-exercise.md
diff --git a/.changeset/strong-zoos-explain.md b/.changeset/strong-zoos-explain.md
diff --git a/.changeset/thin-laws-beam.md b/.changeset/thin-laws-beam.md
@@ -0,0 +1,7 @@
+---
+"@primer/react": patch
+---
+
+Expose `useSlots` from `drafts/hooks`
+
+<!-- Changed components: _none_ -->
diff --git a/.changeset/tidy-melons-type.md b/.changeset/tidy-melons-type.md
diff --git a/...nents/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-colorblind-linux.png b/...nents/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-colorblind-linux.png
diff --git a/...omponents/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-dimmed-linux.png b/...omponents/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-dimmed-linux.png
diff --git a/...ts/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-high-contrast-linux.png b/...ts/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-high-contrast-linux.png
diff --git a/...shots/components/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-linux.png b/...shots/components/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-linux.png
diff --git a/...nents/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-tritanopia-linux.png b/...nents/LabelGroup.test.ts-snapshots/LabelGroup-Default-dark-tritanopia-linux.png
diff --git a/...ents/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-colorblind-linux.png b/...ents/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-colorblind-linux.png
diff --git a/...s/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-high-contrast-linux.png b/...s/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-high-contrast-linux.png
diff --git a/...hots/components/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-linux.png b/...hots/components/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-linux.png
diff --git a/...ents/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-tritanopia-linux.png b/...ents/LabelGroup.test.ts-snapshots/LabelGroup-Default-light-tritanopia-linux.png
diff --git a/...ts/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-colorblind-linux.png b/...ts/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-colorblind-linux.png
diff --git a/...onents/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-dimmed-linux.png b/...onents/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-dimmed-linux.png
diff --git a/...LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-high-contrast-linux.png b/...LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-high-contrast-linux.png
diff --git a/...ts/components/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-linux.png b/...ts/components/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-linux.png
diff --git a/...ts/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-tritanopia-linux.png b/...ts/LabelGroup.test.ts-snapshots/LabelGroup-Playground-dark-tritanopia-linux.png
diff --git a/...s/LabelGroup.test.ts-snapshots/LabelGroup-Playground-light-colorblind-linux.png b/...s/LabelGroup.test.ts-snapshots/LabelGroup-Playground-light-colorblind-linux.png
diff --git a/...abelGroup.test.ts-snapshots/LabelGroup-Playground-light-high-contrast-linux.png b/...abelGroup.test.ts-snapshots/LabelGroup-Playground-light-high-contrast-linux.png
diff --git a/...s/components/LabelGroup.test.ts-snapshots/LabelGroup-Playground-light-linux.png b/...s/components/LabelGroup.test.ts-snapshots/LabelGroup-Playground-light-linux.png
diff --git a/...s/LabelGroup.test.ts-snapshots/LabelGroup-Playground-light-tritanopia-linux.png b/...s/LabelGroup.test.ts-snapshots/LabelGroup-Playground-light-tritanopia-linux.png
diff --git a/.../LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-colorblind-linux.png b/.../LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-colorblind-linux.png
diff --git a/...ents/LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-dimmed-linux.png b/...ents/LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-dimmed-linux.png
diff --git a/...belGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-high-contrast-linux.png b/...belGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-high-contrast-linux.png
diff --git a/.../components/LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-linux.png b/.../components/LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-linux.png
diff --git a/.../LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-tritanopia-linux.png b/.../LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-dark-tritanopia-linux.png
diff --git a/...LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-colorblind-linux.png b/...LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-colorblind-linux.png
diff --git a/...elGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-high-contrast-linux.png b/...elGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-high-contrast-linux.png
diff --git a/...components/LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-linux.png b/...components/LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-linux.png
diff --git a/...LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-tritanopia-linux.png b/...LabelGroup.test.ts-snapshots/LabelGroup-TruncateAuto-light-tritanopia-linux.png
diff --git a/...abelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-colorblind-linux.png b/...abelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-colorblind-linux.png
diff --git a/...ts/LabelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-dimmed-linux.png b/...ts/LabelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-dimmed-linux.png
diff --git a/...lGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-high-contrast-linux.png b/...lGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-high-contrast-linux.png
diff --git a/...omponents/LabelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-linux.png b/...omponents/LabelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-linux.png
diff --git a/...abelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-tritanopia-linux.png b/...abelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-dark-tritanopia-linux.png
diff --git a/...belGroup.test.ts-snapshots/LabelGroup-TruncateToFive-light-colorblind-linux.png b/...belGroup.test.ts-snapshots/LabelGroup-TruncateToFive-light-colorblind-linux.png
diff --git a/...Group.test.ts-snapshots/LabelGroup-TruncateToFive-light-high-contrast-linux.png b/...Group.test.ts-snapshots/LabelGroup-TruncateToFive-light-high-contrast-linux.png
diff --git a/...mponents/LabelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-light-linux.png b/...mponents/LabelGroup.test.ts-snapshots/LabelGroup-TruncateToFive-light-linux.png
diff --git a/...belGroup.test.ts-snapshots/LabelGroup-TruncateToFive-light-tritanopia-linux.png b/...belGroup.test.ts-snapshots/LabelGroup-TruncateToFive-light-tritanopia-linux.png
diff --git a/...Timeline.test.ts-snapshots/Timeline-Timeline-Break-dark-high-contrast-linux.png b/...Timeline.test.ts-snapshots/Timeline-Timeline-Break-dark-high-contrast-linux.png
diff --git a/...imeline.test.ts-snapshots/Timeline-Timeline-Break-light-high-contrast-linux.png b/...imeline.test.ts-snapshots/Timeline-Timeline-Break-light-high-contrast-linux.png
diff --git a/...nents/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-colorblind-linux.png b/...nents/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-colorblind-linux.png
diff --git a/...omponents/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-dimmed-linux.png b/...omponents/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-dimmed-linux.png
diff --git a/...ts/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-high-contrast-linux.png b/...ts/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-high-contrast-linux.png
diff --git a/...shots/components/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-linux.png b/...shots/components/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-linux.png
diff --git a/...nents/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-tritanopia-linux.png b/...nents/drafts/Button2.test.ts-snapshots/Button-sx-prop-dark-tritanopia-linux.png
diff --git a/...ents/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-colorblind-linux.png b/...ents/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-colorblind-linux.png
diff --git a/...s/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-high-contrast-linux.png b/...s/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-high-contrast-linux.png
diff --git a/...hots/components/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-linux.png b/...hots/components/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-linux.png
diff --git a/...ents/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-tritanopia-linux.png b/...ents/drafts/Button2.test.ts-snapshots/Button-sx-prop-light-tritanopia-linux.png
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,119 @@
 # @primer/components
 
+## 35.27.1
+
+### Patch Changes
+
+- [#3589](https://github.com/primer/react/pull/3589) [`d598a53b`](https://github.com/primer/react/commit/d598a53bf4e925f22df6a51aa0f8c933227c85bd) Thanks [@siddharthkp](https://github.com/siddharthkp)! - - PageLayout: Undo deprecation of `position` prop for PageLayout.Pane (Revert primer/react#3389)
+
+  - SplitPageLayout: Undo deprecation of `position` prop for SplitPageLayout.Pane (Revert primer/react#3389)
+
+  <!-- Changed components: PageLayout, SplitPageLayout -->
+
+## 35.27.0
+
+### Minor Changes
+
+- [#3510](https://github.com/primer/react/pull/3510) [`bdbcfd15`](https://github.com/primer/react/commit/bdbcfd151d00a7995b07f57e2b37468af0bd0ee5) Thanks [@camertron](https://github.com/camertron)! - Implement accessibility audit feedback for ToggleSwitch
+
+  <!-- Changed components: ToggleSwitch -->
+
+- [#3466](https://github.com/primer/react/pull/3466) [`11b54ac8`](https://github.com/primer/react/commit/11b54ac88aff4bb8383a0e6a41174e4b477f85d7) Thanks [@mperrotti](https://github.com/mperrotti)! - Allows consumers to disable the behavior where the AvatarStack expands to show each Avatar on hover. There are also changes that allow users to customize the size of the avatars - even responsively!
+
+  <!-- Changed components: Avatar, AvatarStack -->
+
+- [#3390](https://github.com/primer/react/pull/3390) [`b4e15b84`](https://github.com/primer/react/commit/b4e15b8452772dc72d3efda73f5d96dbe2c35150) Thanks [@mperrotti](https://github.com/mperrotti)! - The showPages prop on both Pagination components can now accept a responsive value.
+
+  <!-- Changed components: DataTable, Pagination -->
+
+- [#3496](https://github.com/primer/react/pull/3496) [`11cdbdcc`](https://github.com/primer/react/commit/11cdbdcc3b7a662a93c46eafc92714fc3f1dc0c0) Thanks [@joshblack](https://github.com/joshblack)! - Update dependency ranges to use caret ranges instead of pinned versions
+
+  <!-- Changed components: _none_ -->
+
+### Patch Changes
+
+- [#3264](https://github.com/primer/react/pull/3264) [`5e655203`](https://github.com/primer/react/commit/5e6552039605bff358671e725687b37ce524ce2b) Thanks [@mperrotti](https://github.com/mperrotti)! - Adds truncation features to the LabelGroup component:
+
+  - truncate LabelGroup children after a static number of children (for example, truncate after the 5th label)
+  - truncate LabelGroup children to fit in the width of the parent
+  - show full list in an Overlay
+  - show full list inline
+
+  <!-- Changed components: LabelGroup -->
+
+- [#3505](https://github.com/primer/react/pull/3505) [`c3f1e3c7`](https://github.com/primer/react/commit/c3f1e3c790b36034022ef548dfd300c3d89872a4) Thanks [@siddharthkp](https://github.com/siddharthkp)! - ActionList: Fix icon and description hover colors for danger variant
+
+  <!-- Changed components: ActionList -->
+
+- [#3520](https://github.com/primer/react/pull/3520) [`daee9a9c`](https://github.com/primer/react/commit/daee9a9ce3f21901e029c856d452ca47cfe35887) Thanks [@mattcosta7](https://github.com/mattcosta7)! - passthrough dom props on toggleswitch
+
+  <!-- Changed components: ToggleSwitch -->
+
+- [#3441](https://github.com/primer/react/pull/3441) [`90a145cc`](https://github.com/primer/react/commit/90a145ccd37338f50a47a8e16491a80e2d276b52) Thanks [@tomthorogood](https://github.com/tomthorogood)! - Renders docs.json markdown content
+
+  <!-- Changed components: _none_ -->
+
+- [#3540](https://github.com/primer/react/pull/3540) [`a90350cc`](https://github.com/primer/react/commit/a90350ccc4e2779cd5f21fc343d1fe793ebc5b56) Thanks [@kendallgassner](https://github.com/kendallgassner)! - Css styled block fixes
+
+  <!-- Changed components: DataTable, Timeline -->
+
+- [#3389](https://github.com/primer/react/pull/3389) [`57c4bdf9`](https://github.com/primer/react/commit/57c4bdf928c0c277dfcf896f67443a2e9779a1d7) Thanks [@radglob](https://github.com/radglob)! - Deprecates `position` prop for PageLayout.Pane and SplitPageLayout.Pane.
+
+  ```diff
+  -<PageLayout>
+  -    <PageLayout.Content />
+  -    <PageLayout.Pane position="start" />
+  -</PageLayout>
+
+  +<PageLayout>
+  +    <PageLayout.Pane />
+  +    <PageLayout.Content />
+  +</PageLayout>
+
+  ```
+
+  <!-- Changed components: PageLayout, SplitPageLayout -->
+
+- [#3490](https://github.com/primer/react/pull/3490) [`8d1d5146`](https://github.com/primer/react/commit/8d1d51469f981fc0717adc80637369dd207670ca) Thanks [@langermank](https://github.com/langermank)! - Bug fix: ActionList item label weight and spacing if description exists
+
+  <!-- Changed components: ActionList -->
+
+- [#3361](https://github.com/primer/react/pull/3361) [`bea39c24`](https://github.com/primer/react/commit/bea39c24a7bc210cae78681572e7819edaec13db) Thanks [@broccolinisoup](https://github.com/broccolinisoup)! - UnderlineNav2: underline nav items' selected state can be managed by the app state
+
+  <!-- Changed components: UnderlineNav -->
+
+- [#3533](https://github.com/primer/react/pull/3533) [`33b60551`](https://github.com/primer/react/commit/33b60551af4749d476f970d5447f422a6ace33ca) Thanks [@amarmanhala](https://github.com/amarmanhala)! - Changed div tag to HTML semantic tag header for Header (file Header.tsx) component.
+
+  <!-- Changed components: _none_ -->
+
+- [#3516](https://github.com/primer/react/pull/3516) [`33d43459`](https://github.com/primer/react/commit/33d43459258c28fa5d69a1eca83d46cdb4bfe773) Thanks [@danielguillan](https://github.com/danielguillan)! - ActionList: Fixes the width of items for the full variant
+
+  <!-- Changed components: ActionList -->
+
+- [#3517](https://github.com/primer/react/pull/3517) [`cf9d8a5e`](https://github.com/primer/react/commit/cf9d8a5e0cb21583e3b6280e2d493e54fd2c1ca0) Thanks [@kendallgassner](https://github.com/kendallgassner)! - Adding aria-attributes and role to the ProgressBar component
+
+  <!-- Changed components: ProgressBar -->
+
+- [#3539](https://github.com/primer/react/pull/3539) [`c02f3a2f`](https://github.com/primer/react/commit/c02f3a2f3cdf4cf009e4c4856588f4b34bf97785) Thanks [@mperrotti](https://github.com/mperrotti)! - Adds 'display' text size to PRC theme. This size is described in our [typography documentation](https://primer.style/design/foundations/typography#headings), but was never added to our React theme.
+
+  <!-- Changed components: _none_ -->
+
+- [#3537](https://github.com/primer/react/pull/3537) [`311c8c91`](https://github.com/primer/react/commit/311c8c918e33ca6692a7cb1eeb4c59ac27775ea1) Thanks [@kendallgassner](https://github.com/kendallgassner)! - Make checkmark visible on reduced-motion
+
+  <!-- Changed components: Checkbox -->
+
+- [#3491](https://github.com/primer/react/pull/3491) [`263d5978`](https://github.com/primer/react/commit/263d5978dfceda3c5c18da6cfcb9f72cc616fe2b) Thanks [@nicolleromero](https://github.com/nicolleromero)! - MarkdownViewer: Address scenario in useListInteraction where the position calculation can be incorrect when tasklists appear above legacy task lists
+
+  <!-- Changed components: MarkdownViewer -->
+
+- [#3447](https://github.com/primer/react/pull/3447) [`40808db7`](https://github.com/primer/react/commit/40808db7a603b8b39872317c36b56e655705d475) Thanks [@jesskuo4](https://github.com/jesskuo4)! - [Bug] Leading & Trailing Visual Colors for Button
+
+- [#3562](https://github.com/primer/react/pull/3562) [`53791841`](https://github.com/primer/react/commit/537918414b1f576368efd447962479b9f8afcb27) Thanks [@iansan5653](https://github.com/iansan5653)! - Fix `MarkdownEditor` file uploads inserting the URL into the wrong input when an overlay is open
+
+- [#3547](https://github.com/primer/react/pull/3547) [`7ef802e8`](https://github.com/primer/react/commit/7ef802e84833d08f0912e4ce91d5eedb3e3ca655) Thanks [@mperrotti](https://github.com/mperrotti)! - Prevents body scroll when Dialog (the newer Dialog) is open
+
+  <!-- Changed components: Dialog -->
+
 ## 35.26.1
 
 ### Patch Changes

diff --git a/contributor-docs/versioning.md b/contributor-docs/versioning.md
@@ -10,6 +10,7 @@
 - [Reference](#reference)
   - [The type of a prop is broadened](#the-type-of-a-prop-is-broadened)
   - [The type of a prop is narrowed](#the-type-of-a-prop-is-narrowed)
+  - [The `display` property used for the container of `children` is changed](#the-display-property-used-for-the-container-of-children-is-changed)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
@@ -39,21 +40,22 @@ For a full list of releases, visit our [releases](https://github.com/primer/reac
 
 ## Changes
 
-| Category  | Type of change                                                               | semver bump |
-| :-------- | :--------------------------------------------------------------------------- | :---------- |
-| Component | A component is added                                                         | `minor`     |
-|           | A component is deprecated                                                    | `minor`     |
-|           | A component is removed                                                       | `major`     |
-| Props     | A prop is added                                                              | `minor`     |
-|           | [The type of a prop is broadened](#the-type-of-a-prop-is-broadened)          | `minor`     |
-|           | [The type of a prop is narrowed](#the-type-of-a-prop-is-narrowed)            | `major`     |
-|           | A prop is deprecated                                                         | `minor`     |
-|           | A prop is removed                                                            | `major`     |
-| Package   | A dependency is added                                                        | `minor`     |
-|           | A dependency is removed and it does not affect the public API of the package | `minor`     |
-|           | A dependency is removed and it does affect the public API of the package     | `major`     |
-|           | The version of a dependency is increased to a newer minor or patch version   | `minor`     |
-|           | The version of a dependency is increased to a newer major version            | `major`     |
+| Category  | Type of change                                                                                                                                | semver bump         |
+| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
+| Component | A component is added                                                                                                                          | `minor`             |
+|           | A component is deprecated                                                                                                                     | `minor`             |
+|           | A component is removed                                                                                                                        | `major`             |
+| Props     | A prop is added                                                                                                                               | `minor`             |
+|           | [The type of a prop is broadened](#the-type-of-a-prop-is-broadened)                                                                           | `minor`             |
+|           | [The type of a prop is narrowed](#the-type-of-a-prop-is-narrowed)                                                                             | `major`             |
+|           | A prop is deprecated                                                                                                                          | `minor`             |
+|           | A prop is removed                                                                                                                             | `major`             |
+| Package   | A dependency is added                                                                                                                         | `minor`             |
+|           | A dependency is removed and it does not affect the public API of the package                                                                  | `minor`             |
+|           | A dependency is removed and it does affect the public API of the package                                                                      | `major`             |
+|           | The version of a dependency is increased to a newer minor or patch version                                                                    | `minor`             |
+|           | The version of a dependency is increased to a newer major version                                                                             | `major`             |
+| CSS       | [The `display` property used for the container of `children` is changed](#the-display-property-used-for-the-container-of-children-is-changed) | potentially `major` |
 
 ## Reference
 
@@ -96,3 +98,28 @@ work.
 // change
 const t1: Example = 'd';
 ```
+
+### The `display` property used for the container of `children` is changed
+
+semver bump: potentially **major**
+
+When a React component accepts `children` as an argument, changing the value of
+the `display` property for that container may be considered a breaking change.
+
+Consider the situation where we move from `block` to `flex` and how this might
+change the flow layout of the contents of the component. In situations where
+this order is preserved, this may **not** be considered a breaking change and
+could be considered a refactor.
+
+However, depending on the type of elements used as children, moving from `block`
+to `flex` could also cause unexpected layout changes unrelated to its flow
+layout. For example, there may be whitespace that is important in the following
+markup:
+
+```html
+<button type="button" class="custom-button">Save <span class="custom-class">changes</span></button>
+```
+
+In this situation, changing the layout of the `button` to `flex` would collapse
+the whitespace present between the text "Save" and "changes" and would be
+considered a breaking change.
diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
@@ -88,14 +88,16 @@ import {BaseStyles, Box, Heading} from '@primer/react'
 export default () => (
   <BaseStyles>
     <Box m={4}>
-      <Heading sx={{mb: 2}}>Hello, world!</Heading>
+      <Heading as="h2" sx={{mb: 2}}>
+        Hello, world!
+      </Heading>
       <p>This will get Primer text styles.</p>
     </Box>
   </BaseStyles>
 )
 ```
 
-This will apply the same `color`, `font-family`, and `line-height` styles to the `<body>` as [Primer CSS's base styles](https://github.com/primer/css/blob/master/src/base/base.scss#L15-L20).
+This will apply the same `color`, `font-family`, and `line-height` styles to the `<body>` as [Primer CSS's base styles](https://github.com/primer/css/blob/main/src/base/base.scss#L15-L20).
 
 ## Static CSS rendering