Rename plugins to integrations

docs/scripts/update-readmes.js

@@ -9,9 +9,9 @@ import {URL} from 'node:url';
 const FRONTMATTER_RE = /^---/gm;
 
 const updates = {
-  '../../packages/plugin-css/README.md': '../src/pages/docs/plugins/css.md',
-  '../../packages/plugin-sass/README.md': '../src/pages/docs/plugins/sass.md',
-  '../../packages/plugin-js/README.md': '../src/pages/docs/plugins/js.md',
+  '../../packages/plugin-css/README.md': '../src/pages/docs/integrations/css.md',
+  '../../packages/plugin-sass/README.md': '../src/pages/docs/integrations/sass.md',
+  '../../packages/plugin-js/README.md': '../src/pages/docs/integrations/js.md',
 };
 
 const urlRewrites = {

docs/src/components/DocsNav.astro

@@ -17,11 +17,14 @@ function showSubPage(url) {
   @use '../../tokens' as *;
 
   .nav {
+    box-shadow: inset 1px 0 0 token('color.ui.contrast.10');
     border-bottom: 1px solid rgba(0, 0, 0, 0.2);
     display: flex;
     flex-direction: column;
     font-size: token('font.size.04');
+    height: max-content;
     margin-bottom: token('space.md');
+    margin-left: auto;
     max-height: calc(100vh - #{token('space.layout.sm')});
     min-width: token('space.layout.2xl');
     padding-bottom: token('space.md');
@@ -37,14 +40,22 @@ function showSubPage(url) {
 
   .a {
     align-items: center;
-    color: token('color.ui.contrast.100');
+    border-left: 1px solid token('color.ui.contrast.10');
+    color: token('color.ui.contrast.70');
     display: flex;
-    min-height: token('space.lg');
-    padding-left: token('space.lg');
+    min-height: token('space.xl');
+    padding-left: token('space.sm');
     position: relative;
     text-decoration: none;
 
+    &:hover {
+      border-left-color: token('color.ui.contrast.50');
+      color: token('color.ui.contrast.80');
+    }
+
     &[aria-current='page'] {
+      background-color: color-mix(in oklab, #{token('color.ui.action')}, transparent 90%);
+      border-color: token('color.ui.action');
       color: token('color.ui.action');
       font-weight: 550;
     }
@@ -56,7 +67,13 @@ function showSubPage(url) {
     }
 
     &--subpage {
+      border-left: none;
       margin-left: token('space.md');
+      min-height: token('space.lg');
+
+      &[aria-current='page'] {
+        background: none;
+      }
 
       &::before {
         left: -0.875rem;

docs/src/docs-manifest.json

@@ -20,17 +20,17 @@
     {"title": "Custom",                   "pathname": "/docs/tokens/#custom"},
     {"title": "Aliasing",                 "pathname": "/docs/tokens/#aliasing"},
     {"title": "Modes",                    "pathname": "/docs/tokens/#modes"},
+    {"title": "Integrations",             "pathname": "/docs/integrations"},
+    {"title": "CSS",                      "pathname": "/docs/integrations/css"},
+    {"title": "Sass",                     "pathname": "/docs/integrations/sass"},
+    {"title": "JSON/JS/TS",               "pathname": "/docs/integrations/js"},
+    {"title": "Style Dictionary",         "pathname": "/docs/integrations/style-dictionary"},
+    {"title": "Tokens Studio",            "pathname": "/docs/integrations/tokens-studio"},
+    {"title": "Custom Plugins",           "pathname": "/docs/integrations/custom-plugins"},
     {"title": "Guides",                   "pathname": "/docs/guides"},
     {"title": "What are Design Tokens?",  "pathname": "/docs/guides/design-tokens"},
     {"title": "Best Practices",           "pathname": "/docs/guides/best-practices"},
     {"title": "Modes",                    "pathname": "/docs/guides/modes"},
-    {"title": "Style Dictionary",         "pathname": "/docs/guides/style-dictionary"},
-    {"title": "Tokens Studio",            "pathname": "/docs/guides/tokens-studio"},
-    {"title": "Custom Plugins",           "pathname": "/docs/guides/plugins"},
-    {"title": "Plugins",                  "pathname": "/docs/plugins"},
-    {"title": "CSS",                      "pathname": "/docs/plugins/css"},
-    {"title": "Sass",                     "pathname": "/docs/plugins/sass"},
-    {"title": "JS/JSON/TS",               "pathname": "/docs/plugins/js"},
     {"title": "Reference",                "pathname": "/docs/reference"},
     {"title": "CLI",                      "pathname": "/docs/reference/cli"},
     {"title": "Config API",               "pathname": "/docs/reference/config"},

docs/src/layouts/docs.astro

@@ -8,7 +8,7 @@ import SkipToMain from '../components/SkipToMain.astro';
 const {content = {}} = Astro.props;
 ---
 
-<!DOCTYPE html>
+<!doctype html>
 <html>
   <head>
     <Head title={content.title ? `${content.title} / Cobalt design tokens}` : 'Docs / Cobalt design tokens'} />
@@ -21,17 +21,24 @@ const {content = {}} = Astro.props;
 
         @media (min-width: 600px) {
           flex-direction: row;
+          gap: 2.5rem;
           padding-right: token('space.layout.2xl');
         }
       }
+
+      .content {
+        margin-right: auto;
+        max-width: 100%;
+        width: 65rem;
+      }
     </style>
   </head>
   <body>
     <SkipToMain />
     <Nav />
     <div class="docs">
       <DocsNav />
-      <main class="wrapper content md-content" id="#main">
+      <main class="content md-content" id="#main">
         <slot />
       </main>
     </div>

docs/src/pages/docs/getting-started/generation.md

@@ -71,8 +71,8 @@ That will generate a new `/tokens/` folder along with one output per plugin:
 
 ## Next steps
 
-Learn more about the existing plugins and [view documentation](docs/plugins)
+Learn more about the existing plugins and [view documentation](/docs/integrations)
 
-- **CSS**: [@cobalt-ui/plugin-css](/docs/plugins/css)
-- **JS/TS/JSON**: [@cobalt-ui/plugin-js](/docs/plugins/js)
-- **Sass**: [@cobalt-ui/plugin-sass](/docs/plugins/sass)
+- **CSS**: [@cobalt-ui/plugin-css](/docs/integrations/css)
+- **JS/TS/JSON**: [@cobalt-ui/plugin-js](/docs/integrations/js)
+- **Sass**: [@cobalt-ui/plugin-sass](/docs/integrations/sass)

docs/src/pages/docs/getting-started/index.astro

@@ -17,9 +17,10 @@ const title = 'Getting Started';
   />
 
   <p>
-    Cobalt turns your <a href="/docs/guides/design-tokens">design tokens</a> into code using a CLI or Node.js. Cobalt is configurable and pluggable, and can generate <a href="/plugins/js">JavaScript</a>, <a href="/plugins/js">TypeScript</a
-    >, <a href="/plugins/js">JSON</a>, <a href="/plugins/css">CSS</a>, and <a href="/plugins/js">Sass</a> via the official <a href="/docs/plugins">plugins</a>. Or you can generate anything else by <a href="/docs/guides/plugins"
-      >creating your own plugin</a
+    Cobalt turns your <a href="/docs/guides/design-tokens">design tokens</a> into code using a CLI or Node.js. Cobalt is configurable and pluggable, and can generate <a href="/integrations/js">JavaScript</a>, <a href="/integrations/js"
+      >TypeScript</a
+    >, <a href="/integrations/js">JSON</a>, <a href="/integrations/css">CSS</a>, and <a href="/integrations/js">Sass</a> via the official <a href="/docs/integrations">plugins</a>. Or you can generate anything else by <a
+      href="/docs/guides/plugins">creating your own plugin</a
     >.
   </p>
 
@@ -77,7 +78,10 @@ const title = 'Getting Started';
 
     <blockquote><p>ℹ️ For this step, you’ll need <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">Node.js</a> installed (v20 is recommended).</p></blockquote>
 
-    <p>For this example, we’ll install the <a href="/docs/plugins/js">JS</a>, <a href="/docs/plugins/sass">Sass</a>, and <a href="/docs/plugins/css">CSS</a> plugins, but skip any you don’t need (you can always install them later).</p>
+    <p>
+      For this example, we’ll install the <a href="/docs/integrations/js">JS</a>, <a href="/docs/integrations/sass">Sass</a>, and <a href="/docs/integrations/css">CSS</a> plugins, but skip any you don’t need (you can always install them
+      later).
+    </p>
 
     <p>Run the following in a terminal, in the code project folder you’d like to generate code to:</p>
 
@@ -109,7 +113,7 @@ export default {
 };`}
     />
 
-    <p>To learn more about the config file, see <a href="/docs/reference/config">config options</a>. To learn about plugin options, see <a href="/docs/plugins">plugins</a>.</p>
+    <p>To learn more about the config file, see <a href="/docs/reference/config">config options</a>. To learn about plugins and integrations, see <a href="/docs/integrations">Integrations</a>.</p>
 
     <p>Lastly, run the following command to generate all code from your tokens:</p>
 
@@ -181,7 +185,7 @@ jobs:
       <li><a href="/docs/tokens">Learn about tokens</a></li>
       <li><a href="/docs/guides/tokens-studio">Sync with Figma using Tokens Studio</a></li>
       <li><a href="/docs/reference/config">Learn how to configure Cobalt</a></li>
-      <li><a href="/docs/plugins">Add plugins</a></li>
+      <li><a href="/docs/integrations">Add integrations</a></li>
     </ul>
   </ol>
 

docs/src/pages/docs/guides/modes.astro

@@ -21,17 +21,17 @@ const title = 'Modes';
   </figure>
 
   <p>
-    In this screenshot of GitHub’s dashboard you’ll find 5 color themes: <em>Light default</em>, <em>Light high contrast</em>, <em>Dark default</em>, <em>Dark high contrast</em>, and <em>Dark dimmed</em> (shown above). How might that be represented
-    in tokens?
+    In this screenshot of GitHub’s dashboard you’ll find 5 color themes: <em>Light default</em>, <em>Light high contrast</em>, <em>Dark default</em>, <em>Dark high contrast</em>, and <em>Dark dimmed</em> (shown above). How might that be
+    represented in tokens?
   </p>
 
   <p><em>Note: since this guide was written, GitHub has since added additional color modes. But since that doesn’t change the concept, we’ll stick with the older (simpler) example for the purposes of illustration.</em></p>
 
   <h3>Without Modes</h3>
 
   <p>
-    Consider the <code>red</code> and <code>white</code> colors in the system. Whereas <code>red</code> has a different value for each mode, <code>white</code> is an absolute value that doesn’t change. A (wrong) first attempt may look something
-    like:
+    Consider the <code>red</code> and <code>white</code> colors in the system. Whereas <code>red</code> has a different value for each mode, <code>white</code> is an absolute value that doesn’t change. A (wrong) first attempt may look
+    something like:
   </p>
 
   <JSONYaml
@@ -93,13 +93,13 @@ const title = 'Modes';
   </p>
 
   <p>
-    This simplifies your application code, too, as, you can simply refer to <code>red</code> or <code>white</code> and the mode can be inferred based on the global context (see the <a href="#examples-in-code">Examples in code</a> section below
-    to see the “how”).
+    This simplifies your application code, too, as, you can simply refer to <code>red</code> or <code>white</code> and the mode can be inferred based on the global context (see the <a href="#examples-in-code">Examples in code</a> section
+    below to see the “how”).
   </p>
 
   <h3>With @cobalt/plugin-css</h3>
 
-  <p>If using <a href="/docs/plugins/css">@cobalt/plugin-css</a>, you could generate CSS to handle these modes. That would look something like:</p>
+  <p>If using <a href="/docs/integrations/css">@cobalt/plugin-css</a>, you could generate CSS to handle these modes. That would look something like:</p>
 
   <Code
     lang="js"
@@ -125,8 +125,8 @@ export default {
   />
 
   <p>
-    Then in your CSS, the correct color mode would apply automatically in most instances, but you could also set <code>&lt;body data-color-mode="[mode]"&gt;</code> to override it. Also note there aren’t browser-global colorblind preferences,
-    so for the colorblind color schemes, they’d have to be set manually.
+    Then in your CSS, the correct color mode would apply automatically in most instances, but you could also set <code>&lt;body data-color-mode="[mode]"&gt;</code> to override it. Also note there aren’t browser-global colorblind
+    preferences, so for the colorblind color schemes, they’d have to be set manually.
   </p>
 
   <h2>Example: typographic modes</h2>
@@ -157,8 +157,8 @@ export default {
   />
 
   <p>
-    Referring to a font size as <code>typography.size.title1-Medium</code> or <code>typography.size.title2-Medium</code> is a bad idea, because then every level of your application must be aware of the user’s current preference settings. And
-    if values ever change, now your entire application must be updated everywhere.
+    Referring to a font size as <code>typography.size.title1-Medium</code> or <code>typography.size.title2-Medium</code> is a bad idea, because then every level of your application must be aware of the user’s current preference settings.
+    And if values ever change, now your entire application must be updated everywhere.
   </p>
 
   <h3>With Modes</h3>
@@ -230,9 +230,9 @@ export default {
   <p>The examples above were generic concepts that applied to all languages. To see how to use modes in specific languages, see the following plugin docs:</p>
 
   <ul>
-    <li><a href="/docs/plugins/css#mode-selectors">@cobalt-ui/plugin-css</a></li>
-    <li><a href="/docs/plugins/js#usage">@cobalt-ui/plugin-js</a></li>
-    <li><a href="/docs/plugins/sass#modes">@cobalt-ui/plugin-sass</a></li>
+    <li><a href="/docs/integrations/css#mode-selectors">@cobalt-ui/plugin-css</a></li>
+    <li><a href="/docs/integrations/js#usage">@cobalt-ui/plugin-js</a></li>
+    <li><a href="/docs/integrations/sass#modes">@cobalt-ui/plugin-sass</a></li>
   </ul>
 
   <h2>Advanced</h2>

docs/src/pages/docs/plugins/css.md → docs/src/pages/docs/integrations/css.md

@@ -321,7 +321,7 @@ export default {
 
 ### Usage with @cobalt-ui/plugin-sass
 
-If you’re using Sass in your project, you can load this plugin through [@cobalt-ui/plugin-sass](https://cobalt-ui.pages.dev/docs/plugins/sass/), which lets you use CSS vars while letting Sass typecheck everything and making sure your stylesheet references everything correctly.
+If you’re using Sass in your project, you can load this plugin through [@cobalt-ui/plugin-sass](https://cobalt-ui.pages.dev/docs/integrations/sass/), which lets you use CSS vars while letting Sass typecheck everything and making sure your stylesheet references everything correctly.
 
 To use this, replace this plugin with @cobalt-ui/plugin-sass in `tokens.config.mjs` and pass all options into `pluginCSS: {}`:
 
@@ -342,4 +342,4 @@ To use this, replace this plugin with @cobalt-ui/plugin-sass in `tokens.config.m
   };
 ```
 
-This changes `token('color.blue')` to return CSS vars rather than the original values. To learn more, [read the docs](https://cobalt-ui.pages.dev/docs/plugins/sass/).
+This changes `token('color.blue')` to return CSS vars rather than the original values. To learn more, [read the docs](https://cobalt-ui.pages.dev/docs/integrations/sass/).

docs/src/pages/docs/guides/plugins.md → docs/src/pages/docs/integrations/custom-plugins.md

@@ -5,7 +5,7 @@ layout: ../../../layouts/docs.astro
 
 # Create your own plugins
 
-Creating your own Cobalt plugins is easy if you’re comfortable with JavaScript. This guide is for creating a custom plugin yourself; if you’re looking for instructions on how to use existing plugins, [see the plugins directory](/docs/plugins).
+Creating your own Cobalt plugins is easy if you’re comfortable with JavaScript. This guide is for creating a custom plugin yourself; if you’re looking for instructions on how to use existing plugins, [see the plugins directory](/docs/integrations).
 
 ## Why use Cobalt?
 

docs/src/pages/docs/integrations/index.md

@@ -0,0 +1,29 @@
+---
+title: Integrations
+layout: ../../../layouts/docs.astro
+---
+
+# Integrations
+
+Plugins let you **generate code** from your `tokens.json` / `tokens.yaml` manifest in your projects.
+
+## Plugins
+
+Each Cobalt plugin lets you generate code for your desired platform. You can use one plugin, or all of them!
+
+| Plugin                                            | Generates        | Platform                       |
+| :------------------------------------------------ | :--------------- | :----------------------------- |
+| [@cobalt-ui/plugin-css](/docs/integrations/css)   | CSS              | Web                            |
+| [@cobalt-ui/plugin-js](/docs/integrations/js)     | JS, TS, and JSON | Web and Native Apps (via JSON) |
+| [@cobalt-ui/plugin-sass](/docs/integrations/sass) | Sass (and CSS)   | Web                            |
+
+## External Tools
+
+Cobalt also supports the following external formats/tools, which can also be used in conjunction with any/all plugins.
+
+- [Style Dictionary](/docs/integrations/style-dictionary)
+- [Tokens Studio for Figma](/docs/integrations/tokens-studio)
+
+## Custom 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.

docs/src/pages/docs/plugins/js.md → 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
 

docs/src/pages/docs/plugins/sass.md → docs/src/pages/docs/integrations/sass.md

@@ -5,11 +5,11 @@ 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**
 
-- ✅ Supports all features of the [CSS plugin](https://cobalt-ui.pages.dev/plugins/css)
+- ✅ Supports all features of the [CSS plugin](https://cobalt-ui.pages.dev/integrations/css)
 - ✅ Strong typechecking with Sass to never have broken styles
 
 ## Setup