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:
@@ -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'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'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.
|
||||
|
||||
## 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.
|
||||
@@ -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>
|
||||
@@ -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).
|
||||
@@ -9,7 +9,6 @@
|
||||
margin-bottom: 48px;
|
||||
padding-inline: 40px;
|
||||
padding-block: 48px;
|
||||
background-color: var(--panel);
|
||||
border-radius: 0.5rem;
|
||||
}
|
||||
|
||||
|
||||
@@ -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
@@ -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'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'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.
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user