Britannica Style Guide

Setting up your local machine

1. Install git and node
2. Open a Terminal
3. cd into whatever your project directory is
4. Pull down a copy of the project to your local machine: git clone [email protected]:britannica/institutional-styleguide.git
5. Change directory into the style guide project: cd institutional-styleguide
6. Install project dependencies: npm install

Running locally

1. Open up a couple of Terminal tabs/windows (Ctrl + T)
2. Change directory into the style guide project: cd institutional-styleguide
3. npm start in one tab (Ctrl + C to shut down the server)
4. npm run watch in the other tab (Ctrl + C to stop watching files)
5. Navigate to http://localhost:3000 in your browser

Making changes

Open any .scss file within the src directory in a text editor of your choice. Atom is a popular, free one. We use LivingCSS to generate our style guide, so I would recommend checking out their documentation for full instructions on how to edit the CSS files.

There are essentially 4 different parts to edit within the CSS file:

1. The description of the component, which is the stuff in the comments above the @example part
2. The @example in the comments
3. Configuration of the @section and @page
4. The actual implementation of the styles

Developers will focus on the @example, and the implementation details of the component.

Product and UX will focus on writing the description using Markdown.

Example

/**
 * Fancy component
 *
 * This is the section that product and ux will maintain. The first line, in this case "Fancy Component", will be used as
 * the `@section` name.
 *
 * ### This is an `<h3>` using Markdown
 *
 * The description will end here since the next part is the `@example`.
 *
 * @example
 * <button class="example-component">Example</button>
 *
 * @section
 * @page Atoms
 */

.example-component {
    /* implementation details */
}

Building a new version of the style guide

With the npm run watch task running, every time you save changes to .scss files, a new guide will be generated.

If you want to manually rebuild the style guide, you can run the following task:

npm run guide:build

Publishing a new version of the style guide

After you've verified your changes, it's time to commit and push them back to the GitHub repo.

If you're using GitHub Desktop (recommended for non-developers):

• See their documentation on Committing and reviewing changes to your project

If you're using git:

1. git commit -am "A description of the changes you made"
2. If this is the first push, you'll need to set the upstream branch: git push -u origin master
3. On every subsequent push: git push origin master

Including the style guide in a project

Within your project, run:

npm install --save @britannica/institutional-styleguide

More docs to come...