Codey

Appearance

Report a problem:

Problems can be reported via Microsoft Teams in your team channel within the "IT - Codey" team.

Please include the following information:

Report type:
Docs problem report a bug instead →
Path:
/vnext/contributing/adr/records/010__further-adoption-of-prime-vue-components-with-theming-capabilities.html
Message:

DESCRIBE THE PROBLEM BEFORE SUBMITTING TO CODEY

Further Adoption Of Prime Vue Components With Theming Capabilities ​

Status: Approved

Decision Date: 11/07/2024

Scope: codey-components, codey-style

Context ​

The new Xerius Design Refresh is based upon the Prime Vue Design making it opportune to update and replace more components from the codey component library with prime components. This reduces the maintenance required by our team regarding components and their features. We are not limiting our library only to Prime, but the majority of components will be adopted from it.

This context builds upon the decision previously made to Extend the component library with primevue.

A second requirement to incorporate the new Xerius Design is applying custom theming to the components. Although PrimeVue is the bases of our design choices, we do need to adjust some colors, spacings, and other design elements to fully integrate the new design.

Decision ​

Disband TextField (God Component) ​

The XerTextField component has been long overdue for a refactor. The component contains to many responsibilities and is therefore hard to maintain and extend. It holds almost every features for supporting a text input, text mask, auto-complete, etc.

With the further adaptation of Prime we will disband the XerTextField component and split it up to the Prime equivalent components available. We provide the necessary examples and migration steps to ease the move to the new components.

Introducing XerFormControl & XerOptionControl ​

Splitting up our existing XerTextField component also posed with a need of separating the form control elements from the actual input components as Prime does not provide this. For this reason the XerFormControl and XerOptionControl are introduced. These components provide a reusable approach for placing labels, captions, errors in a a11y friendly way.

These components should be used by Default (as mentioned in the documentation) so that basic accessibility is provided. This also helps to improve testing with the use of accessibility selectors like getByLabel.

To Ensure this approach works within our design system, we introduce playwright tests on the provided examples using a11y selectors as much as possible.

Accessibility ​

At this stage it is not our target to achieve full WCAG compliancy.

We focus on the low hanging fruit like correctly building form html structures and making sure the correct roles and label or aria-label are used. This will make testing with a11y tools easier and provides a step in the right direction.

The scope of how compliant Xerius as an organization needs to be and will be is still under investigation by an external party at the time of writing.

Theming ​

Theming isn't a hard requirement at this moment, but as Tailwind and Prime are build to support it, we want to take advantage of this possibility. It opens the doors to have 1 component library that can support front-office, back-office and my family applications.

PrimeVue has full support for tailwind, therefor we will build the required presets to theme the adopted components. In a later stage we can also update existing Codey components to be styled with tailwind instead of the current custom css. For now we will only do this for the components required by the My Xerius Redesign project.

Tailwind will be our main theme driver together with a css file providing the necessary css variables for that theme. This makes it possible to swap theme's at runtime. The architectural structure of the css will look like this:

Tailwind ---> Tailwind Config ---> theme css variables

Here the tailwind config will utilize css variables to set the theme colors, spacings, etc. The granularity of the css variables will depend on the amount of theme customization we want to support.

Visual Regression Testing ​

In order to ensure that the new components are visually correct, we will introduce visual regression testing using PlayWrights' toHaveScreenshot functionality. This allows us to move fast in the development process of the theming aspect of the components.

Consequences ​

  • This change will be breaking and requires components to be migrated to Primve Vue. The incorporation of migration steps should ease this process.
  • Moving into this direction will make the custom css available in codey style obsolete.
  • Application without any build chain will be harder to support. Tailwind 3 requires a build step to optimize the css bundle required to ship depending on the features used in your application. This will need to be added to have a performant css bundle for the applications needs.
  • Prime Vue is not a hard requirement, as you could recreate the components and apply the tailwind presets yourself. This is however not a recommended approach as it will require more maintenance and will not be in line with the rest of the components. It can be a solution for use in full SRR applications in dotnet for example the identity server login pages.

Alternatives ​

  • Keeping the XerTextField as-is was not on the table due to having had bugs that were unfixable. Fixing one issue introduced another, while fixing the other re-introduced the first issue.
  • Keeping our Style library approach also requires an update to more tech friendly css variables in order to support theming. The downside of this is that we work along side Tailwind and have to maintain these 2 setups.