Design System
AI Rules
Mandatory UI rules for AI coding agents
AI Agent UI Rules
These rules are MANDATORY for all AI coding agents working on HRMS UI. Violations will result in rejected PRs.
Before Writing ANY UI Code
Read and internalize these rules. They are non-negotiable.
Mandatory Rules
| # | Rule | Rationale |
|---|---|---|
| 1 | NEVER create plain white cards with gray borders | Looks like a wireframe, not a shipped product |
| 2 | ALWAYS use gradient backgrounds for stats cards | Visual hierarchy and "shipped product" look |
| 3 | ALWAYS use shadow-lg on content cards (not borders) | Soft, modern aesthetic |
| 4 | ALWAYS use rounded-2xl (16px) on cards | Consistent with Apple/iOS design language |
| 5 | ALWAYS use CSS variables (bg-card, not bg-white) | Enables dark mode support |
| 6 | ALWAYS support dark mode with dark: variants | Required for theme-aware components |
| 7 | NEVER use spacing less than p-6 on cards | Generous whitespace is core to the design |
| 8 | NEVER create new button/component variants without updating design system | Prevents design drift |
Required Imports
Every UI file MUST import from the correct locations:
// Utility function - ALWAYS use
import { cn } from "@/lib/utils";
// Components - from UI folder
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
// ... etc
// Icons - from Lucide
import { Users, Calendar, FileText } from "lucide-react";Component Patterns
Stats Card (REQUIRED Pattern)
// CORRECT - Use this exact pattern
<div className="
bg-gradient-to-br from-blue-500 to-blue-600
rounded-2xl p-6 text-white shadow-lg
transition-all hover:shadow-xl hover:-translate-y-1 duration-300
">
<div className="flex items-center justify-between">
<div>
<p className="text-white/80 text-sm font-medium mb-1">{title}</p>
<p className="text-4xl font-semibold tracking-tight">{value}</p>
</div>
<div className="w-12 h-12 bg-white/20 rounded-2xl flex items-center justify-center backdrop-blur-sm">
<Icon className="w-6 h-6 text-white" />
</div>
</div>
</div>// WRONG - Never do this
<div className="bg-white border border-gray-200 rounded-lg p-4">
<span className="text-gray-600">{title}</span>
<span className="text-2xl">{value}</span>
</div>Content Card (REQUIRED Pattern)
// CORRECT
<div className="
bg-card text-card-foreground
rounded-2xl p-6
shadow-lg shadow-gray-200/50 dark:shadow-black/40
border-none
">
{children}
</div>// WRONG
<div className="bg-white border border-gray-100 rounded-md p-4">
{children}
</div>Button (REQUIRED Pattern)
// CORRECT - Primary button
<Button className="
bg-primary text-white
rounded-full
shadow-lg shadow-primary/25
hover:shadow-primary/35 hover:scale-[1.02]
active:scale-95
transition-all
">
Create
</Button>AI Floating Button (REQUIRED Pattern)
// CORRECT
<button className="
fixed z-50
bottom-6 right-6 md:bottom-8 md:right-8
w-14 h-14 rounded-full
bg-gradient-to-br from-violet-500 via-purple-500 to-fuchsia-500
text-white
shadow-xl shadow-violet-500/30
hover:shadow-2xl hover:shadow-violet-500/40
hover:scale-105 active:scale-95
transition-all duration-200
">
<Sparkles className="w-6 h-6" />
</button>Gradient Reference
Use these exact gradients for stats cards:
| Purpose | Gradient |
|---|---|
| Employees/Primary | from-blue-500 to-blue-600 |
| On Leave/Warning | from-amber-400 to-orange-500 |
| Pending/Secondary | from-violet-500 to-purple-600 |
| Open Positions/Success | from-emerald-400 to-green-500 |
| AI Button | from-violet-500 via-purple-500 to-fuchsia-500 |
Color Usage
CSS Variables (ALWAYS Use)
| Variable | Light Mode | Dark Mode | Usage |
|---|---|---|---|
bg-background | #F2F2F7 | #000000 | Main app background |
bg-card | #FFFFFF | #1C1C1E | Cards, modals |
bg-primary | #008CF0 | #008CF0 | Primary actions |
text-foreground | #000000 | #FAFAFA | Primary text |
text-muted-foreground | #8E8E93 | varies | Secondary text |
FORBIDDEN Hard-Coded Colors
Never use these directly:
bg-white→ usebg-cardtext-black→ usetext-foregroundtext-gray-500→ usetext-muted-foregroundborder-gray-200→ useborder-border
Shadow Rules
| Component | Light Mode | Dark Mode |
|---|---|---|
| Content Cards | shadow-lg shadow-gray-200/50 | shadow-lg shadow-black/40 |
| Stats Cards | shadow-lg | shadow-lg |
| Buttons | shadow-lg shadow-primary/25 | same |
| AI Button | shadow-xl shadow-violet-500/30 | same |
| Sidebar | shadow-2xl shadow-black/5 | same |
Animation Requirements
Hover Effects
| Component | Effect |
|---|---|
| Stats Cards | hover:shadow-xl hover:-translate-y-1 duration-300 |
| Buttons | hover:scale-[1.02] active:scale-95 |
| AI Button | hover:scale-105 active:scale-95 |
Framer Motion Patterns
// Modal/Dialog animation
const modalVariants = {
initial: { opacity: 0, y: 20, scale: 0.95 },
animate: { opacity: 1, y: 0, scale: 1 },
exit: { opacity: 0, y: 20, scale: 0.95 },
};
const transition = { type: "spring", damping: 25, stiffness: 300 };Code Review Checklist
REJECT if any of these are true:
- Plain white cards with gray borders
- Hard-coded colors (
bg-whiteinstead ofbg-card) - Missing dark mode support
- Spacing below minimum (
p-4instead ofp-6on cards) - Custom variants not in design system
- Missing hover/focus states
-
rounded-lginstead ofrounded-2xlon cards - Borders instead of shadows on content cards
APPROVE if all of these are true:
- Follows design system patterns exactly
- Uses CSS variables throughout
- Dark mode works correctly
- Responsive design implemented
- All components from
@/components/ui - Proper hover and focus states
- Correct spacing and radius