# BV-SIS UI/UX Guidelines
## Complete Design Language

**Document Version:** 1.0  
**Brand:** BIG VOICE TECHNOLOGIES

---

## 1. Design Philosophy

BV-SIS follows a **"Familiar Flow, Modern Feel"** philosophy:
- Preserve the client's existing layout patterns (split create/list, filter+table, selector+dynamic)
- Apply modern enterprise aesthetics: clean cards, generous whitespace, consistent typography
- Prioritize data density for admin users while maintaining readability
- Every screen must work on desktop, tablet, and mobile

---

## 2. Color System

### 2.1 Primary Palette (Light Mode)

| Token | Hex | Usage |
|-------|-----|-------|
| `--color-primary` | `#1B4F72` | Primary actions, sidebar active state, links |
| `--color-primary-hover` | `#154360` | Button hover, link hover |
| `--color-primary-light` | `#D4E6F1` | Selected row, active tab background |
| `--color-secondary` | `#2E86C1` | Secondary buttons, badges |
| `--color-accent` | `#F39C12` | Highlights, warnings, KPI accent |
| `--color-success` | `#27AE60` | Success states, cleared, approved |
| `--color-danger` | `#E74C3C` | Errors, delete, rejected, overdue |
| `--color-warning` | `#F1C40F` | Pending, caution |
| `--color-info` | `#3498DB` | Informational badges, tooltips |

### 2.2 Neutral Palette (Light Mode)

| Token | Hex | Usage |
|-------|-----|-------|
| `--color-bg` | `#F4F6F9` | Page background |
| `--color-surface` | `#FFFFFF` | Cards, panels, modals |
| `--color-border` | `#E2E8F0` | Borders, dividers |
| `--color-text-primary` | `#1A202C` | Headings, primary text |
| `--color-text-secondary` | `#718096` | Labels, helper text |
| `--color-text-muted` | `#A0AEC0` | Placeholders, disabled |

### 2.3 Dark Mode Palette

| Token | Hex | Usage |
|-------|-----|-------|
| `--color-bg-dark` | `#0F172A` | Page background |
| `--color-surface-dark` | `#1E293B` | Cards, panels |
| `--color-border-dark` | `#334155` | Borders |
| `--color-text-primary-dark` | `#F1F5F9` | Primary text |
| `--color-text-secondary-dark` | `#94A3B8` | Secondary text |
| `--color-primary-dark` | `#3B82F6` | Primary actions (adjusted for contrast) |

### 2.4 Status Colors

| Status | Color | Usage |
|--------|-------|-------|
| Active / Normal / Registered | Green `#27AE60` | Student course status, enrollment |
| Pending / Not Registered | Amber `#F39C12` | Awaiting action |
| Exempted | Blue `#3498DB` | Course status |
| Repeat / Deferred | Orange `#E67E22` | Course status |
| Withdraw / Suspended | Red `#E74C3C` | Negative status |
| Graduated / Cleared | Teal `#1ABC9C` | Completion states |

---

## 3. Typography

### 3.1 Font Stack
```css
--font-primary: 'Inter', 'Segoe UI', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', 'Consolas', monospace;
```

### 3.2 Type Scale

| Level | Size | Weight | Line Height | Usage |
|-------|------|--------|-------------|-------|
| H1 | 28px / 1.75rem | 700 | 1.2 | Page titles |
| H2 | 24px / 1.5rem | 600 | 1.3 | Section headers |
| H3 | 20px / 1.25rem | 600 | 1.4 | Card titles |
| H4 | 16px / 1rem | 600 | 1.5 | Subsection headers |
| Body | 14px / 0.875rem | 400 | 1.6 | Default text |
| Small | 12px / 0.75rem | 400 | 1.5 | Helper text, table meta |
| Label | 13px / 0.8125rem | 500 | 1.4 | Form labels |

### 3.3 Rules
- Sentence case for labels and buttons (not ALL CAPS except abbreviations)
- Tab names match BRD exactly: "Biodata", "Course Enrollment", "Register Student"
- Monospace font for student numbers, codes, session codes

---

