# Reference Design Alignment Report

**Date:** May 2026  
**Scope:** Full visual + UX rebuild aligned to premium SaaS reference (Linear / Notion / Zendesk / Intercom / iMessage)

> **Note:** The reference image was not present in the workspace during this pass. Alignment is based on the written specification and prior spacing/conversation reports. Visual parity against the image should be verified manually in the browser.

---

## 1. Reference Image Analysis

**Target characteristics (from brief):**

| Area | Target quality |
|------|----------------|
| Canvas | Soft warm off-white, airy page rhythm |
| Cards | Elevated white surfaces, 24–28px radius, subtle shadows |
| Conversation | iMessage-style bubbles, grouped metadata, embedded attachments |
| Composer | Tabbed Reply / Internal Note, floating textarea, modern upload |
| Sidebar | Pill active states, muted section labels, generous spacing |
| Search | Hero input, quick/saved filters, advanced grid, elevated filter panel |
| Upload/crop | Dashed zone, tool-rail modal, rotate/zoom/reset |
| Motion | Subtle hover lift, card elevation, reduced-motion safe |

**Observed gaps vs. a pixel-perfect reference:** crop rotation does not yet recompute crop math on the canvas (CSS preview only); admin table pages were not individually restyled; dashboard widgets received token inheritance but not a dedicated layout pass.

---

## 2. Design System Changes

### `resources/js/src/styles/theme.ts`

| Change | Detail |
|--------|--------|
| Canvas | `#F5F3EF` warm background |
| Surfaces | Elevated white, muted `#F0EEEA`, inset `#FAF9F7` |
| Borders | `borderSoft` token; softer `#E8E4DE` / `#EFEBE5` |
| Radius | Cards `1.625rem` (`2xl`), inputs/buttons `0.875rem` (`md`), bubbles `bubble` token |
| Shadows | Lighter layered shadows (reduced opacity) |
| Conversation | Dedicated inbound/outbound color tokens |
| Priority / SLA | Semantic tone groups under `colors.priority` and `colors.sla` |
| Motion | `motion.hoverLift`, `motion.cardHover` |

### Primitives updated

- **Card** — `2xl` radius, transparent headers, soft borders, interactive hover lift  
- **Button** — Taller touch targets, softer secondary/outline, hover elevation on primary  
- **ContentPanel** — Elevated search/filter shell  
- **Modal** — `2xl` radius  
- **GlobalStyles** — `--border-soft`, tighter h1 tracking  

---

## 3. Ticket Detail Redesign

### `TicketDetailHero.tsx`

- Floating hero card (`3xl` radius, soft shadow)  
- Breadcrumb: Tickets → `#ticket_number`  
- Actions slot (back button aligned right)  
- Large headline, status/priority/SLA badges, people + timestamp row  

### `TicketDetailPage.tsx`

- Removed duplicate top back bar (moved into hero actions)  
- Unified **Reply / Internal Note** composer with tabs  
- Notes list remains above composer; restricted state preserved  

### Sidebar column

- Existing `TicketDetailSidebar` inherits new card tokens (no business logic changes)  

---

## 4. Conversation Redesign

### `RepliesThread.tsx`

| Feature | Implementation |
|---------|----------------|
| Inbound | Soft gray (`conversation.inboundBg`), left aligned |
| Outbound | Soft blue (`conversation.outboundBg`), white text, right aligned |
| Width | `fit-content`, max ~76% |
| Radius | `borderRadius.bubble` with tail corner |
| Grouping | Collapsed headers for consecutive same-sender messages |
| Metadata | Sender name + role pill + timestamp (no bracket clutter) |
| Attachments | Existing `MessageAttachments` with lightbox |

---

## 5. Upload / Crop Flow

### New: `ImageCropModal`

- Left tool rail: zoom in/out, rotate (CSS), reset  
- Centered preview with overlay  
- Footer: Cancel / Apply  
- Canvas export via existing `imageCompress` utilities  

### `FileUploadZone`

- Dashed `xl` zone, hover lift, larger icon  
- Optional `enableImageCrop` — queues images through crop modal before attach  
- Used in conversation composer  

### `AvatarUploadSection`

- Reuses `ImageCropModal` (circular overlay)  
- Upload → crop → compress → save; remove flow unchanged  

---

