Evolving the Australian Government Design System

Introduction

Jordan Overbye, an engineer at Thinkmill, introduces himself and the Agriculture Design System (AgDS), an open-source design system for the Australian Government Department of Agriculture, Fisheries and Forestries.

What is AgDS?

Jordan discusses AgDS, a shared language between content developers and design practitioners. Built using React and TypeScript, AgDS offers templates, patterns, and guidelines for building consistent user interfaces.

Introducing GOLD

The Government Open Language for Design (GOLD) is an open-source design system for building government products. This section covers GOLD's design language, usability, accessibility standards, and limitations.

The Journey of AgDS

Jordan outlines the three phases of AgDS development: Rebuilding GOLD for AgDS, extending AgDS to meet the export service's needs, and validating AgDS's accessibility and usability.

Phase 1: Rebuilding GOLD for AgDS

This phase focuses on AgDS's mission statement, design principles, technological underpinnings, and component library structure, including tokens, primitive components, and composite components.

Color Tokens in AgDS

Jordan delves into the implementation of color tokens in AgDS, covering background colors, foreground colors, and system colors, emphasizing the system's adaptability to light and dark palettes.

Primitive Components

This section explains the role of primitive components like the box component and style props in building layouts and components within AgDS, highlighting their flexibility and responsiveness.

Composite Components

Jordan showcases composite components in AgDS, emphasizing their simplicity and effectiveness in creating user interfaces based on the GOLD framework.

Phase 2: Extending AgDS

The second phase focuses on extending AgDS to meet the export service's needs, including developing new components, uplifting existing elements, iterating on components, and extending the color token schema.

External Resources & Influences

This section highlights the free resources, such as Authoring Practices Guides and design systems like GovUK, ReachUI, ReactARIA, and RadixUI, which influenced AgDS's development.

Phase 3: Accessibility Audit

The final phase covers the accessibility and usability audit conducted by Intopia. This involved testing components in isolation, evaluating page templates and the documentation site, and conducting usability sessions with users with specific accessibility requirements.

Usability Testing & Findings

Jordan shares insights from moderated usability testing conducted with users with specific accessibility requirements, highlighting both positive feedback and areas for improvement based on user observations.

What's Next for AgDS

The presentation concludes by outlining future goals for AgDS, including increasing adoption, iterating on the system, conducting further accessibility testing, and the potential for AgDS to serve as the foundation for a future version of GOLD.

Thank you for that lovely introduction, Jess.

Yes, so hello everyone.

I'm very excited to be here and thank you all for coming.

Speaking at my first conference ever.

Excited but a little bit nervous as well.

So yeah, let's get into it.

To get things started, my name's Jordan and I'm an engineer at a design and development consultancy called Thinkmill.

And for the last 18 months or so, I've been working on the Agriculture Design System, otherwise known as AgDS, which is an open source design system for the export service, which is part of the Australian Government Department of Agriculture, Fisheries and Forestries.

And as this is a public, open source project, I put the link here for anyone that's interested in checking that out.

And what's unique about AgDS is that it's really heavily based on the former Australian government design system, which was formerly known as AuDS.

And before we get too into it, I'd just like to give a special shout out to the AgDS team.

We are a pretty small group of designers and developers.

But I wouldn't be able to be here without all the hard work from the team.

So shout out to all the team members, past and present.

And so most of you in the audience probably have never heard of the export service before, or maybe not even the Department of Agriculture.

So let me talk about that briefly.

The Department of Agriculture are actually responsible for regulating, assuring and certifying agricultural exports to make sure that the exports, the, make sure the Australian exports meet the requirements of the importing countries.

So what the Export Service is responsible for is, it's a digital transformation initiative.

Designed to improve the experience of our exporters.

And the Export Service is building tools to support farmers and producers, as well as inspectors and vets working on the ground, as well as all the internal staff at the department, too.

And these tools that they're building consist of anything from simple informational websites to more complex web applications, and even some API integrations as well.

Now back to AgDS, and to give you all some visual context on what AgDS is, this is what's known as our kitchen sink example, which is essentially just a dump of all of the components in the system, in no particular order.

And this is a really great and easy asset to have, as it allows us to really simply see all of the components in the system at a glance.

