# CRMS-Inspired Admin Dashboard UI Skill

## Purpose

Transform the **existing admin-ecommerce project UI** to follow the visual design language, layout structure, spacing, component patterns, and interaction patterns of the CRMS reference dashboard provided by the user.

This is a **UI/UX modification skill only**.

Do **not** rewrite, replace, remove, or alter existing business functionality.

---

# 1. Primary Rule: UI Only

Before making any changes, analyze the existing codebase and understand the current implementation.

Preserve all existing:

* Routes and navigation logic
* API calls
* Backend integration
* Authentication
* Authorization
* Role and permission logic
* React Query logic
* Zustand stores
* React Hook Form logic
* Zod schemas and validation
* Existing TypeScript interfaces and types
* Data models
* CRUD functionality
* Table functionality
* Filtering logic
* Search functionality
* Pagination
* Sorting
* Existing event handlers
* Loading states
* Error states
* Toast notifications
* Existing component props and contracts

## Important

Do not change functionality just to make the UI easier to implement.

The goal is:

> **Keep the application behavior exactly the same. Improve only the presentation layer.**

If existing functionality and the new UI conflict, preserve the existing functionality and adapt the UI around it.

---

# 2. Technology Constraints

The project uses:

* Next.js 16
* React 19
* TypeScript
* Tailwind CSS v4
* Framer Motion
* Lucide React
* TanStack React Query
* TanStack Table
* TanStack Virtual
* React Hook Form
* Zod
* Zustand
* next-themes
* Recharts
* Sonner

Use the existing stack.

Do not introduce Bootstrap, jQuery, another CSS framework, or unnecessary UI libraries.

Do not add dependencies unless absolutely required.

Prefer existing utilities and installed packages.

Use:

```tsx
lucide-react
```

for icons.

Use:

```tsx
framer-motion
```

only where animation improves the existing UX.

Use:

```tsx
recharts
```

for existing or new visual presentation of chart data without changing the underlying data source.

---

# 3. Existing Design System Must Be Preserved

The existing project already has a Tailwind v4 CSS variable design system.

Do not replace it.

Do not create a second competing design system.

Use the existing semantic variables:

```css
--background
--foreground
--card
--card-foreground
--primary
--primary-foreground
--secondary
--secondary-foreground
--muted
--muted-foreground
--accent
--accent-foreground
--destructive
--border
--input
--ring
--sidebar
--sidebar-foreground
--sidebar-active
--success
--warning
--info
```

The existing primary brand color is:

```text
#e4382f
```

This is the application's main accent color.

Do not replace the brand color with the original CRMS accent color if different.

Instead:

> Reproduce the CRMS UI structure and visual hierarchy while applying the existing project color system.

---

# 4. Design Philosophy

The target UI should feel like a modern, professional SaaS administration dashboard.

Follow these principles:

* Clean
* Compact
* Structured
* Information dense without feeling crowded
* Consistent across every page
* Professional
* Responsive
* Reusable
* Minimal unnecessary decoration

Avoid:

* Excessive gradients
* Large empty spaces
* Oversized cards
* Excessive border radius
* Glassmorphism
* Heavy shadows
* Random colors
* Huge page headings
* Oversized buttons
* Excessive animations
* Every section looking like an isolated floating widget

The UI should feel like one coherent admin application.

---

# 5. Application Shell

Follow this general structure:

```text
┌──────────────────────────────────────────────────────────────┐
│ Sidebar │ Top Header                                         │
│         ├────────────────────────────────────────────────────┤
│         │ Breadcrumb / Page Title / Actions                  │
│         ├────────────────────────────────────────────────────┤
│         │                                                    │
│         │ Main Page Content                                  │
│         │                                                    │
│         │ Cards / Tables / Forms / Charts                    │
│         │                                                    │
└─────────┴────────────────────────────────────────────────────┘
```

The application shell should be reusable.

Prefer a structure similar to:

```text
AppLayout
 ├── Sidebar
 ├── Header
 └── MainContent
      ├── PageHeader
      └── PageContent
```

Do not duplicate layout logic across individual pages.

---

# 6. Sidebar Design

