Theming

Orbit styled system is powered by the values of a theme object provided by the application. The Orbit theme object specification have been inspired by the Styled System Theme Specification.

Theme object

A theme object is a combination of design values and design scales (spacing, sizing, colors, etc..).

Some scales are defined in Orbit as arrays for ordinal values like space or as plain objects for named values like colors. Some are even a mix of both, such as fontSizes.

An Orbit theme object is composed of the following 8 keys:

Output

When rendered with the createThemeVars function, the following CSS variables will be outputted from the theme object values.

Apply a theme

Orbit components and Orbit style props doesn't render any styles until a theme is applied.

To apply a theme:

1. Select a theme object
2. Render the CSS variables of the theme object with the createThemeVars function
3. Define a <ThemeProvider> component with the theme object

import { createThemeVars, ThemeProvider } from "@sharegate/orbit-ui";

createThemeVars([theme]);

<ThemeProvider theme={theme} colorScheme="light">
    <Button>Launch</Button>
</ThemeProvider>

Select a theme object

Any object can be used as an Orbit theme object as long as it extends the OrbitTheme TypeScript type. A few options are available.

Option 1: Define your own theme from scratch

Make sure you provide the right definition by extending the OrbitTheme type.

import { OrbitTheme, createThemeVars, ThemeProvider } from "@sharegate/orbit-ui";

const SpaceTheme: OrbitTheme = {
    name: "space-theme",
    space: [],
    sizing: [],
    fontSizes: {}
    // ...
};

createThemeVars([theme]);

<ThemeProvider theme={theme} colorScheme="light">
    <Button>Launch</Button>
</ThemeProvider>

Option 2: Create a new theme from Orbit defaults

With createTheme, you only have to provide a subset of OrbitTheme values. The remaining values will fallback to Orbit defaults.

import { createTheme, createThemeVars, ThemeProvider } from "@sharegate/orbit-ui";

const SpaceTheme = createTheme({
    name: "space-theme",
    colors: {
        white: "#fff",
        black: "#000",
        accent: [
            "hsla(174, 61%, 94%, 1)",
            "hsla(173, 63%, 85%, 1)",
            "hsla(173, 63%, 75%, 1)",
            "hsla(173, 64%, 65%, 1)",
            "hsla(173, 64%, 50%, 1)",
            "hsla(172, 65%, 48%, 1)",
            "hsla(173, 65%, 46%, 1)",
            "hsla(172, 63%, 45%, 1)",
            "hsla(172, 64%, 43%, 1)",
            "hsla(172, 62%, 41%, 1)"
        ]
        // ...
    }
    // ...
});

createThemeVars([theme]);

<ThemeProvider theme={theme} colorScheme="light">
    <Button>Launch</Button>
</ThemeProvider>

Option 3: Retrieve a pre-constructed theme from Orbit

The only theme available at the moment is ShareGateTheme.

import { ShareGateTheme, createThemeVars, ThemeProvider } from "@sharegate/orbit-ui";

createThemeVars([ShareGateTheme]);

<ThemeProvider theme={ShareGateTheme} colorScheme="light">
    <Button>Launch</Button>
</ThemeProvider>

Use a theme object in code

Theme objects are primarily used to boostrap Orbit styled system but they can also be used directly in JavaScript code when you need to fetch a value.

If you have access to the theme object, use the object directly.

<Div padding={SpaceTheme.spacing[2]}>Hello world!</Div>

If you don't have access to the theme object, retrieve a ThemeAccessor instance from the ThemeContext by using the useThemeContext hook and access the theme values from the instance.

import { useThemeContext } from "sharegate/orbit-ui";

const { themeAccessor } = useThemeContext();

return <Div padding={themeAccessor.getSizing(3)}>Hello world!</Div>