Theming

Create a theme

Creating your first theme is as simple as calling the createTheme function. It's ready to go out-of-the-box with the default theme. The next few sections will show you how to customise the theme to match your brand.

import { createTheme } from '@kaluza-platform/nebula';
import { ThemeProvider } from 'styled-components';

const theme = createTheme({});

const MyApp = () => (
  <ThemeProvider theme={theme}>Welcome to my app!</ThemeProvider>
);
import { createTheme } from '@kaluza-platform/nebula';
import { ThemeProvider } from 'styled-components';

const theme = createTheme({});

const MyApp = () => (
  <ThemeProvider theme={theme}>Welcome to my app!</ThemeProvider>
);

Customise a theme

Themes are built on a set of core tokens or Foundations. These tokens correspond to raw values, such as a font size or hex value.

const myTheme = createTheme<{}>({
  colors: {
    primary: 'green',
    primaryAlt: 'darkgreen',
  },
  fonts: {
    body: 'Tahoma'
  },
  borderWidths: {
    heavy: '2rem'
  }
});
const myTheme = createTheme<{}>({
  colors: {
    primary: 'green',
    primaryAlt: 'darkgreen',
  },
  fonts: {
    body: 'Tahoma'
  },
  borderWidths: {
    heavy: '2rem'
  }
});

Our approach to theming is to set default values and then allow you to override the theme.

Themes are combined with a deep merge. This will update any dynamic tokens. When you add custom theme values you should also provide the typings.

const myTheme = createTheme<{
  fonts: {
    superDisplay: string
  },
  borderRadius: {
    full: string
  }
}>({
  fonts: {
    superDisplay: 'Verdana'
  },
  borderRadius: {
    full: '50%'
  },
  colors: {
    primary: 'tomato'
  }
});
const myTheme = createTheme<{
  fonts: {
    superDisplay: string
  },
  borderRadius: {
    full: string
  }
}>({
  fonts: {
    superDisplay: 'Verdana'
  },
  borderRadius: {
    full: '50%'
  },
  colors: {
    primary: 'tomato'
  }
});

It is also possible to extend the theme, adding your own variables.

type AdditionalValues = {
  somethingCustom: {
    color: string;
  },
}
const myTheme = createTheme<AdditionalValues>({
  colors: {
    primary: 'green',
    primaryAlt: 'darkgreen',
  },
  somethingCustom: {
    color: 'tomato',
  },
});
type AdditionalValues = {
  somethingCustom: {
    color: string;
  },
}
const myTheme = createTheme<AdditionalValues>({
  colors: {
    primary: 'green',
    primaryAlt: 'darkgreen',
  },
  somethingCustom: {
    color: 'tomato',
  },
});

CSS Reset

You will need to import the css reset in order for the theme to display components correctly. It will adjust the font size of the page to make it easier to work with rems. Rem Units in CSS (opens in new window)