Origin

Origin is FreeAgent’s internal CSS framework. These global principles, patterns, and properties mean we can do better work faster.

View the docs

Origin is comprised of these main bits:

• Utilities: our global design properties and CSS for using them
• Components: building blocks of our interfaces. Self-contained units serving specific functions.
• Guidance: a layer of documentation covering broad principles, specifics of code style, naming conventions, and more.

We use Origin across our desktop app, mobile apps, website, and other projects. This not only helps create a familiar experience for customers, but makes improves our development process.

FreeStyle

FreeStyle is FreeAgent's internal design system.

A design system creates a single point of truth that collates and describes all the elements we work with day-to-day, such as typography, layouts, tone of voice. A design system enables an entire team to work quicker, more consistently, and with more confidence – freeing up time and mind for bigger problems.

Contents

• Install
• Documentation
• Implementing Origin into a project
• Contributing
• Publishing
• License

Install

Following these steps will install Origin and it’s docs locally, and allow you to push documentation changes to GitHub Pages.

If you want to implement Origin into a project and don’t want the documentation, follow these instructions

Prerequisites: Ruby 2.1, Bundler, Node.js

$ git clone [email protected]:fac/origin.git
$ cd origin
$ chruby ruby-2.1.2 (or whatever your non-system version of Ruby is)
$ bundle install
$ npm install
$ npm install -g grunt-cli (if you don’t already have Grunt installed)

Documentation

Origin’s documentation is built with Jekyll and Grunt. How to run it locally:

$ grunt

In a new terminal window, run Browsersync for live reloads, synced up browsing and scrolling:

$ grunt sync

A new browser tab should open automatically to http://localhost:9001/origin/.

Running the docs locally gives us our sandbox for trying new ideas and approaches before considering them for deployment. It’s our “kitchen sink” view of our utilities and components.

Aside from Jekyll’s _config.yml and Grunt’s Gruntfile.js, all files related to documentation live in /docs.

The docs don't run at root because when published to GitHub Pages they lives at /origin. There is an established workaround for this, but it’s not applicable to sites where the Jekyll source is anywhere other than the root directory, and ours lives in /docs.

Implementing Origin into a project

Origin is installed via a gem, and assumes your project already has mechanisms in place for compiling Sass. Originally origin was installed via npm, this is now deprecated and will be removed.

In your Gemfile add the origin dependency and replace x.x.x with the version you wish to install.

gem "origin", "x.x.x", github: "[email protected]:fac/origin.git"

After you have added origin to your Gemfile run:

$ bundle install

After installing, do the following:

1. Copy the contents of assets/scss/local to your project’s stylesheet directory. Just the contents, not the directory itself.

2. Open _utility-settings.scss and set all utility variables to false. These are true by default because the Origin docs use them, but each one left as true will add weight to your output CSS, so only do so when you need them.

3. Starting a new project? Use origin.scss as your master stylesheet, or copy it’s contents into your existing master stylesheet. You’ll need to change the paths to suit your project.

If your project already includes normalize.css, delete it, as Origin already includes it.

Updating Origin within a project

$ bundle update origin

Contributing

Development of Origin happens in our primary branch, master. For stable versions, see the releases page. master will always be up to date with the latest changes, including those which have yet to be released.

All team members should be contributing back to this repo in order to improve it. All HTML and CSS should conform to the style guidelines.

Editor preferences are available in the editor config for easy use in common text editors. Read more and download plugins at http://editorconfig.org.

SCSS Linter

We use SCSS-Lint to catch any formatting or syntax issues with SCSS during development. It’s integrated into our Gruntfile, and will automatically lint .scss as soon as they’re saved.

The linter is configured via .scss-lint.yml.

Working with a local version of Origin

Components that look great in isolation are lovely, but they're much more useful when they fit in where they are used!

You can tell Bundler to use a local version of Origin instead of the published version so you can see changes in another project.

By example, assuming your project is on your machine at dev/project and Origin is on your machine at dev/origin:

Change your project Gemfile as follows:

# project/Gemfile

# Find and comment out the existing reference to origin:
# gem "origin", "x.x.x", github: "[email protected]:fac/origin.git"
# And replace it with
gem "origin", "x.x.x", path: "../origin"

If you're working with a Rails project, you will need to restart your rails server. You can then make changes in your local copy of Origin and see them reflected in the project.

Once you're happy, don't forget to get your changes merged to Origin master and change the project's Gemfile back.

Creating a new component

1. Make sure you're up to date with the master branch (git fetch; git pull origin master)
2. Branch off master (git checkout -b <add-amazing-component>)
3. Create a new .scss partial for your component in assets/scss/global/components and give it a (singular, not plural) name
4. @import your partial into origin.scss
5. Create a new .md file in docs/components that matches your .scss partial name, and document examples of all use cases and variants of your component
6. Test that the component renders as expected in all use cases
7. Bump the version numbers in _config.yml and [package.json] (it'll be a patch: 1.0.x)
8. Create a new pull request and provide a helpful description of what the component does and why its been created

Creating a new release

Branch off, make changes, create a PR

1. Make sure you're up to date with the master branch (git fetch; git pull origin master) and have followed any update instructions contained in release notes
2. Branch off master (git checkout -b <your-branch-name>) and make your changes
3. Increment the version numbers in _config.yml and package.json and version.rb. Generally: new components, backwards-compatible fixes, and smaller amendments to existing code are patches, breaking changes count as minor releases, and full rewrites are major releases. See semver.org for detailed guidance.
4. Push up your changes (git push origin <your-branch-name>) and write a helpful pull request describing your changes

Get your PR reviewed, merge to master, create new release

1. Ask a fellow designer or engineer to review your changes. Make any required changes, then merge your branch into master: git checkout master; git merge --no-ff <your-branch-name>
2. Push up the new version of master (git push origin master).
3. Create a new release with a useful description. Your original PR is probably a good starting point. If you’re making breaking changes, provide guidance in the release notes about what people will have to change in their projects
4. Publish the NPM package (npm publish). If you don't yet have access to update the npm package, have someone in the design team add you as an owner.
5. Publish any documentation changes to http://fac.github.io/origin: grunt publish

Let people know, consider upgrading other projects

If this a major or minor release, let people in the #design and/or #origin Slack channels know by linking to the release. Consider bringing other projects up to date with your new release, especially Origin.

Publishing

Use the included Grunt task to generate and publish Origin’s docs to http://fac.github.io/origin/:

$ grunt publish

This takes the _site directory, generates its own Git repository there, and publishes the contents to the gh-pages branch here on GitHub. Changes are reflected in the hosted docs within a minute or so.

License

Created by and copyright FreeAgent Central Limited. Origin is released under the MIT license. The original documentation format and deployment mechanism of Origin was based on a forked version of Primer, created by and copyright of GitHub, Inc.