Design Spec: Manage Customer Vouchers

Generated from: proposal.md (ui_scope: full) Platform: figma Last updated: 2026-05-17

Overview

An admin (management-side) page that lets branch administrators search a customer's vouchers and lets high-privilege roles revoke (void) a voucher with a confirmation step. Covers proposal stories US-1 (search) and US-2 (revoke).

This design reuses the existing M+ hair-salon design system — the shared "Design Tokens" variable collection (warm gold/cream identity) already used by the M+ Customer and Designer portals — so the admin surface is visually consistent with the rest of the product.

---

Visual Identity

Color Palette

Token	Value	Usage
--color-primary	#ca8a04	Primary actions, active states, links
--color-primary-hover	#a16207	Primary hover
--color-primary-muted	#ca8a0415	Subtle tinted backgrounds, pills
--color-primary-border	#ca8a0433	Card / input borders
--color-surface	#ffffffe6	Card backgrounds
--color-surface-solid	#ffffff	Inputs, table surface
--color-surface-muted	#fafaf9	Table header / zebra rows
--color-background	#f5f5f4	Page background
--color-text	#0c0a09	Primary text
--color-text-secondary	#44403c	Secondary text
--color-text-muted	#78716c	Labels, captions
--color-text-disabled	#a8a29e	Disabled / revoked rows
--color-border	#e7e5e4	Table dividers
--color-success	#16a34a / bg #dcfce7	Status: 有效 (active)
--color-error	#dc2626 / bg #fee2e2	Destructive action, status: 已撤銷
--color-disabled-bg	#f3f4f6	Status: 已失效 / 已用完

Typography

Family: Noto Sans TC (CJK-capable). Latin/numeric also rendered with Noto Sans TC.

Token	Size	Weight	Usage
--font-heading-lg	28px	700	Page title
--font-heading	20px	700	Card / dialog titles
--font-title	16px	500	Table column headers, row primary text
--font-body	14px	400	Table cell text, buttons
--font-small	13px	400	Secondary cell text
--font-caption	12px	400	Captions, helper text

Spacing Scale

Token	Value	Usage
--space-xs	4px	Inline gaps
--space-sm	8px	Compact padding, pill padding
--space-md	16px	Default padding, cell padding
--space-lg	24px	Card padding, section spacing

Visual Style

