Skip to main content

Theme Guides

A comprehensive guide to understanding and using themes in the Abyss Design System

github
View source code

If I want to set up tokens and themes in my project...​

To use Abyss themes and tokens, your project must be wrapped with a ThemeProvider, and a theme object made with createTheme must be passed in.

The createTheme function allows for passing in a base brand theme and customizing it with overrides. Pass in uhc or optum to use the respective approved brand themes.

import { ThemeProvider, createTheme } from '@uhg-abyss/mobile';


const theme = createTheme('uhc');


// All children components will have access to the theme and tokens
const App = () => {
  return <ThemeProvider theme={theme}>...</ThemeProvider>;
};

If I want to override tokens in a base theme...​

Use createTheme to customize specific tokens while keeping the rest of the base theme intact. The second argument accepts a theme object with token overrides.

See createTheme for more details.

const themeOverride = {
  theme: {
    colors: {...},
    space: {...},
    fontSizes: {...},
    fonts: {...},
    fontWeights: {...},
    lineHeights: {...},
    letterSpacings: {...},
    sizes: {...},
    borderWidths: {...},
    borderStyles: {...},
    radii: {...},
    shadows: {...},
    zIndices: {...},
    transitions: {...},
  },
};
import { ThemeProvider, createTheme } from '@uhg-abyss/mobile';


const theme = createTheme('uhc', {
  theme: {
    colors: {
      'core.color.brand.100': '#6950C3',
      customColor: '#ff612b',
    },
  },
});


const App = () => (
  <ThemeProvider theme={theme}>
    <YourAppContent />
  </ThemeProvider>
);

If I want to white-label the theme...​

White-labeling a theme overrides the majority of tokens in the base theme, thus creating a new theme as opposed to a customized uhc or optum theme. The three tier tokens structure (core, semantic, component) can be overriden together.

See White-labeling a theme for more details.

If I want to extend an existing theme...​

Use extendTheme to merge additional token overrides into an existing theme. This is useful when you need to layer multiple token sets or extend a theme you don't directly control. You can nest ThemeProvider components to create multiple theme layers. The inner provider will override tokens from the outer provider; an inner provider with an extended theme can then change a portion of the application without touching the rest.

import { createTheme, extendTheme, ThemeProvider } from '@uhg-abyss/mobile';
import { theme as baseTheme } from '../external/source';


const extendedTheme = extendTheme(baseTheme, {
  theme: {
    colors: {
      'core.color.purple.90': '#6950C3',
    },
  },
});


const App = () => (
  <ThemeProvider theme={extendedTheme}>
    <YourAppContent />
  </ThemeProvider>
);

If I want to import tokens from Figma Tokens Studio...​

Export tokens from Figma Tokens Studio as JSON files, then use flattenTokens to combine and resolve token references. Pass the flattened tokens to createTheme.

Note: flattenTokens supports both DTCG and legacy token formats and automatically resolves token references.

import { ThemeProvider, createTheme, flattenTokens } from '@uhg-abyss/mobile';
import coreTokens from './tokens/core.json';
import semanticTokens from './tokens/semantic.json';
import brandTokens from './tokens/brand.json';


const flattenedTokens = flattenTokens(coreTokens, semanticTokens, brandTokens);
const theme = createTheme('optum', { theme: flattenedTokens });


const App = () => (
  <ThemeProvider theme={theme}>
    <YourAppContent />
  </ThemeProvider>
);

If I want to use tokens in styled components...​

Use the styled function with token references prefixed by $. Tokens automatically resolve to their values from the current theme. See Styled Components for more details on using styled components in Abyss.

import { styled } from '@uhg-abyss/mobile';


const Card = styled('View', {
  backgroundColor: '$semantic.color.surface.container.secondary',
  padding: '$semantic.spacing.lg',
  borderRadius: '$core.border-radius.md',
  borderWidth: '$core.border-width.sm',
  borderColor: '$semantic.color.border.interactive.buttons.default',
});

If I want to customize an Abyss component...​

Most Abyss components have token-based props for colors, spacing, typography, etc. There are a number of options:

  • Override component tokens with custom values to change specific components to change how a component looks everywhere in the app. See the guide above for more details.
  • Create styled components that wrap Abyss components and apply custom styles on top of the base component styles.
  • Use classes to override styles on a component instance. See Style Customization for more details.

If I want to access token values directly...​

To access the raw values, use the useToken hook. Specify the token category and pass the token key.

import { useToken } from '@uhg-abyss/mobile';
import { StyleSheet } from 'react-native';


const MyComponent = () => {
  const getColorToken = useToken('colors');
  const svgColor = getColorToken('core.color.brand.80');
  return (
    <View style={styles.container}>
      <Svg color={svgColor}>...</Svg>
    </View>
  );
};

If I want to use tokens with third-party components...​

Use the useToken hook to get token values and pass them as props to third-party components.

import { useToken } from '@uhg-abyss/mobile';
import { Button } from 'external-library';


const MyButton = () => {
  const getColorToken = useToken('colors');
  const buttonColor = getColorToken('core.color.brand.80');
  return <Button color={buttonColor}>Click Me</Button>;
};
Table of Contents