node package manager

sugarcoat

Sugarcoat

NPM version Dependency Status

Making UI documentation a bit sweeter ✨

Sugarcoat was created to enable developers to produce rich UI documentation easily and with minimal up-keep. Sugarcoat works by parsing project files for documentation comments (similar to JavaDoc, JSDoc, etc.) and generates a responsive HTML site or JSON that is organized and easy to read. Sugarcoat allows developers and designers access to up-to-date previews of UI elements, page components, project specific colors and typography, all in one place.

Note: This is still a work in-progress. Please file an issue if you encounter any issues or think a feature should be added.

Screenshot Colors

Screenshot Variables

Screenshot Components

Index


Features✨

  1. Lives in your project seamlessly

Sugarcoat will never force a file/project structure on you, nor make you create extra files for it to work.

  1. Universal Comment Syntax

Sugarcoat parses all comment blocks in the file(s) you specify with JSDoc commenting syntax. Or you can specify your own delimiters.

  1. Easy-to-identify component states

If you declare CSS modifier states within your comment block, Sugarcoat will highlight and display them in your pattern library for extra readability.

  1. Variables Galore

Sugarcoat will understand your variables if they're SCSS, LESS, or CSS Custom Property

  1. Customizable Layout

Sugarcoat allows you to define your own layout, partials and assets.

Install

npm install --save sugarcoat

Usage

Module API

The Sugarcoat module takes a config object and returns a Promise. The Promise resolves to the original config object, expanded to contain the data from your parsed sections.

const sugarcoat = require( 'sugarcoat' );
 
sugarcoat( config );
 
// or 
 
sugarcoat( config ).then( function( data ) {
    console.log( data );
});

CLI

You can also install the Sugarcoat command globally (via npm install -g sugarcoat). The sugarcoat command takes a path to a configuration file which must export the configuration object.

sugarcoat 'path/to/config.js'

Options

sugarcoat [flags] <configuration file>
 
Options:
 
  -h, --help     output usage information
  -V, --version  output the version number

Configuration

Simple Example

{
  settings: {
    dest: 'path/to/dest'
  },
  sections: [
    {
      title: 'Base',
      files: [
        'path/to/styles/typography/*.css'
        'path/to/styles/variables/*.css'
      ]
    },
    {
      title: 'UI',
      files: 'path/to/styles/molecules/**/*.css'
    }
  ]
}

settings Object

This object holds general configuration values.

cwd

  • Required: No
  • Type: String
  • Default: process.cwd()

Path to which dest is relative.

dest

  • Required: Yes
  • Type: String
  • Default: null
  • Relative: settings.cwd

Directory to which Sugarcoat will output the results. This path is relative to cwd. Sugarcoat will create any directories that do not already exist.

graphic

  • Required: No
  • Type: String
  • Default: null

Path to the image to be rendered in the heading of your pattern library.

log

  • Required: No
  • Type: Object

Configure Sugarcoat's logging properties. See npm/npmlog for more info.

prefix.assets

CSS file(s) you wish Sugarcoat to prefix with prefix.selector. The newly prefixed stylesheets will be placed in your document in the order you declare them.

prefix.selector

  • Required: No
  • Type: String
  • Default: .sugar-example

Define the selector to be used to prefix all assets from prefix.assets. Should a user choose to develop their own pattern library templates, they can designate their own selector prefix.

template.cwd

  • Required: No
  • Type: String
  • Default: Sugarcoat's theme directory

The base path to which all template paths are relative.

template.layout

  • Required: No
  • Type: String
  • Default: main.hbs (provided by Sugarcoat)
  • Relative: template.cwd

Path to the Handlebars layout that will define the layout of the site.

template.partials

Partial file(s) to register with Handlebars. If any partials use a reserved name, the respective partial will override the one provided by Sugarcoat.

template.assets

Static asset file(s) to copy to settings.dest. If you would like to use Sugarcoat's default pattern library assets, as well as your own, just include sugarcoat in the asset array.

title

  • Required: No
  • Type: String
  • Default: 'Pattern Library'

The value displayed as the heading of your pattern library.

sections Array

Contains an Array of Section Objects.

Section Object

Each section object in the sections array is rendered as a category. Each comment block within all files in your section object is rendered as a subcategory. You can modify the mode Sugarcoat uses to parse the files in your section object, as well as the template it uses to render the parsed data.

files

File(s) to parse for documentation comments. Sugarcoat uses globby to enable pattern matching.

title

  • Required: Yes
  • Type: String

Heading of the section.

mode & template###

mode

  • Required: No
  • Type: String
  • Default: undefined

By default, all files are parsed only for their comment blocks. By using 'variable' mode, Sugarcoat will parse your stylesheet's variable declarations as well. This works with variables prefixed with $, @, or --, depending on the stylesheet's file extension.

template

  • Required: No
  • Type: String
  • Default: 'section-default'

The default partial name used to display parsed comments is section-default. If mode is provided, the default partial name used is section-variable. mode has two alternate variable renderings available: section-color and section-typography. If you'd like this section to use a custom partial, provide its name to this option. Be sure to register your custom partial in settings.template.partials`. For more information on this, see Custom Templating.

Relationship Table

mode Default template Alternate template Description
undefined 'section-default' Parse comment block only
'variable' 'section-variable' Parse file content for variables and renders a simple table. Inline comments are treated as the variable's description. Groups of variables can be divided in a file by a comment block.
'variable' 'section-color' Same as 'section-variable', except variables are rendered as swatches
'variable' 'section-typography' Same as 'section-variable', except font-family styles are applied to sample text

Examples

Parse all variables in my file:

{
    title: 'Project Defaults',
    files: 'path/to/global/vars.scss',
    mode: 'variable'
}

Parse all variables in my file and render them using the 'section-color' partial:

{
    title: 'Colors',
    files: 'path/to/global/colors.scss',
    type: 'variable',
    template: 'section-color'
}

Standardized File Format

Throughout Sugarcoat we use a standardized format for files. This format allows the user to express a file in three different ways: String, Array, and Object.

String

A path or pattern (Globby) to a location.

Example

files: 'path/to/js/*'

Array

Provide a series of Standardized File Formats (Strings and/or Objects).

Example

files: [
  'path/to/main.js',
  {
    src: 'path/to/main.js',
    options: {
      nodir: true
    }
  }
]

Object

Provide more globbing options in addition to the standardized patterns. See Globby.

Example

files: {
  src: 'path/to/main.js',
  options: {
    nodir: true
  }
}

Code Comment Syntax

/**
 * @title Tooltip
 * @example
 *  <div class="tooltip">
 *    <span class="tooltip-content">This is a tooltip</span>
 *  </div>
 * @modifier .active enabled class on .tooltip
 * @state :focus allows visual contrast for accessibility
 */

Sugarcoat will parse any tag it finds into a key/value pair. For example: @tag value.

The exception being the following three reserved tags that are demonstrated in the above example:

  • @example Takes a single or multiline code example.

  • @modifier Used for a class modifier on a component: @modifier <selector> <description>.

  • @state Used for state pseudo-classes such as :hover: @state :<pseudo-class> <description>.

HTML

For html files, Sugarcoat uses the same comment style. Since HTML doesn't support this style you'll need to wrap your documentation comments with an HTML-style comment.

Comment Example (html)

<!--
/**
 * @title Some Component
 * @description This component has a description
 * @dependencies /path/to/some-component.js
 */
-->
<div class="some-component">
  <span>I'm a Component!</span>
</div>