import { ComponentGrid } from '@/components/ComponentGrid';
import { CodeBlock } from '@/components/CodeBlock';
import { ColorFamily } from '@/components/ColorFamily';
import {
  surfacesSnippet,
  adaptiveSnippet,
  customCardSnippet,
  customTokensSnippet,
  colorPickerSnippet,
} from './snippets';

# Get Started with BUI

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](/get-started/installation) to get started.

## Layout containers

[`Box`](/components/box), [`Flex`](/components/flex), [`Grid`](/components/grid), and [`Card`](/components/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.

<CodeBlock
  lang="tsx"
  title="Nested surfaces with automatic styling"
  code={surfacesSnippet}
/>

## Adaptive components

Components like [`Card`](/components/card), [`Button`](/components/button), [`Text`](/components/text), and others are **adaptive components**. They
automatically adjust their colors, borders, and backgrounds to match the surface they live on. Drop a
[`Button`](/components/button) inside a [`Card`](/components/card) inside a [`Box`](/components/box) and each component styles itself appropriately
without any extra configuration.

<CodeBlock
  lang="tsx"
  title="Nested surfaces with automatic styling"
  code={adaptiveSnippet}
/>

## The neutral scale background colors

<ColorFamily />

## Creating custom components

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.

<CodeBlock
  lang="tsx"
  title="Creating a custom card using BUI components"
  code={customCardSnippet}
/>

If you need to build custom components outside of BUI, you can use our [design tokens](/tokens) as CSS variables to ensure your styles stay consistent with the rest of the system.

<CodeBlock
  lang="tsx"
  title="Creating a custom component using BUI tokens"
  code={customTokensSnippet}
/>

When building custom interactive components, we strongly recommend using [React Aria](https://react-spectrum.adobe.com/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.

<CodeBlock
  lang="tsx"
  title="Building a color picker using React Aria and BUI tokens"
  code={colorPickerSnippet}
/>

## Philosophy

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&apos;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.

## Team

Backstage UI is designed and maintained primarily by Spotify&apos;s Backstage team, leveraging Spotify&apos;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&apos;ve created a design system that looks great and works seamlessly.

## Community

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](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md)
and our [code of conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md).

## License

Backstage UI is licensed under the Apache 2.0 license. See the [LICENSE](https://github.com/backstage/backstage/blob/master/LICENSE) file for more details.