Contributing Shared Widgets

Shared Widgets offer an exciting opportunity for product teams to contribute to a shared library of components utilising the front-end monorepo and Earth Design System coding styles and patterns, while giving teams a level of ownership and responsibility over components that will be used across the business.

Having Shared Widgets sit alongside the Earth Design System in the same monorepo provides some key advantages:

• Instant updates when the design system receive updates.
• Shared linting, testing and publishing infrastructure.
• An opportunity to bring high-quality design system thinking to a broader range of product components.

This document outlines how product teams can contribute to Shared Widgets and collaborate effectively with the EDS team.

While the EDS team set up and manages the Shared Widgets package, they are not the owner of all Shared Widgets.

The benefit of having Shared Widgets separate from the core design system is that you can own the code you build and participate in our shared component ecosystem.

Each Shared Widget is owned and maintained by the developer and team who created it. The EDS team will gladly assist with code reviews, answer questions, and provide guidance, but the responsibility for ongoing maintenance remains with the contributing team.

Creating a shared widget is straightforward. The following list outlines the process, with both required and recommended steps:

1. [Highly recommended] Create a design and dev audit for your new components.
2. Get the aw-frontend-monorepo dev environment setup.
3. Read the shared-widget's README for setup and commands. The adding new components guide also has more information on the files that are created and a guide on where to begin.
4. Check out the component quality standards and coding style guide.
5. Build your component!
6. [Required] Create a changeset for your component.
7. Add yourself as a CODEOWNER for your component.
8. [Required] Raise a pull request. This PR should be reviewed by:
   • Developers from your team who understand the business requirements of the widget.
   • EDS team members to check the component utilises EDS correctly.
9. Coordinate with the EDS team on publishing.

To ensure consistency and maintainability across all Shared Widgets, new components should meet the EDS established quality standards:

• Follow EDS conventions for folder structure and file naming.
• Use design system components and tokens as building blocks for your component.
• Utilise existing EDS design patterns where applicable.
• Match EDS prop naming conventions for consistency.
• Include tests that cover core functionality. This helps the design system team make changes to core components with confidence that any issues will be caught early.
• Add documentation to the EDS docs site, which identifies the owner team. Docs include storybook and playroom examples.
• Pass TypeScript and ESLint checks without errors or warnings. We prefer to avoid ignore statements, but understand they're sometimes necessary for valid technical reasons.

For detailed guidance on aw-frontend-monorepo coding patterns and styles, please refer to the coding style guide.

We highly recommend creating design and dev audits for your new components. The EDS team has found these audits invaluable for ensuring optimal component APIs and maintaining a clear record of design decisions for future reference.

Many times the team has referred back to these documents to remember why we made a particular decision.

The design audit looks at how this component will be used throughout each product, and refers to examples in other design systems.

The dev audit finalises the API (props), looks into any potential libraries if required, and tackles any tough questions on how the component should be built. The dev audit is usually done while prototyping the component at the same time so the developer gets a feel for what the component will look like.

When each audit is ready, the team will get together to discuss and spar on it.

Two examples of comprehensive audits are:

• Design Audit - Tabs
• Dev Audit - Tabs

Checkout the EDS Confluence space for more examples on design and dev audits.

Where possible, aim to keep Shared Widgets as UI-focused components. Avoiding tight coupling to specific APIs or data models ensures maximum reusability across different contexts and teams.

Due to shared-widgets' dependency on eds-core, Shared Widgets follow the standard EDS release cycle and are published every two weeks alongside core design system updates.

Need your changes sooner? No problem! Contact the EDS team and we will try and arrange an ad-hoc release to meet your timeline.

The EDS team are here to help! For any questions or feedback about the Shared Widget contribution process, please reach out to the team in the Shared Widgets collab channel. We welcome your input on how we can continue to improve this process.

The Shared Widgets package was designed to encourage product teams to build, own and maintain EDS-quality components while gaining a real sense of ownership over the code they ship.

While we strongly encourage product teams to build shared components themselves, we recognise there are situations where this isn't feasible due to capacity constraints, or when a component is so generic that no single product team is the natural owner.

In these cases, the EDS team is open to stepping in to build and maintain the widget. These requests will be prioritised alongside other product needs, and the following approach applies:

• We apply the same rigorous standards to EDS-built widgets as we do to core components.
• We conduct design and dev audits and build to EDS core quality standards.
• We focus on UI and layout components rather than components tightly coupled to specific APIs or backend services (e.g. the crop modal or industry dropdown).

On the flip side, since Shared Widgets can evolve more readily than core components with major versioning, the team doesn't need to anticipate every possible use case upfront to streamline the development process.