Design elements to be used across all Citizens Advice products.
© Citizens Advice
The style guide is available on http://citizensadvice.github.io/cab-ui/
cab-ui
├── lib
| ├── styles
| | ├── base Files that do not compile on their own (except /vendor) :eg: variables.less
| | | ├── mixins Mixins that do not compile on their own :eg: mixin─buttons.less
| | | ├── vendor Vendor styles :eg: prism.css
| | | └── print Print styles
| | ├── components Micro layout styles :eg: lists, type
| | ├── modules Visual styles :eg: callouts.less
| | ├── theme Project specific modules :eg: mega─menu
| | ├── docs Documentation specific modules :eg: swatches.less
| | ├── dev Modules in development :eg: energy─comparison.less
| | | └── theme Theme modules in development :eg: feedback.less
| | ├── styles.less Import base/, components/, layouts/ and modules/
| | ├── site.less Import styles.less and theme/
| | └── dev.less Import site.less and dev/ and docs/
| ├── assets
| | ├── fonts
| | └── images
| | ├── theme Theme specific assets, such as images
| | └── dev Assets for features in development, such as images
| ├── jade Jade files for documentation
| | ├── dev Jade files for development features
| | └── partials Partial files for Jade templates
| └── js Un─concatonated JavaScript files
| ├── vendor Vendor JavaScript files
| └── dev JavaScript in development
├── samples A sample gulp setup for new projects using cab─ui
| ├── package.json
| └── gulpfile.js
├── public Public folder that all files compile into
| └── js Currently where JavaScript is kept (yet to move into libs)
├── package.json Node.js dependancies for the build process
└── gulpfile.js Defines the build process
This repository is a set of comment styles and design elements that can be included in another project.
Other projects should:
- include this repository as node dependancy in their package.json file. The styles and assets will then be available in
node_modules/cab-ui - import the less files they required into their own stylesheet. You may need to setup a symlink from the folder containing the less file to the image assets folder
- setup a build process using the same processors as this repository
Example of how to include the package in package.json
{
"devDependencies": {
"cab-ui": "https://github.com/citizensadvice/cab-ui.git#v1.0.0",
}
}Sample files for both package.json and gulpfile.js are maintined within the samples folder. Documentation on using them can be found samples/README.md.
The build process uses Gulp.
- Install the latest version of Node.js
- Install Gulp globally
npm install gulp -g - Install the dependancies locally
npm install - To build:
- To build once run
gulp - To build and watch for changes run
gulp watch - To build for production run
gulp build. This will clean the public directory and minify the CSS. - To clean the public directory run
gulp clean - To publish to gh-pages run
gulp gh-pages. This will run the full build process and publish directly to the gh-pages branch.
The CSS is written in Less. The build process transforms the Less into a single CSS file.
The process also uses PostCSS plugins to make writing the CSS easier. Plugins used are:
- autoprefixer - Automatically add css prefixes for older browsers
- https://github.com/postcss/postcss-color-rgba-fallback - Add a hex colour fallback for rgba for IE8
- postcss-opacity - Add a filter fallback for opacity for IE8
- pixrem - Add pixel fallback for rem units for IE8
- postcss-copy-assets - Copy and rebase image and
- cssnano - Minify the CSS
The build process generates the style-guide in the public folder.
Running the gulp gh-pages task will publish this guide to the gh-pages branch which is available from http://citizensadvice.github.io/cab-ui/.
If you want to run the style-guide locally on a web server then npm run server will start a website on localhost:8080 serving the contents of public folder. Alternatively you can install http-server globally (npm install http-server -g) and start a server for any directory by running http-server.
It's important to start any localhost instance from the public directory. If not, the base directory links used for stylesheets and assets will not load correctly.
The easiest way to do browser testing is with Browser Sync.
- Install Browser Sync
npm install -g browser-sync - Run Browser Sync from the public folder, watching HTML and CSS files
browser-sync start --server --files="*.html, css/*.css"
Gradually, the LESS files will need to fit into a new folder structure.
└─┐ lib Any *.less files in this directory will be built
├─┐ base used for all base level LESS files, such as
│ ├─ colors.less
│ └─ variables.less
├─ vendors all third party CSS and LESS, such as resets
├─ mixins general functional mixins will sit here, giving us a library of funtional mixins to draw on
├─ modules all website page elements, such as breadcrumbs
└─ assets all images and fonts required by the CSS
- Make sure every commit message has a title/summary line, with an explanation on another line beneath
- Always prepend the commit title with either
fix:,change:,add:ordev:, depending on what the content of the commit is
Patch messages should follow this same format, with a summary of changes under each of the four headings above.
As this repository is used by other projects it is important to version the code. We are using semantic versioning.
npm can be used to increase the version numbers and, crucially, tag the git commit.
npm version patchIncrease the patch version and tag. Bug fixes and other minor changes: Patch release, increment the last number, e.g. 1.0.1npm version minorIncrease the minor version and tag. New features which don't break existing features: Minor release, increment the middle number, e.g. 1.1.0npm version majorIncrease the major version and tag. Changes which break backwards compatibility: Major release, increment the first number, e.g. 2.0.0
Git push does not automatically transfer tags to github. In order to push your tags you need to do either git push origin tagname to push a single tag or git push --tags to push all tags.