And as you can see in this video, AgDS is a themable system with support for both the light and the dark palettes.

And I'm just using Storybook controls here to switch between the light palette and the dark palette.

And you can see how all the components respond nicely to that change there.

And I'm also using Storybook to switch between what we call the agriculture theme, which is the theme that we use in the export service, to the GOLD theme.

And we'll talk about what GOLD is in just a moment.

As you can see, AgDS is an open source component library that we built using React and TypeScript, and our consumers download that via NPM.

But at a higher level, it's really a shared language between content development and design practitioners.

We have templates, patterns, and guidelines for how to build common pages as well as common, compositions of components.

And for our designers, we also have components, tokens, templates, and documentation available to use in Figma.

And for our content folks as well, we have guidelines on how to create really clear and consistent content in the export service.

First up, let's discuss what GOLD is, as we saw in the video just before.

GOLD stands for the Government Open Language for Design and that is an open source design system for building government products.

It's designed to replace the former Australian government design system, which was being funded by the DTI up until 2021, when it was unfortunately decommissioned.

At its peak of popularity, GOLD and AuDS was used by a bunch of different government departments and agencies, Service Australia, Department of Health, and many more.

And if you're building a government product or design system, like, why would you want to choose GOLD?

It has a really clear and simple design language that is very suitable for government.

It was thoroughly researched and was widely used across government services, so there was quite a bit of a community built around GOLD.

And all the components and templates that were available had really high usability and accessibility standards as you'd expect from a government design system.

But no system is perfect and GOLD, is no exception there.

So when DTI, the DTI did commission, the design system, unfortunately the community engagement did slow right down after moving to their open source model.

So there is a slack group and open source GitHub repo, but it's not really that active anymore, unfortunately.

And, unfortunately, it lacked a bunch of components.

There was no patterns and the tooling was quite outdated as well.

And the export services primarily building, modern web applications.

It wasn't quite perfect, for our needs.

But, despite all this, we decided to take the aesthetics and the design principles of GOLD and extend that into AgDS, to meet the needs of the export service.

Now that I've introduced a little bit about what the department is, what the export service is, what GOLD is, what I'm going to be talking about today is really the journey of AgDS, which can be split up into three different phases.

The first being how, how AgDS has been, sorry, how GOLD has been rebuilt for AgDS, followed by how AgDS has been extended to meet the needs of the export service, which is still happening as it stands as the export service evolves.

And finally, how we validated the accessibility and usability of AgDS.

Phase one, the start of this project, rebuilding GOLD for AgDS.

One of the first things we did was write down our mission statement.

And one of our main goals was that it should be possible for AgDS to be used as the foundation of a future version of GOLD, if that ever happened.

And this mission was underpinned by one rule, that we would maintain the principles and visual language of GOLD, but we would only iterate if we saw a perceived user experience benefit or an accessibility benefit.

What we also did was document and publish our design principles early.

AgDS strives to support simplicity, usability, and inclusion, because people who use government services, they just don't really have another choice.

They can't go to an alternative service provider, because there's only one government.

GOLD was built quite a number of years ago, and technology has moved a long, way since then.

Personally, I like to view AgDS as a bit of a modern interpretation of GOLD.

All of our components and patterns and templates are built using React and TypeScript, and we use Emotion as well to do all of our styling, which makes it really easy for teams to incrementally adopt.

The design system components, they don't have to have an all or nothing approach.

We built our doc site and our patterns and our templates using Next.JS and Storybook, which has been amazing.

And we also make use of, Seek's open source Playroom, which is a prototyping tool you can use to build interfaces in the browser, which has been absolutely amazing for us.

A bunch of cool tooling and testing libraries as well.

And if anyone's interested in this, it is a public open source repo, so feel free to check it out.

And so let's take a look at how AgDS has been put together.

And there are really three levels to the AgDS component library.

So at the top we have things like buttons and accordions and a select, and these are typically components that you think of when you think of a design system.

But those components are really just compositions of our primitive components, and these are things like box, column, flex, text, etc.

And what's unique about these primitive components is that they have these things called style props, which allow us to interact with our design tokens, so typography, color, border, everything like that, in a way that's type safe and responsive as well.

