Our new home for Atlassian Design System

Atlassian Ecosystem Design Ecosystem Design Announcements
, ,
1

You may have noticed a major change to the Atlassian.design and Atlaskit (AK) websites. What was previously our home for Atlassian Design Guidelines (ADG) has now transformed into our new home for Atlassian Design System.

ads-hero
ads-hero732×384 45 KB

We’re excited to share with the community some of our favorite new features:

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 we were 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. The new site is faster, more reliable, and aligns with Atlassian platform standards. As a platform team, investing in our infrastructure will help us in the future 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!

What else is new?

As with all large-scale design systems and companies, there were some difficult decisions and changes that we had to make, which is necessary for Atlassian to grow and scale as an organization. We know that these decisions could have been communicated better at the time, and we’re sorry about that. We’re working with the Developer Experience team to do better on this front going forward.

Migrating from Sketch to Figma

We are no longer using Sketch as our primary design tool, as the Atlassian design team has migrated to Figma. Thus, the Sketch library has been deprecated and is no longer supported. You can find our design system foundations, components, and patterns available in our Figma libraries.

Atlaskit repository is private

As of January 2020, the repository for Atlaskit was made private to support the inclusion of Atlassian’s private front-end code. This also means that contributions are closed for now. Not to worry though, our public libraries such as Atlassian Design System, Atlassian Editor, and Atlassian Media can be used via npm packages as before, and a public mirror of the source code is available. Read more about this in the Atlaskit getting started guide.

Atlassian-only guides

Previously, a lot of developer “how-to” guides lived publicly on Atlaskit, which were intended for usage by internal Atlassian developers only. This created a source of confusion for external developers, so these misleading guides have been migrated to a private place. (This is separate from the component documentation which is still available on the Atlaskit website).

Where should I go for help?

If you have questions or issues related to the new site, feel free to leave a message here in this thread.

If you want to report a bug or suggest a feature, please start a discussion thread on the Atlassian Developer Community forums (in the Ecosystem Design category). We will monitor the forums and ensure they are addressed by the appropriate maintainers.

What’s next?

The launch of atlassian.design is just the first step in creating a single destination for our documentation and is a big part of our ongoing investment to improve Atlassian Design System.

A few more things we’re excited about:

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

We hope all of these changes make your experience designing and building experiences at Atlassian so much better. Please let us know what you think!

:heart: Atlassian Design System Team

10 Likes
2

Hi @jsyip, since @kmorales closed the last thread, I figured I would try to carry over some of the opens questions that Atlassian has been seemingly ignoring for months now. Can you (or anyone else on the Atlassian side) please clarify some of the items below:

@ngault asked the following (in the closed thread):

  1. What exactly is being delivered in the form of code? Does Atlassian intend to provide, as it did prior to Jan 2, 2020, all of the Atlaskit components in source version? (Currently, about 30% of the source is missing, including components that are dependencies of other key components.) And will the system take a form enabling partners to incorporate it in a commercial-grade CI/CD system? (This stopped being the case in early January).

  2. What is the timeline? @stephenmok 's posts in prior threads have continued in the same vein we’ve seen for the last 6 months, ‘i.e., we can only tell you that we’ve been really busy, but we should be able to tell you more sometime in the future.’ Keep in mind we’ve been told “real soon now” since early January.

To be clear, the concern from the community isn’t about the quality or features of Atlaskit. Rather, we just want to know when (or whether) we can count on Atlaskit as safe to build our businesses on.

@stephenmok posted things Atlassian is working on in this thread on June 19.

… I’ll have more to share about the Design System roadmap after that is finalised.

In the meantime, here are key pieces we’re working on right now…

Specifically with the community in mind:

  • Preparing to move our public repository (the mirror) from Bitbucket to GitHub, where it will be available alongside other Atlassian open-source projects
  • Renewed investigation into whether we can change the licensing for icons to a more permissive license

Clearly, it looks like the design system roadmap is done, as you’ve started pushing out the new design system. Could you thus please provide answers to:

  • Is the move to GitHub done? If so, could you please share the links to the repos.
  • Is there an ETA on getting an answer about license changes for icons?
10 Likes
3

As of January 2020, the repository for Atlaskit was made private.

Wait, Atlaskit is out of commission? Was it deprecated before? I’ve just built a product based on AtlasKit, should I have used something else? What the hell are we supposed to build apps with???

We need clearer answers from Atlassian, you’ve already dodged answering last year. Are we supposed to build our own toolkit that looks like Atlassian’s ADG?

2 Likes
4

If you are looking for non-React alternatives to Atlaskit, here is one of them: GitHub - spartez/vue-atlaskit: https://spartez.github.io/vue-atlaskit, it’s Vue.js based, and it is actively maintained.

4 Likes
5

Wait, Atlaskit is out of commission? Was it deprecated before? I’ve just built a product based on AtlasKit, should I have used something else? What the hell are we supposed to build apps with???