• Border radius: 22px (cards/dialog), 12px (inputs/buttons-rect), 999px (pill badges)
• Shadow: 0 25px 50px #ca8a042e (card), 0 16px 40px #00000026 (dialog)
• Transition: 150ms ease-in-out
• Page background: warm radial gradient (#fff8e1 → #fafaf9 → #f8f5f0)

---

Components

TopBar

Layout: flex, horizontal, space-between, height 64px, full width, padding 0 32px States: single static state. Design Tokens: background --color-surface, bottom border --color-primary-border. Children:

• Brand: M+ logo mark + "M+ 管理後台" label
• Admin meta: admin display name + role badge + logout button

PageHeader

Layout: flex, vertical, gap 8px Children:

• Title "顧客卡券管理" (--font-heading-lg, --color-text)
• Description "搜尋並管理顧客卡券,協助確認餘額或撤銷錯誤卡券。" (--font-body, --color-text-muted)

SearchBar

Layout: card, flex horizontal, gap 12px, align center, padding --space-lg States:

State	Visual Changes
Default	Empty input, placeholder visible
Focused	Input border --color-primary
Disabled (search btn)	Empty input → search button --color-disabled-bg

Children:

• Search input: leading search icon + text field, placeholder "輸入顧客姓名、手機號碼或卡券序號"
• Search button: primary, label "搜尋"
• Helper text (empty submit): "請輸入搜尋條件" (--color-error)

VoucherTable

Layout: card; vertical; header row + data rows; columns separated by --space-md Columns: 顧客 | 卡券類型 | 剩餘 | 購買日期 | 失效日期 | 狀態 | 操作

States:

State	Visual Changes
Default row	Surface background, --color-text text
Revoked row	--color-text-disabled text, no revoke action
Hover row	--color-surface-muted background

Design Tokens: header background --color-surface-muted, row divider --color-border. Children: rows of [CustomerCell, TypeCell, RemainingCell, DateCell ×2, StatusBadge, RevokeButton]

StatusBadge

Layout: pill, padding --space-sm --space-xs, radius 999px States (variants):

Variant	Background	Text	Meaning
active	--color-success-bg	--color-success	有效
used-up	--color-disabled-bg	--color-text-disabled	已用完
expired	--color-disabled-bg	--color-text-disabled	已失效
revoked	--color-error-bg	--color-error	已撤銷

RevokeButton

Layout: text/ghost button, --font-body States:

State	Visual Changes
Default (high-priv)	--color-error label "撤銷"
Hover	underline
Hidden (normal admin)	Not rendered — only high-privilege roles see it
Disabled (already revoked)	Not rendered for revoked rows

EmptyState

Layout: flex vertical, center aligned, gap --space-md, padding 48px Children: package icon (64px circle, --color-surface-muted), title "查無卡券", description "找不到符合搜尋條件的卡券,請確認姓名、手機或序號是否正確。"

RevokeConfirmDialog

Layout: modal — full-screen overlay (--color-overlay) + centered dialog card (radius 22px, dialog shadow, max-width 440px, padding --space-lg) States:

State	Visual Changes
Visible	Overlay + dialog shown
Submitting	Confirm button spinner, both buttons disabled
Already-revoked block	Replaces actions with notice "此卡券已撤銷"

Children:

• Title "撤銷卡券確認"
• Voucher summary block: 顧客 / 卡券類型 / 卡券序號 / 剩餘 / 購買日期
• Warning text "撤銷後此卡券將於顧客端隱藏且無法復原,系統會記錄本次操作。"
• Actions: 取消 (secondary) + 確認撤銷 (destructive, --color-error fill)

---

Responsive Strategy

This is a desktop-first admin tool. Primary target is desktop (≥1024px).

Breakpoints

Name	Min Width	Layout
Tablet	768px	Content full-width with 24px gutter; table scrolls horizontally
Desktop	1024px	Centered content container, max-width 1200px

Layout Adaptations

Component	Tablet	Desktop
SearchBar	Input + button stack-friendly, still inline	Inline, input grows
VoucherTable	Horizontal scroll inside card	All columns visible
RevokeConfirmDialog	90% viewport width	Fixed 440px width

Navigation

• Desktop: persistent top bar; admin sections reachable from top bar (out of scope here).
• The page itself is a single-view destination — no in-page navigation.

Interaction Spec: Manage Customer Vouchers

Generated from: proposal.md + design-spec.md DSL Version: draft-1 Last updated: 2026-05-17

Screens

Screen: VoucherManagement

States:

State	Description	Entry Condition
Idle	Search bar shown, no query run yet	Initial visit
InvalidSubmit	Empty search submitted	Search clicked with blank input
Loading	Fetching voucher results	Valid search submitted
Results	Voucher table rendered with rows	Fetch success, ≥1 match
NoResults	Empty state shown	Fetch success, 0 matches
Error	Fetch failed notice	Fetch error

Transitions:

Idle          -> InvalidSubmit : search click with empty input
InvalidSubmit -> Loading       : search click with non-empty input
Idle          -> Loading       : search click with non-empty input
Loading       -> Results       : fetch success (matches > 0)
Loading       -> NoResults     : fetch success (matches == 0)
Loading       -> Error         : fetch error
Error         -> Loading       : retry click
Results       -> Loading       : new search submitted

Branch scoping (FR-003) is applied server-side: results only ever contain vouchers of the administrator's own branch. Cross-branch matches never enter the Results state.

Component: RevokeConfirmDialog

States:

State	Description	Entry Condition
Hidden	Not shown	Default
Visible	Overlay + dialog with voucher summary	Revoke clicked on an active row
Submitting	Confirm pressed, awaiting result	Confirm click
AlreadyRevoked	Notice "此卡券已撤銷", revoke blocked	Revoke attempted on an already-revoked voucher

Transitions:

Hidden     -> Visible        : revoke click (row not revoked)
Hidden     -> AlreadyRevoked : revoke click (row already revoked)
Visible    -> Submitting     : confirm revoke click
Visible    -> Hidden         : cancel click / overlay click
Submitting -> Hidden         : revoke success (row updates to 已撤銷)
Submitting -> Visible        : revoke error (inline error, re-enable)
AlreadyRevoked -> Hidden     : dismiss click

---

Flows

Flow: Search a customer's vouchers (US-1)

Description: An administrator looks up a customer's vouchers to confirm balance.

Steps:

1. User types a name / phone / voucher serial into the search input
   -> Search button becomes enabled

2. User clicks 搜尋
   -> If input empty: stay on screen, show helper "請輸入搜尋條件"
   -> If valid: show Loading state

3. System fetches branch-scoped voucher results
   -> On success with matches: render VoucherTable (customer, type,
      remaining, purchase date, expiry date, status)
   -> On success with no match: render EmptyState "查無卡券"
   -> On error: show Error notice with retry

Flow: Revoke a voucher (US-2)

Description: A high-privilege administrator voids an incorrect voucher.

Steps:

1. (Precondition) Revoke action is visible only to high-privilege roles
   (store manager / HQ admin). Normal admins never see the 撤銷 button.

2. User clicks 撤銷 on an active voucher row
   -> Open RevokeConfirmDialog (Visible) showing the voucher summary
   -> If the voucher is already revoked: open AlreadyRevoked state instead

3. User reviews voucher info + warning text
   -> Click 取消: close dialog, voucher unchanged
   -> Click 確認撤銷: dialog enters Submitting (confirm spinner)

4. System soft-deletes the voucher and writes an audit log
   (operator, timestamp, voucher identity, prior status)
   -> On success: close dialog, row status updates to 已撤銷 (greyed, no action),
      voucher is hidden on the customer side
   -> On error: stay in dialog, show inline error, re-enable buttons

---

Gestures & Micro-interactions

Trigger	Animation	Duration
Button press	Background color shift to hover/active	150ms
Dialog appear	Overlay fade in + dialog scale 0.96 → 1.0	150ms
Row status change to 已撤銷	Row text fades to disabled color	200ms
Search submit	Search button shows inline spinner	—

Responsive Interactions

Interaction	Tablet	Desktop
Browse table columns	Horizontal scroll within table card	All columns visible at once
Revoke action	Tap 撤銷 → dialog at 90% width	Click 撤銷 → fixed 440px dialog
Search	Inline input + button	Inline input + button