From 805b67a68068201077a9a8c8e2b6fcf7de80338f Mon Sep 17 00:00:00 2001
From: pauliescanlon <pauliescanlon@gmail.com>
Date: Wed, 19 Feb 2020 09:06:17 +0530
Subject: [PATCH] add typescript

---
 packages/components/package.json              |  6 +-
 packages/components/src/Alert.js              | 20 ------
 packages/components/src/Alert.tsx             | 30 ++++++++
 packages/components/src/AspectImage.js        | 15 ----
 packages/components/src/AspectImage.tsx       | 27 +++++++
 packages/components/src/AspectRatio.js        | 32 ---------
 packages/components/src/AspectRatio.tsx       | 41 +++++++++++
 packages/components/src/Avatar.js             | 15 ----
 packages/components/src/Avatar.tsx            | 23 ++++++
 packages/components/src/Badge.js              | 21 ------
 packages/components/src/Badge.tsx             | 25 +++++++
 packages/components/src/Box.js                | 33 ---------
 packages/components/src/Box.tsx               | 72 +++++++++++++++++++
 .../components/src/{Button.js => Button.tsx}  | 18 +++--
 packages/components/src/Card.js               |  6 --
 packages/components/src/Card.tsx              | 16 +++++
 .../src/{Checkbox.js => Checkbox.tsx}         | 19 ++++-
 packages/components/src/Close.js              | 24 -------
 packages/components/src/Close.tsx             | 39 ++++++++++
 packages/components/src/Container.js          | 16 -----
 packages/components/src/Container.tsx         | 28 ++++++++
 packages/components/src/Divider.js            | 18 -----
 packages/components/src/Divider.tsx           | 26 +++++++
 .../components/src/{Donut.js => Donut.tsx}    | 24 ++++++-
 .../components/src/{Embed.js => Embed.tsx}    | 28 ++++++--
 packages/components/src/Flex.js               |  6 --
 packages/components/src/Flex.tsx              | 17 +++++
 packages/components/src/Grid.js               | 35 ---------
 packages/components/src/Grid.tsx              | 54 ++++++++++++++
 packages/components/src/Heading.js            | 17 -----
 packages/components/src/Heading.tsx           | 30 ++++++++
 packages/components/src/IconButton.js         | 25 -------
 packages/components/src/IconButton.tsx        | 41 +++++++++++
 packages/components/src/Image.js              | 16 -----
 packages/components/src/Image.tsx             | 26 +++++++
 packages/components/src/Input.js              | 24 -------
 packages/components/src/Input.tsx             | 34 +++++++++
 packages/components/src/Label.js              | 16 -----
 packages/components/src/Label.tsx             | 26 +++++++
 packages/components/src/Link.js               |  6 --
 packages/components/src/Link.tsx              | 22 ++++++
 packages/components/src/MenuButton.js         | 30 --------
 packages/components/src/MenuButton.tsx        | 42 +++++++++++
 packages/components/src/Message.js            | 19 -----
 packages/components/src/Message.tsx           | 30 ++++++++
 packages/components/src/NavLink.js            | 19 -----
 packages/components/src/NavLink.tsx           | 32 +++++++++
 .../src/{Progress.js => Progress.tsx}         | 17 +++--
 .../components/src/{Radio.js => Radio.tsx}    | 16 ++++-
 packages/components/src/SVG.js                | 14 ----
 packages/components/src/SVG.tsx               | 23 ++++++
 .../components/src/{Select.js => Select.tsx}  | 19 +++--
 packages/components/src/Slider.js             | 41 -----------
 packages/components/src/Slider.tsx            | 54 ++++++++++++++
 .../src/{Spinner.js => Spinner.tsx}           | 27 +++++--
 packages/components/src/Text.js               |  6 --
 packages/components/src/Text.tsx              | 17 +++++
 packages/components/src/Textarea.js           | 24 -------
 packages/components/src/Textarea.tsx          | 37 ++++++++++
 .../components/src/{index.js => index.ts}     |  0
 packages/components/src/{util.js => util.ts}  |  0
 packages/components/tsconfig.json             |  9 +++
 62 files changed, 962 insertions(+), 531 deletions(-)
 delete mode 100644 packages/components/src/Alert.js
 create mode 100644 packages/components/src/Alert.tsx
 delete mode 100644 packages/components/src/AspectImage.js
 create mode 100644 packages/components/src/AspectImage.tsx
 delete mode 100644 packages/components/src/AspectRatio.js
 create mode 100644 packages/components/src/AspectRatio.tsx
 delete mode 100644 packages/components/src/Avatar.js
 create mode 100644 packages/components/src/Avatar.tsx
 delete mode 100644 packages/components/src/Badge.js
 create mode 100644 packages/components/src/Badge.tsx
 delete mode 100644 packages/components/src/Box.js
 create mode 100644 packages/components/src/Box.tsx
 rename packages/components/src/{Button.js => Button.tsx} (50%)
 delete mode 100644 packages/components/src/Card.js
 create mode 100644 packages/components/src/Card.tsx
 rename packages/components/src/{Checkbox.js => Checkbox.tsx} (77%)
 delete mode 100644 packages/components/src/Close.js
 create mode 100644 packages/components/src/Close.tsx
 delete mode 100644 packages/components/src/Container.js
 create mode 100644 packages/components/src/Container.tsx
 delete mode 100644 packages/components/src/Divider.js
 create mode 100644 packages/components/src/Divider.tsx
 rename packages/components/src/{Donut.js => Donut.tsx} (65%)
 rename packages/components/src/{Embed.js => Embed.tsx} (54%)
 delete mode 100644 packages/components/src/Flex.js
 create mode 100644 packages/components/src/Flex.tsx
 delete mode 100644 packages/components/src/Grid.js
 create mode 100644 packages/components/src/Grid.tsx
 delete mode 100644 packages/components/src/Heading.js
 create mode 100644 packages/components/src/Heading.tsx
 delete mode 100644 packages/components/src/IconButton.js
 create mode 100644 packages/components/src/IconButton.tsx
 delete mode 100644 packages/components/src/Image.js
 create mode 100644 packages/components/src/Image.tsx
 delete mode 100644 packages/components/src/Input.js
 create mode 100644 packages/components/src/Input.tsx
 delete mode 100644 packages/components/src/Label.js
 create mode 100644 packages/components/src/Label.tsx
 delete mode 100644 packages/components/src/Link.js
 create mode 100644 packages/components/src/Link.tsx
 delete mode 100644 packages/components/src/MenuButton.js
 create mode 100644 packages/components/src/MenuButton.tsx
 delete mode 100644 packages/components/src/Message.js
 create mode 100644 packages/components/src/Message.tsx
 delete mode 100644 packages/components/src/NavLink.js
 create mode 100644 packages/components/src/NavLink.tsx
 rename packages/components/src/{Progress.js => Progress.tsx} (61%)
 rename packages/components/src/{Radio.js => Radio.tsx} (78%)
 delete mode 100644 packages/components/src/SVG.js
 create mode 100644 packages/components/src/SVG.tsx
 rename packages/components/src/{Select.js => Select.tsx} (61%)
 delete mode 100644 packages/components/src/Slider.js
 create mode 100644 packages/components/src/Slider.tsx
 rename packages/components/src/{Spinner.js => Spinner.tsx} (72%)
 delete mode 100644 packages/components/src/Text.js
 create mode 100644 packages/components/src/Text.tsx
 delete mode 100644 packages/components/src/Textarea.js
 create mode 100644 packages/components/src/Textarea.tsx
 rename packages/components/src/{index.js => index.ts} (100%)
 rename packages/components/src/{util.js => util.ts} (100%)
 create mode 100644 packages/components/tsconfig.json

