adithiyan/ifixkart-admin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ifixkart-admin/SKILL.md

1238 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.**
Reference in a new issue View git blame Copy permalink