# UI layout & UX — product shell contract

This document describes the **product UI** shell and screen layouts  
(`server/web`, served at http://localhost:4000).

**Keep this shell and these screen layouts.**  
Do **not** invent a different navbar, control panel, card style, or form chrome.

Reference implementation:

| Layer | Path |
|-------|------|
| Shell HTML | `server/web/index.html` (`#app-shell`, `#login-screen`) |
| Styles | `server/web/css/styles.css` (brand tokens `--o-purple*` → Zettai blue `#00579a`) |
| Shell / routing / control panel / facet search | `server/web/js/app.js` |
| Apps & menus | `server/web/js/auth.js` → `apps()`, `navItems()` |
| Employees | `server/web/js/employees.js` |
| Projects | `server/web/js/projects.js` |
| Tasks / Bugs / … | `server/web/js/tasks.js`, `server/web/js/bugs.js`, … |

> Open http://localhost:4000 — API-backed UI under `server/web`.

---

## 1. Visual system

| Token / rule | Value |
|--------------|--------|
| Brand primary | `#00579a` (`--o-purple`); darker `#004578`; light `#e6f1f8` |
| Page background | `#f0f1f2` |
| Font | Roboto 14px; mono: Roboto Mono |
| Icons | Bootstrap Icons |
| CSS framework | Bootstrap 5.3.x (tables, modals, badges, forms) |
| Primary buttons | Brand blue (`btn-primary` overridden to `--o-purple`) |
| “New” button | `.btn-o-new` — brand blue, left of control-panel title |
| Dates (display) | **DD-MM-YYYY** |
| Hours (display) | **HH:MM** |

---

## 2. App shell (every logged-in screen)

Sticky brand-blue top bar (`.o-navbar`, ~46px):

**Left**

1. **Apps grid** button (`#btn-apps`, `bi-grid-3x3-gap-fill`) → dropdown `.o-apps-menu`
2. Current **app name** (`.o-app-name`) e.g. `Project`, `Employees`, `Dashboards`
3. **Per-app top menu** (`#top-nav` / `.o-top-nav`) — horizontal links for that app only

**Right**

1. **Notifications** bell + unread badge
2. **User block**: avatar + name + role; role label only
3. **Logout** icon

**Below navbar**

- Main content `#main-content` inside `.o-content`
- Optional breadcrumb
- Global **floating timer bar** (`#timer-bar`)
- Shared Bootstrap **modal** (`#appModal`) + toast (`#toast`)

### Apps grid (must exist)

| App | Home route | Top menus |
|-----|------------|-----------|
| Dashboards | `dashboard` | Dashboard, My Work |
| Project | `projects` | Projects, Tasks, Bugs, Activities, Reporting, Releases |
| Timesheets | `timesheets` | Timesheets |
| Time Off | `leave` | My Time, Overview, Management (**SA only**) |
| Employees | `employees` | Employees (**SA only**) |

Switching app changes the app name + top menu set. Routes stay hash-style (`#/projects`); **menu structure must stay the same**.

---

## 3. Control panel (secondary toolbar)

Almost every list/detail screen starts with `.o-control-panel` (sticky under navbar):

| Zone | Contents |
|------|----------|
| **Left** | Purple **New** (`.btn-o-new`) when allowed + bold **title** (optional gear ⚙) |
| **Center** | Search (`.o-search`) **or** facet search (`.o-facet-search`) |
| **Right** | Counts, view toggles (kanban/list), extra actions |

This is **not** a page title inside a white card with a blue “New employee” button on the right. The demo pattern is: **New on the left**, title beside it, search centered, tools on the right.

---

## 4. Employees — `#/employees`

**Who:** Super Admin only (app + menu gated).

**Layout**

1. Control panel: **New** | title `Employees` | center search “Search employees…”
2. Optional warning alert if tasks assigned to inactive employees
3. White `.card-panel` table (hover rows)

**Columns**

`ID` · `Name` (avatar + name) · `Email` · `Phone` · `Department` · `Designation` · `Role` · `Status` (badge) · actions

**Actions per row:** `Edit` · `Deactivate` / `Activate`

**Create / Edit:** shared Bootstrap **modal** (not a custom centered card):

- Full name, Email, Phone, Department, Designation, System role, Status (Active/Inactive)
- Footer: Cancel + Save

---

## 5. Projects list — `#/projects`

**Layout**

1. Control panel: **New** | title `Projects` | center search | right: `1-N / N` + **view toggles** (kanban icon = cards, list icon = table)
2. Body `.o-page-body`

### Cards view — `.project-grid` / `.project-card`

Default list screen opens on **status kanban** (Active / On Hold / Completed). Cards and list stay available from the view toggle. Facet search (Filters / Group By / Favorites) filters by text, status, project admin, and “My projects”.

Odoo-style kanban cards (white, light border, **no** thick colored top stripe as the main motif):

| Element | Behaviour |
|---------|-----------|
| ★ star | Favorite toggle (visual) |
| Title | Project name |
| ⚙ gear | Opens **project settings/detail** (`#/projects?project=…`); does **not** open tasks |
| Client line | Tags joined · or code, uppercase + people icon |
| Meta | `N Tasks`, clock + actual hours, open bugs, date range `DD-MM-YYYY → DD-MM-YYYY` |
| Right | Admin avatar + green status dot when Active |
| Card click | Navigate to **Tasks filtered by project** (`#/tasks?project=…`) |

### List view

Table columns: Code, Name, Admin, Status, Tasks, Alloc / Actual, Open Bugs, actions (`Tasks`, `Settings`).

---

## 6. Project detail / settings — `#/projects?project=<id>`

**Not** a thin summary modal page. Full page:

1. Control panel: title = project name; right **Edit Project** (if `manage_project`)
2. Breadcrumb: `Projects / {name}`
3. Code (mono)
4. **Stat strip**: Progress %, Allocated h, Actual h, Open bugs
5. Two columns (`.detail-cols`):
   - **Main:** Description; Tasks by stage counts
   - **Side:** Members (avatar + name + role badge); Internal statuses (color dot + text + stage)
6. Button **View project tasks**

---

## 7. New / Edit Project

Full-page form (`.project-form-page`) — **not** a small floating modal. Breadcrumb + title on the left; **Discard** + **Create project** / **Save project** on the right.

**Two-column layout (`.project-form-layout`)**

| Column | Cards |
|--------|--------|
| Main | **Project details** (code, name, description, tags) · **Schedule and status** (dates, status, colour swatches) · **Delivery rules** (all Gate A/B/C + bug Yes/No toggles) |
| Side | **Team** — project admin select + member rows (checkbox, avatar, name/role, project-role select). Create-only note: default internal statuses cloned |

| Field | Notes |
|-------|--------|
| Project code | required |
| Name | required |
| Description | textarea |
| Tags | comma-separated → `tags[]` |
| Start date / Target end date | date |
| Status | Active / On Hold / Completed |
| Colour | swatches (default `#00579a`) |
| Delivery rules | Full gate policy toggles (assignee/hours, BA analysis, description+AC, req doc, ready status, required subtasks, development complete, unit-test evidence, typed evidence, dependencies, code review, QA passed/evidence, blocking bugs, acceptance, tester approval, bug retest evidence) |
| Project admin | select — Project Admin or Super Admin |
| **Members** | checkbox + avatar + per-row project role (`Project Admin`, `BA`, `Developer`, `Tester / QA`, `Member`) |

On create: clone default **internal statuses** (13 statuses across Inbox → Done).

---

## 8. Other screens (layout contracts — same shell)

| Screen | Control panel / body pattern |
|--------|------------------------------|
| Tasks | Facet search + kanban/list; list **multi-level Group By** (order = nest, e.g. Stage › Project › Client); stage columns; kanban card status dot opens coloured internal-status menu; click → detail with stage chevrons, inline edit, chatter |
| Bugs | Facet search + kanban/list; list **multi-level Group By** (e.g. Status › Project › Task); status columns; click → detail |
| Timesheets | Grouped tables; HH:MM editors |
| Time Off | Balance cards, calendar, management tabs (SA) |
| Dashboard / My Work / Reports | Role-based widgets + report filters + CSV |

Full behaviour: [README.md](../README.md) §6–§8.

---

## 9. Acceptance checklist (UI parity)

Production is **not** done for a module until:

- [ ] Purple Odoo navbar + apps grid + per-app menus match §2
- [ ] Screens use control panel layout (§3), not a reinvented toolbar
- [ ] Employees table matches §4 columns/actions/modal
- [ ] Projects cards/list match §5 (click → tasks; gear → settings)
- [ ] Project detail matches §6 (stats + two-column members/statuses)
- [ ] Project create/edit is a **two-column card form** with all fields + Team picker (§7)
- [ ] `server/web/css/styles.css` tokens/classes matched (Roboto, brand blue `#00579a`, cards)
- [ ] Product UI is `server/web` (not a separate alternate admin shell)

---

## 10. How to open the UI

```bash
npm run dev   # from repo root
# → http://localhost:4000
```