So let's have a look at these three levels in a little bit more detail.

First up we have tokens, and I'm only going to cover color tokens today because everyone loves colors and, timing as well.

So here's a screenshot of the color token page, in GOLD.

And at the top we have four background colors, and sitting on each of the background colors are all of the foreground colors available.

And at the bottom we can see how all of these colors, adapt to the topic.

The dark palette.

So GOLD, like in some design systems, you have a light and dark mode, where the whole page is dark mode.

But in GOLD, only parts of the section, sections of the page are in the light or the dark palette.

And a little practical example of these colors in use is the GOLD button component, so on the left we have the button in the light palette and on the right we have the button in the dark palette.

So for background colors we have body, alt, shade, and shade alt.

Very, simple.

Body and body alt are used for the main and alternative backgrounds of a page, while shade and shade alt are used to differentiate or highlight certain, components on the page.

And as mentioned before, these four colors do adapt to the dark palette.

And so we can see in this video from the GOLD homepage how background colors are typically used.

So the header and the footer are in the dark palette and use the body background.

And then the main section of the page is in the light palette.

And then we use body and body alt to create like a highlighting or a striping effect to bring it to, to highlight certain sections of the page.

So next up we have foreground colors and for foreground colors.

It's very simple as well we have text muted and action and that's it and actions are used for things like links and buttons according any sort of like interactive component And again, these foreground colors do adapt to the dark palette.

GOLD also had an idea of system colors, which weren't really documented, but they are typically used to indicate system status.

So we had system, error, success, warning, and info.

And an example, oh, sorry, what's unique about system colors in GOLD, compared to foreground and background colors is that they do not adapt to the light or the dark palette.

The color is always the same between the two.

And as an example of these system colors, here is what the page alert component in GOLD looks like.

And you can see between the light and the dark palette version, the text color is changing, the background color is changing, but that red system alert color does not change.

So now that we understand how colors work in GOLD, let's take a look at how we've implemented this in AgDS.

AgDS requires you to wrap your application in a core component, and what you can do with the core component is you can pass your own theme to that, to override the theme.

And by default, the GOLD color scheme is used by default, not the agriculture theme.

And this small but nuanced technical decision really speaks to our original statement about AgDS being compatible with a future version of GOLD.

So if you were, building a government service and you wanted the same theme as GOLD but only really wanted to change the action colors, you could do something like this code snippet here.

And we don't want to use the GOLD theme in the export service, so what we do is we wrap that up in a package, called Ag branding, which contains the agriculture theme, so in every application, in the export service, they do something like this.

And as you can see here, AgDS has maintained support for the light and the dark palette.

So this is, Seek's Playroom tool.

We've got the code editor at the bottom and we've got the live preview up the top and we've just got a simple example of some components in the light and the dark mode.

And so what our core component is actually doing is It will add a bunch of CSS variables to the root, for, which specify all the colors that it needs for the light and the dark palette.

And then it will set itself to the light palette by default, so any component you use out of the box will just be in the light palette.

And then you can have sections, in the page in the dark palette.

And the way you do that is you use our primitive components which have, this palette prop.

And what that allows you to do is say, hey, all these child components I want to be in the, dark palette.

And how that's working under the hood is that when a palette prop is set, We just add some CSS variables to that element, saying, hey, this is the new action color that you need to use.

This is the new background colors that you need to use.

Because the browser works in a cascade, all those child elements automatically inherit that theme.

So this is great.

It doesn't rely on any React context or anything for theming.

It's a really simple solution, which has been great.

Finally, sorry, next up, let's talk about our primitive components.

So we offer a bunch of primitive components which make building layouts and components a breeze, and our most primitive component is the box component, which is really the foundation of everything.

By default, it renders a plain div, nothing fancy, but we can use these style props like background, etc.

to interact with our design tokens.

Style props are not just limited to color, as you saw there, but we can also interact with typographic components if we want to set font size or font weight, which is really cool.

And primitive components are also polymorphic.

So you can use the as prop to render a different element.

If you didn't want to div out of the box, you wanted a section, you could do something like this.

And this is really key to creating semantic and accessible HTML.

Style props are also responsive too.

