Design System Team/FAQs
Vue.js FAQs
[edit]Why are we using Vue.js for the Codex Design System?
[edit]In 2019, the Wikimedia Foundation convened a Front-end Architecture Working Group (FAWG) to discuss ways to modernize and improve the way that user interfaces (UI) are developed across Foundation projects. One of the recommendations of the FAWG was that we adopt the Vue.js JavaScript framework for use in certain new features. Codex, our new Vue-based component library, builds on top of this decision. Our goal is to give teams new and improved ways to build UIs that align with the overall Wikimedia design system, and which prioritize accessibility, internationalization, and usability.
When should my team start to use/implement Vue.js?
[edit]Depending on your team’s use-case, you may be able to start using Vue and Codex right now. Features like dashboards, special pages, and contributor tools are often well suited for this. Non-MediaWiki microsites are also great places to start using Vue and Codex right away.
Some teams are working on features that have more constraints in terms of performance, backwards-compatibility, or other requirements – for example, features that show up at the top of every article page must operate within a very strict performance budget. The Design System Team is working on unblocking the use of Vue and Codex in more highly-constrained areas, but Vue and Codex are not necessarily suitable for every feature at the moment. The Design System Team is currently working on some infrastructure projects to enable teams to use Vue and Codex more widely across our projects in the near future.
If your team is interested in Vue or Codex but not sure if your project is a good fit, talk to us (for Wikimedia Foundation staff: #talk-to-design-system-team Slack channel) and we can help you strategize.
Do I need to use Codex in order to build features in Vue.js?
[edit]The Design System team encourages teams to use Codex when they build features in Vue.js, and recommends against teams building their own components. If Codex doesn't provide all the components you need, we ask that you use Codex components where possible, and build your own components as “one-offs” where Codex doesn't have what you need yet. Those components could then be upstreamed (moved into Codex) in the future.
What are the steps to add Vue.js to a MediaWiki extension? Is it as simple as installing Vue?
[edit]In order to use Vue in a front-end feature, it's as simple as creating a module (using the ResourceModules section in extension.json) that contains a .vue file and lists the vue module as one of its dependencies.
If you want to write unit tests for Vue code you will have to add Vue (and other things like the Vue plugin for Jest) to the devDependencies in package.json.
See also: Vue.js#Guidelines
Design System FAQs
[edit]Why are we investing in a Design System?
[edit]Our goal is to provide an easy-to-use and extensible way to design and build user-interfaces for Wikimedia projects by following a universal Design Style Guide by a shared and comprehensive development kit that codifies the visual and experience principles and guidelines:
- Less feature redundancy
- Consistent user experience across all Wikimedia projects
- Web-accessible and internationalization by default
- Standardized browser and device support
- Faster onboarding
- Better designer and developer experience
- Faster software upgrades, time-to-product
- Systems thinking: teams make an impact outside of immediate focus area
Please also see History of user-interface libraries and frameworks in MediaWiki.
What is the role of the Wikimedia Design System team?
[edit]The Design System team are the stewards of the Codex Design System, helping to lay out the design foundation and to unblock common design and front-end challenges shared across user-interface contributors..
Does Codex support web and native-mobile experiences?
[edit]Currently Codex mainly supports web use cases. However, part of our design system includes a set of Design Tokens which are platform-agnostic, and could be used to bring greater consistency between our products across various platforms (Web, iOS, Android, etc).
What about existing UI toolkits such as OOUI, etc.? How do they fit in?
[edit]OOUI is widely used and we don’t see it going away any time soon. The Design System Team brought the lower-level Design Tokens from Codex into OOUI to mitigate visual inconsistencies between it and Codex components. Codex predecessor WVUI got retired in favor of Codex and can't be used in MediaWiki context anymore.
What types of components does the Vue.js component library support?
[edit]https://doc.wikimedia.org/codex/latest/ contains the most up-to-date components, design tokens, and icons.
What types of components should be built into Codex?
[edit]Codex is a UI component library, so we want to eventually include most of the common interface elements that developers would need in a user-facing website or feature – similar to the list of components you would see in a project like Bootstrap or Google’s Material Design. Components should be reusable and low-level, and are not meant to be specific to MediaWiki or Wikipedia.
If we need a new component to support a feature, what should we do?
[edit]We believe that the Design System Team can have the most impact by helping other teams to develop the components they need, rather than trying to do everything by ourselves. If teams are working on a feature and realize they need a component that does not yet exist as part of Codex, we encourage them to create it themselves. DST engineers and designers can work with their counterparts on other teams to help develop components that fit in with Codex’s development practices and design system. Codex is an open-source project and it needs a large pool of contributors in order to thrive.
How do I know that components have been vigorously tested?
[edit]We have documented guidelines for testing Codex components which covers a range of scenarios to ensure compatibility, functionality and accessibility. Following these guidelines, as well as exploring edge cases specific to each component, will ensure a good measure of quality.
When can I use Codex visual styles design tokens?
[edit]As of November 2022, we are currently working on making the design tokens available as npm package alongside the other Codex tokens, they should be available for use in your project in the coming weeks.
When should we use Codex design tokens?
[edit]Generally always! It’s important for design and UX consistency and cheap to use. Using tokens provides the Foundation with all flexibility and consistency in design decisions. Imagine a change in Wikimedia/Wikipedia branding or user-experience centered design improvements. With help of tokens, those changes are brought to your product in a breeze.
Can I use tokens if I am not using Codex?
[edit]Yes! And similar to one-off component development it’s useful to orient around the Codex tokens architecture (nomenclature and philosophy) to enable identifying gaps and place for improvement and aim to upstream to Codex in the mid-run. Please also be welcome to reach out about any questions on possible gaps to the Design System team.
Do we support accessibility? How so?
[edit]Codex aims first-and foremost to be technically fully conforming to WCAG 2 level AA. On a similar level we aim for feature-parity to OOUI as long-term in production library with lots of accessibility learnings, and also exceeding its accessibility support where possible in its design decisions and implementation.