The sidebar should follow a professional CRM/admin pattern.

## Structure

Include:

1. Brand/logo area
2. Main navigation
3. Navigation groups
4. Optional group labels
5. Nested menu support
6. Active item state
7. Expand/collapse behavior where already supported

## Visual Style

Use:

* Compact vertical spacing
* Small but readable icons
* Consistent icon alignment
* Clear hierarchy
* Subtle hover states
* Strong active state
* Group labels with smaller typography
* Smooth submenu transitions

The sidebar should use:

```css
var(--sidebar)
```

for the main background.

Use:

```css
var(--sidebar-foreground)
```

for normal navigation text.

Use:

```css
var(--sidebar-active)
```

for active navigation emphasis.

Do not hardcode unrelated colors.

## Active Navigation

The active item should be immediately recognizable.

Recommended pattern:

```text
Active item:
- Brand-colored background or accent indicator
- White/high-contrast icon
- Stronger text weight

Inactive item:
- Transparent background
- Muted sidebar text
- Subtle hover background
```

Avoid large pill-shaped menu items unless the existing application already uses them consistently.

---

# 7. Top Header

The header should be compact and functional.

Recommended layout:

```text
[Sidebar Toggle] [Global Search / Context]

                              [Theme] [Notifications] [Profile]
```

Use:

* White or card background
* Bottom border using `--border`
* Compact height
* Horizontally aligned controls
* Icon buttons with consistent dimensions
* Clear spacing between actions

Do not make the header excessively tall.

The header should visually separate navigation from application content.

---

# 8. Page Header Pattern

Every main page should follow a consistent page header.

Recommended structure:

```text
Page Title                         Primary Action
Breadcrumb / Context               Secondary Actions
```

Example:

```text
Products
Dashboard / Products                         + Add Product
```

Rules:

* Keep the page title concise.
* Do not use oversized headings.
* Breadcrumbs should be subtle.
* Actions should align to the right on desktop.
* Stack intelligently on smaller screens.
* Primary actions should use the existing primary color.
* Secondary actions should use outline or neutral styling.

Avoid wrapping the entire page header in a large unnecessary card.

The page header should generally be part of the page layout, not a floating container.

---

# 9. Spacing System

The CRMS-style UI should be compact but comfortable.

Prefer consistent spacing.

Use a predictable scale such as:

```text
4px
8px
12px
16px
20px
24px
32px
```

General guidance:

* Small gap between related controls: `8px`
* Standard component spacing: `12px` or `16px`
* Card padding: `16px` to `24px`
* Major section spacing: `20px` to `24px`

Avoid large empty areas unless they intentionally improve readability.

Do not use arbitrary spacing values throughout the project.

---

# 10. Cards

Cards are a major part of the UI.

Use the existing:

```css
--card
--card-foreground
--border
```

Recommended card style:

```text
Background: var(--card)
Border: subtle 1px var(--border)
Radius: 8px to 12px
Shadow: none or extremely subtle
Padding: 16px to 24px
```

Cards should not look overly rounded or oversized.

Avoid:

```text
rounded-3xl
heavy drop shadows
large padding
huge empty card areas
```

Use cards only when they provide meaningful grouping.

Do not place every small element inside its own card.

---

# 11. Dashboard Widgets

Dashboard statistics should follow a compact KPI pattern.

Recommended structure:

```text
┌──────────────────────────────┐
│ Label                  Icon  │
│                              │
│ 1,245                        │
│ +12.5% from last period      │
└──────────────────────────────┘
```

Rules:

* Label should be smaller and muted.
* Main value should have strong hierarchy.
* Trend indicators should be visually distinct.
* Icons should use subtle background containers.
* Do not make the icon container too large.
* Keep card heights consistent when displayed in a grid.

Use semantic colors:

```text
Success → --success
Warning → --warning
Info → --info
Error → --destructive
Primary → --primary
```

Do not use random Tailwind color palettes when a semantic variable exists.

---

# 12. Charts and Analytics Sections

For analytics cards:

```text
Card Header
├── Title
├── Optional description
└── Filter / Date Range

Chart Area

Optional Legend / Summary
```

