How to create a custom theme

Table of contents

Examples

Example Theme / Theme Starter

There is an example theme that demonstrates all the possibilities.

The easiest way to start a new theme in a project is to go to the Design tab and install the “example” theme.

Then go to the Repository tab and edit the files.

Predefined themes

The example theme is just one of the predefined themes that Interkit comes with.

Check the themes folder in the interkit repository for the source code of all predefined themes and see how they are made!

Techniques of Customization in a Theme

Custom CSS

CSS knowledge required.

You can override the default CSS of the components by writing CSS in the app folder in static/theme/global.css. This file will be loaded after the default CSS, so you can override the default CSS.

See Component CSS for more information on how to come up with appropriate CSS selectors. Use #Theming to raise the specificity. Example:

#Theming .Icon {
  border: 1px solid black;
}

Loading of static/theme/global.css can be toggled using “Load Theme” in the settings of the Preview.

Custom assets

You can create a custom assets (static/theme/assets) folder and put your images, fonts, etc. in it.

You can then reference these assets in your global.css, for example as background images or use the :before and :after pseudo elements to add more images to the UI.

You can also import fonts this way.

Style Variables

Style variables are global variables that are used in all interkit components. You can start your theme by adjusting these variables. They are saved in the src/styleTokens.json file in your project. You can also edit this file directly.

See the list of variables
key type info
colorText color The default text color used in most places
colorTextStrong color A more intense variant of the default text color used in headers for example
colorTextSoft color A less intense variant of the default text color used for additional information
colorTextLink color The color used for links in richtext content.
colorBackground color The default background color used in most places
colorBackgroundHighlight color Background color that is used in modals, selected <BottomMenu> states and the popout <AudioPlayer> and other places
colorBackgroundBackdrop color Background color that is used in the backdrop of Sections and Chat background
colorBorder color The default border color used in most places
colorDummyAsset color The color used for dummy assets when no image is available
colorTextButtonPressed color The color used for the text of a button when it is pressed
colorBackgroundButtonPressed color The color used for the background of a button when it is pressed
colorTextButtonDanger color The color used for the text of a button when it is a danger button
colorBackgroundButtonDanger color The color used for the background of a button when it is a danger button
colorBackgroundButtonDangerPressed color The color used for the background of a button when it is a danger button and pressed
colorTextButtonPrimary color The color used for the text of a button when it is a primary button
colorTextButtonPrimaryPressed color The color used for the text of a button when it is a primary button and pressed
colorBackgroundButtonPrimary color The color used for the background of a button when it is a primary button
colorBackgroundButtonPrimaryPressed color The color used for the background of a button when it is a primary button and pressed
colorBorderButtonPrimary color The color used for the border of a button when it is a primary button
colorBorderButtonPrimaryPressed color The color used for the border of a button when it is a primary button and pressed
colorBackgroundLabel1 color The color for the background of a label, used in cards for example
colorTextLabel1 color The color for the text of a label, used in cards for example
colorBackgroundChatMe color The color for the background of a chat message sent by the current user
colorBackgroundChatOther color The color for the background of a chat message sent by another user
colorPagination color The color for the pagination indicator in PictureBook
borderWidth size The default border width used in most places
borderRadius size The default border radius used in many containers
borderRadiusButton size The default border radius used in buttons and in elements inside a container. Should be equal to borderRadius for best fit.
borderRadiusLabel size A smaller border radius used in labels
boxShadow shadow The default box shadow used in many containers. The default evaluates to a 1px border
googleFont googleFont url fragment for first font to load from google fonts
googleFont2 googleFont url fragment for second font to load from google fonts
fontFamilyInterface fontStack font stack for interface font (--font-family-interface)
fontFamilyContent fontStack font stack for content font (--font-family-content)
fontHeadline1 font text style for interface headlines 1
fontHeadline2 font text style for interface headlines 2
fontHeadline3 font text style for interface headlines 3
fontHeadline4 font text style for interface headlines 4
fontHeadline5 font text style for interface headlines 5
fontBody1 font text style for interface body 1
fontBody2 font text style for interface body 2
fontSubtitle1 font text style for interface body 2
fontSubtitle2 font text style for interface Subtitle 2
fontButton font text style for interface buttons
fontCaption font text style for interface captions
fontCaptionBold font text style for interface captions (bold)
fontOverline font text style for interface 'overline' style
fontContentHeadline1 font text style for content headline 1
fontContentHeadline2 font text style for content headline 2
fontContentHeadline3 font text style for content headline 3
fontContentHeadline4 font text style for content headline 4
fontContentHeadline5 font text style for content headline 5
fontContentBody1 font text style for content body 1
fontContentBody2 font text style for content body 2
letterSpacingHeadline1 size letter spacing for interface headlines 1
letterSpacingHeadline2 size letter spacing for interface headlines 2
letterSpacingHeadline3 size letter spacing for interface headlines 3
letterSpacingHeadline4 size letter spacing for interface headlines 4
letterSpacingHeadline5 size letter spacing for interface headlines 5
letterSpacingBody1 size letter spacing for interface body 1
letterSpacingBody2 size letter spacing for interface body 2
letterSpacingSubtitle1 size letter spacing for interface Subtitle 1
letterSpacingSubtitle2 size letter spacing for interface Subtitle 2
letterSpacingButton size letter spacing for interface buttons
letterSpacingCaption size letter spacing for interface captions
letterSpacingCaptionBold size letter spacing for interface captions (bold)
letterSpacingOverline size letter spacing for interface 'overline' style
letterSpacingContentHeadline1 size letter spacing for content headline 1
letterSpacingContentHeadline2 size letter spacing for content headline 2
letterSpacingContentHeadline3 size letter spacing for content headline 3
letterSpacingContentHeadline4 size letter spacing for content headline 4
letterSpacingContentHeadline5 size letter spacing for content headline 5
letterSpacingContentBody1 size letter spacing for content body 1
letterSpacingContentBody2 size letter spacing for content body 2
scale number A factor that scales the whole theme (anything that is defined in em or rem, and not in px)
distanceScaleFactor number A factor that is used to scale distances, serves only as the default value for inset/outset
inset varOrNumber A factor that is used to scale inner distances within elements (like paddings)
insetX varOrNumber A factor that is used to scale inner, horizontal distances within elements (like paddings)
insetY varOrNumber A factor that is used to scale inner, vertical distances within elements (like paddings)
outsetX varOrNumber A factor that is used to scale outer, horizontal distances between elements (like margins)
outsetY varOrNumber A factor that is used to scale outer, vertical distances between elements (like margins)