If I wanted to create a component where on mobile, I was using the backgr the body alt background color, and then on desktop I needed to use the body background color, rather than writing a bunch of media queries, I can use this object syntax here as to say, hey, on the extra small breakpoint, please use the body alt color, and on our large breakpoint, please use the body color.

Under the hood the styled props will generate the media queries for us, which is great.

And not only are styles that map really nicely to our design token supported, but we can also support native CSS properties such as align-items, justify-content, flex gap, etc.

The ability of, doing this plus being able to map back out to our design tokens create this really powerful way of being able to style your components without ever having to leave JSX.

All of it is just done in this file, which is really, easy to maintain.

So finally, let's have a look at how the components work.

And GOLD had roughly 30 components ranging from anywhere from simple tables to buttons, to form inputs and grids.

And most of the components that you would need to build a simple informational website you could probably find in GOLD.

And as a really simple example of a component that was in GOLD that we've rebuilt is called Callouts.

It's really simple.

It has a title, a description, as well as some basic styling.

And if we look at the code for this component, it's just so simple.

We're using a stack to create a gap between the title and the description.

The stack also has some basic style props applied for the styling, like the border left, the background color.

We've also got like a high contrast outline prop, so when we're in Windows high contrast mode, we get the nice, transparent border there, with using a text component, which has some default typographic styles applied.

So yeah, really simple.

And to summarize this phase, at the end of this phase, all the components that were in GOLD were available in AgDS.

We had built a really solid foundation to a design system.

And as you can see here, a video from my colleague Nathan.

He's using Playroom to put together a really simple, informational based website page, in just a matter of minutes.

Thanks.

Which is really awesome to see.

However, we didn't have all the components that we needed to support the export service.

So we had to evolve.

And that brings us to our next phase, phase two.

Cool, so AgDS has constantly been evolving to meet the needs of the export service and other products in the department.

We've basically doubled the amount of components that were in GOLD, brought that into AgDS, while also documenting templates and patterns, which encourage high quality and inclusive and consistent interactions at scale across the export service.

So let's take a look at some practical examples of how we've extended AgDS.

And to give you an idea of some of the types of interfaces that AgDS is being used for, here is a video of a prototype, that we've built recently to mimic a pattern found in some internal applications.

So we've developed an AppLayout component which contains the header, the sidebar, the footer.

We've created a drop down menu component to support switching accounts as well as accessing all your account features.

We've extended the basic GOLD table component into something more that supports sorting, filtering, selecting.

Multiple items, paginating.

We've also developed a series of modal components.

So we have a modal and a draw component to display information to the user without them having to leave the page.

So while this type of UI is a little different to what GOLD was primarily being used for, you can see that we've worked really hard to try and, carry the design language across from GOLD, into these new, more interactive components, and we've also tried really hard to make sure that these highly interactive components are as accessible and usable for all types of users.

We've also uplifted components that were featured on the GOLD Docs site, but were never an actual, official component.

This screenshot from the GOLD website of a, the bottom of the button documentation page contains a little sub nav component that you can see in this section here.

We needed something very, similar in the export service, so we decided to uplift this into an official component for AgDS, which we've called sub nav.

And this is a screenshot of our documentation site for the sub nav page.

And in the first highlighted section here, you can see the code snippet for how this component would be used by a consumer.

In the second highlighted section, you can see how we've also used all of our components to build our documentation site.

So we try and dog food all of our components as much as possible, just to make sure everything we're building, is as good as it can be before it reaches our consumers.

We've also made small iterations to existing components that were in GOLD.

So on the left is the GOLD text input component, and on the right is the AgDS version.

And you can see we've just introduced an icon, as well as updated the font weight as well, which better improves the affordance that something went wrong.

And this actually came as the result of some accessibility testing we conducted.

And as you saw in the video before, we've also acquired really highly, complex, interactive components.

So we've built things like date pickers, combo boxes, tabs, autocompletes, et cetera.

So this is a small video of our date range picker component.

As you can see, it supports both text input as well as, support for the, calendar widget input as well.

We've also had to make some small changes to the color token schema too.

In the highlighted section is part of the main nav component.

And in GOLD, that strip of line you see there, that color was always the same as the action color.

