## Summary
Should we officially "adopt" one of the existing component codebases (WVUI, WiKit, etc.) or start a new repository? What kind of policies around governance should we adopt for contributing, versioning, and more? We have already had many of these conversations in relation to WVUI; some/most of that work may apply here too.
## Considerations
#### Existing component libraries in the Wiki-verse
- **WiKit**: Wikimedia Deutschland's component library ([[ https://wmde.github.io/wikit/?path=/story/documentation-getting-started--page | Storybook ]])
- **WVUI**: Wikimedia Foundation's experimental shared library ([[ https://doc.wikimedia.org/wvui/master/ui/?path=/story/components-button--configurable | Storybook ]]). First developed by the Web team during the [[ https://phabricator.wikimedia.org/T255902 | Vue.js search experience project ]], now maintained by the Design Systems team
- **WMF team-specific libraries**: Language's [[ https://github.com/wikimedia/mediawiki-extensions-ContentTranslation/tree/master/app/src/lib/mediawiki.ui | MediaWikiUI ]], Structured Data's [[ https://github.com/wikimedia/mediawiki-extensions-MediaSearch/tree/master/resources/components/base | MediaSearch library ]]
- And more: see T272885 for a more comprehensive list
#### Some notes on recent WVUI work
The Design Systems team spent Q4 of FY 2020-2021 building new components in WVUI and thinking through library architecture, developer experience (DX), contributing guidelines and governance, and more. The goal of this experimentation was to help us come to a recommendation for a path toward a Vue component library that could be shared by the Wikimedia Foundation and Wikimedia Deutschland.
During this time, we maintained these priorities:
- Adhere to the [[ https://design.wikimedia.org/style-guide/index.html | Design Style Guide ]] (and Figma designs, if available). If we need to add a component that's not yet in the DSG, match OOUI design and accessibility standards
- Aim to offer similar functionality as OOUI, both to provide end users with all the tools they'll need to migrate their UIs to Vue, and to minimize cognitive overload of migrating from OOUI to WVUI. Exceptions: simplifying things if possible, use Vue tools when available (e.g. `v-model`), rethinking component architecture in terms of composition (versus the inheritance model in OOUI)
- For each component or set of components, create a task ([[ https://phabricator.wikimedia.org/T279714 | example ]]) that outlines:
- Existing versions of the component in the Wiki-verse
- Existing versions of the component in third-party libraries
- Existing design standards and resources for the component
- Possible implementations and their pros and cons
- Discussion, in comments, of what we think is the ideal implementation in terms of reusing existing work, following Wikimedia design standards, maintaining accessibility standards and other solved-problems from OOUI, DX for the library end user, maintainability of code and DX for developers of the library, and establishing/following patterns in the library itself
As a result of this process, we gained the following:
- A better understanding of how we can build and maintain a shared component library that will be useful to developer end-users, maintainable and scalable, collaboratively built, and adherent to Wikimedia design
- A process for thoroughly reviewing existing Vue work in the Wiki-verse to gain understanding of different potential implementations, re-use existing code whenever possible, and carry over lessons learned from developers who have been building with Vue within our ecosystems for a while now
#### Contribution policy
* WiKit and WVUI have some existing documentation about how to contribute:
** WiKit: [[ https://wmde.github.io/wikit/?path=/story/documentation-contributing--page | Contributing ]], [[ https://wmde.github.io/wikit/?path=/story/documentation-how-to-modify-existing-components--page | modifying existing components ]], [[ https://wmde.github.io/wikit/?path=/story/documentation-how-to-create-reusable-components-overview--page | creating reusable components ]]
** WVUI: [[ https://github.com/wikimedia/wvui/blob/master/CONTRIBUTING.md | contributing ]]
* How will we facilitate contributions from those outside the Design Systems team? What base work should be prioritized to enable more effective contributions, like getting the design token architecture implemented? What will the process be for teams that need a component that doesn't exist yet in the shared library?
#### Guiding principles
* See T288380 for draft guiding principles and discussion about them
* See the governance model task (T287535) for guiding principles followed when creating that model
#### Relevant links
* T272885: list of Vue projects and components in the wiki-verse (may be somewhat outdated; please update it as needed)
---
## Decisions
#### 1. Which codebase, existing or new, will serve the canonical, shared component library?
**Design Systems Team Proposals**
<table>
<tr>
<th>Proposal</th>
<th>Process</th>
<th>Pros</th>
<th>Cons</th>
</tr>
<tr>
<td>1. Transition WVUI from an experiment to the canonical shared library</td>
<td>
1. Update existing technology as needed (e.g. moving to Vue 3, switching to a new build tool, employing new design token architecture)
2. Welcome feedback on existing WVUI code
3. Continue to methodically and closely review existing work when adding new code to WVUI, carrying over lessons learned and actual code from that existing work (see notes above for more details on this process)
4. Identify other aspects of existing libraries that could be incorporated into WVUI (e.g. WiKit's documentation structure and design tokens visualization)
</td>
<td>
1. Most efficient from the Design Systems Team perspective, which has limited resourcing and really wants to deliver a usable shared library ASAP
2. Initial churn won't affect many people
3. We know everything adheres to the Design Style Guide and code design patterns/standards developed by the Design Systems Team
</td>
<td>
1. Could be viewed as WMF-centric
2. Extra work required to incorporate stuff from WiKit, which is a more robust library that's been developed for a longer time
3. WMDE eventually has to migrate features to WVUI
</td>
</tr>
<tr>
<td>2. Transition WiKit from WMDE's Wikidata/Wikibase design system to the canonical shared library</td>
<td>
1. Change primary maintainer of WiKit from WMDE to the Design Systems Team
2. Figure out how to transition the library while avoiding disruption of WMDE production features
3. Update existing technology as needed (e.g. moving to Vue 3, switching to a new build tool, employing new design token architecture)
4. Update documentation to reflect Wikimedia-wide processes and information
5. Make feedback welcome on existing WiKit code, including ensuring alignment of existing components with Wikimedia Design Style Guide
6. Use the Design Systems Team's process for closely review existing work when adding new code to WiKit, carrying over lessons learned and actual code from that existing work (see notes above for more details on this process)
</td>
<td>
1. Maintain all of the work done by WMDE, including existing components, design token visualization, thorough documentation, and robust storybook setup
2. Start from a place of direct collaboration between WMDE and WMF
</td>
<td>
1. Initial churn could disrupt WMDE features that use WiKit in production
2. Some adjustments would be needed to transition the library from WMDE-specific to Wikimedia-wide (update docs and contributing guidelines, slight adjustments to match design style guide, figure out what to do with Wikibase-specific components and component features)
3. WMF eventually has to migrate features to WiKit
</td>
</tr>
<tr>
<td>3. Start a new codebase for the canonical shared library and add bits and pieces from the different libraries</td>
<td>
1. Fresh start with all the technologies and standards we choose during the summit, plus everything that goes along with starting a new repository
2. Come up with a cool new library name (this is not an insignificant amount of work!)
3. Determine what code from what libraries to move into the new library, and come up with a review process (e.g. designated reviewers from certain teams)
4. Continue to methodically and closely review existing work when adding new code to the new library, carrying over lessons learned and actual code from that existing work (see notes above for more details on this process)
</td>
<td>
1. Starting fresh seems fair and allows us to re-evaluate all the existing work again
2. Initial churn affects no one
</td>
<td>
1. Starting from scratch means lots of initial boilerplate work
2. Re-reviewing code from both WVUI and WiKit will take a lot of time
2. Everyone eventually has to migrate to the new library
</td>
</tr>
</table>
#### 2. What is the contribution policy for changes and new components?
**Design Systems Team Proposal:** Follow the governance model developed by WMF + WMDE designers (see T287535), and continue to document tech-specific contribution policy info in the shared component library.
#### 3. What are the library's guiding principles, and where will they be documented?
**Design Systems Team Proposal:** As noted in T288380, develop these asynchronously first, potentially discuss at the summit if there's time or at a Front-end Standards Group meeting, then document in the shared library (and make visible in Storybook).
#### 4. How will the Design Systems team roll out releases and version those releases?
####