Citizens Advice Design System
Table of contents
We've made it pretty simple to get up and running with the latest Citizens Advice Design System framework. We use
npm to allow you to bring the framework into your projects.
In order to get the framework make sure you're in your projects root directory:
$ cd project/directory
$ npm install cadesignsystem
If you check in your
node_modules directory you should now have a
cadesignsystem module that contains a few key files and folders.
node_modules └── cadesignsystem ├── dist │ ├── css │ └── images └── scss
The first directory will be the
dist folder that contains both minified and un-minified versions of the entire framework. We added this just for convenience.
dist folder also contains an
images directory that should contain all images required for the framework.
Finally we have the meat of the framework. In the
scss folder, you'll find all the source files that will get compiled using
sass. This directory has a set structure which makes use of the ideas of "ITCSS", an methodology from Harry Roberts. Let's take a look at this structure and concept:
||global variables, config switches|
||default mixins and functions|
||ground-zero styles (Normalize.css, resets, box-sizing)|
||unclassed HTML elements (type selectors)|
||cosmetic-free design patterns|
||designed components, chunks of UI|
||helpers and overrides (it's ok to use
Now that you've
npm install the framework into your
node_modules, you'll need to link to it like you would any other
scss file. We've purposely left this step missing from the documentation because each project and build step may be setup slightly differently and we don't want to pin you down to one method.
NOTE: Don't forget to grab the
images/media files during this build step too, it's easy to overlook these.
So you'd like to get the documentation up and running on your machine? There are a few things we need to take care of first. Once you're confident you have your environment setup, move onto the Setup Documentation section.
You need to have the following installed on your machine:
- node.js (we recommend installing via NVM)
- git (we recommend using Homebrew)
- ruby (we recommend installing via RVM)
Navigate to the repo and
clone it by running either (it depends on how your security is setup).
$ git clone email@example.com:btomy/ca-designsystem.git
$ git clone https://github.com/btomy/ca-designsystem.git
Great you have the repository on your machine now.
cd into the
ca-designsystem directory (the
root), and continue to install our projects
$ npm install
We run the documentation site on the Jekyll platform, so you'll need to install it's dependencies too. You can do that by running:
$ bundle install
Start the docs site
When all the above is complete, we can get the docs up and running by running:
$ npm run start
This will start Jekyll, compile the stylesheets and create a watcher for changes to those assets.
Now if you open a browser window at
http://localhost:4000 you should see the homepage.
This is a great area with which to start developing new features and components and to test them out.
The files are located in the
root of the repo under the directory
Most of the hard work has already been taken care of by following the Documentation guide, installing all necessary dependencies in order to run the sandbox.
Starting the sandbox
$ npm run start-sandbox
and navigate to
http://localhost:5000, you should see a very basic page with a heading. This area is completely at the developers disposal.
You will find:
If you need more pages, you can create them, if you need to add images or styles you can do that too in the
assets/scss/ directories respectively. Manage this area as you see fit, any
compile commands can be found in the
package.json should you need them.
How to contribute
Anybody and everybody is welcome to get involved in contributing to the framework, but in order to stop it from becoming bloated, we usually only consider adding new components to the framework when one is being used on more than one application, site or service.
- Create a new branch making sure you adhere to the git style guidelines.
- Use the sandbox to start hacking away at your new feature / fix.
- If you're fixing the
framework, make sure to make
CSSchanges in the
scss/directory as these are the framework source files.
- next create a pull request where upon some discussion around the PR will happen.
Git style guide
This section may sound rather prescriptive, but in order to keep things easy to manage, let's try to stick to some conventions around branch names, and commit messages
$ git checkout -b [issue-type]/[issue-number]-[issue-title]
$ git checkout -b docs/71-refactor-readme-content
Another developer can see exactly what this is from the branch name, which issue / PR it relates to and the type of change it is, all without having to look at the log.
[issue-type] [issue-number]: Brief description of commitA longer description, perhaps also listing out the solution orany other relevant detail
Again, an example would be...
Docs #71: Refactor repo READMERewrite the repo README to include setup information around the framework.[#71]
You'll make many different types of change to the codebase over time but most changes can be categorised under one of the following types. Make use of one of these when writing your commit messages.
||a new feature|
||a bug fix|
||changes to documentation|
||formatting, missing semi colons, etc; no code change|
||refactoring production code|
||adding tests, refactoring test; no production code change|
||updating build tasks, package manager configs, etc; no production code change|
While this might feel overkill to dictate how to write commit messages, doing so also means when reviewing Pull Requests, we can quickly see which commit belongs to which ticket without having to match up commit messages to ticket titles.