diff --git a/AGENTS.md b/AGENTS.md
index cba7d7df..30f3dfd9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,7 +22,7 @@ Perf benches
 - Hot paths: `packages/system/src/style.ts`, `packages/util/src/index.ts` (`merge`/`assign`/`flattenStrings`/`get`), `packages/core/src/transform.ts`, `packages/emotion/src/createCssFunction.ts`.
 
 Module augmentation (consumer contract)
-- `declare module '@xstyled/system' { export interface Theme { … } }` from `styled.d.ts`. Augmenting any other module specifier won't reach the system types.
+- Docs augment the binding (`declare module '@xstyled/styled-components'` or `'@xstyled/emotion'`), which re-exports `Theme`. `colors` uses `Omit` plus an intersection so the default palette stays. The augmentation test in `packages/system/type-tests-aug/` imports `@xstyled/system` directly and still augments that module.
 
 Type gotchas
 - `useTheme` in `@xstyled/emotion` returns `@emotion/react`'s `Theme`, not `@xstyled/system`'s. Emotion users augment `@emotion/react` separately.
diff --git a/packages/babel-preset-emotion-css-prop/README.md b/packages/babel-preset-emotion-css-prop/README.md
index fa10d870..f5c98d28 100644
--- a/packages/babel-preset-emotion-css-prop/README.md
+++ b/packages/babel-preset-emotion-css-prop/README.md
@@ -2,4 +2,10 @@
 
 Same interface as [babel-preset-css-prop](https://github.com/emotion-js/emotion/tree/master/packages/babel-preset-css-prop).
 
+```bash
+npm install @xstyled/babel-preset-emotion-css-prop @babel/core@^7
+```
+
+The preset peers on `@babel/core` `^7`. Babel 8 breaks this preset with `path.hoist is not a function`. Yarn 1 does not install the peer, so install `@babel/core@^7` directly.
+
 See [xstyled documentation](https://xstyled.dev)
diff --git a/packages/system/README.md b/packages/system/README.md
index 7ec6b84f..1706964f 100644
--- a/packages/system/README.md
+++ b/packages/system/README.md
@@ -28,6 +28,12 @@ Quicklinks to some of the most-visited pages:
 
 ## Example
 
+The example imports `styled-components`. Install it for this sample only. An Emotion app should not add a second CSS-in-JS runtime.
+
+```bash
+npm install styled-components
+```
+
 ```js
 import styled from 'styled-components'
 import { system } from '@xstyled/system'
diff --git a/packages/system/type-tests-aug/augmentation.test-d.ts b/packages/system/type-tests-aug/augmentation.test-d.ts
index c8994eea..ba0c8c97 100644
--- a/packages/system/type-tests-aug/augmentation.test-d.ts
+++ b/packages/system/type-tests-aug/augmentation.test-d.ts
@@ -1,19 +1,10 @@
 /**
- * Pins down how a downstream consumer is meant to specialise xstyled's
- * `Theme` via module augmentation (#344 / #417 / #418). The contract,
- * as documented at website/pages/docs/core-concepts/typescript.mdx, is:
- *
- *   declare module '@xstyled/system' {
- *     export interface Theme {
- *       colors: { ... }
- *     }
- *   }
- *
- * This file mirrors that exactly — importing from `@xstyled/system` and
- * augmenting `@xstyled/system` — so the test exercises the same code path
- * a real consumer hits. The `tsconfig.aug.json` project owns this file,
- * which keeps the project-wide augmentation from leaking into the normal
- * src compile.
+ * Pins down module augmentation of `Theme` (#344 / #417 / #418).
+ * This file imports `@xstyled/system` directly, so it augments that module.
+ * The docs augment the binding instead (`@xstyled/styled-components` or
+ * `@xstyled/emotion`), which re-exports `Theme`. The `tsconfig.aug.json`
+ * project owns this file, which keeps the project-wide augmentation from
+ * leaking into the normal src compile.
  *
  * Requires `yarn build` to have produced `packages/system/dist/index.d.ts`
  * first (the workspace symlink `node_modules/@xstyled/system` resolves
diff --git a/website/pages/docs/core-concepts/prop-types.mdx b/website/pages/docs/core-concepts/prop-types.mdx
index 23051aa8..e598ab27 100644
--- a/website/pages/docs/core-concepts/prop-types.mdx
+++ b/website/pages/docs/core-concepts/prop-types.mdx
@@ -15,16 +15,17 @@ Add Prop Types on your declarative components.
 ## Installation
 
 ```
-npm i @xstyled/prop-types
+npm i @xstyled/prop-types @xstyled/styled-components styled-components
 ```
 
+`prop-types` is a peer dependency of `@xstyled/prop-types`. npm and pnpm install it. Yarn 1 does not, so install `prop-types` directly or loading the library throws `Cannot find package 'prop-types'`.
+
 ## Usage
 
 `getSystemPropTypes` let you get prop types from a system utility.
 
 ```js
-import styled from 'styled-components'
-import { compose, space, color } from '@xstyled/system'
+import styled, { compose, space, color } from '@xstyled/styled-components'
 import { getSystemPropTypes } from '@xstyled/prop-types'
 
 const customSystem = compose(space, color)
diff --git a/website/pages/docs/core-concepts/typescript.mdx b/website/pages/docs/core-concepts/typescript.mdx
index 76e26ad5..070ac804 100644
--- a/website/pages/docs/core-concepts/typescript.mdx
+++ b/website/pages/docs/core-concepts/typescript.mdx
@@ -18,23 +18,26 @@ You may have to configure styled-components or Emotion, especially if you use a
 
 ### Create a declaration file
 
+`@xstyled/styled-components` re-exports `Theme`. Augment that package, the one the install command already added.
+
+`colors` is omitted and then intersected. Replacing the default palette outright is a type error, because the new `colors` would be missing the built-in keys.
+
 ```js
 // styled.d.ts
 
-// import original module declarations
 import 'styled-components'
-import '@xstyled/system'
 import {
   ITheme,
   DefaultTheme as XStyledDefaultTheme,
 } from '@xstyled/styled-components'
 
-interface AppTheme extends ITheme, XStyledDefaultTheme {
-  /* Customize your theme */
+interface AppTheme extends ITheme, Omit<XStyledDefaultTheme, 'colors'> {
+  colors: XStyledDefaultTheme['colors'] & {
+    brand: string
+  }
 }
 
-// and extend them!
-declare module '@xstyled/system' {
+declare module '@xstyled/styled-components' {
   export interface Theme extends AppTheme {}
 }
 declare module 'styled-components' {
@@ -48,26 +51,30 @@ Read [styled-components TypeScript guide](https://styled-components.com/docs/api
 
 ### Create a declaration file
 
+`@xstyled/emotion` re-exports `Theme`. Augment that package, the one the install command already added. `useTheme` from this package is Emotion's theme, so `@emotion/react` is augmented too.
+
+`colors` is omitted and then intersected. Replacing the default palette outright is a type error, because the new `colors` would be missing the built-in keys.
+
 ```js
 // styled.d.ts
 
-// import original module declarations
-import '@xstyled/system'
 import '@emotion/react'
-import { ITheme, DefaultTheme as XStyledDefaultTheme } from '@xstyled/emotion'
+import {
+  ITheme,
+  DefaultTheme as XStyledDefaultTheme,
+} from '@xstyled/emotion'
 
-interface AppTheme extends ITheme, XStyledDefaultTheme {
-  /* Customize your theme */
+interface AppTheme extends ITheme, Omit<XStyledDefaultTheme, 'colors'> {
+  colors: XStyledDefaultTheme['colors'] & {
+    brand: string
+  }
 }
 
-// and extend them!
-declare module '@xstyled/system' {
+declare module '@xstyled/emotion' {
   export interface Theme extends AppTheme {}
 }
 declare module '@emotion/react' {
-  export interface Theme extends XStyledDefaultTheme {
-    /* Customize your theme */
-  }
+  export interface Theme extends AppTheme {}
 }
 ```
 
diff --git a/website/pages/docs/getting-started/migrate-from-emotion.mdx b/website/pages/docs/getting-started/migrate-from-emotion.mdx
index 871d90f0..f2338dba 100644
--- a/website/pages/docs/getting-started/migrate-from-emotion.mdx
+++ b/website/pages/docs/getting-started/migrate-from-emotion.mdx
@@ -209,6 +209,12 @@ const Button = ({ children }) => {
 
 To avoid the `/** @jsx jsx */` you can use `@xstyled/babel-preset-emotion-css-prop`. It has the same interface as `@emotion/babel-preset-css-prop`, see [Emotion documentation](https://emotion.sh/docs/css-prop#babel-preset).
 
+```
+npm install @xstyled/babel-preset-emotion-css-prop @babel/core@^7
+```
+
+The preset peers on `@babel/core` `^7`. Babel 8 breaks this preset with `path.hoist is not a function`. Yarn 1 does not install the peer, so install `@babel/core@^7` directly.
+
 **.babelrc**
 
 ```js