This post is part of a blog series on how we approach design at Atlassian. Find the other posts in this series under the Design tag.
We internally released the new product design language in June 2012.
Our design team had worked hard on a unified design vision for our products. What we hadn’t worked out was how we’d be able to communicate all the decisions we’d made to the wider company and add-on developers for implementation across our product suite.
We searched for similar situations in other companies and came up almost empty handed. Of course, frameworks like Bootstrap, Zurb foundation, and Ratchet, were already out there and very popular. Our problem wasn’t that we needed a UI framework, since we already had one of our own, but that we needed a method to communicate the design transition within Atlassian.
After watching a talk about how Google had transformed its design, we were inspired to create our own design guidelines. Google’s three main points were:
- Make it in code
- Make it so easy to use that it’s harder to not follow it
- Have a deadline
Atlassian User Interface (AUI)
AUI is the open-source UI framework we’ve used for a number of years to drive the experience of our products. The library of UI controls was previously only available via a products plugin system so it was almost hidden from designers. With a little bit of work, the AUI team was able to export a flatpack version of AUI for anyone to hack with.
Traditionally being engineering led, AUI didn’t have a lot of design input from its inception. Removing the technical barrier enabled the design team to start hacking around in code to make the experience consistent and build on the existing library. Having shiny new controls to show off instantly raised some questions. Where should we put things? What are the rules around when to use tabs instead of horizontal navigation? What blue do I use for links?
We knew that just using a UI framework was never going to be enough. We practice Agile and Lean UX here at Atlassian and one of the key principles of lean is to reduce waste. We would never advocate skipping the design process, but there is great value in reducing the waste of solving the same problem multiple times.
We believe that if the interaction models and patterns from our products are unified, we’d not only give the people using our products some consistency, the designers would be able to work collaboratively with the product teams to focus on customer needs, flow, structure and the bigger interaction problems. The Atlassian Design Guidelines (ADG) is our answer for the design implementation that achieves a consistent user experience for our products.
Documenting your decisions
We started documenting our design decisions in Confluence but didn’t want to use screenshots because they changed too quickly to make adding new images after every iteration feasible. The first few controls we documented ended up being coded in the exported flatpack from AUI and collaborated on via a Git repository on Bitbucket. We would then iframe the working examples into Confluence with the supporting documentation.
That Git repository could be accessed by the whole company. You could start hacking away on the styling and behaviour of a control by just copying a specific folder set up in the repository. 100% access and no process. It was a maintenance nightmare, both in code and in Confluence. We knew that this approach wasn’t going to work long term, but the decisions we came to from this chaos were invaluable.
One of the biggest challenges was feeding the changes the design team made back into the engine driving our products. Traditionally, the individual products would override a style coming from the AUI library to maintain bespoke styles in the individual products. We were doing a similar thing with the flatpack, causing the source of truth to become an ongoing struggle.
We ultimately needed one source of truth: the ADG (powered by AUI).
Not every designer can code
The design team is distributed across all products and locations within Atlassian, so we had to make time away from our regular product work to contribute. One of the keys to working on the ADG in a distributed design team is that a design solution needs to work for all our products, not just one specific use case. It’s very important to establish areas of responsibility; otherwise we’d end up with four variations of our buttons with the new design language.
In the beginning, the team struggled to contribute. We forced ourselves to use Bitbucket, Jira, Greenhopper and Confluence. We raised issues on Jira to track our bugs and tasks, organised ourselves with Greenhopper (trying out both Kanban and Agile approaches at different stages), and used Git, accepting contributions via pull requests on Bitbucket. It exposed the team to our software suite in order to build a better version of our software.
By doing this, we learned that the distributed team model works well as long as you have someone in a maintainer role. This person needs to maintain the code base, accept pull requests, sort through the backlog of issues to prioritise the workload and generally make sure things are released on time and documented correctly.
Building the guidelines
We believe that a good understanding of the medium you’re designing for is key for every designer. Our goal was to move out of (or skip) Photoshop as quickly as possible to refine the details in code.
Embracing the medium meant we had to build out the design guidelines in flat HTML/CSS using the AUI flatpack as the base. It was important to lower the barrier for entry so that designers could contribute immediately. If there were any hiccups with using a templating system of any kind, it would stop people from being able to do their jobs.
The ADG started taking shape during a ShipIt event in the Sydney office. I coded up the structure and fleshed out a dozen of the controls to get a feel for how we should proceed. I made a conscious decision to initially not use any templating technology so there were no excuses for designers to not contribute if they had HTML/CSS skills.
We believed that having a dedicated team isolates the initiative from the rest of the company. We had to be pragmatic about keeping the ADG moving and use a two-phased approach to ensure that.
Once a month, the whole team would gather together and work on the ADG. Everyone was present to answer questions and to keep things moving. It was high output, getting many new patterns to 80% completion in a short amount of time. We’d then spend the next week or so dedicating small amounts of time to refine a pattern and get the guidelines and code up to scratch to include in the ADG.
Like every product we needed a deadline to launch the ADG. The deadline was Atlascamp, which at the time was about two months. In hindsight, it was probably too aggressive but without it we wouldn’t have shipped. The initial feedback from the event was positive but like everything in design, it was nowhere near done.
Improving the engine
The process of sketching, coding, polishing, pull requesting, and commenting helped us to continuously improve not only our guidelines, but also our process.
Since the team had become comfortable with using Git and coding their own pages together for the ADG, I decided to move away from static files and use Jekyll templates. It’s been great using this little technology with the short learning curve for the team.
We have iterated and adapted as we’ve built these guidelines. We’re continuing to create more patterns and build the ADG so we’re confident a designer or developer can reference it to build a great Atlassian experience. We’ll be versioning the ADG with detailed change logs so developers will be able to build a plugin or Atlassian product against a particular version of the ADG.
Releasing the ADG to the public was a big milestone for us. We will follow the same approach as for developing the 1.0 going forward – continuously enriching and improving the guidelines and the process, as a team.