159 lines
5.1 KiB
Markdown
159 lines
5.1 KiB
Markdown
# Gishen Email Templates — Design Spec
|
|
|
|
**Date:** 2026-08-07
|
|
**Status:** Approved for implementation planning
|
|
**Repo:** `Gishen/Gishen-Email-Templates`
|
|
**Remote:** `https://gitea.yaltopia.com/Gishen/Gishen-Email-Templates.git`
|
|
|
|
## Goal
|
|
|
|
A shared React Email project that demos and exports transactional (and light marketing) emails for all Gishen surfaces: **Ecom**, **Admin**, and **B2B**. Brand, colors, and logo match the existing Gishen apps. Preview UI supports **English and Amharic**.
|
|
|
|
## Non-goals (v1)
|
|
|
|
- Sending mail (SMTP/ESP integration)
|
|
- Live backend wiring inside Ecom/Admin/B2B
|
|
- Dark-mode email variants
|
|
- Pixel-perfect Amharic typography across every client (system + common web-safe fallbacks)
|
|
|
|
## Architecture
|
|
|
|
Mirror **Amba-Emails**:
|
|
|
|
| Piece | Role |
|
|
|-------|------|
|
|
| `emails/` | React Email templates + shared components |
|
|
| `emails/theme.ts` | Gishen brand tokens |
|
|
| `emails/i18n/` | `en` / `am` string tables per template family |
|
|
| `emails/components/` | `EmailLayout`, `Button`, `Card`, `StatusBanner`, `OrderSummary` |
|
|
| `app/` | Next.js preview: template switcher + locale toggle |
|
|
| `app/api/email/[template]/route.ts` | Render HTML for demos / future consumer apps |
|
|
| `public/brand/` | Logo assets (from Gishen-B2B) |
|
|
| `CHANGELOG.md` | Keep a Changelog |
|
|
| `README.md` | Templates, props, how to consume |
|
|
|
|
**Scripts:** `npm run preview` (Next), `npm run email` (React Email CLI), `npm run build` (HTML export).
|
|
|
|
**Consumer contract:** apps pass props + `locale`; they either call the render API in demo setups or copy exported HTML / import templates later. v1 does not mutate sibling repos beyond using them as brand/reference sources.
|
|
|
|
## Brand
|
|
|
|
From `Gishen-B2B/src/data/brand.ts` and Admin Tailwind:
|
|
|
|
| Token | Value |
|
|
|-------|--------|
|
|
| brand | `#A8C73A` |
|
|
| brandDeep | `#8FAD2F` |
|
|
| forest | `#141414` |
|
|
| accent | `#E28A1A` |
|
|
| cream / background | `#F6F7F2` |
|
|
| surface | `#FFFFFF` |
|
|
| line | `#E2E5D8` |
|
|
| muted | `#5C5F56` |
|
|
|
|
- Product name: **Gishen Pharmacy**
|
|
- Logo: `Gishen-B2B/public/brand/gishen-logo.png` → `public/brand/` + optional data URI for clients that block remote images poorly in local demos
|
|
- Footer: `info@gishenpharmacy.org` · `https://gishenpharmacy.org` · Addis Ababa, Ethiopia
|
|
|
|
## Locales
|
|
|
|
- Every template accepts `locale: 'en' | 'am'` (default `'en'`).
|
|
- Preview UI has an en/am toggle.
|
|
- String tables live under `emails/i18n/`; Amharic copy is production-intent for v1 (not `TODO` placeholders).
|
|
|
|
## Template inventory
|
|
|
|
### Auth / account
|
|
|
|
1. `welcome`
|
|
2. `password-reset`
|
|
3. `email-verify`
|
|
4. `user-invite`
|
|
|
|
### Orders (Ecom / member)
|
|
|
|
5. `order-confirmation`
|
|
6. `order-packing`
|
|
7. `order-out-for-delivery`
|
|
8. `order-delivered`
|
|
9. `order-cancelled`
|
|
|
|
### B2B
|
|
|
|
10. `org-invite`
|
|
11. `join-code`
|
|
12. `approval-needed`
|
|
13. `statement-ready`
|
|
14. `credit-alert`
|
|
15. `organisation-verified`
|
|
|
|
### Prescriptions
|
|
|
|
16. `prescription-submitted`
|
|
17. `prescription-decision` (approved | rejected via props)
|
|
18. `prescription-ready`
|
|
|
|
### Admin ops
|
|
|
|
19. `low-stock`
|
|
20. `dispatch-assigned`
|
|
21. `procurement-alert`
|
|
|
|
### Marketing
|
|
|
|
22. `promotional`
|
|
|
|
### Ecom analytics
|
|
|
|
23. `shop-summary` — **one** template with `period: 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'` and summary metrics props (orders, revenue, top SKUs, etc.)
|
|
|
|
## Shared components
|
|
|
|
- `EmailLayout` — logo header, cream body shell, branded footer
|
|
- `Button` — primary CTA (brand / forest text)
|
|
- `Card` — section block with line border
|
|
- `StatusBanner` — success / warning / danger / info using brand + accent
|
|
- `OrderSummary` — line items + totals for order emails
|
|
- `MetricGrid` — for `shop-summary` KPI rows
|
|
|
|
## Preview app behavior
|
|
|
|
- List all templates by category
|
|
- Live iframe or server-rendered preview of selected template
|
|
- Locale toggle (en/am)
|
|
- Sample props hardcoded per template for demo realism (Ethiopian pharmacy / B2B context)
|
|
|
|
## Git / repo setup
|
|
|
|
1. Create directory, `README.md`, `CHANGELOG.md`, scaffold app
|
|
2. `git init` → branch `main`
|
|
3. Initial commit(s)
|
|
4. `git remote add origin https://gitea.yaltopia.com/Gishen/Gishen-Email-Templates.git`
|
|
5. `git push -u origin main` (requires credentials available in environment)
|
|
|
|
## Reference projects
|
|
|
|
| Repo | Use |
|
|
|------|-----|
|
|
| Amba-Emails | Structure, React Email patterns, API route |
|
|
| Gishen-B2B | Brand, logo, portal email contexts |
|
|
| Gishen-Admin | Ops domains (stock, dispatch, procurement, Rx) |
|
|
| Gishen-Ecom | Order + shop summary contexts (clone if auth available) |
|
|
| Yaltopia-Ticket-Email | Secondary email reference (clone may need auth) |
|
|
|
|
**Note:** HTTPS clone of private Gitea repos failed in this environment without credentials. Local `Gishen-Admin` and `Gishen-B2B` copies are sufficient for brand; Ecom specifics use documented B2B/Admin order/stock flows where Ecom is unavailable.
|
|
|
|
## Success criteria
|
|
|
|
- `npm install && npm run preview` shows all templates with en/am switching
|
|
- Colors and logo clearly match Gishen apps
|
|
- HTML render API returns each template
|
|
- `CHANGELOG.md` records `0.1.0`
|
|
- Remote `main` pushed when credentials allow
|
|
|
|
## Out-of-scope follow-ups
|
|
|
|
- Wire templates into Nest/API workers
|
|
- ESP (Resend/SendGrid) adapters
|
|
- Automated visual regression of rendered HTML
|