From 4a6c8d0b056a234ab2ab5d08a39d3f4bffa84956 Mon Sep 17 00:00:00 2001 From: JLou Date: Wed, 22 Jan 2025 15:39:26 +0100 Subject: [PATCH] docs(adr): add proposals for client architecture and slash roadmap --- .../0003-client-packages-architecture.md | 72 +++++++++++++++++ docs/decision-records/0004-roadpmap-slash.md | 78 +++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 docs/decision-records/0003-client-packages-architecture.md create mode 100644 docs/decision-records/0004-roadpmap-slash.md diff --git a/docs/decision-records/0003-client-packages-architecture.md b/docs/decision-records/0003-client-packages-architecture.md new file mode 100644 index 000000000..881702837 --- /dev/null +++ b/docs/decision-records/0003-client-packages-architecture.md @@ -0,0 +1,72 @@ +# Architecture of the client packages to support multiple themes + +## Status + +Accepted on 14/01/2025. Present at the meeting: Samuel Gomez, Johnathan Meunier, +Martin Stievenart, Guillaume Kesteman, Paul Plancq, Jean-Lou Piermé. + +## Context + +Our design system needs to support 2 themes for the client oriented +applications: Look and feel, and Apollo. The proposal made by Samuel Gomez is to +create a new package for each theme. The architecture looks like this + +``` +client +├───look-and-feel +│ ├───css +│ │ └───src +│ │ └───Button +│ │ Button.scss +│ └───react +│ └───src +│ └───Button +│ Button.tsx +├───apollo +│ ├───css +│ │ └───src +│ │ └───Button +│ │ Button.scss +│ └───react +│ └───src +│ └───Button +│ Button.tsx +└───common + └───src + └───Button + Button.scss + Button.tsx +``` + +In the common folder, code that can be shared between the two themes will be +stored. For the necessary adjustments, each theme can override code. Ideally, in +the theme source files, we would only re-export the common component. + +Four package would be created: + +- @axa-fr/design-system-look-and-feel-css +- @axa-fr/design-system-look-and-feel-react +- @axa-fr/design-system-apollo-css +- @axa-fr/design-system-apollo-react + +### Pros + +- Most of the code would be common, only variants not found in a specific theme + would be developped inside their own theme, and minor visual changes would be + done in the respective css package. + +### Cons + +- More packages to maintain pipelines for +- Build is a tad more complex + +## Decision + +A unanimous decision was made to follow the proposed architecture. + +## Consequences + +- The architecture will be updated to reflect the new structure. +- The new packages will be created. +- The new packages will be published to the npm registry. +- Build pipelines will be updated to include the new packages. diff --git a/docs/decision-records/0004-roadpmap-slash.md b/docs/decision-records/0004-roadpmap-slash.md new file mode 100644 index 000000000..051ec787b --- /dev/null +++ b/docs/decision-records/0004-roadpmap-slash.md @@ -0,0 +1,78 @@ +# Technical roadmap for slash in 2025 + +## Status + +Accepted on 14/01/2025. Present at the meeting: Samuel Gomez, Johnathan Meunier, +Martin Stievenart, Guillaume Kesteman, Paul Plancq, Jean-Lou Piermé. + +## Context + +Our slash codebase has been around since 2019 and much has changed in the +frontend, and react worlds. Some of the technique we had to use back then are +obsolete now, and we have to adapt to the new standards. + +We also have to think about the future, and how we can make our codebase more +maintainable, while avoiding large breaking changes each version. + +### 1.1.0 - Immediate future + +Our #1 priority is to support react 19. As soon as we are confident with it, a +1.1.0 will be shipped. + +### 2.0.0 - Variants + +The code has been using BEM and `classmodifier`s to handle variants. This has +been working well, but there are some challenges. The main one being that typing +`classmodifier` is impossible. Using variants, we can leverage TypeScript's +union types to type our variants. It would align with what is done in the more +recent client codebase. + +Example: + +```tsx +// In 1.x + + +// In 2.x + +``` + +Removing `classModifier` means we need to add a way for our users to inject +custom classes into our components. This can be done by using the `className` +which will not remove base classes anymore. + +```tsx + +// In 1.x + // would render + +// In 2.x + // would render +``` + +This means a massive breaking change on all of our components, either with the +removal of `classModifier` or the change in the `className` behavior. + +### 3.0.0 - Dropping bootstrap grid system + +We have been using the bootstrap grid system for a long time. It has been +working well, but it is not the most efficient way to handle layout in 2025. +With flexboxes, and grid there are more elegant ways to align our components. + +There is a massive unmaintained css file copied from bootstrap v4 that we can +remove. + +Projects relying on `col-md-x` and others will have 2 options: + +- include that css file themselves +- update their code to avoid relying on these classes + +## Decision + +A unanimous decision was made to make theses changes, in that order. + +## Consequences + +- Milestones will be created for each of the versions +- A migration guide will be written for each of the versions +- A post will be written to explain the changes to our users