Vue.js/OOUI migration guide

This page documents guidelines for migrating OOUI functionality to Wikimedia Codex components based on Vue.js. As the note above is already mentioning, this is currently only a draft and a collection of preliminary notes.

Context
OOUI is considered Wikimedia's gold standard for accessible, internationalized, and well-styled components. Without it, we would not be here today and its lessons are needed to step into tomorrow. Like any code it is imperfect but it encapsulates literal years of learnings and should be used as a frequent reference when building new components in Vue.js.

If you have invested heavily in OOUI, we hope you will take the time needed now to document how others can learn and translate that knowledge encoded in OOUI to Vue.js. This great migration requires great guidance and the efforts of many.

Migration guidelines
""Any fool can write code that a computer can understand. Good programmers write code that humans can understand.""

- Martin Fowler, Refactoring: Improving the Design of Existing Code

General

 * Focus on needed use cases first. For example, a button may not need to implement frameless or destructive styles initially but should assume hover, focus, and active states will be needed.
 * Split code requiring lengthier discussions into new patches and tickets. For example, if the template of a component is agreed upon but the styles are not, consider merging the template with minimal styles. There's a lot to migrate so completing even a partial component is progress.
 * Combine "frameless" into "quiet". Frameless is a legacy term for quiet. When migrating, collapse the two into quiet.
 * Avoid dependencies (explicit or implicit) and globals.
 * Some complexity in OOUI is due to browser compatibility. Some of these browsers have fallen off of the support matrix and should not hinder the new implementation.
 * Avoid inheritance.
 * Avoid unnecessary nesting. For example, the outer span in the following may be eliminated:
 * Use semantic HTML5. For example, favor button and anchor elements appropriately. For a component named button, the correct semantic HTML element to use is  for the current browser support matrix. It is possible to use an anchor but then the implementation must re-implement browser button functionality that is provided by default for proper button elements.
 * Always migrate accessibility features (ARIA roles and attributes following WAI best-practices), keyboard ( and  ), and internationalization (for example, directionality) styles and functionality.
 * Port existing or add missing documentation. What you write should be maximally readable.

Styling

 * Use BEM CSS / Less conventions. Long term conventions are being discussed but BEM should be used in the interim.
 * Use wikimedia-ui-base for Less variables whenever possible.
 * CSS classes should separate common properties into the default class (for example, ) and state properties into state classes (for example,  ). This means that specifying only   is an invalid presentational state but that will be enforced by a default component state enumeration property in Vue.js.

For example, the CSS class  may be an unsupported presentation by itself, as a CSS implementation detail, but   or   are valid CSS class name configurations. Class names can be configured by the component's properties and computed state:
 * HTML attributes should be favored to class names. For example,  instead of   on an HTML `button`.

OOUI component states
The following states are generally supported and should be migrated:
 * Default or normal
 * Hover
 * Active
 * Focus

Additional states to migrate as needed:
 * Visited
 * Disabled
 * Checked or toggled

OOUI component progress action types
The following types are generally supported. Always migrate the default but only migrate progressive / destructive as needed:
 * Default or normal: generic action consequence
 * Progressive: an action that moves forward
 * Destructive: an action which destroys or has potentially negative, dangerous, or irreversible effects

OOUI component boundary and background styles
The following box boundary styles are generally supported. Always migrate the default but only migrate the rest as wanted:
 * Default or normal
 * Quiet (the legacy name is frameless): no border and no background