Document rationale and decision about design system replacement

j08lue commented 5 months ago

The refactor/architecture ADR includes notes about a change of design system. This should be documented in a separate ADR.

Acceptance criteria

[ ] Wrote new ADR for design system

sandrahoang686 commented 3 months ago

Creating this RFC so we can come into agreement with the plan moving forward for the new DS. If all is good to move forward with this proposal, then I will go ahead and document this decision in the DS ADR. Please feel free to add comments, questions, flag any risks or if you think there is a better solution.

Related to: Issue#804

VEDA Design System Replacement RFC

Status: Proposed / Accepted / Implemented / Obsolete Reviewers: @faustoperez @oliverroick @hanbyul-here @dzole0311 @j08lue

Context

Replace the existing custom design system with a well-maintained, widely adopted community-supported design system. This ensures built-in accessibility standards and eliminates the need for designers and developers to invest time in ongoing maintenance.

Options Considered

Design System Options

Opt1: Chakra UI Built to support React apps, it is a comprehensive component library featuring accessible, reusable and composable components that is widely adopted and has strong community backed open-source development and documentation.

Opt2: USWDS Tailored for government projects. It's designed to meet the specific needs of U.S. federal websites, offering components that are accessible, secure, and in line with U.S. digital standards

Implementation Timeline

Opt1: Post VEDA2 Refactor To reduce the amount of moving pieces during the refactor, it makes sense to replace the DS separately and post the veda2 refactor work because while core feature components and smaller reusable components are broken out, we can ensure the look and behavior of these components are maintained.

Opt2: During Development of New Features Introduce the new DS sooner rather than later to accommodate and develop new feature requests. This would highly likely need to happen during the refactor epic, as the team will continue to support these requests. However, adding the new DS should be isolated to only new code/features and without altering or replacing existing components during the refactor to mitigate risks in change of behavior of current components / the application and to reduce the amount of moving parts in the existing codebase.

Proposal

Opt1: Chakra UI Opt2: During Development of New Features

I propose moving forward with Chakra UI as its widely used and documented and there is experience with using this DS in devseed already. I think it makes sense to also integrate this sooner rather than later during the refactor work as we will need to also support new feature requests. This DS should only be isolated to new features / code without altering currently existing components so current behavior of these components and the application is maintained (as much as possible) throughout the refactor and to reduce the amount of moving parts with the existing code. Introducing the new DS to build new features also reduces the amount of re-work later if we were to build these out with the old DS just to swap it out with the new DS. This also allow our new feature request designs in figma to use the new DS system.

Pros / Cons

Chakra UI Pros:

Widely community adopted and supported
Currently used is some devseed projects

Cons:

Only works in client-side components

USWDS Pros:

Tailored for government projects and designed to meet the specific needs of U.S. federal websites

Cons:

Not currently used in any devseed projects
Would require to update node version in veda-ui (trussworks/react-uswds)

oliverroick commented 3 months ago

I don’t know too much about the internals of VEDA UI, but this seems like a sensible approach. I’ve got a couple of comments and questions for consideration.

If were to go down the NextJS route, how does this affect our choice for the UI library? Chakra requires all components to be client-side components effectively ruling out server-side rendering of we wanted to use it. That might be con for Chakra.
What are the differences between Chakra and USWDS in terms of available components. Does one of them offer components that we often need and that the other doesn’t offer?
If we go with Option 2 for implementation and do it during development of new features, will there be noticeable difference between old and new, and will our partners go along with that. Do we need to specifically manage the communication around these differences with partners? Do we have an estimate, roughly how many new feature we’ll introduce during the refactor? Maybe the overhead of having to redo some features is smaller than selling the differences to partners.

Would require to update node version in veda-ui (trussworks/react-uswds)

I don’t think this is a con against USWDS. Node 16 isn’t maintained anymore, so we should upgrade VEDA to Node 22 anyway.

sandrahoang686 commented 3 months ago

Thanks for your thoughts @oliverroick 🙇🏼

I had to look up what you meant and that is indeed a con if chakra only works client-side. We can't take advantage of NextJs's SSR benefits. This might not be an optimal combo since it also looks like it degrades SEO. We can still use Chakra but we just wont have the benefits from NextJs. I'm wondering if this is okay to still move forward then or if it makes sense to pivot? I think we initially made the soft decision to just go with Chakra because it is currently used in other devseed projects.

In terms of available components, chakra-ui looks like it doesnt have date picker components. Which we use in a few places in the dashboard. USWDS does have this though. @faustoperez do you have any input here as you have referenced chakra(?) and uswds in your designs? and @j08lue would you have an estimate on the new features?

faustoperez commented 3 months ago

@faustoperez do you have any input here as you have referenced chakra(?) and uswds in your designs?

Over the past months, I have incorporated some patterns from the USWDS, such as the accessibility recommendations, the date picker, and the footer.

The date picker is the pattern we discussed for the E&A timeline: USWDS Date Picker.

The USWDS also offers a basic widget for data visualizations: USWDS Data Visualizations.

I think adopting USWDS would be beneficial as they comply off the shelf with federal laws and policies. This is a strong selling point, for this and future government projects. A couple of examples:

Mine is a strong opinion, weakly held. Happy to work with Chakra or any other solution that makes more sense on the dev side :)

j08lue commented 3 months ago

Do we have an estimate, roughly how many new feature we’ll introduce during the refactor?

@aboydnw and I can try to come up with an estimate for next quarter (my assumption for "during the refactor"), looking into the GHG Center development targets we know of.

On my radar are:

New GHG Center welcome page (details not specified yet, but will probably involve data facts and graphs) https://github.com/US-GHG-Center/veda-config-ghg/issues/307
Improved E&A timeline design https://github.com/NASA-IMPACT/veda-ui/issues/822
Data Catalog support for "datasets light" that do not have a full-blown custom Overview page (not yet specified yet) https://github.com/NASA-IMPACT/veda-architecture/issues/426 / https://github.com/NASA-IMPACT/veda-ui/issues/840
Better presentation of data access information (not yet specified) https://github.com/NASA-IMPACT/veda-ui/issues/839

sandrahoang686 commented 3 months ago

Conclusion from DS Discussion with team: We are good with moving forward with USWDS but will be moving forward with it as a spike where we will be implementing a new component as part of a sandbox experiment and converting an existing component so we could see if it fits with the current needs. Based off of that we can revisit on whether or not we would like to continue with USWDS. This will also apply to the design process, Fausto will be creating the design scaffolds and will make sure he has all he needs with this new DS going forward.

Decision documented on ADR will be held off until after this pilot/spike but this decision can close this RFC/ticket.

@hanbyul-here mentioned we may be able to use this issue for the pilot/experiment https://github.com/US-GHG-Center/veda-config-ghg/issues/288

cc @aboydnw

NASA-IMPACT / veda-ui