Change Details

===UI component library demo tool ==== Background Storybook has been the tool of choice both for demoing a library/design system and for use during the development process by WMF and WMDE teams. Storybook is a powerful tool with many useful features and addons that can empower developers to create documentation and interactive demos. ==== Evaluation However, Storybook has its downsides. Here are a few I've run into: * Configuration and story-writing aren't straightforward, especially when you're first learning. While text documentation only requires markdown knowledge, you must be comfortable with JavaScript to edit stories (e.g. component documentation) * Storybook isn't built for Vue and this shows both when writing stories and reading the docs. * Stories are not the same as normal Vue components, which means the demos we're creating don't line up 1:1 with the code an end user needs to use that component. For this reason and others, the code samples displayed on the demo tab are not sufficient for our needs (see T287049). * It has many dependencies (e.g. the `docs` addon requires markdown, which requires react) * I set up Storybook with Vite/Vue 3 in an [[ https://github.com/catrope/wvui-next | experimental project ]], using `storybook-builder-vite`, an [[ https://github.com/eirslett/storybook-builder-vite | experimental library ]] in its early stages, and ran into issues: ** Source code isn't working, both in the story source panel in the addons tab, or in the "show code" feature on the docs tab. This is a critical feature for us ([[ https://github.com/catrope/wvui-next/pull/6 | see this PR ]] for details) ** HMR doesn't work when you're editing a story file ==== Must-haves - Presentation of all components & patterns, interactive and the underlying code - Presentation of props/slots/actions/events per component/pattern - Presentation of all component/pattern types, even obscure ones - Presentation of icon tokens, including all language variants ==== Nice-to-haves - Interactive (hot module reloading) presentation of components/patterns - Presentation of all component states - Presentation of involved tokens building the component/pattern - Open source tool with big developer community to build on progress and maintenance from the outside - Similar underlying technology (not far off Vue.js) - Plugin ecosystem to build on top -- (Technical) Accessibility plugin -- Responsive viewport plugin -- Visual impairment filter plugin -- Measurement plugin -- Themability plugin (dark/black/white…) - Adding components/patterns to demo is simple without a lot of technical finesse - Low dependencies - Long-term maintenance simple and reliable. - On brand with Design Style Guide - Visual regression tooling ==== Alternatives: VitePress Now that we have decided to use Vite to build the new library, we may want to consider VitePress, a Vue-powered static site generator built with Vite (as opposed to VuePress, which is built with Webpack), or other options. --- ===== Exploration I've been building a proof-of-concept static site with VitePress [[ https://github.com/AnneTee/wvui-next | in this repository ]]. [[ https://elastic-elion-823fb5.netlify.app/ | You can visit the static site here ]].

===UI component library demo tool ==== Background Storybook has been the tool of choice both for demoing a library/design system and for use during the development process by WMF and WMDE teams. Storybook is a powerful tool with many useful features and addons that can empower developers to create documentation and interactive demos. ==== Evaluation However, Storybook has its downsides. Here are a few I've run into: * Configuration and story-writing aren't straightforward, especially when you're first learning. While text documentation only requires markdown knowledge, you must be comfortable with JavaScript to edit stories (e.g. component documentation) * Storybook isn't built for Vue and this shows both when writing stories and reading the docs. * Stories are not the same as normal Vue components, which means the demos we're creating don't line up 1:1 with the code an end user needs to use that component. For this reason and others, the code samples displayed on the demo tab are not sufficient for our needs (see T287049). * It has many dependencies (e.g. the `docs` addon requires markdown, which requires react) * I set up Storybook with Vite/Vue 3 in an [[ https://github.com/catrope/wvui-next | experimental project ]], using `storybook-builder-vite`, an [[ https://github.com/eirslett/storybook-builder-vite | experimental library ]] in its early stages, and ran into issues: ** Source code isn't working, both in the story source panel in the addons tab, or in the "show code" feature on the docs tab. This is a critical feature for us ([[ https://github.com/catrope/wvui-next/pull/6 | see this PR ]] for details) ** HMR doesn't work when you're editing a story file ==== Must-haves - Presentation of all components & patterns, interactive and the underlying code - Presentation of props/slots/actions/events per component/pattern - Presentation of all component/pattern types, even obscure ones - Demos include code samples that can be directly referenced for usage (e.g. a user should be able to copy/paste a code sample to use as a starting point) - Presentation of icon tokens, including all language variants - Interactive (hot module reloading) presentation of components/patterns ==== Nice-to-haves - Presentation of all component states - Presentation of involved tokens building the component/pattern - Open source tool with big developer community to build on progress and maintenance from the outside - Similar underlying technology (not far off Vue.js) - Plugin ecosystem to build on top -- (Technical) Accessibility plugin -- Responsive viewport plugin -- Visual impairment filter plugin -- Measurement plugin -- Themability plugin (dark/black/white…) - Adding components/patterns to demo is simple without a lot of technical finesse - JavaScript knowledge is not needed to edit documentation - Editing documentation requires only knowledge of Markdown - Low dependencies - Long-term maintenance simple and reliable. - On brand with Design Style Guide - Visual regression tooling ==== Alternatives: VitePress Now that we have decided to use Vite to build the new library, we may want to consider VitePress, a Vue-powered static site generator built with Vite (as opposed to VuePress, which is built with Webpack), or other options. --- ===== Exploration I've been building a proof-of-concept static site with VitePress [[ https://github.com/AnneTee/wvui-next | in this repository ]]. [[ https://elastic-elion-823fb5.netlify.app/ | You can visit the static site here ]].

===UI component library demo tool ==== Background Storybook has been the tool of choice both for demoing a library/design system and for use during the development process by WMF and WMDE teams. Storybook is a powerful tool with many useful features and addons that can empower developers to create documentation and interactive demos. ==== Evaluation However, Storybook has its downsides. Here are a few I've run into: * Configuration and story-writing aren't straightforward, especially when you're first learning. While text documentation only requires markdown knowledge, you must be comfortable with JavaScript to edit stories (e.g. component documentation) * Storybook isn't built for Vue and this shows both when writing stories and reading the docs. * Stories are not the same as normal Vue components, which means the demos we're creating don't line up 1:1 with the code an end user needs to use that component. For this reason and others, the code samples displayed on the demo tab are not sufficient for our needs (see T287049). * It has many dependencies (e.g. the `docs` addon requires markdown, which requires react) * I set up Storybook with Vite/Vue 3 in an [[ https://github.com/catrope/wvui-next | experimental project ]], using `storybook-builder-vite`, an [[ https://github.com/eirslett/storybook-builder-vite | experimental library ]] in its early stages, and ran into issues: ** Source code isn't working, both in the story source panel in the addons tab, or in the "show code" feature on the docs tab. This is a critical feature for us ([[ https://github.com/catrope/wvui-next/pull/6 | see this PR ]] for details) ** HMR doesn't work when you're editing a story file ==== Must-haves - Presentation of all components & patterns, interactive and the underlying code - Presentation of props/slots/actions/events per component/pattern - Presentation of all component/pattern types, even obscure ones - Demos include code samples that can be directly referenced for usage (e.g. a user should be able to copy/paste a code sample to use as a starting point) - Presentation of icon tokens, including all language variants ==== Nice-to-haves - Interactive (hot module reloading) presentation of components/patterns ==== Nice-to-haves - Presentation of all component states - Presentation of involved tokens building the component/pattern - Open source tool with big developer community to build on progress and maintenance from the outside - Similar underlying technology (not far off Vue.js) - Plugin ecosystem to build on top -- (Technical) Accessibility plugin -- Responsive viewport plugin -- Visual impairment filter plugin -- Measurement plugin -- Themability plugin (dark/black/white…) - Adding components/patterns to demo is simple without a lot of technical finesse - JavaScript knowledge is not needed to edit documentation - Editing documentation requires only knowledge of Markdown - Low dependencies - Long-term maintenance simple and reliable. - On brand with Design Style Guide - Visual regression tooling ==== Alternatives: VitePress Now that we have decided to use Vite to build the new library, we may want to consider VitePress, a Vue-powered static site generator built with Vite (as opposed to VuePress, which is built with Webpack), or other options. --- ===== Exploration I've been building a proof-of-concept static site with VitePress [[ https://github.com/AnneTee/wvui-next | in this repository ]]. [[ https://elastic-elion-823fb5.netlify.app/ | You can visit the static site here ]].