But in the export service, we needed that strip to be a special color, so what we decided to do was extend the color token schema to support an accent token.

Another example of where we've extended the color token schema is our page alert component.

As you saw before, this is the GOLD page alert component.

And here is the AgDS version of the page alert component, which has been slightly redesigned.

The contrast is not so great on, on this screen, but We have, a muted color of the green and the red as the background.

And in order to do this, we've had to introduce, four new system colors.

We've got system error muted, system error success, et cetera.

And what's cool about, system colors in AgDS is that we've made them adapt to the light and the dark theme.

And this provides a much more consistent affordance of an experience of status by maintaining the same, contrast values between foreground and background colors.

This was our light color palette at the beginning of the project, very simple compared to some of the other design systems that have been featured on this track, and as this, as it stands today, this is our light, color schema right now.

As you can see, we've kept everything the same.

We've still got the original background, foreground system colors, but we've introduced the muted system colors, as mentioned, we've got accent, we've got selected and selected muted.

And this is all customizable by consumers as well.

So we've tried to make it easier for people to customize themes.

And so while developing all these new components, we relied pretty heavily on some really great free resources out there.

As an example, while I was building the tabs component, we were referring to the Authoring Practice Guides by WA ARIA, which go into really great detail about how all the keyboard interactions should work, how the focus management should work for the tabs component.

So that's, great.

But it is quite verbose and boring at times, so it's great to see like a more practical example out in the wild.

GovUK is great, but since we're in React land, I really like looking at ReachUI, ReactARIA, RadixUI, to name a few as they really care about accessibility too.

And this is a great segue into the last phase, the accessibility audit.

Prior to releasing the design system, beta last year, it was really important for us to test the accessibility of AgDS.

We undertook an accessibility and usability audit.

And the accessibility audit was actually facilitated by Intopia, who, have their booth outside and sponsoring this event too.

And the audit consisted of three phases.

So we had the first phase was just a simple test of all of our components in isolation.

And then we moved on to testing our page templates and documentation site.

And finally we had usability sessions with users that had a specific accessibility requirements.

So we had users who were blind and they needed a screen reader.

We had users with low vision, they needed a screen magnification software.

We had users with mobility issues that used facial tracking software to move around the page, which was just so, cool.

Phase one, some of the tests and checks, that were conducted on components were simple screen reader and keyboard checks, making sure everything adapts nicely to Windows High Contrast mode, making sure when you zoom up all the way to 400 percent that all the components reflow nicely, making sure everything has sufficient color contrast, and really simple as well, making sure all your HTML is valid.

And having Storybook for this phase was super valuable as it allows us to test components in isolation for free basically and we can see the component in all the different states as well.

An example of some of the bugs that were uncovered in this phase was our date range picker that we saw before.

So in Windows High Contrast mode, we were relying on color alone to convey the status of the selected date range and that didn't carry over to Windows High Contrast mode.

So that's easily fixed by, we can just add a font weight bold and also a high contrast outline available to the selected datarange.

Another example was in our main nav component, on mobile it goes into a hamburger dialogue type menu.

And me, or our other developer, forgot to add overflow y auto on that element.

So when you zoom in all the way, the content doesn't reflow properly.

Luckily it was a small fix, but, Yeah, really good catch from Intopia.

And once all those issues were resolved, we moved on to phase two, which was audit of our page templates and documentation site.

An example of one of the pages that were being tested was our sign in form template.

And although this is a really simple piece of UI, it was really great to test this because it tests how all of our components are typically composed together on a page.

So we've got the header, the footer, a bunch of different form inputs.

We're managing focus, we're showing loading states, we're moving things around like when, validation errors occur.

So this was, really great and once that phase was completed, we moved onto phase three, where we observed users, with a specific accessibility requirement, using an example application that we've built called Registry And as this video plays, I've registered your pet, I'll talk a little bit about what this is.

So recruiting for usability with the export service is very challenging, as you need quite specific domain knowledge.

So what we decided to do was build an example form flow, which mimics the user experience that's typically found, in the export service, which can be these huge forms that are split up into multiple tasks, and then each task is split up into multiple steps.

And as the user progresses through the form, they see a series of forms.

