FPSMS-frontend/.cursor/rules.md

Project Guidelines - Always Follow These Rules

UI Standard (apply to all pages)

All pages under (main) must share the same look and feel. Use this as the single source of truth for new and existing pages.

Stack & layout

• Styling: Tailwind CSS for layout and utilities. MUI components are used with the project theme (primary blue, neutral borders) so they match the standard.
• Page wrapper: Do not add a full-page wrapper with its own background or padding. The main layout (src/app/(main)/layout.tsx) already provides:
  • Background: bg-slate-50 (light), dark:bg-slate-900 (dark)
  • Padding: p-4 sm:p-4 md:p-6 lg:p-8
• Responsive: Mobile-first; use breakpoints sm, md, lg (e.g. flex-col sm:flex-row, p-4 md:p-6 lg:p-8).
• Spacing: Multiples of 4px only: p-4, m-8, gap-2, gap-4, mb-4, etc.

Theme & colors

• Default: Light mode. Dark mode supported via dark class on html; use dark: Tailwind variants where needed.
• Primary: #3b82f6 (blue) — main actions, links, focus rings. In MUI this is palette.primary.main.
• Accent: #10b981 (emerald) — success, export, confirm actions.
• Design tokens are in src/app/global.css (:root / .dark): --primary, --accent, --background, --foreground, --card, --border, --muted. Use these in custom CSS or Tailwind when you need to stay in sync.

Page structure (every page)

1. Page title bar (consistent across all pages):

   • Use the shared PageTitleBar component from @/components/PageTitleBar so every menu destination has the same title style.
   • It renders a bar with: left primary accent (4px), white/card background, padding, and title typography (text-xl / sm:text-2xl, bold, slate-900 / dark slate-100).
   • Usage: <PageTitleBar title={t("Page Title")} className="mb-4" /> or with actions: <PageTitleBar title={t("Page Title")} actions={<Button>...</Button>} className="mb-4" />.
   • Do not put a bare <h1> or <Typography variant="h4"> as the main page heading; use PageTitleBar for consistency.

2. Content: Fragments or divs with space-y-4 (or Stack spacing={2} in MUI) between sections. No extra full-width background wrapper.

Search criteria

• When using the shared SearchBox component: It already uses the standard card style. Ensure the parent page does not wrap it in another card.
• When building a custom search/query bar: Use the shared class so it matches SearchBox:
  • Wrapper: className="app-search-criteria ..." (plus layout classes like flex flex-wrap items-center gap-2 p-4).
  • Label for “Search criteria” style: className="app-search-criteria-label" if you need a small uppercase label.
• Search button: Primary action = blue (MUI variant="contained" color="primary", or Tailwind bg-blue-500 text-white). Reset = outline with neutral border (e.g. MUI variant="outlined" with slate border, or Tailwind border border-slate-300).

Forms & inputs

• Standard look (enforced by MUI theme): White background, border #e2e8f0 (neutral 200), focus ring primary blue. Use MUI TextField / FormControl / date pickers as-is; the theme in src/theme/devias-material-kit already matches this.
• Tailwind-only forms (e.g. /ps): Use the same tokens: border border-slate-300, bg-white, focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20, text-slate-900, placeholder-slate-400.

Buttons

• Primary action: Blue filled — MUI variant="contained" color="primary" or Tailwind bg-blue-500 text-white hover:bg-blue-600.
• Secondary / cancel: Outline, neutral — MUI variant="outlined" with border #e2e8f0 / #334155 text, or Tailwind border border-slate-300 text-slate-700 hover:bg-slate-100.
• Accent (e.g. export, success): Green — MUI color="success" or Tailwind bg-emerald-500 / text-emerald-600 for outline.
• Spacing: Use gap-2 or gap-4 between buttons; keep padding multiples of 4 (e.g. px-4 py-2).

Tables & grids

• Container: Wrap tables/grids in a card-style container so they match across pages:
  • MUI: <Paper variant="outlined" sx={{ overflow: "hidden" }}> (theme already uses 8px radius, neutral border).
  • Tailwind: rounded-lg border border-slate-200 bg-white shadow-sm.
• Data grid (MUI X DataGrid): Use StyledDataGrid from @/components/StyledDataGrid. It applies header bg neutral[50], header text neutral[700], cell padding and borders to match the standard.
• Table (MUI Table): Use SearchResults when you have a paginated list; it uses Paper variant="outlined" and theme table styles (header bg, borders).
• Header row: Background bg-slate-50 / neutral[50], text text-slate-700 / neutral[700], font-weight 600, padding px-4 py-3 or theme default.
• Body rows: Border border-slate-200 / theme divider, hover hover:bg-slate-50 / action.hover.

Cards & surfaces

• Standard card: 8px radius, 1px border (var(--border) or neutral[200]), white background (var(--card)), light shadow (0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)). MUI Card and Paper are themed to match.
• Search-criteria card: Use class app-search-criteria (left 4px primary border, same radius and shadow as above).

Menu bar & sidebar

• App bar (top): White background, 1px bottom border (palette.divider), no heavy shadow (elevation={0}). Toolbar with consistent min-height and horizontal padding. Profile and title use text.secondary and font-weight 600.
• Sidebar (navigation drawer): Same as cards: white background, 1px right border, light shadow. Logo area with padding and bottom border; nav list with 4px/8px margins, 8px border-radius on items. Selected item: primary light background tint, primary text/icon, font-weight 600. Hover: neutral hover background. Use ListItemButton with mx: 1, minWidth: 40 on icons. Child items slightly smaller font (0.875rem).
• Profile dropdown: Menu with 8px radius, 1px border (outlined Paper). Dense list, padding on header and items. Sign out as MenuItem.
• Selection logic: Nav item is selected when pathname === item.path or pathname.startsWith(item.path + "/"). Parent with children expands on click; leaf items navigate via Link.
• Icons: Use one icon per menu item that matches the action or section (e.g. Dashboard, LocalShipping for delivery, CalendarMonth for scheduling, Settings for settings). Prefer distinct MUI icons so items are easy to scan; avoid reusing the same icon for many items.

Reference implementations

• /ps — Tailwind-only: query bar (app-search-criteria), buttons, table container, modals. Good reference for Tailwind patterns.
• /do — SearchBox + StyledDataGrid inside Paper; page title on layout. Good reference for MUI + layout.
• /jo — SearchBox + SearchResults (Paper-wrapped table); page title on layout. Same layout and search pattern as /do.

When adding a new page, reuse the same structure: rely on the main layout for background/padding, use one optional standard <h1>, then SearchBox (or app-search-criteria for custom bars), then Paper-wrapped grid/table or other content, with buttons and forms following the rules above.

Checklist for new pages

• No extra full-page wrapper (background/padding come from main layout).
• Page title: use <PageTitleBar title={...} /> (optional actions). Add className="mb-4" for spacing below.
• Search/filter: use SearchBox or a div with className="app-search-criteria" for the bar.
• Tables/grids: wrap in Paper variant="outlined" (MUI) or rounded-lg border border-slate-200 bg-white shadow-sm (Tailwind); use StyledDataGrid or SearchResults where applicable.
• Buttons: primary = blue contained, secondary = outlined neutral, accent = green for success/export.
• Spacing: multiples of 4px (p-4, gap-2, mb-4); responsive with sm/md/lg.