Living Styleguide for componentized front end development.
Uses the Gulp task runner to
With Yarn:
yarn add global front-end-styleguide-cli
With npm:
npm install -g front-end-styleguide-cli
On some systems root (sudo
) is needed to install global packages.
Create a new project in an empty folder:
front-end-styleguide init
If the folder already contains a Git repository, this information will be used to populate the package.json
.
config/config.json
{
"css": {
"dev": {
/* Sass options for development */
},
"dist": {
/* Sass options for production */
}
},
"html": {
"browsersync": {
/* Browsersync options */
}
},
"img": {
"svgSpriteDev": {
/* SVG Sprite options for development */
},
"svgSpriteDist": {
/* SVG Sprite options for production */
},
"imagemin": {
/* Imagemin options */
}
}
}
config/paths.json
{
"output": {
"css": {
"path": "css",
"name": "styles.css"
},
"js": {
"path": "js",
"name": "scripts.js"
},
"img": {
"path": "img",
"icons": "icons.svg"
}
}
}
.babelrc
: Configuration for Babel.browserslistrc
: Set supported browsers.editorconfig
: Set basic rules for editors/IDEs.eslintignore
: Files ignored by ESLint.eslintrc.json
: Configuration and rules for ESLint.stylelintrc.json
: Configuration and rules for Stylelint
.
├── config [optional]
│ ├── config.json
│ ├── branding.json
│ └── paths.json
├── src
│ ├── components
│ │ ├── example
│ │ │ ├── default.guide.njk
│ │ │ ├── default.njk
│ │ │ ├── scripts.js
│ │ │ └── styles.scss
│ │ └── icons
│ │ ├── usage.guide.svg
│ │ └── menu.svg
│ ├── images
│ │ └── img-name.png
│ ├── layouts
│ │ ├── components.njk
│ │ └── prototypes.njk
│ ├── prototypes
│ │ └── index.njk
│ ├── setup
│ │ ├── scaffolding.scss
│ │ └── variables.scss
│ ├── copy.js
│ ├── main.js
│ └── main.scss
├── .babelrc
├── .browserslistrc
├── .editorconfig
├── .eslintignore
├── .eslintrc.json
└── .stylelintrc.json
These are the main tasks:
front-end-styleguide
to start the default task.- Watches for file changes.
- Starts Browsersync.
- Opens the default web browser.
front-end-styleguide development
to start the development task.- Same as the default task.
- No file watching / Browsersync.
front-end-styleguide preview
to create a prototype preview.- Minifies CSS, JavaScript and images.
- Doesn't generate component HTML.
- Errors break pipe.
front-end-styleguide production
to create production ready files.- Minifies CSS, JavaScript and images.
- Doesn't generate any HTML.
- Errors break pipe.
front-end-styleguide test
to run all tests.- Lints CSS and JavaScript.
There are more tasks available for standalone execution:
css:dev
,css:prev
andcss:dist
for Sass to CSS compilation.css:lint
andcss:lint:break
for CSS linting.js:dev
,js:prev
andjs:dist
for JavaScript compilation with Babel.js:lint
andjs:lint:break
for JavaScript linting.html:dev
andhtml:prev
for Nunjucks to static HTML generation.img:dev
,img:prev
andimg:dist
for image copying and icon sprite generation.copy:dev
,copy:prev
andcopy:dist
for the copy task.
The generated folders dev
, prev
and dist
are excluded from Git.
Output to dev/css
, prev/css
or dist/css
.
Sass is a CSS preprocessor supporting variables, nesting and mixins – among many other features. For a quick start jump to the Sass Basics. stylelint monitors the code for errors and consistency deviations. It uses the standard config with a few additions.
This styleguide splits the source CSS into small parts. This ensures a better organization of style declarations. Each component sits in it's own folder and is re-usable across the project.
The function @import
includes Sass or CSS files in the main Sass file. The final output is one large CSS file to minimize browser requests. See src/main.scss
for more information.
Global stylelint rules are set in .stylelintrc.json
. Per-file rules can be set with comments (e.g. /* stylelint-disable selector-max-id */
). With a .stylelintignore
file in the project root, CSS files can be excluded from linting.
The development task generates sourcemaps. The preview and production tasks minify the CSS.
Output to dev/js
, prev/js
or dist/js
.
JavaScript files are bundled together with Browserify and compiled with Babel and the ES2015 preset. To learn more about JavaScript modules head over to the MDN article on import
. ESLint checks if the code follows the Standard Style.
Global ESLint rules are set in .eslintrc.json
. Per-file rules can be set with comments (e.g. /* eslint no-console: "off" */
). With a .eslintignore
file in the project root, JavaScript files can be excluded from linting.
The development task generates sourcemaps. The preview and production tasks minify the source.
Output to dev
and dev/components
or prev
.
Nunjucks is an HTML templating engine based on JavaScript. The styleguide creates static HTML from Nunjucks files. Take a look at the templating docs for further information on Nunjucks.
Component pages are references for UI elements. They will be generated only if the component folder contains at least on *.guide.njk
file. Each of these files represent a section within the component page, ordered by filename. The tasks preview
and production
will not render component pages.
Each component-name/*.guide.njk
file should follow this pattern for a nicely styled output:
{% set title = "Sub-component title [optional]" %}
{% set description = "A little description [optional]" %}
{% extends sgSection %}
{% block body %}
<p>This is the actual code for the component.</p>
{% endblock %}
The following variables can be used:
- [optional]
title
sets a heading for the component variation. - [optional]
description
provides additional information. - [optional]
background
injectsstyle="background: value"
into the component. - [optional]
padding
sets the padding. Possible values:none
.
Prototypes represent final pages. The prototypes folder supports hierarchy with subfolders. Go ahead and try out a basic website structure!
The default
and development
tasks inject a navigation bar into both component and prototype HTML files for faster site switching and additional settings. The task production
will not render protoype pages.
meta.version
: Current package.json version (e.g. "1.7.0").meta.env
:development
orproduction
depending on the task.meta.path.fileName
: The name of the current HTML file with extension (e.g. "index.html").meta.path.filePath
: Relative path containing the filename of the current HTML file (e.g. "components/header.html").meta.path.toRoot
: Relative path to the root (e.g. "../"). Returns an empty string if the file is already in the output root.
Output to dev/img
, prev/img
or dist/img
.
All files and folders placed in src/images
will be copied to dev/img
, prev/img
or dist/img
.
SVG files placed in the src/components/icons
folder will be transformed into an SVG icon sprite named icons.svg
. The original icons will not be copied to the output folders. SVG symbols can be referenced with their ID. The icon workflow creates IDs from the filename of the original SVG placed in src/components/icons
. Each ID is suffixed with "-icon" for better compatibility with browsers that need a polyfill.
Use the icon macro for easy icon linking. The macro takes the following parameters:
filename
: The icon filename in thesrc/components/icons
-folder without the.svg
extension.classes
: Additional classes separated with whitespace.size
: The initial icon size set withwidth
andheight
attributes. Defaults to24
.ariaHidden
: Show (false
) or hide (true
) the icon for screen readers. Defaults totrue
.
{% import "path/to/components/icons/icons.njk" as icon %}
{{ icon.link('filename', 'classes', size, ariaHidden) }}
The styleguide ships with svgxuse, a polyfill for browsers that do not support external SVG reference.
The preview and production tasks minify images with a lossless compressor.
Files that don’t fit in the above mentioned categories can be integrated into the styleguide with the copy utility src/copy.js
. To copy files from Node modules, install the module with yarn add module-name
or npm install --save module-name
and add files or folders to copy.js
.
copy.js
contains an array of objects. Each object is a copy instruction and has a folder
, files
, dest
and optional exclude
key.
folder
is the base path.files
specifies which files and folders will be copied. The folder structure will be kept (e.g.dist/**
results indev/js/dist/**
). Use globs to copy more than one file.dest
sets the destination for the copy process. The development, preview and production tasks each prefix the destination with their specific output folders (e.g.dev/
for development).- [optional]
excludes
contains a string or an array of strings with names for tasks that will not perform the copy instruction. Available task names aredev
,prev
anddist
.
Beware of overwriting files from other tasks (e.g. css/styles.css
). The copy task is started last, but due to asynchronous task execution the exact write order is unknown.
module.exports = [
{
folder: 'node_modules/svgxuse',
files: 'svgxuse.{js,min.js}',
dest: paths.js.base,
exclude: 'dist'
}
];
This declaration copies the files node_modules/svgxuse/svgxuse.js
and node_modules/svgxuse/svgxuse.min.js
to output/js/svgxuse.js
and output/js/svgxuse.min.js
. output
is either dev
or prev
depending on the task. The dist
task is excluded.
module.exports = [
{
folder: 'node_modules/@polymer',
files: '**',
dest: 'polymer'
}
];
Everything from node_modules/@polymer
will be copied to output/polymer
. Subfolders will be kept as is.
module.exports = [
{
folder: 'node_modules/@polymer/font-roboto',
files: '**',
dest: 'polymer'
}
];
Everything from node_modules/@polymer/font-roboto
will be copied to output/polymer
. No font-roboto
folder will be created.
The styleguide provides branding capabilities for the navigation bar and the component pages. Custom colors, an icon and logo can be set.
Create the file config/branding.json
to turn on branding. If no branding-file was found, the default colors from the styleguide will be used.
The following options are available:
{
"css": {
"color-primary": "#f88",
"color-secondary": "#999",
"color-text": "#000",
"color-background": "#ddd"
},
"logo": {
"icon": "filename.svg",
"logo": "another-filename.svg",
"title": "Title for the link",
"url": "https://example.com/"
}
}
The icon and logo have to be SVG files. The icon must be square but the logo can have any aspect ratio. Make sure to include a width="x"
and height=""
to limit the logo dimensions. Both files have to be placed in the config
-folder and will be inlined with Nunjucks.