Page MenuHomePhabricator

Decide where the code for the shared component library should live and how it should be governed
Closed, ResolvedPublic



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.


Existing component libraries in the Wiki-verse
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 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 (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:
  • 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)


1. Which codebase, existing or new, will serve the canonical, shared component library?

Design Systems Team Proposals

1. Transition WVUI from an experiment to the canonical shared library 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)
1. Most efficient from the Design Systems Team perspective, which has limited resourcing and really wants to deliver a usable shared library ASAP so product teams/WMDE/volunteers can focus on higher-level, complex problems
2. Initial churn won't affect many people
3. WVUI has a rigorous process for component review and contribution, and volunteers are already contributing to it
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
2. Transition WiKit from WMDE's Wikidata/Wikibase design system to the canonical shared library 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
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)
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
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 (documentation, design tokens?)
3. WMF eventually has to migrate features to WiKit, which impacts the Design System's Team's timeline to provide the shared library
3. Start a new codebase for the canonical shared library and add bits and pieces from the different libraries 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)
1. Starting fresh seems fair and allows us to re-evaluate all the existing work again
2. Initial churn affects no one
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
3. Everyone eventually has to migrate to the new library
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).


**Summit participants voted to begin a new shared component library from scratch in order for it to be a truly shared project. Neither Wikit nor WVUI will be converted into the canonical shared library, but existing code from both places may be adapted in some capacity. A dedicated task force that includes representatives from key teams at WMF and WMDE will spearhead the creation of this new shared library and will make some key decisions about where code is hosted, library name, contribution policies, etc (soon). This library will also implement the governance model developed by WMF and WMDE designers at the designer summit. Guiding principles were discussed and will be finalized asynchronously and documented in the new library.

See T288980 for more details about future work.**

Event Timeline

AnneT updated the task description. (Show Details)

@karapayneWMDE This task covers the shared component library governance discussion we plan to have at the Developer Summit next week. I would love to get some feedback from you and your colleagues on the 3 proposals I've laid out for the future shared component library (see the poorly formatted table in the task description). Who would be good to include on this ticket to provide that feedback? You or anyone else are welcome to edit the task description directly. I would especially like to know additional pros and cons from your perspectives for the different proposals (the existing ones were written with my own WMF/Design Systems Team bias).

AnneT updated the task description. (Show Details)
egardner updated the task description. (Show Details)