docs: fix Wave 3 documentation gaps — remove hardcoded credentials and add marketing theme ADR
- 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 <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
20
ROADMAP.md
20
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
|
||||
|
||||
|
||||
92
docs/adr/001-marketing-dual-theme.md
Normal file
92
docs/adr/001-marketing-dual-theme.md
Normal file
@@ -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
|
||||
<MudThemeProvider IsDarkMode="true" Theme="AppTheme.MarketingDark" />
|
||||
```
|
||||
|
||||
All other layouts use:
|
||||
|
||||
```razor
|
||||
<MudThemeProvider IsDarkMode="true" Theme="AppTheme.DefaultDark" />
|
||||
```
|
||||
|
||||
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 |
|
||||
Reference in New Issue
Block a user