node package manager
Stop wasting time. Easily manage code sharing in your team. Create a free org ยป

coatroom

npm-version npm-total-downloads npm-monthly-downloads npm-license github-stars github-issues github-forks github-watchers

Coatroom

Coatroom is an easy way to create a front end component library. A tool that helps you create, organize and get an overview of all your components.

Components are made of HTML and CSS, generated by a template and LESS and documented by creating style guides written in Markdown to help other developers understand how and when to use these components.

Here is a live example of a generated overview page.

screenshot of a generated overview page example

Quick guide

This quick guide uses the example project which is located in the bundled /example/ folder.

  • Install Coatroom with npm install coatroom --save in your project folder.
  • Create a folder for your components, as in the example. Each component should have its own folder with its associated files. How exactly components are defined is described below.
  • Create a bootstrap in Node, as in the example. This will invoke coatroom. A configuration object is required as an argument. More information regarding the configuration object is described below.
  • Run your bootstrap code, for example npm run-script build-example. Coatroom will generate, validate and build your components and the overview page.

Running the example project locally

Simply type node run-script build-example.

The configuration object

In order to invoke Coatroom, a configuration object is required. An example of the configuration object can be found here.

Property name Explanation
title {string} The title of the overview page.
input {object}
input.components {string} Path to the folder where the components are located.
input.less {array of strings} [optional] An array of .less files. These files will automatically be prepended to the generated .less file. If your components or style guides use any shared LESS use this option.
input.lessModifyVars {object} [optional] An object with modified LESS variables supported by the LESS tool.
input.styleguides {object} [optional] An object to add external style guide documents. Keys is the document title, value is the path to the file.
input.scripts {array of strings} [optional] An array of .js JavaScript files. These files will automatically be appended to the overview page, enable it to include custom JavaScript.
input.externalStylesheets {array of strings} [optional] An array of external CSS stylesheets that may be appended to the overview page, enable it to include external custom CSS such as fonts.
input.defaultTableHeaderBackgroundColor {strings} [optional] Possible to set a custom table header color.
input.defaultTableCellBackgroundColor {strings} [optional] Possible to set a custom table cell color.
output {object}
output.overview {string} Path to a file which will be the generated overview page.
output.less {string} Path to a file which will be the generated concatenated LESS file.
output.css {string} [optional] Path to a file which will be the generated compiled CSS file.
validation {string} [optional]
validation.disallowedCSSRules {array of strings} [optional] An array of CSS properties that should be disallowed within components. It is also possible to disallow property values by writing position=absolute, while allowing all other values with z-index!=0.
validation.disallowedCSSUnits {array of strings} [optional] An array of units that should be disallowed within components.

How components work

A component consists of a folder and various files residing in that folder. The file of the folder is the same name of the CSS class name. For example if the folder is called "btn" then the core CSS class for the component will be btn.

Here is an example of a component.

Each component requires three types of files:

  • component.less
  • component.mustache
  • component.md

component.less

The CSS of a component is written in LESS.

Coatroom also uses flavor of Documented Style Sheets in order to obtain component data such as its name, description, states and types.

Here is a list of supported annotations Coatroom uses:

Annotation Description
@name The name of the component.
@description A short description of the component.
@state List of different states the component can be in. CSS pseudo classes (:hover, :active, :disabled) for the component are usually the states, but this can be expanded to custom states depending on your own conventions.
@type List of different types the component can be of. For example, a button can be a confirm or a warning button. These should only be small alternative alterations, as only the CSS will change, not the template markup.
@overviewBackgroundColor If you want to change the color of the component background table cell with a specific color.

Here is an example of a component LESS.

component.mustache

This contains the HTML template of the component. The template needs to have the {{classes}} curly braces. Coatroom will use this template and replace the {{classes}} placeholder with real CSS classes, based on the different states and types, when generating the overview page.

Here is an example of a template.

component.md

Each component can have their own custom style guide documentation to help describe the component for the readers. The style guide should be written in [Markdown].

Here is an example of a component style guide.

The overview page

Coatroom creates a stand-alone component overview HTML-page, with all the CSS bundled in itself.

Here is a live example of a generated overview page.

Running Coatroom as a Grunt task

It is fully possible to run Coatroom as a Grunt task.

Here is an example of a registered Grunt task.

Tests

Tests ends with the file extension .test.js and can be invoked by typing npm test.

Bugs, questions, suggestions or other feedback

Simply create an issue here.

NPM releases

Can be found here.

Contribution and contributors

Contributions are appreciated!

The list of all contributors can be found here.

License

Coatroom is licensed under the Apache License, Version 2.0.