## 4. Spacing System

Base unit: **4px**

| Token | Value | Usage |
|-------|-------|-------|
| `--space-1` | 4px | Tight gaps |
| `--space-2` | 8px | Icon gaps, inline spacing |
| `--space-3` | 12px | Form field gaps |
| `--space-4` | 16px | Card padding, section gaps |
| `--space-6` | 24px | Between cards |
| `--space-8` | 32px | Page section spacing |
| `--space-12` | 48px | Major section breaks |

---

## 5. Cards

### 5.1 Standard Card
```
Background: var(--color-surface)
Border: 1px solid var(--color-border)
Border-radius: 8px
Padding: 16px (space-4)
Box-shadow: 0 1px 3px rgba(0,0,0,0.06)
```

### 5.2 KPI Card
```
Same as standard + left border accent (4px, primary color)
Large number: H1 size, bold
Label: Small, secondary text
Trend indicator: ↑↓ with color
```

### 5.3 Card Types by Module
| Module | Card Style |
|--------|-----------|
| Institution Setup Dashboard | KPI cards with counts |
| Student Registration | Profile card with photo |
| Student Finance | Financial summary cards |
| Examination | Mark summary cards |

---

## 6. Buttons

### 6.1 Button Hierarchy

| Type | Style | Usage |
|------|-------|-------|
| Primary | Filled primary color, white text | Save, Submit, Approve |
| Secondary | Outlined primary, primary text | Cancel, Back |
| Danger | Filled red | Delete, Reject |
| Ghost | No border, text only | Close, minor actions |
| Icon | Circle, icon only | Edit (x), Delete (x) in tables |

### 6.2 Button Sizes
| Size | Height | Padding | Font |
|------|--------|---------|------|
| sm | 32px | 8px 12px | 12px |
| md (default) | 40px | 10px 16px | 14px |
| lg | 48px | 12px 24px | 16px |

### 6.3 BRD-Preserved Buttons
- **Update** — Primary, used on Computer Number, Update Student Id
- **Get Manager** — Secondary, Course Managers
- **Save** — Primary, prerequisites
- **Close** — Ghost, student detail tab

---

## 7. Icons

**Library:** Heroicons (outline for nav, solid for actions)

| Context | Icon |
|---------|------|
| Institution Setup | building-library |
| Course Management | book-open |
| Student Admission | document-text |
| Student Finance | currency-dollar |
| Student Registration | user-group |
| Examination | clipboard-document-check |
| BulkSMS | chat-bubble-left-right |
| System Maintenance | wrench-screwdriver |
| Student ID Cards | identification |
| Edit | pencil-square |
| Delete | trash |
| Export | arrow-down-tray |
| Print | printer |
| Approve | check-circle |
| Reject | x-circle |
| Search | magnifying-glass |

---

## 8. Forms

### 8.1 Layout Rules
- Required fields marked with red asterisk (*) — per BRD convention
- Labels above inputs (not inline/floating) for accessibility
- Two-column form layout on desktop; single column on mobile
- Split create/list pattern: form width 35%, list 65%

### 8.2 Input Types
| Field Type | Component |
|-----------|-----------|
| Text | Standard input with validation |
| Dropdown | Searchable select (choices.js / custom) |
| Date | Date picker (flatpickr) — replaces Year/Month/Day separate fields |
| Multi-select | Tag/chip multi-select (Programs assignment) |
| File upload | Drag-drop zone with preview |
| Rich text | TipTap editor (Template Letter) |
| Percentage | Number input with % suffix (Pass Mark) |

### 8.3 Validation
- Inline validation on blur
- Error message below field in red
- Success checkmark on valid required fields
- Form-level error summary at top

---

## 9. Tables

### 9.1 Standard Data Table
```
Header: bg gray-50, font-weight 600, sticky top
Rows: alternating white/gray-50, hover highlight
Actions column: right-aligned icon buttons
Pagination: bottom, showing "Retrieved X records in Y seconds"
Sortable columns: click header
```

