Config documentation

Author: devowhippit

config/alerts.js

@@ -6,15 +6,16 @@ let emoji = require('node-emoji');
 let chalk = require('chalk');
 
 /**
- * Config
+ * Alert configuration
+ *
+ * @type {Object}
  */
-
 module.exports = {
   /**
-   * Node Emoji
+   * Node Emoji. Refer to the package for details on the available options.
    *
-   * @param  {String}  Source  https://github.com/omnidan/node-emoji
-   * @param  {String}  Dict    https://raw.githubusercontent.com/omnidan/node-emoji/master/lib/emoji.json
+   * @source https://github.com/omnidan/node-emoji
+   * @source https://raw.githubusercontent.com/omnidan/node-emoji/master/lib/emoji.json
    */
   styles: emoji.get('nail_care'),
   scripts: emoji.get('rainbow'),
@@ -30,11 +31,16 @@ module.exports = {
   compression: emoji.get('compression') + ' ',
   package: emoji.get('package'),
   accessible: emoji.get('person_doing_cartwheel'),
+
   /**
-   * Chalk string coloring functions
+   * Chalk configuration. Refer to the package for details on the available
+   * options. The current color selection is based on the NYC Opportunity
+   * brand colors.
+   *
+   * @source https://github.com/chalk/chalk
+   * @source https://nycopatterns.cityofnewyork.us/colors
    *
-   * @param  {String}  Source  https://github.com/chalk/chalk
-   * @param  {String}  Colors  https://nycopatterns.cityofnewyork.us/colors
+   * @type {Object}
    */
   str: {
     path: s => chalk.hex('#FFC0F6').underline(s), // pink

config/global.js

@@ -1,11 +1,11 @@
 /**
- * Global Configuration
+ * Global configuration
  *
  * @type {Object}
  */
 module.exports = {
   /**
-   * Main Project Directories
+   * Main project directories
    *
    * @type {String}
    */
@@ -14,7 +14,8 @@ module.exports = {
   dist: 'dist',
 
   /**
-   * Project Entrypoints
+   * Project entrypoints. These are used by other files to determine defaults.
+   * They must also have a reference in the directories configuration below.
    *
    * @type {Object}
    */
@@ -28,15 +29,17 @@ module.exports = {
   },
 
   /**
-   * Directories to scaffold
+   * Directories to scaffold. The scaffold command will create the filesystem
+   * configured here and use files in the ./scaffold directory as the contents
+   * for files described here.
    *
    * @type {Object}
    */
   directories: [
     /**
-     * Configuration Path(s)
+     * Configuration path(s)
      *
-   * @type {Object}
+     * @type {Object}
      */
     {
       __dirname: 'config',
@@ -49,7 +52,7 @@ module.exports = {
     },
 
     /**
-     * Distribution Directory
+     * Distribution directory
      *
      * @type {Object}
      */
@@ -58,7 +61,7 @@ module.exports = {
     },
 
     /**
-     * Source and Patterns path(s)/naming
+     * Source and patterns path(s)/naming
      *
      * @type {Object}
      */
@@ -173,14 +176,14 @@ module.exports = {
     }
   ],
 
-  /**
-   * Default arguments
-   *
-   * @type {Object}
-   */
-  args: {
-    notifications: '', // '--nondescript -nd' or '--silent'
-    linting: '',       // '--no-lint -nl'
-    pa11y: '',         // '--no-pa11y -np'
-  }
+  // /**
+  //  * Default arguments
+  //  *
+  //  * @type {Object}
+  //  */
+  // args: {
+  //   notifications: '', // '--nondescript -nd' or '--silent'
+  //   linting: '',       // '--no-lint -nl'
+  //   pa11y: '',         // '--no-pa11y -np'
+  // }
 };

config/lint.js

@@ -1,8 +1,16 @@
+/**
+ * Lint configuration
+ *
+ * @type {Object}
+ */
 module.exports = {
   /**
-   * ES Lint Configuration
+   * ESLint configuration. Refer to the package for details on the available options.
    *
-   * @param  {String}  url  https://eslint.org
+   * @source https://eslint.org/docs/user-guide/configuring
+   * @source https://github.com/google/eslint-config-google
+   *
+   * @type {Object}
    */
   eslint: {
     extends: 'google',
@@ -24,17 +32,21 @@ module.exports = {
       ]
     }
   },
+
   /**
-   * Stylelint
+   * stylelint configuration. Refer to the package for details on the available options.
+   *
+   * @source https://stylelint.io/user-guide/configure
    *
-   * @param  {String}  url  https://stylelint.io
+   * @type {Object}
    */
   stylelint: {
     extends: 'stylelint-config-standard',
     rules: {
+      'color-hex-case': 'upper',
       'no-missing-end-of-source-newline': null,
       'at-rule-no-unknown': [true, {
-        'ignore': ['use', 'tailwind']
+        'ignoreAtRules': ['use', 'forward', 'tailwind']
       }]
     }
   }

config/make.js

@@ -10,7 +10,7 @@ const alerts = resolve('config/alerts');
 /**
  * Templates
  *
- * Templates are stored in the config/make directory. These are the templates
+ * Templates are stored in the ./config/make directory. These are the templates
  * used for the different filetypes. There are a few template variables that
  * are interpolated in by the make.js script;
  *
@@ -45,7 +45,7 @@ const dirs = {
 };
 
 /**
- * Make Configuration
+ * Make configuration
  *
  * @type {Object}
  */

config/pa11y.js

@@ -1,7 +1,9 @@
 /**
- * Configuration options for pa11y
+ * Pa11y configuration. Refer to the package for details on the available options.
  *
- * @param  {String}  url  https://github.com/pa11y/pa11y#configuration
+ * @source https://github.com/pa11y/pa11y#configuration
+ *
+ * @type {Object}
  */
 module.exports = {
   standard: 'WCAG2AA',

config/postcss.js

@@ -7,7 +7,10 @@ const resolve = require(path.join(__dirname, '../', 'bin/util/resolve'));
 const installed = require(path.join(__dirname, '../', 'bin/util/installed'));
 
 /**
- * PostCSS Plugins
+ * PostCSS plugins. This is where most of the configuration for PostCSS is
+ * handled. Refer to the PostCSS docs for details and available plugins.
+ *
+ * @source https://github.com/postcss/postcss#plugins
  *
  * @type {Array}
  */
@@ -16,7 +19,7 @@ let plugins = [
 ];
 
 /**
- * Check for tailwindcss
+ * Check for the tailwindcss package
  */
 
 if (installed('tailwindcss')) {
@@ -27,7 +30,7 @@ if (installed('tailwindcss')) {
 }
 
 /**
- * PostCSS Configuration
+ * PostCSS configuration.
  *
  * @type {Object}
  */

config/slm.js

@@ -17,6 +17,7 @@ module.exports = {
   src: global.src,           // Base source directory for all possible slm files
   dist: global.dist,         // Distribution for slm files
   views: global.entry.views, // View directory within source directory ^
+
   /**
    * Options to pass to the marked package
    *
@@ -27,6 +28,7 @@ module.exports = {
     headerIds: true,
     smartypants: true
   },
+
   /**
    * Options to pass to the JS Beautify package for formatting html
    *
@@ -41,6 +43,7 @@ module.exports = {
     wrap_line_length: 0,
     indent_inner_html: false
   },
+
   /**
    * The following objects are locals passed to the slm view render and
    * are accessed via control codes. For example, in a .slm template;

config/svgs.js

@@ -15,51 +15,20 @@ module.exports = {
   src: `${global.src}/svg`,   // svg source
   dist: `${global.dist}/svg`, // svg distribution
   prefix: 'pttrn-',           // Prefix to prepend to optimized svgs
+
   /**
    * Plugin options for SVGO
    *
-   * @param {String} source https://github.com/svg/svgo#what-it-can-do
+   * @source https://github.com/svg/svgo#what-it-can-do
    */
   svgo: {
     convertPathData: false,
-    // cleanupAttrs: true,
-    // removeDoctype: true,
-    // removeXMLProcInst: true,
-    // removeComments: true,
-    // removeMetadata: true,
-    // removeTitle: true,
-    // removeDesc: true,
-    // removeUselessDefs: true,
-    // removeEditorsNSData: true,
-    // removeEmptyAttrs: true,
-    // removeHiddenElems: true,
-    // removeEmptyText: true,
-    // removeEmptyContainers: true,
-    // removeViewBox: false,
-    // cleanupEnableBackground: true,
-    // convertStyleToAttrs: true,
-    // convertColors: true,
-    // convertTransform: true,
-    // removeUnknownsAndDefaults: true,
-    // removeNonInheritableGroupAttrs: true,
-    // removeUselessStrokeAndFill: true,
-    // removeUnusedNS: true,
-    // cleanupIDs: true,
-    // cleanupNumericValues: true,
-    // moveElemsAttrsToGroup: true,
-    // moveGroupAttrsToElems: true,
-    // collapseGroups: true,
-    // removeRasterImages: false,
-    // mergePaths: true,
-    // convertShapeToPath: true,
-    // sortAttrs: true,
-    // removeDimensions: true,
-    // removeAttrs: {attrs: '(stroke|fill)'}
   },
+
   /**
    * Plugin options for svgstore
    *
-   * @param {String} source https://github.com/svgstore/svgstore#options
+   * @source https://github.com/svgstore/svgstore#options
    */
   svgstore: {
     /** Filename of the sprite. It will not use the prefix defined above. */

config/tailwindcss.js

@@ -6,7 +6,10 @@
 // const tokens = require('./tokens.js');
 
 /**
- * Config
+ * Tailwindcss Config
+ *
+ * @source https://tailwindcss.com/docs/configuration
+ *
+ * @type {Object}
  */
-
 module.exports = {};

config/tokens.js

@@ -14,11 +14,13 @@ const package = resolve('package.json');
  */
 module.exports = {
   /**
-   * Possiple options (and their defaults) to pass to json-to-scss
+   * JSON-TO-SCSS configuration. Below possible options and their defaults are listed
    *
-   * @type {Source} https://github.com/rlapoele/json-to-scss
+   * @source https://github.com/rlapoele/json-to-scss
+   *
+   * @type {Mixed}
    */
-  output: `"${global.src}/${global.entry.config}/_tokens.scss"`,
+  output: `"${path.join(global.base, global.src, global.entry.config, '_tokens.scss')}"`,
   // prefix: '"$tokens:"',
   // suffix: '"";""',
   // format: '".scss"',
@@ -31,6 +33,18 @@ module.exports = {
   // keys: 'auto',
   // values: 'auto',
   // stringKeys: '"family,font-family,fontfamily,font-stack,fontstack,font-face,fontface"',
+
+  /**
+   * Design tokens. These can be custom values for your Sass library as well
+   * as be values mapped directly to tokens in the Tailwindcss configuration.
+   * CSS variables can also be used in the token configuration. Note, other
+   * Tailwindcss configuration options, such as variants and modules should
+   * be configured in the `tailwindcss` configuration.
+   *
+   * @source https://tailwindcss.com/docs/configuration
+   *
+   * @type {Mixed}
+   */
   'version': `"${package.version}"`,
   'border': {
     'width': '3px',