Problem
On-wiki, the Vector skin uses a 14px base font size, while MinervaNeue uses 16px. These do not necessarily correspond to desktop and mobile, respectively, because you can use either skin on any viewport size.
Because of this difference in base font size, in Figma, Codex components are documented at both font sizes:
However, this distinction is MediaWiki-specific. Following our guiding principle to support the wider Wikimedia ecosystem by maintaining platform-agnosticism, in the code implementation of Codex components, a base font size of 16px is used. On the Codex docs site, components are only shown in a 16px context. We have a custom build process to produce multiple CSS files, ones that work in a 16px context and ones that work in a 14px context. These CSS files are then made available in MediaWiki and used by the skins.
Because the docs site, which contains demos of components meant to demonstrate all of their variants, does not show components at 14px, designers often cannot see a working example of a component as it will appear in Vector. This leads to confusion, especially since the components at 14px are not directly scaled from 16px in an intuitive way.
Potential solutions
Show components in a 14px context on the Codex docs site
This solution would involve adding a way for users to view the component demos on the Codex docs site in a 14px context. This might be accomplished via a theme or font size switcher.
Pros:
- All of the carefully curated component demos on the docs site would be available at 14px
- All implementation documentation lives in one place
- The text size of components Demos and the components Guidelines match
Cons:
- Design and implementation of this feature would be complex and time-consuming
- We'd be introducing something MediaWiki-specific into the docs site and codebase
Considerations:
- If we provide a switcher, we should carefully consider how to present it. We should remain as MediaWiki-agnostic as possible (not showing "Vector" or "MinervaNeue"), avoid correlating 14px with desktop and 16px with mobile, and make the options clearly understandable by our users
- Would just the component demos be shown at the chosen font size, or the whole site?
Build a demo page on-wiki
For this solution, we would replicate the component demos on the docs site on-wiki, so they could be viewed in any skin.
Pros:
- This keeps the MediaWiki-specific stuff in MediaWiki, and is true to the actual difference here (it's really about skin vs. skin, not font size vs. font size or desktop vs. mobile)
- We've already built a version of this in VueTest
Cons:
- The way VueTest was updated was very non-ideal, to the point that we recently decided to kill it. We would need to figure out a more sustainable way to keep VueTest in sync with Codex
- This would be a separate location from the docs site, distributing our documentation more
Considerations:
- We'd need to install VueTest on some test or beta wiki to make it available to the design team
Here's a screenshot from the page generated by VueTest, showing a variety of Lookup demos:
Acceptance criteria
- Discuss the options asynchronously
- Propose a solution to the design team and get feedback
- Open tasks to implement that solution