Coatroom NPM | npm.io

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.