Theme creation tips

Advice, tips and suggested best practices for theme creators.

Identify your plugin CSS

A common practice in modular or collaborative coding projects is to encase parts of code within comments to clearly indicate what each section does. Since all Marketplace themes share a common stylesheet, embracing this practice makes it easier for anyone inspecting the campaign_plugin.styles sheet of a given campaign to identify the origins of any troublesome rule and find the right creator to contact, or the right plugin to disable. Here is a suggested format for identification:

/* BEGIN <plugin name> by <creator> */
...
/* END <plugin name> by <creator> */

Note that Kanka now inserts its own "begin" comment in the stylesheet, with the plugin name and version number, but no end comment. I prefer to have both so I don't have to find the start of a plugin to know what it is when scrolling towards the top.

Of course, it’s always helpful to include additional comments as you see fit to explain particular sections when your plugin is particularly extensive, or if you have rules whose purpose may not be clear. This helps others troubleshoot any issues that might arise with your plugin in the future, but also helps people using it as a basis for their own work.

Choose your IDs and classes carefully

At the time of writing, the Marketplace is a fairly recent addition to Kanka and overlap isn’t much of a concern, but keep in mind that users can have any number of plugins installed and you can’t foretell what other plugin creators will add to the mix (or what will be introduced into Kanka itself in the future). To avoid conflicting rules and unintended shared names, you should endeavour to use unique names that will stand the test of time. A fairly sure-fire way to achieve this is to include your username or an abbreviation of your plugin’s name in your classes and id’s; for example, div.bobs-handwritten-quotes is far safer than div.quote.

@import rules

It is often desirable to use custom fonts in campaign CSS and themes, and the best way to add fonts that aren't already installed on Kanka is by using @import rules to request fonts from services such as Google Fonts. However, @import rules only work when they are placed at the top of a stylesheet (comments notwithstanding):

Valid ✅ Valid ✅ Invalid ❌

Valid ✅	Valid ✅	Invalid ❌
`@import url('...'); body { ... }`	`/* Any number of comments */ @import url('...'); body { ... }`	`body { ... } @import url('...');`

@import url('...');
body { ... }

/* Any number of comments */
@import url('...');
body { ... }

body { ... }
@import url('...');

Since all Marketplace themes share a single stylesheet (campaign_plugin.styles), you should place your @import rules in the Font Rules field, as described in the docs. @import rules from all themes are moved to the top of the stylesheet as long as they are correctly specified this way.

Adapt to each campaign’s or user’s base theme

Since 1.17, the <body> tag contains a data-theme attribute that can be referenced in your selectors to make some assumptions about the end user’s overall color scheme. For example, you might want to use a darker background image on Dark and Midnight. This attribute is not present on the Default theme.

To get the most up-to-date list of such variables, I suggest switching to the Dark theme on your campaign and inspecting the dark.css stylesheet. Remember that you can add ?_theme=dark to any Kanka URL to view the current page in a different theme without changing your user or campaign preferences! See Introduction to campaign CSS — Themes and custom properties for details.

See also Introduction to campaign CSS — Query parameters for useful URL parameters you can use to test your plugins in various themes and states without changing your user or campaign settings back and forth.

Last updated 7 months ago