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 complicated js or something that needs to work exactly so (and why the hell would you in a skin?!), don't test chrome unless you're actually used to using chrome. 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 complicated js and crap 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:  Everything around that is just filler you mess with to make the site navigable and pretty.

The actual bloody 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:
 * 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.

But don't take my word for it. Actually check the files. Also you can probably delete any random things that say 'composer' or 'grunt' or whatever in the filenames. Not really sure why those are in the example skin. That's a bit confusing.

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.

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)

Do some form styling maybe
This is also 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.

Even so, you may want to put this off until you have everything else styled. Either way works, though I do find it's a good way to test out the LESS variables. Turn the main colours into some buttons or stuff, use the greys for some inputs.

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. We don't care about these because they don't work now. Maybe they will later. We'll worry about that later.

I usually just copy the entire thing out of skin:GreyStuff because I'm lazy and I already did it once there, but that skin's forms.less is a mess so I don't actually recommend doing that in practice. Just, uh, do whatever. Check some special pages and see where your styles work and don't. Once you have Special:Preferences and the page editing form styled, you'll have 90% of all MediaWiki forms done.

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.

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.

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  to their elements in your SomeSkinTemplate.

They should disappear in print mode.

Relatedly, you may want to also add a definition for  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.