CSS

support-frontend uses Emotion for CSS, with core style tokens drawn from the Guardian's design system, Source.

Emotion is a CSS-in-JS library that enables us to write styles in our .tsx and .ts files and have these compiled to CSS at runtime. It makes it much simpler to write precise and component-scoped styles and easily find the source of styles applied to specific bits of our rendered HTML.

The support site was originally styled using SCSS and several pages that see less developer traffic are still using this for part or all of their styling.

Adding styles to a component

Ideally styling should be done in the same .tsx file as the component itself. If either the style or component code is so complex that it makes the file excessively long to co-locate them, styles should be moved into a separate .ts file in the same folder.

Shared styles

Rather than creating shared style files between components as one might when writing SCSS or vanilla CSS, when working with Emotion your first move should always to try to share the styles through a component, whether that's making a single component that is more flexible and extensible and can cover more use cases, or creating a shared parent component. This avoids creating unwanted dependencies between components, and generally makes debugging CSS issues much, much easier.

There are a few exceptions for very high-level shared styles such as our reset, font loading code, and some shared constants. These can be found under assets/stylesheets/emotion

Legacy SCSS code

Style changes should be made using Emotion wherever possible, and if the time requirements of a task allow then the styles of components being updated or changed in older parts of the site should be actively migrated to Emotion. New .scss files should never be created outside of truly exceptional circumstances, and we should actively avoid making style changes within .scss files unless it is truly unavoidable due to time pressure or the complexity of the code.