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 94e2bcfdcd..c47286ec30 100644 --- a/docs/.well-known/skills/mui-to-bui-migration/SKILL.md +++ b/docs/.well-known/skills/mui-to-bui-migration/SKILL.md @@ -5,8 +5,8 @@ description: Migrate Backstage plugins from Material-UI (MUI) to Backstage UI (B # MUI to BUI Migration Skill -This skill helps migrate Backstage plugins from Material-UI (@material-ui/core, @material-ui/icons) to Backstage UI ( -@backstage/ui). +This skill helps migrate Backstage plugins from Material-UI (@material-ui/core, @material-ui/icons) to +Backstage UI (@backstage/ui). ## Prerequisites @@ -19,6 +19,7 @@ Before starting migration: ``` 2. Add the CSS import to your root file (typically `src/index.ts` or app entry point): + ```typescript import '@backstage/ui/css/styles.css'; ``` @@ -38,11 +39,14 @@ Before starting migration: - `Accordion` - Collapsible content panels (`Accordion`, `AccordionTrigger`, `AccordionPanel`, `AccordionGroup`) - `Alert` - Alert/notification banners (`status`, `title`, `description`) - `Avatar` - User/entity avatars +- `Badge` - Inline badge/label with optional icon (`size`, `icon`) - `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 +- `CheckboxGroup` - Grouped checkboxes with shared label (`label`, `orientation`, `isRequired`) +- `DateRangePicker` - Date range input field (`label`, `value`, `onChange`) - `Dialog` - Modal dialogs (`DialogTrigger`, `Dialog`, `DialogHeader`, `DialogBody`, `DialogFooter`) - `FieldLabel` - Form field label with description and secondary label - `Header` - Page headers with breadcrumbs and tabs @@ -57,6 +61,7 @@ Before starting migration: - `SearchField` - Search input - `Select` - Dropdown select (single and multiple selection modes) - `Skeleton` - Loading skeleton +- `Slider` - Range slider input (`label`, `minValue`, `maxValue`, `step`) - `Switch` - Toggle switch - `Table` - Data tables (with `useTable` hook for data management) - `TablePagination` - Standalone pagination component @@ -103,9 +108,9 @@ Create a `.module.css` file alongside your component using BUI CSS variables. **Before (MUI `makeStyles`):** -```typescript +```tsx // MyComponent.tsx -import {makeStyles, Theme} from '@material-ui/core/styles'; +import { makeStyles, Theme } from '@material-ui/core/styles'; const useStyles = makeStyles((theme: Theme) => ({ container: { @@ -130,18 +135,16 @@ const useStyles = makeStyles((theme: Theme) => ({ function MyComponent() { const classes = useStyles(); return ( -
- Title < /Typography> - < div - className = {classes.listItem} > -
- +
+ Title +
+
+ +
+ Content +
- < span > Content < /span> - < /div> - < /div> -) - ; + ); } ``` @@ -177,27 +180,24 @@ function MyComponent() { } ``` -```typescript +```tsx // MyComponent.tsx -import {Box, Text} from '@backstage/ui'; -import {RiSomeIcon} from '@remixicon/react'; +import { Box, Text } from '@backstage/ui'; +import { RiSomeIcon } from '@remixicon/react'; import styles from './MyComponent.module.css'; function MyComponent() { return ( - - Title < /Text> - < div - className = {styles.listItem} > -
- - < /div> - < span > Content < /span> - < /div> - < /Box> -) - ; + + Title +
+
+ +
+ Content +
+
+ ); } ``` @@ -205,38 +205,27 @@ function MyComponent() { **Before (MUI Box with display prop):** -```typescript +```tsx - - {children} - < /Box> - < /Box> + + {children} + + ``` **After (BUI `Flex` component):** -```typescript - - -{ - children -} +```tsx + + + {children} + -< /Flex> ``` Note: BUI `Flex` uses `justify="between"` not `justify="space-between"`. @@ -245,70 +234,40 @@ Note: BUI `Flex` uses `justify="between"` not `justify="space-between"`. **Before (MUI Grid):** -```typescript - - - {content} - < /Grid> - < /Grid> +```tsx + + + {content} + + ``` **After (BUI Grid):** -```typescript - - -{ - content -} - -< /Grid.Root> +```tsx + + {content} + ``` ### 5. Typography to Text **Before (MUI Typography):** -```typescript - Heading < /Typography> - < Typography -variant = "h6" > Subheading < /Typography> - < Typography -variant = "body1" > Body -text < /Typography> -< Typography -variant = "body2" -color = "textSecondary" > Secondary -text < /Typography> +```tsx +Heading +Subheading +Body text +Secondary text ``` **After (BUI Text):** -```typescript - Heading < /Text> - < Text -variant = "title-small" > Subheading < /Text> - < Text -variant = "body-medium" > Body -text < /Text> -< Text -variant = "body-small" -color = "secondary" > Secondary -text < /Text> +```tsx +Heading +Subheading +Body text +Secondary text ``` Valid Text variants: `title-large`, `title-medium`, `title-small`, `title-x-small`, `body-large`, `body-medium`, @@ -318,19 +277,17 @@ Valid Text variants: `title-large`, `title-medium`, `title-small`, `title-x-smal **Before (MUI Tooltip):** -```typescript -import {Tooltip, Typography} from '@material-ui/core'; +```tsx +import { Tooltip, Typography } from '@material-ui/core'; - Tooltip -content < /Typography>}> -< span > Hover -me < /span> -< /Tooltip>; +Tooltip content}> + Hover me +; ``` **After (BUI TooltipTrigger pattern):** -```typescript +```tsx import { Tooltip, TooltipTrigger, Text } from '@backstage/ui'; @@ -343,26 +300,23 @@ import { Tooltip, TooltipTrigger, Text } from '@backstage/ui'; **Before (MUI Dialog):** -```typescript -import {Dialog, DialogTitle, DialogActions, Button} from '@material-ui/core'; +```tsx +import { Dialog, DialogTitle, DialogActions, Button } from '@material-ui/core'; - -Title < /DialogTitle> -< DialogActions > - + + +; ``` **After (BUI Dialog):** -```typescript +```tsx import { Dialog, DialogTrigger, @@ -373,78 +327,58 @@ import { -{ - if (!open) onClose(); -} -} -> -Title < /DialogHeader> -< DialogFooter > - + + + +; ``` ### 8. Button Changes **Before (MUI Button):** -```typescript - + + ``` **After (BUI Button):** -```typescript - +} + variant="secondary" +/> ``` ### 9. TextField Changes **Before (MUI TextField):** -```typescript +```tsx - - - + + + + - < TabPanel -value = "tab1" > Content -1 < /TabPanel> -< TabPanel -value = "tab2" > Content -2 < /TabPanel> -< /TabContext>; + Content 1 + Content 2 +; ``` **After (BUI Tabs):** -```typescript -import {Tabs, TabList, Tab, TabPanel} from '@backstage/ui'; +```tsx +import { Tabs, TabList, Tab, TabPanel } from '@backstage/ui'; - - - Tab -1 < /Tab> -< Tab -id = "tab2" > Tab -2 < /Tab> -< /TabList> -< TabPanel -id = "tab1" > Content -1 < /TabPanel> -< TabPanel -id = "tab2" > Content -2 < /TabPanel> -< /Tabs>; + + + Tab 1 + Tab 2 + + Content 1 + Content 2 +; ``` ### 11. Menu Pattern **Before (MUI Menu):** -```typescript +```tsx import {IconButton, Popover, MenuList, MenuItem} from '@material-ui/core'; import MoreVertIcon from '@material-ui/icons/MoreVert'; - - < Popover -open = {open} -anchorEl = {anchorEl} -onClose = {handleClose} > - - Action < /MenuItem> - < /MenuList> - < /Popover> + + + + + + Action + + ``` **After (BUI Menu):** -```typescript -import {ButtonIcon, Menu, MenuItem, MenuTrigger} from '@backstage/ui'; -import {RiMore2Line} from '@remixicon/react'; +```tsx +import { ButtonIcon, Menu, MenuItem, MenuTrigger } from '@backstage/ui'; +import { RiMore2Line } from '@remixicon/react'; - -} -variant = "secondary" / > - - Action < /MenuItem> - < /Menu> - < /MenuTrigger>; + } variant="secondary" /> + + Action + +; ``` ### 12. List to BUI List **Before (MUI List):** -```typescript +```tsx import { List, ListItem, ListItemIcon, ListItemText } from '@material-ui/core'; @@ -570,7 +487,7 @@ import { List, ListItem, ListItemIcon, ListItemText } from '@material-ui/core'; **After (BUI List):** -```typescript +```tsx import { List, ListRow } from '@backstage/ui'; import { RiSomeIcon } from '@remixicon/react'; @@ -587,7 +504,7 @@ Note: `ListRow` supports `icon`, `description`, `menuItems`, and `customActions` **Before (MUI Chip):** -```typescript +```tsx import { Chip } from '@material-ui/core'; ; @@ -595,17 +512,17 @@ import { Chip } from '@material-ui/core'; **After (BUI Tag):** -```typescript -import {Tag} from '@backstage/ui'; +```tsx +import { Tag } from '@backstage/ui'; - Category < /Tag>; +Category; ``` ### 14. Alert Pattern **Before (MUI Alert):** -```typescript +```tsx import { Alert, AlertTitle } from '@material-ui/lab'; @@ -616,7 +533,7 @@ import { Alert, AlertTitle } from '@material-ui/lab'; **After (BUI Alert):** -```typescript +```tsx import { Alert } from '@backstage/ui'; - + + ``` **After (Remix Icons):** -```typescript +```tsx import {RiCloseLine, RiSearchLine} from '@remixicon/react'; - - + + ``` Common icon mappings: @@ -683,6 +599,239 @@ Common icon mappings: Find more icons at: https://remixicon.com/ +### 16. Paper to Card + +**Before (MUI Paper):** + +```tsx +import { Paper, Typography } from '@material-ui/core'; + + + Title + Body content +; +``` + +**After (BUI Card):** + +```tsx +import { Card, CardHeader, CardBody, Text } from '@backstage/ui'; + + + Title + + Body content + +; +``` + +### 17. Select + +**Before (MUI Select):** + +```tsx +import { FormControl, InputLabel, Select, MenuItem } from '@material-ui/core'; + + + Framework + +; +``` + +**After (BUI Select):** + +```tsx +import { Select } from '@backstage/ui'; + +