percona · matejkubinec · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026
@@ -55,4 +55,4 @@ dev/clickhouse-backups/
 # Exclude AI skills to support fast local experimentation
 .claude/
 .cursor/
-.cursorrules/
+.cursorrules/
@@ -0,0 +1,50 @@
+---
+description: "Percona UI + PMM UI styling — MUI + @percona/percona-ui, theme tokens, layout conventions, what not to do"
+alwaysApply: true
+---
+
+## Stack order
+
+1. **MUI** (mostly `@mui/material`, `@mui/icons-material`, `@mui/x-date-pickers` — though other MUI dependencies may also be in use) is the base component and styling API. Use MUI primitives for layout and composition.
+2. **`@percona/percona-ui`** is the Percona design layer on top of MUI (theme, branded components, tables, dialogs). Prefer exports from `@percona/percona-ui` when they wrap or standardize behavior (e.g. `Table`, `Dialog`, `ThemeContextProvider`, `pmmThemeOptions`, `NotistackMuiSnackbar`, `primitives`).
+
+## Do not introduce
+
+- Do not introduce other CSS/UI frameworks (Tailwind, Bootstrap, styled-components, etc.) or ad-hoc global CSS that fights the theme.
+- Do not introduce hard-coded colors, font families, or spacing that bypass the theme. Prefer `sx` with `theme.palette`, `theme.spacing`, breakpoints, and MUI `Typography` variants.
+- Do not introduce custom component libraries outside MUI + `@percona/percona-ui` unless explicitly requested.
+
+## Theming and color mode
+
+- The app root uses `ThemeContextProvider` with `pmmThemeOptions` from `@percona/percona-ui` — do not replace with a separate `ThemeProvider` or duplicate theme objects in feature code.
+- Use `ColorModeContext` / existing hooks (e.g. `useColorMode` in `hooks/theme.ts`) for light/dark; avoid direct `document` or `localStorage` theme hacks.
+
+## Layout and PMM consistency
+
+- Follow established layout patterns: MUI `Stack`, `Box`, `Grid`, page shells like `components/page/Page.tsx` (max width, padding, `gap` aligned with existing `sx`).
+- Avoid one-off page structures that break alignment with the rest of PMM (arbitrary full-viewport hacks, inconsistent gutters).
+
+## Styling mechanics
+
+- Prefer **`sx`** and **`useTheme()`** from `@mui/material/styles` for component-level styling.
+- For icons, use **`@mui/icons-material`** (Outlined variants where the codebase already does).
+
+## When something is missing
+
+- If a token or component behavior should be shared across products, explain it to them, plan a change, present it as a proposal to extend **`@percona/percona-ui`** (theme / components) rather than embedding one-off design in PMM only.
+- If unsure whether a primitive exists in `percona-ui`, check that package or Storybook before inventing a parallel implementation in PMM.
+
+## Examples
+
+```tsx
+// Good — MUI + theme tokens
+<Stack spacing={2} sx={{ pt: 1, color: 'text.secondary' }}>
+
+// Bad — unrelated styling stack
+<div className="tailwind-p-4 text-gray-500">
+
+// Good — branded table from design system
+import { Table } from '@percona/percona-ui';
+
+// Bad — pulling in another data-table library for the same job
+```
@@ -158,6 +158,11 @@ export const initialize = () => {
     },
   });
 
