diff --git a/docs/content/guidelines/design.mdx b/docs/content/guidelines/design.mdx
new file mode 100644
index 000000000..c2dab40cc
--- /dev/null
+++ b/docs/content/guidelines/design.mdx
@@ -0,0 +1,303 @@
+---
+title: Design guidelines
+---
+
+import {Grid, Flex, Box} from '@primer/components'
+
+These are guidelines to use as a reference when designing new octicons.
+
+## Grid sizes
+
+Design two versions of each icon: a 16px version and a 24px version.
+
+
+
+
+ 
+
+
16x16 grid
+
+
+ 
+
+
24x24 grid
+
+
+ 
+
+
1.5px stroke on 16px icon
+
+
+ 
+
+
Circle on 16x16 grid
+
+
+ 
+
+
Circle on 16x16 grid example
+
+
+ 
+
+
Circle on 24x24 grid
+
+
+ 
+
+
Circle on 24x24 grid example
+
+
+ 
+
+
Square on 16x16 grid example
+
+
+ 
+
+
Square on 16x16 grid example
+
+
+ 
+
+
Square on 24x24 grid
+
+
+ 
+
+
Square on 16x16 grid example
+
+
+ 
+
+
Rectangle on 16x16 grid
+
+
+ 
+
+
Rectangle on 16x16 grid example
+
+
+ 
+
+
Rectangle on 24x24 grid
+
+
+ 
+
+
Rectangle on 24x24 grid example
+
+
+ 
+
+
Round caps and joins
+
+
+ 
+
+
1px radius on 16px icon
+
+
+ 
+
+
1px radius on 24px icon
+
+
+ 
+
+
0.25px radius on arrowhead
+
+
+ 
+
+
0.25px radius on bookmark in repo icon
+
+
+ 1px gap in comment-discussion icon
+
+
+Use a 1.5px gap around modifier elements, like lines and arrows.
+
+
+
+
+ 
+
+
1.5px gap in bookmark-slash icon
+
+
+ 
+
+
1.5px gap in package-dependencies icon
+
+
+ Use 2D perspective
+
+
+
+ 
+
+ Don't add unnecessary depth
+
+
+
+ 
+
+ Use depth when it adds meaning
+
+
+
+ 
+
+ Don't use a 2D perspective if it makes the icon unrecognizable
+
+
+
+## Pixel alignment
+
+Align the outer edge of shapes to pixel boundaries when possible.
+
+
+
+
+ 
+
+ Align the outer edge of shapes to pixel boundaries
+
+
+
+ 
+
+ Don't align the inner edge of shapes to pixel boundaries
+
+
+
+
+## Arrowheads
+
+Use line arrowheads unless there is not enough room.
+
+
+
+
+
+ 
+
+
Line arrowhead in sign-out icon
+
+
+ 
+
+
Filled arrowhead in link-external icon
+