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/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.

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,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**
 

docs/src/pages/docs/tokens/index.astro

@@ -26,7 +26,9 @@ const tokenDef = {
   <h1>Tokens</h1>
 
   <p>
-    Tokens are defined via the <a href="https://design-tokens.github.io/community-group/format/" target="_blank">the W3C Design Tokens format</a> schema (Apr 2023). Cobalt supports 100% of the spec, but with the following changes:
+    Tokens are defined via the <a href="https://design-tokens.github.io/community-group/format/" target="_blank">the W3C Design Tokens format</a> schema (Apr 2023). You’ll save your tokens in a <code>tokens.yaml</code> or <code
+      >tokens.json</code
+    > file in the root of your project. Cobalt supports 100% of the spec, but with the following changes:
   </p>
 
   <ul>

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**
 

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