Applying custom styles

While, ideally, you should be able to use the system components as-is, there are times when you need to apply custom styles to a component. Here you'll find guidance around how and when to do so.

When to leverage custom styles

To ensure consistency and promote the evolution of the design system, styles for system components should come from the theme defined in system. With that said, it's impossible to account for all use cases so there are valid reasons to selectively apply custom styles to system components, but doing so should be a last resort.

Reach out

Any time you find yourself needing to apply a custom style, please raise it in the #design-system Slack channel to make design aware that we're diverging from the system. Here are some signs to look out for that indicate styling being applied belongs in the system:

• You find yourself applying the same custom styles repetedly to the same component or across multiple components
• You're overriding styles that are already accounted for in a feature of the component API such as colorScheme, size or variant

🙏 If any of the above is true, please file a ticket to track styling exception so we can account for it in the system.

How to apply custom styles (web)

tldr;

Use the sx prop, which is available on all system components.

There are several ways to go about applying custom styles. However, the only recommended way to do so is via the sx prop, which is available on all components.

Using the sx prop has the following benefits over other approaches:

• Styles defined in sx style objects are still theme-aware, so you can still pass token names for theme CSS properties (see style props)
• It's still possible to define responsive styles using responsive style props sx
• The sx object can still support composition (see the example below)

Composing components with custom styles applied

By merging the sx prop your component accepts with your custom styles, it's still possible to support composition when using custom styles and allow consumers of your component to override any custom styles applied by default.