When we create an add-on for one of the Atlassian products, we want to create an experience that feels integrated into the Atlassian platform. This is why we’ve decided to as stay close to the Atlassian style guide, also known as AUI, as possible. We’re glad we made this decision as we think it provides the best experience to our users and we’re not going to change our tactics anytime soon. But we have experienced that this is not always an easy path to follow.

AUI constantly evolves

There are several reasons why it’s not easy to build add-ons that follow the Atlassian style guide. One of them is that this style guide is not a finished product. As Atlassian is always working on improving the user interface of their platform, the style guide is a living product that always changes and evolves. This is definitely a good thing as the world is constantly changing and Atlassian is constantly learning from their users.

If you’re an add-on seller and want to offer your users a great experience, this will have some consequences though. When the platform changes, you need to make sure that you change with it. It might feel like a burden to keep up with this but keep in mind that it’s beneficial for you when the platform’s quality is improved. After all, we want the platform to maintain a healthy user base.

Our advice for dealing with this is to embrace change. Make sure that the whole team is on the same page here and make sure that everyone understands that change is a good thing. It is work. And sometimes it’s annoying because there are so many projects to work on. But Atlassian products are always improving and you need to make sure that you want to change with them.

Not everything is documented

Another reason why building add-ons that follow AUI closely is not always easy, is that not everything is documented (yet). Of course it’s impossible to document every little bit in a style guide and I don’t expect anyone to do that. But every now and then I run into an issue where I want to add an element or flow that I can’t find in AUI.

This is where we go beyond AUI to see how we can implement the element in a way that it would fit in the platform. We do this by reading up on Atlassian news, blogs, presentations and by attending events such as AtlasCamp. We make sure that we know everything there is to know about Atlassian and their products. This might sound like it’s a lot of work, but this is not something you have to do by yourself. We have several people working on Atlassian add-ons and we have a team of Atlassian Experts. The only thing we need to do is share the knowledge that we think is useful for the team.

Another great resource for the design language is, of course, the Atlassian products themselves. Investigate how Atlassian tackles design issues or implements certain UI elements and interaction flows in their products. Even if you don’t use all of the products yourself, open them some times and see how they work.

Atlassian updates their products in phases

When you look into Atlassian products for design inspiration or guidance, be aware that these products are not always completely up-to-date. I don’t have any inside information about Atlassian’s way of working, but from what I noticed, I do think that they update their products in phases.

A while back, for example, I noticed that Stash had a new sidebar design. But the Jira and Confluence sidebar hadn’t been updated and still showed the old sidebar. As far as I could tell (and yes, I definitely could be wrong), this didn’t mean that the whole Stash UI was updated to the newest version.

So if you’re looking at Atlassian products, which you really should do a lot, then be aware that you’re not looking at outdated parts of their UI. It’s not always clear what parts are new, but if you compare the UI to other resources, you’ll definitely recognise parts that you can use as guidance.

I knew that the sidebar in Stash was going to be implemented across all products as I had seen it in an online video of an AtlasCamp presentation of last year. But I noticed that the design had already changed quite a bit since the presentation. This leads me back to my first point, AUI is going to change and you need to change with it.

Wrap-up

If you want to create Atlassian Add-ons that are close to the Atlassian Style Guide, then you and your team will have to embrace change. Not everything is documented in AUI, which is why you need to look beyond the documentation and keep en eye out for everything Atlassian. When you want to learn from Atlassian products, keep in mind that they're not always up to date.

If you'd like to have a look at our Atlassian Add-ons, you can find them in the marketplace.

Our Atlassian Experts team posts interesting Atlassian news on twitter every now and then. If you'd like to follow them, you can find them here: @Avisi_Atlassian. Send them a tweet if you're going to AtlasCamp and want to have a talk with them!