## Summary
Shared libraries often document guiding principles to describe the paradigms followed when designing, building, collaborating on, and sharing the library. These can include many different things depending on the purpose of the library and the priorities of the maintainers: visual design paradigms, code design patterns, collaboration principles, etc.
Some examples:
- [[ https://reactjs.org/docs/design-principles.html | React ]]
- [[ https://material.io/design/introduction#principles | Material Design ]]
- [[ https://getbootstrap.com/docs/4.0/extend/approach/ | Bootstrap ]]
Defining and documenting guiding principles for the future Vue component library could help us in the following ways:
- Communicate to our end users who the library is for: which users we intend to prioritize and what we intend to provide them
- Communicate to our collaborators how we intend to work with them
- Be a resource for resolving issues or conflicts when they come up
- Document high-level principles of the kind of code we want to write
---
## Proposal
The Wikimedia Design Style Guide captures [[ https://design.wikimedia.org/style-guide/design-principles.html | design-specific principles ]]. In the shared component library, we could cover the following (note: these are some initial ideas and the wording will need work):
### Who we're serving
* **End-user developer experience**: we want the library to make building UIs easy and fast. Let's aim to serve users of varying levels of experience and stick to existing patterns as much as possible.
* **Accessibility and internationalization**: Wikimedia aims to serve every human being, eventually. We'll follow [[ https://design.wikimedia.org/style-guide/design-principles_accessibility.html | Wikimedia's accessibility principles ]] and aim to support many languages.
* **To be determined: MediaWiki-specific, -agnostic, or something in between?**
** At the summit we discussed this initial proposed principle: "MediaWiki agnostic: the library should not depend on MediaWiki. Though many components are added to be used in features built within MediaWiki, the library should be usable outside of it."
** This may not be realistic or ideal for the following reasons:
*** OOUI did not see wider adoption
*** We don't have the resources to create a true platform-agnostic library (on par with Vuetify, for example) with all the support that goes along with it
*** This library is being primarily built for MediaWiki developers
*** Some components may get pretty MediaWiki specific, between use case (e.g. a wikidata field) and data format (e.g. how data comes back from a MediaWiki API)
** We could consider making components as agnostic as possible, but we should define what that means more clearly.
* **To be determined: mobile-first/mobile support**
** Historically, components have often been designed and built for desktop, with mobile being an afterthought that often requires extra work to fix on the mobile site. Should components be mobile first? If so, we should document this standard and make it part of our review processes.
### Collaboration principles
Note that these came from Sarai and Volker via T287535.
* **Transparency**: we work in the open and aim to provide consumers as much information as possible about what we're working on and how we're prioritizing that work
* **Enable rather than enforce**: the Design Systems Team welcomes contributions from others and wishes to collaboratively build resources to enable others to easily contribute to the library
* **Knowledge sharing rather than knowledge silos**: Contributors should have support and access to resources that allows them to understand and influence the system's workflows, methodologies, standards and infrastructure.
Note that there are additional, more specific collaboration guidelines in WVUI: [[ https://github.com/wikimedia/wvui/blob/master/CONTRIBUTING.md | contributing ]] and 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 ]]
### Code design patterns
* **Composition over complexity**: smaller components are easier to understand and more reusable
* **Clarity over brevity**: it's better for code to be easily understandable than to be as short or as clever as possible.
* **Use existing patterns**: sticking to patterns established in the greater front-end community enables more people to contribute. Following consistent patterns within the library makes the code easier to write, review, and maintain.
* **Keep the template simple**: The template within single file Vue components can be a tool to clearly illustrate what a component is and does. Consider moving everything but the most basic JavaScript code to the script tag.
Please feel free to comment on these principles or suggest additional ones in the comments!
---
## Acceptance criteria
[x] Propose an initial list of guiding principles at the Vue.js Developer Summit, or shortly afterward if there isn't time at the summit
[] Solicit feedback on additional principles to include
[] Discuss principles within this task
[] Document them in the shared library, ideally in a way that's visible in Storybook