ADG3 vs AtlasKit

Hi everyone,

There are some differences between the design guidelines and AtlasKit components. I know it’s a work in progress, so this is expected. But which one of the two is the most recent version?

Take lozenges for example. This is what lozenges look like in the design guidelines:

And this is what they look like in AtlasKit:

Is one more up-to-date than the other? And which one would that be?

Thank you,

1 Like

Hi @Maarten thanks for raising this. In general the source of truth is the ADG 3 guidelines, which AtlasKit then implements. I’ve messaged the ADG 3 team to double check this, and will comment back here soon. If it turns out that AtlasKit’s lozenge component needs to be updated, you’ll be able to get the fix (once it’s ready) by updating the @atlaskit/lozenge component version in your project.


1 Like

Hi again @Maarten yes it looks like the AtlasKit component needs to be updated to match the latest ADG 3 lozenge design spec. It’s not scheduled at the moment but it’ll be mentioned in the component release notes (available on component pages) when it happens.


Thanks Ben, I’ll use the ADG 3 guidelines as my source of truth then.


Hey @Maarten , as AtlasKit catches up to ADG3 guidelines, something to consider is the development effort to match the guidelines. A one-off adjustment to AK component to look like the guidelines incurs overhead and future adjustment when AK catches up. I’ve taken the strategy of going with AK components to save the team effort of updating later. There are a few cases where we’ve had to roll our own because the component wasn’t the right fit for our use case.


I definitely agree @ksnow. Unfortunately, the ADG3 Sketch file that Atlassian provided is missing a lot of components. So I’m recreating a lot of these components based on what I see in ADG 3 and AtlasKit.

I have designed a number of pages using components that turned out to be old and/or changed. The new look of the components didn’t match with what we had in mind, so we had to change the design after learning about this.

But I’m using ADG 3 as the main source of truth now.

i feel your pain!! :smiling_imp:

I’m in the same situation @Maarten, I’m using the Sketch files (which are awesome, but out of date) and I needed the new ones (sadpanda)

Should we let you know about components that don’t match with ADG3?

The single-select component, for example, is much lighter than ADG3 tells us it should be. On some (non-calibrated) screens, we can’t even see the background of the component.

1 Like

yes, this is really helpful. i can file a bug for items you find.