Default Theme

Amplify UI follows a consistent pattern when defining our default tokens for properties such as color, font size, border radius, and more. In addition to the reference here, you can browse our default tokens and their corresponding types on GitHub.

Explore theme tokens

Referencing default theme tokens

The overall structure of the default theme object gives us a clue as to how to reference each token. If we look at the top level of the object, we can see how the tokens are separated by properties:

*/
interface BaseTokens<Output extends OutputVariantKey = unknown> {
  borderWidths?: BorderWidths<Output>;
  colors?: Colors<Output>;
  fonts?: Fonts<Output>;
  fontSizes?: FontSizes<Output>;
  fontWeights?: FontWeights<Output>;
  lineHeights?: LineHeights<Output>;
  opacities?: Opacities<Output>;
  outlineOffsets?: OutlineOffsets<Output>;
  outlineWidths?: OutlineWidths<Output>;
  radii?: Radii<Output>;
  shadows?: Shadows<Output>;
  space?: Space<Output>;
  time?: Time<Output>;
  transforms?: Transforms<Output>;
}

If we use space as an example, we'd discover its token definition looks similar to the following (shortened for example):

  space: {
    xxs: {},
    xs: {},
    small: {
      value: "0.75rem"
    }
    medium: {},
    large: {},
  }

All of our tokens follow this pattern: a top level namespace that is further defined by a scale, each which has their own unique value. In the case of our space design tokens, that scale is based on a size: small, medium, large, etc. Our color tokens, on the other hand, are further defined by hue (red, blue, yellow, etc), and then by a numerical scale based on lightness (10-100).

This structure allows us to reference the small space value as space.small using Style Props like in the following example.

import { View } from '@aws-amplify/ui-react';

const MyComponent = () => {
  return <View marginBottom="space.small">{children}</View>;
};

Or we can use the design token to create a custom theme.

const theme {
  name: 'custom-theme',
  tokens: {
    components: {
      card: {
        padding: { value: '{space.small}' },
      },
    },
  },
};

The space token definition also gives us an idea of how the CSS custom properties associated with each token are named. Amplify UI uses StyleDictionary to generate the associated CSS custom properties for each token. For the small space token, this would be --amplify-space-small and you can use it in your stylesheet as:

.my-component {
  margin-bottom: var(--amplify-space-small);
}