## 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?
#### Design principles
* See the governance model task (T287535) for guiding principles followed when creating that model
* Other potential topics that could be covered in documented design principles:
** Who are the library's intended users?
** Is the library MediaWiki-specific or agnostic? Will we prioritize making it usable by third parties?
** How will we enable customization, e.g. offering theming options, exposing shared JS code like composables/mixins, facilitating composition of components, etc.?
** How will we develop the library in a way that is maintainable, understandable to onboarding developers, etc.?
** Define measures of inclusiveness: it may seem like a given to us that we will meet certain accessibility, internationalization, and browser/device support metrics, but we could still explicitly define them as design principles
#### 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 Proposal**: Transition WVUI from an experiment to the canonical shared library, or start a new library for this purpose. This would include:s**
| Proposal | Process | Pros | Cons |
* Updating existing technology as needed (e.g. moving to Vue 3, switching to a new build tool, employing new design token architecture)| ---- | ---- | ---- | ---- |
<table>
* Welcoming feedback on existing WVUI code <tr>
* Continuing 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) <th>Proposal</th>
* Identifying other aspects of existing libraries that could be incorporated into WVUI (e.g. WiKit has excellent and extensive documentation that displays in Storybook) <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. Updating existing technology as needed (e.g. moving to Vue 3, switching to a new build tool, employing new design token architecture)
2. Welcoming feedback on existing WVUI code
3. Continuing 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. Identifying 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. Changing primary maintainer of WiKit from WMDE to the Design Systems Team
2. Figuring out how to transition the library while avoiding disruption of WMDE production features
3. Updating existing technology as needed (e.g. moving to Vue 3, switching to a new build tool, employing new design token architecture)
4. Updating documentation to reflect Wikimedia-wide processes and information
5. Feedback being welcome on existing WiKit code, including ensuring alignment of existing components with Wikimedia Design Style Guide
6. Using 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. Coming up with a cool new library name (this is not an insignificant amount of work!)
3. Determining what code from what libraries to move into the new library, and coming up with a review process (e.g. designated reviewers from certain teams)
4. Continuing 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. Everyone eventually has to migrate to the new library
</td>
</tr>
</table>
#### 2. How will the Design Systems team roll out releases and version those releases?
#### 3. 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.
#### 4. What are the library's design principles, and where will they be documented?
####