Design elements to be used across all Citizens Advice products.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
libs
public
samples
.eslintrc
.gitignore
.npmignore
LICENSE
README.md
gulpfile.js
package.json

README.md

Citizens Advice UI

Design elements to be used across all Citizens Advice products.

© Citizens Advice

The style guide is available on http://citizensadvice.github.io/cab-ui/

Folder structure

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

Including in a project

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.

Build process

The build process uses Gulp.

  1. Install the latest version of Node.js
  2. Install Gulp globally npm install gulp -g
  3. Install the dependancies locally npm install
  4. 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.

Less

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:

Generating the style-guide

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.

Browser testing

The easiest way to do browser testing is with Browser Sync.

  1. Install Browser Sync npm install -g browser-sync
  2. Run Browser Sync from the public folder, watching HTML and CSS files browser-sync start --server --files="*.html, css/*.css"

Folder structure

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

Commit and patch messages

  • 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: or dev:, 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.

Versioning

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 patch Increase the patch version and tag. Bug fixes and other minor changes: Patch release, increment the last number, e.g. 1.0.1
  • npm version minor Increase the minor version and tag. New features which don't break existing features: Minor release, increment the middle number, e.g. 1.1.0
  • npm version major Increase 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.