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 } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme } from '@uhg-abyss/web/tools/theme';


const theme = createTheme('uhc');


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

If I want to override tokens in a base theme (white-label)...​

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

See createTheme for more details.

const themeConfig = {
  theme: {
    colors: {...},
    space: {...},
    fontSizes: {...},
    fonts: {...},
    fontWeights: {...},
    lineHeights: {...},
    letterSpacings: {...},
    sizes: {...},
    borderWidths: {...},
    borderStyles: {...},
    radii: {...},
    shadows: {...},
    opacities: {...},
  },
};
import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme } from '@uhg-abyss/web/tools/theme';


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


const App = () => (
  <ThemeProvider theme={theme}>
    <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 } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme, flattenTokens } from '@uhg-abyss/web/tools/theme';
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/web/tools/styled';


const Card = styled('div', {
  backgroundColor: '$web.semantic.color.surface.container.secondary',
  padding: '$web.semantic.spacing.scale.lg',
  borderRadius: '$core.border-radius.md',
  borderWidth: '$core.border-width.sm',
  borderColor: '$web.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 the css prop to override styles on a component instance.
  • Use static class names to apply overrides using regular CSS style sheets.

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/web/hooks/useToken';


const MyComponent = () => {
  const getColorToken = useToken('colors');
  const color = getColorToken('$core.color.brand.80');


  return (
    <div style={{ backgroundColor: color }}>
      <h1>Abyss Design System</h1>
    </div>
  );
};

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/web/hooks/useToken';
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>;
};

If I want to use Enterprise Sans font (UHC theme only)...​

The default font for the UHC theme is UHC Sans. Teams looking to utilize Enterprise Sans can do so by setting the enterpriseFont property to true in the themeConfig object.

const theme = createTheme('uhc', {
  enterpriseFont: true,
});

Note: This flag only applies to the UHC theme.

Table of Contents