Comrade:CriticalResist/sandboxColor theme picker documentation

The citizen theme has a settings menu available on both desktop and mobile through the gear icon located on the sidebar (a misnomer on mobile, where it is located at the bottom of the screen).

By using common.js, it is possible to inject our own javascript into this menu and add our own settings options. Ideally these options should later be moved to the skin's PHP files somehow to increase robustness but for now, they are on JS implementation.

Custom color themes, on top of the default Light and Dark modes, happen in two steps: JS definition, then CSS customization.

Tl;dr:

1. Append theme definition at end of array in Common.js script,
2. Go to common.css to customize theme as well as preview button in menu.
   1. Theme customize is in @media screen, after :root.skin-citizen-auto (near top of file)
   2. Button customize is "Custom BUTTON styling" (near top of file after @media screen def)

Adding a new skin

The first step is to open common.js and scroll down to the Custom theme switcher comment.

Near the top of that code is the following:

var themes = [
            { value: 'day',  label: 'Light', className: 'skin-citizen-light' },
            { value: 'os',   label: 'Auto', className: 'skin-citizen-auto' },
            { value: 'night', label: 'Dark', className: 'skin-citizen-dark' },
            { value: 'sepia', label: 'Sepia', className: 'skin-citizen-sepia', labelId: 'sepia-style-label' }
];

This is an array, and it contains all our themes. To add a theme, it is as simple as adding a line to this array that follows the format of the color themes above. That is to say, it needs a value definition, a label (this will show on the button in the settings menu), and a class name (I recommend following the naming convention skin-citizen-X).

Warnings about arrays: all items in an array need a , (comma) character at the end, except for the last item before closing the array, which must have no comma. Be careful about this, this is a common source of errors and will disable all custom JS if you save without placing the commas properly. When defining a new theme, add a comma to the last line, hit Enter, add your theme - in this order.

Do not change the order of themes in the array - it will break the easter egg theme(s) and will also move the themes selection buttons around which will be confusing to the readers.

Looking at the last theme in the array above (sepia), you will see that it also has a labelId field. This will determine the ID of the button itself. I recommend following the X-style-label naming convention, where X is the name of your theme.

(Some of this could definitely be simplified but this is how it works for now, you have to enter your own class and ID names)

CSS customization

All CSS customization happens in common.css.

Adding your theme to the CSS

Theme customization happens at the very top of the css file, where it begins with

@media screen{
	:root.skin-citizen-light {

Scroll down to the bottom of the @media screen container, just below :root.skin-citizen-auto (which is purposely left blank), and add a new line where you will select your new theme, following the same naming convention. So if your theme is 'forest', then you would add:

:root.skin-citizen-forest{
    //values go here
}

While making sure you are still declaring this selector within @media screen.

Actually customizing your theme's coloring

Citizen works heavily with CSS variables. I won't go into CSS variables here because it's its own course, but suffice to say this makes color swaps very easy on Citizen.

To build your actual theme coloring, you can simply use the Inspector tool, inspecting various elements on the page, and then figuring out which color variable they use. The other defined themes in the CSS will give you an idea of what variables exist but, at this moment, we have no documentation on the different variables (and neither does the Citizen github repo).

--color-surface-0 for example is the main background color, and --color-surface-1 is the secondary background color (used for submenus mostly).

Thus in your 'forest' theme, you can redefine them simply in the same way other themes redefine them:

:root.skin-citizen-forest{
    --color-surface-0:#hex;
    --color-surface-1:#hex;
}

You will very rarely (if not never) need to actually do your own properties. Most of the time you just need to redefine the variables.

You may want to style the sidebar, which you can do with: .skin-citizen-X .citizen-header{ } (still inside @media screen).

There is one limitation with our Javascript implementation: if a variable is set by another theme, and your theme doesn't overwrite it, it will remain with the same value when the user switches to another theme. This is why when adding a new theme, you should test it in various configurations to make sure you've properly redefined all relevant variables.

Selection button customizing

In the JS code, we add an ID to the button itself, i.e. the one that appears in the settings menu. This allows us to select the button directly with CSS. If you look near the top of the css file, a bit below the :root clauses, you will see Custom BUTTON styling as a comment.

This is where you will customize the selection button itself in the settings menu. By simply selection the button's ID with CSS, you will be able to customize the button to give a preview of the color theme that carries across all theme.

Simply look at the already defined ID's in there to understand how it works, but this is also an important step to do for your theme so the preview works correctly.

A caution on adding themes

Since custom themes simply add a button to a 3-cell-wide grid, it will quickly become overcrowded if we just keep adding themes. I can only urge caution in adding custom themes: make sure they are useful and serve an actual purpose, and aren't just a gimmick for people to say "huh, neat", and then switch off to an 'actual' theme, never to use it again. We write and design for the readers, and want to bring them useful features that they will use and will improve their experience.