hms/DESIGN.md

# Design System — Enterprise ERP Platform

> Generated by UI UX Pro Max | Style: Soft UI Evolution | Target: Cross-industry business users

## 1. Visual Theme & Atmosphere

A warm, professional, and approachable design that feels trustworthy for business users across all industries — manufacturing, retail, finance, services, and more. The design uses a clean white canvas with soft blue as the primary brand color, conveying reliability and clarity without feeling cold or corporate.

The Soft UI Evolution style provides subtle depth through improved shadows — softer than flat design but clearer than neumorphism. This creates a sense of modern polish that invites interaction while maintaining excellent readability and accessibility (WCAG AA+).

**Key Characteristics:**
- Clean white canvas with soft blue accent — trustworthy, professional, warm
- Subtle depth through soft shadows — modern but not flat, not skeuomorphic
- Moderate border-radius (10-12px) — friendly but not playful
- Chinese-first typography with Noto Sans SC — readable at all sizes
- Two-tier token system: CSS Variables (`--erp-*`) + Ant Design ConfigProvider
- Dual theme support: light (default) + dark mode

## 2. Color Palette & Roles

### Primary Brand
- **Primary Blue** (`#2563EB`): Primary CTA, active states, links, brand accent
- **Primary Hover** (`#1D4ED8`): Pressed/active primary state
- **Primary Light** (`#EFF6FF`): Primary background tint, subtle highlights
- **Primary Subtle** (`#DBEAFE`): Light blue backgrounds for badges, chips

### Semantic Colors
- **Success Green** (`#059669`): Success states, positive indicators, confirmations
- **Success Light** (`#ECFDF5`): Success background tint
- **Warning Amber** (`#D97706`): Warnings, pending states, attention needed
- **Warning Light** (`#FFFBEB`): Warning background tint
- **Error Red** (`#DC2626`): Errors, destructive actions, required fields
- **Error Light** (`#FEF2F2`): Error background tint
- **Info Blue** (`#0284C7`): Informational elements, tooltips, help text

### Text
- **Primary Text** (`#0F172A`): Headings, primary body text — deep navy, professional
- **Secondary Text** (`#475569`): Descriptions, labels, helper text
- **Tertiary Text** (`#94A3B8`): Placeholders, disabled text, timestamps
- **Inverse Text** (`#FFFFFF`): Text on colored/dark surfaces

### Surface & Border
- **Page Background** (`#F8FAFC`): App background — cool off-white
- **Container Background** (`#FFFFFF`): Cards, panels, modals
- **Elevated Background** (`#FFFFFF`): Dropdowns, popovers, tooltips
- **Border** (`#E2E8F0`): Default borders, dividers
- **Border Strong** (`#CBD5E1`): Emphasized borders, active card outlines
- **Hover Background** (`#F1F5F9`): Row hover, item hover backgrounds
- **Muted Background** (`#F1F5F9`): Subtle section backgrounds, table headers

### Dark Mode
- **Dark Page** (`#0F172A`): Dark app background
- **Dark Container** (`#1E293B`): Dark cards, panels
- **Dark Elevated** (`#334155`): Dark dropdowns, popovers
- **Dark Border** (`#334155`): Dark borders
- **Dark Hover** (`#1E293B`): Dark row hover
- **Dark Text Primary** (`#F8FAFC`): Dark mode primary text
- **Dark Text Secondary** (`#94A3B8`): Dark mode secondary text

## 3. Typography Rules

### Font Family
- **Primary**: `Noto Sans SC`, fallbacks: `-apple-system, system-ui, 'Segoe UI', Roboto, 'PingFang SC', 'Microsoft YaHei', sans-serif`
- **Monospace (optional)**: `'JetBrains Mono', 'Fira Code', Consolas, monospace`

### Hierarchy

| Role | Size | Weight | Line Height | Usage |
|------|------|--------|-------------|-------|
| Page Title | 24px (1.5rem) | 700 | 1.3 | Page headings, dialog titles |
| Section Title | 20px (1.25rem) | 600 | 1.4 | Section headings, card titles |
| Subsection | 16px (1rem) | 600 | 1.5 | Subsection labels, form group titles |
| Body | 14px (0.875rem) | 400 | 1.6 | Standard body text, table cells, descriptions |
| Caption | 12px (0.75rem) | 400 | 1.5 | Timestamps, badges, helper text, metadata |

