From 6ceb6c9850d3e43af1d4a31c2fab86c7675fd4ab Mon Sep 17 00:00:00 2001
From: Peterlits Zo <peterlitszo@gmail.com>
Date: Tue, 8 Feb 2022 12:14:08 +0800
Subject: [PATCH] docs/style: Update document for sx-prop. (#2118)

It is hard to find that how sx prop works and how to let sx-prop works for
user-defind components.

We update the document to make it easy to get.
---
 packages/docs/src/pages/sx-prop.mdx | 39 +++++++++++++++++++++++++++++
 packages/parse-props/src/index.ts   |  2 ++
 2 files changed, 41 insertions(+)

diff --git a/packages/docs/src/pages/sx-prop.mdx b/packages/docs/src/pages/sx-prop.mdx
index 7e5250cbc..f7504f3d6 100644
--- a/packages/docs/src/pages/sx-prop.mdx
+++ b/packages/docs/src/pages/sx-prop.mdx
@@ -407,6 +407,45 @@ import { Box } from 'theme-ui'
 </Box>
 ```
 
+## Work with `className`
+
+`theme-ui` has its own function to build JSX with sx prop. How does it works?
+`theme-ui` will use `praseProps` to deal with all props. it will firstly deal
+with `sx` and/or `css` props, to get the **new** `css` prop with original props
+except the **old** `sx` and/or **old** `css` props. Then it will let
+`emtion`'s `jsx` function to finish the other works.
+
+You can click [emotion css-prop][] to get more infomation.
+
+[emotion]: https://emotion.sh/docs/css-prop#style-precedence
+
+So, emtion will deal with the **new** `css` prop and `className`(for example,
+`'bar'`) prop. Then make **new** style class with new name(for example,
+`'foo'`), and replace old `className` with new `className`.
+
+``` jsx
+const Comp = (props) => {
+  // - theme-ui will turn `sx` prop into `css` prop.
+  // - emtion will mixin `css` prop and `className` prop to get new `className`
+  // prop
+  <div className={props.className} sx={{width: 1}}/>
+}
+
+<Comp />
+// => <div class="bar" />
+// => .bar {
+//   width: 1px;
+// }
+
+// sx prop with turn into `className` prop.
+<Comp sx={{height: 1}} />
+// => <div class="foo" />
+// => .foo {
+//   width: 1px;
+//   height: 1px;
+// }
+```
+
 ## Object Styles
 
 If you're new to using JavaScript object notation for authoring styles, see the
diff --git a/packages/parse-props/src/index.ts b/packages/parse-props/src/index.ts
index fa03902c8..b373c0022 100644
--- a/packages/parse-props/src/index.ts
+++ b/packages/parse-props/src/index.ts
@@ -9,6 +9,8 @@ const getCSS = (props: any) => (theme: any) => {
 
 const parseProps = (props: any) => {
   if (!props || (!props.sx && !props.css)) return props
+
+  // Now props should be a object with `sx` and/or with `css` prop.
   const next: typeof props & { css: Interpolation<any> } = {}
   for (let key in props) {
     if (key === 'sx') continue