diff --git a/packages/components/package.json b/packages/components/package.json
index 849616e59..d7f97dda6 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -1,12 +1,14 @@
 {
   "name": "@theme-ui/components",
   "version": "0.3.1",
+  "source": "src/index.ts",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
   "sideEffects": false,
   "scripts": {
-    "prepare": "microbundle --no-compress --jsx React.createElement",
-    "watch": "microbundle watch --no-compress --jsx React.createElement"
+    "prepare": "microbundle --no-compress --jsx React.createElement --tsconfig tsconfig.json",
+    "watch": "microbundle watch --no-compress --jsx React.createElement --tsconfig tsconfig.json"
   },
   "dependencies": {
     "@emotion/core": "^10.0.0",
diff --git a/packages/components/src/Alert.js b/packages/components/src/Alert.js
deleted file mode 100644
index 6a71f6864..000000000
--- a/packages/components/src/Alert.js
+++ /dev/null
@@ -1,20 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Alert = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    {...props}
-    __themeKey="alerts"
-    __css={{
-      display: 'flex',
-      alignItems: 'center',
-      px: 3,
-      py: 2,
-      fontWeight: 'bold',
-      color: 'white',
-      bg: 'primary',
-      borderRadius: 4,
-    }}
-  />
-))
diff --git a/packages/components/src/Alert.tsx b/packages/components/src/Alert.tsx
new file mode 100644
index 000000000..c7d7fd028
--- /dev/null
+++ b/packages/components/src/Alert.tsx
@@ -0,0 +1,30 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+type AlertProps = BoxProps
+/**
+ * Component for displaying messages, notifications, or other application state.
+ *
+ * Alert variants can be defined in `theme.alerts`.
+ * The Alert component uses `theme.alerts.primary` as its default variant.
+ */
+
+export const Alert: ForwardRef<HTMLDivElement, AlertProps> = React.forwardRef(
+  (props, ref) => (
+    <Box
+      ref={ref}
+      {...props}
+      __themeKey="alerts"
+      css={{
+        display: 'flex',
+        alignItems: 'center',
+        px: 3,
+        py: 2,
+        fontWeight: 'bold',
+        color: 'white',
+        bg: 'primary',
+        borderRadius: 4,
+      }}
+    />
+  )
+)
diff --git a/packages/components/src/AspectImage.js b/packages/components/src/AspectImage.js
deleted file mode 100644
index 6459a3674..000000000
--- a/packages/components/src/AspectImage.js
+++ /dev/null
@@ -1,15 +0,0 @@
-import React from 'react'
-import { AspectRatio } from './AspectRatio'
-import { Image } from './Image'
-
-export const AspectImage = React.forwardRef(({ ratio, ...props }, ref) => (
-  <AspectRatio ratio={ratio}>
-    <Image
-      ref={ref}
-      {...props}
-      __css={{
-        objectFit: 'cover',
-      }}
-    />
-  </AspectRatio>
-))
diff --git a/packages/components/src/AspectImage.tsx b/packages/components/src/AspectImage.tsx
new file mode 100644
index 000000000..255871578
--- /dev/null
+++ b/packages/components/src/AspectImage.tsx
@@ -0,0 +1,27 @@
+import React from 'react'
+import { AspectRatio } from './AspectRatio'
+import { Image, ImageProps } from './Image'
+import { ForwardRef } from './Box'
+
+interface AspectImageProps extends ImageProps {
+  ratio?: number
+}
+/**
+ * Image component constrained by as aspect ratio.
+ * @see https://theme-ui.com/components/aspect-image
+ */
+
+export const AspectImage: ForwardRef<
+  HTMLImageElement,
+  AspectImageProps
+> = React.forwardRef(({ ratio, ...props }, ref) => (
+  <AspectRatio ratio={ratio}>
+    <Image
+      ref={ref}
+      {...props}
+      __css={{
+        objectFit: 'cover',
+      }}
+    />
+  </AspectRatio>
+))
diff --git a/packages/components/src/AspectRatio.js b/packages/components/src/AspectRatio.js
deleted file mode 100644
index 8c563097f..000000000
--- a/packages/components/src/AspectRatio.js
+++ /dev/null
@@ -1,32 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const AspectRatio = React.forwardRef(
-  ({ ratio = 4 / 3, children, ...props }, ref) => (
-    <Box
-      ref={ref}
-      sx={{
-        position: 'relative',
-        overflow: 'hidden',
-      }}>
-      <Box
-        sx={{
-          width: '100%',
-          height: 0,
-          paddingBottom: 100 / ratio + '%',
-        }}
-      />
-      <Box
-        {...props}
-        __css={{
-          position: 'absolute',
-          top: 0,
-          right: 0,
-          bottom: 0,
-          left: 0,
-        }}>
-        {children}
-      </Box>
-    </Box>
-  )
-)
diff --git a/packages/components/src/AspectRatio.tsx b/packages/components/src/AspectRatio.tsx
new file mode 100644
index 000000000..441b54583
--- /dev/null
+++ b/packages/components/src/AspectRatio.tsx
@@ -0,0 +1,41 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+interface AspectRatioProps extends BoxProps {
+  ratio?: number
+}
+/**
+ * Component for maintaining a fluid-width aspect ratio
+ * @see https://theme-ui.com/components/aspect-ratio
+ */
+
+export const AspectRatio: ForwardRef<
+  HTMLDivElement,
+  AspectRatioProps
+> = React.forwardRef(({ ratio = 4 / 3, children, ...props }, ref) => (
+  <Box
+    ref={ref}
+    sx={{
+      position: 'relative',
+      overflow: 'hidden',
+    }}>
+    <Box
+      sx={{
+        width: '100%',
+        height: 0,
+        paddingBottom: 100 / ratio + '%',
+      }}
+    />
+    <Box
+      {...props}
+      css={{
+        position: 'absolute',
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0,
+      }}>
+      {children}
+    </Box>
+  </Box>
+))
diff --git a/packages/components/src/Avatar.js b/packages/components/src/Avatar.js
deleted file mode 100644
index ff7a0110b..000000000
--- a/packages/components/src/Avatar.js
+++ /dev/null
@@ -1,15 +0,0 @@
-import React from 'react'
-import { Image } from './Image'
-
-export const Avatar = React.forwardRef(({ size = 48, ...props }, ref) => (
-  <Image
-    ref={ref}
-    width={size}
-    height={size}
-    variant="avatar"
-    {...props}
-    __css={{
-      borderRadius: 9999,
-    }}
-  />
-))
diff --git a/packages/components/src/Avatar.tsx b/packages/components/src/Avatar.tsx
new file mode 100644
index 000000000..1d40c9bbc
--- /dev/null
+++ b/packages/components/src/Avatar.tsx
@@ -0,0 +1,23 @@
+import React from 'react'
+import { Image, ImageProps } from './Image'
+import { ForwardRef } from './Box'
+
+interface AvatarProps extends ImageProps {
+  size?: number | string
+}
+
+export const Avatar: ForwardRef<
+  HTMLImageElement,
+  AvatarProps
+> = React.forwardRef(({ size = 48, ...props }, ref) => (
+  <Image
+    ref={ref}
+    width={size}
+    height={size}
+    variant="avatar"
+    {...props}
+    css={{
+      borderRadius: 9999,
+    }}
+  />
+))
diff --git a/packages/components/src/Badge.js b/packages/components/src/Badge.js
deleted file mode 100644
index 912f59ead..000000000
--- a/packages/components/src/Badge.js
+++ /dev/null
@@ -1,21 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Badge = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    {...props}
-    __themeKey="badges"
-    __css={{
-      display: 'inline-block',
-      verticalAlign: 'baseline',
-      fontSize: 0,
-      fontWeight: 'bold',
-      whiteSpace: 'nowrap',
-      px: 1,
-      borderRadius: 2,
-      color: 'white',
-      bg: 'primary',
-    }}
-  />
-))
diff --git a/packages/components/src/Badge.tsx b/packages/components/src/Badge.tsx
new file mode 100644
index 000000000..9669066b5
--- /dev/null
+++ b/packages/components/src/Badge.tsx
@@ -0,0 +1,25 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export type BadgeProps = BoxProps
+
+export const Badge: ForwardRef<HTMLDivElement, BadgeProps> = React.forwardRef(
+  (props, ref) => (
+    <Box
+      ref={ref}
+      {...props}
+      __themeKey="badges"
+      css={{
+        display: 'inline-block',
+        verticalAlign: 'baseline',
+        fontSize: 0,
+        fontWeight: 'bold',
+        whiteSpace: 'nowrap',
+        px: 1,
+        borderRadius: 2,
+        color: 'white',
+        bg: 'primary',
+      }}
+    />
+  )
+)
diff --git a/packages/components/src/Box.js b/packages/components/src/Box.js
deleted file mode 100644
index c4c0c0bfa..000000000
--- a/packages/components/src/Box.js
+++ /dev/null
@@ -1,33 +0,0 @@
-import styled from '@emotion/styled'
-import { css, get } from '@theme-ui/css'
-import { createShouldForwardProp } from '@styled-system/should-forward-prop'
-import space from '@styled-system/space'
-import color from '@styled-system/color'
-
-const shouldForwardProp = createShouldForwardProp([
-  ...space.propNames,
-  ...color.propNames,
-])
-
-const sx = props => css(props.sx)(props.theme)
-const base = props => css(props.__css)(props.theme)
-const variant = ({ theme, variant, __themeKey = 'variants' }) =>
-  css(get(theme, __themeKey + '.' + variant, get(theme, variant)))
-
-export const Box = styled('div', {
-  shouldForwardProp,
-})(
-  {
-    boxSizing: 'border-box',
-    margin: 0,
-    minWidth: 0,
-  },
-  base,
-  variant,
-  space,
-  color,
-  sx,
-  props => props.css
-)
-
-export default Box
diff --git a/packages/components/src/Box.tsx b/packages/components/src/Box.tsx
new file mode 100644
index 000000000..c70fe6c4c
--- /dev/null
+++ b/packages/components/src/Box.tsx
@@ -0,0 +1,72 @@
+import styled from '@emotion/styled'
+import { css, get } from '@theme-ui/css'
+import { createShouldForwardProp } from '@styled-system/should-forward-prop'
+import space from '@styled-system/space'
+import color from '@styled-system/color'
+
+import { StyledComponent } from '@emotion/styled'
+import { InterpolationWithTheme } from '@emotion/core'
+import { SxStyleProp } from 'theme-ui'
+import { SpaceProps, ColorProps } from 'styled-system'
+
+export type Omit<T, K> = Pick<T, Exclude<keyof T, K>>
+
+export type Assign<T, U> = {
+  [P in keyof (T & U)]: P extends keyof T
+    ? T[P]
+    : P extends keyof U
+    ? U[P]
+    : never
+}
+
+export type ForwardRef<T, P> = React.ForwardRefExoticComponent<
+  React.PropsWithoutRef<P> & React.RefAttributes<T>
+>
+
+export interface BoxOwnProps extends SpaceProps, ColorProps {
+  as?: React.ElementType
+  variant?: string
+  sx?: SxStyleProp
+  css?: InterpolationWithTheme<any>
+  __themeKey?: string //TODO is __themeKey a "keyof / typeof" from the theme spec?
+}
+
+export interface BoxProps
+  extends Assign<React.ComponentProps<'div'>, BoxOwnProps> {}
+
+/**
+ * Use the Box component as a layout primitive to add margin, padding, and colors to content.
+ * @see https://theme-ui.com/components/box
+ */
+
+const shouldForwardProp = createShouldForwardProp([
+  ...space.propNames,
+  ...color.propNames,
+])
+
+const sx = props => css(props.sx)(props.theme)
+const base = props => css(props.__css)(props.theme)
+const variant = ({ theme, variant, __themeKey = 'variants' }) =>
+  css(get(theme, __themeKey + '.' + variant, get(theme, variant)))
+
+export const Box: StyledComponent<
+  React.ComponentProps<'div'>,
+  BoxOwnProps,
+  {}
+> = styled('div', {
+  shouldForwardProp,
+})(
+  {
+    boxSizing: 'border-box',
+    margin: 0,
+    minWidth: 0,
+  },
+  base,
+  variant,
+  space,
+  color,
+  sx,
+  props => props.css
+)
+
+export default Box
diff --git a/packages/components/src/Button.js b/packages/components/src/Button.tsx
similarity index 50%
rename from packages/components/src/Button.js
rename to packages/components/src/Button.tsx
index 100224899..a22575a15 100644
--- a/packages/components/src/Button.js
+++ b/packages/components/src/Button.tsx
@@ -1,14 +1,24 @@
 import React from 'react'
