diff --git a/packages/webawesome/docs/docs/theming/index.md b/packages/webawesome/docs/docs/theming/index.md
new file mode 100644
index 000000000..89b142074
--- /dev/null
+++ b/packages/webawesome/docs/docs/theming/index.md
@@ -0,0 +1,141 @@
+---
+title: Theming
+description: TODO
+layout: page-outline
+---
+
+Web Awesome themes apply a cohesive look and feel across the entire library. A theme is a collection of predefined CSS custom properties that cover a range of styles from colors to transitions. We call these CSS custom properties design tokens.
+
+There are 3 pre-made Free themes to choose from and an additional 8 pre-made themes in Web Awesome Pro. You can also build your own manually with CSS or with our Pro Theme Builder.
+
+## Key Concepts
+
+### Color Palettes
+`.wa-palette-{name}`
+
+Color palettes give you a full spectrum of colors to use in your project. A color palette defines 10 hues — red, orange, yellow, green, cyan, blue, indigo, purple, pink, and gray — each with 11 tints.
+
+There are 3 Free color palettes to choose from and an additional 6 color palettes in Web Awesome Pro.
+
+While the tints have consistent lightness values across palettes, each palette has unique hue shifts and chroma to give it character so you can find just the right vibe to your project.
+
+TODO: Add color palette preview
+
+Your color palette is determined by `class="wa-palette-{name}"` on the `` element. If no class is specified, the default color palette for your chosen theme is used.
+
+### Variants
+`.wa-{variant}-{hue}`
+
+Variants convey a specific meaning through color. There are five variants:
+- **Brand** for product recognition
+- **Neutral** for generic and ordinary content
+- **Success** for validity or confirmation
+- **Warning** for caution or uncertainty
+- **Danger** for errors or risk
+
+Brand and neutral are used by nearly every element, component, and pattern across the library. Success, warning, and danger are used selectively by components that could benefit from semantic reinforcement, such as buttons and callouts.
+
+TODO: Add variant scale preview
+
+Any hue from a color palette can be assigned to a variant. Each variant is determined by `class="wa-{variant}-{hue}"` on the `` element. If no class is specified:
+- **Brand** defaults to **blue**
+- **Neutral** defaults to **gray**
+- **Success** defaults to **green**
+- **Warning** defaults to **yellow**
+- **Danger** defaults to **red**
+
+### Themes
+`.wa-theme-{name}`
+
+Themes assign specific tints from your chosen variant colors — along with qualities like fonts, borders, space, and shadows — to design tokens that style elements and components. Themes may also contain custom CSS overrides to change the default look of components.
+
+TODO: Add theme preview
+
+Your color palette is determined by `class="wa-theme-{name}"` on the `` element. If no class is specified, the default theme is used.
+
+### Light and Dark Modes
+`.wa-light` | `.wa-dark` | `.wa-invert`
+
+Every theme is designed to adapt to light and dark mode. Light mode styles are applied by default, but you can apply a specific color scheme to an entire page or just a section with `class="wa-light"` or `class="wa-dark"`.
+
+```html {.example}
+
+
+
+
+
Light
+
+
+
+
+
+ Whipped cream
+ Hershey's Kisses
+ Jelly beans
+
+
+
+ Make Waffles
+
+
+
+
+
+
+
Dark
+
+
+
+
+
+ Whipped cream
+ Hershey's Kisses
+ Jelly beans
+
+
+
+ Make Waffles
+
+
+
+
+
This card will always use the opposite of the color scheme applied to the docs.
+
+
+
+
Invert
+
+
+
+
+ Hawkins Lab
+ Starcourt Mall
+ The Upside Down
+
+
+
+
+
+ Go!
+
+
+
+```
+
+#### Detecting Color Scheme Preference
+
+TODO
+
+## Bringing it Together
+
+TODO
+
+## Creating Your Own
+
+TODO
\ No newline at end of file