Hi - Atlaskit is still actively developed, maintained, and being invested in! Internally Atlassian has been using the repository of Atlaskit (now named Atlassian Frontend) to house more than a component library, but many front end packages. Some of which are private code, and some are public.

Looking at the homepage for getting started (here: Atlaskit by Atlassian) there is a link to the public mirror if you need to see the source code of the public packages inside Atlassian Frontend (here: https://bitbucket.org/atlassian/design-system-mirror/src/master/) :pray:

If you need help or have found a bug, or want to request a new feature, please start a thread here: Atlassian Ecosystem Design - The Atlassian Developer Community and we’ll jump in :slight_smile: .

1 Like
6

@douges , thanks very much for the response. Respectfully, I’d say you’ve missed the context. And you have not answered the pressing questions that @ademoss asks above, which are the same persistently asked questions that have gone unanswered for the last 8 months.

In early January, 2020, AtlasKit stopped being what it had been since its inception, about, IIRC, 5 years ago: an entirely open source project, with all of it publicly available. When Atlassian promoted it to the community, as anybody would expect, was that it would always stay open source and available. That commitment has apparently been forgotten.

In early January, the source code for large portions of AtlasKit, some of the modules with thousands of daily NPM installs, disappeared. These were not exclusively “in-house” modules. Many of them are dependencies to other widely used modules. The AtlasKit team members promised continually for several months that the source code and project would soon be completely restored. That has not happened, even as many of us wasted much time and money coping.

When you say that some of the AtlasKit are components are “private code”, that is the first time this has been stated publicly. (In fact, I’d venture that it’s been flatly denied, but that may a matter of semantics). The fear that the disappearing AtlasKit modules had become permanently “private” is exactly why we have so persistently asked about this since early January. Hopefully, this is not happening.

You say that AtlasKit is alive and well, but perhaps that may now apply only to consumers inside Atlassian, not to its developers? If AtlasKit is going to be used outside of Atlassian, these requirements will have to be met:

  1. Your open source components cannot have as dependencies non-open source components. (For example, several components in the design-system-mirror rely on components like locale, which recently became “private”.). That’s a non-starter for GitHub and a significant portion of 3rd party devs.
  2. Your open source components cannot have as devDependencies your “private”, internal CI/CD components. At the same time, you have to provide working tooling.
  3. You must commit publicly that existing open source components will never be taken “private” in the future. You only lose your open source virginity once. To that end, don’t retire/deprecate existing open source components and replace them with “private” components, as appears to be happening with the complete set of navigation components.
  4. Don’t promote to AtlasKit consumers new “private” components without informing us that they won’t be open source, as appears to be happening with, for example, atlassian-navigation and side-navigation.

Everybody here hopes for a successful future for AtlasKit.

5 Likes
7

In early January, 2020, AtlasKit stopped being what it had been since its inception, about, IIRC, 5 years ago: an entirely open source project, with all of it publicly available. When Atlassian promoted it to the community, as anybody would expect, was that it would always stay open source and available. That commitment has apparently been forgotten.

In early January, the source code for large portions of AtlasKit, some of the modules with thousands of daily NPM installs, disappeared. These were not exclusively “in-house” modules. Many of them are dependencies to other widely used modules. The AtlasKit team members promised continually for several months that the source code and project would soon be completely restored. That has not happened, even as many of us wasted much time and money coping.

I’ll follow up during the next work week to escalate getting the remainder public packages added to the mirror.

When you say that some of the Atlaskit are components are “private code”, that is the first time this has been stated publicly.

Sorry let me clarify. There is new code/packages added to the repository (previously named Atlaskit, now Atlassian Frontend) - that is private. This is all semantics but to be as clear as I can - previously public packages have not transitioned to private packages. And they are all still publicly available on NPM.

Your open source components cannot have as dependencies non-open source components. … locale , which recently became “private”

I will follow up and add get it added to the mirror (including the new navigation packages). From my understanding anything under @atlaskit org should be public (which - it is on NPM - just some seem to be missing in the mirror currently).

You must commit publicly that existing open source components will never be taken “private” in the future.

I agree and I’ll pass this message on. I’m sorry for how the transition went and I’ll keep pushing for us to do better

Thanks for caring, I appreciate you taking the time to post.

6 Likes
8

@douges , thanks so much for the fast and thorough response! The commitments you make here would represent enormous progress. I’d like to add a couple of critical issues for your consideration.

  1. Some folk at Atlassian seem to be confusing themselves with their use of the word “public”. Being “public” and not “open source” is what developers call “private”. When you say the missing AtlasKit components have remained “public” on NPM (which is NOT true, by the way, but let’s go with it for sake of discussion), that defies the definition of “public” used by external consumers. Anyway, inconsistent use of “public” seems to be causing a lot of problem. The solution is to start using “open source” instead.

(One source of confusion is that the Apache v2 license doesn’t require the licensor provide source code, so you can comply without being “open source” or “public”.)

  1. Beyond the components, there is the rest of the Atlaskit project. If Atlassian is sincere in honoring its original promise that AtlasKit would always remain Open Source, then the entire project, including the build system, should also be restored. Atlassian promoted the build system in all presentations, including in the “Getting Started” docs that were removed in January, and many of us had relied on it. In removing the build system, along with its various internal dependencies, as has been done, the test and build code in each of the existing modules is effectively useless to external consumers.

My larger point, which you definitely seem to appreciate, is that a public commitment to Open Source, as Atlassian the company has made over and again since its founding, is absolute. We’ve operated in a bubble on these forums for the past 8 months, so little harm has been done. But you can’t go to GitHub without reconfirming the same commitment.

5 Likes
9

Hi folks,

Thanks for bringing up these issues again! We’re currently working together behind the scenes on how to address your questions and concerns. We realise this is taking longer than expected — Atlaskit is an umbrella for the work of multiple teams at Atlassian, and we’re trying to paint you a full picture. Thanks for your patience!

We are collating all your questions and will post a new FAQ once we have the answers. We’ll keep that updated over time. We want to make sure we’re not missing anything, so two questions for you too:

  1. Which components specifically do you rely on?
  2. In addition to npm packages, how do you currently consume them?

Quick updates to the more straightforward bits:

  • We’ve heard your feedback about how moving the repository to GitHub needs to be carefully considered. We’re putting the move on hold, and will continue updating the existing mirror repo on Bitbucket.
  • It was an oversight that the Navigation components (horizontal and side navigation) were left out of the mirror repo since they are in a separate /navigation folder. We’ll add them. You can upgrade to them and rely on them.
  • Good news on the license changes for icons! We just received confirmation that we are able to change the license to Apache 2.0. This will all be official shortly, once we update the license in the repo itself.
  • The “What’s next?” section above covers new items on the Design System roadmap since I last wrote about what we’re focused on. The docs website mentioned is the newly-launched atlassian.design, and the per-component performance improvement work is still our top priority right now. That will continue for many months to come.

Again, we hear that you have questions about private vs. public components, how we share the code, etc. We will address those. The underlying investment in Atlaskit and the Atlassian Design System that we wrote about a few months ago continues unchanged — it’s not going away!

Cheers,
Stephen

2 Likes
11

In addition to npm packages, how do you currently consume them?

@stephenmok , judging from this statement, I’ll assume that you are unaware that there has been no other way to “consume” Atlaskit components for 8 months other than to install their “built” versions by npm. I’ll try to explain, but any member of your team will be able to do a much better job. Here goes…

It has not been possible to build or test any Atlaskit component for 8 months, the time at which you removed access to the Atlaskit build system. In order to do anything but eyeball the files in the current design-system-mirror, a developer needs to be able to install the dependencies for a component.
Try doing a yarn install on any Atlaskit component. The command will fail because a large numbers of dependencies required by any/all of the components are no longer public. It’s good that you’ve spared yourself the response of the GitHub community to this phenomenon.

I hope that this helps to better explain what developers have been saying for so long: the design-sytem-mirror without the build system serves little useful purpose. The mirror doesn’t ship with the “built” versions used for npm distribution, nor can it build those versions. Beyond the mirror, your team IS providing two things of value: the built npm versions of the components and the venerable documentation/examples site that shows how to use these.

Generally speaking, enterprise customers will only use software that enables important problems to be fixed promptly. This means that the software will come in one of two forms: either, one, licensed for a fee with a support agreement (as witih most Atlassian products), or, two, fully open source, so that they can fix those problems by the enterprise itself in urgent circumstances. Atlaskit currently falls in neither category, so it can’t be used by such customers. In our team’s case, working with Atlassian customers in US financial services and healthcare, Atlaskit is no longer an option.

Years ago, Atlassian introduced and promoted Atlaskit to the community with these requirements in mind. The company has every right to change course, but, if doing so, it should first restore the build system and access to all dependencies with a reasonable deprecation period of, say, one year.

1 Like
12

Hello @douges and @stephenmok , it’s been exactly 6 weeks since @douges said, above, that important missing packages would be moved to the mirror and exactly 4 weeks since @stephenmok said that it was an oversight that these were missing and this would be corrected immediately.

Several of us have been eagerly waiting and would be most grateful for an update. Thanks!

13

@ngault This work is currently in progress. We should have this done in the next week if everything goes according to plan. Thanks for your patience.

1 Like
14

@jcheung Thank you.

15

We’ve now made the repository changes to include the source for all public @atlaskit packages. Again, thanks for your patience!

Details here: New expanded mirror repository including source for all public Atlaskit packages

(Please note you will need to update your remote URLs — details in that topic.)

2 Likes