-import Box from './Box'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
 
-export const Button = React.forwardRef((props, ref) => (
+export interface ButtonProps
+  extends Assign<React.ComponentPropsWithRef<'button'>, BoxOwnProps> {}
+/**
+ * Primitive button component with variants
+ * @see https://theme-ui.com/components/button
+ */
+
+export const Button: ForwardRef<
+  HTMLButtonElement,
+  ButtonProps
+> = React.forwardRef((props, ref) => (
   <Box
-    ref={ref}
+    ref={ref} // TODO
     as="button"
     variant="primary"
     {...props}
     __themeKey="buttons"
-    __css={{
+    css={{
       appearance: 'none',
       display: 'inline-block',
       textAlign: 'center',
diff --git a/packages/components/src/Card.js b/packages/components/src/Card.js
deleted file mode 100644
index ead00ca51..000000000
--- a/packages/components/src/Card.js
+++ /dev/null
@@ -1,6 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Card = React.forwardRef((props, ref) => (
-  <Box ref={ref} variant="primary" {...props} __themeKey="cards" />
-))
diff --git a/packages/components/src/Card.tsx b/packages/components/src/Card.tsx
new file mode 100644
index 000000000..dfce34e05
--- /dev/null
+++ b/packages/components/src/Card.tsx
@@ -0,0 +1,16 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export type CardProps = BoxProps
+/**
+ * Card style variants can be defined in the `theme.cards` object.
+ * By default the Card component uses the `theme.cards.primary` variant.
+ * @see https://theme-ui.com/components/card
+ */
+
+export const Card: ForwardRef<
+  HTMLDivElement,
+  CardProps
+> = React.forwardRef((props, ref) => (
+  <Box ref={ref} variant="primary" {...props} __themeKey="cards" />
+))
diff --git a/packages/components/src/Checkbox.js b/packages/components/src/Checkbox.tsx
similarity index 77%
rename from packages/components/src/Checkbox.js
rename to packages/components/src/Checkbox.tsx
index 65803c655..29e506c4e 100644
--- a/packages/components/src/Checkbox.js
+++ b/packages/components/src/Checkbox.tsx
@@ -1,7 +1,17 @@
 import React from 'react'
-import Box from './Box'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
 import SVG from './SVG'
 
+export interface CheckboxProps
+  extends Assign<React.ComponentProps<'input'>, BoxOwnProps> {}
+/**
+ * Form checkbox input component
+ *
+ * Checkbox variants can be defined in `theme.forms` and the
+ * component uses the `theme.forms.checkbox` variant by default.
+ * @see https://theme-ui.com/components/checkbox/
+ */
+
 const CheckboxChecked = props => (
   <SVG {...props}>
     <path d="M19 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.11 0 2-.9 2-2V5c0-1.1-.89-2-2-2zm-9 14l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z" />
@@ -37,7 +47,10 @@ const CheckboxIcon = props => (
   </React.Fragment>
 )
 
-export const Checkbox = React.forwardRef(
+export const Checkbox: ForwardRef<
+  HTMLInputElement,
+  CheckboxProps
+> = React.forwardRef(
   ({ className, sx, variant = 'checkbox', ...props }, ref) => (
     <Box>
       <Box
@@ -61,7 +74,7 @@ export const Checkbox = React.forwardRef(
         variant={variant}
         className={className}
         sx={sx}
-        __css={{
+        css={{
           mr: 2,
           borderRadius: 4,
           color: 'gray',
diff --git a/packages/components/src/Close.js b/packages/components/src/Close.js
deleted file mode 100644
index 8eb9b9b38..000000000
--- a/packages/components/src/Close.js
+++ /dev/null
@@ -1,24 +0,0 @@
-import React from 'react'
-import { IconButton } from './IconButton'
-
-const x = (
-  <svg
-    xmlns="http://www.w3.org/2000/svg"
-    width="24"
-    height="24"
-    fill="currentcolor"
-    viewBox="0 0 24 24">
-    <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z" />
-  </svg>
-)
-
-export const Close = React.forwardRef(({ size = 32, ...props }, ref) => (
-  <IconButton
-    ref={ref}
-    title="Close"
-    aria-label="Close"
-    variant="close"
-    {...props}
-    children={x}
-  />
-))
diff --git a/packages/components/src/Close.tsx b/packages/components/src/Close.tsx
new file mode 100644
index 000000000..1dc7707ca
--- /dev/null
+++ b/packages/components/src/Close.tsx
@@ -0,0 +1,39 @@
+import React from 'react'
+import { IconButton, IconButtonProps } from './IconButton'
+import { ForwardRef } from './Box'
+
+interface CloseProps extends Omit<IconButtonProps, 'children'> {}
+/**
+ * Button with close (×) icon.
+ *
+ * The Close component renders as a <button> element by default.
+ * Pass any button attributes as props to the component.
+ *
+ * Close component variants can be defined in the theme.buttons object.
+ * The Close component uses theme.buttons.close as its default variant style.
+ */
+
+const x = (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    fill="currentcolor"
+    viewBox="0 0 24 24">
+    <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z" />
+  </svg>
+)
+
+export const Close: ForwardRef<
+  HTMLButtonElement,
+  CloseProps
+> = React.forwardRef(({ size = 32, ...props }, ref) => (
+  <IconButton
+    ref={ref}
+    title="Close"
+    aria-label="Close"
+    variant="close"
+    {...props}
+    children={x} //TODO should x be an SVG component
+  />
+))
diff --git a/packages/components/src/Container.js b/packages/components/src/Container.js
deleted file mode 100644
index 5697e059b..000000000
--- a/packages/components/src/Container.js
+++ /dev/null
@@ -1,16 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Container = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    variant="container"
-    {...props}
-    __themeKey="layout"
-    __css={{
-      width: '100%',
-      maxWidth: 'container',
-      mx: 'auto',
-    }}
-  />
-))
diff --git a/packages/components/src/Container.tsx b/packages/components/src/Container.tsx
new file mode 100644
index 000000000..df476811c
--- /dev/null
+++ b/packages/components/src/Container.tsx
@@ -0,0 +1,28 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export type ContainerProps = BoxProps
+/**
+ * Centered, max-width layout component
+ *
+ * Container variants can be defined in the `theme.layout` object.
+ * The Container component uses `theme.layout.container` as its default variant style.
+ * @see https://theme-ui.com/components/container
+ */
+
+export const Container: ForwardRef<
+  HTMLDivElement,
+  ContainerProps
+> = React.forwardRef((props, ref) => (
+  <Box
+    ref={ref}
+    variant="container"
+    {...props}
+    __themeKey="layout"
+    css={{
+      width: '100%',
+      maxWidth: 'container',
+      mx: 'auto',
+    }}
+  />
+))
diff --git a/packages/components/src/Divider.js b/packages/components/src/Divider.js
deleted file mode 100644
index da52c442c..000000000
--- a/packages/components/src/Divider.js
+++ /dev/null
@@ -1,18 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Divider = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="hr"
-    variant="styles.hr"
-    {...props}
-    __css={{
-      color: 'gray',
-      m: 0,
-      my: 2,
-      border: 0,
-      borderBottom: '1px solid',
-    }}
-  />
-))
diff --git a/packages/components/src/Divider.tsx b/packages/components/src/Divider.tsx
new file mode 100644
index 000000000..9c843eb49
--- /dev/null
+++ b/packages/components/src/Divider.tsx
@@ -0,0 +1,26 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export type DividerProps = BoxProps
+/**
+ * The Divider component reuses styles from `theme.styles.hr` as its default variant.
+ */
+
+export const Divider: ForwardRef<
+  HTMLDivElement,
+  DividerProps
+> = React.forwardRef((props, ref) => (
+  <Box
+    ref={ref}
+    as="hr"
+    variant="styles.hr"
+    {...props}
+    css={{
+      color: 'gray',
+      m: 0,
+      my: 2,
+      border: 0,
+      borderBottom: '1px solid',
+    }}
+  />
+))
diff --git a/packages/components/src/Donut.js b/packages/components/src/Donut.tsx
similarity index 65%
rename from packages/components/src/Donut.js
rename to packages/components/src/Donut.tsx
index 9f0e0e305..069fcccec 100644
--- a/packages/components/src/Donut.js
+++ b/packages/components/src/Donut.tsx
@@ -1,7 +1,25 @@
 import React from 'react'
-import Box from './Box'
+import Box, { BoxOwnProps, ForwardRef } from './Box'
 
-export const Donut = React.forwardRef(
+export interface DonutProps
+  extends Omit<
+      React.SVGProps<SVGSVGElement>,
+      'opacity' | 'color' | 'css' | 'sx' | 'max' | 'min'
+    >,
+    BoxOwnProps {
+  size?: string | number
+  strokeWidth?: number
+  value: number
+  min?: number
+  max?: number
+  title?: string
+}
+/**
+ * Single value SVG donut chart
+ * @see https://theme-ui.com/components/donut/
+ */
+
+export const Donut: ForwardRef<SVGSVGElement, DonutProps> = React.forwardRef(
   (
     {
       size = 128,
@@ -20,7 +38,7 @@ export const Donut = React.forwardRef(
 
     return (
       <Box
-        ref={ref}
+        ref={ref} // TODO
         as="svg"
         viewBox="0 0 32 32"
         width={size}
diff --git a/packages/components/src/Embed.js b/packages/components/src/Embed.tsx
similarity index 54%
rename from packages/components/src/Embed.js
rename to packages/components/src/Embed.tsx
index 13d92149f..a5c1db3ed 100644
--- a/packages/components/src/Embed.js
+++ b/packages/components/src/Embed.tsx
@@ -1,7 +1,27 @@
 import React from 'react'
-import Box from './Box'
+import Box, { BoxProps, ForwardRef } from './Box'
 
-export const Embed = React.forwardRef(
+export interface EmbedProps extends BoxProps {
+  ratio?: number
+  src?: React.IframeHTMLAttributes<any>['src']
+  frameBorder?: React.IframeHTMLAttributes<any>['frameBorder']
+  allowFullScreen?: React.IframeHTMLAttributes<any>['allowFullScreen']
+  allow?: React.IframeHTMLAttributes<any>['allow']
+  width?: number
+  height?: number
+}
+/**
+ * Responsive iframe for video embeds.
+ *
+ * Embed variants can be defined anywhere in the theme object.
+ *
+ * @see https://theme-ui.com/components/embed
+ */
+
+export const Embed: ForwardRef<
+  HTMLIFrameElement,
+  EmbedProps
+> = React.forwardRef(
   (
     {
       ratio = 16 / 9,
@@ -17,7 +37,7 @@ export const Embed = React.forwardRef(
   ) => (
     <Box
       {...props}
-      __css={{
+      css={{
         width: '100%',
         height: 0,
         paddingBottom: 100 / ratio + '%',
@@ -27,7 +47,7 @@ export const Embed = React.forwardRef(
       <Box
         ref={ref}
         as="iframe"
-        src={src}
+        src={src} // TODO
         width={width}
         height={height}
         frameBorder={frameBorder}
diff --git a/packages/components/src/Flex.js b/packages/components/src/Flex.js
deleted file mode 100644
index 881f18c9f..000000000
--- a/packages/components/src/Flex.js
+++ /dev/null
@@ -1,6 +0,0 @@
-import styled from '@emotion/styled'
-import Box from './Box'
-
-export const Flex = styled(Box)({
-  display: 'flex',
-})
diff --git a/packages/components/src/Flex.tsx b/packages/components/src/Flex.tsx
new file mode 100644
index 000000000..847af80f6
--- /dev/null
+++ b/packages/components/src/Flex.tsx
@@ -0,0 +1,17 @@
+import styled from '@emotion/styled'
+import { StyledComponent } from '@emotion/styled'
+import Box, { BoxProps } from './Box'
+
+export type FlexProps = BoxProps
+/**
+ * Use the Flex component to create flexbox layouts.
+ * @see https://theme-ui.com/components/flex
+ */
+
+export const Flex: StyledComponent<
+  React.ComponentProps<'div'>,
+  FlexProps,
+  {}
+> = styled(Box)({
+  display: 'flex',
+})
diff --git a/packages/components/src/Grid.js b/packages/components/src/Grid.js
deleted file mode 100644
index e5c3a0416..000000000
--- a/packages/components/src/Grid.js
+++ /dev/null
@@ -1,35 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-const px = n => (typeof n === 'number' ? n + 'px' : n)
-
-const widthToColumns = width =>
-  Array.isArray(width)
-    ? width.map(widthToColumns)
-    : !!width && `repeat(auto-fit, minmax(${px(width)}, 1fr))`
-
-const countToColumns = n =>
-  Array.isArray(n)
-    ? n.map(countToColumns)
-    : !!n && (typeof n === 'number' ? `repeat(${n}, 1fr)` : n)
-
-export const Grid = React.forwardRef(
-  ({ width, columns, gap = 3, ...props }, ref) => {
-    const gridTemplateColumns = !!width
-      ? widthToColumns(width)
-      : countToColumns(columns)
-
-    return (
-      <Box
-        ref={ref}
-        {...props}
-        __themeKey="grids"
-        __css={{
-          display: 'grid',
-          gridGap: gap,
-          gridTemplateColumns,
-        }}
-      />
-    )
-  }
-)
diff --git a/packages/components/src/Grid.tsx b/packages/components/src/Grid.tsx
new file mode 100644
index 000000000..2cf9d4c9b
--- /dev/null
+++ b/packages/components/src/Grid.tsx
@@ -0,0 +1,54 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export interface GridProps extends BoxProps {
+  /**
+   * Minimum width of child elements
+   */
+  width?: string | number
+  /**
+   * 	Number of columns to use for the layout (cannot be used in conjunction with the width prop)
+   */
+  columns?: number
+  /**
+   * Space between child elements
+   */
+  gap?: string | number
+}
+/**
+ * CSS grid layout component to arrange direct child elements in a tiled grid layout.
+ * @see https://theme-ui.com/components/grid
+ */
+
+const px = n => (typeof n === 'number' ? n + 'px' : n)
+
+const widthToColumns = (width: string | number) =>
+  Array.isArray(width)
+    ? width.map(widthToColumns)
+    : !!width && `repeat(auto-fit, minmax(${px(width)}, 1fr))`
+
+const countToColumns = (n: number) =>
+  Array.isArray(n)
+    ? n.map(countToColumns)
+    : !!n && (typeof n === 'number' ? `repeat(${n}, 1fr)` : n)
+
+export const Grid: ForwardRef<HTMLDivElement, GridProps> = React.forwardRef(
+  ({ width, columns, gap = 3, ...props }: GridProps, ref) => {
+    const gridTemplateColumns = !!width
+      ? widthToColumns(width)
+      : countToColumns(columns)
+
+    return (
+      <Box
+        ref={ref}
+        {...props}
+        __themeKey="grids"
+        css={{
+          display: 'grid',
+          gridGap: gap,
+          gridTemplateColumns,
+        }}
+      />
+    )
+  }
+)
diff --git a/packages/components/src/Heading.js b/packages/components/src/Heading.js
deleted file mode 100644
index 67764fc59..000000000
--- a/packages/components/src/Heading.js
+++ /dev/null
@@ -1,17 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Heading = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="h2"
-    variant="heading"
-    {...props}
-    __themeKey="text"
-    __css={{
-      fontFamily: 'heading',
-      fontWeight: 'heading',
-      lineHeight: 'heading',
-    }}
-  />
-))
diff --git a/packages/components/src/Heading.tsx b/packages/components/src/Heading.tsx
new file mode 100644
index 000000000..8abfcbc11
--- /dev/null
+++ b/packages/components/src/Heading.tsx
@@ -0,0 +1,30 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface HeadingProps
+  extends Assign<React.ComponentPropsWithRef<'h2'>, BoxOwnProps> {}
+/**
+ * Primitive heading component, defaults to <h2>.
+ *
+ * Text style variants can be defined in the theme.text object.
+ * The Heading component uses theme.text.heading as its default variant style.
+ * @see https://theme-ui.com/components/heading
+ */
+
+export const Heading: ForwardRef<
+  HTMLHeadingElement,
+  HeadingProps
+> = React.forwardRef((props, ref) => (
+  <Box
+    ref={ref}
+    as="h2"
+    variant="heading"
+    {...props}
+    __themeKey="text"
+    css={{
+      fontFamily: 'heading',
+      fontWeight: 'heading', //TODO
+      lineHeight: 'heading',
+    }}
+  />
+))
diff --git a/packages/components/src/IconButton.js b/packages/components/src/IconButton.js
deleted file mode 100644
index f776cdd4b..000000000
--- a/packages/components/src/IconButton.js
+++ /dev/null
@@ -1,25 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const IconButton = React.forwardRef(({ size = 32, ...props }, ref) => (
-  <Box
-    ref={ref}
-    as="button"
-    variant="icon"
-    {...props}
-    __themeKey="buttons"
-    __css={{
-      appearance: 'none',
-      display: 'inline-flex',
-      alignItems: 'center',
-      justifyContent: 'center',
-      padding: 1,
-      width: size,
-      height: size,
-      color: 'inherit',
-      bg: 'transparent',
-      border: 'none',
-      borderRadius: 4,
-    }}
-  />
-))
diff --git a/packages/components/src/IconButton.tsx b/packages/components/src/IconButton.tsx
new file mode 100644
index 000000000..19de74f89
--- /dev/null
+++ b/packages/components/src/IconButton.tsx
@@ -0,0 +1,41 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface IconButtonProps
+  extends Assign<React.ComponentPropsWithRef<'button'>, BoxOwnProps> {
+  size?: number | string
+}
+/**
+ * Transparent button for SVG icons
+ *
+ * IconButton variants can be defined in the `theme.buttons` object.
+ * By default the IconButton component will use styles defined in `theme.buttons.icon`.
+ *
+ * @see https://theme-ui.com/components/icon-button
+ */
+
+export const IconButton: ForwardRef<
+  HTMLButtonElement,
+  IconButtonProps
+> = React.forwardRef(({ size = 32, ...props }, ref) => (
+  <Box
+    ref={ref} //TODO
+    as="button"
+    variant="icon"
+    {...props}
+    __themeKey="buttons"
+    css={{
+      appearance: 'none',
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: 1,
+      width: size,
+      height: size,
+      color: 'inherit',
+      bg: 'transparent',
+      border: 'none',
+      borderRadius: 4,
+    }}
+  />
+))
diff --git a/packages/components/src/Image.js b/packages/components/src/Image.js
deleted file mode 100644
index 915eeb271..000000000
--- a/packages/components/src/Image.js
+++ /dev/null
@@ -1,16 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Image = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="img"
-    {...props}
-    __themeKey="images"
-    __css={{
-      maxWidth: '100%',
-      height: 'auto',
-      ...props.__css,
-    }}
-  />
-))
diff --git a/packages/components/src/Image.tsx b/packages/components/src/Image.tsx
new file mode 100644
index 000000000..e61e26bae
--- /dev/null
+++ b/packages/components/src/Image.tsx
@@ -0,0 +1,26 @@
+import React from 'react'
+import Box from './Box'
+import { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface ImageProps
+  extends Assign<React.ComponentProps<'img'>, BoxOwnProps> {}
+/**
+ * Image style variants can be defined in the theme.images object.
+ * @see https://theme-ui.com/components/image/
+ */
+
+export const Image: ForwardRef<HTMLImageElement, ImageProps> = React.forwardRef(
+  (props, ref) => (
+    <Box
+      ref={ref}
+      as="img"
+      {...props}
+      __themeKey="images"
+      css={{
+        maxWidth: '100%',
+        height: 'auto',
+        ...(props.css as any), //TODO
+      }}
+    />
+  )
+)
diff --git a/packages/components/src/Input.js b/packages/components/src/Input.js
deleted file mode 100644
index 313a83d99..000000000
--- a/packages/components/src/Input.js
+++ /dev/null
@@ -1,24 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Input = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="input"
-    variant="input"
-    {...props}
-    __themeKey="forms"
-    __css={{
-      display: 'block',
-      width: '100%',
-      p: 2,
-      appearance: 'none',
-      fontSize: 'inherit',
-      lineHeight: 'inherit',
-      border: '1px solid',
-      borderRadius: 4,
-      color: 'inherit',
-      bg: 'transparent',
-    }}
-  />
-))
diff --git a/packages/components/src/Input.tsx b/packages/components/src/Input.tsx
new file mode 100644
index 000000000..3904d391c
--- /dev/null
+++ b/packages/components/src/Input.tsx
@@ -0,0 +1,34 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface InputProps
+  extends Assign<React.ComponentProps<'input'>, BoxOwnProps> {}
+/**
+ * Input variants can be defined in `theme.forms`
+ * and the component uses the `theme.forms.input` variant by default.
+ * @see https://theme-ui.com/components/input/
+ */
+
+export const Input: ForwardRef<HTMLInputElement, InputProps> = React.forwardRef(
+  (props, ref) => (
+    <Box
+      ref={ref}
+      as="input"
+      variant="input"
+      {...props}
+      __themeKey="forms"
+      css={{
+        display: 'block',
+        width: '100%',
+        p: 2,
+        appearance: 'none',
+        fontSize: 'inherit',
+        lineHeight: 'inherit',
+        border: '1px solid',
+        borderRadius: 4,
+        color: 'inherit',
+        bg: 'transparent',
+      }}
+    />
+  )
+)
diff --git a/packages/components/src/Label.js b/packages/components/src/Label.js
deleted file mode 100644
index 0f6070e3f..000000000
--- a/packages/components/src/Label.js
+++ /dev/null
@@ -1,16 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Label = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="label"
-    variant="label"
-    {...props}
-    __themeKey="forms"
-    __css={{
-      width: '100%',
-      display: 'flex',
-    }}
-  />
-))
diff --git a/packages/components/src/Label.tsx b/packages/components/src/Label.tsx
new file mode 100644
index 000000000..4c666b4dc
--- /dev/null
+++ b/packages/components/src/Label.tsx
@@ -0,0 +1,26 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface LabelProps
+  extends Assign<React.ComponentProps<'label'>, BoxOwnProps> {}
+/**
+ * Label variants can be defined in `theme.forms`
+ * and the component uses the `theme.forms.label` variant by default.
+ * @see https://theme-ui.com/components/label/
+ */
+
+export const Label: ForwardRef<HTMLLabelElement, LabelProps> = React.forwardRef(
+  (props, ref) => (
+    <Box
+      ref={ref} // TODO
+      as="label"
+      variant="label"
+      {...props}
+      __themeKey="forms"
+      css={{
+        width: '100%',
+        display: 'flex',
+      }}
+    />
+  )
+)
diff --git a/packages/components/src/Link.js b/packages/components/src/Link.js
deleted file mode 100644
index 2bbe19b0b..000000000
--- a/packages/components/src/Link.js
+++ /dev/null
@@ -1,6 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Link = React.forwardRef((props, ref) => (
-  <Box ref={ref} as="a" variant="styles.a" {...props} __themeKey="links" />
-))
diff --git a/packages/components/src/Link.tsx b/packages/components/src/Link.tsx
new file mode 100644
index 000000000..1e2da4b79
--- /dev/null
+++ b/packages/components/src/Link.tsx
@@ -0,0 +1,22 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface LinkProps
+  extends Assign<React.ComponentPropsWithRef<'a'>, BoxOwnProps> {}
+/**
+ * Link variants can be defined in the `theme.links` object.
+ * By default the Link component will use styles defined in `theme.styles.a`.
+ * @see https://theme-ui.com/components/link
+ */
+
+export const Link: ForwardRef<HTMLAnchorElement, LinkProps> = React.forwardRef(
+  (props, ref) => (
+    <Box
+      ref={ref} // TODO
+      as="a"
+      variant="styles.a"
+      {...props}
+      __themeKey="links"
+    />
+  )
+)
diff --git a/packages/components/src/MenuButton.js b/packages/components/src/MenuButton.js
deleted file mode 100644
index fd7b92709..000000000
--- a/packages/components/src/MenuButton.js
+++ /dev/null
@@ -1,30 +0,0 @@
-import React from 'react'
-import Box from './Box'
-import { IconButton } from './IconButton'
-
-export const MenuIcon = ({ size = 24 }) => (
-  <Box
-    as="svg"
-    xmlns="http://www.w3.org/2000/svg"
-    width={size}
-    height={size}
-    fill="currentcolor"
-    viewBox="0 0 24 24"
-    sx={{
-      display: 'block',
-      margin: 0,
-    }}>
-    <path d="M3 18h18v-2H3v2zm0-5h18v-2H3v2zm0-7v2h18V6H3z" />
-  </Box>
-)
-
-export const MenuButton = React.forwardRef((props, ref) => (
-  <IconButton
-    ref={ref}
-    title="Menu"
-    aria-label="Toggle Menu"
-    variant="menu"
-    {...props}>
-    <MenuIcon />
-  </IconButton>
-))
diff --git a/packages/components/src/MenuButton.tsx b/packages/components/src/MenuButton.tsx
new file mode 100644
index 000000000..4e08982ff
--- /dev/null
+++ b/packages/components/src/MenuButton.tsx
@@ -0,0 +1,42 @@
+import React from 'react'
+import Box, { ForwardRef } from './Box'
+import { IconButton, IconButtonProps } from './IconButton'
+
+export interface MenuButtonProps extends IconButtonProps {
+  size?: number | string
+}
+/**
+ * MenuButton variants can be defined in the `theme.buttons` object.
+ * By default the MenuButton component will use styles defined in `theme.buttons.menu`.
+ *
+ * @see https://theme-ui.com/components/menu-button
+ */
+
+export const MenuIcon: ForwardRef<HTMLButtonElement, MenuButtonProps> = ({
+  size = 24,
+}) => (
+  <Box
+    as="svg"
+    xmlns="http://www.w3.org/2000/svg" // TODO
+    width={size}
+    height={size}
+    fill="currentcolor"
+    viewBox="0 0 24 24"
+    sx={{
+      display: 'block',
+      margin: 0,
+    }}>
+    <path d="M3 18h18v-2H3v2zm0-5h18v-2H3v2zm0-7v2h18V6H3z" />
+  </Box>
+)
+
+export const MenuButton = React.forwardRef((props, ref) => (
+  <IconButton
+    ref={ref} // TODO
+    title="Menu"
+    aria-label="Toggle Menu"
+    variant="menu"
+    {...props}>
+    <MenuIcon />
+  </IconButton>
+))
diff --git a/packages/components/src/Message.js b/packages/components/src/Message.js
deleted file mode 100644
index 93715ef11..000000000
--- a/packages/components/src/Message.js
+++ /dev/null
@@ -1,19 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Message = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    {...props}
-    __themeKey="messages"
-    __css={{
-      padding: 3,
-      paddingLeft: t => t.space[3] - t.space[1],
-      borderLeftWidth: t => t.space[1],
-      borderLeftStyle: 'solid',
-      borderLeftColor: 'primary',
-      borderRadius: 4,
-      bg: 'highlight',
-    }}
-  />
-))
diff --git a/packages/components/src/Message.tsx b/packages/components/src/Message.tsx
new file mode 100644
index 000000000..205f67809
--- /dev/null
+++ b/packages/components/src/Message.tsx
@@ -0,0 +1,30 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export type MessageProps = BoxProps
+/**
+ * Styled Box component for callouts and inline messages
+ *
+ * Message variants can be defined in the theme.messages object.
+ * @see https://theme-ui.com/components/message
+ */
+
+export const Message: ForwardRef<
+  HTMLDivElement,
+  MessageProps
+> = React.forwardRef((props, ref) => (
+  <Box
+    ref={ref}
+    {...props}
+    __themeKey="messages"
+    css={{
+      padding: 3,
+      paddingLeft: t => t.space[3] - t.space[1], //TODO
+      borderLeftWidth: t => t.space[1], //TODO
+      borderLeftStyle: 'solid',
+      borderLeftColor: 'primary',
+      borderRadius: 4,
+      bg: 'highlight',
+    }}
+  />
+))
diff --git a/packages/components/src/NavLink.js b/packages/components/src/NavLink.js
deleted file mode 100644
index 8b6dbcd01..000000000
--- a/packages/components/src/NavLink.js
+++ /dev/null
@@ -1,19 +0,0 @@
-import React from 'react'
-import { Link } from './Link'
-
-export const NavLink = React.forwardRef((props, ref) => (
-  <Link
-    ref={ref}
-    variant="nav"
-    {...props}
-    __css={{
-      color: 'inherit',
-      textDecoration: 'none',
-      fontWeight: 'bold',
-      display: 'inline-block',
-      '&:hover, &:focus, &.active': {
-        color: 'primary',
-      },
-    }}
-  />
-))
diff --git a/packages/components/src/NavLink.tsx b/packages/components/src/NavLink.tsx
new file mode 100644
index 000000000..97f2b5905
--- /dev/null
+++ b/packages/components/src/NavLink.tsx
@@ -0,0 +1,32 @@
+import React from 'react'
+import { Link, LinkProps } from './Link'
+import { ForwardRef } from './Box'
+
+export type NavLinkProps = LinkProps
+/**
+ * Link component for use in navigation
+ *
+ * NavLink variants can be defined in the `theme.links` object.
+ * By default the NavLink component will use styles defined in `theme.links.nav`.
+ * @see https://theme-ui.com/components/nav-link
+ */
+
+export const NavLink: ForwardRef<
+  HTMLAnchorElement,
+  NavLinkProps
+> = React.forwardRef((props, ref) => (
+  <Link
+    ref={ref}
+    variant="nav"
+    {...props}
+    css={{
+      color: 'inherit',
+      textDecoration: 'none',
+      fontWeight: 'bold',
+      display: 'inline-block',
+      '&:hover, &:focus, &.active': {
+        color: 'primary',
+      },
+    }}
+  />
+))
diff --git a/packages/components/src/Progress.js b/packages/components/src/Progress.tsx
similarity index 61%
rename from packages/components/src/Progress.js
rename to packages/components/src/Progress.tsx
index cd651be99..e58a58917 100644
--- a/packages/components/src/Progress.js
+++ b/packages/components/src/Progress.tsx
@@ -1,13 +1,22 @@
 import React from 'react'
-import Box from './Box'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
 
-export const Progress = React.forwardRef((props, ref) => (
+export interface ProgressProps
+  extends Assign<React.ComponentProps<'progress'>, BoxOwnProps> {}
+/**
+ * @see https://theme-ui.com/components/progress/
+ */
+
+export const Progress: ForwardRef<
+  HTMLProgressElement,
+  ProgressProps
+> = React.forwardRef((props, ref) => (
   <Box
-    ref={ref}
+    ref={ref} //TODO
     as="progress"
     variant="styles.progress"
     {...props}
-    __css={{
+    css={{
       display: 'block',
       width: '100%',
       height: '4px',
diff --git a/packages/components/src/Radio.js b/packages/components/src/Radio.tsx
similarity index 78%
rename from packages/components/src/Radio.js
rename to packages/components/src/Radio.tsx
index a655872c3..ac2206e90 100644
--- a/packages/components/src/Radio.js
+++ b/packages/components/src/Radio.tsx
@@ -1,7 +1,17 @@
 import React from 'react'
-import Box from './Box'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
 import SVG from './SVG'
 
+export interface RadioProps
+  extends Assign<React.ComponentProps<'input'>, BoxOwnProps> {}
+/**
+ * Form radio input component
+ *
+ * Radio variants can be defined in `theme.forms` and the
+ * component uses the `theme.forms.radio variant` by default.
+ * @see https://theme-ui.com/components/radio/
+ */
+
 const RadioChecked = props => (
   <SVG {...props}>
     <path d="M12 7c-2.76 0-5 2.24-5 5s2.24 5 5 5 5-2.24 5-5-2.24-5-5-5zm0-5C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8z" />
@@ -37,7 +47,7 @@ const RadioIcon = props => (
   </React.Fragment>
 )
 
-export const Radio = React.forwardRef(
+export const Radio: ForwardRef<HTMLInputElement, RadioProps> = React.forwardRef(
   ({ className, sx, variant = 'radio', ...props }, ref) => (
     <Box>
       <Box
@@ -61,7 +71,7 @@ export const Radio = React.forwardRef(
         variant={variant}
         className={className}
         sx={sx}
-        __css={{
+        css={{
           // todo: system props??
           mr: 2,
           borderRadius: 9999,
diff --git a/packages/components/src/SVG.js b/packages/components/src/SVG.js
deleted file mode 100644
index a3f28e1d3..000000000
--- a/packages/components/src/SVG.js
+++ /dev/null
@@ -1,14 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export default ({ size = 24, ...props }) => (
-  <Box
-    as="svg"
-    xmlns="http://www.w3.org/2000/svg"
-    width={size + ''}
-    height={size + ''}
-    viewBox="0 0 24 24"
-    fill="currentcolor"
-    {...props}
-  />
-)
diff --git a/packages/components/src/SVG.tsx b/packages/components/src/SVG.tsx
new file mode 100644
index 000000000..25287596b
--- /dev/null
+++ b/packages/components/src/SVG.tsx
@@ -0,0 +1,23 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface SVGProps
+  extends Assign<React.ComponentProps<'svg'>, BoxOwnProps> {
+  size?: number | string
+}
+
+const SVG: ForwardRef<HTMLOrSVGElement, SVGProps> = React.forwardRef(
+  ({ size = 24, ...props }) => (
+    <Box
+      as="svg" //TODO
+      xmlns="http://www.w3.org/2000/svg"
+      width={size + ''}
+      height={size + ''}
+      viewBox="0 0 24 24"
+      fill="currentcolor"
+      {...props}
+    />
+  )
+)
+
+export default SVG
diff --git a/packages/components/src/Select.js b/packages/components/src/Select.tsx
similarity index 61%
rename from packages/components/src/Select.js
rename to packages/components/src/Select.tsx
index 8972b733f..a7b55056a 100644
--- a/packages/components/src/Select.js
+++ b/packages/components/src/Select.tsx
@@ -1,27 +1,38 @@
 import React from 'react'
-import Box from './Box'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
 import SVG from './SVG'
 import { getMargin, omitMargin } from './util'
 
+export interface SelectProps
+  extends Assign<React.ComponentProps<'select'>, BoxOwnProps> {}
+/**
+ * Select variants can be defined in `theme.forms`
+ * and the component uses the `theme.forms.select` variant by default.
+ * @see https://theme-ui.com/components/select/
+ */
+
 const DownArrow = props => (
   <SVG {...props}>
     <path d="M7 10l5 5 5-5z" />
   </SVG>
 )
 
-export const Select = React.forwardRef((props, ref) => (
+export const Select: ForwardRef<
+  HTMLSelectElement,
+  SelectProps
+> = React.forwardRef((props, ref) => (
   <Box
     {...getMargin(props)}
     sx={{
       display: 'flex',
     }}>
     <Box
-      ref={ref}
+      ref={ref} // TODO
       as="select"
       variant="select"
       {...omitMargin(props)}
       __themeKey="forms"
-      __css={{
+      css={{
         display: 'block',
         width: '100%',
         p: 2,
diff --git a/packages/components/src/Slider.js b/packages/components/src/Slider.js
deleted file mode 100644
index 16ba43bda..000000000
--- a/packages/components/src/Slider.js
+++ /dev/null
@@ -1,41 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-const thumb = {
-  appearance: 'none',
-  width: 16,
-  height: 16,
-  bg: 'currentcolor',
-  border: 0,
-  borderRadius: 9999,
-  variant: 'forms.slider.thumb',
-}
-
-export const Slider = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="input"
-    type="range"
-    variant="slider"
-    {...props}
-    __themeKey="forms"
-    __css={{
-      display: 'block',
-      width: '100%',
-      height: 4,
-      my: 2,
-      cursor: 'pointer',
-      appearance: 'none',
-      borderRadius: 9999,
-      color: 'inherit',
-      bg: 'gray',
-      ':focus': {
-        outline: 'none',
-        color: 'primary',
-      },
-      '&::-webkit-slider-thumb': thumb,
-      '&::-moz-range-thumb': thumb,
-      '&::-ms-thumb': thumb,
-    }}
-  />
-))
diff --git a/packages/components/src/Slider.tsx b/packages/components/src/Slider.tsx
new file mode 100644
index 000000000..d5904e83d
--- /dev/null
+++ b/packages/components/src/Slider.tsx
@@ -0,0 +1,54 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface SliderProps
+  extends Assign<React.ComponentProps<'input'>, BoxOwnProps> {}
+/**
+ * Range input element
+ *
+ * Slider variants can be defined in the `theme.forms` object.
+ * The Slider component uses `theme.forms.slider` as its default variant style.
+ * @see https://theme-ui.com/components/slider/
+ */
+
+const thumb = {
+  appearance: 'none',
+  width: 16,
+  height: 16,
+  bg: 'currentcolor',
+  border: 0,
+  borderRadius: 9999,
+  variant: 'forms.slider.thumb',
+}
+
+export const Slider: ForwardRef<
+  HTMLInputElement,
+  SliderProps
+> = React.forwardRef((props, ref) => (
+  <Box
+    ref={ref}
+    as="input"
+    type="range"
+    variant="slider"
+    {...props}
+    __themeKey="forms"
+    css={{
+      display: 'block',
+      width: '100%',
+      height: 4,
+      my: 2,
+      cursor: 'pointer',
+      appearance: 'none',
+      borderRadius: 9999,
+      color: 'inherit',
+      bg: 'gray',
+      ':focus': {
+        outline: 'none',
+        color: 'primary',
+      },
+      '&::-webkit-slider-thumb': thumb, //TODO
+      '&::-moz-range-thumb': thumb, //TODO
+      '&::-ms-thumb': thumb, //TODO
+    }}
+  />
+))
diff --git a/packages/components/src/Spinner.js b/packages/components/src/Spinner.tsx
similarity index 72%
rename from packages/components/src/Spinner.js
rename to packages/components/src/Spinner.tsx
index 641979567..35282cc72 100644
--- a/packages/components/src/Spinner.js
+++ b/packages/components/src/Spinner.tsx
@@ -1,6 +1,18 @@
 import React from 'react'
 import { keyframes } from '@emotion/core'
-import Box from './Box'
+import Box, { BoxOwnProps, ForwardRef, Omit } from './Box'
+
+export interface SpinnerProps
+  extends Omit<
+      React.SVGProps<SVGSVGElement>,
+      'opacity' | 'color' | 'css' | 'sx'
+    >,
+    BoxOwnProps {
+  size?: number | string
+  title?: string
+  duration?: number
+  strokeWidth?: number
+}
 
 const spin = keyframes({
   from: {
@@ -11,7 +23,10 @@ const spin = keyframes({
   },
 })
 
-export const Spinner = React.forwardRef(
+export const Spinner: ForwardRef<
+  SVGSVGElement,
+  SpinnerProps
+> = React.forwardRef(
   (
     {
       size = 48,
@@ -29,7 +44,7 @@ export const Spinner = React.forwardRef(
 
     return (
       <Box
-        ref={ref}
+        ref={ref} //TODO
         as="svg"
         viewBox="0 0 32 32"
         width={size}
@@ -39,7 +54,7 @@ export const Spinner = React.forwardRef(
         stroke="currentcolor"
         role="img"
         {...props}
-        __css={{
+        css={{
           color: 'primary',
           overflow: 'visible',
         }}>
@@ -47,12 +62,12 @@ export const Spinner = React.forwardRef(
         <circle cx={16} cy={16} r={r} opacity={1 / 8} />
         <Box
           as="circle"
-          cx={16}
+          cx={16} // TODO
           cy={16}
           r={r}
           strokeDasharray={C}
           strokeDashoffset={offset}
-          __css={{
+          css={{
             transformOrigin: '50% 50%',
             animationName: spin.toString(),
             animationTimingFunction: 'linear',
diff --git a/packages/components/src/Text.js b/packages/components/src/Text.js
deleted file mode 100644
index 6f7c09535..000000000
--- a/packages/components/src/Text.js
+++ /dev/null
@@ -1,6 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Text = React.forwardRef((props, ref) => (
-  <Box ref={ref} {...props} __themeKey="text" />
-))
diff --git a/packages/components/src/Text.tsx b/packages/components/src/Text.tsx
new file mode 100644
index 000000000..38f18995d
--- /dev/null
+++ b/packages/components/src/Text.tsx
@@ -0,0 +1,17 @@
+import React from 'react'
+import Box, { BoxProps, ForwardRef } from './Box'
+
+export type TextProps = BoxProps
+/**
+ * Primitive typographic component.
+ *
+ * Text style variants can be defined in the theme.text object.
+ * @see https://theme-ui.com/components/text
+ */
+
+export const Text: ForwardRef<
+  HTMLDivElement,
+  BoxProps
+> = React.forwardRef((props, ref) => (
+  <Box ref={ref} {...props} __themeKey="text" />
+))
diff --git a/packages/components/src/Textarea.js b/packages/components/src/Textarea.js
deleted file mode 100644
index 071492a27..000000000
--- a/packages/components/src/Textarea.js
+++ /dev/null
@@ -1,24 +0,0 @@
-import React from 'react'
-import Box from './Box'
-
-export const Textarea = React.forwardRef((props, ref) => (
-  <Box
-    ref={ref}
-    as="textarea"
-    variant="textarea"
-    {...props}
-    __themeKey="forms"
-    __css={{
-      display: 'block',
-      width: '100%',
-      p: 2,
-      appearance: 'none',
-      fontSize: 'inherit',
-      lineHeight: 'inherit',
-      border: '1px solid',
-      borderRadius: 4,
-      color: 'inherit',
-      bg: 'transparent',
-    }}
-  />
-))
diff --git a/packages/components/src/Textarea.tsx b/packages/components/src/Textarea.tsx
new file mode 100644
index 000000000..ccc11aa51
--- /dev/null
+++ b/packages/components/src/Textarea.tsx
@@ -0,0 +1,37 @@
+import React from 'react'
+import Box, { Assign, BoxOwnProps, ForwardRef } from './Box'
+
+export interface TextareaProps
+  extends Assign<React.ComponentProps<'textarea'>, BoxOwnProps> {}
+/**
+ * Form textarea component
+ *
+ * Textarea variants can be defined in `theme.forms`
+ * and the component uses the `theme.forms.textarea` variant by default.
+ * @see https://theme-ui.com/components/textarea/
+ */
+
+export const Textarea: ForwardRef<
+  HTMLTextAreaElement,
+  TextareaProps
+> = React.forwardRef((props, ref) => (
+  <Box
+    ref={ref} // TODO
+    as="textarea"
+    variant="textarea"
+    {...props}
+    __themeKey="forms"
+    css={{
+      display: 'block',
+      width: '100%',
+      p: 2,
+      appearance: 'none',
+      fontSize: 'inherit',
+      lineHeight: 'inherit',
+      border: '1px solid',
+      borderRadius: 4,
+      color: 'inherit',
+      bg: 'transparent',
+    }}
+  />
+))
diff --git a/packages/components/src/index.js b/packages/components/src/index.ts
similarity index 100%
rename from packages/components/src/index.js
rename to packages/components/src/index.ts
diff --git a/packages/components/src/util.js b/packages/components/src/util.ts
similarity index 100%
rename from packages/components/src/util.js
rename to packages/components/src/util.ts
diff --git a/packages/components/tsconfig.json b/packages/components/tsconfig.json
new file mode 100644
index 000000000..9bbf96fe1
--- /dev/null
+++ b/packages/components/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "jsx": "react"
+  },
+  "include": ["./src/**/*.ts", "./src/**/*.tsx"]
+}