User:Isarra/How to make a skin

Making a skin is easy.

First some notes/considerations/advice

• If all your styles disappeared, it's probably because there's a syntax error in your LESS. Usually a missing semicolon or brace or mistyped variable name.
• LESS variables and simple mixins are your friends; excessive includes and nesting and programming logic are not. Set up common styles and reuse them everywhere. Your end result with be a much more coherent design this way. Also easier.
• Set up a local test wiki before you start and run the in-progress skin code as you go to see how it looks. It's a skin. It's all about looks.
• Unless you're doing particularly complicated css/js that needs to work exactly so, don't test chrome unless you're actually used to using chrome. It's mostly standards-compliant anyway, and it does a lot of really weird things that will more likely than not just confuse you. Yes, the weird highlighting is by design. The on-click hover stuff is intentional. The fonts are just how they are. Don't read into it.
• Don't do overcomplicated programmatic stuff in a skin.
• Some things do require database queries to effectively pull off. If you know SQL, don't worry about it. Try to be efficient. Or just do something else. You don't actually need to get the largest two categories the page is in to put in the breadcrumbs, do you?
• The only really important part of the page is the content: $this->html( 'bodycontent' ); Everything around that is just filler you mess with to make the site navigable and pretty.

The process

Sometimes with real blood.

Step one: Copy the Example skin and rename it

Copy or clone or checkout it however. It's public domain, so nobody really cares how.

• Download a tar via mw.org
• Clone from Gerrit or off GitHub
• Whatever. You probably want master, unless you're making your skin for a pre-1.25 wiki, in which case download the one for 1.24 or whatever. If there is one. That's really old.

Then rename it. Update the filenames and the file contents. Suppose your skin is called 'SomeSkin'. All instances of 'Example' become 'SomeSkin'. All instances of 'example' become 'someskin'. Mind the case.

At current count, this should be something along the lines of:

• The parent directory
• Three php files which also need to be renamed
• Two json i18n files
• The skin.json file
• One comment in a LESS file (in resources) that you don't actually need to change because it's just a comment in a LESS file.

Now install your skin and make sure it actually shows up and works. It should look exactly the same as Skin:Example. A nearly-naked eyesore of a page with a logo floated to the right of the content.

Step two: Figure out what you're doing

What are you making? Are you making it complex and responsive with different layouts for different screen sizes? Are you trying to support IE6? What does the html structure need to look like to make it all work?

Wrap that html structure around the php and stuff in the execute() function (or helper functions) in your SomeSkinTemplate. Move things around. Delete any unneeded helper functions from the bottom, or make some new ones.

The vast bulk of making you skin will consist of mucking around with the html structure in your SomeSkinTemplate and writing CSS. Or LESS. Or whatever. LESS is just CSS dressed up all fancy anyway.

Step three: Styles

Set up some LESS variables

Totally optional, but generally a good idea. The example skin comes with a 'variables.less' file. Put some colours in that. @blue1, @blue2, @luridgreen, @bloodyaxe, @purple. Some white and black for background and text, and a bunch of soft greys for random interface stuff. Now you can reuse all these colours in your other LESS files and they'll be consistent.

Good rule of thumb is:

• 2-3 main colours for your overall design, with two to three brightness variants of each
• A text colour (probably black)
• A background colour for the content (probably something whitish)
• A bunch of greys ranging from actually stands out to so faint it might as well be white. Use these for borders and subtle backgrounds and stuff. (usually things from #aaa to #f6f6f6)

Set up the general styles

If you're doing different layouts for different screen sizes, figure out what goes in which stylesheet now. Add any other needed ones to skin.json. Then just style everything. Set your common styles, make your mobile layout, make your fancy-arse tools out the wazoo giant desktop screen. Or whatever. It's your skin.

If you need containers, ids, whatever, add them to your SomeSkinTemplate. That's what it's there for.

Do some form styling maybe

This is completely optional. Popular skins from 2005 like Monobook and Vector don't do this. But are you making a skin from 2005? No, this is a skin from 2024.

You'll want to make a separate LESS file for this. Just call it forms.less or something. Add it to the skins.someskin module in the skin.json. Plop in some styles for form elements. Inputs and buttons and textareas. MediaWiki has a lot of random classes and names for these, though, so you'll want to track them down and set up some rather horrifying selectors to catch them all, and override all the conflicting random styles that have also been added to core in the meantime. MediaWiki UI and oo-js and stuff. Reuse your colours.

Check some special pages and see where your styles work and don't. Once you have Special:Preferences and actions delete and edit styled, you'll have 95% of all MediaWiki forms done.

Step four: Testing

Go through a bunch of test pages and see how it all renders/what you missed.

I have a bunch of test pages on my test wiki. You'll probably want something like that. Regular pages, headers, subpages, interwiki links, weird permissions, run through the obvious or not so obvious. Check a bunch of special pages. Go from Special:SpecialPages. Check out Special:Search and Special:Preferences and Special:Version. See how bad Special:RecentChanges and Special:AllMessages look.

Other stuff you probably want

Fallbacks for stupid broken stuff

Check all the browsers you reasonably care about working. Fix them.

Some common things to add will include:

• js to make mobile actually work (there isn't enough space to put everything in without a ton of JQuery, so go ahead and add your ton of JQuery references. JQuery's already in core anyway, so you can just use it.) You may want to add another module for this. Add it below the js one in the skin.json and add its name to the addModuleStyles array in your SomeSkin.skin.php.
• CSS to make IE work
  • IE8 doesn't support @media queries with sizes, so you'll want to make a redundant module out of you desktop.less file and selectively load that if IE8. I usually just make the main js check the browser and load it there.
  • IE9- don't support flexbox (properly), so make some float rules for them to fall back on or something if you used that.
• JS to make safari mobile work
  • Don't look at me. I can't afford apple.

noprint and nomobile

To set up the print layout, don't worry. MediaWiki mostly does this for you. Just go to print view, see what things are still showing up that you wouldn't want printed, and add class="noprint" to their elements in your SomeSkinTemplate.

They should disappear in print mode.

Relatedly, you may want to also add a definition for class="nomobile" to your mobile stylesheet if you have one, since some things on-wiki may also use that and expect this sort of behaviour too. Just on mobile.

There. You have a skin.

Congratulations. Go request a gerrit repository for it or something.