Contribution guidelines

You can contribute to the Agriculture Design System (AgDS) in many ways, including:

• Reporting or fixing bugs,
• New component and pattern suggestions,
• Submitting pull requests to enhance existing components and patterns,
• Or even writing documentation

All contributions should:

• Align with the visual language and design principles of the system
• Offer improvement to the way all teams deliver their services
• Be made in collaboration with the Design System team
• Include designs documented in Figma, and
• If coded, be built using React.js

How to contribute

Check if it exists

Before you propose a pattern or component, please check the design system documentation to see if something already exists and check our backlog to see if something is planned or already started.

Message the Design System Teams chat

To propose a new component or pattern please message the Design System Teams chat and include the user need, visual examples (screenshots) and links to Figma. Please ensure details about interactivity, states, content requirements and responsive behaviour are detailed.

Wait for your contribution to be reviewed

All proposed designs will be reviewed by the AgDS team but are open for comment on the Design System Teams chat by the design community.

Work with us once accepted

If your design proposal is accepted, we will work with you to ensure the design aligns with the principles, interactive behaviours, and visual language of AgDS. We can then add the component to the AgDS backlog for development or work with you to develop the code and documentation if you need it faster than we can deliver.

Code contribution

If your proposal to build is accepted, your design and code will need to meet our contribution criteria, use existing AgDS components and patterns (if applicable), and be developed in the open so that the AgDS team and the community has visibility of the work.

Once your code is ready the AgDS team can work with you to review and publish the contribution.

Contribution criteria

Communicate the benefits to the users and the business

All contributions should satisfy a user need and offer value to the way all teams deliver their services. Providing a clear rationale will help us to understand the problem you are solving for end users, internal users, and any potential business improvements it will create.

The contribution aligns with the visual language of the design system

AgDS uses design tokens to create a simple, consistent, and inclusive visual language. This language helps users understand the interactive behaviour of our components and creates a common language between designers and developers. Tokens are used for background and foreground colour, space, typography, border, shadow, and corner radius.

All designs should use AgDS tokens to maintain visual and functional consistency with other design system components and patterns. Information about the tokens and how to apply them can be found on the Core page of our documentation site and Figma design file.

Aligns with our design principles

Our design system is a continuation of the Australian Government Design System, which was built on principles of simplicity and inclusion. AgDS maintains these basic design principles to ensure our services are fast, intuitive, and easy to use and can be accessed by users of all abilities in any location. Learn more about our design principles.

Meets our design standard

Accessibility is a foundation of AgDS. Any design or code contributed must meet WCAG 2.1 AA as a minimum.

AgDS is built using React.js and TypeScript. Any code contributions should meet minimum code hygiene levels outlined in this recontribution guide. We work in GitHub so contribution can be made to the AgDS repository.

All patterns and components of AgDS are designed to be used across common screen sizes. All contributed patterns and components need to be responsive and function from 320px mobile to 1600px desktop viewports.

Is unique

Proposed patterns and components should be unique and not duplicate existing patterns and components of the design system unless your proposal is intended to replace or enhance something. Always check the design system to see if a solution already exists before starting your design, and check with the team to see if we are already working on something.

If your pattern or component is not unique but improves user experience, it may be considered as an enhancement of an existing pattern or component and may still be considered.

Provides broad value

Patterns and components should offer value to multiple services or products teams before they will be considered for contribution to AgDS. Building, testing, and documenting a design system component or pattern takes time so a design that offers benefit to many teams will take priority.

Tested

The fastest way to get your pattern or component into AgDS is to design, build it, test it with users, and provide the evidence. Validating your designs through usability testing will provide evidence to support your contribution.

All contributions should be tested for accessibility against WCAG 2.1 AA and checked for browser compatibility.