node package manager



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



  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.


npm install --save sugarcoat


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 );


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'


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


Simple Example

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

settings Object

This object holds general configuration values.


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

Path to which dest is relative.


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


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

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


  • Required: No
  • Type: Object

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


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.


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


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

The base path to which all template paths are relative.


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


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


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.


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


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


  • Required: Yes
  • Type: String

Heading of the section.

mode & template###


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


  • 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


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.


A path or pattern (Globby) to a location.


files: 'path/to/js/*'


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


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


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


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


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>