05) CSS Components
The following features were identified as critical for success:
- CSS components are as simple and easy to use as possible
- We aim to load as little extra code on the page as possible to support these components
We considered two main implementation paths for CSS components:
The Less mixin approach
This involves exporting Less mixins that contain component styles. Developer users would apply these Less mixins to their own markup in their own style files. This gives developer users more flexibility in terms of markup: they can apply the mixins to whichever elements and selectors they choose. However, it means that the same styles could be applied to many different selectors on a page, increasing the overall size of the styles. It also requires use of Less, which is used in MediaWiki but is not as popular elsewhere. Finally, it would require changes in the Codex library to remove styles from Vue single file components (SFCs) and move them into separate mixin files, which makes writing and maintaining component code more difficult both for library maintainers and new contributors.
The CSS class approach
This means keeping the styles as-is in the Vue SFCs, exporting the styles separately from the Vue components (which we already do), and providing recommended markup and CSS classes for developer users to copy. This is similar to how Bootstrap works. This allows us to keep the styles in the SFCs and is easy to use: you simply copy the markup we recommend, or add the CSS classes to your own markup. One downside to this approach is that the markup for some components can get fairly long and include things like ARIA attributes. To ease this burden, we could add a markup generator in MediaWiki that could generate markup for a CSS component based on provided parameters. This approach also currently means loading the CSS for all components in MediaWiki since there is no concept of code splitting—in the future, a build step or system for generating a dist CSS file with only some components would help.
We decided to use the CSS class approach for its simplicity and maintainability. We'd like to develop solutions for markup generation and code splitting to reduce some of the downsides of this approach.
- We now have a set of easy-to-use CSS-only components available in Codex that follow the design system and can be used anywhere
- We provide copy-able code samples on the Codex docs site (e.g. Button) for CSS components
- We need to consider markup generation in MediaWiki and code splitting
Further reading: https://phabricator.wikimedia.org/T323179