Notes: Add more notes on component API and how theming works

Author: flexdinesh

README.md

@@ -1,18 +1,43 @@
 # Design System Boilerplate
 
-Boilerplate monorepo setup with the design system as an internal package and two example apps using the monorepo.
+Boilerplate monorepo setup with the design system as an internal package and two example apps built with the design system.
 
 ## Design System
 
-A strongly typed opinionated design system based on system ui theme specification and styled system component API.
+A strongly typed opinionated design system based on [System UI Theme Specification](https://system-ui.com/theme/) and [Styled System](https://styled-system.com/) component API for rapid UI development.
 
 ### Principles
 
-- Predefine all your themes. i.e no runtime theme creation. This allows us to statically define themes using css variables and create strongly typed themes. Strong types help with full autocomplete support in component APIs.
-- Token groups are identified and based on theme ui specification. Eg. `colors`, `space`, `fontSizes`, etc.
+The design system follows a set of constraints that allows us to statically compile theme definitions and build flexibile APIs.
+
+- Predefine all your themes. i.e no runtime theme creation. This allows us to statically define themes using css variables and create strongly typed themes. Strong types help with full autocomplete support in component APIs. Eg. 
+  - `Box` component `backgroundColor` prop autocompletes with available color tokens - `primary`, `secondary`, etc.
+  - `Box` component `padding` prop autocompletes with available spacing tokens - `small`, `large`, etc.
+
+- Token groups are identified and based on [System UI Theme Specification](https://system-ui.com/theme/). Eg. `colors`, `space`, `fontSizes`, etc.
+
 - Keep your token groups flat. Don't nest your tokens within token groups. Eg. `colors.primary` is allowed. `colors.primary.success` is not allowed.
+
+- All themes should have the same set of tokens. Eg. dark theme cannot have a token that's not available in light theme.
+
 - Theming is driven using CSS custom properties (variables). This allows all themes to have the same tokens values which makes it easy to switch or server render themes. Eg. `token.colors.primary` has the same css variable across themes and makes it easy to statically define styles instead of defining the styles during runtime based on theme. `background: ${tokens.colors.primary}` instead of `background: ${(prop) => prop.theme.colors.primary}`.
 
+### How does theming work?
+
+- Theme definitions are automatically converted to css variables using the `createTheme` utility.
+- The generated css variables are theme-name scoped in `ThemeProvider`.
+
+```
+body[data-theme="light"] {
+  --theme-colors-primary: blue;
+  --theme-colors-secondary: lightblue;
+}
+body[data-theme="dark"] {
+  --theme-colors-primary: green;
+  --theme-colors-secondary: lightgreen;
+}
+```
+
 ### Stack
 
 - Components are styled using emotion
@@ -43,19 +68,6 @@ const Example = () => {
 };
 ```
 
-How does that work? css variables names are theme name scoped.
-
-```
-body[data-theme="light"] {
-  --theme-colors-primary: blue;
-  --theme-colors-secondary: lightblue;
-}
-body[data-theme="dark"] {
-  --theme-colors-primary: green;
-  --theme-colors-secondary: lightgreen;
-}
-```
-
 #### Getting current theme name
 
 Getting current theme is as simple as querying the DOM attribute. You don't need Context or fancy hooks to provide you the value. Although you do have a hook if you need — `useTheme`.

packages/design-system/src/core/theme.ts

@@ -7,7 +7,7 @@ import {
   fontFamily,
   lineHeights,
 } from '../tokens/typography';
-import { createTheme } from '../util/theme';
+import { createTheme } from '../util/create-theme';
 
 /* light mode - default */
 const light = createTheme({

packages/design-system/src/util/__tests__/theme.test.ts renamed to packages/design-system/src/util/__tests__/create-theme.test.ts

@@ -1,4 +1,4 @@
-import { createTheme } from '../theme';
+import { createTheme } from '../create-theme';
 
 describe('util/theme', () => {
   it('createTheme', () => {