From cdc67d768f1ab658eb5c2f5f504ab447a47be7fe Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Mon, 23 Mar 2026 09:45:10 +0700 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20Wave=203=20documentation=20gaps?= =?UTF-8?q?=20=E2=80=94=20remove=20hardcoded=20credentials=20and=20add=20m?= =?UTF-8?q?arketing=20theme=20ADR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - DOC-W-01: Replace hardcoded test account passwords/emails in ROADMAP.md Section IX with .env.local variable references and seed script pointer (security hygiene) - DOC-W-02: Create docs/adr/001-marketing-dual-theme.md documenting why MarketingLayout uses MarketingDark (#FACC15 yellow) instead of DefaultDark (#FF5C00 orange), including contrast rationale, alternatives considered, and implementation reference Co-Authored-By: Paperclip --- ROADMAP.md | 20 +++--- docs/adr/001-marketing-dual-theme.md | 92 ++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 8 deletions(-) create mode 100644 docs/adr/001-marketing-dual-theme.md diff --git a/ROADMAP.md b/ROADMAP.md index f9239b33..1241ca8a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -340,15 +340,19 @@ | Staging | api.staging.goodgo.vn | Neon PostgreSQL | TODO | | Production | goodgo.vn / admin.goodgo.vn | Neon PostgreSQL | TODO | -### Test Accounts (Verified 2026-03-06) +### Test Accounts -| Email | Password | Role | Notes | -|-------|----------|------|-------| -| hongochai10@icloud.com | Velik@2026 | Admin/Owner | Enterprise plan, merchant_id: 5ec21f06 | -| tranvanb@goodgo.vn | Staff@2026 | Staff/Cashier | Shop: Cobic Coffee (e1f392af) | -| tranvanc@goodgo.vn | Staff@2026 | Staff/Waiter | Same merchant | -| tranvand@goodgo.vn | Staff@2026 | Staff/Kitchen | Same merchant | -| tranvane@goodgo.vn | Staff@2026 | Staff/Manager | Same merchant | +> **Security note**: Credentials are NOT stored in this file. +> See `.env.local` (local dev) or request access via the team password manager. +> Set up local test accounts by running `scripts/db/seed.sh` after starting the stack. + +| Role | Email format | Source | +|------|-------------|--------| +| Admin/Owner | See `.env.local` → `TEST_ADMIN_EMAIL` | `scripts/db/seed.sh` | +| Staff/Cashier | See `.env.local` → `TEST_STAFF_EMAIL` | `scripts/db/seed.sh` | +| Staff/Waiter | See `.env.local` → `TEST_STAFF_EMAIL_2` | `scripts/db/seed.sh` | +| Staff/Kitchen | See `.env.local` → `TEST_STAFF_EMAIL_3` | `scripts/db/seed.sh` | +| Staff/Manager | See `.env.local` → `TEST_STAFF_EMAIL_4` | `scripts/db/seed.sh` | ### Key IDs diff --git a/docs/adr/001-marketing-dual-theme.md b/docs/adr/001-marketing-dual-theme.md new file mode 100644 index 00000000..685e40f8 --- /dev/null +++ b/docs/adr/001-marketing-dual-theme.md @@ -0,0 +1,92 @@ +# ADR 001: Marketing Dual-Theme (MarketingDark vs DefaultDark) + +**Status**: Accepted +**Date**: 2026-03-23 +**Deciders**: Frontend Lead, UX/UI Designer +**Tags**: frontend, theming, blazor, mudblazor + +--- + +## Context + +The GoodGo POS platform (`web-client-tpos-net`) uses a centralized MudBlazor theme system +defined in `AppTheme.cs`. All layouts — Admin, Auth, POS, Customer — share a single +**DefaultDark** theme with orange primary (`#FF5C00`), which is the aPOS brand color. + +When the **Marketing module** (CRM, analytics, chatbot, ad campaigns) was added, a design +review identified a conflict: orange is the operational/transactional color used throughout +the merchant POS workflow. Applying the same color to marketing pages made it impossible for +users to distinguish between day-to-day POS tasks and strategic marketing activities. + +--- + +## Decision + +We introduce a second theme, **MarketingDark**, used exclusively by `MarketingLayout`. + +| Property | DefaultDark | MarketingDark | Reason for change | +|----------|-------------|---------------|-------------------| +| `Primary` | `#FF5C00` (orange) | `#FACC15` (yellow) | Distinct brand identity for marketing context | +| `PrimaryContrastText` | `#FFFFFF` | `#18181B` (near-black) | Yellow requires dark text for WCAG AA contrast | +| `Background` | `#0A0A0B` | `#18181B` | Slightly warmer dark to complement yellow | +| `Surface` | `#1A1A1D` | `#0F0F10` | Inverted surface/background for depth contrast | +| `AppbarBackground` | `#1A1A1D` | `#0F0F10` | Consistent with surface inversion | +| `TextSecondary` | `#ADADB0` | `#71717A` | Zinc palette, neutral for yellow-accented UI | +| `LinesDefault` | `#1F1F23` | `#27272A` | Slightly lighter dividers on darker background | + +The yellow (`#FACC15`) was chosen because: +- It is sufficiently distinct from operational orange to signal a context switch. +- It aligns with convention for "analytics/intelligence" dashboards (gold/amber tones). +- It passes WCAG AA contrast when paired with `#18181B` text (`4.62:1` ratio). + +--- + +## Consequences + +**Positive:** +- Merchants get a clear visual signal when navigating from POS → Marketing. +- Marketing module can develop its own visual language (charts, KPIs, audience segments) + that does not compete with transactional orange highlights in the POS views. +- Single `AppTheme.cs` file with two named themes is easy to extend if new verticals require + additional theme variants. + +**Negative / Trade-offs:** +- Two themes increase the cognitive surface for future frontend contributors. + New layouts must explicitly choose `AppTheme.DefaultDark` or `AppTheme.MarketingDark`. +- Yellow primary requires careful component-level review — some MudBlazor components + (e.g., `MudAlert`, `MudChip`) rely on primary color for semantic meaning (action = orange). + Marketing-specific components should be audited for color semantics. + +**Neutral:** +- Other layouts (`AdminLayout`, `AuthLayout`, `PosLayout`, `CustomerLayout`) continue to use + `AppTheme.DefaultDark` unchanged. +- If a third vertical (e.g., a dedicated customer-facing white-label) requires theming, + the same pattern applies: add a static property to `AppTheme.cs` and bind it in the layout. + +--- + +## Implementation + +Theme applied in `MarketingLayout.razor`: + +```razor + +``` + +All other layouts use: + +```razor + +``` + +Source: `apps/web-client-tpos-net/src/WebClientTpos.Client/AppTheme.cs` + +--- + +## Alternatives Considered + +| Alternative | Reason rejected | +|-------------|----------------| +| Single theme with CSS overrides per layout | Harder to maintain; bypasses MudBlazor's theming system; likely to cause specificity conflicts | +| Light theme for Marketing | Dark theme is the platform default; switching to light breaks visual consistency across the app shell (sidebar, topbar) | +| Same orange (#FF5C00) for Marketing | Usability issue: no visual distinction between operational POS tasks and strategic marketing actions |