paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 48 Packages Projects Releases Wiki Activity

Improving our get started page in BUI

Browse Source 
Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
This commit is contained in:
Charles de Dreuille
2026-02-11 19:44:11 +00:00
parent 36573c6dd0
commit 13422d70aa
22 changed files with 447 additions and 480 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs-ui/src/app/components/page.mdx
+5 -169
View File
@@ -1,173 +1,9 @@
import { ComponentCards, ComponentCard } from '@/components/ComponentCards';
import { LayoutComponents } from '@/components/LayoutComponents';
import { CodeBlock } from '@/components/CodeBlock';
import { ComponentGrid } from '@/components/ComponentGrid';
# Components
## Layout Components
Below is the full list of components available in the library. Each component is designed to be flexible, accessible,
and easy to integrate into your plugins. We are actively working on adding more components, so check back regularly
for updates.
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>
<ComponentGrid />
docs-ui/src/app/get-started/installation/page.mdx
+46
View File
@@ -0,0 +1,46 @@
import { CodeBlock } from '@/components/CodeBlock';
import { Banner } from '@/components/Banner';
import { snippet } from './snippets';
# Installation
## 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"
/>
## 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} />
docs-ui/src/app/get-started/installation/snippets.ts
+6
View File
@@ -0,0 +1,6 @@
export const snippet = `import { Flex, Button, Text } from '@backstage/ui';
<Flex>
<Text>Hello World</Text>
<Button>Click me</Button>
</Flex>;`;
docs-ui/src/app/page.mdx
+54 -35
View File
@@ -1,59 +1,78 @@
import { ComponentGrid } from '@/components/ComponentGrid';
import { CodeBlock } from '@/components/CodeBlock';
import { Banner } from '@/components/Banner';
import { snippet } from './snippets';
import { ColorFamily } from '@/components/ColorFamily';
import {
surfacesSnippet,
adaptiveSnippet,
customCardSnippet,
customTokensSnippet,
colorPickerSnippet,
} from './snippets';
# Welcome to Backstage UI
# 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.
## Import BUI's global styles
Backstage UI is installed by default on every instance of Backstage, so you can start using it right away.
If your setup doesn&apos;t include it yet, follow the [installation guide](/get-started/installation) to get started.
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 containers
<CodeBlock
lang="shell"
title="Run this command in your `packages/app` directory"
code={`yarn add @backstage/ui`}
/>
[`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="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 />);`}
title="Nested surfaces with automatic styling"
code={surfacesSnippet}
/>
<Banner
text="Import these styles only once at your application root. Plugin developers should skip this step to avoid conflicts."
variant="warning"
/>
## Adaptive components
## 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.
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="shell"
title="Run this command in your `packages/[your-plugin]` directory"
code={`yarn add @backstage/ui`}
lang="tsx"
title="Nested surfaces with automatic styling"
code={adaptiveSnippet}
/>
<CodeBlock lang="tsx" title="Let's get started 🚀" code={snippet} />
## The neutral scale background colors
## Support
<ColorFamily />
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).
## 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
docs-ui/src/app/snippets.ts
+37 -4
View File
@@ -1,6 +1,39 @@
export const snippet = `import { Flex, Button, Text } from '@backstage/ui';
export const surfacesSnippet = `<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>`;
<Flex>
export const adaptiveSnippet = `<Box bg="neutral-1">
<Card> {/* automatically set background to neutral-2 */}
<Button variant="secondary">Button with background set to neutral-3</Button>
</Card>
</Box>`;
export const customCardSnippet = `<Box bg="autoIncrement">
<Text>Hello World</Text>
<Button>Click me</Button>
</Flex>;`;
</Box>`;
export const customTokensSnippet = `<div style={{ backgroundColor: 'var(--bui-bg-solid)' }}>
<div style={{ color: 'var(--bui-fg-solid)' }}>Hello World</div>
</div>`;
export const colorPickerSnippet = `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>
);
}`;