docs(design-tokens): restore some docs internally (#348)

* docs(design-tokens): restore some docs internally

* style: format

packages/design-tokens/scripts/build.js

@@ -11,6 +11,32 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/**
+ * Creating an output target
+ * -------------------------
+ * An output target is a plain object with 4 methods and 4 props. The callbacks
+ * will fire as the tokens tree is being traversed, so you can build the contents
+ * of the output file accordingly. It has the following signature:
+ *
+ * - filename (string) the name of the generated file
+ * - ext (string) is the extension of the output file, eg. .css
+ * - suffix (string) optional if present, will be appended to the filename
+ * - content (string) the actual content of the file
+ *
+ * ```js
+ *   export const target = {
+ *     onCategory: ({ categoryName, tokens }) => {},
+ *     onSection: ({ categoryName, sectionName, tokens }) => {},
+ *     onValue: ({ categoryName, sectionName, key, value, tokens }) => {},
+ *     onComplete: () => {},
+ *     filename: 'design-tokens-telekom',
+ *     ext: '',
+ *     suffix: '',
+ *     content: null,
+ *   };
+ * ```
+ */
+
 import { join } from 'path';
 import fs from 'fs-extra';
 import each from 'lodash/each.js';

packages/design-tokens/src/tokens.js

@@ -9,6 +9,30 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/**
+ * The tokens are organized in categories, and each category has sections,
+ * which include the actual key/value pairs.
+ *
+ * CATEGORY-SECTION-KEY: VALUE
+ *
+ * The name of the token is determined by this structure. For example,
+ * if we look at the family section within the font category, we'll find
+ * at least the sans and mono values, so the tokens —in the CSS output—
+ * look like this:
+ *
+ * ```css
+ *   :root {
+ *     --{namespace}-{category}-{section}-{key}: {value};
+ *     --scl-font-family-sans: TeleNeoWeb, sans-serif;
+ *     --scl-font-family-mono: monospace;
+ *   }
+ * ```
+ *
+ * Sometimes you don't need a section, for this there's the special
+ * keyword DEFAULT we can use to omit the section name in the
+ * resulting token name.
+ */
+
 import { Color, Shadow } from './factories.js';
 
 export const NAMESPACE_PREFIX = 'scl';