And what we did was we ran moderated testing so we could, we as a team as well as parts of the organization as well could observe these users using this application.

And some of the findings that came out of this were really interesting is that, we had super positive feedback from our screen reader users, so this was really great to hear because we put a lot of effort into this.

It means that our components respond nicely to keyboard input, everything was getting announced correctly, focus was being managed correctly.

But unfortunately some visual users, so low vision or maybe some neurodivergent users as well worked pretty confused by some UI elements on the page.

So we knew we had a bit of work to do.

So here's a screenshot of our page from Registry a Pet before any changes were made.

And this is a screenshot of the same page after we made changes.

So some changes to highlight are, the progress indicator was redesigned slightly to make it more, look like a timeline of, a series of step tasks rather than a series of individual tasks.

We've also introduced some colors as well, to better improve the affordance of task status.

We also worked with, the content team to make sure that all of our labels, not only in the progress indicator but throughout the form as well were as clear as possible.

And finally, this SummaryList component here.

Previously, the key and the value were, like, 50 50 split of the container.

But we brought those elements closer together, as a lot of users reported.

They thought they weren't connected.

At the end of this process, we received a certificate of compliance for WCAG 2.1 AA compliance, which, is a great achievement for the team that we're all super proud of.

And, to wrap things up, let's talk about what's next for AgDS.

We're focusing now on increasing adoption across the, department while also obviously iterating and improving the system as more, we get more users.

We'll be hopefully testing all of the new components and stuff we built over the last year or so to make sure everything that we've done is as accessible and usable as possible.

And maybe one day, you'll see AgDS as a foundation of the next version of GOLD.

We'll see.

But yeah, thank you so much, everyone.

APPLAUSE

EVOLVING THE AUSTRALIAN GOVERNMENT DESIGN SYSTEM

Jordan Overbye

Senior Engineer

Hello

  • I’m Jordan Overbye, Senior Engineer at Thinkmill
  • Working on the Agriculture Design System (AgDS), an open-source design system for the Export Service at the Australian Government Department of Agriculture, Fisheries and Forestry (DAFF)
    design-system.agriculture.gov.au

AgDS team

The image displays eight individual profile pictures arranged in a circular pattern, with four on the top and three on the bottom, and the text "AgDS team" in bold at the center.
exports.agriculture.gov.au
A screenshot of the Export Service page from the Australian Government Department of Agriculture

Website hero banner title - xxxl/display (H1)

Short hero banner sentence - md/default (P)

A webpage layout showcasing an AgDS page

What is AgDS?

  • An open-source component library built with React and Typescript and available via npm
  • Shared language between practitioners
  • Templates, patterns and guidelines for common compositions
  • Figma library of components, tokens, templates and docs
  • Content guidelines to create clear and consistent content

What is GOLD?

  • Government Open Language for Design (GOLD) is an open-source design system for building government products gold.designsystemau.org
  • Replaces the former Australian Government Design System (AuDS) which was decommissioned in 2021
  • Was used by Services Australia, Department of Health, Department of Veterans Affairs, NSW Government, ACT Government and many more

Why choose GOLD?

  • Clear and simple design language suited by government
  • Thoroughly researched and was widely used across Australian Government services
  • Large number of components and templates with the highest usability and accessibility standards
A series of illustrations showing a team of people working with rockets, including a drawing, rocket construction, and a launching rocket, representing collaboration and innovation.

Why not just use GOLD?

  • Unfortunately community engagement slowed down after moving to an open-source model
  • Lacked components, patterns and tooling required to build modern web applications

The AgDS journey

Phase 1

Rebuild GOLD for AgDS

Phase 2

Extend AgDS to meet the needs of the Export Service

Phase 3

Validating accessibility of AgDS

Three square diagrams labeled Phase 1, Phase 2, and Phase 3, each accompanied by a brief description.

Phase 1

Rebuilding GOLD

AgDS is an extension and reimplementation of the GOLD Design System written for modern React web applications. It should be possible for AgDS to be used as the foundation of a future version of GOLD”

Excerpt from the original AgDS mission statement

Design principles

design-system.agriculture.gov.au/foundations/design-principles
  • AgDS is for everyone
  • User’s needs come first
  • Consistent, not uniform
  • Function over fashion
  • Evidence over opinion

