Origin is FreeAgent’s internal CSS framework. We’re a growing team working across a range of different projects and codebases, and making CSS work at scale is hard. Agreed principles, approaches, and patterns mean we can do better work faster. That’s what Origin gives us.

Origin consumes our CSS utilities and provides some global UI components. It also documents our principles and HTML & CSS code style. We use it in our desktop app, mobile apps, website, and a bunch of other projects.

Read the Origin documentation to learn more.

• Install
• Structure
  • Documentation
  • Publishing
• Implementing Origin into a project
• Development
  • Developing ideas locally
• Contributing
• License

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

Requirements: Ruby, Bundler, Node.js and npm

$ git clone git@github.com:fac/origin.git
$ cd origin
$ bundle install
$ bower install
$ npm install
$ npm install -g grunt-cli

Then start a local Jekyll server:

$ jekyll serve

Visit http://localhost:4000/origin/ in your browser — note /origin/.

You may need to run bundle exec jekyll serve depending on which version of Ruby the gems were installed to on your machine.

The /origin/ path is required to view the documentation locally, because when the documentation is published to GitHub Pages it 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.

Very little of this repository is actually part of the origin-css npm package. Only:

.
├── assets
|   ├── fonts
|   └── scss
├── LICENSE.md
├── package.json
└── README.md

These are the only files needed to implement Origin in a project, so that’s all npm needs to know about. .npmignore defines what’s hidden from npm in the same way a .gitignore file does.

If you want to make changes to Origin, it’s these files you want to change. The rest of the repository is dedicated to the documentation.

Origin’s documentation is built with Jekyll and Grunt. It can be run locally, and is published to http://fac.github.io/origin/ via the gh-pages branch.

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

Here’s where things get a bit inception-y: Origin’s documentation uses Origin to document Origin.

The /docs/assets directory contains many of the same files as the root /assets directory (the one included in the npm package). In this sense, the Origin docs are a good example of how you might implement Origin into a project.

But the real purpose of the docs (aside from the obvious) is to give us a sandbox for trying new ideas and approaches before considering them for deployment. It’s our “kitchen sink” view of utilities and components.

Use the included Grunt task to generate and publish Origin’s docs to the gh-pages branch.

$ grunt publish

This takes the _site directory, generates it's 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.

These instructions assume you’re implementing Origin into a new or existing project. Origin is installed via npm, and assumes your project already has mechanisms in place for compiling Sass.

Requirements: Node.js and npm.

$ cd <your-project-directory>
$ npm install origin-css --save

This will add the Origin files to a new /origin-css directory inside the /node_modules directory at the root of your project, and save origin-css as a dependency in your package.json file. If npm isn’t yet being used in your project, running the above command will create the /node_modules directory too. You’ll want to create a package to manage your npm dependencies.

After installing, do the following:

1. Copy the contents of /origin-css/assets/scss/local to your project’s stylesheet directory. Just the contents, not the directory itself.
2. 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 the global Sass partials if the location of your stylesheets directory isn’t the standard Rails app/assets/stylesheets.

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.

As mentioned above, Origin’s documentation uses Origin. The /docs directory is the place to experiment with new ideas before considering adding any of them to the root /assets directory.

It’s also possible to try out new ideas for Origin in any other projects where it’s implemented. npm provides a way to point to your local version of Origin instead of referencing the one installed by npm. This means you could, for example, trial changing the background-color of a button in Origin and see the effect it has in your app without actually having to push a new version of the Origin package to npm.

How to symlink a package folder

All team members should be contributing back to this repo in order to improve it. The process:

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 <your-branch-name>) and make your changes
3. Increment the version numbers in _config.yml and package.json. Generally: backwards-compatible fixes and smaller amendments to existing code are patches, new components and 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
5. 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>
6. Push up the new version of master (git push origin master).
7. Create a new release with a useful description. If you’re making breaking changes, provide guidance in the release notes about what people will have to change in their projects (e.g. “rename instances of u-padding--none to u-padding--0”)
8. Update 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.
9. Consider updating Origin in projects that should receive these updates.

In addition, please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

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.

Origin is based on a fork of Primer, created by and copyright of GitHub, Inc. Released under the MIT license.