Skip to main content

Component Library

Our component library can be found under main/frontend/src/common/components.

Previously, our component library was housed in a separate repo calles base5-ui. As such, don't be suprised if you still find references to base5-ui dotted around the place.

General guidelines​

  • Any new common components (components which are used within the Admin dashboard and the hub) are added under main/frontend/src/common/components.

  • We aim to add new components in TypeScript. If a new component which you are adding requires the use of another common component, which is not yet converted to TypeScript, please refactor it to TypeScript before using it.

  • Common code can only utilise other common code. If you find that you would like to use a component or function which currently lives in the admin folder or main folder, please refactor and move that file over to the common folder as well (e.g. common/components, common/hooks, common/utils).

    Only use common logic in common/components

    Importing and using components from admin or main in common/components can cause build issues.

  • Each common component should be accompanied by an appropriate Storybook story. You can find a template for a component story under main/frontend/src/common/components/README.templatestories.mdx.

  • New components should be accessible. Use appropriate aria labels and test your component usage with a screenreader. See Accessibility for more information.

Using colours in components​

We utilise custom theming for colouring our components. See Storybook 5app Design System - Theming for an overview and more in-depth information.

ThemeSection colours - the go-to​

Most components are used within a ThemeSection and therefore have access to the ThemeSection colours. It's generally best to use colours from the current ThemeSection, as these are usually chosen to provide good readability and contrast.

The main ThemeSection colours are: text, background, links, shade, highlight.

See e.g. the SectionColors under hub/frontend/src/common/styles/types.d.ts for a list of all available ThemeSection colours.

Use case example:

import Box from 'components/Box';
import Arrow from 'components/Arrow';

function ArrowBox() {
	return (
			<Box p="s" textColor="text" backgroundColor="background">
			  Box with a pointy arrow.
				<Arrow  size={16} placement="top-end" />
			</Box>
	);
}

colorBlock colours - the exceptions​

If needed, colours from the colorBlocks can be utilised. These are colours mapped to a concept, e.g. "positive" or "negative", or content types. An overview of all colorBlocks can be found in the 5app theme config in Themepark.

All colorBlocks can be customised per client theme in Themepark, but for the majority of themes we fall back on the defaults defined in the 5app theme config.

Use colorBlocks sparingly

colorBlocks should only be used decoratively or in controlled conditions, as they are harder to optimise for general use.

Use case example: Sparkles

The Sparkles component adds decorative accents to a wrapped component. As such, the usage of colorBlocks here is fine and doesn't impact legibility of a theme.

The colorBlock sparkles was even specifically added to the 5app theme for the Sparkles component.

In the 5app theme config:

5app/themepark/blob/main/src/5app/config.json:

{
  "clr": {
    "vividOrange": "#FFC700",
  },
  "globals": {
    "colorBlocks": {
      "sparkles": "@clr.vividOrange"
    }
  }
}

5app/hub/blob/main/frontend/src/common/components/Sparkles/index.tsx:

import {useTheme} from 'styled-components';

const Sparkles = ({
	color: setColor,
	...otherProps
}: SparklesProps) => {

  const theme = useTheme();
	const color =
		setColor || theme.globals.colorBlocks.sparkles || FALLBACK_COLOR;

  	return <Sparkle color={color} />;
};

See also the Sparkles Story in Storybook.

Further resources​