+  messenger.addListener({
+    type: 'SETTINGS_CHANGED',
+    onMessage: () => getAppEvents().publish(new SettingsUpdatedEvent()),
+  });
+
   getAppEvents().subscribe(SettingsUpdatedEvent, () => {
     messenger.sendMessage({
       type: 'SETTINGS_CHANGED',

@@ -12,6 +12,7 @@ See the [PMM Documentation](https://www.percona.com/doc/percona-monitoring-and-m
 See detailed information about prerequisites and setup [here](../../README.md)
 
 # Locally testing @percona/percona-ui
+
 - Checkout code from https://github.com/percona/percona-ui
 - From the lib folder, run `pnpm build:watch` and `yarn link`
 - On this repo's `ui/apps/pmm` folder, run `yarn link @percona/percona-ui` and uncomment the `exclude` block from `vite.config.ts`

@@ -22,10 +22,11 @@
     "@fontsource/poppins": "^5.0.15",
     "@fontsource/roboto": "^5.0.14",
     "@fontsource/roboto-mono": "^5.0.18",
+    "@hookform/resolvers": "^5.2.2",
     "@mui/icons-material": "^7.3.7",
     "@mui/material": "^7.3.7",
     "@mui/x-date-pickers": "^7.5.0",
-    "@percona/percona-ui": "1.0.13",
+    "@percona/percona-ui": "1.0.15",
     "@pmm/shared": "*",
     "@reactour/tour": "^3.8.0",
     "@tanstack/react-query": "^5.45.1",
@@ -35,13 +36,15 @@
     "notistack": "^3.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-hook-form": "^7.71.2",
     "react-is": "18.3.1",
     "react-markdown": "^9.0.1",
     "react-router-dom": "^6.30.2",
     "react-syntax-highlighter": "^16.1.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.0",
-    "vite-plugin-svgr": "^4.3.0"
+    "vite-plugin-svgr": "^4.3.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@percona/prettier-config": "^1.1.0",

@@ -26,6 +26,9 @@ const Providers: FC<PropsWithChildren> = () => (
                 <TourProvider>
                   <GlobalStyles
                     styles={{
+                      html: {
+                        scrollbarGutter: 'stable',
+                      },
                       'html, body, div#root': {
                         minHeight: '100vh',
                       },

@@ -1,6 +1,10 @@
 import {
   GetFrontendSettingsResponse,
+  GetReadonlySettingsResponse,
   GetSettingsResponse,
+  ReadonlySettings,
+  Settings,
+  UpdateSettingsPayload,
 } from 'types/settings.types';
 import { api, grafanaApi } from './api';
 
@@ -9,8 +13,10 @@ export const getSettings = async () => {
   return res.data.settings;
 };
 
-export const getReadonlySettings = async () => {
-  const res = await api.get<GetSettingsResponse>('/server/settings/readonly');
+export const getReadonlySettings = async (): Promise<ReadonlySettings> => {
+  const res = await api.get<GetReadonlySettingsResponse>(
+    '/server/settings/readonly'
+  );
   return res.data.settings;
 };
 
@@ -19,3 +25,10 @@ export const getFrontendSettings = async () => {
     await grafanaApi.get<GetFrontendSettingsResponse>('/frontend/settings');
   return res.data;
 };
+
+export const updateSettings = async (
+  payload: UpdateSettingsPayload
+): Promise<Settings> => {
+  const res = await api.put<GetSettingsResponse>('/server/settings', payload);
+  return res.data.settings;
+};
@@ -20,8 +20,8 @@ export const getStyles = (theme: Theme) => ({
         : theme.palette.error.dark,
     backgroundColor:
       theme.palette.mode === 'light'
-      ? theme.palette.error.surface
-      : theme.palette.error.dark,
+        ? theme.palette.error.surface
+        : theme.palette.error.dark,
     transition: 'none',
   },
   down: {

@@ -1,6 +1,8 @@
 import { Theme } from '@mui/material';
 
-export const getStyles = ({ palette: { background, warning, error, info } }: Theme) => ({
+export const getStyles = ({
+  palette: { background, warning, error, info },
+}: Theme) => ({
   icon: {
     width: 20,
     height: 20,

@@ -32,7 +32,7 @@ const setup = ({
       )}
     </TestWrapper>
   );
-}
+};
 
 describe('MainWithNav', () => {
   it('shows loading', () => {
@@ -60,12 +60,16 @@ describe('MainWithNav', () => {
   });
 
   it('hides sidebar so the renderer gets a minimal layout', () => {
-    setup({ isLoading: false, isLoggedIn: true, kioskModeActive: false, search: 'render=1' });
+    setup({
+      isLoading: false,
+      isLoggedIn: true,
+      kioskModeActive: false,
+      search: 'render=1',
+    });
 
     expect(screen.queryByTestId('pmm-sidebar')).toBeNull();
   });
 
-
   it('shows sidebar when not in renderer mode', () => {
     setup({ isLoading: false, isLoggedIn: true, kioskModeActive: false });
 

@@ -12,7 +12,10 @@ export const QanHeaderActions: FC = () => {
 
   const handleCopy = async () => {
     try {
-      const path = constructUrl(location).replace(/\/pmm-ui\/(next\/)?graph\//, '');
+      const path = constructUrl(location).replace(
+        /\/pmm-ui\/(next\/)?graph\//,
+        ''
+      );
       const res = location.pathname.includes('/graph')
         ? await createShortUrl(path)
         : { url: window.location.href };

@@ -2,8 +2,11 @@ import { FC } from 'react';
 import { PageProps } from './Page.types';
 import {
   Alert,
+  Box,
   Card,
   CardActions,
+  Divider,
+  GlobalStyles,
   Link,
   Stack,
   Typography,
@@ -14,46 +17,71 @@ import { PMM_HOME_URL } from 'lib/constants';
 import { Footer } from 'components/footer';
 import { updateDocumentTitle } from 'utils/document.utils';
 
-export const Page: FC<PageProps> = ({ title, topBar, footer, children }) => {
+export const Page: FC<PageProps> = ({
+  title,
+  topBar,
+  footer,
+  children,
+  fullWidth,
+  surface,
+}) => {
   const { user } = useUser();
   updateDocumentTitle(title);
 
   return (
-    <Stack
-      sx={(theme) => ({
-        flex: 1,
-        [theme.breakpoints.up('lg')]: {
-          width: 1000,
-        },
-        width: {
-          md: 'auto',
-        },
-        p: {
-          xs: 2,
-        },
-        mx: 'auto',
-        gap: 3,
-        mt: 1,
-      })}
-    >
-      {topBar}
-      {!!title && <Typography variant="h2">{title}</Typography>}
-      {user?.isAuthorized ? (
-        children
-      ) : (
-        <Card variant="outlined" sx={{ p: 2 }}>
-          <Alert severity="error" sx={{ mb: 1 }}>
-            {Messages.noAcccess}
-          </Alert>
-          <CardActions>
-            <Typography>
-              {Messages.goBack}
-              <Link href={PMM_HOME_URL}>{Messages.home}</Link>
-            </Typography>
-          </CardActions>
-        </Card>
+    <>
+      {surface && (
+        <GlobalStyles
+          styles={(theme) => ({
+            'html, body': {
+              backgroundColor:
+                surface === 'paper'
+                  ? theme.palette.background.paper
+                  : theme.palette.background.default,
+            },
+          })}
+        />
       )}
-      {footer !== undefined ? footer : <Footer />}
-    </Stack>
+      <Stack
+        sx={{
+          flex: 1,
+          width: '100%',
+          maxWidth: {
+            lg: 1000,
+          },
+          p: {
+            xs: 2,
+          },
+          px: {
+            md: fullWidth ? 4 : undefined,
+          },
+          mx: 'auto',
+          gap: 2,
+          mt: 1,
+        }}
+      >
+        {topBar}
+        {!!title && <Typography variant="h2">{title}</Typography>}
+        <Box sx={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
+          {user?.isAuthorized ? (
+            children
+          ) : (
+            <Card variant="outlined" sx={{ p: 2 }}>
+              <Alert severity="error" sx={{ mb: 1 }}>
+                {Messages.noAcccess}
+              </Alert>
+              <CardActions>
+                <Typography>
+                  {Messages.goBack}
+                  <Link href={PMM_HOME_URL}>{Messages.home}</Link>
+                </Typography>
+              </CardActions>
+            </Card>
+          )}
+        </Box>
+        <Divider />
+        {footer !== undefined ? footer : <Footer />}
+      </Stack>
+    </>
   );
 };
@@ -4,4 +4,6 @@ export interface PageProps extends PropsWithChildren {
   title?: string;
   footer?: ReactNode;
   topBar?: ReactNode;
+  fullWidth?: boolean;
+  surface?: 'default' | 'paper';
 }
@@ -4,6 +4,8 @@ import { NavigationHeading } from './nav-heading';
 import { Drawer } from './drawer';
 import { NavItem } from './nav-item';
 import List from '@mui/material/List';
+import useMediaQuery from '@mui/material/useMediaQuery';
+import { useTheme } from '@mui/material/styles';
 import { findActiveNavItem } from 'utils/navigation.utils';
 import { useLocation } from 'react-router-dom';
 import { NavItem as NavItemType } from 'types/navigation.types';
@@ -13,6 +15,8 @@ export const Sidebar: FC = () => {
   const [activeItem, setActiveItem] = useState<NavItemType>(navTree[0]);
   const [animating, setAnimating] = useState(false);
   const location = useLocation();
+  const theme = useTheme();
+  const isNarrow = useMediaQuery(theme.breakpoints.down('md'));
 
   const toggleSidebar = useCallback(() => {
     setNavOpen(!navOpen);
@@ -35,6 +39,13 @@ export const Sidebar: FC = () => {
     }
   }, [navTree, location.pathname]);
 
+  const handleNavItemClick = () => {
+    // autoclose sidebar when layout is narrow
+    if (isNarrow) {
+      setNavOpen(false);
+    }
+  };
+
   return (
     <Drawer
       open={navOpen}
@@ -63,6 +74,7 @@ export const Sidebar: FC = () => {
             item={item}
             activeItem={activeItem}
             drawerOpen={navOpen}
+            onClick={handleNavItemClick}
           />
         ))}
       </List>

@@ -16,6 +16,17 @@ const Drawer = styled(MuiDrawer, {
       style: {
         ...openedMixin(theme),
         '& .MuiDrawer-paper': openedMixin(theme),
+        [theme.breakpoints.down('md')]: {
+          ...closedMixin(theme),
+          '& .MuiDrawer-paper': {
+            ...openedMixin(theme),
+            position: 'fixed',
+            top: 0,
+            left: 0,
+            height: '100vh',
+            zIndex: theme.zIndex.drawer + 1,
+          },
+        },
       },
     },
     {