Clean up Getting Started docs (#89)

terrazzoapp · Aug 27, 2023 · 29a05e1 · 29a05e1
1 parent 54b451c
commit 29a05e1
Show file tree

Hide file tree

Showing 6 changed files with 172 additions and 116 deletions.
diff --git a/docs/src/docs-manifest.json b/docs/src/docs-manifest.json
@@ -4,7 +4,7 @@
     {"title": "Tokens",          "pathname": "/docs/tokens"},
     {"title": "Color",           "pathname": "/docs/tokens/#color"},
     {"title": "Dimension",       "pathname": "/docs/tokens/#dimension"},
-    {"title": "Font Family",     "pathname": "/docs/tokens/#font"},
+    {"title": "Font Family",     "pathname": "/docs/tokens/#font-family"},
     {"title": "Font Weight",     "pathname": "/docs/tokens/#font-weight"},
     {"title": "Duration",        "pathname": "/docs/tokens/#duration"},
     {"title": "Cubic Bézier",    "pathname": "/docs/tokens/#cubic-bezier"},
@@ -21,10 +21,11 @@
     {"title": "Aliasing",        "pathname": "/docs/tokens/#aliasing"},
     {"title": "Modes",           "pathname": "/docs/tokens/#modes"},
     {"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": "Tokens Studio",   "pathname": "/docs/guides/tokens-studio"},
-    {"title": "Create Plugins",  "pathname": "/docs/guides/plugins"},
+    {"title": "Custom Plugins",  "pathname": "/docs/guides/plugins"},
     {"title": "Plugins",         "pathname": "/docs/plugins"},
     {"title": "CSS",             "pathname": "/docs/plugins/css"},
     {"title": "Sass",            "pathname": "/docs/plugins/sass"},

diff --git a/docs/src/pages/docs/getting-started/index.astro b/docs/src/pages/docs/getting-started/index.astro
@@ -1,6 +1,7 @@
 ---
 import {Code} from 'astro/components';
 import JSONYaml from '../../../components/JSONYaml.astro';
+import Token from '../../../components/Token.astro';
 import Layout from '../../../layouts/docs.astro';
 
 const title = 'Getting Started';
@@ -9,54 +10,24 @@ const title = 'Getting Started';
 <Layout content={{title}}>
   <h1>{title}</h1>
 
-  <p>Cobalt turns your <a href="/docs/tokens">W3C design tokens</a> into code using a CLI or Node.js. Cobalt is configurable and pluggable, and can generate the following <a href="/docs/plugins">via plugins</a>:</p>
-  <ul>
-    <li><a href="/docs/plugins/css">CSS</a></li>
-    <li><a href="/docs/plugins/sass">Sass</a></li>
-    <li><a href="/docs/plugins/js">JS/TS/JSON</a></li>
-    <li>You can also make a <a href="/docs/guides/plugins">custom plugin</a> to generate more!</li>
-  </ul>
-  <h2>Introduction</h2>
-  <p>
-    Cobalt is tooling for the <a href="https://designtokens.org" target="_blank" rel="noopener noreferrer">W3C Community Group Design Tokens format</a> which is <strong>currently under development</strong>. You may be familiar with <a
-      href="https://amzn.github.io/style-dictionary"
-      target="_blank"
-      rel="noopener noreferrer">Style Dictionary</a
-    > which is an alternative design token system, but differs as it predates the new standard (that Cobalt uses). The new design tokens standard is the <a
-      href="https://github.com/design-tokens/community-group#companies-and-open-source-projects-represented-on-the-dtcg"
-      target="_blank"
-      rel="noopener noreferrer">largest collaborative format</a
-    > to-date, involving input from Figma, Adobe, Salesforce, Google, and more to push the format forward.
-  </p>
+  <Code lang="shell" code={`$ npx co build
+  ✔  180 tokens built 100ms`} />
 
-  <p>Figma has a great video explaining what an exciting leap forward this is:</p>
+  <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>.</p>
 
-  <div class="yt-embed">
-    <iframe
-      width="560"
-      height="315"
-      src="https://www.youtube-nocookie.com/embed/ssOdzxZdg58"
-      title="YouTube video player"
-      frameborder="0"
-      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-      allowfullscreen></iframe>
-  </div>
-
-  <h2>Workflow</h2>
-
-  <p>Starting with your design tokens (which will usually be in a program like Figma, or whatever you use to manage your design system), working with Cobalt involves the following steps:</p>
+  <p>Using Cobalt is as easy as:</p>
 
   <ol>
-    <li>Creating a <code>tokens.json</code> design tokens file</li>
-    <li>Installing Cobalt output plugins of your choice (e.g. JS, TS, CSS, and/or Sass)</li>
-    <li>Running the CLI to output all your desired formats</li>
-    <li>(Bonus) Adding Cobalt to CI to always keep your design system up-to-date</li>
+    <li>Creating a <code>tokens.json</code> file</li>
+    <li>Installing Cobalt plugins</li>
+    <li>Running the CLI
+    <li><i>(Optional)</i> Adding Cobalt to CI</li>
   </ol>
 
-  <h3>1. Creating the `tokens.json` file</h3>
+  <h2>1. Creating the <code>tokens.json</code> file</h2>
 
   <p>
-    This is the boring part—converting your tokens to JSON. Usually this involves manually pulling values from your styleguide or your design program (like Figma) and formatting the JSON yourself. There’s not a great UI for this yet (feel
+    Converting your tokens to JSON is a manual process of grabbing values from your design files and formatting the JSON yourself. There’s not a great UI for this yet (feel
     free to <a href="https://github.com/drwpow/cobalt-ui/issues">suggest one</a> if you have one you like), but <strong>the Cobalt team is developing one currently</strong>.
   </p>
 
@@ -75,34 +46,34 @@ const title = 'Getting Started';
 
   <p>You can use the following token types (organizing them into any <a href="/docs/tokens/#groups">Groups</a> you’d like) (<a href="/docs/tokens">docs</a>):</p>
 
-  <ul>
-    <li><a href="/docs/tokens/#color">Color</a></li>
-    <li><a href="/docs/tokens/#dimension">Dimension</a></li>
-    <li><a href="/docs/tokens/#font">Font Family</a></li>
-    <li><a href="/docs/tokens/#font-weight">Font Weight</a></li>
-    <li><a href="/docs/tokens/#duration">Duration</a></li>
-    <li><a href="/docs/tokens/#cubic-bezier">Cubic Bézier</a></li>
-    <li><a href="/docs/tokens/#number">Number</a></li>
-    <li><a href="/docs/tokens/#link">Link</a></li>
-    <li><a href="/docs/tokens/#stroke-style">Stroke style</a></li>
-    <li><a href="/docs/tokens/#border">Border</a></li>
-    <li><a href="/docs/tokens/#transition">Transition</a></li>
-    <li><a href="/docs/tokens/#shadow">Shadow</a></li>
-    <li><a href="/docs/tokens/#gradient">Gradient</a></li>
-    <li><a href="/docs/tokens/#typography">Typography</a></li>
+  <ul class="tokens-list">
+    <li><a class="token-card" href="/docs/tokens/#color"><Token type="color" /><span class="token-type">Color</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#dimension"><Token type="dimension" /><span class="token-type">Dimension</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#font-family"><Token type="fontFamily" /><span class="token-type">Font Family</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#font-weight"><Token type="fontWeight" /><span class="token-type">Font Weight</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#duration"><Token type="duration" /><span class="token-type">Duration</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#cubic-bezier"><Token type="cubic-bezier" /><span class="token-type">Cubic Bézier</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#number"><Token type="number" /><span class="token-type">Number</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#link"><Token type="link" /><span class="token-type">Link</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#stroke-style"><Token type="stroke-style" /><span class="token-type">Stroke style</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#border"><Token type="border" /><span class="token-type">Border</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#transition"><Token type="transition" /><span class="token-type">Transition</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#shadow"><Token type="shadow" /><span class="token-type">Shadow</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#gradient"><Token type="gradient" /><span class="token-type">Gradient</span></a></li>
+    <li><a class="token-card" href="/docs/tokens/#typography"><Token type="typography" /><span class="token-type">Typography</span></a></li>
   </ul>
 
-  <h3>2. Installing Cobalt Plugins of your choice</h3>
+  <h2>2. Installing Cobalt Plugins</h2>
 
   <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>Run the following in a terminal, in the code project you’d like to generate code to:</p>
+  <p>Run the following in a terminal, in the code project folder you’d like to generate code to:</p>
 
   <Code lang="bash" code="npm i -D @cobalt-ui/plugin-js @cobalt-ui/plugin-css @cobalt-ui/plugin-sass" />
 
-  <h3>3. Running the CLI to output your desired formats</h3>
+  <h2>3. Running the CLI</h2>
 
   <p>First install the CLI:</p>
 
@@ -136,7 +107,51 @@ export default {
 
   <p>This will output JS, CSS, and Sass in the <code>./tokens/</code> folder (which you can change in your config). It will also alert you of any errors in your schema.</p>
 
-  <h3>Next steps</h3>
+  <h2>4. (optional) Adding Cobalt to CI</h2>
+
+  <p>Using your preferred CI stack, here’s an example of how you could add Cobalt to your CI. First, we’ll take a <code>package.json</code> that had an existing <code>npm run build</code> command, and add <code>co build</code> to it:</p>
+
+  <Code lang="diff" code={`  {
+     "scripts": {
+-      "build": "npm run build:app",
++      "build": "npm run build:tokens && npm run build:app",
+       "build:app": "vite build",
++      "build:tokens": "co build",
+     }
+  }`} />
+
+  <p><em>Note: this is just a generic example. The important part is that <code>co build</code> is run somehow during the build.</em></p>
+
+  <p>Then add the <code>npm run build</code> command to your preferred CI tool. Here’s an example in GitHub Actions:</p>
+
+  <Code lang="yaml" code={`name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: ci-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - run: npm i
+      - run: npm run build`} />
+
+  <p>This will then run <code>co build</code> on every code change. This not only validates your tokens to make sure they’re 100% valid; it also runs all the code plugins so you know if there was an error generating tokens to CSS, etc.</p>
+
+  <p>You could then take the additional step of using a package versioning tool like <a href="https://github.com/changesets/changesets" target="_blank" rel="noopener noreferrer">Changesets</a> to release npm packages from CI (the <a href="https://github.com/drwpow/cobalt-ui/blob/main/.github/workflows/release.yml" target="_blank" rel="noopener noreferrer">the Cobalt GitHub repo</a> uses this to release new package versions automatically).</p>
+
+  <h2>Next steps</h2>
 
   <ul>
     <li><a href="/docs/tokens">Learn about tokens</a></li>
@@ -145,3 +160,48 @@ export default {
     <li><a href="/docs/plugins">Add plugins</a></li>
   </ul>
 </Layout>
+
+<style lang="scss">
+  @use '../../../../tokens/index' as *;
+
+
+  .tokens-list {
+    display: grid;
+    gap: 1rem;
+    grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr));
+    margin: 0;
+    padding: 0;
+
+    li {
+      list-style: none !important;
+      margin: 0 !important;
+      padding: 0 !important;
+    }
+  }
+  .token-card {
+    align-items: center;
+    border-radius: 1rem;
+    border: 2px solid token('color.ui.contrast.20');
+    color: token('color.ui.contrast.90');
+    display: flex;
+    font-size: 1.125rem;
+    font-weight: 550;
+    gap: 0.75rem;
+    padding: 1rem;
+    text-decoration: none;
+    transition: border-color 100ms linear, color 100ms linear;
+
+    &:hover {
+      border-color: token('color.ui.action');
+      color: token('color.ui.action');
+    }
+
+    :global(.token) {
+      transform: translate3d(0, 0, 0);
+    }
+  }
+
+  .token-type {
+    display: block;
+  }
+</style>
diff --git a/docs/src/pages/docs/guides/design-tokens.md b/docs/src/pages/docs/guides/design-tokens.md
@@ -0,0 +1,48 @@
+---
+title: What are Design Tokens?
+layout: ../../../layouts/docs.astro
+---
+
+# What are Design Tokens?
+
+Tokens are the fundamental building blocks of design. They typically refer to things like colors, typography, and icons, but have no formal definition or restriction on what they can be. Tokens aren’t user interface (UI); they’re the lower-level **common building blocks** that make up a UI design system.
+
+## History
+
+The coinage of the phrase “design tokens” dates back to a <a href="https://www.youtube.com/watch?v=wDBEc3dJJV8" target="_blank" rel="noopener noreferrer">2016 talk with Jina Bolton and Jon Levine</a> talking about Salesforce’s _Lightning Design System_. In it they define their tokens as “basic sub-atoms of their design system.”
+
+<div class="yt-embed">
+  <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/wDBEc3dJJV8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+</div>
+
+## Why use Tokens?
+
+It‘s easy to fall into the trap of thinking that a design system is truly complete, and finished, and will never change. The reality is that just like products, design systems go through micro-iterations as well. Colors and typography get tweaked as you go through accessibility audits. Values get improved. It’s more realistic to look at your design system as a living, breathing, evolving creature that changes with time.
+
+Of course, keeping all code across all your products and platforms up-to-date with this changing, evolving, iterative brand is hard. Things have to be embedded into code at some level. So the thinking around design tokens is to find the elements of design that are so small and reusable that they can be managed in one central place and be reused across different programming languages and in different contexts.
+
+## Design Token Formats
+
+Though there is <a href="https://designtokens.org" target="_blank" rel="noopener noreferrer">“one standard to rule them all”</a> being actively worked on by the W3C that hopes to improve upon all previous formats, it’s still **under development** and subject to change.
+
+<div class="yt-embed">
+  <iframe
+    width="560"
+    height="315"
+    src="https://www.youtube-nocookie.com/embed/ssOdzxZdg58"
+    title="YouTube video player"
+    frameborder="0"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowfullscreen></iframe>
+</div>
+
+Cobalt uses this new W3C community standard in the hopes that it will become a common/universal way of expressing design tokens. To get started, you can view either:
+
+- [Cobalt’s guide to writing tokens](/docs/tokens), or
+- [The W3C Design Tokens specification itself](https://design-tokens.github.io/community-group/format/)
+
+Other competing formats include, but aren’t limited to:
+
+- <a href="https://amzn.github.io/style-dictionary" target="_blank" rel="noopener noreferrer">Style Dictionary</a>
+- <a href="https://docs.tokens.studio/tokens/token-types" target="_blank" rel="noopener noreferrer">Tokens Studio for Figma plugin</a>
+- <a href="https://diez.org" target="_blank" rel="noopener noreferrer">Diez</a>
diff --git a/docs/src/pages/docs/guides/index.md b/docs/src/pages/docs/guides/index.md
@@ -5,6 +5,7 @@ layout: ../../../layouts/docs.astro
 
 # Guides
 
+- [What are Design Tokens?](/docs/guides/design-tokens/)
 - [Best Practices](/docs/guides/best-practices/)
 - [Thinking in Modes](/docs/guides/modes)
 - [Syncing with Figma using Tokens Studio](/docs/guides/tokens-studio)

diff --git a/docs/src/pages/docs/guides/tokens.md b/docs/src/pages/docs/guides/tokens.md
diff --git a/docs/src/pages/docs/tokens/index.astro b/docs/src/pages/docs/tokens/index.astro
@@ -75,7 +75,7 @@ const tokenDef = {
 }`}
   />
 
-  <h2 id="font">
+  <h2 id="fontFamily">
     <Token type="fontFamily" />
     Font Family
   </h2>