This page contains frequently asked questions from our community.
If you can’t find an answer to a question you have please email us at guides@digital.gov.au or join our conversation on slack.
You can view our current unit tests. We’re creating a new version which will make it easier to get started with the UI-Kit.
You can view our project backlog to see an up to date list of tasks. We generally try to balance 50% community engagement (capability uplift and understanding user needs) and 50% product (maintenance and building).
Version one was implemented following strict semantic HTML. This caused issues with implementation as users who didn’t have easy control over their HTML struggled to implement the UI-Kit. Due to this version one is now deprecated and is no longer supported. Version two uses classes that need to be added. This allows users to be more flexible with the HTML they are provided with.
The UI-Kit is built for everyone. We want government and private sector to embrace the UI-Kit. It aims to solve common usability and accessibility problems in a simple and robust way.
That’s awesome! Please take a look at the Github issue queue, if you find a relevant issue please join the conversation and note down any steps you took to find it. If it’s a new issue please create a new issue and provide detailed instructions. We’ve provided an issue template to make this process easier.
The current spacing in the UI-Kit is going through a change which we hope to implement in the coming months. Currently the spacing is based on
font-size (em) which has caused some unexpected behaviour for our users. We’re planning to move from using em in the uikit-space function to
rem’s. We’re also moving to one font (previously we had two font families one for headings and one for the body) which will allow a consistent line-height.
These changes in spacing will also influence our typographic rhythm for the spacing under headers and paragraphs which we’ve also had feedback on.
During research we have met many Australians who live in rural and remote areas where Internet access is limited but Government services are still required. Using system fonts makes the load times faster with only a slight compromise on aesthetics. System fonts have come a long way. Manufacturers are now shipping some elegant fonts as default in their operating systems.
To optimise readability we have set a max-width on certain elements inside the body. This creates a consistent and easy to use user interface. You can
override the code as necessary, but please understand your users needs.
We currently don’t provide any design files. In the future we’d love to provide users with variations of files to allow them to access the latest components in the UI-Kit.
Complicated functions and interactions need careful accessibility consideration during development and design; usually on a per-project basis. We plan on looking at some of these things in the future and provide guidance around them.
- Carousels: hides content, are difficult to navigate, and often add more accessibility issues than they solve.
http://bradfrost.com/blog/post/carousels/
http://shouldiuseacarousel.com/ - Tabs / Collapsible panels: Need work to be done correctly. They can hide content, often spoil
find in pagefunctions, require understanding of how they work, add more accessibility issues.
https://baymard.com/blog/accordion-and-tab-design
The UI-Kit is built to be system agnostic. This means that it can work with any system, development environment, build tools or stack. Currently we support three different entry-points:
There are also many communities which are connecting content management systems and other javascript frameworks to the UI-Kit. If you would like to do the same we recommend having a look at the question How do I add the UI-Kit to my build process? How do I add custom code/variables/overrides?.
From our learnings in version 1 of the UI-Kit, we decided it was best to provide our users with css classes which they can then invoke onto the
HTML output their system provides. This means that by default a <h1> will not get the .uikit-display-6 styles as you may decide to make your <h1>’s look
like <h2>’s. Where possible we recommend adding the UI-Kit classes directly into the HTML.
The reverse number system was implemented because when headings can get bigger but can't really get smaller. To be able to scale the system up further you need
to have room: (uikit-display-6, uikit-display-7, uikit-display-8). That being said we have identified this as very confusing.
We’re going to be changing to a more sensible xxs, xs, sm, md, lg, xl, xxl system.
The purpose of a UI-Kit is to bring consistency, quality, efficiency and accessibility to government. IT is to help you get started and give you a foundation while not having to reinvent the wheel every time. as with any framework there is still an expectation that custom code will be needed to fully suit your users needs. There are always going to be gaps as the framework is help intentionally lose to help as many different platforms. Our recommendation is to write your custom code in a reusable and robust pattern. If you’re making a new component, follow the same patterns as the UI-Kit components. That will allow you to contribute back, or replace those components in the future if your team want to implement another solution.
You don’t need to know or fully understand pancake. It’s a tool used to distribute the UI-Kit. We would recommend reading the
repository documentation and having an understanding of the pancake object in the package.json file. Pancake allows users
to npm install @gov.au/breadcrumbs and get a the assets file copied into a folder of your choosing. It’s a powerful tool that we have built to enable us to
use npm as our distribution manager. This means that one user can have breadcrumbs version 1.2 and another can have version 2.1 and nothing will break.
Users can then choose to upgrade their components when necessary. A great
article around pancake can be found on medium.
New components can be requested in lots of ways. Our preferred approach is currently through Github. Please take a look at the Github issue queue, if you find a relevant component please join the conversation and note down any additional requirements or variations. If it’s a new issue please create a new issue and provide detailed instructions of the component.
Build processes can be complicated, we recommend first looking at our UI-Kit starter pack. This is a simple
implementation of the UI-Kit showing how to include the UI-Kit into your project. After you npm install and run npm run watch you should have some generated
files. Looking at the src/sass/main.scss file you can see the order:
// OVERWRITES
// UI-Kit
@import 'uikit';
// CUSTOM SASS
This pattern is how we recommend to apply the UI-Kit. You are able to overwrite variables as we use the SASS
default flag on our variables. Then when creating or overriding
existing components we recommend adding your code in the custom SASS section.
Pull requests are awesome so thank you for reading this! The general procedure we follow when making a pull request is:
- Create a new branch off the development branch for what you’re working on
- Do the necessary changes
- If possible please test the work, we understand this is not always possible :)
- Please submit your PR against the
developbranch of the govau/uikit repo.
while we want to be open to the community and allow collaboration to happen without barriers, we do follow a strict set of rules for code that ends up into the UI-Kit. It would be a great help if you could test or specify what you have tested against that list. Please also work with the code style, not against it.
We currently have a community on slack and github. If you’re working on a specific implementation with a javascript framework or content management system there may also be communities external to the UI-Kit.