== Goal
#Codex **is set out to be themeable** in order to
1. **be used outside of Wikimedia context and**
2. **be adaptable within Wikimedia for different use cases like MediaWiki skins.**
Clarify the use cases and find technical abilities and limitations.
---
==== Existing theme documentation (design/development)
* **Wikimedia Design Style Guide**: Theming has not yet been made a part of the [[ https://design.wikimedia.org/style-guide/ | Design Style Guide ]].
Only existing documentation in Wikimedia context is around
* **[[ https://www.mediawiki.org/wiki/Manual:Skins | MediaWiki skins ]]** (a historic mess) and
* **[[ https://www.mediawiki.org/wiki/Special:MyLanguage/OOUI/Themes | OOUI themes ]]**
** (three out of box, template Default, WikimediaUI – the DSG derived and Apex – used in MW Monobook skin)
==== Existing implementations
===== Wikimedia
**MediaWiki Core**
Additionally to skins, different folks including myself, @Volker_E have worked in the past on a low-level framework to bring central style decisions to skins:
* mediawiki.skin.defaults.less – definition of all agreed on stylistic pieces to provide to skins. If a var isn't defined here, it's not supported to be replaced by RL in the skin
** mediawiki.skin.variables (fallback pointing at above for skins that don't define variables file themselves)
**MediaWiki Skins**
* mediawiki.skin.variables (currently used by Vector and MinervaNeue, copies of each other with Wikimedia Design Style Guide/Codex equivalent values)
**OOUI**:
* OOUI provides the two themes, which a skin can choose from. Monobook uses Apex theme, Vector, MinervaNeue and all others WikimediaUI.
The themeability of OOUI is technically burdensome and outside of the default theme provided, no other themes have been worked on in the years of its existence.
=== Open questions
1. How should our theming approach be? **rigid** or **flexible**?
Design System talked about what theming approach to follow. We've agreed that it won't be goal-oriented to provide an everything goes path in Codex. We don't want theme to support major UX issues, like fully broken minimum interaction sizes/touch areas.
2. Is the technical path of JSON tokens and Style Dictionary provided sufficient?
Currently we end up with different CSS/stylesheet files that need to be set/replaced when using/changing themes. Or chained together in case of theme overrides.
Alternatives:
- Generated styles via JS, which Vue 3 supports, but it would be difficult with a server-rendered UI
- Include themes as Vue plugins
=== Implementation notes and challenges
**Developer/themer experience**
**Default theme with other theme featuring overrides **
As theming is a burdensome and error-prone activity, we assume that providing a default theme as fallback and theme overrides might be the designer/developer friendliest solution.
We don't want to end up in a situation, where a themer needs to keep 5000 attributes/tokens in sync with the main theme and has to provide decisions for each and everyone.
Premise, that most needs are covered by changing colors (or gradients) and possibly other visual attributes like border size/border radius
Possible way out is to work with an inheritance model, having theme modifications only be applied on top of a default theme.
Pro
- Themers are freed up from caring about a large number of visual attributes
Con
- As long as you don't define all properties you can't achieve a clean slate, meaning there will be default visual decisions lurk into override theme. That on the backside would mean we should consider a default (orienting on CSS and HTML defaults) looking theme to start with.