From a6285dde5e38a14c747291333741d61a318e5c75 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden.halko@gmail.com>
Date: Mon, 8 Dec 2025 21:11:32 +0000
Subject: [PATCH] chore(site): mark MUI components and Stack as deprecated
 (#20973)

Adds deprecation markers for MUI components and the custom Stack
component to guide migration to shadcn/ui and Tailwind CSS.

Changes:
- Added JSDoc @deprecated tags to Stack component and type definitions
- Added deprecation comments to MUI imports in theme files
- Expanded Biome noRestrictedImports rules to flag all MUI component
imports

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 biome.jsonc                         | 81 ++++++++++++++++++++++++-----
 site/.storybook/preview.tsx         |  1 -
 site/src/@types/mui.d.ts            |  1 -
 site/src/components/Alert/Alert.tsx |  1 -
 site/src/components/Stack/Stack.tsx |  6 +++
 site/src/contexts/ThemeProvider.tsx |  4 +-
 site/src/theme/dark/mui.ts          |  7 ++-
 site/src/theme/index.ts             |  2 +-
 site/src/theme/light/mui.ts         |  7 ++-
 site/src/theme/mui.ts               |  9 +++-
 10 files changed, 98 insertions(+), 21 deletions(-)

diff --git a/biome.jsonc b/biome.jsonc
index 42a920eeea..d45b5cabb2 100644
--- a/biome.jsonc
+++ b/biome.jsonc
@@ -17,12 +17,12 @@
 				"useSemanticElements": "off",
 				"noStaticElementInteractions": "off"
 			},
