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) 

Transitional configuration

The config block of the theme object contains properties used to manage the rollout of breaking changes. These are transitional mechanisms only — they exist to let apps adopt new behaviour on their own schedule and are not intended as permanent configuration options. All apps are expected to migrate to the default (enabled) state.

markRequiredFormFields

Controls whether the new required field marking behaviour is active.

• false (default during rollout) - Existing behaviour: optional prop appends "(optional)" text; no asterisk is shown
• true - New behaviour: required fields display a red asterisk; optional suppresses it; Form renders the "Fields marked * are required" key

const theme = createTheme({
    config: {
      markRequiredFormFields: true,
    },
  });
const theme = createTheme({
    config: {
      markRequiredFormFields: true,
    },
  });

When adopting this change:

1. Set markRequiredFormFields: true in your theme.
2. Audit your forms for fields that are genuinely optional and add optional to them.
3. Check forms that use field components outside the Nebula Form component - you will need to add the key text manually.

Once all teams have migrated, this property will be removed and the new behaviour will become the unconditional default.