PostCSS plugin to generate a style guide automatically
JavaScript HTML CSS
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
docs update theme guideline Jun 9, 2015
lib utility functions May 29, 2017
test fix tests May 29, 2017
.editorconfig init Apr 19, 2015
.gitignore update .gitignore Feb 5, 2016
.travis.yml add node v6 to travis Jun 23, 2016 update CHANGELOG Jul 5, 2017
LICENSE rename May 25, 2015 fix typo Jun 18, 2016
index.js pass opts to analyzer and print output styleguide filename May 29, 2017
package.json v0.14.0 Jul 5, 2017
style-guide-default.png update default theme Feb 10, 2016

postcss-style-guide Build Status

PostCSS plugin to generate a style guide automatically.

CSS comments will be parsed through Markdown and displayed in a generated HTML document.


$ npm install postcss-style-guide



var fs = require('fs');
var postcss = require('postcss');
var styleguide = require('postcss-style-guide');
var input = fs.readFileSync('input.css', 'utf8');

var output = postcss([
.then(function (reuslt) {
  var output = fs.readFileSync('styleGuide/index.html', 'utf8');
  console.log('output:', output);

in Gulp:

var gulp = require('gulp')

gulp.task('build:css', function () {
    var concat = require('gulp-concat')
    var postcss = require('gulp-postcss')
    var autoprefixer = require('autoprefixer')
    var customProperties = require('postcss-custom-properties')
    var Import = require('postcss-import')
    var styleGuide = require('postcss-style-guide')
    var nano = require('cssnano')

    return gulp.src('./app.css')
            customProperties({ preserve: true }),
                project: 'Project name',
                dest: 'styleguide/index.html',
                showCode: false,
                themePath: '../'

We can generate color palette from CSS Custom Properties with @start color and @end color annotations.


@import "color";
@import "button";


@import "button";
/* @start color */
:root {
    --red: #e23B00;
    --blue: #3f526b;
    --black: #000;
    --background: #faf8f5;
/* @end color */

postcss-style-guide generate style guide from CSS comments that have special annotation(@styleguide).

@title: set component name



@title Button

Use the button classes on and `<a>`, `<button>`, `<input>` elements.

<button class="button button--large button--red">Red Button</button>

    <button class="button button--large button--red">Red Button</button>

<button class="button button--large button--blue">Red Button</button>

    <button class="button button--large button--blue">Red Button</button>
.button {
    display: flex;
    align-items: center;
    justify-content: center;
    border-radius: 6px;
    cursor: pointer;

.button--large {
    width: 140px;
    height: 40px;
    font-size: 14px;

.button--red {
    color: #fff;
    background-color: var(--red);

.button--blue {
    color: #fff;
    background-color: var(--blue);

You will get styleguide/index.html for the style guide.

Default style guide design


  • options.src: The path to the source CSS file.
  • options.dest: The path to style guide file. (default: styleguide/index.html)
  • options.project: Project name. (default: Style Guide)
  • options.showCode: The flag to show CSS code (default: true)
  • options.theme: Theme name. (default: psg-theme-default)
  • options.themePath: The path to theme file. (default: node_modules/psg-theme-default)


You can select a theme of style guide with options.theme. And you can also create original themes. When you create themes, please read theme guideline

All of postcss-style-guide themes that can be used are here.

Themes list

How to develop postcss-style-guide theme


The MIT License (MIT)

Copyright (c) 2015 Masaaki Morishita