## 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.
* **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.
#### 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.
---
## Acceptance criteria
[] Propose an initial list of guiding principles at the Vue.js Developer Summit, or shortly afterward if there isn't time at the summit
[] Discuss them within this task
[] Document them in the shared library, ideally in a way that's visible in Storybook