What kind of component library is Elements?

[kurtdoherty]

Now that we have a Design System working group and investment in Elements v5 starting to ramp up, I believe there is a key foundational question in front of us: what kind of component library is Elements? A clear answer will provide alignment and clarity across the group and help simplify some of the decisions that we'll face in future.

It seems to me there are two obvious answers we could settle on:

1. Elements is a generic component library whose default appearance implements the Reapit Design System (Reapit DS); or,
2. Elements is a specific implementation of the Reapit DS.

Answer 1: Elements is a generic components library with a default appearance

This answer would make Elements similar to MUI, Chakra UI, Reakit, React Aria and other popular generic component libraries in the React ecosystem. With this answer, the appearance of Elements' components can be modified to match any design system and the following design decisions would seem acceptable:

• We allow (potentially extensive) visual customisation of components:
  • Design tokens used in Elements are a superset of those used in the Reapit DS;
  • Elements may include component-specific design tokens for all components to provide maximum visual flexibility;
  • Elements may support page layouts that are not used in the Reapit DS (e.g. sidebar navigation menus);
• Elements can diverge from the Reapit DS over time, so long as its default appearance remains close to the Reapit DS:
  • Elements can have its own roadmap and future vision that is not coupled to the roadmap and future vision of the Reapit DS (that is, adoption of Elements does not necessarily mean adoption of the Reapit DS);
  • Contributions to Elements do not necessarily need to involve Reapit Design approval/collaboration (e.g. component names and interfaces can be different);
  • Elements can implement components, or variants of components, that are not used by the Reapit DS.
• If another technology choice, like web components, were added to Elements in future, it would also be design system agnostic.

Answer 2: Elements is a specific implementation of the Reapit DS

This answer would make Elements similar to Lightning, Atlaskit, Fluent UI, Spectrum and other publicly-available design systems that can provide various implementations of a business' internal design system in different technologies (e.g. web components, React and others). With this answer, Elements could effectively become the name of the Reapit Design System itself and the following design decisions would seem acceptable:

• Visual customisation of components is tightly constrained by the Reapit DS;
  • Design tokens used in Elements are an exact export of what is defined by the Reapit DS;
  • Elements does not introduce any additional design tokens in order to enhance visual customisation;
  • Elements only supports page layouts used by the Reapit DS (e.g. sidebar navigation is unsupported by Elements);
• Elements does not diverge from the Reapit DS (though some implementation lag may exist):
  • Elements' roadmap is always aligned with, and geared towards growing adoption of, the Reapit DS (that is, adoption of Elements represents adoption of the Reapit DS);
  • Contributions to Elements require Reapit Design approval/collaboration (e.g. component names and interfaces should be agreed on);
  • Elements only implements components, and variants of components, that are used by the Reapit DS.
• If another technology choice, like web components, were added to Elements in future, it would also be a specific implementation of the Reapit DS.

Why no third option? Surely there's a compromise?

It is possible there is another option you see that I have not considered. I am deliberately presenting a clear dichotomy here, but maybe there's some appropriate middle ground or alternatives that are worth our consideration. Please take some time to think about the main question—what kind of component library is Elements?—and respond below 🙏

Once we've collected our thoughts here, we'll be able to discuss verbally at an upcoming working group meeting, get input from the Design team and, hopefully, find an answer we're confident in 🤞 If we discover other important questions during the discussion, we can take a similar approach for them (assuming it works well enough for us this time).

[willmcvay]

@kurtdoherty For me it's option 2 - the sole mandate we have is to implement as faithfully as possible the Reapit Design system. Advanced customisation is not on the agenda and we should support basic level theming only insofar as the design tokens exported from the design system are exported and can be overridden as a native feature of CSS, purely at the user's discretion. Our focus should be to ensure as 1:1 parity with the Design System as possible.

[kurtdoherty]

Thanks for weighing in @willmcvay. Option 2 is what I would hope for, and what Tony, Karmen and Andrei would expect too 👍

Option 2 does constrain what the PayProp-branded version of the new owner portal can look like though; I take it the business accepts that? (If the same code is meant to service PayProp and Reapit UK versions, I don't see any alternatives here, because the Reapit UK version would be expected to match the Design System).

[willmcvay]

@kurtdoherty Based on our last discussions, am pretty confident any PP theme requirements can be met inline with this option but am sure we can ask the team at the next working group and will be lead by the Design team on this.

[kurtdoherty]

The Design System working group, on 24 April, all agreed that answer (2) is correct; Elements is a specific implementation of the Reapit DS. This means:

• Visual customisation of components is tightly constrained by the Reapit DS;
  • Design tokens used in Elements are an exact export of what is defined by the Reapit DS;
  • Elements does not introduce any additional design tokens in order to enhance visual customisation;
  • Elements only supports page layouts used by the Reapit DS (e.g. sidebar navigation is unsupported by Elements);
• Elements does not diverge from the Reapit DS (though some implementation lag may exist):
  • Elements' roadmap is always aligned with, and geared towards growing adoption of, the Reapit DS (that is, adoption of Elements represents adoption of the Reapit DS);
  • Contributions to Elements require Reapit Design approval/collaboration (e.g. component names and interfaces should be agreed on);
  • Elements only implements components, and variants of components, that are used by the Reapit DS.
• If another technology choice, like web components, were added to Elements in future, it would also be a specific implementation of the Reapit DS.