OOUI/Themes

Themes specify how OOUI interfaces look and feel. Skin authors can create additional themes and use them in MediaWiki.

Themes primarily provide the CSS, but they can also provide some JS code (in practice this is only used to implement icon variants) and custom icon images (not currently used in practice).

Built-in themes

Two themes are provided out of the box.

• “WikimediaUI” theme conforming to Wikimedia Foundation's design style guide. This is the default theme and in active development.
• “Special:MyLanguage/Skin:Apex” theme inspired by the skin of the same name. It receives maintenance updates only.

We do not plan to have more than two built-in themes due to the additional effort that would be required to maintain them.

Custom themes

It is possible to create custom OOUI themes. Note that this requires a lot of initial work and a lot of continuing effort to keep your theme up-to-date with OOUI changes.

OOUI themes currently must live in the same repository as the main OOUI source code (T76632), due to limitations of the build process.

To create a new OOUI theme:

1. Fork the OOUI repository, e.g. from https://github.com/wikimedia/oojs-ui.
2. Navigate to the oojs-ui folder and run npm install
3. Make sure you can build the library with grunt build and view the demo. To initialise the demo, run npm run-script demos and open /resources/lib/oojs-ui/demos/index.html in your browser.
4. Run grunt add-theme --name=FooBar --template=Blank, substituting your theme's name for FooBar. Rather than use the Blank theme, you can also start with Apex or WikimediaUI.
   • This will create a copy of the template theme under a new name, and tweak the build process and demos to include your new theme. Run grunt build afterwards to make the build process pick up the new theme.
   • Your theme's styles are now in src/themes/foobar/.
   • The theme names are case-sensitive; if you type the template theme's name in lowercase, you'll get confusing errors. You might want to name your theme with uppercase first letter too to avoid lint errors.
5. Write the styles for your theme!
   • Run grunt build (or grunt quick-build) to build it, use the demo to test your changes.
6. Regularly merge back the changes from the OOUI repository into your fork. We release OOUI every couple of weeks. You should probably do it at least for new MediaWiki versions (roughly every 6 months).
   • Although we don't usually make gratuitous changes that would require fixes to theme styles, they sometimes happen, and there probably won't be any warnings. Sorry. You can watch for changes in the Apex theme to spot things that are likely to affect your theme too (Apex is not in active development).
   • Even if there were no such breaking changes, you should still occasionally rebuild your version to include any changes to the base styles.

Using themes in MediaWiki

Every widget will use the theme defined by the current skin using SkinOOUIThemes in extension.json. To use a built-in theme, this is all you need to do.

To use a custom theme in your MediaWiki skin:

1. Run grunt build.
2. Copy-paste the generated files from dist/ (you will need oojs-ui-foobar.js and all oojs-ui-...-foobar.css, ignore the others) into a subdirectory in your skin. Also copy FooBarTheme.php from php/.
3. If you have custom images, also copy-paste contents of dist/themes/foobar/ and the .json files from src/themes/foobar/.
4. Define the theme using OOUIThemePaths in the skin.json file, and make your skin use the new theme with SkinOOUIThemes as before.

Example change using a custom theme in a skin: https://gerrit.wikimedia.org/r/c/mediawiki/skins/Example/+/343240