I know that the Atlassian ecosystem isn’t really the focus of atlaskit anymore (or if Atlassian really wants to invest into the support for atlaskit to be used by external parties). But here’s hoping that somebody out there is listening.
It would be awesome if we could get the old design guidelines back - especially around the components that we have to recreate in order to use Atlassian Connect (cough cough Modal Dialog).
The current design site is really more targeted for the folks that are using Atlaskit and not for “here’s how”. (we really need the here’s how and the reasoning behind things).
Could you clarify what you mean by old design guidelines? We didn’t remove any of the old design guidelines with the redesign. We actually merged design and developer documentation and guidance into a single location. Our new design system documentation site is not targeted for anything or anyone using “Atlaskit” any longer — we’ve actually expanded our audience to designers, developers, content designers, and more. You can read more about this here: Our new home for Atlassian Design System - #11 by ngault
we’ve actually expanded our audience to designers, developers, content designers, and more.
I think this is actually the main problem. You have lost sight of the one group that probably uses Atlaskit the most, which is the app developers that want to deliver a consistent in-app experience for Cloud and Server apps.
The atlassian.design website is clean, neat and pretty. But it’s not helping out the power users that are catering to our shared customers.
If you want to hear about concrete examples, please bring back the old site and we can show you. I hope you understand that I do not know at heart the content of the old AtlasKit site.
The only thing I do know is that I’m missing a lot of guidance for creating an in-app like experience for my apps that would benefit our mutual customers.
Another one that’s missing btw - Page header. There was a page that discussed the number of buttons in the upper right area.
Things might be there I guess but I doubt it (one of the really nice things of this new site is that it is really easy to find things - and when things aren’t there).
Now all of this might be me misremembering things (I don’t think so though). And with the clear target of design.atlassian.com towards using atlaskit - I really do feel that there’s a large gap of awareness that there are situations where you can’t use atlaskit (especially in connect) and have to recreate things…
I think I need to note - I’m not saying that the old site was better etc. It just had content that was less atlaskit specific and getting that stuff back would be awesome.
There used to be some nice style guides for terminology, capitalization, and so forth with examples that I can’t find or are restricted and I can’t access them.
@jsyip , thanks for your guidance, but your statement is not true. In fact, at least 1/2 of the old design guidelines are not present on the new site. The old site remains the only way to find these guidelines.
Some of the omissions in the new site are striking. For instance, although the new site had user guidelines for the “Pagination” component, the new site doesn’t include the “DynamicTable” component, much less the user guidelines for the DynamicTable, a component without which a Pagination component on is an orphan.
Nor does the new site have the “Form” component (a lynchpin of any design system) or that component’s user guidelines. Similarly, it’s missing all layout related components, all date/time related components, and all navigation components.
IMO, @remie hits the nail on the head: the main problem with the new site, along with Atlassian’s decision to disable real-world usage of the source code (a successful yarn install for any of the “public” components hasn’t been possible since 2019) means that Atlaskit no longer serves the more deeply committed app developers and integrators that have spent years working with these components. To this audience, the old site remains the only alternative for documentation. So, if you don’t intend to invest in it, hopefully it won’t follow the path of the Atlaskit source code to non-public access.
Atlaskit used to be a complete solution for, as @remie says, delivering consistent in-app experiences to enterprise customers. With full source and build system built in, it could pass security review and be integrated into an enterprise pipeline. But not any longer.
@jsyip , thanks for your guidance, but your statement is not true. In fact, at least 1/2 of the old design guidelines are not present on the new site. The old site remains the only way to find these guidelines.
Migration of the remaining 30+ design system components (which still live on Atlaskit for now)
So yes, in your words, “1/2 the old design guidelines are not present on the new site.” and this was intentional as it was not part of our MVP to launch. We are working on migrating the remaining content and components over from the Atlaskit site to the new site.
I think we are all misunderstanding each other in some way because we are not speaking the same language and using terms differently. I will try to clarify a few terms and provide some history:
Design guidelines:
Documentation that contains usage guidance (how to use things), best practices, Do’s/Dont’s, and content (writing) guidance.
Developer guidelines:
Documentation that contains examples, API definitions, code sandbox, prop tables, etc.
History
Atlassian Design Guidelines (ADG)
The old atlassian.design website, which was previously home to Atlassian Design Guidelines (ADG).
The old ADG site had design guidelines for 27 components. Each of these 27 design guidelines had a button on the upper right of each page, which would link to respective components on the AK documentation site.
August 2020: The new atlassian.design website launches, which becomes the new home for Atlassian Design System (ADS).
The 27 components with existing design guidelines and corresponding developer guidelines are the first set of components to migrate to the new ADS website (https://atlassian.design/components)
We did not remove/sunset/delete any of the design guidelines from the old site, we simply moved them over to their corresponding “Usage” tabs on their relevant component pages.
Atlaskit (AK)
There are about 60design system components on the old Atlaskit website.
For the first 27 components that migrated to ADS, there is a redirect from AK in place pointing to the new documentation.
There are 30+ design system components remaining that need to be migrated to the new ADS website. To be super clear, these components were not migrated in August 2020 because they actually do not have corresponding design guidelines. They only have developer guidelines (which are still accessible on AK). This means that the component was created and released without design vetting. Our design team needs to do research, and write up new guidelines and best practices for how best to use these components before we can migrate them.
This is why some components have been migrated, and some have not, and why some seem to be missing. Please be patient as our team works on creating new guidelines and content in order to migrate the remaining components.
Why are we moving to one site?
It has been difficult to maintain two separate documentation sites as Atlassian and the design system has evolved over the years. Internally, the Design System Team has changed, which means ownership over parts of the design system has also changed as well. One of the biggest pains for our consumers (internal and external) is the inconsistencies across our two documentation sites, and the sites have became more and more out of sync (also out of sync with our tools). The Design System Team is now aiming to create a better source of truth for all designers, developers, and content designers through a unified destination.
Hope this helped clarify some things in the meantime, please let me know if I can clarify anything else.
@jsyip , I believe the larger misunderstanding is over the purpose of this “new home for Atlassian Design System”. When you say it’s an MVP, the letter “V” stands for “viable”. But you can see on the board that many existing Atlaskit developers feel the new site is not “viable”, especially in the context of what we had up to Jan 1, 2020. Not only was the previous version “viable”, but it was a mature and robust solution to all of our needs.
Previously, we had complete documentation for all components in one place, both design guidelines and example code. Even for the components that are included on your new site, many code examples are missing and most all of the technical documentation seems to have disappeared. There are many open source, public design systems on the web that set an expectation in terms of requiring BOTH ux/ui guidelines AND extensive example code. The old incarnation of your site exceeded the standard, whereas the new incarnation of your site falls short.
In terms of actual code, the old site was associated with an open source monorepo where the source for any component was freely available and could be built and tested. The components that you point to in the current site cannot be built or tested (yarn install on any of them fails), which has caused many new developers, like @danielwester, above, to waste time, not to mention frustrating Atlaskit’s long-standing users. It’s not a good look.
It appears that Atlassian is wasting an extraordinary amount of money creating an entirely new site. Why not simply add the design guidelines for the 30 newly documented components to the existing site? That can’t be more than a few hours of work once the content is created.
At the least, why not complete the work on the new site before introducing it and causing all this confusion when the previous version of the site ain’t broke?
MVP, as a concept, is fine for shipping a prototype to market to assess traction + appetite. Using it for what should be comprehensive technical reference documentation is, IMO, misguided. Atlassian marketplace developers clearly rely on levels of granularity that need a stronger focus than MVP. Appreciate the transparency from Atlassian via @jsyip, but the developer community need the fine level detail that AtlasKit clearly delivered. Having done stints as a technical writer, I know the challenge you’re trying to pull off, but would it hurt to have them running in parallel during the content migration/optimisation?
So my level of frustration with the state of the atlaskit documentation continues (this being the third or fourth time I’m trying to put my words down here). I’ve been trying to use the @atlaskit/grid component ('cause it’s a pretty easy to implement).
None of those really talks about how to use it - it’s just example code. We’re left to our own devices to figure out what it does (apart from reading the source code). There is a link to what I think was an explanation https://atlassian.design/guidelines/product/components/grid - but that’s gone…
So I’m left with an @atlaskit package that I’ve used before, but is no longer documented…
The current situation makes me start questioning if I really should be using atlaskit in my future projects or perhaps instead finding alternatives and re-theming them. I really want to use atlaskit - but the cost of development with it is increasing.
I was just looking for the format that Atlassian uses when displaying a date, but I can’t seem to find it. Perhaps I’m looking in the wrong place or it’s no longer there. I remember there was design documentation about this at some point in the past.
(sharing it here in case anyone is looking for examples / feedback for improvements)
You can read more about this here: 