Our new home for Atlassian Design System ✨

jennie § yip
Designing Atlassian
6 min readAug 11, 2020

--

An image representing Atlassian Design System

The Atlassian Design System Team is pleased to announce that our new home for Atlassian Design System is now live at atlassian.design! What was previously our home for Atlassian Design Guidelines has now transformed into our new home for Atlassian Design System.

Our design system is evolving

The last time we launched atlassian.design was back in 2017 when our bold new rebrand was introduced. Over the years, many exciting things have developed for us at Atlassian: our organization has grown; the Design System Team officially formed; the tools and technologies that we use to power design and development have shifted; and design systems, in general, have evolved to focus beyond the tangible outputs of our system, to demonstrate that trust, relationships, and operations around creating a design system are just as important as all the design system outputs themselves.

As our design system has evolved, all the fragmentation and inconsistency across the outputs of our design system — Atlassian Design Guidelines (ADG), Atlaskit (AK), Sketch, Figma, and Confluence — have led to a confusing experience for our consumers, which in turn, creates mistrust in our system.

We have a wide range of consumers, that range from internal Atlassians (who design and build Atlassian experiences), to our ecosystem vendors (who build apps that integrate with Atlassian products), to our end customers (internal and external users who use our Atlassian products).

Images of Atlassian.design and Atlaskit.atlassian.com
Our two documentation sites: atlassian.design and atlaskit.atlassian.com

One of the biggest pains for our consumers is the inconsistencies across our two documentation sites. Over time, the sites became more and more out of sync. Nathan Curtis cites Atlassian as a specific example of what not to do when architecting a design system site:

Be wary of a design and code split. While convenient to author and publish early on, long term risks may outweigh benefits. Sibling sites can indicate a corrosive divide between design and engineering, too.

These takeaways are all true. 😅

Feedback from an external audit and multiple customer satisfaction surveys nudged us to combine the Atlassian Design Guidelines and Atlaskit sites, so it was prioritized as a specific area of improvement for us to invest in. Through our research, we set out to improve key user pains, which revolved around:

  • Misalignment between Atlaskit and Atlassian Design Guidelines sites
  • Poor navigation and feature discoverability
  • Documentation not easy to understand
  • Overwhelming Atlaskit code examples
  • Absence of content design guidance
  • Reliance on old specs in Confluence

As our Design System Team weaved content and code together from both sites, we aimed to create a source of truth — for designers, developers, and content designers — through a unified destination that is easy to update, contribute to, and build upon.

Connecting the stars

Over the last year, our cross-disciplinary team has accomplished so much to bring the new design system site to life. It began with extensive audits across our content, design, tooling, and code. We focused on organizing, structuring, and designing our content in an effective and sustainable way, which evolved into various layers of navigation, thoughtful information architecture, scalable content models, and reusable developer tooling. We applied the visual foundations of our design system and reused existing components to design and build the new site, truly putting our design system to the test.

We’re excited to share that we achieved everything we strove for, but more importantly, we’re inspired to share everything we’ve discovered along the way. We uncovered a few larger systemic issues, and there were lots of challenges and hurdles we had to overcome. It has been an immense cross-collaborative effort across brand, design, content design, and engineering, and this would not have been possible without our perseverance to play, as a team (one of our core Atlassian values).

Look forward to a series of blogs around these details, as we reflect upon our learnings from this great journey. First, we’re excited to share with the community some of our favorite new features.

A screenshot of Atlassian.design, our new home for Atlassian Design System
Our new design system documentation site for Atlassian Design System

A few of our favorite things ✨

A source of truth

We understand how unpleasant it is to navigate across two sites to find the right information you need. One of the biggest pains for our users is the inconsistencies across our two documentation sites, so we set out to combine them. We’ve begun this journey by launching a single home for our design system documentation at atlassian.design.

Content first, then design

Content is what users need to achieve their goals, and content is what breathes life into a design. Our team has spent a lot of time brainstorming, prioritizing, and mapping out content to user goals. Only then, were we able to redesign the site with a fresh look and feel, new layers of navigation, and thoughtful information architecture. We’ve re-written documentation and created clear and comprehensive examples for the first 27 (out of 60) design system components, combining the content for designers and developers into a unified experience.

Laying the foundation

Improving the design and content of atlassian.design is just the tip of the iceberg. Beyond the surface of the redesign, our engineers have also rearchitected the foundation of what our site is built upon. We improved our infrastructure with Gatsby, integrating with Contentful. The new site is faster, more reliable, and aligns with Atlassian platform standards. As a platform team, investing in our infrastructure will help us as we continue to scale.

A better user experience

Aside from the new content strategy, redesign, and infrastructure changes, we’ve also made many other improvements to enhance your designer and developer experience:

  • Content in context to where you need it
  • Easy sharing via click-to-copy heading links
  • An improved unified search
  • More visual content to break up long chunks of guidance
  • …and more coming soon!

Cheers!

The team at Atlassian that brought it across the finish line!
Sharing for fun~ the team that brought it across the finish line!

The milestone we’ve reached has been an amazing multi-disciplinary and cross-collaborative effort across multiple Atlassian teammates, in collaboration with the Atlassian Design System Team. Deep appreciation goes to all the team members involved in making this launch happen and for continuing to help us scale design and development at Atlassian.

What’s next?

A common misconception about design systems is that once they’re established, or, in this case, once their documentation is published or site is launched, they become an omnipotent and an unchangeable source of truth. A design system is never complete. This launch is simply the first step of many.

At Atlassian, we’re beginning to shift our perspectives of how we view our design system, as we are slowly bringing it back to life, into a living and breathing entity. We still have a lot of important work to do, and we on the Design System Team are very excited. ✨

A few more things on the horizon:

  • Migration of the remaining 30+ design system components (which still live on Atlaskit for now)
  • Hardening our visual foundations (color, typography, iconography, spacing, and more)
  • Consolidation of content design guidance and standards
  • Making our design system more accessible, usable, and inclusive

We hope all of these changes make your experience designing and building experiences at Atlassian so much better. Please enjoy the new site! ❤️

--

--