System Requirements Document for loyality-qr-wallet

1. Introduction

loyality-qr-wallet is a loyalty QR wallet product built for the business side: a business runs its own loyalty program for its own customers. The business owner sets up a program, issues loyalty QR codes, and tracks customer participation and rewards; their customers scan those QR codes at the point of interaction to collect stamps/points, hold their loyalty cards and rewards in a wallet, and redeem accumulated rewards.

The product intent is a small gift economy made operational: the register-side work is real and durable, but the experience must feel pleasant, optimistic and almost toy-like — scanning a QR code should feel like a small reward in itself, never like enterprise admin. The audience is everyday shop owners and everyday shoppers: coffee shops, salons, bakeries, gyms, retail.

The audience for this document is the implementing team (design, frontend, backend) and the product owner.

2. System Overview

loyality-qr-wallet is a custom-UI web application with an application-owned backend. It has two accepted human actors:

• Business Owner / Loyalty Program Operator — sets up and operates the loyalty program, issues and manages the loyalty QR codes customers scan, and tracks customer participation and rewards.
• Customer / Loyalty Member — scans the business's loyalty QR code at the point of interaction, accumulates stamps/points, holds loyalty cards and rewards in a wallet, and redeems rewards.

Current delivery is a first-party application with application-owned identity: both actors establish identity on first use and verify it on return, because each holds durable, actor-specific state (the business owner's program, QR codes and participation records; the customer's cards, stamp balances and rewards). The anonymous entry surface (Landing) explains the product before any identity is established.

Narrow exclusions. The product is for the business side, not for shoppers to run their own program. Shoppers are loyalty members of a business's program; they do not create or operate programs of their own. No adjacent capabilities beyond the accepted loyalty lifecycle are in scope.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. All accepted behavior is delivered by the first-party application: the business owner's program operation and the customer's wallet, scanning and redemption are custom application surfaces backed by the application's own backend and durable storage. There is no provider-owned or external-only surface in the accepted scope, and no headless-only delivery.

Access ownership. Identity is application-owned. The Landing surface is anonymously reachable and establishes no identity. Business Login and Customer Login are the anonymous entry boundaries where each actor establishes identity on first use and verifies it on return; they are reachable without an existing session because a protected destination cannot own the interaction that establishes access to itself. Dashboard, Program Setup and QR Codes are restricted to the business owner; Wallet, Scan and Redeem are restricted to the customer. Access restriction here is actor-continuity restriction — each actor's durable state must remain bound to the correct participant — not a differentiated permission model over shared product state.

Current vs. future. Everything described in this document is current. No future-horizon requirements were accepted.

2b. Source Content Inventory

Not applicable — no reference directive declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression. Explains the loyalty QR wallet product, who it is for (businesses running their own loyalty program for their customers), and what it does (customers scan QR codes to collect stamps/points and hold cards and rewards in a wallet). No identity, no session, no durable state.
• Primary actions: "Start your program" — pill CTA in ink-on-lime, routing to Business Login. "I have a card" — secondary text link, routing to Customer Login.
• Supporting actions: None beyond the two entry routes.
• Domain entities: None owned; the page describes the product only.
• Component responsibilities: Full-bleed bubblegum field; giant flat hot-pink organic blob bleeding off the top and right edges; glossy white loyalty capsule card rotated −4° overlapping the blob's left curve, carrying a pink QR plaque and a row of eight stamp circles (first five filled lime); three-line flush-left Comfortaa headline with "stamps" and "rewards" set in lime against the pink blob; bottom-edge ticker of tiny stamp tokens and shop names; curved elliptical pink arc dipping into the next section.
• States: Loading — static content, no data fetch; no loading state required. Empty — not applicable. Success — not applicable (no submission). Error — not applicable. Recovery — not applicable. Under prefers-reduced-motion, the blob drift stops and the bottom ticker resolves into a static two-row list.

Business Login

• Information/state: Anonymous identity-access surface for the Business Owner / Loyalty Program Operator. Two modes: first-use enrollment (establish identity) and returning verification (verify identity). No protected business state is visible before identity is established.
• Primary actions: Enroll on first use; verify on return; submit credentials.
• Supporting actions: Switch between enrollment and returning verification; move to Customer Login if the visitor is a customer.
• Domain entities: Business owner identity (application-owned credential record).
• Component responsibilities: Mode switch; credential fields; submit pill button; inline validation messaging; link to Customer Login.
• States: Loading — submit in progress, control disabled with visible progress. Empty — blank credential fields on first arrival. Success — identity established or verified, routing to Dashboard. Error — invalid or unrecognized credentials, or an enrollment conflict, shown inline with the fields preserved for correction. Recovery — the actor can retry, correct fields, or switch modes without losing entered values.

