From 8f27b700788d9bf6f7fe447498629c750d58fb1b Mon Sep 17 00:00:00 2001
From: Van Anderson <van.m.anderson@gmail.com>
Date: Tue, 22 Jun 2021 14:29:27 -0500
Subject: [PATCH] Update documentation

---
 docs/content/Flex.md     | 25 +++++++++++++++++++++++++
 docs/content/Grid.md     | 31 +++++++++++++++++++++++++++++++
 docs/content/Position.md | 25 +++++++++++++++++++++++++
 3 files changed, 81 insertions(+)

diff --git a/docs/content/Flex.md b/docs/content/Flex.md
index ab342589a41..a373986222f 100644
--- a/docs/content/Flex.md
+++ b/docs/content/Flex.md
@@ -1,11 +1,36 @@
 ---
 title: Flex
+status: Deprecated
 ---
 
 The `Flex` component behaves the same as the `Box` component except that it has `display: flex` set by default.
 
 _Previously, a `Flex.Item` component was used for flex item specific properties; `Box` now contains all those properties and should be used in its place._
 
+## Deprecation
+
+Please use [Box](/Box) instead.
+
+_Before:_
+
+```
+<Flex flexWrap="nowrap">
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    Item 1
+  </Box>
+</Flex>
+```
+
+_After:_
+
+```
+<Box display="flex" flexWrap="nowrap">
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    Item 1
+  </Box>
+</Box>
+```
+
 ## Default example
 
 ```jsx live
diff --git a/docs/content/Grid.md b/docs/content/Grid.md
index 315c2de8b27..0c102ac394a 100644
--- a/docs/content/Grid.md
+++ b/docs/content/Grid.md
@@ -1,9 +1,40 @@
 ---
 title: Grid
+status: Deprecated
 ---
 
 Grid is a component that exposes grid system props. See the [CSS Tricks Complete Guide to Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) to learn more about Grid Layout.
 
+## Deprecation
+
+Please use [Box](/Box) instead.
+
+_Before:_
+
+```
+<Grid gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    1
+  </Box>
+  <Box p={3} color="text.inverse" bg="bg.warningInverse">
+    2
+  </Box>
+</Grid>
+```
+
+_After:_
+
+```
+<Box display="grid" gridTemplateColumns="repeat(2, auto)" gridGap={3}>
+  <Box p={3} color="text.inverse" bg="bg.infoInverse">
+    1
+  </Box>
+  <Box p={3} color="text.inverse" bg="bg.warningInverse">
+    2
+  </Box>
+</Box>
+```
+
 ## Default example
 
 ```jsx live
diff --git a/docs/content/Position.md b/docs/content/Position.md
index 3ff968176d4..5f6ea9c7fe4 100644
--- a/docs/content/Position.md
+++ b/docs/content/Position.md
@@ -1,9 +1,34 @@
 ---
 title: Position Components
+status: Deprecated
 ---
 
 The Position component is a wrapper component that gives the containing component css positioning abilities.
 
+## Deprecation
+
+Please use [Box](/Box) instead.
+
+_Before:_
+
+```
+<Position position="absolute" {...props}>x</Position>
+<Absolute {...props}>x</Absolute>
+<Relative {...props}>x</Relative>
+<Fixed {...props}>x</Fixed>
+<Sticky {...props}>x</Sticky>
+```
+
+_After:_
+
+```
+<Box position="absolute" {...props}>x</Box>
+<Box position="absolute" {...props}>x</Box>
+<Box position="relative" {...props}>x</Box>
+<Box position="fixed" {...props}>x</Box>
+<Box position="sticky" {...props}>x</Box>
+```
+
 ## Default examples
 
 ```jsx live