The values are not part of the theme, but you can override the values in your theme. Check the source code of the Styling component Example:

#Theming * {
  --color-text: rgb(0, 0, 0);
}
Styling source code Loading component source...

Custom Javascript

Required knowledge: Javascript.

You can also write custom Javascript Code in static/theme/global.js.

README.md

You can add a description to your theme that will show up in the interface. Use frontmatter to add metadata. Example:

---
name: My theme
version: 0.1
slug: my-theme
---

# A custom theme just for this project

Description on what it does and how to use it

Custom Icons

Required Knowledge: CSS.

To use custom Icons, generate your own assets and put the into static/theme/icons. Use CSS to override the icons from the Icon component. Example:

#Theming .icon-Full-Camera       { background-image: url("icons/Full/Camera.svg"); }

The source code lists a number of icon names you can override.

Icon source code Loading component source...

Map Style

You can also change the default style of the Map component by providing a custom TileJSON file at static/theme/maptiler/style.json. One way to create one is maptiler cloud.

Custom components

Required knowledge: Javascript, Svelte.

You can create your own components. This is the most powerful way to customize interkit apps. However, you cannot include custom components in themes yet. See Components

Style Recommendations

A general learning from our outdoor projects is that dark backgrounds do not work, mostly because of the reflections on the screen. We strongly recommend to use light backgrounds for versatile themes.

Development workflows

Create a custom theme for an existing project

  1. Go to the Design tab and apply the Example Starter theme
  2. Go to the Repository tab and commit the changed to set a baseline to return to
  3. Edit the files in static/theme
    • either directly in the Repository/Files tab
    • locally with git (see below)

Create a theme to share and to contribute to interkit

  1. Clone the Maxi template
  2. Go to the Design tab and apply the Example Starter theme
  3. Go to the Repository tab and commit the changed to set a baseline to return to
  4. Edit the files in static/theme locally with git (see below)
  5. Test the theme with different projects and templates:
    • locally
      1. clone a project locally with git (see below) and manually copy the static/theme folder into the cloned project
      2. test and iterate
      3. Don’t git push because that would change the template
    • OR on interkit
      1. dumplicate a template
      2. Go to Repository/Files and copy the theme folder into the project
      3. Test and iterate, then download the improved theme from the folder
    • OR if you have a local interkit running
      1. copy the theme to repositories/themes and restart interkit
      2. duplicate the template project and press apply this theme. Whenever you press this button, interkit copies the contents of the theme’s folder into the project. This way you can easily test a change on a range of projects.
  6. Once the theme works fine on a range of different projects, copy it into the interkit repository in repositories/themes

Local git workflow

You can clone an interkit project and work on it locally. You can also clone a template.

  1. Go to the Repository/GIT tab and find the URL for cloning
  2. git clone <URL from 1.>
  3. install interkit package, the tab should provide an exact URL npm install https://...
  4. npm run dev
  5. Edit files in static/theme
    • you need to manually reload to enable changes
    • you can make git commits and push if this is your own project
    • do not push if this is a template