### Principles
- **Chinese-first**: Noto Sans SC ensures excellent CJK rendering
- **Readable weights**: 400 for body, 600-700 for headings — always substantial, never thin
- **Generous line-height**: 1.5-1.6 for body text ensures comfortable reading
- **Moderate scale**: 12-24px range creates a compact, professional information hierarchy

## 4. Component Stylings

### Buttons
- **Primary**: Blue (#2563EB) background, white text, 10px radius, soft shadow
- **Secondary**: White background, slate border (#CBD5E1), dark text, 10px radius
- **Ghost**: Transparent background, primary blue text, no border
- **Danger**: Red (#DC2626) background, white text, for destructive actions
- **All buttons**: Min height 36px, 40px preferred; smooth hover transition 200ms

### Cards & Containers
- White background, 12px radius, soft shadow: `0 1px 3px rgba(0,0,0,0.06), 0 1px 2px rgba(0,0,0,0.04)`
- Hover: Slightly elevated shadow: `0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.05)`
- No thick borders — shadows and subtle background differences create depth

### Inputs
- White background, 1px solid #CBD5E1 border, 10px radius
- Focus: Blue ring (2px solid #2563EB) with outer glow
- Error: Red border + error message below field
- Height: 40px standard, 32px small

### Tables
- Header: #F1F5F9 background, #475569 text, 14px weight 600
- Row hover: #F1F5F9 background
- Cell padding: 16px vertical, 12px horizontal
- Border: Bottom-only using #E2E8F0

### Navigation / Sidebar
- Background: White (#FFFFFF) with right border #E2E8F0
- Active item: #EFF6FF background, #2563EB text, left accent bar (3px)
- Hover item: #F1F5F9 background
- Item height: 40px, 12px radius
- Icons: 20px, inline with label text

### Tags / Badges
- Small radius (6px), medium padding (4px 8px)
- Color-coded backgrounds: blue tint, green tint, amber tint, red tint
- Text matches semantic color (darker shade than background)

### Modals / Dialogs
- 16px radius, generous padding (24px)
- Soft elevated shadow: `0 8px 30px rgba(0,0,0,0.12)`
- Header with title, footer with action buttons

## 5. Layout Principles

### Spacing System
- Base unit: 4px
- Scale: 4px, 8px, 12px, 16px, 20px, 24px, 32px, 40px, 48px, 64px
- Content padding: 24px standard, 16px compact

### Layout
- Fixed sidebar: 240px wide, collapsible to 72px
- Sticky header: 56px
- Content area: Fluid width with max comfortable reading width
- Standard CRUD table/list views for data management

### Border Radius Scale
- Small (6px): Tags, badges, small elements
- Standard (10px): Buttons, inputs, cards
- Large (12px): Panels, modals, large containers
- Full (50%): Circular avatars, icon buttons

## 6. Depth & Elevation

| Level | Shadow | Use |
|-------|--------|-----|
| Level 0 (Flat) | None | Page background, sidebar |
| Level 1 (Subtle) | `0 1px 2px rgba(0,0,0,0.05)` | Cards, form sections |
| Level 2 (Default) | `0 1px 3px rgba(0,0,0,0.06), 0 1px 2px rgba(0,0,0,0.04)` | Elevated cards, dropdowns |
| Level 3 (Elevated) | `0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.05)` | Hover states, active cards |
| Level 4 (Modal) | `0 8px 30px rgba(0,0,0,0.12)` | Modals, overlays |

## 7. Interactive States

### Hover
- Background color shift: `#F1F5F9` for neutral, semantic tint for colored elements
- Transition: 200ms ease
- Cursor: `pointer` on clickable elements

### Focus
- 2px solid ring using `#2563EB`
- 2px offset for visibility
- Always visible for keyboard navigation

### Active / Pressed
- Slightly darker shade of the element's color
- Brief scale or shadow change for tactile feedback

### Disabled
- Reduced opacity (0.5)
- No hover effects
- Cursor: `not-allowed`

### Loading
- Spinner or skeleton placeholder
- Disabled interactions during async operations

## 8. Do's and Don'ts

### Do
- Use soft shadows for depth — the Soft UI Evolution identity
- Apply Primary Blue (#2563EB) only for primary actions and active states
- Use Noto Sans SC for consistent Chinese rendering
- Apply 10-12px radius — friendly but professional
- Use semantic color tints for status backgrounds
- Keep tables clean with subtle header differentiation
- Ensure 4.5:1 contrast ratio for all text

### Don't
- Don't use heavy or dramatic shadows — keep depth subtle
- Don't use pure black (#000000) for text — use #0F172A instead
- Don't use pill-shaped buttons — 10px radius is rounded but not pill
- Don't mix warm and cool neutrals — stay in the slate family
- Don't use emojis as icons — use SVG icons (Lucide/Heroicons)
- Don't use decorative-only animations — every animation must serve a purpose
- Don't use colors as the sole means of conveying information

## 9. Responsive Behavior

### Breakpoints
| Name | Width | Key Changes |
|------|-------|-------------|
| Mobile | <576px | Sidebar collapsed, single column |
| Tablet | 576-768px | Sidebar collapsed, 2-column grid |
| Desktop Small | 768-1024px | Sidebar expanded, responsive grid |
| Desktop | 1024-1440px | Full layout |
| Large Desktop | >1440px | Maximum content width |

### Collapsing Strategy
- Sidebar: 240px → 72px (icon only) on mobile/tablet
- Tables: Horizontal scroll on narrow screens
- Forms: Single column on mobile, multi-column on desktop
- Cards: Full-width stack → grid layout

## 10. ERP Platform Adaptations

### Layout
- Fixed sidebar navigation (240px wide, collapsible to 72px)
- Sticky header (56px) with search, notifications, user menu
- Content area uses CSS Grid for responsive multi-column dashboards
- Standard CRUD table/list views replace masonry grid for data management

### Color Adaptations
- Primary Blue (#2563EB) for primary actions (Save, Create, Submit)
- Success Green (#059669) for positive states (Approved, Completed, Paid)
- Warning Amber (#D97706) for pending states (Pending Review, Awaiting)
- Error Red (#DC2626) for destructive/error states (Rejected, Failed, Overdue)
- Info Blue (#0284C7) for informational elements (Tips, Help, Documentation)

### Component Adaptations
- **Tables**: Slate header bg (#F1F5F9), generous cell padding, subtle hover (#F1F5F9)
- **Forms**: 10px radius inputs, slate borders (#CBD5E1), generous spacing
- **Cards**: 12px radius, soft shadow, white background
- **Sidebar**: Blue active states (#EFF6FF bg), slate hover, 12px radius items
- **Tags/Badges**: 6px radius, semantic color tints (blue/green/amber/red)
- **Modals**: 16px radius, elevated shadow, generous padding

### Dark Mode
- Background: #0F172A (deep navy)
- Container: #1E293B (dark slate)
- Elevated: #334155 (medium slate)
- Border: #334155
- Active accent: #3B82F6 (lighter blue for dark backgrounds)
- Text: #F8FAFC primary, #94A3B8 secondary

## 11. Agent Prompt Guide

### Quick Color Reference
- Brand: Primary Blue (#2563EB)
- Background: Cool Off-White (#F8FAFC)
- Text: Deep Navy (#0F172A)
- Secondary text: Slate (#475569)
- Border: Light Slate (#E2E8F0)
- Success: Green (#059669)
- Warning: Amber (#D97706)
- Error: Red (#DC2626)
- Focus: Blue (#2563EB)

### Example Component Prompts
- "Create a card: white background, 12px radius, soft shadow (0 1px 3px rgba(0,0,0,0.06)). Title in 16px weight 600 #0F172A. Body in 14px #475569."
- "Design a primary button: #2563EB background, white text, 10px radius, 8px 16px padding. Hover: #1D4ED8. Focus: 2px solid #2563EB ring."
- "Build a table: header #F1F5F9 background, #475569 text 14px weight 600. Row hover #F1F5F9. Cell padding 16px 12px. Border bottom #E2E8F0."
- "Create a sidebar: white background, right border #E2E8F0. Active item: #EFF6FF background, #2563EB text, 3px left accent bar. Hover: #F1F5F9."
- "Design a modal: 16px radius, shadow 0 8px 30px rgba(0,0,0,0.12). Title 20px weight 600. Footer with primary blue CTA."

### Iteration Guide
1. Soft shadows everywhere — subtle depth is the identity
2. Primary Blue for CTAs and active states — trustworthy, not overwhelming
3. 10px radius on buttons/inputs, 12px on cards — friendly but professional
4. Noto Sans SC is the primary font — Chinese-first, readable at all sizes
5. Slate neutrals — never pure black or pure gray, always with blue undertone
6. Semantic tints for status — green/amber/red backgrounds with matching text