Dashboard

• Information/state: Business owner's summary and entry point for operating the loyalty program and tracking customer participation and rewards. Shows the program's current state and participation/reward activity. Restricted to the business owner.
• Primary actions: Open Program Setup; open QR Codes; review participation and reward activity.
• Supporting actions: Navigate between the business surfaces via the left rail of pill-shaped tabs.
• Domain entities: Loyalty program, QR codes, customer participation records, reward records.
• Component responsibilities: Left rail of pill-shaped tabs; canvas of stacked glossy cards with big numerals; program summary card; participation summary card; reward summary card; empty-program prompt pointing to Program Setup.
• States: Loading — summary cards in a loading state while program and participation data resolve. Empty — no program set up yet: a prompt directing the owner to Program Setup, with no fabricated participation figures. Success — program summary and participation/reward figures rendered. Error — summary data could not be loaded: an inline message with a retry action. Recovery — retry reloads the summary; the owner can still navigate to Program Setup or QR Codes.

Customer Login

• Information/state: Anonymous identity-access surface for the Customer / Loyalty Member. Two modes: first-use enrollment (establish identity) and returning verification (verify identity). No wallet, card, stamp or reward state is visible before identity is established.
• Primary actions: Enroll on first use; verify on return; submit credentials.
• Supporting actions: Switch between enrollment and returning verification; move to Business Login if the visitor is a business owner.
• Domain entities: Customer identity (application-owned credential record).
• Component responsibilities: Mode switch; credential fields; submit pill button; inline validation messaging; link to Business Login.
• States: Loading — submit in progress, control disabled with visible progress. Empty — blank credential fields on first arrival. Success — identity established or verified, routing to Wallet. Error — invalid or unrecognized credentials, or an enrollment conflict, shown inline with the fields preserved for correction. Recovery — the actor can retry, correct fields, or switch modes without losing entered values.

Program Setup