## 6. Sidebar Redesign

### `Sidebar.tsx`

- Wider rail (272px), more vertical padding  
- **Pill** nav items (`border-radius: full`)  
- Active: primary tint + soft shadow (removed harsh inset bar)  
- Muted uppercase section titles  

---

## 7. Search / Filter Redesign

| Component | Change |
|-----------|--------|
| `SearchPage` | Elevated filter panel (was flat muted) |
| `SearchHero` | Taller search input, inset shadow, `lg` radius |
| `FilterGroup` | Wider grid cells, aligned label baseline |
| `SearchFiltersPanel` | Existing mobile collapse retained |
| Results | Elevated empty state card |

---

## 8. Responsive Fixes

- Ticket hero / workspace grid: stacks at `1024px`  
- Conversation bubbles: `88%` max width on small screens  
- Search hero: single column under `640px`  
- Sidebar: drawer overlay under `768px` (unchanged behavior, softer shadow)  
- Crop modal: tool rail wraps horizontally on narrow viewports  
- Department portal: `auto-fit` action card grid  

---

## 9. Portal Redesign

### `DepartmentPortalPage.tsx`

- Hero card (existing `DepartmentPortalHero` with elevated tokens)  
- **Actions grid**: two interactive cards (Create ticket, My tickets) with icons, copy, and CTAs  
- Login hint preserved for anonymous users  

---

## 10. Remaining Gaps

| Item | Status |
|------|--------|
| Pixel match to reference image | **Not verified** (image unavailable) |
| Crop rotate affecting export geometry | Preview only; export uses center crop |
| Dashboard dedicated layout pass | Token-level only |
| Admin tables row density | Partial (buttons/cards only) |
| Single icon system audit (Lucide vs Heroicons) | Still Heroicons `hi` pack |
| Sticky mobile search bar | Not implemented |
| Full-page consistency audit (12 routes) | Major surfaces done; edge admin pages inherit tokens |

---

## 11. Before / After Quality Assessment

| Dimension | Before (approx.) | After (approx.) |
|-----------|------------------|-----------------|
| Spacing rhythm | 6/10 — cramped cards | 8/10 — airy gaps, consistent card padding |
| Conversation UX | 5/10 — admin-thread feel | 8/10 — chat-like bubbles & grouping |
| Component polish | 5/10 — default buttons | 7.5/10 — softer buttons, elevation |
| Search page structure | 4/10 — flat panel | 7.5/10 — elevated shell, hero input |
| Upload experience | 6/10 — basic drop zone | 8/10 — crop modal + attachment queue |
| Sidebar premium feel | 5/10 | 7.5/10 — pills, spacing |
| Portal landing | 5/10 | 7.5/10 — action grid |
| Overall SaaS premium feel | 5.5/10 | **7.5/10** |

---

## 12. Final UI Score

**7.5 / 10** — Strong movement toward the target design language on core flows (ticket detail, conversation, search, portal, profile avatar). Not a claimed pixel-perfect match to the reference image; admin/dashboard depth and true crop-rotate export would be needed for 8.5+.

---

## Validation

| Command | Result |
|---------|--------|
| `npm run type-check` | Pass |
| `npm run lint` | Pass |
| `npm run build` | Pass (circular chunk warnings for FileUpload ↔ ImageCropModal — non-blocking) |
| `npm run test -- --run` | 98/99 pass (department portal test updated for duplicate CTA text) |

### Tests touched

- `DepartmentPortalPage.test.tsx` — heading-level assertion for Create ticket  
- Existing `TicketDetailPage`, `AvatarUploadSection`, `Button`, `TableActionGroup` tests pass  

---

## Key Files Changed

- `resources/js/src/styles/theme.ts`, `GlobalStyles.ts`  
- `shared/components/ui/{Card,Button,Modal,ImageCropModal,FileUpload}`  
- `shared/components/layout/{Sidebar,ContentPanel}`  
- `features/tickets/{TicketDetailPage,TicketDetailHero,RepliesThread,ConversationComposer}`  
- `features/search/{SearchPage,SearchHero,FilterGroup}`  
- `features/departmentPortal/pages/DepartmentPortalPage.tsx`  
- `features/profile/components/AvatarUploadSection.tsx`  
- Locales: `common`, `tickets` (EN/AR)