# FleetTruck360 — Design Guide

> Design phase (visual mockup) · v3 · 2026-11-14
> Companion to [SOFTWARE_DETAILS.md](SOFTWARE_DETAILS.md). Mockups live in [design/](design/).

---

## 1. How to view the mockups

1. Start XAMPP (Apache).
2. Open **http://localhost/keep-trucking/doc/design/index.html**
   (or open `doc/design/index.html` straight from disk in Chrome/Edge/Firefox).
3. You need an internet connection, because fonts, Bootstrap, icons and Chart.js load from a CDN.
4. Top bar controls:
   - The **coloured dots** switch between the 8 themes.
   - **Dark** turns on dark mode.
   - The **sidebar** button switches the sidebar between dark, light and brand.
   - Your choices are remembered on every page.
5. Each page has **screen tabs** under the top bar. You can bookmark a single screen, e.g. `company.html#trips`.
6. Amber **Design note** boxes explain the reasons behind a screen. They are not part of the real app.

| Page | File | Contents |
|---|---|---|
| Overview | `design/index.html` | Entry point and links |
| Design System | `design/design-system.html` | Tokens, themes, status colours, charts, typography, every component |
| Public & Signup | `design/public.html` | Landing + pricing, signup (14-day trial), login, forgot/reset password, verify email, setup wizard |
| Mobile App | `design/mobile.html` | Phone screens: owner/staff, trips, interactive 6-step trip sheet, driver, billing, support & notifications |
| Company Web | `design/company.html` | Desktop company app: dashboard, trips, trip form, paper print view, settlements, fleet, employees, roles, reports, billing, profile, announcements, support |
| Super Admin | `design/super-admin.html` | Platform dashboard, companies, company account, plans (standard/custom), payment verification, bank accounts, tickets, help center, announcements, jurisdictions, settings |

Shared code: `design/assets/tms.css` (design tokens and components) and `design/assets/tms.js` (theme switcher, screen tabs, charts, demo interactions).

---

## 2. Design principles

1. **Mobile first.**
   - Most users are on phones. Every screen is designed at 375px wide first, then widened for desktop.
   - Tap targets are at least 48px, and the main action button is pinned to the bottom of the screen.
2. **Looks and works like an app.**
   - Installable PWA: home-screen icon, full screen, splash screen.
   - Bottom tab bar with a raised amber **＋** button, frosted header, bottom sheets.
3. **One task per screen.**
   - On phones the trip sheet is a 6-step wizard. On desktop it's one page laid out like the paper form.
4. **Live feedback.**
   - Totals, MPG and cost per mile update as the user types.
   - Warnings appear inline in amber.
   - Drafts save automatically, so nothing is lost on a weak signal.
5. **Always findable.**
   - Every list has filters and sortable columns.
   - Active filters are highlighted so nobody misses them (see §6).
6. **Colour has meaning.**
   - Each status has one colour everywhere: badge, card edge and chart.
7. **Help is always close.**
   - Setup checklist, page tours, ⓘ field hints, helpful empty pages, the floating Help button and support tickets.

---

## 3. Design tokens