Use Recharts where charts already exist.

Do not change:

* API data
* Data transformation logic
* Query logic
* Business calculations

Only improve:

* Chart container
* Typography
* Legend
* Tooltip styling
* Layout
* Spacing
* Responsive behavior

Charts should integrate visually with the design system.

Avoid excessive grid lines or visual noise.

---

# 13. Tables

Tables should follow a modern CRM/admin pattern.

Recommended structure:

```text
Card
├── Header
│   ├── Title / Record Count
│   └── Actions
│
├── Toolbar
│   ├── Search
│   ├── Filters
│   └── View / Export / Add actions
│
├── Table
│
└── Pagination
```

## Table Style

Use:

* Compact row height
* Clear column alignment
* Muted table header
* Subtle row separators
* Soft hover state
* Sticky header only when useful
* Horizontal scrolling on smaller screens

Avoid excessive borders around every cell.

Prefer horizontal row separation.

Example hierarchy:

```text
Header:
- Smaller
- Muted
- Semibold

Cell:
- Normal readable text

Primary entity:
- Stronger text

Secondary information:
- Muted text
```

Do not change TanStack Table logic.

Only modify the presentation layer.

---

# 14. Search and Filter Toolbars

Avoid large search cards with too many buttons.

Instead, create a compact responsive toolbar.

Desktop:

```text
[Search Input] [Filter] [Sort] [More]              [Primary Action]
```

Smaller screens:

```text
[Search Input                      ]
[Filter] [Sort] [More] [Add]
```

Rules:

* Search input should be the largest flexible element.
* Secondary controls should be icon buttons or compact buttons when appropriate.
* Group related controls.
* Hide low-priority actions inside a dropdown when space is limited.
* Do not allow controls to consume excessive vertical space.

Use existing functionality.

Do not remove filters or actions.

If necessary, move existing actions into a dropdown or overflow menu while preserving access.

---

# 15. Buttons

Create a consistent button hierarchy.

## Primary

Use for the main action:

```text
Background: --primary
Text: --primary-foreground
```

Examples:

```text
Add Product
Create Order
Save Changes
```

## Secondary

Use for non-primary actions.

Recommended:

```text
Neutral/card background
Border
Foreground text
```

## Icon Buttons

Use for:

* Filter
* More actions
* Edit
* Delete
* Refresh
* Settings
* Notifications

Keep icon buttons consistent in size.

Do not create different button styles on every page.

---

# 16. Forms

Forms should be visually compact and structured.

Use a consistent field pattern:

```text
Label
Input / Select / Control
Helper text or Validation message
```

Rules:

* Keep labels above fields.
* Use consistent control heights.
* Align related fields in responsive grids.
* Avoid excessive nesting.
* Avoid placing each field inside a separate card.
* Group fields only when there is a meaningful section.

Recommended:

```text
Desktop:
2 or 3 column responsive grid

Mobile:
1 column
```

Do not change:

* React Hook Form
* Zod validation
* Field names
* Submit handlers
* Form submission logic

Only change the visual layout.

---

# 17. Modals and Right-Side Drawers

For create/edit experiences, prefer the interaction pattern already used by the application.

When a right-side panel is appropriate:

```text
Closed
↓
Smooth slide from right
↓
Form content
↓
Save
↓
Success
↓
Close
```

Use Framer Motion only if the project does not already have an existing animation implementation.

Keep transitions subtle:

```text
Duration: approximately 200ms–300ms
Ease: smooth
```

Do not introduce heavy animations.

Do not alter submit behavior.

After successful submission, preserve the existing success and refresh behavior.

---

# 18. Dropdowns and Action Menus

Use compact action menus for secondary actions.

Typical actions:

```text
Edit
Duplicate
Archive
Delete
```

Destructive actions must remain visually distinguishable.

Use:

```css
--destructive
```

Do not expose every action as a visible button when space is limited.

---

# 19. Badges and Status

Status indicators should be compact and easy to scan.

Recommended statuses:

```text
Active
Inactive
Pending
Completed
Cancelled
Draft
Published
```

Use semantic colors and subtle backgrounds.

Example:

