Backstage UI is a design system created specifically for Backstage, built with React, TypeScript, and vanilla CSS. This open-source library is hosted in the Backstage monorepo. While it can be used in other projects, Backstage UI is designed to deliver a consistent, accessible, and extensible experience tailored to Backstage users.
Backstage UI is installed by default on every instance of Backstage, so you can start using it right away. If your setup doesn't include it yet, follow the installation guide to get started.
Box, Flex, Grid, and Card are the foundation of every layout in Backstage UI.
Each one offers a set of utility props that map directly to our design tokens, so you can build consistent
layouts without writing any CSS. When nested, they also act as surfaces and automatically increment the
background depth so visual hierarchy is handled for you.
<Flex direction="column" gap="4">
<Box bg="neutral-1">
<Button variant="secondary">Hello World</Button>
</Box>
<Box bg="neutral-1">
<Button variant="secondary">Hello World</Button>
</Box>
</Flex>Components like Card, Button, Text, and others are adaptive components. They
automatically adjust their colors, borders, and backgrounds to match the surface they live on. Drop a
Button inside a Card inside a Box and each component styles itself appropriately
without any extra configuration.
<Box bg="neutral-1">
<Card> {/* automatically set background to neutral-2 */}
<Button variant="secondary">Button with background set to neutral-3</Button>
</Card>
</Box>BUI uses a layered neutral scale from 0 to 4. Each level nests inside the previous one, automatically incrementing the background depth. This creates clear visual hierarchy without manually picking colors.
Neutral 0 is the application background and should only be used once, at the root of your app. All other surfaces build on top of it.
Each level can be interactive or non-interactive. A Card, for example, can be flat (just a surface) or fully clickable with hover and pressed states. The three interaction states (hover, pressed, disabled) are built into every neutral level.
Explore the full list of color tokens on the tokens page.
As much as possible we would like you to use components directly without creating custom components. If you need to create a custom component, you should use the components provided by Backstage UI.
<Box bg="autoIncrement">
<Text>Hello World</Text>
</Box>If you need to build custom components outside of BUI, you can use our design tokens as CSS variables to ensure your styles stay consistent with the rest of the system.
<div style={{ backgroundColor: 'var(--bui-bg-solid)' }}>
<div style={{ color: 'var(--bui-fg-solid)' }}>Hello World</div>
</div>When building custom interactive components, we strongly recommend using React Aria as your foundation. React Aria provides all the necessary accessibility features out of the box — keyboard navigation, focus management, ARIA attributes, and screen reader support — so you can focus on styling and logic without worrying about compliance.
import { ColorPicker, ColorArea, ColorSlider, ColorField } from 'react-aria-components';
function MyColorPicker() {
return (
<ColorPicker defaultValue="#184">
<ColorArea
colorSpace="hsb"
xChannel="saturation"
yChannel="brightness"
style={{ width: 192, height: 192, borderRadius: 'var(--bui-radius-md)' }}
/>
<ColorSlider colorSpace="hsb" channel="hue" />
<ColorField label="Hex" />
</ColorPicker>
);
}Backstage empowers product teams to build software faster and with greater quality. Its extensibility, however, required us to rethink how to deliver a consistent and accessible user experience. Our goal is to enable plugin creators to design plugins that seamlessly integrate with Backstage's look and feel while still allowing customization to match individual brands.
Instead of reinventing the wheel, we chose to focus on layout and styling while leveraging existing headless component libraries for functionality. This approach allows us to dedicate our efforts to creating a cohesive and flexible theming system.
Backstage UI is designed and maintained primarily by Spotify's Backstage team, leveraging Spotify's expertise in crafting high-quality design and technology. Drawing from our experience in building reliable and intuitive user experiences for the music industry, we've created a design system that looks great and works seamlessly.
Backstage UI is an open-source project and we welcome contributions from the community. If you are interested in contributing to Backstage UI, please read our contributing guide and our code of conduct.
Backstage UI is licensed under the Apache 2.0 license. See the LICENSE file for more details.