-			"correctness": {
-				"noUnusedImports": "warn",
+		"correctness": {
+			"noUnusedImports": "warn",
 				"useUniqueElementIds": "off", // TODO: This is new but we want to fix it
 				"noNestedComponentDefinitions": "off", // TODO: Investigate, since it is used by shadcn components
-				"noUnusedVariables": {
-					"level": "warn",
+			"noUnusedVariables": {
+				"level": "warn",
 					"options": {
 						"ignoreRestSiblings": true
 					}
@@ -40,19 +40,76 @@
 				"useNumberNamespace": "error",
 				"noInferrableTypes": "error",
 				"noUselessElse": "error",
-				"noRestrictedImports": {
-					"level": "error",
+			"noRestrictedImports": {
+				"level": "error",
 					"options": {
 						"paths": {
-							"@mui/material": "Use @mui/material/<name> instead. See: https://material-ui.com/guides/minimizing-bundle-size/.",
+							// "@mui/material/Alert": "Use components/Alert/Alert instead.",
+							// "@mui/material/AlertTitle": "Use components/Alert/Alert instead.",
+							// "@mui/material/Autocomplete": "Use shadcn/ui Combobox instead.",
 							"@mui/material/Avatar": "Use components/Avatar/Avatar instead.",
-							"@mui/material/Alert": "Use components/Alert/Alert instead.",
+							"@mui/material/Box": "Use a <div> with Tailwind classes instead.",
+							"@mui/material/Button": "Use components/Button/Button instead.",
+							// "@mui/material/Card": "Use shadcn/ui Card component instead.",
+							// "@mui/material/CardActionArea": "Use shadcn/ui Card component instead.",
+							// "@mui/material/CardContent": "Use shadcn/ui Card component instead.",
+							// "@mui/material/Checkbox": "Use shadcn/ui Checkbox component instead.",
+							// "@mui/material/Chip": "Use components/Badge or Tailwind styles instead.",
+							// "@mui/material/CircularProgress": "Use components/Spinner/Spinner instead.",
+							// "@mui/material/Collapse": "Use shadcn/ui Collapsible instead.",
+							// "@mui/material/CssBaseline": "Use Tailwind CSS base styles instead.",
+							// "@mui/material/Dialog": "Use shadcn/ui Dialog component instead.",
+							// "@mui/material/DialogActions": "Use shadcn/ui Dialog component instead.",
+							// "@mui/material/DialogContent": "Use shadcn/ui Dialog component instead.",
+							// "@mui/material/DialogContentText": "Use shadcn/ui Dialog component instead.",
+							// "@mui/material/DialogTitle": "Use shadcn/ui Dialog component instead.",
+							// "@mui/material/Divider": "Use shadcn/ui Separator or <hr> with Tailwind instead.",
+							// "@mui/material/Drawer": "Use shadcn/ui Sheet component instead.",
+							// "@mui/material/FormControl": "Use native form elements with Tailwind instead.",
+							// "@mui/material/FormControlLabel": "Use shadcn/ui Label with form components instead.",
+							// "@mui/material/FormGroup": "Use a <div> with Tailwind classes instead.",
+							// "@mui/material/FormHelperText": "Use a <p> with Tailwind classes instead.",
+							// "@mui/material/FormLabel": "Use shadcn/ui Label component instead.",
+							// "@mui/material/Grid": "Use Tailwind grid utilities instead.",
+							// "@mui/material/IconButton": "Use components/Button/Button with variant='icon' instead.",
+							// "@mui/material/InputAdornment": "Use Tailwind positioning in input wrapper instead.",
+							// "@mui/material/InputBase": "Use shadcn/ui Input component instead.",
+							// "@mui/material/LinearProgress": "Use a progress bar with Tailwind instead.",
+							// "@mui/material/Link": "Use React Router Link or native <a> tags instead.",
+							// "@mui/material/List": "Use native <ul> with Tailwind instead.",
+							// "@mui/material/ListItem": "Use native <li> with Tailwind instead.",
+							// "@mui/material/ListItemIcon": "Use lucide-react icons in list items instead.",
+							// "@mui/material/ListItemText": "Use native elements with Tailwind instead.",
+							// "@mui/material/Menu": "Use shadcn/ui DropdownMenu instead.",
+							// "@mui/material/MenuItem": "Use shadcn/ui DropdownMenu components instead.",
+							// "@mui/material/MenuList": "Use shadcn/ui DropdownMenu components instead.",
+							// "@mui/material/Paper": "Use a <div> with Tailwind shadow/border classes instead.",
 							"@mui/material/Popover": "Use components/Popover/Popover instead.",
+							// "@mui/material/Radio": "Use shadcn/ui RadioGroup instead.",
+							// "@mui/material/RadioGroup": "Use shadcn/ui RadioGroup instead.",
+							// "@mui/material/Select": "Use shadcn/ui Select component instead.",
+							// "@mui/material/Skeleton": "Use shadcn/ui Skeleton component instead.",
+							// "@mui/material/Snackbar": "Use components/GlobalSnackbar instead.",
+							// "@mui/material/Stack": "Use Tailwind flex utilities instead (e.g., <div className='flex flex-col gap-4'>).",
+							// "@mui/material/styles": "Use Tailwind CSS instead.",
+							// "@mui/material/SvgIcon": "Use lucide-react icons instead.",
+							// "@mui/material/Switch": "Use shadcn/ui Switch component instead.",
+							"@mui/material/Table": "Import from components/Table/Table instead.",
+							// "@mui/material/TableRow": "Import from components/Table/Table instead.",
+							// "@mui/material/TextField": "Use shadcn/ui Input component instead.",
+							// "@mui/material/ToggleButton": "Use shadcn/ui Toggle or custom component instead.",
+							// "@mui/material/ToggleButtonGroup": "Use shadcn/ui Toggle or custom component instead.",
+							// "@mui/material/Tooltip": "Use shadcn/ui Tooltip component instead.",
 							"@mui/material/Typography": "Use native HTML elements instead. Eg: <span>, <p>, <h1>, etc.",
-							"@mui/material/Box": "Use a <div> instead.",
-							"@mui/material/Button": "Use a components/Button/Button instead.",
-							"@mui/material/styles": "Import from @emotion/react instead.",
-							"@mui/material/Table*": "Import from components/Table/Table instead.",
+							// "@mui/material/useMediaQuery": "Use Tailwind responsive classes or custom hook instead.",
+							// "@mui/system": "Use Tailwind CSS instead.",
+							// "@mui/utils": "Use native alternatives or utility libraries instead.",
+							// "@mui/x-tree-view": "Use a Tailwind-compatible alternative.",
+							// "@emotion/css": "Use Tailwind CSS instead.",
+							// "@emotion/react": "Use Tailwind CSS instead.",
+							"@emotion/styled": "Use Tailwind CSS instead.",
+							// "@emotion/cache": "Use Tailwind CSS instead.",
+							// "components/Stack/Stack": "Use Tailwind flex utilities instead (e.g., <div className='flex flex-col gap-4'>).",
 							"lodash": "Use lodash/<name> instead."
 						}
 					}
diff --git a/site/.storybook/preview.tsx b/site/.storybook/preview.tsx
index 13a875442d..d0c741e458 100644
--- a/site/.storybook/preview.tsx
+++ b/site/.storybook/preview.tsx
@@ -4,7 +4,6 @@ import CssBaseline from "@mui/material/CssBaseline";
 import {
 	ThemeProvider as MuiThemeProvider,
 	StyledEngineProvider,
-	// biome-ignore lint/style/noRestrictedImports: we extend the MUI theme
 } from "@mui/material/styles";
 import { DecoratorHelpers } from "@storybook/addon-themes";
 import isChromatic from "chromatic/isChromatic";
diff --git a/site/src/@types/mui.d.ts b/site/src/@types/mui.d.ts
index daad165f7d..5128ae7b19 100644
--- a/site/src/@types/mui.d.ts
+++ b/site/src/@types/mui.d.ts
@@ -1,4 +1,3 @@
-// biome-ignore lint/style/noRestrictedImports: base theme types
 import type { PaletteColor, PaletteColorOptions } from "@mui/material/styles";
 
 declare module "@mui/material/styles" {
diff --git a/site/src/components/Alert/Alert.tsx b/site/src/components/Alert/Alert.tsx
index 86ae99b3b0..2673cd9bc4 100644
--- a/site/src/components/Alert/Alert.tsx
+++ b/site/src/components/Alert/Alert.tsx
@@ -1,7 +1,6 @@
 import MuiAlert, {
 	type AlertColor as MuiAlertColor,
 	type AlertProps as MuiAlertProps,
-	// biome-ignore lint/style/noRestrictedImports: Used as base component
 } from "@mui/material/Alert";
 import Collapse from "@mui/material/Collapse";
 import { Button } from "components/Button/Button";
diff --git a/site/src/components/Stack/Stack.tsx b/site/src/components/Stack/Stack.tsx
index 98904422d4..4acd98d67d 100644
--- a/site/src/components/Stack/Stack.tsx
+++ b/site/src/components/Stack/Stack.tsx
@@ -1,6 +1,9 @@
 import type { CSSObject } from "@emotion/react";
 import { forwardRef } from "react";
 
+/**
+ * @deprecated Stack component is deprecated. Use Tailwind flex utilities instead.
+ */
 type StackProps = {
 	className?: string;
 	direction?: "column" | "row";
@@ -10,6 +13,9 @@ type StackProps = {
 	wrap?: CSSObject["flexWrap"];
 } & React.HTMLProps<HTMLDivElement>;
 
+/**
+ * @deprecated Stack component is deprecated. Use Tailwind flex utilities instead.
+ */
 export const Stack = forwardRef<HTMLDivElement, StackProps>((props, ref) => {
 	const {
 		children,
diff --git a/site/src/contexts/ThemeProvider.tsx b/site/src/contexts/ThemeProvider.tsx
index 2a3fcb2215..31eb8ad698 100644
--- a/site/src/contexts/ThemeProvider.tsx
+++ b/site/src/contexts/ThemeProvider.tsx
@@ -1,13 +1,15 @@
 import createCache from "@emotion/cache";
+/** @deprecated Emotion is deprecated. Migrate to Tailwind CSS. */
 import {
 	CacheProvider,
 	ThemeProvider as EmotionThemeProvider,
 } from "@emotion/react";
+/** @deprecated MUI CssBaseline is deprecated. Migrate to shadcn/ui components and Tailwind CSS. */
 import CssBaseline from "@mui/material/CssBaseline";
+/** @deprecated MUI components are deprecated. Migrate to shadcn/ui components and Tailwind CSS. */
 import {
 	ThemeProvider as MuiThemeProvider,
 	StyledEngineProvider,
-	// biome-ignore lint/style/noRestrictedImports: we extend the MUI theme
 } from "@mui/material/styles";
 import { appearanceSettings } from "api/queries/users";
 import { useEmbeddedMetadata } from "hooks/useEmbeddedMetadata";
diff --git a/site/src/theme/dark/mui.ts b/site/src/theme/dark/mui.ts
index 0d3133db1c..fd526e4bcc 100644
--- a/site/src/theme/dark/mui.ts
+++ b/site/src/theme/dark/mui.ts
@@ -1,4 +1,9 @@
-// biome-ignore lint/style/noRestrictedImports: createTheme
+/**
+ * @deprecated MUI dark theme is deprecated. Migrate to Tailwind CSS theme system.
+ * This file provides MUI theme configuration for legacy compatibility only.
+ */
+
+/** @deprecated MUI createTheme is deprecated. Migrate to Tailwind CSS theme system. */
 import { createTheme } from "@mui/material/styles";
 import { BODY_FONT_FAMILY, borderRadius } from "../constants";
 import { components } from "../mui";
diff --git a/site/src/theme/index.ts b/site/src/theme/index.ts
index 9ffc9b7566..50c16b3257 100644
--- a/site/src/theme/index.ts
+++ b/site/src/theme/index.ts
@@ -1,4 +1,4 @@
-// biome-ignore lint/style/noRestrictedImports: We still use `Theme` as a basis for our actual theme, for now.
+/** @deprecated MUI Theme type is deprecated. Migrate to Tailwind CSS theme system. */
 import type { Theme as MuiTheme } from "@mui/material/styles";
 import type * as monaco from "monaco-editor";
 import type { Branding } from "./branding";
diff --git a/site/src/theme/light/mui.ts b/site/src/theme/light/mui.ts
index d504bcdf77..c5aa3327e6 100644
--- a/site/src/theme/light/mui.ts
+++ b/site/src/theme/light/mui.ts
@@ -1,4 +1,9 @@
-// biome-ignore lint/style/noRestrictedImports: createTheme
+/**
+ * @deprecated MUI light theme is deprecated. Migrate to Tailwind CSS theme system.
+ * This file provides MUI theme configuration for legacy compatibility only.
+ */
+
+/** @deprecated MUI createTheme is deprecated. Migrate to Tailwind CSS theme system. */
 import { createTheme } from "@mui/material/styles";
 import { BODY_FONT_FAMILY, borderRadius } from "../constants";
 import { components } from "../mui";
diff --git a/site/src/theme/mui.ts b/site/src/theme/mui.ts
index 95b66520b5..82d1a0314d 100644
--- a/site/src/theme/mui.ts
+++ b/site/src/theme/mui.ts
@@ -1,6 +1,11 @@
-// biome-ignore lint/style/noRestrictedImports: we use the classes for customization
+/**
+ * @deprecated MUI theme configuration is deprecated. Migrate to Tailwind CSS theme system.
+ * This file provides MUI theme overrides for legacy compatibility only.
+ */
+
+/** @deprecated MUI Alert classes are deprecated. Use shadcn/ui Alert component instead. */
 import { alertClasses } from "@mui/material/Alert";
-// biome-ignore lint/style/noRestrictedImports: we use the MUI theme as a base
+/** @deprecated MUI ThemeOptions is deprecated. Migrate to Tailwind CSS theme system. */
 import type { ThemeOptions } from "@mui/material/styles";
 import {
 	BODY_FONT_FAMILY,