First pass at bringing our new navigation to BUI's docs

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
This commit is contained in:
Charles de Dreuille
2025-11-03 18:13:26 +00:00
parent 037536c627
commit 510f9ede8b
24 changed files with 506 additions and 604 deletions
-32
View File
@@ -1,32 +0,0 @@
# About Backstage UI
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.
## 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.
+173
View File
@@ -0,0 +1,173 @@
import { ComponentCards, ComponentCard } from '@/components/ComponentCards';
import { LayoutComponents } from '@/components/LayoutComponents';
import { CodeBlock } from '@/components/CodeBlock';
# Components
## Layout Components
We built a couple of layout components to help you build responsive elements
that will be consistent with the rest of your Backstage instance. These
components are opinionated and use TypeScript to ensure that the props you
provide are the ones coming from the theme.
<CodeBlock
title="Layout components"
code={`<Flex direction="column" gap="4">
<Box>Hello World</Box>
<Inline gap="sm">
<Box>Project 1</Box>
<Box>Project 2</Box>
</Inline>
</Flex>
`}
/>
<LayoutComponents />
## Components
### Actions
<ComponentCards>
<ComponentCard
title="Button"
description="A button component to help you trigger actions."
href="/components/button"
/>
<ComponentCard
title="ButtonLink"
description="A button component to help you trigger actions."
href="/components/button-link"
/>
<ComponentCard
title="ButtonIcon"
description="A button for actions with an icon."
href="/components/button-icon"
/>
<ComponentCard
title="Link"
description="A link component to help you navigate to other pages."
href="/components/link"
/>
</ComponentCards>
### Content display
<ComponentCards>
<ComponentCard
title="Card"
description="A component to separate your content on the page."
href="/components/card"
/>
<ComponentCard
title="Collapsible"
description="A collapsible component for expandable content."
href="/components/collapsible"
/>
</ComponentCards>
### Selection and inputs
<ComponentCards>
<ComponentCard
title="Checkbox"
description="A checkbox component to help you select items."
href="/components/checkbox"
/>
<ComponentCard
title="TextField"
description="A text field component to help you input text."
href="/components/text-field"
/>
<ComponentCard
title="SearchField"
description="A search field component to help you search for items."
href="/components/search-field"
/>
<ComponentCard
title="PasswordField"
description="A password field component to help you input passwords."
href="/components/password-field"
/>
<ComponentCard
title="Select"
description="A select component to help you select items."
href="/components/select"
/>
<ComponentCard
title="Switch"
description="A switch component to help you toggle items."
href="/components/switch"
/>
<ComponentCard
title="RadioGroup"
description="A radio group component to help you select items."
href="/components/radio-group"
/>
</ComponentCards>
### Navigation
<ComponentCards>
<ComponentCard
title="Header"
description="A header component to help you display a header."
href="/components/header"
/>
<ComponentCard
title="HeaderPage"
description="A header to complement the Header component."
href="/components/header-page"
/>
<ComponentCard
title="Menu"
description="A menu component to help you display a menu."
href="/components/menu"
/>
<ComponentCard
title="Tabs"
description="A tabs component to help you display a tabs."
href="/components/tabs"
/>
</ComponentCards>
### Images and icons
<ComponentCards>
<ComponentCard
title="Avatar"
description="A avatar component to help you display user avatars."
href="/components/avatar"
/>
<ComponentCard
title="Icon"
description="A icon component to help you display icons."
href="/components/icon"
/>
</ComponentCards>
### Feedback indicators
<ComponentCards>
<ComponentCard
title="Skeleton"
description="A skeleton component to help you display loading states."
href="/components/skeleton"
/>
<ComponentCard
title="Tooltip"
description="A tooltip component to help you display a tooltip."
href="/components/tooltip"
/>
</ComponentCards>
### Typography
<ComponentCards>
<ComponentCard
title="Text"
description="A text component to help you style your text."
href="/components/text"
/>
</ComponentCards>
-52
View File
@@ -1,52 +0,0 @@
import { CodeBlock } from '@/components/CodeBlock';
import { Banner } from '@/components/Banner';
import { snippet } from './snippets';
# How to install Backstage UI
## How to import BUI's global styles
Backstage UI works by importing a global CSS file at the root of your application. This file includes all the default styles for the components.
First, you'll need to install the package using a package manager. For example, if you're using Yarn:
<CodeBlock
lang="shell"
title="Run this command in your `packages/app` directory"
code={`yarn add @backstage/ui`}
/>
<CodeBlock
lang="tsx"
title="Add this line to `packages/app/src/index.tsx`"
code={`import '@backstage/cli/asset-types';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@backstage/ui/css/styles.css'; // [!code ++]
ReactDOM.createRoot(document.getElementById('root')!).render(<App />);`}
/>
<Banner
text="Import these styles only once at your application root. Plugin developers should skip this step to avoid conflicts."
variant="warning"
/>
## How to use BUI components
As a plugin maintainer, you can use BUI components in your plugin. As mentioned above, you should not import the styles
again in your plugin as this will be handled at the root of your application. To get started, just add the library to
your plugin and import the components you need.
<CodeBlock
lang="shell"
title="Run this command in your `packages/[your-plugin]` directory"
code={`yarn add @backstage/ui`}
/>
<CodeBlock lang="tsx" title="Let's get started 🚀" code={snippet} />
## Next steps
Now that you have the basics down, you can start building your plugin using the new design system.
Please familiarise yourself first with our theming principles. This will help you understand the core concepts of the design system.
If you have any questions, please reach out to us on [Discord](https://discord.gg/MUpMjP2).
-1
View File
@@ -9,7 +9,6 @@
margin-bottom: 48px;
padding-inline: 40px;
padding-block: 48px;
background-color: var(--panel);
border-radius: 0.5rem;
}
-42
View File
@@ -1,42 +0,0 @@
import { LayoutComponents } from '@/components/LayoutComponents';
import { CodeBlock } from '@/components/CodeBlock';
# Layout
Backstage UI is made for extensibility. We built this library to make it easy for any
Backstage plugin creator to be able to build their ideas at speed ensuring
consistency across the rest of your ecosystem. Each component is designed to
be editable to match your need but sometimes you want to have more control
over the layout of your page. To help you with that, we created a set of
layout components that you can use to build your own layouts. All of these
components are built to extend on our theming system, making it easy for you
to build your own layouts. Sometimes these components are not enough so we
created a set of helpers to be used with any CSS-in-JS library.
## Layout Components
We built a couple of layout components to help you build responsive elements
that will be consistent with the rest of your Backstage instance. These
components are opinionated and use TypeScript to ensure that the props you
provide are the ones coming from the theme.
<CodeBlock
title="Layout components"
code={`<Flex direction="column" gap="4">
<Box>Hello World</Box>
<Inline gap="sm">
<Box>Project 1</Box>
<Box>Project 2</Box>
</Inline>
</Flex>
`}
/>
<LayoutComponents />
## Layout Helpers
Sometimes you want to use global tokens dynamically outside of React
components. To help you with that we would like to provide a set of helpers
that you can use in your code. These helpers are not available just yet but we
are working on it.
+65 -161
View File
@@ -1,179 +1,83 @@
import { ComponentCards, ComponentCard } from '@/components/ComponentCards';
import { CodeBlock } from '@/components/CodeBlock';
import { Banner } from '@/components/Banner';
import { snippet } from './snippets';
## Welcome to Backstage UI, the new design library for Backstage plugins.
# Welcome to Backstage UI
This project is still under active development but we will make sure to document
the API as we go. We are aiming to improve the general UI of Backstage and
plugins across Backstage. This new library will take time to build but we are
building it incrementally with not conflict with the existing theming system.
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.
### Actions
## Import BUI's global styles
<ComponentCards>
<ComponentCard
title="Button"
description="A button component to help you trigger actions."
href="/components/button"
/>
<ComponentCard
title="ButtonLink"
description="A button component to help you trigger actions."
href="/components/button-link"
/>
<ComponentCard
title="ButtonIcon"
description="A button for actions with an icon."
href="/components/button-icon"
/>
<ComponentCard
title="Link"
description="A link component to help you navigate to other pages."
href="/components/link"
/>
</ComponentCards>
Backstage UI works by importing a global CSS file at the root of your application. This file includes all the default styles for the components.
First, you'll need to install the package using a package manager. For example, if you're using Yarn:
### Layout
<CodeBlock
lang="shell"
title="Run this command in your `packages/app` directory"
code={`yarn add @backstage/ui`}
/>
<ComponentCards>
<ComponentCard
title="Box"
description="The simplest component to help you style your content."
href="/components/box"
/>
<ComponentCard
title="Flex"
description="A flex container for your layout."
href="/components/flex"
/>
<ComponentCard
title="Grid"
description="A grid container for your layout."
href="/components/grid"
/>
<ComponentCard
title="Container"
description="Helps you center your content."
href="/components/container"
/>
<ComponentCard
title="Card"
description="A component to separate your content on the page."
href="/components/card"
/>
<ComponentCard
title="Collapsible"
description="A collapsible component for expandable content."
href="/components/collapsible"
/>
</ComponentCards>
<CodeBlock
lang="tsx"
title="Add this line to `packages/app/src/index.tsx`"
code={`import '@backstage/cli/asset-types';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@backstage/ui/css/styles.css'; // [!code ++]
### Selection and inputs
ReactDOM.createRoot(document.getElementById('root')!).render(<App />);`}
/>
<ComponentCards>
<ComponentCard
title="Checkbox"
description="A checkbox component to help you select items."
href="/components/checkbox"
/>
<ComponentCard
title="TextField"
description="A text field component to help you input text."
href="/components/text-field"
/>
<ComponentCard
title="SearchField"
description="A search field component to help you search for items."
href="/components/search-field"
/>
<ComponentCard
title="PasswordField"
description="A password field component to help you input passwords."
href="/components/password-field"
/>
<ComponentCard
title="Select"
description="A select component to help you select items."
href="/components/select"
/>
<ComponentCard
title="Switch"
description="A switch component to help you toggle items."
href="/components/switch"
/>
<ComponentCard
title="RadioGroup"
description="A radio group component to help you select items."
href="/components/radio-group"
/>
</ComponentCards>
<Banner
text="Import these styles only once at your application root. Plugin developers should skip this step to avoid conflicts."
variant="warning"
/>
### Navigation
## Use BUI components
<ComponentCards>
<ComponentCard
title="Header"
description="A header component to help you display a header."
href="/components/header"
/>
<ComponentCard
title="HeaderPage"
description="A header to complement the Header component."
href="/components/header-page"
/>
<ComponentCard
title="Menu"
description="A menu component to help you display a menu."
href="/components/menu"
/>
<ComponentCard
title="Tabs"
description="A tabs component to help you display a tabs."
href="/components/tabs"
/>
</ComponentCards>
As a plugin maintainer, you can use BUI components in your plugin. As mentioned above, you should not import the styles
again in your plugin as this will be handled at the root of your application. To get started, just add the library to
your plugin and import the components you need.
### Images and icons
<CodeBlock
lang="shell"
title="Run this command in your `packages/[your-plugin]` directory"
code={`yarn add @backstage/ui`}
/>
<ComponentCards>
<ComponentCard
title="Avatar"
description="A avatar component to help you display user avatars."
href="/components/avatar"
/>
<ComponentCard
title="Icon"
description="A icon component to help you display icons."
href="/components/icon"
/>
</ComponentCards>
### Feedback indicators
<ComponentCards>
<ComponentCard
title="Skeleton"
description="A skeleton component to help you display loading states."
href="/components/skeleton"
/>
<ComponentCard
title="Tooltip"
description="A tooltip component to help you display a tooltip."
href="/components/tooltip"
/>
</ComponentCards>
### Typography
<ComponentCards>
<ComponentCard
title="Text"
description="A text component to help you style your text."
href="/components/text"
/>
</ComponentCards>
<CodeBlock lang="tsx" title="Let's get started 🚀" code={snippet} />
## Support
Now that you have the basics down, you can start building your plugin using the new design system.
Please familiarise yourself first with our theming principles. This will help you understand the core concepts of the design system.
If you have any questions, please reach out to us on [Discord](https://discord.gg/MUpMjP2).
## 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.
-107
View File
@@ -1,107 +0,0 @@
import * as Table from '@/components/Table';
import { Chip } from '@/components/Chip';
import { CodeBlock } from '@/components/CodeBlock';
# Responsive
Backstage UI is built on a responsive design system, meaning that the components are
designed to adapt to different screen sizes. By default we offer a set of
breakpoints that you can use to create responsive components.
## Breakpoints
<Table.Root>
<Table.Header>
<Table.HeaderRow>
<Table.HeaderCell>Breakpoint prefix</Table.HeaderCell>
<Table.HeaderCell>Minimum width</Table.HeaderCell>
<Table.HeaderCell>CSS</Table.HeaderCell>
</Table.HeaderRow>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
<Chip head>xs</Chip>
</Table.Cell>
<Table.Cell>
<Chip>0px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`{ ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>sm</Chip>
</Table.Cell>
<Table.Cell>
<Chip>640px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 640px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>md</Chip>
</Table.Cell>
<Table.Cell>
<Chip>768px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 768px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>lg</Chip>
</Table.Cell>
<Table.Cell>
<Chip>1024px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 1024px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>xl</Chip>
</Table.Cell>
<Table.Cell>
<Chip>1280px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 1280px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>2xl</Chip>
</Table.Cell>
<Table.Cell>
<Chip>1536px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 1536px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
</Table.Body>
</Table.Root>
## Responsive components
Backstage UI components are designed to be responsive, meaning that they will adapt
to different screen sizes. Not every component is responsive, but the ones
that are will have a prop to control the responsive behavior.
The behaviour is the same for each component. For each prop, instead of adding
the value, you add an object with the value and the breakpoint prefix.
<CodeBlock
code={`// Fixed value
<Button size="small">Button</Button>
// Responsive value
<Button size={{ xs: 'small', md: 'medium' }}>Button</Button>`} />
@@ -3,48 +3,109 @@ import * as Table from '@/components/Table';
import { Chip } from '@/components/Chip';
import { customTheme } from '@/snippets/code-snippets';
# Theming
# Tokens
Backstage UI theming is built entirely on CSS, without relying on any CSS-in-JS libraries.
At its core, it provides a solid default theme that is easily customizable using a
comprehensive set of CSS variables. Additionally, it enables anyone to adapt the design
to their specific needs. Each component comes with fixed class names, making customization
even more straightforward.
## Responsive breakpoints
## Light & Dark modes
Backstage UI is built on a responsive design system, meaning that the components are
designed to adapt to different screen sizes. By default we offer a set of
breakpoints that you can use to create responsive components.
By default, Backstage UI supports both light and dark modes using the `data-theme-mode` attribute.
The light theme is applied by default if no `data-theme-mode` attribute is specified. To create
a custom theme, you'll need to define both light and dark modes as outlined below. If
only one mode is defined, the other will fall back to the default theme.
<Table.Root>
<Table.Header>
<Table.HeaderRow>
<Table.HeaderCell>Breakpoint prefix</Table.HeaderCell>
<Table.HeaderCell>Minimum width</Table.HeaderCell>
<Table.HeaderCell>CSS</Table.HeaderCell>
</Table.HeaderRow>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
<Chip head>xs</Chip>
</Table.Cell>
<Table.Cell>
<Chip>0px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`{ ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>sm</Chip>
</Table.Cell>
<Table.Cell>
<Chip>640px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 640px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>md</Chip>
</Table.Cell>
<Table.Cell>
<Chip>768px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 768px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>lg</Chip>
</Table.Cell>
<Table.Cell>
<Chip>1024px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 1024px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>xl</Chip>
</Table.Cell>
<Table.Cell>
<Chip>1280px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 1280px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
<Chip head>2xl</Chip>
</Table.Cell>
<Table.Cell>
<Chip>1536px</Chip>
</Table.Cell>
<Table.Cell>
<Chip>{`@media (min-width: 1536px) { ... }`}</Chip>
</Table.Cell>
</Table.Row>
</Table.Body>
</Table.Root>
## How to create your own theme
Backstage UI components are designed to be responsive, meaning that they will adapt
to different screen sizes. Not every component is responsive, but the ones
that are will have a prop to control the responsive behavior.
In our [started guide](/), we ask you to import two css files. The `core.css` file includes
the default set of variables. We recommend to keep this file in place and add your own theme
on top of it. `core.css` also include an opinionated reset. If you decided to remove `core.css`
you will have to provide your own reset css.
The behaviour is the same for each component. For each prop, instead of adding
the value, you add an object with the value and the breakpoint prefix.
Here's an example of how your theme.css file should look like:
<CodeBlock
code={`// Fixed value
<CodeBlock lang="css" code={customTheme} />
<Button size="small">Button</Button>
## CSS class name structure
// Responsive value
All Backstage UI components come with a set of CSS classes that you can use to style them. To make it
easier to identify the class name you can use, we use a specific structure for the class names.
<Button size={{ xs: 'small', md: 'medium' }}>Button</Button>`} />
<img
src="/css-classname-structure.png"
style={{ width: '100%', marginBottom: '32px', marginTop: '16px' }}
/>
Every component has a unique prefix `.bui-` followed by the component name. Component props
are represented using the `data-` attribute. That way, class names are easily identifiable.
## Available CSS variables
### Base colors
## Base colors
These colors are used for special purposes like ring, scrollbar, ...
@@ -123,7 +184,7 @@ These colors are used for special purposes like ring, scrollbar, ...
</Table.Body>
</Table.Root>
### Core background colors
## Core background colors
These colors are used for the background of your application. We are mostly using for now a
single elevated background for panels. `--bui-bg` should mostly use as the main background
@@ -224,7 +285,7 @@ color of your app.
</Table.Body>
</Table.Root>
### Foreground colors
## Foreground colors
Foreground colours are meant to work in pair with a background colours. Typically this would work
for icons, texts, shapes, ... Use a matching name to know what foreground color to use. These colors
@@ -329,7 +390,7 @@ are prefixed with `fg` to make it easier to identify.
</Table.Body>
</Table.Root>
### Border colors
## Border colors
These border colors are mostly meant to be used as borders on top of any components with
low contrast to help as a separator with the different background colors.
@@ -391,7 +452,7 @@ low contrast to help as a separator with the different background colors.
</Table.Body>
</Table.Root>
### Special colors
## Special colors
These colors are used for special purposes like ring, scrollbar, ...
@@ -424,7 +485,7 @@ These colors are used for special purposes like ring, scrollbar, ...
</Table.Body>
</Table.Root>
### Font families
## Font families
We have two fonts that we use across Backstage UI. The first one is the sans-serif
font that we use for the body of the application. The second one is the
@@ -453,7 +514,7 @@ monospace font that we use for code blocks and tables.
</Table.Body>
</Table.Root>
### Font weights
## Font weights
We have two font weights that we use across Backstage UI. Regular or Bold.
@@ -480,7 +541,7 @@ We have two font weights that we use across Backstage UI. Regular or Bold.
</Table.Body>
</Table.Root>
### Spacing
## Spacing
We built a spacing system based on a single value `--bui-space`. This value is
used to calculate the spacing for all the components. By default if you would like to
@@ -619,7 +680,7 @@ tokens for pretty much each spacing properties like padding, margin, gaps, ...
</Table.Body>
</Table.Root>
### Radius
## Radius
We use a radius system to make sure that the components have a consistent look and feel.