README

AXA Switzerland Web Style Guide

Guides you through our design principles and helps you build web apps faster!

Intro

This project guides you on how to design and build web apps @ AXA Switzerland. Here you get all the CSS, icons, JS and additional assets to simplify the development of our web apps.

Use it!

Want to use the Web Style Guide in your web app? There are different ways of integration, but the preferred one is to add it as an npm dependency:

$ npm install @axa-ch/style-guide

After that, include the styles from the dist folder into your scss file:

// app.scss
@import 'scss/normalize';
@import 'scss/style';

Or just consume the precompiled css files, also from the dist folder:

<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/style.css">

If you don't want to reimplement the interactivity of our components, just use our jQuery plugins:

<script src="jquery/axa-wsg.jquery.all.js"></script>

You'll additionally need to copy the images folder into your project.

If you don't want to use npm to include the style guide, you might download the latests release package from our GitHub releases page. We're also working on a bower distribution.

Versioning

As a project that is depended on from several apps, we take versioning seriously!

We do versioning using the Semantic Versioning 2.0.0 specification. A typical version number has the format of MAJOR.MINOR.PATCH.

MAJOR changes when we make incompatible API changes
MINOR changes when we add functionality in a backwards-compatible manner
PATCH changes when we make backwards-compatible bug fixes

But keep in mind that as long as we run in 0.y.z, anything can break at any time. This is called Initial Development.

Build it yourself!

Do you want to add an exciting new feature or fix a bug? For that you'll need to build the Web Style Guide yourself, so you can make sure things work. In order to do that, it's required that you have node with npm installed on your system, whether it's Windows, Linux or Mac OS X. With Git installed you'll be able to deploy a new version of the docs.

After you've successfully cloned the project and stepped into it, download the dependencies.

# Install the dependencies
$ npm install

With the dependencies in place, you're now able to run one of the many build tasks we provide for you. Using the dev task you can build the assets, run the showcase and let it refresh your browser on each change in the file system.

# Start development mode (afterwards check http://localhost:3000)
$ npm run dev

But but but.... Enterprise Proxy?

If you're working on a heavily guarded machine as used by many enterprises, follow our Enterprise Proxy Guide.

What do we build it with?

In order to make changes as easy as possible and simplify our build process, we make use of many different technologies. It's great to have an understanding for what these do, when you decide to dive deeper into the code.

Sass for mixins, variables and other fancy styling helpers
Babel for readable and extended scripts based on cutting edge standards (ES6, ES7)
SVG for colorful and sometimes animated icons
Metalsmith for our static site documentation
Webpack for bundling JS, CSS and SVG icons
Pug which simplifies how we write markup
Markdown for text-heavy documentation pages

Feedback

We love feedback! File an issue and we'll reach out to you.

Contributing

Do not hesitate, we appreciate every contribution. Do not fear non-perfect Pull Requests, nobody is perfect.

When contributing please stick to the following guides:

Branching

Please add every feature/bugfix in a separate branch and create a pull request to the master branch.

We stick to the following naming conventions for branches:

feature/... for new features
bugfix/... for bugfixes
improvement/... for improvements on existing features

Commit messages

Begin you commit message with a verb in the imperative. (e.g. Introduce foo bar, Fix baz, ...)
Try to have small, atomic commits.
First line of a commit message should sum up your changes and should not be longer than 50 characters.
Second line should be empty
Third and following lines can optionally contain a longer description

Code Style Guidelines

Rule number one: Consistency is key; So when you contribute follow the code style patterns you see in the code you're changing.

For SCSS code, we stick to the guidelines formulated by @mdo. Take a look at http://codeguide.co/#css.

Who's behind it?

The project is developed by UX, design and IT people at AXA Switzerland. Check the collaborators list for the people behind it.

@axa-ch/style-guide

Usage no npm install needed!