# Open Questions & Risks — Phase 4

Flagged for awareness before Phase 5+ implementation begins. None block Phase 4.

## 1. This design system covers the merchant admin, not the customer-facing storefront

Every document in this phase builds on `../ux/01-information-architecture.md`, which is scoped entirely to the merchant-facing admin (Home, Orders, Products, Customers, Marketing, Reports, Settings). **The customer-facing storefront — product listing pages, product detail, cart, checkout — has no IA or design coverage yet from Phase 2 or Phase 4.**

**This is a real gap, not a deferred detail.** The admin and storefront are different audiences with different design pressures (the storefront needs to support a merchant's own branding/theming, per `../architecture/01-product-vision.md`'s positioning against being "a website builder" — but customers still need to buy things through it). Recommend explicitly scoping storefront IA and design as its own follow-up before Phase 5 implementation reaches Catalog/Orders screens that customers interact with directly, rather than assuming the admin's design tokens (built for an operator's tool) directly transfer to a customer-facing sales surface.

## 2. Color contrast — RESOLVED

**Decision (2026-07-09):** Audited. Three token values failed WCAG AA in their actual usage context — `neutral.500` muted text (3.4:1, needed 4.5:1), and all three semantic badge colors (`success.500`, `warning.500`, `danger.500` on their `*.100` backgrounds, 2.9–4.0:1, needed 4.5:1). A fourth issue was found beyond what this question originally flagged: `neutral.300`, used both as disabled-text color (contrast-exempt) and as the input/secondary-button border color (not exempt — needs 3:1), only passed by coincidence of the exemption; the border use case actually failed at 1.7:1.

All four are fixed in `02-design-tokens.md`, which now includes the full audit table: `neutral.500`, `success.500`, `warning.500`, and `danger.500` were darkened until each cleared its binding constraint, and a new `neutral.400` token was split out specifically for interactive borders, leaving `neutral.300` for its correctly-exempt disabled/placeholder-text use only. `03-component-conventions.md` was updated so inputs and secondary buttons reference `neutral.400`, not `neutral.300`. No further action needed before Phase 5.

## 3. No brand identity (logo, wordmark, marketing treatment) exists

This phase designs the *product's* visual system, not brand collateral. There is no CommerceDex logo, wordmark, or marketing-site treatment. The indigo accent color (`02-design-tokens.md`) was chosen to fit the product design principles, not derived from an existing brand mark.

**Not a blocker for Phase 5** (the product doesn't need a logo to be built and used), but flagged so that if/when brand identity work happens, it's treated as informing this token set (adjusting the accent color to match a chosen brand color, for instance) rather than happening independently and drifting from it.

## 4. Dark mode is not designed

Every token in `02-design-tokens.md` is a light-mode value. The token *naming* (semantic names like `color.neutral.900` for "primary text" rather than hardcoded hex references throughout the component specs) is structured so a dark palette could be added later as a parallel token set without restructuring components — but no dark palette has actually been designed, and it's not committed to any phase.

**Deferred, not decided:** revisit only if there's clear merchant demand; per "simplicity before flexibility," this shouldn't be built speculatively.

## 5. Icon library not chosen

Component specs (`03-component-conventions.md`) reference icons (nav items, status indicators, the suggestion card's indicator) without specifying a source. 

**Deferred to Phase 5 implementation:** pick a single open-source icon set (rather than mixing sources, which would break `01-design-principles.md`'s consistency principle) once the frontend framework is chosen in Phase 5, so the icon set's integration matches the stack.

---

**Status (updated 2026-07-09):** Item 2 is resolved — see above. Item 1 is addressed by a lightweight storefront flow addendum (`../ux/05-storefront-flows.md`) rather than a full storefront design phase; full storefront visual design remains deferred but the flow shape Phase 5 needs is no longer missing. Items 3–5 remain explicitly deferred, not open decisions blocking progress.