All colours are CSS variables, so the theme and dark mode can switch without changing any page code. In the real React app they live in `frontend/src/styles/` with the same names (the conventions file's `--sms-*` names become `--tms-*`).

### 3.1 Default theme: Fleet Blue (`data-theme="ocean"`)

| Token | Light | Dark | Use |
|---|---|---|---|
| `--tms-primary` | `#2563EB` | (theme colour) | Buttons, links, active items |
| `--tms-primary-dark` | `#1E40AF` | | Hover/pressed |
| `--tms-gradient` | `135° #1E3A8A → #2563EB → #06B6D4` | | Page header, login, main KPI card, upgrade buttons |
| `--tms-accent` | `#F59E0B` | | "Create" actions only (＋ New Trip Sheet, the ＋ button), count badges |
| `--tms-surface` | `#FFFFFF` | `#111A2E` | Cards |
| `--tms-surface-2` | `#F4F7FC` | `#0B1220` | Page background |
| `--tms-surface-3` | `#EEF2F9` | `#17223A` | Table headers, input groups, meters |
| `--tms-border` | `#E5E9F2` | `#24324D` | Borders |
| `--tms-text` | `#0F172A` | `#E2E8F0` | Text |
| `--tms-muted` | `#64748B` | `#94A3B8` | Labels and secondary text |

### 3.2 Themes

The theme names come from the conventions file:

| Theme | Primary | Gradient | Note |
|---|---|---|---|
| **ocean** (Fleet Blue) | `#2563EB` | `#1E3A8A → #2563EB → #06B6D4` | **Default for companies** |
| indigo | `#4F46E5` | `#312E81 → #4F46E5 → #818CF8` | |
| emerald | `#059669` | `#064E3B → #059669 → #34D399` | |
| sunset | `#EA580C` | `#7C2D12 → #EA580C → #F59E0B` | Accent switches to sky `#0EA5E9` |
| **royal** | `#7C3AED` | `#4F46E5 → #7C3AED → #DB2777` | **Locked for the Super Admin area** |
| rose | `#E11D48` | `#881337 → #E11D48 → #FB7185` | |
| teal | `#0D9488` | `#134E4A → #0D9488 → #22D3EE` | |
| slate | `#334155` | `#0F172A → #334155 → #64748B` | |

How themes are set:
- HTML attributes: `<html data-theme="…" data-bs-theme="light|dark" data-sidebar="dark|light|brand">`.
- The company sets the default (`appearance.*` settings).
- Each user can override it (`PUT /auth/preferences`).

### 3.3 Status colours

Every status uses the same colour everywhere:

| Status | Colour | Used for |
|---|---|---|
| Draft | `#64748B` | Trip being filled in |
| Submitted | `#3B82F6` | Signed by the driver, waiting for approval |
| Approved | `#10B981` | Approved and locked |
| Rejected | `#EF4444` | Sent back with a reason |
| Settled | `#8B5CF6` | Paid in a driver settlement |
| Warning | `#F59E0B` | Mileage mismatch, a document expiring, a limit nearly reached |
| Trial | `#06B6D4` | Company is on its trial |

### 3.4 Chart palette

- Series colours in order: `primary, #10B981, #F59E0B, #8B5CF6, #EF4444, #06B6D4, #EC4899, #84CC16`.
- Charts read their colours from the theme with `themeColors()`, so they update when the theme or dark mode changes.
- Chart styles:
  - Area/line charts: no point markers and a soft 12–15% fill.
  - Donut charts: 68% cutout with a border in the card colour.

### 3.5 Typography

| Role | Font | Size/weight |
|---|---|---|
| Display / KPI value | Plus Jakarta Sans | 26–32 / 800 |
| Page title | Plus Jakarta Sans | 22 / 700 |
| Card title | Plus Jakarta Sans | 15 / 700 |
| Body | Inter | 14 / 400 |
| Label | Inter | 12.5 / 600, muted |
| Overline | Inter | 11 / 600, uppercase, letter-spacing .08em |

All numbers use fixed-width digits (`font-variant-numeric: tabular-nums`) so columns line up.

### 3.6 Shape and spacing

- **Corner radius:** cards 16px · inputs and buttons 12px · phone cards 18px · bottom sheets 26px · pills 999px.
- **Shadows:** `--tms-shadow-sm` for cards at rest, `--tms-shadow` for hover and dropdowns, `--tms-shadow-lg` for modals and sheets.
- **Spacing:** 4px grid (4 · 8 · 12 · 16 · 24 · 32).

---

## 4. Components

These are the mockup classes and the React components that will replace them:

| Component | Mockup class | React (frontend/src/components) |
|---|---|---|
| App shell, sidebar, topbar | `.app-shell .sidebar .side-link .topbar` | `Layout`, `Sidebar` (dynamic menus), `Topbar` |
| Page header (gradient) | `.page-hero` + `.page-body` | `PageHeader variant="hero"` |
| Card | `.tms-card .tms-card-header .tms-card-body` | `Card` |
| KPI card | `.kpi-card` (`.kpi-hero`, `.kpi-spark`) | `StatCard` |
| Status badge | `.status-badge.status-*` | `StatusBadge` |
| Buttons | `.btn-primary .btn-accent .btn-gradient .btn-soft .btn-ghost` | Bootstrap + theme tokens |
| Filter bar | `.filter-bar .filter-select(.is-set) .btn-filter(.active)` | `FilterBar` (inside `ResourcePage`) |
| Active filter chips | `.filter-chips .chip .clear-all .result-count` | `ActiveFilters` |
| Table with sorting | `.tms-table th.sortable/.sort-asc/.sort-desc/.filtered` | `DataTable` |
| Pagination | `.pager` | `Pagination` |
| Usage meter | `.meter(.warn)` | `UsageMeter` |
| Status pipeline | `.pipeline .pipe-step` | `StatusPipeline` |
| State tile map | `.tile-map .tile.l1–l4` | `StateTileMap` |
| Plan card | `.plan-card(.popular/.custom) .plan-limits .feature-list` | `PlanCard` |
| Banners | `.banner-trial/-warn/-urgent/-info` | `Banner`, `AnnouncementBanner` |
| Chat thread | `.bubble.me/.them/.note` | `TicketThread` |
| Signature pad | `.sig-pad` | `SignaturePad` (react-signature-canvas) |
| Trip state grid | `.state-grid .state-row(.used)` | `StateMileageGrid` |
| Paper print sheet | `.paper-sheet .paper-head` | `TripSheetPrint` (`.print-sheet` + `window.print()`) |
| Empty state | `.empty-state` | `EmptyState` |
| Tour popover | `.tour-pop .tour-highlight` | driver.js tour |
| Setup checklist | `.checklist-item .progress-ring` | `OnboardingChecklist` |
| Phone tab bar / ＋ button | `.m-tabbar .m-tab .m-fab` | `MobileTabBar` |
| Bottom sheet | `.bottom-sheet .sheet-backdrop` | `BottomSheet` |
| Wizard stepper | `.m-stepper .m-steps` | `Wizard` |

### Button rules

- Only **one Primary** button per screen.
- **Accent (amber)** is only for create actions.
- **Gradient** is only for marketing and upgrade/CTA buttons.
- **Success-soft / Danger-soft** are for Approve / Reject.

---

## 5. Navigation

| Area | Desktop | Phone |
|---|---|---|
| Company (owner/staff) | Sidebar: Dashboard · Trips · Settlements · Fleet · Employees & Drivers · Shippers & Consignees · Reports · Announcements · Support · Help Center · Billing & Plan · Settings | Bottom tabs: **Home · Trips · ＋ · Fleet · More** |
| Driver | Same layout, but the menu depends on permissions | Bottom tabs: **Home · My Trips · ＋ · My Pay · More** |
| Super Admin (Royal theme) | Sidebar: Dashboard · Companies · Plans · Invoices · Payments to Verify · Bank Accounts · Support Tickets · Help Center · Announcements · Jurisdictions · Platform Users · Audit Logs · Settings | Bottom tabs: Home · Companies · Payments · Tickets · More |

Menus come from the database (`menus` table), so admins can rename, reorder or hide them in the Menu Manager.

**Locked modules** (not included in the company's plan) are not hidden. They show a 🔒 badge and open an "Unlock with <plan>" upgrade page.

---

## 6. Filters and sorting (applies to every list)

### 6.1 Filter layout

- **Desktop:** search box, 3–4 quick filters, then a **Filters** button that opens a side panel with all the other filters.
- **Phone:** the filter icon opens a full-height bottom sheet. Its **Apply · N results** button shows the live result count.
- **Date presets:** Today · Yesterday · This Week · Last Week · This Month · Last Month · This Quarter · This Year · Custom.

### 6.2 How an active filter is highlighted

When any filter is on, all four of these change:
1. The Filters button turns solid primary and shows an amber count badge.
2. A chip row appears for the active filters (tinted background, dashed border), with ✕ on each chip and a **Clear all** link.
3. The result count is highlighted: *Showing **12** of 340*.
4. An amber dot appears on the header of each filtered column.

Quick filter dropdowns that are set also turn tinted (`.filter-select.is-set`).

### 6.3 Saved filters and exports

- Filters are stored in the URL query string. They survive a refresh and can be shared as a link.
- Users can **Save view** (stored in `saved_filters`).
- Export always exports exactly the filtered result.

### 6.4 Sorting

- Every column can be sorted. Clicking a header cycles **▲ → ▼ → off**.
- **Shift-click** sorts by several columns.
- The sorted column header is tinted.
- Sorting runs on the server: `?sort=-trip_date,driver_name`.
- On phones, a **Sort** bottom sheet replaces column headers.

The per-list filter matrix is in SOFTWARE_DETAILS.md §11.

---

## 7. Mobile patterns

- **Status bar spacing:** a 46px top area keeps content clear of the phone's status bar.
- **Headers:** large title + 38px icon buttons. Inner pages use a back arrow.
- **Hero screens** (Home, Login, Billing): gradient header, with content cards overlapping it by 44px.
- **Lists are cards, not tables.** Each card has a coloured left edge for its status, the route as `City → City` with a truck icon, and a meta row (miles · gallons · $).
- **Wizard:** step bar + "Step N of 6 · name". Back/Next are pinned to the bottom, and the last step shows **Submit**. The draft auto-saves, with a "Saved ✓" indicator.
- **Inputs:**
  - Amounts and miles use `inputmode="decimal"` so the number keyboard opens.
  - Selects open bottom sheets with search.
  - A camera icon on each expense row attaches a receipt photo, compressed on the phone to about 200 KB.
- **States step:** only the states actually driven are shown as cards. **＋ Add State** opens a bottom sheet with the states in paper order, plus the extra US states, Canadian provinces, and "Add other jurisdiction".
- **Pull to refresh** on lists. Grey placeholder shapes show while loading, instead of spinners.
- **Offline:** the app shell is cached. Trip drafts are stored on the phone and synced when the connection returns.

---

## 8. Accessibility basics

- Text contrast meets WCAG AA. Status is never shown by colour alone: badges always include the status word.
- All icon-only buttons have `aria-label`/`title` text, and focus is shown as a 4px primary ring.
- Tap targets are at least 44–48px, and forms show error text under the field (`.invalid-feedback`).
- Animations are respected: transitions are switched off when the phone or computer asks for reduced motion (`prefers-reduced-motion`).

---

## 9. Design → build checklist

- [ ] Client approves the look (theme, mobile screens, trip sheet flow).
- [ ] Copy tokens from `design/assets/tms.css` into `frontend/src/styles/theme.css`.
- [ ] Build the shared components in §4 before the module pages.
- [ ] Build each module page from `ResourcePage` with the filter/sort standard in §6.
- [ ] Make sure the printed trip sheet matches the paper form (screenshot in the project root).