### 9.2 BRD Table Patterns
- Delete action shown as "x" in legacy → modern: trash icon with confirmation modal
- Row numbers for search results (1, 2, 3...) preserved in student search
- Nested tables for Programme Structure (period headers spanning columns)

### 9.3 Responsive Tables
- Desktop: full table
- Tablet: horizontal scroll with sticky first column
- Mobile: card view (each row becomes a card)

---

## 10. Tabs

### 10.1 Student Detail Tabs (Preserved Order)
```
Biodata | Course Enrollment | Courses | Register Student | Program Structure | Close
```
- Horizontal tabs below student header
- Active tab: primary color underline
- Close tab: right-aligned, ghost style

### 10.2 General Tab Rules
- Max 7 tabs visible; overflow into "More" dropdown
- Tab state persisted in URL hash

---

## 11. Filters

### 11.1 Advanced Filter Panel
- Collapsible panel above search results
- Filter chips showing active filters
- "Clear All" button
- Saved filter presets (enterprise)

### 11.2 BRD Filters (Preserved)
| Screen | Filters |
|--------|---------|
| Sessions Setup | Qualification Path Name |
| Academic Intake | Path Name, Intake Session, Period Scheme |
| Student Registration | Student Number, NRC, Name |
| Student Status | Advanced search |

---

## 12. Animations

| Animation | Duration | Usage |
|-----------|----------|-------|
| Fade in | 200ms ease | Page transitions, modal open |
| Slide down | 250ms ease | Dropdown, accordion expand |
| Skeleton pulse | 1.5s infinite | Loading states |
| Toast slide-in | 300ms ease | Notifications |
| Button press | 100ms | Scale 0.98 on click |

**Rule:** Animations respect `prefers-reduced-motion`

---

## 13. Hover Effects

| Element | Hover Effect |
|---------|-------------|
| Table row | Background lighten + subtle shadow |
| Card (clickable) | Shadow increase + translateY(-1px) |
| Button | Darken background 10% |
| Sidebar item | Background primary-light |
| Link | Underline appear |

---

## 14. Responsive Rules

| Breakpoint | Width | Layout |
|------------|-------|--------|
| Mobile | <768px | Single column, bottom nav, card tables |
| Tablet | 768–1279px | Collapsible sidebar, 2-column forms |
| Desktop | ≥1280px | Full sidebar, split panels, 3-column dashboards |
| Wide | ≥1536px | Max content width 1440px, centered |

### 14.1 Split Panel Responsive
- Desktop: 35/65 split (BRD pattern)
- Tablet: 40/60 split
- Mobile: Stacked — form above list

---

## 15. Accessibility (WCAG 2.1 AA)

- Color contrast ratio ≥ 4.5:1 for text
- All form inputs have associated labels
- Keyboard navigation for all interactive elements
- Focus rings visible (2px primary outline)
- ARIA labels on icon-only buttons
- Screen reader announcements for dynamic content (search results count)
- Skip to main content link

---

## 16. Dark Mode

- Toggle in user menu (top right)
- Preference stored in localStorage + user profile
- All color tokens have dark variants
- Charts adapt colors for dark background
- Images/logos: use dark-mode variant if needed

---

## 17. Notifications & Toasts

| Type | Color | Icon | Duration |
|------|-------|------|----------|
| Success | Green | check-circle | 4s auto-dismiss |
| Error | Red | x-circle | Persistent until dismissed |
| Warning | Amber | exclamation-triangle | 6s |
| Info | Blue | information-circle | 4s |

Position: Top-right, stacked

---

## 18. Loading States

- **Page load:** Full-page skeleton with sidebar + content placeholders
- **Table load:** Skeleton rows (5 rows)
- **Form submit:** Button spinner + disabled state
- **Search:** Inline spinner in search field; results count updates

---

## 19. Empty States

Each module empty state includes:
- Illustration (simple SVG)
- Descriptive message
- Primary action button ("Add Campus", "Create Course", etc.)

---

## 20. Footer

```
Powered by BIG VOICE TECHNOLOGIES | © 2026 [Institution Name] | v1.0
```
- Fixed at bottom on short pages
- Sticky on long scroll pages

---

*End of UI/UX Guidelines*