```text
Success → green semantic styling
Warning → amber semantic styling
Info → info semantic styling
Destructive → red semantic styling
```

Badges should not dominate the interface.

Avoid overly large pills.

---

# 20. Icons

Use `lucide-react`.

Rules:

* Use consistent stroke widths.
* Use consistent icon sizes.
* Standard interface icons: approximately 16px–20px.
* Larger dashboard icons: approximately 20px–24px.
* Do not mix multiple icon libraries.
* Do not use emoji as UI icons.

Icons must align correctly with text.

---

# 21. Typography

Maintain a clear hierarchy.

Recommended hierarchy:

```text
Page Title
20px–24px
Semibold / Bold

Section Title
16px–18px
Semibold

Card Label
12px–14px
Medium / Semibold

Body
13px–15px
Normal

Secondary Text
12px–14px
Muted
```

Do not use extremely large typography for normal dashboard pages.

Use:

```css
var(--foreground)
```

for primary text.

Use:

```css
var(--muted-foreground)
```

for secondary information.

---

# 22. Light and Dark Mode

The existing dark mode system must continue working.

Do not:

* Remove `.dark` overrides.
* Replace CSS variables with hardcoded light colors.
* Add components that only work in light mode.

Every UI change must be tested in:

```text
Light Mode
Dark Mode
```

When adding new styles:

Prefer:

```tsx
bg-card
text-foreground
border-border
bg-muted
text-muted-foreground
bg-primary
```

Avoid:

```tsx
bg-white
text-slate-900
border-gray-200
```

unless the existing global dark mode override intentionally supports that usage.

The preferred approach is to use semantic design tokens directly.

---

# 23. Responsive Rules

The UI must work across:

```text
Desktop
Laptop
Tablet
Mobile
```

Recommended behavior:

## Desktop

* Full sidebar
* Full table layout
* Inline actions
* Multi-column forms

## Tablet

* Adaptive sidebar
* Reduced spacing
* Wrapping page actions
* Responsive card grids

## Mobile

* Overlay sidebar
* Single-column layout
* Horizontally scrollable tables
* Compact action controls
* Stacked forms
* Full-width primary actions where appropriate

Do not simply shrink the desktop UI.

Reorganize controls intelligently.

---

# 24. Animation Rules

Animations should feel subtle and functional.

Allowed:

* Sidebar transition
* Dropdown fade/scale
* Drawer slide
* Modal appearance
* Small hover transitions
* Card interaction feedback

Avoid:

* Constant animation
* Bouncing elements
* Large entrance animations
* Excessive motion
* Long animation durations

Respect:

```css
prefers-reduced-motion
```

The existing reduced motion implementation must remain intact.

---

# 25. Component Reusability

Before creating a new UI component:

1. Search the existing project.
2. Check whether a similar component already exists.
3. Reuse or improve the existing component when possible.
4. Create a reusable component only when it will be used in multiple places.

Useful reusable UI patterns include:

```text
AppLayout
SidebarNavItem
SidebarGroup
PageHeader
PageActionBar
StatCard
SectionCard
TableToolbar
StatusBadge
EmptyState
LoadingState
IconButton
ConfirmDialog
SlideOver
```

Do not create duplicate versions of the same UI pattern.

---

# 26. CSS Rules

Modify the existing project CSS carefully.

Do not rewrite the entire stylesheet unless necessary.

Do not remove existing:

* Theme variables
* Dark mode support
* Accessibility styles
* Scrollbar styles
* Reduced motion support

When additional reusable styles are needed:

* Add them in a clearly organized section.
* Use existing CSS variables.
* Avoid global selectors that can unexpectedly affect unrelated pages.
* Avoid `!important` unless working around an unavoidable existing conflict.

Prefer component-level Tailwind classes for page-specific styling.

Use global CSS only for genuinely global patterns.

---

# 27. Existing Global CSS

The existing CSS design system is authoritative.

Specifically preserve:

```css
--background: #f4f7fe;
--foreground: #1b2559;
--card: #ffffff;
--primary: #e4382f;
--sidebar: #1b2559;
--success: #01b574;
--warning: #ffb547;
--info: #4318ff;
```