A modern interpretation

  • Code: React (v18 support), Typescript, Emotion (CSS-in-JS)
  • Frameworks: NextJS, Storybook and Playroom
  • Tooling: Preconstruct, manypkg and changesets
  • Testing: react-testing-library, jest, puppeteer, axe

Architecture of AgDS

Components

<Button/> <Accordion/> <Select/>

Primitives

<Box/> <Columns/> <Text/>

Design Tokens

Typography, Colors etc

A flowchart showing Components leading to Primitives, and Primitives leading to Design Tokens;

Tokens

The image contains two sets of typographical elements on different colored backgrounds. The top section has a white background with different shades of grey cards, each containing repeated lines of text: "Abc Abc Abc" in various styles and sizes. The bottom section has a dark teal background with darker shades of teal cards, each containing similar repeated lines of text: "Abc Abc Abc" in various styles and sizes.
Slide contains a comparison of primary and secondary buttons in different styles.

Background colours

A slide with four squares labeled as "Body," "Body Alt," "Shade," and "Shade Alt," each in varying shades of gray, representing different background colors.

Background colours

The image contains four square color swatches labeled as Body, Body Alt, Shade, and Shade Alt.

Community

The design system has been created for designers and developers across government to share and create a set of quality tools and designs that can be used by everyone.

Components

Components can be used and extended by anyone to help kickstart the design and development process or even build production-ready interfaces.

Templates

Templates combine components to help you kickstart your project. They'll save your team time and resources and help get value to your users sooner.

Illustrations of simple line drawings: the first shows two people giving a high-five with a cloud above them, the second shows a person holding a tablet with design screens, and the third shows a person pointing at layered design templates.

Foreground colours

Three colored squares labeled "Text," "Text Muted," and "Action," representing different foreground colors.

Foreground colours

Text

Text Muted

Action

Three squares representing different foreground colours: the first square is white labeled "Text", the second is gray labeled "Text Muted", and the third is light blue labeled "Action".

System colours

System Error

System Success

System Warning

System Info

Four colored squares labeled from left to right: dark red for System Error, green for System Success, orange for System Warning, and cyan for System Info on a light background

System colours

System Error System Success System Warning System Info
Four colored squares representing system states: red for error, green for success, orange for warning, and light blue for information on a dark background

There is a problem

Two panels demonstrating error messages, one with a light background and one with a teal background. Each panel contains an 'X' mark icon.

Tokens in AgDS

import { Core, Theme } from '@ag.ds-next/react/core';

const theme: Theme = {
  lightForegroundAction: '#00558B',
  darkForegroundAction: '#9EE8FF',
};

function Example() {
  return (
    <Core theme={theme}>
      <YourApplication />
    </Core>
  );
}
import { Core, Theme } from '@ag.ds-next/react/core';
import { theme } from '@ag.ds-next/react/ag-branding';

function Example() {
    return (
        <Core theme={theme}>
            <YourApplication />
        </Core>
    );
}
<Stack gap={1} padding={1}> 
	<Button variant="primary">Primary button</Button> 
	<Switch checked label="Show establishments" /> 
		<Stack palette="dark" gap={1} background="body" padding={1}> 
		<Button variant="primary">Primary button</Button> 
		<Switch checked label="Show establishments" /> 
	</Stack> 
</Stack> 
Image showing a user interface with two "Primary button" buttons and two "Show establishments" switches, in both light and dark themes.
The code and example above in developer tools

Primitives

<Box />
<Columns />
<Flex />
<Stack />
<Heading />
<Text />
import { Box } from "@ag.ds-next/react/box";

function MyComponent() {
  return <Box background="bodyAlt">Hello world</Box>;
}

// <div class="css-j42pp2">Hello world</div>
import { Box } from "@ag.ds-next/react/box";

function MyComponent() {
  return (
    <Box background="bodyAlt" fontSize="xs" fontWeight="bold">
      Hello world
    </Box>
  );
}

// <div class="css-1rrog0k">Hello world</div>
import { Box } from '@ag.ds-next/react/box';

function MyComponent() {
  return <Box background={{ xs: "bodyAlt", lg: "body" }} />
}

Components

