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

Typography

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

Spacing Scale

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:

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:

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):

RevokeButton

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

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:

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

Layout Adaptations

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:

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:

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

Responsive Interactions