From 9e80eff573fde353af759cae1f9a7958abadb8b5 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 26 Mar 2026 15:03:33 +0100 Subject: [PATCH] docs: update MUI to BUI migration skill (#33548) Update the MUI to BUI migration skill to reflect the current state of the @backstage/ui package. Made-with: Cursor Made-with: Cursor Signed-off-by: Patrik Oldsberg --- .../skills/mui-to-bui-migration/SKILL.md | 185 +++++++++--------- 1 file changed, 91 insertions(+), 94 deletions(-) diff --git a/docs/.well-known/skills/mui-to-bui-migration/SKILL.md b/docs/.well-known/skills/mui-to-bui-migration/SKILL.md index cb2d037d4c..94e2bcfdcd 100644 --- a/docs/.well-known/skills/mui-to-bui-migration/SKILL.md +++ b/docs/.well-known/skills/mui-to-bui-migration/SKILL.md @@ -29,44 +29,51 @@ Before starting migration: - `Box` - Basic layout container with CSS properties - `Container` - Centered content container with max-width +- `Flex` - Flex layout component +- `FullPage` - Full-page layout wrapper - `Grid` - CSS Grid-based layout (`Grid.Root`, `Grid.Item`) -- `Flex` - `Flexbox` layout component ### UI Components -- `Accordion` - Collapsible content panels +- `Accordion` - Collapsible content panels (`Accordion`, `AccordionTrigger`, `AccordionPanel`, `AccordionGroup`) +- `Alert` - Alert/notification banners (`status`, `title`, `description`) - `Avatar` - User/entity avatars -- `Button` - Primary action buttons (`variant="primary"`, `variant="secondary"`, `isDisabled`) +- `Button` - Action buttons (`variant="primary"`, `variant="secondary"`, `variant="tertiary"`, `isDisabled`, `destructive`, `loading`) - `ButtonIcon` - Icon-only buttons (`icon`, `onPress`, `variant`) - `ButtonLink` - Link styled as button - `Card` - Content cards (`Card`, `CardHeader`, `CardBody`, `CardFooter`) - `Checkbox` - Checkbox input - `Dialog` - Modal dialogs (`DialogTrigger`, `Dialog`, `DialogHeader`, `DialogBody`, `DialogFooter`) -- `Header` - Page headers -- `Header` - Full page header component +- `FieldLabel` - Form field label with description and secondary label +- `Header` - Page headers with breadcrumbs and tabs - `Link` - Navigation links -- `Menu` - Dropdown menus (`MenuTrigger`, `Menu`, `MenuItem`) +- `List` - List component (`List`, `ListRow`) +- `Menu` - Dropdown menus (`MenuTrigger`, `Menu`, `MenuItem`, `MenuSection`, `MenuSeparator`, `SubmenuTrigger`) - `PasswordField` - Password input field +- `PluginHeader` - Plugin-level header with icon, title, tabs, and actions - `Popover` - Popover overlays -- `RadioGroup` - Radio button groups +- `RadioGroup` - Radio button groups (`RadioGroup`, `Radio`) +- `SearchAutocomplete` - Search input with autocomplete popover (`SearchAutocomplete`, `SearchAutocompleteItem`) - `SearchField` - Search input -- `Select` - Dropdown select +- `Select` - Dropdown select (single and multiple selection modes) - `Skeleton` - Loading skeleton - `Switch` - Toggle switch -- `Table` - Data tables +- `Table` - Data tables (with `useTable` hook for data management) +- `TablePagination` - Standalone pagination component - `Tabs` - Tab navigation (`Tabs`, `TabList`, `Tab`, `TabPanel`) - `Tag` - Tag/chip component (replaces MUI Chip) - `TagGroup` - Tag/chip groups -- `Text` - Typography component (`variant`, `color`) +- `Text` - Typography component (`variant`, `color`, `weight`, `truncate`) - `TextField` - Text input (`isRequired`, `onChange` receives string directly) - `ToggleButton` - Toggle buttons - `ToggleButtonGroup` - Grouped toggle buttons -- `Tooltip` - Tooltip overlays (used with TooltipTrigger from react-aria-components) +- `Tooltip` - Tooltip overlays (`TooltipTrigger`, `Tooltip` — both from `@backstage/ui`) - `VisuallyHidden` - Accessibility helper ### Hooks - `useBreakpoint` - Responsive breakpoint hook +- `useTable` - Table data management hook (supports `complete`, `offset`, and `cursor` pagination modes) ## Migration Patterns @@ -145,7 +152,7 @@ function MyComponent() { @layer components { .container { padding: var(--bui-space-4); - background-color: var(--bui-bg-surface-1); + background-color: var(--bui-bg-neutral-1); border-radius: var(--bui-radius-2); } @@ -324,19 +331,14 @@ me < /span> **After (BUI TooltipTrigger pattern):** ```typescript -import {Tooltip, Text} from '@backstage/ui'; -import {TooltipTrigger} from 'react-aria-components'; +import { Tooltip, TooltipTrigger, Text } from '@backstage/ui'; - Hover -me < /Text> -< Tooltip > Tooltip -content < /Tooltip> -< /TooltipTrigger>; + Hover me + Tooltip content +; ``` -Note: Add `react-aria-components` to your dependencies. - ### 7. Dialog Pattern **Before (MUI Dialog):** @@ -549,75 +551,38 @@ variant = "secondary" / > < /MenuTrigger>; ``` -### 12. List to HTML with CSS Modules +### 12. List to BUI List **Before (MUI List):** ```typescript -import {List, ListItem, ListItemIcon, ListItemText} from '@material-ui/core'; +import { List, ListItem, ListItemIcon, ListItemText } from '@material-ui/core'; - - -< ListItemText -primary = "Title" -secondary = "Description" / > + + + - < /List>; +; ``` -**After (HTML list with BUI and CSS Modules):** - -```css -/* MyList.module.css */ -@layer components { - .list { - list-style: none; - padding: 0; - margin: 0; - } - - .listItem { - display: flex; - align-items: flex-start; - padding: var(--bui-space-2) 0; - } - - .listItemIcon { - min-width: 36px; - display: flex; - align-items: center; - color: var(--bui-fg-primary); - } -} -``` +**After (BUI List):** ```typescript -import {Flex, Text} from '@backstage/ui'; -import {RiSomeIcon} from '@remixicon/react'; -import styles from './MyList.module.css'; +import { List, ListRow } from '@backstage/ui'; +import { RiSomeIcon } from '@remixicon/react'; -