commit 8261920b9e66d8eadffab97f6228ac5c3249e1f6 Author: Kirubel-Kibru-Yaltopia Date: Fri Aug 7 22:02:39 2026 +0300 Add design spec for Gishen email templates. Co-authored-by: Cursor diff --git a/README.md b/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/superpowers/specs/2026-08-07-gishen-email-templates-design.md b/docs/superpowers/specs/2026-08-07-gishen-email-templates-design.md new file mode 100644 index 0000000..90199ad --- /dev/null +++ b/docs/superpowers/specs/2026-08-07-gishen-email-templates-design.md @@ -0,0 +1,158 @@ +# 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