FAQs

A component is a modular, reusable piece of a user interface that can be independently created, tested, and maintained. Components are the building blocks of digital products, designed to encapsulate specific functionality and appearance. They can range from simple elements like buttons and form fields to more complex structures like navigation menus or data tables.

The design system provides a set of components detailed on the component status page. The components are under design review and detailed component guidelines will be provided on this documentation site as each component is reviewed.

Component implementations are provided that includes vanilla HTML components that are local and stable and an alpha library of React components currently under development.

The existing HTML components are described as local because they are tailored for usage within a gov.ie context. The components are styled for specific use cases, so may not be suitable for your needs. The design system team is in the process of globalising the components.

The term global conveys the idea that global components are designed to work across various contexts, platforms, or brands, making them flexible and adaptable to different needs.

In particular, global components:

• Have component anatomy documentation available
• Have guidelines available for their usage
• Are available as a design component within Figma
• Are built as an HTML component, including macro
• Are built as a React component
• Use design tokens so that they are themeable across both design and engineering

The existing HTML component implementations are undergoing the following globalisation process, converting a single HTML component at a time from local to global based on priority:

• Review design of the component
• Define semantic design tokens
• Implement as a design component within Figma
• Document component anatomy
• Document component guidelines
• Implement the component in HTML using design tokens
• Implement the component in React using design tokens
• Document the component usage in HTML and React
• Mark the local component as deprecated and provide links to the global component

The components will be globalised based on the needs of departments with which we are currently collaborating and on usage statistics across various digital products. The current priority is reflected in the component status information. If you are interested in particular components being made available globally, then please contact the design system team.

Yes, the existing local HTML components will be supported whilst they are being globalised. When a global version of a component is made available, the existing local version will be deprecated, but the local version will continue working unaffected. You can run the local version for as long as needed, and update to the global version when convenient for you.

The markup will likely be similar in structure, but with design modernisation, and will use different class names and data attribute names. Therefore when switching from local to global components, you will need to update the HTML markup.

However, we are also looking to provide macros for global components that are compatible with Nunjucks and Jinja templating engines, so we would recommend switching to the use of macros where possible when moving from local to global components.

The use of macros that are Nunjucks and Jinja compatible means that consumers of the global HTML components are protected from any underlying HTML markup changes whilst the global components are being built or as new features are added.

This reduces the risk of having to deal with breaking changes as you update versions of global HTML components. It also greatly reduces the amount of code required to render components.

No, the local components will require using the HTML markup directly, as already documented on the HTML components Storybook. The priority for the design system team is to globalise the local components, rather than spending time improving the developer experience of the local components. However, we will still support the local components as they are globalised, providing assistance and implementing any necessary bug fixes.

When the global version of a component becomes available, we recommend favouring the use of the global component and the associated macros where possible.

Yes you can, but this would require more code compared to the use of macros, and having to deal with any underlying HTML markup changes as you update versions of the component library.

We therefore strongly recommend the use of macros if you are using a technology stack that supports the execution of macros server side. There will be some situations where the use of the HTML markup directly will be necessary, either due to a lack of server environment or templating tooling.

You can run local and global components side by side. Both sets of components will use different class and data attribute names, so will not interfere with each other. This provides a piecemeal migration path from a local component to the equivalent global component, one component at a time, when convenient for you.

The HTML components are data-driven components (also known as attribute-driven components). This means that they use standard HTML tags with data- attributes. Any behaviour is attached to the component via JavaScript running on the client by querying the DOM for the appropriate data- attribute.

Web Components are a suite of technologies that provide a standard component model for the web, with wide browser support. Users can define new HTML tags that encapsulate appearance and behaviour. Web Components are framework agnostic, so promise a build once and run anywhere approach.

The primary reason for the use of data-driven components over Web Components is that they provide a far simpler configuration for Server Side Rendering (SSR). Implementing SSR with data-driven components is straightforward. The server can render the components as standard HTML, and the client-side JavaScript can initialise or enhance the components based on data attributes.

This approach supports progressive enhancement, where the basic content and functionality are available immediately, improving perceived performance and ensuring better accessibility and Search Engine Optimisation (SEO), as the content is fully rendered and indexable by search engines.

In comparison, Web Components are more complex to implement with SSR. While the server can render custom elements in the HTML, the full functionality of these components typically relies on client-side JavaScript to define and upgrade the elements, manage shadow DOM, and apply styles.

This dependency can delay interactive features, affecting progressive enhancement and perceived performance. Additionally, web components can present challenges for SEO and accessibility, as crucial content and interactions might not be visible to search engines or accessible to assistive technologies until the JavaScript fully loads and executes.

The SSR story for Web Components is constantly in review though, so the situation may change in future and a set of Web Components included in the design system.

Although having a single set of components would be easier to maintain, unfortunately the HTML components are not a good fit for React. Other than being non-idiomatic, the increasing popularity of moving work back to the server via technology such as React Server Components requires a seamless integration between server-side and client-side rendering, which is facilitated by React's unified component model using JSX. Using the HTML components would greatly increase the complexity of building modern React applications.

The choice of React components is based on the available ecosystem and innovation in the React space. The design system documentation site is built with React, which allows us to use the same React components to document component anatomies on the documentation site.

The other Building Blocks are also built with React, which allows the Building Blocks to be themeable as the React components are built out, broadening the use cases for all Building Blocks.

Ideally the design system would provide additional idiomatic components in technologies such as Angular, Vue etc. However, given the current resources available to the design system team, we can only support the HTML and React component implementations.

If your components are working well for you, we recommend that you keep maintaining them in the medium term. You should align your components with the design system guidelines as we make them available. In future, we will also look to provide the design tokens as packages that you can use directly to build out components.

Long term, we would look to incorporate components implemented in other technologies into the design system. This would require aligning them with the latest guidelines and ensuring they are global, for example that they are built with our design tokens so that they are themeable using the same theming mechanism as our other components.

If you have any suggestions for updates to existing components, or new components that you feel should be part of the design system, we recommend contacting the design system team.

This ensures that any changes or additions align with the overall design system principles, maintaining the goal of consistency and quality across multiple products.