Preserve the corresponding dark mode variables.

The CRMS-inspired UI should therefore use:

> CRMS layout and component patterns + the existing application's color system.

Do not blindly copy colors from the reference.

---

# 28. Implementation Workflow

Follow this workflow for every UI modification.

## Step 1: Analyze First

Before editing:

* Inspect the relevant page.
* Inspect its parent layout.
* Inspect reusable components.
* Identify existing functionality.
* Identify existing data flow.
* Identify state and event handlers.
* Identify existing responsive behavior.

Do not start rewriting JSX before understanding the component.

## Step 2: Define UI Changes

Determine:

```text
What can change:
- Layout
- Tailwind classes
- Spacing
- Typography
- Component composition
- Icon placement
- Responsive structure
- Visual hierarchy

What must not change:
- Logic
- Data
- APIs
- State
- Validation
- Permissions
- Business rules
```

## Step 3: Reuse

Use existing components wherever possible.

## Step 4: Implement

Modify only the required UI layer.

## Step 5: Verify

After implementation, verify:

```text
- Existing page still renders
- No TypeScript errors
- No broken imports
- No changed API behavior
- Existing forms still submit
- Existing permissions still work
- Existing table behavior still works
- Light mode works
- Dark mode works
- Desktop works
- Mobile works
```

---

# 29. Safety Rules for Code Changes

Never perform broad refactoring when the task is only UI-related.

Do not:

* Rename API fields
* Rename form fields
* Change Zod schemas
* Change API endpoints
* Change database models
* Replace state management
* Rewrite working hooks
* Change permission checks
* Remove loading/error states
* Replace working table logic
* Modify route behavior

If JSX is difficult to restyle because logic and presentation are mixed:

1. Extract presentation components carefully.
2. Keep existing logic intact.
3. Pass the same props and handlers.
4. Verify behavior remains unchanged.

---

# 30. Code Quality

Follow these rules:

* TypeScript must remain valid.
* Avoid `any`.
* Avoid unused imports.
* Avoid duplicate components.
* Avoid dead CSS.
* Avoid hardcoded repeated values when a semantic variable exists.
* Preserve existing naming conventions.
* Keep components readable.
* Do not over-engineer.

Run or verify:

```bash
npm run lint
npm run build
```

Fix UI-related TypeScript or lint issues introduced by the modification.

Do not make unrelated code changes merely to clean up the project.

---

# 31. Visual Checklist

Before considering a page complete, verify:

* [ ] Page follows the shared application shell.
* [ ] Sidebar matches the CRMS-inspired navigation pattern.
* [ ] Header is compact and consistent.
* [ ] Page title and actions are aligned correctly.
* [ ] Excessive empty space has been removed.
* [ ] Cards use consistent padding and radius.
* [ ] Search and filters are compact.
* [ ] Tables are clean and readable.
* [ ] Actions do not consume unnecessary space.
* [ ] Buttons follow a consistent hierarchy.
* [ ] Icons come from Lucide React.
* [ ] Status colors use semantic variables.
* [ ] Existing primary red color is preserved.
* [ ] Light mode works.
* [ ] Dark mode works.
* [ ] Mobile layout works.
* [ ] Existing functionality remains unchanged.
* [ ] No unnecessary dependencies were added.
* [ ] No unrelated files were modified.

---

# 32. Final Instruction

When asked to modify any page in this project:

1. First inspect the existing implementation.
2. Preserve all functionality.
3. Modify only the UI and presentation layer.
4. Follow the CRMS-inspired admin dashboard design language.
5. Use the existing Tailwind v4 CSS variable design system.
6. Preserve the existing primary color and dark mode.
7. Reuse existing components before creating new ones.
8. Keep the interface compact, professional, and responsive.
9. Do not introduce Bootstrap or another UI framework.
10. Do not perform unrelated refactoring.
11. Verify that the application behavior remains exactly the same.

The final result should feel like:

> **A polished, compact, modern CRM/admin dashboard inspired by the provided CRMS reference, while remaining visually branded with the existing project's design tokens and preserving 100% of the current application functionality.**