A grid with icons of 20 or more components

<Callout title="Callout heading">
  <Text>Description of the callout.</Text>
</Callout>
  
Two callout boxes side by side with the headings "Callout heading" and the description "Description of the callout."

function Callout({ children, title }: CalloutProps) {
  return (
    <Stack
			gap={1}
			background="shade"
			padding={1}
			borderLeft
			borderLeftWidth="xl"
			borderColor="muted"
			highContrastOutline
			>
      {title ? (
        <Text fontSize="lg" fontWeight="bold" lineHeight="heading">
          {children}
        </Text>
      ) : null}
      {children}
    </Stack>
  );
}
Narrow and wide versions of the same page side by side

Phase 2

Extending AgDS

Screenshot of an example app with long spreedsheet like UI.

Sub nav

A horizontal list of links typically placed between the main navigation and page content.

View in Figma View in Storybook View in Github

import { ... } from '@ag.ds-next/react/sub-nav';

Code


<SubNav 
  activePath="#usage" 
  links={[ 
    { href: '#usage', label: 'Usage' }, 
    { href: '#code', label: 'Code' }, 
    { href: '#content', label: 'Content' }, 
    { href: '#accessibility', label: 'Accessibility' }
  ]}
/>
    
Home > Components > Sub nav

Screenshot displaying a web documentation page for the "Sub nav" component, including component description, links to external tools (Figma, Storybook, Github), and an embedded code example.

Email

Enter an email address in the correct format, like [email protected]

Illustration of two email input fields with error validation. The left input field has no error icon, while the right input field displays an error icon before the text.

Date range picker

Date range picker with a calendar interface displaying months October and November 2023 for selecting a start and end date. The date format specified is dd/mm/yyyy.

Website hero banner title - xxxl/display (H1)

Short hero banner sentence - md/default (P)

Two screen designs for a website hero banner compared side by side, one with a green theme and the other with a dark blue theme. Both feature the Australian Government crest, a search bar, and a menu link. The layout for both designs is otherwise identical. An arrow on the left highlights the border color under the nav bar.
Two graphical error messages with different background colors: one in red and white, and one in teal and white, each containing a close button marked with an "X".
Two notification boxes showing success and error messages with check and cross icons respectively.
The same notifications in a dark theme.
Color definition documentation.

Reputable resources

  • WAI-ARIA Authoring Practices Guide (APG)
  • MDN Web Docs
  • GOV.UK Design System
  • Reach UI, React Aria, Radix UI
  • A11y slack group

Accessibility audit

  • Facilitated by third party accessibility experts Intopia
  • Consisted of three phases:
  1. Audit of components in isolation
  2. Audit of page templates and documentation site
  3. Usability sessions with users that have specific accessibility requirements (screen readers, screen magnifier etc)

Phase 1

  • Screenreader and keyboard checks
  • Windows high contrast mode compatibility
  • Components reflows at 400% zoom
  • Elements have sufficient colour contrast
  • HTML validation

Example

https://design-system.agriculture.gov.au/storybook/index.html?path=/story...
Documentation of a component selection tree on the left, a canvas panel showing an example of a text input field labeled "Example" in the center, and a controls panel with various settings on the right.
An illustration of a calendar interface in high contrast mode

Phase 2

Audit of page templates and the documentation site

Sign in form - xxl/display (H1)

https://design-system.agriculture.gov.au/example-site/sign-in-form#main-content
Screenshot of sign in form page in them design system

Phase 3

  • Usability sessions
  • Observe users with specific accessibility requirements using an example application to “Register a Pet”

Screenshot of the app.

Usability session findings

  • Positive feedback from screen reader users
  • Visual users were confused by some UI elements
yourGov webpage titled "Address details," with sections and form fields for entering and checking an address.
Same page as above with modified sidebar showing progress more clearly.
"The Department of Agriculture's design system site presents very minor accessibility barriers for users with disability and is a credit to the Department of Agriculture's time and effort towards making the application accessible."

intopia

What's next?

  • Increasing adoption across the department while iterating and improving the system
  • Testing all new components and patterns for WCAG compliance
  • Maybe, the foundation of the next GOLD?

Thank you ‍

@JordanOverbye