# RetailOS — Phase 01: Complete UI Kit

**Status:** Draft for review · **Depends on:** Phase 00 (Architecture) sign-off
**Duration estimate:** সপ্তাহ ২–৩ (UI prototype scope)
**Goal:** Foundation layer — এখানে theme, spacing, ও component-এর মান ঠিক হবে যা বাকি ৭৮টা পেজে reuse হবে। এই ধাপ শেষে কোনো নতুন পেজে নতুন করে design decision নিতে হবে না, শুধু existing component বসাতে হবে।

**Stack:** Bootstrap 5 + Bootstrap Icons + Chart.js/ApexCharts + DataTables + Flatpickr + SweetAlert2 (per Tech Stack section) — modular HTML partials (`header.html`, `sidebar.html`, `footer.html`) যাতে পরে Laravel-এ blade partial-এ রূপান্তর সহজ হয়।

---

## 1. Deliverable Checklist (per roadmap chip list)

| # | Component | Description |
|---|---|---|
| 1 | Login | Email/phone + password, "remember me", validation states |
| 2 | Register | Shop owner self-signup — shop name, owner info, plan selection |
| 3 | Forgot / Reset Password | Email/OTP-based reset flow, expiring token |
| 4 | Verify OTP | 6-digit OTP input, resend timer, used for register + reset |
| 5 | Lock Screen | Session-timeout re-auth without full logout |
| 6 | Dashboard Shell | Base authenticated layout — sidebar + header + content area |
| 7 | Sidebar | Collapsible, role-aware menu (hides modules per Permission Matrix) |
| 8 | Header | Shop switcher (if multi-branch later), notifications, profile menu |
| 9 | Footer | Version/branding, minimal |
| 10 | Light / Dark Theme | CSS variable-based toggle, persisted per user |
| 11 | Responsive Grid | Mobile-first breakpoints — cashier/manager often on tablet/phone |

## 2. Design Tokens (base for all 78 pages)

| Token | Purpose |
|---|---|
| `--rs-primary` | Brand accent — used for CTAs, active nav state |
| `--rs-surface` / `--rs-surface-alt` | Card and page background layers (light + dark variants) |
| `--rs-border` | Consistent border color across all inputs/cards |
| `--rs-text` / `--rs-text-dim` | Primary vs secondary text — no ad-hoc grey values in individual pages |
| `--rs-radius` | Single border-radius value reused everywhere (cards, buttons, inputs) |
| `--rs-font-ui` / `--rs-font-bn` | Latin font + বাংলা font pairing (Hind Siliguri or similar) |

*Rule: no page-level CSS should hardcode a hex color — everything pulls from these tokens so theme switching and future rebranding stays centralized.*

## 3. Component Library (reused across all 78 pages)

- **Buttons** — primary / secondary / danger / ghost, with loading-spinner state
- **Form inputs** — text, select, date (Flatpickr), searchable dropdown, file upload
- **Data table** — DataTables wrapper: search, pagination, column sort, export (used in Product List, Customer List, Reports, etc.)
- **Modal** — standard confirm/edit dialogs (SweetAlert2 for confirm/delete actions)
- **Toast/Alert** — success/error/warning, consistent placement and timing
- **Badge/Status pill** — order status, subscription status, stock status (reused pattern from `sev-badge`-style visual language)
- **Empty state** — no-data illustration + CTA, used across all list pages
- **Chart wrapper** — Chart.js/ApexCharts container with consistent legend/tooltip styling

## 4. Responsive & Accessibility Rules

- Breakpoints: mobile (<640px), tablet (640–1024px), desktop (>1024px) — sidebar auto-collapses to off-canvas below tablet.
- POS screen specifically optimized for tablet landscape (cashier's primary device).
- All interactive elements meet minimum 44×44px touch target on mobile.
- Color contrast checked against both light and dark theme (WCAG AA minimum) — dashboard is used for long shifts, eye strain matters.

## 5. Role-Awareness in Shell

- Sidebar menu items rendered from the Permission Matrix (Phase 00) — a `cashier` never sees a "Settings" link rather than seeing it and getting a 403.
- Dashboard Shell accepts a `role` context so KPI widgets shown on the dashboard differ by role (owner sees revenue, cashier sees today's sales count only).

## 6. Multi-language Support (per ADR-015)

- Every UI Kit component ships with an **i18n key**, not hardcoded বাংলা/English string — new languages are added as translation files, no code touched.
- User-level language preference (not tenant-wide) — two staff at the same shop can use the dashboard in different languages.
- Missing-key fallback defaults to English, never a blank/raw-key display.
- Number/date formatting respects locale (Bangla numeral option for receipts/invoices if needed).

---

## Deliverable Sign-off Checklist
- [ ] Design tokens finalized (colors, radius, fonts) — light + dark
- [ ] Auth flow pages (Login, Register, Forgot/Reset, OTP, Lock Screen) built and reviewed
- [ ] Dashboard Shell (Sidebar + Header + Footer) built and role-aware
- [ ] Core component library (buttons, forms, table, modal, toast, badge, empty state, chart wrapper) documented with usage examples
- [ ] Responsive behavior verified on mobile/tablet/desktop
- [ ] Multi-language (i18n) key framework verified — new language addable without code change, missing-key fallback tested

**Once every box above is checked, Phase 01 is Done and Phase 02 (Shop Owner Panel) may begin — this is also where the "10-item Sprint 01" build receipt in the roadmap gets fulfilled.**