Design System Team/Vue and Codex for non-Developers

What is Vue?

Vue (pronounced "view") is a popular, modern JavaScript framework for building user interfaces. This frameworks guide the developers to create a modular tree of clean HTML/JS/CSS elements, agglomerated into component, then web pages (web views) and web app. Built-in features ease the creation of interactions and synchronization with complementary databases.

What is Codex?

Codex is the design system for Wikimedia that is aligned with the Wikimedia Design Style Guide.

DSG + Vue = Codex

Codex consists of:

1. Out-of-the-box, interactive components (e.g., button, dialog, menu). Some components are also available in a CSS-only version for use in no-JavaScript contexts.
2. Standardized colors, shadows, spacing values, backgrounds, borders, and paddings, called design tokens. These are the smallest building blocks of the design system: they define, document and enable the application of systemic design decisions at scale.
3. Icons which can be used to convey actions or other information visually.

What is the difference between Vue and Codex?

You can build features in Vue without using Codex; however, the Design System team encourages teams to use Codex and recommends against teams building their own components when Codex versions are available. 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 is Pinia?

Pinia is a JavaScript library that works with Vue to help keep track of the "state" of an app. For example, if you're building a search page, you might use Pinia to keep track of things like the current search input, how many results are being displayed, and what filters are being applied. Pinia makes all of this data available across an entire app, so it's easy to get or update that data from any component. It makes developing complex features much easier and faster, and makes code easier to maintain and update in the long run. Other reactive state managers include Vuex, Redux, and Mobx.

What are long-term benefits of adopting Vue or Codex?

While adopting Vue or Codex might mean more time spent on learning and experimenting during design and development, and longer project timelines, the long-term benefits are:

• Less feature redundancy
• Consistent user experience across all Wikimedia projects
• Accessible and multilingual by default
• Standardized browser and device support
• Faster onboarding
• Faster software upgrades
• More time available for high-leverage work, less time reinventing the wheel

Is my project a good fit for Vue or Codex (whether starting from scratch, or migrating from another library)?

As an initial guide to making this decision, review the project with your team's engineers against the following criteria:

Criteria	Explanation
Project is mostly front-end	Vue migration will have the most positive impact in front-end-centric projects.
Project only needs components that already exist in Codex (or can be added there in the very near future)	We want to encourage development of the shared component library across foundation projects; this avoids new duplicate implementations of existing components being created separately in each project codebase.
Project is constrained by significant performance, caching, SEO, etc. requirements.	We do not (yet) have good support for server-side rendering of Vue components in MediaWiki. Features which must be available to search crawlers, logged-out users, users without JavaScript, etc. will still require the development of a separate server-rendered UI for the time being.
Project is under active development, or in need of refactoring	Porting a project under active development to Vue would result in immediate developer productivity gains
Project has high visibility and serves many users	This will help make the benefits of using Vue more apparent.
Project is lower visibility or serves lower number or users	Lower-stakes projects are good candidates for early migration so we can learn lessons before taking on critical pages or features.
Project has low exposure or is well-isolated	Code that only runs on one special page, or in very specific circumstances, can better afford to load the library.
Project includes extensive in-browser user interaction	Vue excels when we need to take complex input from the user and keep the rest of the UI in sync with that changing input at all times. Static presentations of data that require no user interaction will not benefit as much from introducing a modern JS framework.
Project is centered on fetching (or submitting) data from an API and displaying it to the user, as opposed to parsing wikitext/templates/etc	Vue works well as a decoupled front-end that talks to a back-end API over HTTP. A feature that needs deep integration with Mediawiki's PHP internals (the parser, templates, etc) will not see as much benefit from Vue adoption until we are able to do server-side rendering.

Jargon

Technical acronyms used in this page:

• Javascript, JS : ubiquitous coding languages allowing interactive behaviors and under-the-hood logic and calculations within the webpages or on servers.
• DSG : Design System Guideline
• WMF : Wikimedia Foundation
• RFC : Request For Comments, the most common democratic review process within the Wikimedian community
• DST : Design System Team
• SEO : Search Engine Optimization
• MediaWiki : the server-side software under online Wiki websites
• API : Application Programming Interface, the interface points to communicate with a program