• Information/state: The business owner sets up and operates its own loyalty program for its customers. Holds the program's definition and its current operating state. Restricted to the business owner.
• Primary actions: Create the program; define and edit its settings; save changes.
• Supporting actions: Review the program's current configuration; move to QR Codes once the program exists.
• Domain entities: Loyalty program (the business's own program, its settings, and its stamp/point and reward definition).
• Component responsibilities: Program definition form in glossy cards; save control; current-configuration summary; prompt to issue QR codes after the program exists.
• States: Loading — existing program configuration loading. Empty — no program yet: the creation form is presented as the primary content. Success — program saved, with confirmation and a route to QR Codes. Error — validation failure or save failure, shown inline with entered values preserved. Recovery — correct and resubmit; previously saved configuration remains intact.

QR Codes

• Information/state: The business owner issues and manages the loyalty QR codes customers scan to collect stamps/points. Lists the program's issued QR codes and their state. Restricted to the business owner.
• Primary actions: Issue a QR code; view a QR code for display at the point of interaction.
• Supporting actions: Manage issued QR codes; return to Dashboard or Program Setup.
• Domain entities: Loyalty QR code (bound to the business's program).
• Component responsibilities: Issue control; QR code list; QR code display with the QR modules kept square for scannability; pink QR frame treatment; empty-state prompt when no code has been issued.
• States: Loading — QR code list loading. Empty — no QR code issued yet: prompt to issue the first code. Success — issued code listed and displayable for scanning. Error — issue or load failure, shown inline with a retry action. Recovery — retry the failed operation; previously issued codes remain listed and displayable.

Wallet

• Information/state: The customer holds and views their loyalty cards and rewards in a wallet. Shows the customer's cards, their stamp/point progress, and their rewards. Restricted to the customer.
• Primary actions: View the active loyalty card and its stamp/point progress; view rewards; move to Scan to collect; move to Redeem when a reward is available.
• Supporting actions: Move between cards in the stack.
• Domain entities: Loyalty card, stamp/point balance, reward.
• Component responsibilities: Physical card-stack metaphor — active card at full size with the next two peeking behind at 2° and 4° with soft offset shadows; stamp token row (eight glossy candy discs, filled ones lime with a 2px white inner highlight, empty ones pink outlines); reward-ready accent in lime; pointer/drag tilt on desktop and gentle drag tilt on mobile.
• States: Loading — cards and balances loading. Empty — no cards yet: prompt directing the customer to Scan. Success — cards, stamp/point progress and rewards rendered. Error — wallet data could not be loaded: inline message with retry. Recovery — retry reloads the wallet; the customer can still move to Scan. Under prefers-reduced-motion, the stack becomes a static vertical list.

Scan

• Information/state: The customer scans a business's loyalty QR code to collect stamps/points. Shows the scanning interaction and the result of a scan. Restricted to the customer.
• Primary actions: Scan a business's loyalty QR code; confirm the collected stamp/point.
• Supporting actions: Move to Wallet to view the updated card; move to Redeem when a reward becomes available.
• Domain entities: Loyalty QR code (scanned), loyalty card, stamp/point balance.
• Component responsibilities: Scan capture surface; stamp token row as the primary progress component; stamp token scaling from 0.6 to 1 with a light overshoot on a successful scan; lime "collected" tick.
• States: Loading — scan processing. Empty — no scan captured yet: the capture surface is presented as the primary content. Success — stamp/point collected, the token row advances with a single liquid overshoot, and the lime collected tick appears. Error — the scanned code is not a valid loyalty QR code for a program, or the scan could not be processed: an inline message with a retry action, and no stamp/point is recorded. Recovery — rescan; the customer's existing balance is unchanged by a failed scan.

Redeem

• Information/state: The customer redeems accumulated loyalty rewards. Shows the customer's available rewards and the redemption interaction. Restricted to the customer. A reward is redeemable only once the customer has collected enough stamps/points.
• Primary actions: Select an available reward; redeem it.
• Supporting actions: Return to Wallet to view the updated card and balance.
• Domain entities: Reward, stamp/point balance, loyalty card.
• Component responsibilities: Available-reward presentation with the lime reward-ready accent; stamp token row showing progress toward the reward; redeem control; confirmation of the redeemed reward.
• States: Loading — rewards and balance loading. Empty — no reward available yet: the customer's current progress toward the next reward is shown with a route back to Scan. Success — reward redeemed, with confirmation and the updated balance reflected. Error — redemption failed or the reward is no longer available: an inline message with a retry action, and the balance is unchanged. Recovery — retry, or return to Wallet; a failed redemption does not consume stamps/points.

3. Functional Requirements

FR-1 — Business owner first-use enrollment and returning verification (required_inference) As a Business Owner / Loyalty Program Operator, I should be able to establish my identity on first use and verify it on return, so that my program and its durable records stay bound to me.

• Trigger/input: Arrival at Business Login; credential entry.
• Observable result: On first use, an identity is established and the owner reaches Dashboard. On return, verification succeeds and the owner reaches Dashboard.
• Access state: Business Login is anonymously reachable; Dashboard, Program Setup and QR Codes are restricted to the business owner.
• Failure/recovery: Invalid or unrecognized credentials, or an enrollment conflict, are shown inline with entered values preserved; the owner can retry, correct fields, or switch modes.
• Continuation: On success, the owner continues into Dashboard.

FR-2 — Customer first-use enrollment and returning verification (required_inference) As a Customer / Loyalty Member, I should be able to establish my identity on first use and verify it on return, so that my cards, stamp/point balances and rewards stay bound to me.

• Trigger/input: Arrival at Customer Login; credential entry.
• Observable result: On first use, an identity is established and the customer reaches Wallet. On return, verification succeeds and the customer reaches Wallet.
• Access state: Customer Login is anonymously reachable; Wallet, Scan and Redeem are restricted to the customer.
• Failure/recovery: Invalid or unrecognized credentials, or an enrollment conflict, are shown inline with entered values preserved; the customer can retry, correct fields, or switch modes.
• Continuation: On success, the customer continues into Wallet.

FR-3 — Business owner sets up its own loyalty program (explicit) As a Business Owner / Loyalty Program Operator, I should be able to set up my own loyalty program for my customers, so that my business has a program to run.

• Trigger/input: The owner opens Program Setup and defines the program's settings.
• Observable result: The program exists and its configuration is saved and visible.
• Access state: Restricted to the business owner.
• Failure/recovery: Validation or save failure is shown inline with entered values preserved; previously saved configuration remains intact.
• Continuation: Once the program exists, the owner continues to QR Codes to issue a code.

FR-4 — Business owner operates its loyalty program (explicit) As a Business Owner / Loyalty Program Operator, I should be able to operate my own loyalty program for my customers, so that the program keeps running as I intend.

• Trigger/input: The owner edits the program's settings in Program Setup and saves.
• Observable result: The updated configuration is saved and reflected in the program's current state.
• Access state: Restricted to the business owner.
• Failure/recovery: Save failure is shown inline with entered values preserved; the previously saved configuration remains in effect.
• Continuation: The owner returns to Dashboard or QR Codes with the updated configuration in effect.

FR-5 — Business owner issues loyalty QR codes (explicit) As a Business Owner / Loyalty Program Operator, I should be able to issue loyalty QR codes, so that my customers have a code to scan to collect stamps/points.

• Trigger/input: The owner issues a QR code from QR Codes, bound to the program.
• Observable result: The QR code is issued, listed, and displayable for scanning at the point of interaction.
• Access state: Restricted to the business owner.
• Failure/recovery: Issue or load failure is shown inline with a retry action; previously issued codes remain listed and displayable.
• Continuation: The owner displays the code at the point of interaction for customers to scan.

FR-6 — Business owner manages loyalty QR codes (explicit) As a Business Owner / Loyalty Program Operator, I should be able to manage the loyalty QR codes I have issued, so that the codes in circulation match what my program needs.

• Trigger/input: The owner reviews and manages issued QR codes from QR Codes.
• Observable result: The set of issued QR codes and their state are visible and current.
• Access state: Restricted to the business owner.
• Failure/recovery: Load failure is shown inline with a retry action; the last known list remains usable.
• Continuation: The owner returns to Dashboard or continues managing codes.

FR-7 — Business owner tracks customer participation and rewards (explicit) As a Business Owner / Loyalty Program Operator, I should be able to track customer participation and rewards, so that I can see how my customers are engaging and keep them returning.

• Trigger/input: The owner opens Dashboard.
• Observable result: Participation and reward activity for the program are summarized and visible.
• Access state: Restricted to the business owner.
• Failure/recovery: Summary load failure is shown inline with a retry action; navigation to Program Setup and QR Codes remains available.
• Continuation: The owner acts on what they see by adjusting the program or its QR codes.

FR-8 — Customer scans a business's loyalty QR code to collect stamps/points (explicit) As a Customer / Loyalty Member, I should be able to scan a business's loyalty QR code to collect stamps/points, so that my visits accumulate toward a reward.

• Trigger/input: The customer scans the business's loyalty QR code from Scan.
• Observable result: The stamp/point is collected, the stamp token row advances with a single liquid overshoot, and the lime collected tick appears.
• Access state: Restricted to the customer.
• Failure/recovery: An invalid or unprocessable code shows an inline message with a retry action and records no stamp/point; the existing balance is unchanged.
• Continuation: The customer continues to Wallet to see the updated card, or to Redeem when a reward becomes available.

FR-9 — Customer holds and views loyalty cards and rewards in a wallet (explicit) As a Customer / Loyalty Member, I should be able to hold and view my loyalty cards and rewards in a wallet, so that everything I have collected is in one place.

• Trigger/input: The customer opens Wallet.
• Observable result: The customer's cards, stamp/point progress and rewards are visible in the card stack.
• Access state: Restricted to the customer.
• Failure/recovery: Wallet load failure shows an inline message with retry; the customer can still move to Scan.
• Continuation: The customer continues to Scan to collect or to Redeem when a reward is available.

FR-10 — Customer redeems accumulated loyalty rewards (explicit) As a Customer / Loyalty Member, I should be able to redeem accumulated loyalty rewards, so that my collected stamps/points turn into something I actually get.

• Trigger/input: The customer selects an available reward in Redeem and redeems it.
• Observable result: The reward is redeemed, confirmed, and the updated balance is reflected.
• Access state: Restricted to the customer; a reward is redeemable only once enough stamps/points have been collected.
• Failure/recovery: A failed redemption or an unavailable reward shows an inline message with a retry action; the balance is unchanged and no stamps/points are consumed.
• Continuation: The customer returns to Wallet to view the updated card and balance.

FR-11 — Anonymous product entry (required_inference) As a visitor (Business Owner / Loyalty Program Operator or Customer / Loyalty Member), I should be able to understand what the loyalty QR wallet product is, who it is for, and what it does before establishing any identity, so that I can choose the right entry.

• Trigger/input: Anonymous arrival at Landing.
• Observable result: The product's purpose and audience are explained, with "Start your program" routing to Business Login and "I have a card" routing to Customer Login.
• Access state: No identity required; no protected state is visible.
• Failure/recovery: Not applicable — static content with no submission.
• Continuation: The visitor continues into Business Login or Customer Login.

FR-12 — Program prerequisite for scanning (required_inference) As a Business Owner / Loyalty Program Operator, I should have set up a loyalty program and issued a QR code before a customer can scan and collect stamps/points, so that a scan always resolves to a real program.

• Trigger/input: A customer scan of a business's loyalty QR code.
• Observable result: A scan resolves to the business's program and records a stamp/point; a scan that does not resolve to a valid program records nothing.
• Access state: The prerequisite is satisfied by the business owner's own restricted surfaces.
• Failure/recovery: An unresolved scan is reported to the customer as an inline error with a retry action.
• Continuation: Once the program and code exist, the customer's scan collects normally.

FR-13 — Reward eligibility prerequisite (required_inference) As a Customer / Loyalty Member, I should have collected enough stamps/points before redeeming a reward, so that redemption reflects what I actually earned.

• Trigger/input: The customer attempts to redeem in Redeem.
• Observable result: A reward is redeemable only when the collected stamps/points meet its requirement; otherwise the customer's current progress toward the next reward is shown.
• Access state: Restricted to the customer.
• Failure/recovery: An ineligible redemption is not performed; the balance is unchanged and the customer is shown their progress.
• Continuation: The customer returns to Scan to keep collecting.

4. User Personas

Business Owner / Loyalty Program Operator

Product context. This is the business side of the product. The owner runs a small everyday business — a coffee shop, salon, bakery, gym or retail store — and runs its own loyalty program for its own customers. They are not administering someone else's platform; the program, its codes and its records are theirs.

Primary goal. Keep customers returning by running a loyalty program that is easy to operate at the counter and that shows them how their customers are engaging.

Distinct accepted responsibilities. Setting up the program and defining its settings; operating the program by editing and saving those settings; issuing loyalty QR codes bound to the program; managing the codes already issued; and tracking customer participation and rewards.

Relevant inputs and decisions. The program's settings and reward definition; when to issue a code and which code to display at the point of interaction; how to read participation and reward activity and what to change in response.

Interactions with other accepted participants. The owner's issued QR code is the object the Customer / Loyalty Member scans. The owner's program is what the customer's stamps/points and rewards accrue against. The owner sees the participation and reward activity that the customer's scans and redemptions produce.

Observable success. The program exists and is configured as intended; a QR code is issued and displayable; participation and reward activity are visible on Dashboard; customers keep collecting and redeeming.

Constraints. The product is for the business side, not for shoppers to run their own program. This role is the one that owns and operates the program.

Customer / Loyalty Member

Product context. This is the shopper side of the product. The customer is an everyday shopper at a business whose loyalty program they have joined. They interact with the product at the point of interaction — at the counter, on a phone — and they hold their loyalty cards and rewards in a wallet.

Primary goal. Collect stamps/points on their visits and turn them into rewards, without friction and without having to think about admin.

Distinct accepted responsibilities. Scanning a business's loyalty QR code to collect stamps/points; holding and viewing their loyalty cards and rewards in a wallet; and redeeming accumulated rewards once enough stamps/points have been collected.

Relevant inputs and decisions. The QR code presented by the business at the point of interaction; which card in the wallet to look at; which available reward to redeem and when.

Interactions with other accepted participants. The customer scans the QR code the Business Owner / Loyalty Program Operator issued. Their stamps/points and rewards accrue against that owner's program, and their scans and redemptions are what the owner sees as participation and reward activity.

Observable success. A scan collects a stamp/point and the progress row advances; the wallet shows the cards, progress and rewards; a reward is redeemed and the balance updates.

Constraints. The customer is a loyalty member of a business's program; they do not create or operate a program of their own.

5. Core User Flows

Flow A — Business owner sets up and operates a loyalty program

1. The Business Owner / Loyalty Program Operator arrives at Landing anonymously and reads what the product is, who it is for, and what it does.
2. The owner selects "Start your program" and arrives at Business Login.
3. On first use, the owner enrolls at Business Login and establishes identity. On return, the owner verifies identity instead.
4. On success, the owner arrives at Dashboard. Because no program exists yet, Dashboard shows the empty state with a prompt to Program Setup.
5. The owner opens Program Setup and defines the program's settings for their customers.
6. The owner saves. The program is created and its configuration is visible. If validation or saving fails, the error is shown inline with the entered values preserved, and the owner corrects and resubmits.
7. The owner continues to QR Codes and issues a loyalty QR code bound to the program. The code is issued and listed.
8. The owner returns to Dashboard, where the program summary and participation/reward activity are now shown. If the summary fails to load, an inline message with a retry action appears and the owner can still navigate to Program Setup or QR Codes.
9. The owner displays the issued QR code at the point of interaction for customers to scan.
10. Later, the owner returns to Program Setup to edit and save the program's settings, and to QR Codes to manage the codes in circulation. The updated configuration takes effect and the owner continues operating the program.

Flow B — Customer joins, scans and collects stamps/points

1. The Customer / Loyalty Member arrives at Landing anonymously and reads what the product is, who it is for, and what it does.
2. The customer selects "I have a card" and arrives at Customer Login.
3. On first use, the customer enrolls at Customer Login and establishes identity. On return, the customer verifies identity instead.
4. On success, the customer arrives at Wallet. Because no cards exist yet, the wallet shows the empty state with a prompt to Scan.
5. The customer opens Scan and scans the business's loyalty QR code at the point of interaction.
6. The scan resolves to the business's program and the stamp/point is collected: the stamp token row advances with a single liquid overshoot and the lime collected tick appears.
7. If the scanned code is not a valid loyalty QR code for a program, or the scan cannot be processed, an inline message with a retry action is shown, no stamp/point is recorded, and the customer's existing balance is unchanged. The customer rescans.
8. The customer continues to Wallet, where the card stack shows the updated stamp/point progress. If the wallet fails to load, an inline message with retry appears and the customer can still move to Scan.
9. The customer repeats steps 5–8 on later visits, accumulating stamps/points toward a reward.

Flow C — Customer redeems an accumulated reward

1. The Customer / Loyalty Member opens Wallet and sees a reward is available, marked with the lime reward-ready accent.
2. The customer moves to Redeem. The available reward is shown along with the stamp token row reflecting progress toward it.
3. If the customer has not yet collected enough stamps/points, no reward is redeemable: the customer's current progress toward the next reward is shown, and the customer returns to Scan to keep collecting.
4. Once enough stamps/points have been collected, the customer selects the available reward and redeems it.
5. The reward is redeemed and confirmed, and the updated balance is reflected.
6. If the redemption fails or the reward is no longer available, an inline message with a retry action is shown, the balance is unchanged, and no stamps/points are consumed. The customer retries or returns to Wallet.
7. The customer returns to Wallet to view the updated card and balance, and continues collecting toward the next reward.

6. Visuals Colors and Theme

Muse and headline. Karim Rashid — sensual pop minimalism for the loyalty counter: glossy candy curves on a hot pink field. Loyalty is a small gift economy; glossy, organic, candy-coloured forms make a stamp feel like a prize. The business side gets a program builder that looks like a design object instead of a neutral dashboard; the customer side gets a wallet that feels like a bright plastic card holder. The "for the business side" constraint is a role boundary, not a mandate for grey UI.

Colour tokens (light mode).

Ratio: 60% pink/white ground, 25% white glossy surface, 10% ink, 5% lime. Contrast: ink on #FFF4F7 and white on #FF2E88 both pass body-size contrast. Never set body copy in lime, and never pink on pink.

Typography.

• Headings: Comfortaa at 700, soft rounded terminals, tight-to-normal tracking, sentence case, generous size. Never all-caps for display; letterspaced uppercase only for tiny 11px micro-labels.
• Body: Quicksand at 500/600, roomy 1.6 line-height for phone reading.
• Scale: 1.333 modular with rounded display steps — hero line 44px mobile / 72px tablet / 112px desktop; section titles 28/36/48; card titles 20/22; body 16; labels 13; micro-labels 11 uppercase with 0.12em tracking.

Shape language. Organic and glossy. Everything is a capsule, a blob or a soft-squircle: cards at 28–36px radii, buttons fully pill (999px), stamp tokens as perfect circles with a thin inner ring. Section boundaries are gentle curves — a wide elliptical pink arc that dips into the next section. Controls look moulded, not drawn: a 2px inner highlight along the top edge of a button reads as a glossy plastic catch-light. No hard 90-degree corners anywhere except the QR code modules themselves, which stay square to remain scannable.

Layout. Mobile-first, one dominant column on phones; asymmetric two-column on desktop with a 12-column grid and a consistent 24px gutter. Business pages (Dashboard, Program Setup, QR Codes) use a left rail of pill-shaped tabs and a canvas of stacked glossy cards with big numerals. Customer pages (Wallet, Scan, Redeem) use a centred card-stack metaphor — the active loyalty card sits slightly rotated above two ghost cards behind it. Never a grid of identical hover-lift cards: cards differ by size and by the colour field they sit on. Generous 32–64px breathing room around every cluster.

Imagery. Glossy 3D candy objects rendered as abstract stand-ins for loyalty: a pink torus of stamps, a lime capsule counter, a chrome QR plaque, floating soap-bubble spheres. No stock photography of people, no clip art. On the customer side, one photographed or rendered macro of a phone held at a counter, cropped so the phone bleeds off the right edge. Icons are rounded, 2px-stroke, filled with candy colour, never outlined-only.

Readable-text rule. Headlines, wordmarks, labels, numbers, card text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration and motion may be cropped, bled off an edge, rotated, overlapped or cut exactly as the direction asks, as long as they cover no readable text or control. Moving and scrollable content may cross the viewport or container edge by design; every item must become fully readable as it passes.

7. Signature Design Concept

The hero object is the loyalty card, not an illustration.

The public entry (Landing) is a full-bleed bubblegum field (#FFF4F7) with a giant flat hot-pink organic blob (#FF2E88, one soft inner shadow, no gradient) occupying the right 55% of the viewport and bleeding off the top and right edges. Overlapping the blob's left curve sits a glossy white capsule card — the loyalty card — rotated −4°, carrying a pink QR plaque and a row of eight stamp circles with the first five filled lime. The headline is set in Comfortaa 700 at 44px on mobile to 112px on desktop, stacked in three short lines flush-left in the upper left, with the words "stamps" and "rewards" set in lime against the pink blob so they punch. Below the headline, a single pill CTA "Start your program" in ink-on-lime, and a secondary text link "I have a card". A thin marquee of tiny stamp tokens drifts left-to-right along the bottom edge, crossing the viewport edge by design. A wide elliptical pink arc dips into the next section instead of a straight divider, so the page reads as one continuous moulded surface.

No centred headline, no sub-headline paragraph, no blue button, no gradient blob: the blob is flat colour with one soft inner shadow, and the QR plaque is the only square thing on the screen.

This concept recomposes only accepted content and controls — the product explanation, the two entry routes, the loyalty card, the stamp row and the QR plaque. It introduces no new behaviour, page or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: The glossy white loyalty capsule card, rotated −4°, overlapping the left curve of the giant flat hot-pink blob, with its pink QR plaque and its row of eight stamp circles (first five filled lime).
• Input → transformation → outcome thesis: As the visitor arrives, the loyalty card settles into its −4° resting angle against the blob's curve and the filled stamp tokens resolve in sequence; the bottom ticker of tiny stamp tokens and shop names drifts continuously left-to-right across the viewport edge. The outcome is a first frame that already reads as "a card you collect stamps on" — the product's defining state — with the two entry routes ("Start your program", "I have a card") held whole and uncovered.
• Motion vocabulary: Liquid and soft. Cards morph into each other on navigation with a 320ms ease-out; the stamp token scales from 0.6 to 1 with a light overshoot when a scan succeeds; a glossy highlight sweeps once across the primary button on press. Nothing loops forever except a slow 8s colour drift inside the hero blob.
• Composed first frame: Bubblegum field, flat pink blob bleeding top and right, glossy white card at −4° overlapping the blob's left curve, three-line flush-left Comfortaa headline with "stamps" and "rewards" in lime, ink-on-lime pill CTA and secondary text link beneath, ticker along the bottom edge.
• Reduced-motion state: The blob's 8s colour drift stops entirely, the ticker resolves into a static two-row list, and the wallet card stack becomes a static vertical list. No decorative motion runs when prefers-reduced-motion is set.

9. Non-Functional Requirements

• NFR-1 — Durable state. The product must persist durable state: the business's program and its configuration, the issued loyalty QR codes, customer participation records, and each customer's cards, stamp/point balances and rewards. (Source: planning scope durable_state_required; rationale: the accepted lifecycles create and change durable relationships and value.)
• NFR-2 — Application-owned identity and continuity. Identity is application-owned. Each actor establishes identity on first use and verifies it on return, so that durable actor-specific state remains bound to the correct participant. (Source: planning scope app_owned_identity; rationale: both accepted actors hold durable, actor-specific state.)
• NFR-3 — Access restriction by actor continuity. Dashboard, Program Setup and QR Codes are restricted to the business owner; Wallet, Scan and Redeem are restricted to the customer. Landing, Business Login and Customer Login are anonymously reachable. This is actor-continuity restriction, not a differentiated permission model over shared product state. (Source: planning scope page contract.)
• NFR-4 — QR scannability. QR code modules must remain square and unrounded so the codes stay scannable; the square-module exception is the only place hard 90-degree corners are permitted. (Source: creative direction.)
• NFR-5 — Readable text and controls at every viewport. Headlines, wordmarks, labels, numbers, card text and controls must stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, with no other element covering any part of them. (Source: creative direction.)
• NFR-6 — Reduced-motion support. Under prefers-reduced-motion, the hero blob drift stops, the ticker resolves into a static two-row list, and the wallet card stack becomes a static vertical list. No decorative motion runs. (Source: creative direction.)

• NFR-7 — Contrast. Ink on #FFF4F7 and white on #FF2E88 must pass body-size contrast; body copy is never set in lime, and never pink on pink. (Source: creative direction.)
• NFR-8 — Backend integration. The product requires backend integration to support program setup, QR code issuance and management, scan-based stamp/point collection, wallet state, and redemption. (Source: planning scope requires_backend_integration.)

10. Tech Stack

• Frontend: React (custom UI, mobile-first responsive web).
• Backend: Python / FastAPI, extending a single shared backend process for the product's APIs and domain logic (programs, QR codes, scans, wallets, rewards).
• Storage: A durable relational store for programs, QR codes, participation records, cards, stamp/point balances and rewards.
• Packaging/deployment: Docker with docker-compose.yml as the inventory of runnable services; the backend and its storage run as the project's services. Kubernetes is not required by any accepted requirement.

[Default — not specified by user] for the concrete storage engine and container orchestration details; the source specifies no technology choices beyond the product's functional shape.

11. Assumptions and Constraints

Constraints

• C-1 (explicit, binding): The product is for the business side, not for shoppers to run their own program. Shoppers are loyalty members of a business's program; they do not create or operate programs of their own.
• C-2: The product is a loyalty QR wallet: a business runs its own loyalty program for its customers; customers collect stamps/points by scanning QR codes at the business; loyalty cards/rewards are held in a wallet.
• C-3: A business owner must have set up a loyalty program and issued a QR code before a customer can scan and collect stamps/points.
• C-4: A customer must have collected enough stamps/points before redeeming a reward.

Assumptions

• A-1: Identity is application-owned and self-service; first-use enrollment and returning verification are the chosen bootstrap for both accepted actors. (required_inference)
• A-2: A customer's loyalty card, stamp/point balance and rewards accrue against a specific business's program, established by the QR code they scan. (required_inference)
• A-3: The concrete storage engine and deployment orchestration beyond Docker/docker-compose are unspecified by the user and are treated as implementation defaults. [Default — not specified by user]
• A-4: No future-horizon requirements were accepted; everything in this document is current.

12. Glossary

• Loyalty program — The business's own program for its own customers, defined and operated by the Business Owner / Loyalty Program Operator.
• Loyalty QR code — A QR code issued by the business and bound to its program; customers scan it at the point of interaction to collect stamps/points.
• Stamp / point — The unit a customer collects by scanning a business's loyalty QR code.
• Loyalty card — The customer's card for a business's program, holding their stamp/point progress.
• Reward — What a customer redeems once enough stamps/points have been collected.
• Wallet — Where the customer holds and views their loyalty cards and rewards.
• Business Owner / Loyalty Program Operator — The accepted persona who sets up and operates the loyalty program, issues and manages QR codes, and tracks customer participation and rewards.
• Customer / Loyalty Member — The accepted persona who scans a business's loyalty QR code, holds cards and rewards in a wallet, and redeems rewards.
• Point of interaction — The counter or equivalent place where the business displays its loyalty QR code and the customer scans it.