diff --git a/docs/src/pages/docs/plugins/css.md b/docs/src/pages/docs/integrations/css.md
similarity index 100%
rename from docs/src/pages/docs/plugins/css.md
rename to docs/src/pages/docs/integrations/css.md
diff --git a/docs/src/pages/docs/guides/plugins.md b/docs/src/pages/docs/integrations/custom-plugins.md
similarity index 100%
rename from docs/src/pages/docs/guides/plugins.md
rename to docs/src/pages/docs/integrations/custom-plugins.md
diff --git a/docs/src/pages/docs/integrations/index.md b/docs/src/pages/docs/integrations/index.md
new file mode 100644
index 00000000..6e2b4fc0
--- /dev/null
+++ b/docs/src/pages/docs/integrations/index.md
@@ -0,0 +1,18 @@
+---
+title: Plugins
+layout: ../../../layouts/docs.astro
+---
+
+# Plugins
+
+Plugins let you **generate code** from your `tokens.json` / `tokens.yaml` manifest in your projects. Here are all current plugins available:
+
+| Plugin | Generates | Platform |
+| :------------------------------------------- | :--------------- | :------------------------- |
+| [@cobalt-ui/plugin-css](/docs/plugins/css) | CSS | Web |
+| [@cobalt-ui/plugin-js](/docs/plugins/js) | JS, TS, and JSON | Web and Native Apps (JSON) |
+| [@cobalt-ui/plugin-sass](/docs/plugins/sass) | Sass (and CSS) | Web |
+
+## Creating Plugins
+
+Cobalt was designed to be easy to create plugins within minutes. View the [developer guide to creating plugins](/docs/guides/plugins) to learn more.
diff --git a/docs/src/pages/docs/plugins/js.md b/docs/src/pages/docs/integrations/js.md
similarity index 85%
rename from docs/src/pages/docs/plugins/js.md
rename to docs/src/pages/docs/integrations/js.md
index 2bbf52e2..bcedb33e 100644
--- a/docs/src/pages/docs/plugins/js.md
+++ b/docs/src/pages/docs/integrations/js.md
@@ -5,7 +5,7 @@ layout: ../../../layouts/docs.astro
# @cobalt-ui/plugin-js
-Generate `.js`, and `.json` from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
+Generate JSON and JS (with TypeScript types) from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
**Features**
@@ -72,7 +72,13 @@ In addition, you’ll also find the following named exports:
### JSON
-This plugin’s JSON output has the same shape as the JS output. This format may be preferable if you’re preparing the tokens for an API or some other non-JS runtime.
+This plugin’s JSON output has the same shape as the JS output. This format is preferable if you’re preparing tokens for an API, or for native apps (iOS or Android).
+
+Note that even if your tokens started off as a `tokens.json` file, this output JSON differs in the following ways:
+
+- It flattens deeply-nested structures into a single depth (e.g. `color.core.blue.500` becomes `tokens["color.core.blue.500"]`)
+- It resolves all aliases (so you don’t have to)
+- It normalizes token values (especially helpful when the original spec is loose in what’s accepted)
## Options
diff --git a/docs/src/pages/docs/plugins/sass.md b/docs/src/pages/docs/integrations/sass.md
similarity index 98%
rename from docs/src/pages/docs/plugins/sass.md
rename to docs/src/pages/docs/integrations/sass.md
index 9741b9c0..9498ecc6 100644
--- a/docs/src/pages/docs/plugins/sass.md
+++ b/docs/src/pages/docs/integrations/sass.md
@@ -5,7 +5,7 @@ layout: ../../../layouts/docs.astro
# @cobalt-ui/plugin-sass
-Generate `.scss` and `.sass` output from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
+Generate Sass output (`.scss` or `.sass`) from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
**Features**
diff --git a/docs/src/pages/docs/guides/style-dictionary.md b/docs/src/pages/docs/integrations/style-dictionary.md
similarity index 100%
rename from docs/src/pages/docs/guides/style-dictionary.md
rename to docs/src/pages/docs/integrations/style-dictionary.md
diff --git a/docs/src/pages/docs/guides/tokens-studio.md b/docs/src/pages/docs/integrations/tokens-studio.md
similarity index 100%
rename from docs/src/pages/docs/guides/tokens-studio.md
rename to docs/src/pages/docs/integrations/tokens-studio.md
diff --git a/docs/src/pages/docs/plugins/index.md b/docs/src/pages/docs/plugins/index.md
deleted file mode 100644
index 04e7fd20..00000000
--- a/docs/src/pages/docs/plugins/index.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-title: Plugins
-layout: ../../../layouts/docs.astro
----
-
-# Plugins
-
-Plugins let you **generate code** from `tokens.json`. Here are all current plugins available:
-
-- [@cobalt-ui/plugin-css](/docs/plugins/css): Generate `.css`
-- [@cobalt-ui/plugin-js](/docs/plugins/js): Generate `.js`, `.ts`, and `.json`
-- [@cobalt-ui/plugin-sass](/docs/plugins/sass): Generate `.scss` or `.sass`
-
-## Creating Plugins
-
-Cobalt was designed to be easy to create plugins within minutes. View the [developer guide to creating plugins](/docs/guides/plugins) to learn more.
diff --git a/docs/src/pages/docs/tokens/index.astro b/docs/src/pages/docs/tokens/index.astro
index 087041d7..bcefbfa6 100644
--- a/docs/src/pages/docs/tokens/index.astro
+++ b/docs/src/pages/docs/tokens/index.astro
@@ -26,7 +26,9 @@ const tokenDef = {
Tokens
- Tokens are defined via the the W3C Design Tokens format schema (Apr 2023). Cobalt supports 100% of the spec, but with the following changes:
+ Tokens are defined via the the W3C Design Tokens format schema (Apr 2023). You’ll save your tokens in a tokens.yaml or tokens.json file in the root of your project. Cobalt supports 100% of the spec, but with the following changes:
diff --git a/packages/plugin-css/README.md b/packages/plugin-css/README.md
index 67b785d2..d08393b2 100644
--- a/packages/plugin-css/README.md
+++ b/packages/plugin-css/README.md
@@ -1,6 +1,6 @@
# @cobalt-ui/plugin-css
-Generate `.css` from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
+Generate CSS from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
**Features**
diff --git a/packages/plugin-js/README.md b/packages/plugin-js/README.md
index b5e04736..76ab5b7e 100644
--- a/packages/plugin-js/README.md
+++ b/packages/plugin-js/README.md
@@ -1,6 +1,6 @@
# @cobalt-ui/plugin-js
-Generate `.js`, and `.json` from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
+Generate JSON and JS (with TypeScript types) from your design tokens using [Cobalt](https://cobalt-ui.pages.dev).
**Features**
@@ -67,7 +67,13 @@ In addition, you’ll also find the following named exports:
### JSON
-This plugin’s JSON output has the same shape as the JS output. This format may be preferable if you’re preparing the tokens for an API or some other non-JS runtime.
+This plugin’s JSON output has the same shape as the JS output. This format is preferable if you’re preparing tokens for an API, or for native apps (iOS or Android).
+
+Note that even if your tokens started off as a `tokens.json` file, this output JSON differs in the following ways:
+
+- It flattens deeply-nested structures into a single depth (e.g. `color.core.blue.500` becomes `tokens["color.core.blue.500"]`)
+- It resolves all aliases (so you don’t have to)
+- It normalizes token values (especially helpful when the original spec is loose in what’s accepted)
## Options