Docusaurus will be used as the component library for Ashlar
Context
When Ashlar was first created in 2018, we decided to use a theme (Shila) that used PatternLab as the component library technology for the new Design System. This allowed us to make use of Atomic Design, and build a new component based theme with a popular upcoming Framework.
PatternLab has not seen any real improvements in the past few years, and was broken for several months due to PHP incompatibilities with our profile. For this reason, we decided to find a new tool for documenting our components.
In 2021, we discussed the possibility of switching from PatternLab to Storybook.js. Storybook.js is a more robust component library with some additional built-in features, such as accessibility testing, and automated workflows to other software used on campus, such as Figma. However, setting up and maintaining Storybook.js instances can be complex, and we decided that it was not a good fit for our team.
In 2022, Docusaurus was explored as an option. It was found to be easy to set up and easy to use as a tool for documentation and testing.
Decision
We decided in late 2022 to make the switch from PatternLab to Docusaurus. The reasons and benefits for this change are outlined in detail in the 5.0.0 release notes for Ashlar.
For posterity's sake, the reasons we chose not to switch to Storybook in 2021 were as follows:
- Changing from PatternLab to Storybook would require extensive manual refactoring of the codebase
- The change over offers some hypothetical neat benefits, but doesn't solve existing problems, for example:
- The accessibility testing built into the front end, while very cool, doesn't necessarily fix any existing problem: All components are built with accessibility in mind, Carly has already built in some automated accessibility checks, and what gets through those would likely also get through the Storybook testing.
- The front end of Storybook.js has the potential to be more user-friendly, but only a small handful of people on campus actually use the front end of PatternLab and none have thus far reported problems with its use
- The automated workflows with technologies like Figma still require communication and manual coding, so is of limited tangible benefits
- While Storybook.js ostensibly supports vanilla Web components, documentation for how to get up and running with these (as opposed to Vue.js or React.js type frameworks) is very slim
In summary, the work required to change over currently outweighs the benefit of the additional features Storybook.js offers. This may change in the future as more technologies relating to our Drupal workflow are explored, at which time this decision may need to be revisited.